ContextOS Docs Author
Publish a documentation page that fits the reader journey and does not create spec drift.
Inspect the local publishing surface
Read the repository instructions, the nearest related docs, current navigation source, MDX loader/renderer, component registry, redirects, and relevant tests. Verify actual imports before following a possibly stale statement about where navigation is hardcoded; if repository guidance conflicts with code, report the conflict rather than editing both blindly.
Read references/docs-map.md for page classes, coupled files, and validation routing.
Choose the page contract
- Every docs MDX page has non-empty
title and description frontmatter.
- A new foundation page uses the standard
## sections: Definition, Why it exists, How it works, Interfaces, Failure modes, Operational concerns, Evaluation metrics, Example, Common misconceptions. Do not expand an allowlist to avoid the template.
- Implementation pages prioritize executable contracts, field semantics, invariants, lifecycle, validation, and examples.
- Reference pages act as routing tables or precise lookup surfaces.
- Tutorials produce one observable artifact at a time and keep identifiers aligned with the canonical scenario.
Optional metadata such as status, review date, primitive planes, lifecycle, inputs, outputs, and key types should match neighboring pages and real consumers.
Write without changing the spec accidentally
- Use the five-plane vocabulary and canonical type names consistently.
- Search the foundations, implementation docs, TypeScript types, scenario fixture, and schemas before claiming something is absent or canonical.
- Link to the authoritative page instead of redefining a primitive in multiple places.
- Use canonical example identifiers from the current scenario for on-ramp pages.
- Mark proposals and implementation-specific extensions clearly.
- Treat ActionRisk as multidimensional and approval mode as compatibility vocabulary.
- Do not imply that retrieved text, memory, approval, or a model can widen technical authority.
Integrate the page
- Add a discoverable nav entry in the current single source of truth when the page belongs in the reader journey.
- Register any custom MDX component in the renderer before using it.
- Prefer existing components and code-native diagrams. Do not add a bespoke component when prose, a table, Mermaid, or an existing diagram suffices.
- Add a redirect when moving or renaming a published route.
- Update LLM discovery or schema indexes only when the new page changes those curated surfaces.
Verify
Run the frontmatter and docs-template tests for content changes. Run spec-reference drift tests when canonical examples or runtime terms change; MDX loader tests when rendering changes; typecheck/lint/build when TypeScript, components, navigation, or routes change. Preview the affected route when practical.
Report the page's role in the reader journey, integration points changed, and any preview/build/live check not performed.
1---2name: contextos-docs-author3description: Create or revise ContextOS MDX documentation while preserving frontmatter, foundation templates, navigation, component registration, canonical examples, URL stability, and spec/reference alignment. Use for docs pages, not blog posts or contract implementation alone.4---56# ContextOS Docs Author78Publish a documentation page that fits the reader journey and does not create spec drift.910## Inspect the local publishing surface1112Read the repository instructions, the nearest related docs, current navigation source, MDX loader/renderer, component registry, redirects, and relevant tests. Verify actual imports before following a possibly stale statement about where navigation is hardcoded; if repository guidance conflicts with code, report the conflict rather than editing both blindly.1314Read [references/docs-map.md](references/docs-map.md) for page classes, coupled files, and validation routing.1516## Choose the page contract1718- Every docs MDX page has non-empty `title` and `description` frontmatter.19- A new foundation page uses the standard `##` sections: Definition, Why it exists, How it works, Interfaces, Failure modes, Operational concerns, Evaluation metrics, Example, Common misconceptions. Do not expand an allowlist to avoid the template.20- Implementation pages prioritize executable contracts, field semantics, invariants, lifecycle, validation, and examples.21- Reference pages act as routing tables or precise lookup surfaces.22- Tutorials produce one observable artifact at a time and keep identifiers aligned with the canonical scenario.2324Optional metadata such as status, review date, primitive planes, lifecycle, inputs, outputs, and key types should match neighboring pages and real consumers.2526## Write without changing the spec accidentally2728- Use the five-plane vocabulary and canonical type names consistently.29- Search the foundations, implementation docs, TypeScript types, scenario fixture, and schemas before claiming something is absent or canonical.30- Link to the authoritative page instead of redefining a primitive in multiple places.31- Use canonical example identifiers from the current scenario for on-ramp pages.32- Mark proposals and implementation-specific extensions clearly.33- Treat ActionRisk as multidimensional and approval mode as compatibility vocabulary.34- Do not imply that retrieved text, memory, approval, or a model can widen technical authority.3536## Integrate the page3738- Add a discoverable nav entry in the current single source of truth when the page belongs in the reader journey.39- Register any custom MDX component in the renderer before using it.40- Prefer existing components and code-native diagrams. Do not add a bespoke component when prose, a table, Mermaid, or an existing diagram suffices.41- Add a redirect when moving or renaming a published route.42- Update LLM discovery or schema indexes only when the new page changes those curated surfaces.4344## Verify4546Run the frontmatter and docs-template tests for content changes. Run spec-reference drift tests when canonical examples or runtime terms change; MDX loader tests when rendering changes; typecheck/lint/build when TypeScript, components, navigation, or routes change. Preview the affected route when practical.4748Report the page's role in the reader journey, integration points changed, and any preview/build/live check not performed.
contextosai