documentation.mdx

title	Documentation maintenance
description	Maintain the information architecture, MDX components, routes, and documentation validation gates.

Documentation maintenance

Documentation is part of the product contract. A page is complete only when its content, route, component usage, icon, source of truth, and links are all verified.

Source of truth

• action.yml: public inputs and defaults.
• src/: runtime behavior, validation, adapters, and policies.
• .github/workflows/: event, permissions, and variable propagation.
• docs.json: tabs, groups, titles, icons, and routes.
• docs-page catalog: supported MDX components and icon vocabulary.
• scripts/validate-documentation-contract.cjs: routes and heading anchors, YAML snippets, Action refs and input names, workflow/single-action catalogs, issue-template parity, and high-risk deployment documentation contracts.
• specs/catalog.json: capability ownership and the exact SDD, workflow, code, test, and user-documentation evidence for each product area.

Change procedure

Read the implementation and workflow before changing prose. Keep one user task or concept per page. Use only supported MDX components and icons, and register every public page in `docs.json`. Run `validate:agent-docs`, `validate:docs-page`, `validate:documentation`, and `validate:workflows`. Together they check routes/anchors, YAML snippets, frontmatter, selected defaults, action refs and input names, catalogs, issue templates, terms, components/icons, and workflow contracts. Run `validate:specifications`; regenerate `specs/CATALOG.md` first when catalog metadata changed.

These gates cannot inspect npm or GitHub settings and do not replace real desktop/mobile, light/dark, or screen-reader review. Record those checks as explicit operator or UX evidence when a specification requires them.

See the documentation completeness plan for the complete information architecture. See Product specifications for the as-built SDD method and capability-to-evidence catalog.