The map of every doc and the order to read them. Two tracks: Architecture (what the system is and where it's going) and Reference (how to use the package). On any architecture conflict, architecture.md wins.
| # | Doc | Role | Purpose |
|---|---|---|---|
| 1 | architecture.md | canonical spine | One recursive agent tree, two timescales, many benchmarks — the visual mental model (act/Scope/recursion, the up-flow, the three improvement timescales) folded in. The single source of truth; wins on conflict. |
| 2 | architecture-interpretations.md | coherence verdict | Stress-tests the spine through five lenses + the decision gate. Answers "does it cohere?" — and where it doesn't. |
| 3 | roadmap-rsi.md | build plan | The dependency-ordered sequence from scaffold to a measured surface. Phases, exit gates, open decisions. |
| 4 | learning-flywheel.md | theory deep-dive | The moat thesis — the (π, τ, J, D, O) recursion and cross-run flywheel. |
| 5 | eval-substrate.md | north star + discipline | The neutral measurement substrate, the data engine, and the measurement non-negotiables. |
| 6 | ../bench/HARNESS.md | empirical harness map | Commands, the data flow, the wired/needs-creds matrix, the canonical-suite runbook. |
| Doc | Role | Purpose |
|---|---|---|
| ../README.md | API entry point | Install, the loop API, the plain-language framing, the exported subpaths. Start HERE. |
| canonical-api.md | API spine + decision table | The conceptual spine + the "I want to ___ → use ___" anti-reinvention matrix of LOCAL symbols. Per-symbol signatures are generated into api/. |
| concepts.md | mental model | The product-API layer cake (chat turns, tasks, runs) — the onramp before the loop/strategy docs. |
| glossary.md | canonical vocabulary | One definition per term, grounded to file:line; drifted synonyms flagged. |
| execution-model.md | the picture | The unified Executor port (router/bridge/cli/sandbox/BYO) + two engines, driver vs worker, spawn mechanics. |
| agent-bus-protocol.md | normative protocol | The multi-agent call bus — depth limits, headers, refusal contract. |
| durability-adapters.md | subsystem | Journal + durability for resumable conversations + supervisor trees. |
| intelligence-sdk.md | subsystem | The product intelligence drop-in (withTangleIntelligence). |
| BUILDING.md | process | Building discipline: goal first, cheapest decisive proof, verification rules. |
| ANTI_PATTERNS.md | process | Named failure modes. |
| MAINTAINING.md | process | How the generated API reference + the docs-freshness gate stay honest. |
| Doc | Role | Purpose |
|---|---|---|
| simplification-plan.md | live tracker | The in-flight simplification/rearchitecture: the converged design, the scratch list, the doc/module inventory, the workstreams + completion criteria. |
| research/README.md | research index | Forward-looking design threads + decision log. Not the canonical spine. |
| archive/ | retired notes | Superseded/niche docs kept for history (delivery manifest, conversation economics, artifact-lifecycle, go-live, results). |
- On any architecture conflict,
architecture.mdwins; "Built vs Designed" is stated explicitly with afile:lineanchor — never assume a documented design is shipped without one. - The generated api/ reference + the docs-freshness gate (
scripts/check-docs-freshness.mjs) keep the curated docs honest: every backticked symbol must resolve. See MAINTAINING.md. - Repo bootloader + authorship/comment/layering deltas live in ../CLAUDE.md.