docs(readme): lead with the front doors consumers actually use

[drewstone]

Why

A measured DX audit read the README cold and counted the entry points that real consumers use: 183 importing files across 10 repositories. Findings that drove every decision here:

• README was 591 lines / 3,433 words, about 71% prose. 28 of ~40 concepts were never defined; 5 were defined after first use.
• The flagship runAgentRounds example did not compile as pasted (worker, output, validator free identifiers; Task and Note undefined) and has zero real call sites in the fleet.
• The most imported symbol fleet-wide is RuntimeStreamEvent (36 files). The README never mentioned it.
• One API family (improve) took 40.6% of the file, including an 86-line code block and pip installs pinned to git revisions.
• The worst paragraph ran 12 sentences and 193 words.

What changed

README: 591 → 127 lines, 3,433 → 1,176 words.

• The quickstart is now examples/quickstart/minimal.ts in full. It compiles and runs as pasted, offline.
• One decision table replaces the three routers that disagreed (README 5-row, canonical-api §2.1 4-verb, canonical-api §2 75-row). Columns follow agent-eval's concepts.md pattern: when to call it, what you give it, what you get back. Rows are ordered by real consumer use, so runAgentTaskStream leads and the zero-consumer driver pattern is no longer the front door.
• A five-word table defines worker, driver, decision, verdict, and harness under the quickstart.
• docs/improve.md and docs/primeintellect.md receive the moved reference material, pinned pip revisions included. Retained-run depth moves into its example, which also carries the "what died → which mechanism continues it" table for the five continuity paths.

Examples: one directory per front door, each README in three sections — when to use it (honest, against its siblings), how to use it (runnable compiling code), why it exists.

Directory	When to use it
stream-a-turn (new)	You run one agent turn and read its events yourself.
chat-handler	A web route must stream one turn to a browser and save the reply.
stream-backends	You must choose where the tokens come from.
tool-loop (new)	The model must call your tools and then answer in the same turn.
runtime-run	You must record what a run cost and whether it succeeded.
quickstart (absorbed)	One prompt is not enough, and your code owns the stop rule.
supervise	A model must decide the plan, not your code.
retained-run (new)	The job must outlive the process that started it.
improve	You must change one part of an agent and prove the change is better.

examples/quickstart now holds minimal.ts (the README quickstart) and quickstart.ts (the same call grown into a refine loop), so there is one place for the loop instead of two.

Two API honesty fixes

1. TERMINAL_DECISIONS, TerminalDecision, and isTerminalDecision are exported from /kernel. The four values that stop the loop were a private string comparison, so a reader could not tell kernel keywords (stop, pick-winner, fail, done) from caller vocabulary. Drivers can now type decide as 'your-word' | TerminalDecision.
2. Driver.name documents that it is a trace label with no behavioral effect, and the quickstart stops naming a driver 'refine' — a word that also worked as a decision value three lines later.

Out of scope, deliberately: the /kernel barrel exports 770 names (767 before this change). Tiering that surface is real work and belongs in its own change.

Proof

• pnpm typecheck (source + examples): clean. tsconfig.examples.json gains the /tool-loop path mapping so the new example resolves.
• pnpm lint: 596 files checked, no findings.
• pnpm run docs:freshness: OK, no drift. docs/api regenerated for the three new kernel exports.
• Every runnable example prints what its README claims: minimal.ts → decision: done — 1 iteration(s); quickstart.ts → decision: pick-winner — winner: shot 1; stream-a-turn → cost: $0.0009 — reply chars: 81; tool-loop → turns: 2 — stopReason: completed. retained-run is compile-checked only, and its README says so: no in-repo provider advertises the seven retained capabilities.
• pnpm test: 2,696 of 2,711 tests pass. Every failure is a 15s/20s/60s timeout under concurrent load on this host, and the set changes between runs. The three files that failed in the full run pass in isolation (79/79), as do the tests for the changed code path (run-loop.test.ts + run-loop.provenance.test.ts, 31/31).

[tangletools]

✅ Auto-approved drewstone PR — 58f581f2

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-15T07:03:36Z}

[tangletools]

✅ Auto-approved drewstone PR — 8b570a08

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-15T07:05:23Z}

[tangletools]

✅ Auto-approved drewstone PR — 07186d45

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-15T07:09:01Z}

[tangletools]

✅ Auto-approved drewstone PR — 3d4abe1c

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-15T07:33:26Z}

[tangletools]

✅ Auto-approved drewstone PR — 3d4abe1c

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-15T08:06:17Z}

[drewstone]

@tangletools review now

[tangletools]

✅ Auto-approved drewstone PR — 3d4abe1c

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-15T08:16:16Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Coverage	2 of 2 lenses (value, usefulness)
Concerns	3 (1 low, 2 weak-concern)
Heuristic	0.0s
Duplication	0.2s
Interrogation	470.5s (2 bridge agents)
Total	470.7s

💰 Value — sound-with-nits

Rewrites the README around a usage-ordered front-door table with a verified-compiling quickstart, adds the three missing front-door examples, and promotes the terminal-decision vocabulary to public API — a coherent, verified improvement; two weak concerns only.

• What it does: Three deltas. (1) README 591→133 lines: the flagship quickstart is now examples/quickstart/minimal.ts in full (self-contained; old version at 08fc914:README.md:36-67 referenced free identifiers output/validator/Task/Note defined only in another file), a 9-row front-door table ordered by real consumer use replaces the old 5-row router, the 240-line improve deep-dive and PrimeIntellect section move
• Goals it achieves: Make the package's front door match what real consumers actually do: a quickstart that compiles and runs as pasted (verified), the fleet's most-imported symbol RuntimeStreamEvent finally named in the README (README.md:84), runnable examples for the two front doors that had none (runToolLoop, startRetainedRun), reference depth moved out of the install-time page into docs/, and the terminal-decision
• Assessment: Good on its merits and in the codebase's grain. Every claim I could test held: pnpm typecheck:examples passes; after pnpm build, minimal.ts, quickstart.ts, stream-a-turn.ts, and tool-loop.ts all run offline and print exactly the outputs the READMEs promise; the old quickstart demonstrably did not compile as pasted; docs/api regeneration is in sync with the new exports and docstrings; the '33 examp
• Better / existing approach: none — this is the right approach. Searched for prior art before concluding: no example used runToolLoop (rg hits only in src/, docs/, tests); no example or doc demo covered startRetainedRun for consumers; runAgentTaskStream appeared only inside examples/stream-backends' three-factory comparison and examples/agents-of-all-shapes, neither of which teaches the bare contract. The lighter alternative
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: opencode: opencode error

🎯 Usefulness — sound

An evidence-driven README/examples rewrite plus a minimal, correct kernel export (TERMINAL_DECISIONS/TerminalDecision/isTerminalDecision) that makes the documented front doors compile, run offline, and match measured consumer usage; every claim I checked held.

• Integration: Verified reachable and wired. pnpm run typecheck:examples passes; all four runnable examples execute offline and minimal.ts prints exactly the README-claimed decision: done — 1 iteration(s). The new exports flow src/runtime/run-loop.ts:1223-1231 → src/runtime/index.ts:386-394 → tsdown kernel entry → package.json ./kernel, and the generated docs were regenerated (docs/api/runtime.md:19638
• Fit with existing patterns: Fits the grain. The code delta is a pure visibility change (private isTerminalDecision → exported const array + type predicate; identical logic, run-loop tests 11/11 pass), which exists so the README example can type decide without inline string unions — the exact awkwardness the old example exposed. The examples follow the established pattern (one dir per front door, imports via published pac
• Real-world viability: The examples are deterministic and verified to run; the retained-run example is honestly labeled compile-checked-only and that is accurate — startRetainedRun requires a real provider and an awaited onAdmission hook (retained-run-start.ts:75), and the file's guard prints its template notice instead of failing. The quickstart rewrite drops maxIterations: 3 but the plan closure still caps attempt
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🔎 Heuristic Signals

🟡 Cruft: console debug added examples/quickstart/minimal.ts

+console.log(decision: ${result.decision} — ${result.iterations.length} iteration(s))

💰 Value Audit

🟡 stream-a-turn overlaps stream-backends' first section [duplication] ``

Both write a scripted backend by hand and call runAgentTaskStream (examples/stream-backends/stream-backends.ts:34-42 vs examples/stream-a-turn/stream-a-turn.ts:29-78). The overlap is deliberate and bounded — stream-backends is about choosing among three factory sources, stream-a-turn about the bare AgentExecutionBackend contract plus the full event vocabulary (llm_call, final) — and each README points to the other as the sibling for its non-question (stream-backends/README.md:14-16). Keeping bot

🟡 'front door' now names two different routers [maintenance] ``

The PR motivates the rewrite by the three disagreeing routers, but only the README's side is reconciled: docs/canonical-api.md §2.1 (line 192) still titles itself 'Which front door do I use?' with a disjoint four-verb list (delegate/supervise/runAgentic/runPersonified), while README.md:77-92 presents nine front doors ordered by consumer use. The audiences differ (contributor vs npm consumer) so it is not a contradiction, but the shared term now has two authoritative tables with no cross-referenc

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260815T082521Z}