The map of every doc. Start here if you're new; the deeper tracks follow.
- The README — what the package is, a runnable offline quickstart, and the front-door table.
- concepts.md — the mental model (chat turns, tasks, runs) in plain terms.
- canonical-api.md — find the right primitive: "I want to ___ → use ___".
- ../examples/ — copy a runnable example near your task.
Building something specific? Go straight to canonical-api.md and the matching example — that's all you need to use the package. The tracks below are for understanding or extending the internals (design, RSI research, benchmark harness); skip them if you're just building.
These are internal working documents: design theses, research narrative, and roadmap bookkeeping for the team building the package. design.md is the plain-terms front door to all of them.
| # | Doc | Role | Purpose |
|---|---|---|---|
| 0 | design.md | front door | The design philosophy in plain terms + the map of the internal docs below. Start here for background. |
| 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. |
| 1a | agent-managed-compute/ | distributed execution plan | Current-state audit, converged design, failure behavior, dependency-ordered roadmap, and measurable completion criteria for agents that allocate and steer compute. |
| 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 | agent-managed-compute/roadmap.md | build plan | The canonical, dependency-ordered implementation roadmap: phases, exit gates, open decisions. |
| 4 | learning-flywheel.md | theory deep-dive | The cross-run learning thesis: why the outer improvement loop, not any single run, is the product. |
| 5 | eval-substrate.md | measurement principles | Neutral scoring, honest graders, and the claims discipline the team holds itself to. |
| 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/. |
| STABILITY.md | stability contract | What @stable / @experimental promise consumers, the graduation bar, and the demotion/removal policy. |
| 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. |
| improve.md | improvement reference | The improve() call, the optimizer object, official GEPA and SkillOpt installs, surfaces, redaction, and the proposal→review→activation path. |
| 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 | SQL-backed journal and restart behavior for conversations. Supervised-tree recovery is not implemented. |
| intelligence-sdk.md | product SDK | Observe + OFF billing floor + effort tiers + certified delivery + capability resolver — the /intelligence subpath. Designed-not-shipped verbs fenced at the tail. |
| live-agent-improvement-loop.md | execution contract | Trace-to-candidate-to-promotion path, evidence gates, and missing product joins for a live agent. |
| recursive-improvement-readiness.md | evidence scorecard | Dated pass/fail decisions for the live-agent improvement requirements. |
| 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 |
|---|---|---|
| design/prime-agent-harness-integration.md | integration contract | Prime Agent as a sandbox-materialized harness: the boundary, the anti-reinvention map, the substrate wish-list, and the first gated experiment. |
| simplification-plan.md | historical tracker | Earlier simplification analysis. The active execution and API convergence plan is agent-managed-compute/roadmap.md. |
| 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, benchmark-matrix consolidation). |
- 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.