Trim the README and relocate its reference material

[CCDevelopForFun]

Summary

The README had grown to 369 lines / 2,545 words and read as a reference manual rather than a front door. This brings it to 205 lines / ~1,200 words (−44% lines, −54% words) with nothing lost — every removed block moved to a file that either already existed or now does, verified mechanically rather than by eye.

The dominant problem was duplication of one fact. Adapter selection and prerequisites were restated across 17 lines in 8 separate places — the tagline, the intent paragraph, the quick-start agentctl run comments, the npm-install comments, the SVG alt text, the architecture prose, the ADL field table, and the chat section — each maintaining its own copy of "needs X CLI on PATH". Adding a fourth adapter meant editing all eight, which is exactly how the four accuracy bugs below crept in. They now collapse into a single ## Adapters table that is the source of truth, linked from everywhere else.

The second problem was the intent paragraph: 205 words enumerating every per-adapter exception (which harness rejects extensions, which rejects subagents, which pins which provider) — duplicating the capability matrix it linked to in the same breath. It now states the idea in two sentences and defers to the matrix.

Part 1: Changes

1. README.md:7-18 — one Adapters table replaces 17 scattered lines

| `runtime.type` | Harness | Package | Also needs |
|---|---|---|---|
| `local-pi` (or `local`) | Pi | `@agent-controller/runtime` | — |
| `local-opencode` | opencode | `@agent-controller/runtime-opencode` | `opencode` CLI on `PATH` |
| `local-codex` | Codex | `@agent-controller/runtime-codex` | `codex` CLI on `PATH`; `model.provider: openai` |
| `local-claude` | Claude Agent SDK | `@agent-controller/runtime-claude` | `model.provider: anthropic` |

Why this matters: a fifth adapter is now one row, not eight edits.

2. New docs/serve.md — the HTTP reference moves out

The ### Flags and ### Endpoints tables plus the curl example were 27 lines of API reference in a README. The README keeps a four-line orientation and a link; the tables, error codes, SSE frame format, and the deferred metrics/auth note all move intact.

3. New examples/README.md — the examples index gets a real home

The 14-row examples table was deleted from the README, but examples/ had no README, so it had nowhere to go. Created one — and expanded it, because the old table was itself incomplete: it covered 14 of the directory's 19 entries, omitting serve-test.yaml, with-installs.yaml, and any detail on bindings/ or schedulers/. Now organised as one-per-adapter / by-feature / serving-and-scheduling.

4. README.md:195-201 — Status and Repo layout become links

The 36-line Status section (a release table plus a <details> block of 11 v0.1.x tags) duplicated CHANGELOG.md, which documents every tag from v0.1.0 to v0.8.0 across 12 version sections. The 17-row Repo layout table duplicated the one in AGENTS.md. Both are now one-line links under ## Project.

5. Six accuracy fixes found while reading

Four are omissions from #3, the claude-adapter PR — each in one of the eight duplicated spots, which is the point:

• Repo layout had no runtime-claude/ row
• Source-clone build didn't build runtime-codex or runtime-claude
• e2e list read ADAPTER=pi|opencode|codex
• --resume was documented as "(Pi + opencode + codex)" though claude supports it

Two were pre-existing:

• The MCP section stated the Pi-only .pi/mcp.json mechanism as if it were general behaviour across adapters
• ## Commands listed agentctl serve nowhere despite a whole section documenting it

Part 2: Assumptions & Decisions

1. Relocate, never delete

   • Reasoning: a 54% cut is only safe if nothing valuable evaporates.
   • Verification: I extracted every distinctive token from the old README — flags, /v1/* endpoints, SCREAMING_CASE env vars, referenced file paths, agentctl <verb> forms — and asserted each still appears in the new README or a linked doc. Final result: 12 referenced files, 0 unreferenced; all --flags, endpoints, and env vars homed.

2. Kept the ADL field table in the README

   • Reasoning: it's the one reference block that earns front-door space — it's what a reader scans to decide whether the tool does what they need.
   • Alternative considered: move it to docs/. Rejected as it would leave the README unable to answer "what can I express?".

3. Kept the feature guides, tightened them

   • Reasoning: Skills / MCP / Guardrails / Tracing / Sessions / RuntimeBinding / Scheduler tasks are the "how do I use this" content — the opposite of the reference material being moved out. Grouped under one ## Feature guides heading and trimmed prose; the YAML snippets stay.

4. Left the version claim and the quick-start model id alone

   • Reasoning: both look questionable but changing either is a factual claim I can't verify from the docs. See Surprises.

Part 3: Potential Surprises

1. Two things I deliberately did not touch, both worth your call:

   • ## Project says "Developer preview" without a version. The old text said v0.7.0, which matches the latest git tag — but CHANGELOG.md documents [0.8.0] — 2026-07-02 as released, and the README already described serve as v0.8. Rather than pick a version I can't confirm, I dropped the number. If 0.8.0 shipped, the tag is missing.
   • The quick-start spec still uses claude-sonnet-4-20250514. It works (the pi-ai 0.82.1 bump only added newer ids), but it's a dated identifier while examples/hello-claude.yaml uses claude-opus-4-6. Changing it is a functional edit, not a verbosity one.

2. ## Feature guides introduces an h3 layer the README didn't have. It groups seven previously top-level sections, which shortens the GitHub sidebar table of contents considerably — a readability gain, but it does change the anchor links for those sections (e.g. #skills → still #skills, but #chat--sessions → #sessions). Any external deep links to the old anchors would break.

3. The ## Examples section is now three lines pointing at examples/README.md. If you'd rather the table stayed inline, it's one revert of that hunk — the new file can stay as the fuller index either way.

4. docs/serve.md is not linked from docs/architecture/README.md, which indexes the other docs. It isn't an architecture doc, so I left that index alone rather than widen its scope.

🤖 Generated with Claude Code