ADR 0060: Derive Human Documentation From Canonical Sources

Status: Accepted

Date: 2026-07-29

Context

Repository Markdown is reviewable and agent-readable, but a large documentation tree is not an ideal owner reading surface. Agent instructions also optimize for compact routing and control flow rather than human teaching. Copying the same guidance into a hosted knowledge base would create conflicting sources.

Decision

Keep Markdown, YAML, schemas, and code in Git as canonical. Provide:

• a compact agent interface through AGENTS.md, skills, and scripts; and
• a Docusaurus human reading interface generated from selected canonical documents.

The site may add navigation and presentation metadata, but generated content is ignored and never edited as source. Do not enable documentation versioning until a named consumer requires frozen historical sites.

External trackers and knowledge bases remain optional attention views. They do not become canonical project memory.

Alternatives Considered

• Repository Markdown alone remains the canonical baseline, but its large tree is a poor owner-facing reading surface.
• Mintlify would provide polished hosted documentation quickly, but adds a hosted product dependency and configuration surface without reducing the need for canonical Git sources.
• Notion or another wiki would make editing approachable while creating a second authority and synchronization burden.
• Linear is an issue and attention system, not a documentation system. It may mirror Ready work later but cannot own method, repository, or evidence truth.

Docusaurus is selected because it builds locally into removable static output, can consume repository Markdown directly, and permits a curated human information architecture without transferring authorship outside Git.

Consequences

• Humans gain a readable, navigable guide without weakening Git review.
• Agents keep a small context surface and load detail progressively.
• Documentation fixes occur once in canonical source.
• Site build tooling adds maintenance cost and must remain independently removable without losing STAGE's method or plugin.