3.6 KiB
Documentation ownership and authoring
Use the documentation directory to find existing material before adding another guide. Preserve one canonical owner for each contract or workflow; link to that owner instead of copying its claims into several guides.
When a contract changes, update its owning page with the implementation. Check the examples and recovery steps in related guides against the supported CLI and MCP entry points. Link guides to the section that owns the shared behavior so readers can reach it from the task they are performing.
Choose a destination
| Document | Destination |
|---|---|
| Installation, client setup and first CLI/MCP steps | docs/getting-started/ |
| Analyst workflows and evidence interpretation | docs/guides/<domain>/ |
| Analysis-engine configuration and format prerequisites | docs/providers/ |
| Shared runtime contracts and evidence semantics | docs/reference/ |
| Development, testing, release and authoring instructions | docs/development/ |
| Compatibility changes for a released version | docs/migrations/ |
Use meaningful, lowercase slugs. Guides describe current workflows, behavior and limitations. Ground their claims in the implementation and verify examples through the supported entry points.
Follow the repository guidance on where to keep planning and architecture records and the contribution scope for proposals that require a maintainer decision.
Links and public routes
Use relative links to physical Markdown files so GitHub readers can follow them.
Link repository files outside docs/ with their full GitHub URLs. Preserve
existing heading anchors when moving a guide.
documentation.ts
owns categorized site navigation and the existing guides' stable public routes.
Update it and the documentation directory when adding or
recategorizing a guide. VitePress rewrites categorized sources
to the existing public paths; its Markdown hook resolves repository links from
the physical source and renders them against those public routes. Keep basenames
and route assignments unique. Edit links use the physical source file.
For a move, search for both the basename and its old full path. Update README translations, authored skills, verification instructions, documentation-fact readers and release configuration when they consume that path. Preserve historical release records and references bound to earlier commits or tags.
Generated ownership and checks
The documentation directory lists generated files, their producers, and release records. Scripts, package consumers, and release history depend on the listed paths. Update the producer or its inputs and regenerate.
Do not write the number of tools in living prose; link the generated catalog
instead. docs:check refuses a count of ten or more tools outside dated
records (docs/releases/ and docs/verification/).
Run npm run docs:check for documentation facts and generated consistency, and
npm run verify:docs:routes to build the complete production site and check local
links, anchors and physical edit targets.
When a physical path moves, also run the tests that read it. Follow
development checks before requesting review.