Documentation maintenance

​

Truth policy

1. Pin repository, commit, and version once in apps/docs/docs.json.
2. Verify examples against that exact source commit.
3. Describe concrete classes as implemented only when they can be imported and exercised.
4. Label proposals, rationale, and unimplemented flows as Design Notes.
5. Do not substitute the unrelated PyPI project for a source checkout.

​

Local setup

corepack enable
pnpm install --frozen-lockfile
pnpm dev:docs

​

Required checks

pnpm docs:validate
pnpm docs:links
pnpm docs:a11y
pnpm docs:structure
pnpm docs:source-smoke
git diff --check

​

Routes and redirects

• Add every intended public page to docs.json navigation.
• Use lowercase route paths.
• When moving a published page, add a permanent redirect only when the destination is genuinely equivalent.
• Do not redirect arbitrary typos or removed starter features to unrelated product pages.
• Keep the custom 404 page non-redirecting so an unknown URL remains an honest 404.

​

Content review

• search for stale class and method names;
• remove numerical product claims unless they are reproducible measurements with context;
• ensure every code block uses runnable core.* source-checkout imports;
• confirm images have meaningful alternative text;
• inspect rendered desktop and mobile navigation; and
• fetch every rendered internal destination, because static Markdown checks can miss generated navigation failures.

​

Release verification