docs: beef up docs/README.md navigation

docs/README.md

@@ -2,27 +2,43 @@
 
 This is the central index for all documentation in the CORE project.
 
-## Directories
+## Canonical Root Documents
-- `adr/` - Architecture decision records
+- [Whitepaper.md](../Whitepaper.md) - The CORE architectural and philosophical whitepaper.
-- `analysis/` - Deep dives and master plans
+- [Yellowpaper.md](../Yellowpaper.md) - Technical specifications and mathematical formulation of the CORE engine.
-- `architecture/` - Architecture docs
+- [PROGRESS.md](../PROGRESS.md) - High-level project progress tracking.
-- `audit/` - Audit reports
+- [specs/runtime_contracts.md](specs/runtime_contracts.md) - Critical invariants and bounds for the runtime execution flow.
-- `benchmarks/` - Benchmark evidence
-- `briefs/` - Briefs
-- `curriculum/` - Teaching/learning order
-- `evals/` - Eval docs
-- `examples/` - Usage examples
-- `handoffs/` - Handoff docs
-- `implementation/` - Implementation guides
-- `issues/` - Detailed issue analyses
-- `lab/` - Experimental content (Not ratified)
-- `outreach/` - External comms
-- `plans/` - Plans
-- `research/` - Research notes
-- `sessions/` - Session logs
-- `specs/` - Specifications
-- `workbench/` - Workbench docs
-- `zig/` - Zig language docs
-- `agents/` - Agent-specific operational guides
 
-> **Note regarding `grokbuild/`**: Agent-specific operational guide for Grok 4.3 + Grok Build. Not architecture documentation. Candidate for relocation to `docs/agents/grok/`.
+## Directories
+
+### Architecture & Design
+- **[adr/](adr/)** - Architecture Decision Records (ADRs). The canonical history of all ratified engineering choices.
+- **[architecture/](architecture/)** - High-level architectural documents (e.g., pipelines, schemas).
+- **[analysis/](analysis/)** - Deep dives and master plans for structural changes.
+- **[specs/](specs/)** - Detailed technical specifications and invariants.
+
+### Planning & Progress
+- **[plans/](plans/)** - Capability roadmaps and implementation plans.
+- **[briefs/](briefs/)** - Project briefs and scoping documents for upcoming work.
+- **[issues/](issues/)** - Detailed issue analyses and technical reproductions (not standard trackers).
+- **[audit/](audit/)** - Audit reports and claims ledgers.
+
+### Operations & Usage
+- **[examples/](examples/)** - Usage examples and reference integrations.
+- **[workbench/](workbench/)** - Documentation for the CORE workbench UI and related tooling.
+- **[agents/](agents/)** - Agent-specific operational guides.
+  > **Note regarding `agents/grok/`**: Operational guide for using Grok 4.3 + Grok Build with CORE. This is not architecture documentation.
+
+### Learning & Evaluation
+- **[curriculum/](curriculum/)** - Documentation on the teaching/learning order and knowledge progression.
+- **[evals/](evals/)** - Evaluation methodology and performance criteria documentation.
+- **[benchmarks/](benchmarks/)** - Benchmark evidence and performance tracking logs.
+
+### Historical & Experimental
+- **[sessions/](sessions/)** - Chronological session logs documenting the "decision trail" and intellectual history of major choices.
+- **[handoffs/](handoffs/)** - Handoff documents transferred between agent sessions.
+- **[research/](research/)** - Raw research notes and preliminary findings.
+- **[lab/](lab/)** - Experimental content (Warning: Not ratified; must not be referenced as authoritative in production PRs).
+
+### External
+- **[outreach/](outreach/)** - External communications and messaging.
+- **[zig/](zig/)** - Scoped documentation for the Zig language components.