Docs development

Preview locally

Install the docs project and start the default internal site from the repository root:

npm ci --prefix docusaurus-docs
npm run docs

The preview is normally available at http://localhost:3001 and hot-reloads changes under docusaurus-docs/**.

Documentation surfaces

• docusaurus-docs/docs/**: hosted internal/product documentation.
• docs/**: internal references, runbooks, ADRs, generated contracts, and OpenAPI artifacts.
• docusaurus-docs/sidebars*.js: audience/domain navigation variants.
• docusaurus-docs/docusaurus.config.js: shared site configuration and build filtering.
• Code-adjacent README.md files: local package/app ownership and commands.

Internal and external builds share content infrastructure but apply different audience filters. Never assume a page is safe for the external site merely because an internal build succeeds.

Source-backed editing workflow

1. Identify the owning source, test, workflow, schema, environment config, or generated contract.
2. Preserve the page's audience and frontmatter; keep current behavior, proposals, and historical evidence clearly labelled.
3. Update every affected hosted/internal link and example in the same slice.
4. Run the narrow freshness checks for generated contracts instead of editing generator-owned JSON by hand.
5. Build the affected audience/domain variant.

Use source in this order when claims disagree: implementation/configuration, behavioral tests, freshly checked generated contracts, current architecture or accepted decisions, then prose/runbooks.

Validation

Default internal build:

npm run docs:docusaurus:build

Explicit variants (run sequentially because they share the build directory):

npm --prefix docusaurus-docs run build:internal
npm --prefix docusaurus-docs run build:external
npm --prefix docusaurus-docs run build:k12
npm --prefix docusaurus-docs run build:tap
npm --prefix docusaurus-docs run build:sdac

When route, registry, MCP, or API behavior changed, run the affected freshness and mapping checks:

npm run contracts:check
npm run contracts:ingestion:check
npm run docs:routes:check
npm run docs:symbols:check
npm run docs:mcp:check
npm run docs:context:check
npm run contracts:bruno

The testing APIM/Replit workbench has an additional npm run docs:revival:check guard. It is a focused workbench contract, not the whole documentation corpus.

Writing conventions

• Use project-relative source paths and commands that exist in the relevant package manifest.
• Link to hosted pages with absolute Docusaurus paths such as /deployment/overview and to sibling pages with normal Markdown links.
• Do not copy secrets, live tokens, production data, or developer-local paths.
• Avoid volatile pass counts, prices, and rollout claims unless the page records the evidence date and source.
• Use diagrams only when they clarify ownership or multi-stage behavior.

Agent documentation

Agents are created with the shared factory pattern, but their source belongs in the owning domain package or the retained shared runtime surface. Before documenting a new agent:

• follow .claude/agent-architecture.md and the repo-local create-agent skill;
• keep profile ID, registry ID, descriptor, loader, and exports aligned;
• register it through the owning loader composed by apps/runtime/src/mastra-runtime.ts;
• add conformance/domain tests and regenerate affected contracts;
• document the public registry/profile IDs and owning package path, not an invented constructor example.

See Unified Agent Platform and Testing.