Cortex Docs Map
At-a-glance map of what lives where in the Cortex docs and why.
Cortex Docs Map
A one-page orientation to the documentation tree. When in doubt about where a new doc belongs, start here.
By Kind
| Kind | Where | Lifetime | Dated? |
|---|---|---|---|
| Usage guide | Usage/ | Long-term canon | No |
| Canonical architecture chapter | Architecture/ | Long-term canon | No |
| Normative specification | Reference/ | Long-term canon | No |
| Code style guide | Style.md | Long-term canon | No |
| Architecture decision record | ADRs/ | Permanent | No |
| Downstream consumer binding | Consumers/{consumer}.md | Long-term per consumer | No |
| Logos reasoning library | Consumers/Logos/ | Long-term downstream library canon | No |
| Active roadmap plan | Roadmap/Plans/ | Active until completed or superseded | No |
| Active roadmap epic | Roadmap/Epics/ | Active while retained | No |
| Completed initiative | Roadmap/Completed/ | Historical, retained selectively | No |
| Archived idea | Roadmap/Archive/ | Historical, retained selectively | No |
| Paper manuscript and figures | Publications/paper-N-*/ | Published-once | No |
| Paper notes and ideas | Publications/Notes/ | Working | No |
| Research or synthesis memo | Research-notes/{scope}/ | Historical, retained selectively | Yes |
| Controlled experiment | Experiments/{scope}/ | Epic-controlled, retained selectively | Yes |
| Template | Templates/ | Long-term canon | No |
By Question
Where do I document a settled architecture decision? Use ADRs/ with the next NNNN- number.
Where do I write up the Wire grammar surface? Use Reference/Wire/. Canonical language rules
live in reference docs, not research notes.
Where do I explain how to use Cortex? Use Usage/. Usage pages should lead with working paths,
commands, and decision points. Link to Architecture/ for rationale and Reference/ for exact
rules.
Where do I document runtime architecture? Use Architecture/06-pulse-runtime.md for the stable
model and Architecture/07-rewrites-and-materialization.md for topology evolution.
Where do I document LLM or model-mediated reasoning workflows? Use Consumers/Logos/. Cortex
architecture should describe the substrate those workflows run on, not the reasoning library itself.
Where does downstream-specific design belong? Start with Consumers/{consumer}.md. Consumer
docs may contain concrete product bindings; Cortex architecture should stay consumer-independent.
Create a consumer subdirectory only when a public binding grows beyond one page.
Where does an implementation plan go? Use Roadmap/Plans/ while it is active. Move or delete it
when it ships, is superseded, or stops explaining the current plan.
Where do dated synthesis notes go? Use Research-notes/ under the right scope. Keep only notes
that still explain the current canon or a live research thread.
Canonical Docs Versus Dated Artifacts
Canonical docs are edited to remain current. They should frame Cortex as an independent upstream substrate and use downstream products only as examples.
Dated artifacts preserve reasoning from a point in time. They are retained only when they still help explain the current system. Stale transition notes, issue-specific migration plans, and superseded research snapshots should be removed instead of preserved by default.
Related
- index.md - docs landing and reading order.
- taxonomy.md - concept classification.
- glossary.md - term definitions.
- Templates/ - per-kind frontmatter and section shape.