rea/docs/development/documentation.md

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.

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/
Composition diagrams	docs/architecture/
Compatibility changes for a released version	docs/migrations/
One feature specification, plan and tasks	docs/specs/<domain>/<feature-slug>/
One architectural decision	docs/adr/<domain>/<decision-slug>.md

Use meaningful, lowercase domain and feature slugs. Global numeric prefixes are unnecessary: different domains can add features independently, and branches do not compete for the next sequence number. Check the existing domain directory and linked issues before creating a feature with the same slug.

Guides describe existing behavior and limitations. Specs define one proposed feature or domain change; an existing guide does not become a specification by moving it into specs/.

Feature lifecycle

Create the specification before implementation. Each feature directory contains:

• spec.md: problem, desired behavior, requirements, acceptance and non-goals.
• plan.md: the single implementation plan, contracts and architectural choices.
• tasks.md: incremental, testable steps linked to requirements and verification.

Split independent domains or separately reviewable features before writing their specs. A broad ROADMAP.md, when useful, only lists child specifications, order and dependencies; requirements and implementation tasks belong to each child. Cross-repository contracts have one producer-owned specification. Consumers link to that contract instead of maintaining competing copies.

Record an isolated architectural decision separately in docs/adr/<domain>/<decision-slug>.md, with Status, Context, Decision and Consequences. Link the ADR from affected specifications. Do not create decision records for routine file moves or invent past decisions.

Specs do not replace the contribution-scope decision required for a new provider or expanded execution authority. Follow contribution scope.

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 when adding or moving 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 identifies the machine-owned outputs and their producers. Their existing paths are retained because scripts, package consumers and release history depend on them. Change canonical sources and regenerate; do not fix a generated projection by hand.

Run npm run docs:check for documentation facts and generated consistency, and npm run docs:build for the complete production site and dead-link validation. When a physical path moves, also run the tests that read it. Follow development checks before requesting review.