refactor(docs): cut README 551→138 + reorder examples by progression + trim headers#57
Merged
Merged
Conversation
…trim example headers Staff audit at .evolve/audits/2026-05-25-claude-staff-audit.md found: 1. The 17 examples teach a surface no production consumer uses. Grep across 6 product repos shows zero imports of runAgentTask / coderProfile / runLoop / createFanoutVoteDriver — real consumers import handleChatTurn (chat path) / defineAgent / runAnalystLoop / PlatformHubClient / DefaultVerdict. The example pedagogy was leading with the wrong primitive. 2. README was 551 lines on landing — overwhelming first impression. 3. Each loop+MCP+fleet example had a 15-line block comment narrating what the example IS — pure README content sitting in .ts file. Changes: - README: 551 → 138 lines. New structure: hello world is handleChatTurn (the real production surface), decision tree for picking entry points, defaults table, composition story with agent-eval / knowledge / sandbox. Full original archived to docs/README-full.md for one minor. - examples/README.md: reordered. chat-handler / with-knowledge-readiness / sanitized-telemetry-streaming / runtime-run are the "start here" progression. mcp-delegation is "add tools". coder-loop / researcher-loop / fleet-delegation are "advanced fanout". Lower-level building blocks (basic-task, sandbox-stream-backend, openai-stream-backend, sse-stream, sanitized-telemetry, agent-into-reviewer) demoted with one-minor migration note — they're now redundant with the consolidated four. - Trimmed 14-16-line JSDoc headers in coder-loop / researcher-loop / mcp-delegation / fleet-delegation to single-line // comments pointing at README.md. Code does the talking now. Verified: pnpm typecheck clean; 284/284 tests pass. Follow-ups (per audit, not in this PR): - backends.ts 897 LOC → split into ~5 files - Sweep JSDoc on every public export in src/index.ts - Add self-improving-loop composition example (agent-runtime + agent-eval + agent-knowledge + sandbox all wired — the 100x post-worthy demo) - Migration note for consumers still on 0.18.x (creative-agent)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Following a staff audit (`/.evolve/audits/2026-05-25-claude-staff-audit.md`) that found three big DX problems, this PR addresses the highest-leverage docs/examples fixes.
What the audit found
Changes
README: 551 → 138 lines
examples/README.md reorder
The four "start here" examples are everything a production product needs. The grab-bag of lower-level building blocks is demoted with a migration note.
Example header trims
Replaced 14-16 line JSDoc block comments in `coder-loop` / `researcher-loop` / `mcp-delegation` / `fleet-delegation` with single-line `//` pointers to README.md. Code does the talking now.
Verified
Follow-ups (in audit, not in this PR)