TopoloDocs

What It Is

TopoloDocs is the canonical multi-tenant documentation application and registry surface for the Topolo Platform. It publishes product documentation, internal system handbooks, system registry metadata, Auth catalog snapshots, and launch-readiness evidence, while giving each organization isolated documentation workspaces.

Architecture

The signed-in product is a React/Vite TypeScript application using the shared Topolo app shell, workspace model, Auth client, and localization provider. A TypeScript API Worker owns workspace-scoped spaces, documents, immutable versions, locale variants, full-text retrieval, and publication. The platform handbook builds from checked-in Markdown and JSON under apps/web/src/content into public and gated static routes plus agent-readable manifests.

The original Topolo platform corpus belongs to organization org_topolo_platform. Repository content remains its authored source of truth and is projected into an Auth-owned Docs workspace as locked, revisioned documents. Public platform pages are published from the topolo-platform space; internal handbooks and system registry contracts are projected into separate gated spaces. This preserves the public documentation website while making the corpus available through the same multi-tenant search, version, citation, and automation architecture as other Docs workspaces.

Runtime Surfaces

• public docs at https://docs.topolo.app
• development docs at https://docs.topolo.dev
• staging docs at https://docs.stg.topolo.us
• signed-in documentation workspaces at /app
• public tenant publications at /s/:space/:document
• system registry entries under src/content/systems
• generated machine output for system and security evidence
• source-backed public capability coverage at /reference/source-coverage and /machine/source-coverage.json, including exact action schemas, valid examples, route-implementation evidence, verification steps, and recovery guidance
• public /llms.txt index and /llms-full.txt retrieval corpus
• full-text Docs search across headings, metadata, and page bodies
• command-palette search over documents in the space you are reading, matching titles and summaries instantly and published body text behind them
• browsable public action contracts backed by Topolo Developers
• Auth app manifest app_topolo_docs

API Reference

TopoloDocs exposes workspace-scoped authoring, version, localization, search, grounded-answer, and publication APIs under /api/docs/*; public published-document reads and space search under /api/public/docs/*, whose space manifest carries the configurable section hierarchy readers and agents navigate by; and generated machine-readable system output under /machine/systems/:system.json. Its complete 34-action surface is published through Topolo Developers, including the docs:write-protected platform_corpus.sync projection action fixed to the canonical platform organization, the section-hierarchy actions that reorder a space's sections and file documents into them, and the anonymous public_search.query action, which searches one published space and matches published versions only.

Auth and Permissions

Public docs and explicitly published tenant snapshots are readable without application auth. Authoring APIs require a verified organization, a canonical Docs workspace, and the relevant Docs permission; tenant identifiers are derived from trusted Auth context rather than accepted from request bodies.

Data Ownership

TopoloDocs owns tenant spaces, sections, documents, immutable versions, locale variants, publication state, documentation content, system metadata, generated docs evidence, and validation output. It does not own product runtime data for the applications it documents.

Deployments

TopoloDocs deploys through the standard CloudControl-backed development, staging, and production paths. Bare npm run deploy is disabled; use npm run deploy:development, npm run deploy:staging, or npm run deploy:production.

Failure Modes

• system registry drift from Auth app catalog manifests
• launch-readiness evidence out of date with checked-in systems
• production or publication gates bypassed before docs validation
• generated machine output stale after catalog or registry changes

Debugging

Run npm run validate first, then run the relevant security/privacy gate profile. For app registry issues, compare src/content/systems/*.json with the Auth app catalog manifests.

Use It

Open TopoloDocs 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-docs --json
topolo actions --service topolo-docs --json
topolo actions capabilities --service topolo-docs --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 TopoloDocs 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

• Reverified canonical source discovery on 2026-08-01. Generated fleet evidence excludes local clones by matching each checkout directory to its configured origin repository and currently covers 51 canonical repositories, 64 systems, 1,832 actions, 34 shared packages, and 1,688 exports.

• Converted TopoloDocs to the canonical multi-tenant React/Vite and TypeScript Worker architecture on 2026-07-28, with shared shell, Auth, workspace, and i18n contracts plus isolated authoring, search, localization, and publication data paths.

• Assigned the original platform corpus to org_topolo_platform on 2026-07-28 and added its revisioned projection into the canonical Auth-owned Docs workspace, with public, internal, and system-registry spaces and a fully published 27-action catalog.

• Added canonical source-backed coverage on 2026-07-28 for 64 systems, 51 repositories, 1,820 unique actions, 34 shared packages, and 1,670 package exports. Public output is visibility-filtered and strips secret names, database table details, test details, package manifests, and binding targets; internal system and package references retain the complete operator evidence.

• Rebuilt Docs evidence on 2026-07-27 from all 63 registered systems and their canonical staging workspaces; added revisioned runtime/API snapshots, resolvable source-path gates, full-text search, public/internal llms-full.txt, browsable action discovery, practical usage examples for every public application guide, and explicit TopoloProvision coverage.

• Reconciled this page against system-apps/TopoloDocs origin/staging 33239895a0d8 on 2026-07-25 after the fleet workspace-ownership documentation correction and a clean 179-document validation.

• Reconciled this page against system-apps/TopoloDocs origin/staging 459193fd223f 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.

• Reconciled workspace verification on 2026-06-28 against system-apps/TopoloDocs commits through 9ebc732; reviewed 31 commits since 2026-06-26, including 9ebc732 docs: bump app-shell lazy route factory release; 24ccaa4 docs: record app-shell lazy route factory; 9a5cbde docs: add workspace docs audit; 03ec7ca docs: record app-shell route preloader.

• Added first-class TopoloDocs system coverage on 2026-05-11 so Auth catalog validation can verify the Docs service boundary.