Topolo Web

What It Is

Topolo Web is a website studio and publishing runtime. Human users can work in the browser studio; Codex, Claude, and other authenticated agents can use the same product through credential-scoped actions published by Topolo Developers.

The agent interface is repository-independent. It publishes the complete site-content JSON Schema, renderer-backed block catalog, required responsive viewports, a full example, deterministic quality findings, preview/public URLs, publish preflight, immutable versions, and recovery actions.

Architecture

Topolo Web separates its authenticated studio and control-plane API from the public site runtime. Topolo Developers owns publication and credential-scoped projection of machine actions; Topolo Auth supplies identity, organization context, service permissions, and API-key resource bindings. Topolo Web remains the target-owned authorization, site-data, rendering, quality, versioning, and domain boundary.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

• https://web.topolo.app — authenticated website studio
• https://web-api.topolo.app — credential-protected site control plane
• https://sites.topolo.app — public site runtime

API Reference

Agents should use the Topolo Developers action catalog described below. The action definitions publish the exact routes and schemas needed by CLI and MCP clients, so callers do not need to construct control-plane URLs directly.

Open any Web contract in the Agent Actions reference, or follow the exact docsUrl returned by action discovery.

Workspace management

The authenticated studio exposes workspace settings from the shared workspace switcher. Users with the matching permissions can create and rename workspaces, choose the default workspace, and delete an empty non-default workspace. Renaming preserves the workspace's stable id and slug; changing the default is a separate operation.

Agents can use the same declared actions:

Mutation calls require the exact target workspace resource context. Auth validates access before Topolo Web applies its product-owned lifecycle rules.

Capability discovery

Start with the capability action instead of constructing a site from memory:

topolo actions capabilities --service web --json
topolo actions get app_topolo_web.sites.capabilities.get --json

sites.capabilities.get returns:

• the current public contract version
• canonical site-content and build-input schemas
• allowed block types, fields, presentations, and presentation intent descriptions
• canonical examples for every supported site intent
• audience-specific composition recipes with a visual thesis, ordered content plan, interaction thesis, and failure modes to avoid
• mobile, tablet, desktop, and 4K QA viewports
• the ordered build and publication workflow

Do not add fields or block types that are absent from the returned contract.

Composition contract

Supported blocks publish renderer-backed presentations in the returned block catalog. A presentation changes the composition and hierarchy of a block, not only its border or background. Every option includes a description of its intended use. Use only a value declared for that block; validation and write actions reject cross-block presentation values.

The current composition families include:

For presentations whose block-catalog entry has supportsItemsPlacement=true, set style.itemsPlacement to left or right to reverse the relationship between section copy and repeated items. style.imagePlacement controls the copy/media relationship on supported hero and image compositions, as well as media and captions inside image frames. Both fields can be overridden at the declared responsive breakpoints.

Composition recipes and quality

The returned compositionRecipes cover platform, venture-investor, angel-investor, partner-channel, and marketplace-developer narratives. Recipes are planning guidance, not fixed templates: preserve the recipe's audience and visual thesis while adapting the content plan to verified material and the available assets.

Do not build a long page by cloning one feature-card section and changing the nouns. Quality reports flag:

• composition_repetition when one visual family dominates a long page
• composition_media_thin when a long page lacks purposeful media-bearing sections
• composition_layout_flat when a long page never uses structural layout blocks
• section_presentation_invalid when a block persists a presentation it does not declare

The first three findings are composition warnings that require visual judgement; the last is a blocking contract error. Agents must still inspect the whole page at every required viewport because a valid schema cannot prove that copy length, art direction, crop, spacing, or rhythm is good.

Composition is part of the public contract. An agent should discover it from sites.capabilities.get, choose deliberately from the selected block's presentations, validate the complete payload, and visually inspect the result at every returned viewport. Do not infer a presentation from its name or use a presentation on a block that does not declare it.

Build workflow

1. Call sites.capabilities.get and construct only declared content.
2. Call sites.validate with the complete site and content payload. This is a read-only POST and does not persist data.
3. Validate and plan sites.build locally, then execute it with publish=false after confirmation.
4. Read sites.preview.get and sites.quality.get.
5. Inspect the draft at every required viewport. Resolve every blocking quality issue.
6. Call sites.publish.preflight. Continue only when canPublish=true.
7. Plan and confirm sites.publish.
8. Open the returned public URL and confirm the returned immutable version is active.

The primary action ids are:

Responsive quality

Topolo Web requires visual verification at the viewport widths returned by the capability and preview actions. Schema validity is necessary but does not prove that hierarchy, typography, media, navigation, or content density works on mobile and desktop.

sites.quality.get, sites.validate, and sites.publish.preflight provide deterministic findings. The agent must also open the returned preview URL at each required viewport before publication.

Publish and recover

Publishing creates and activates an immutable version. Run sites.publish.preflight first, then plan sites.publish so the exact request, confirmation status, verification step, and rollback action are visible before execution.

To recover, list versions for the same site, select a returned version id, validate and plan sites.versions.restore, confirm it, and verify the new active version at the returned public URL. Never use a version id copied from another site.

Auth and Permissions

The action catalog is filtered to the current credential. Read and validation actions require the published studio-read permission. Build, publish, and restore actions require their corresponding write permissions and explicit confirmation. Target-owned policy remains authoritative for the concrete organization, workspace, site, and version.

Data Ownership

Topolo Web owns sites, canonical content, draft state, quality findings, assets, domains, form submissions, events, agent sessions, and immutable published versions. Topolo Developers owns action publication; Topolo Auth owns credentials and service permission projection.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /sites, its offline policy is read_through_cache, and it requires organization context.

Published permissions: studio:read, studio:write.

• /sites uses /api/studio/sites with the record.list template and web.sites.list data source.
• /sites/:id uses /api/studio/sites/:id with the record.detail template and web.sites.detail data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Production serves the studio, API, and public runtime from their separate hosts above. Staging uses web.stg.topolo.us, web-api.stg.topolo.us, and sites.stg.topolo.us with separate credentials and data.

Failure Modes

• capability/schema metadata is missing or older than the site payload
• schema-valid content still fails responsive visual QA
• publish is attempted before blocking quality findings are resolved
• a site/version id is copied from another resource boundary
• publication succeeds but the returned public URL/version is not verified
• recovery is improvised instead of using a published immutable version

Debugging

Preserve the request id, action id, plan, schema errors, quality report, and returned site/version ids. Repeat the credential-scoped read or preflight action before escalating; do not replace a failed action with an inferred private endpoint.

Use It

Open TopoloWeb for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-web --json
topolo actions --service topolo-web --json
topolo actions capabilities --service topolo-web --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

1. Confirm the active identity and organization with topolo whoami --json.
2. Discover TopoloWeb and select one published action rather than guessing a route.
3. Inspect its input/output schemas and published example.
4. Validate and plan the exact payload; obtain confirmation for a mutation.
5. Execute and perform every published verification step.

Change Log / Verification

• Reconciled the Auth-owned workspace identity model and removal of Web's unapplied legacy migration tree through apps/TopoloWeb origin/staging 05c6f48c25dd on 2026-07-28.

• Verified the native_capability mobile experience contract and its 2 published route(s) against apps/TopoloWeb origin/staging cb7aad9fc430 on 2026-07-27.

• Reconciled this page against apps/TopoloWeb origin/staging 40c4ece2febc on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

• Published the workspace-management contract on 2026-07-22 with shared-switcher UI, explicit default selection, safe deletion, dedicated permissions, and five declared workspace actions.

• Expanded the composition contract on 2026-07-22 with asymmetric mosaics, quote spotlights, horizontal pricing tiers, reversible repeated-item placement, and matching CLI/MCP schemas.

• Published the clean-room site contract on 2026-07-14 with canonical schemas, capability discovery, deterministic quality/preflight output, responsive QA viewports, typed publish/restore inputs and outputs, examples, verification URLs, and immutable-version recovery.