Repository Source Map
Where canonical truth lives in the repo, what is archival, and what should stay out of the main docs UX.
This page is for maintainers and researchers. It maps the repo's documentation layers so the docs app can stay curated instead of collapsing back into a dump of every markdown file.
Canonical Sources
| Concern | Canonical source |
|---|---|
| Brand semantics | docs/design/BRAND_COLOR_SEMANTICS.md and docs/design/BRAND_FINALIZATION_2026-03-03.md |
| Current architecture state | docs/architecture/unified-architecture-state.md |
| Research corpus | docs/research/RESEARCH_INVENTORY.md and docs/research/analysis/MASTER-SYNTHESIS.md |
| Extracted source notebooks | context/* summaries and notebook extracts |
| Code truth | apps/* and packages/* implementation files |
| Public docs content | apps/docs/content/docs/* |
Useful But Not Canonical
These sources are often valuable for context, but should not drive public docs copy without verification:
archive/work-logs/*context/*docs/plans/*docs/internal/*docs/ideas/*.claude/cache/*.claude/agents/*
They are best treated as:
- decision history
- experiments
- operational memory
- abandoned or superseded plans
What Should Stay Out Of Primary Navigation
- raw PRDs
- temporary planning notes
- migration scratchpads
- deployment checklists
- agent logs and session traces
Those materials are worth mining, but they should be summarized into current docs pages instead of being surfaced directly to every reader.
Maintenance Rules For This Docs App
- Keep one clear entry page per concern.
- Link to deeper source documents instead of duplicating long research dumps.
- When repo documents disagree, prefer live code and the latest architecture tracker.
- Hide historical notes from primary navigation unless they help current users.
The goal is not to erase repository history. The goal is to keep the docs app readable while still pointing maintainers at the deeper material when they need it.