docs: rework README into per-feature sections with runnable examples - #96
Merged
Conversation
The README was feature-dense but section-light: Transports & primitives was one bullet blob, Profiles had a blurb instead of a section, and Status & roadmap was frozen at v0.3.0. New structure: TOC + a section per feature — the manifest (schema tour), rules (full match/when/respond walkthrough), PROFILES (the three sources: per-service bundles, adapter-authored profile_active() modes, global presets — semantics: pre-dispatch precedence, runtime-only, determinism), adapters, transports, state & primitives (+ lifecycle commands), webhooks, networking & TLS, observability & lifecycle, determinism, safety. Every example is verified runnable: the profiles block was booted verbatim (activate launch-day -> 4/12 curls 429 under chance:30, deactivate clean) and the rules quickstart blocks pass stunt plan. CLI snippets checked against --help (snapshot load not restore; state is a subcommand group). Status section rewritten to current facts with no version-pinned narrative; AGENTS.md loses its stale '91 adapters' count and binary size (both had drifted). No new hand-maintained numbers introduced; the readme-counts gate anchor is intact.
Accuracy review of #96 found four inherited drifts, all fixed: - the dashboard request inspector captures HTTP only (WS upgrades bypass the recorder; gRPC serves off its own listener) — README + dashboard.md no longer claim gRPC/WebSocket rows - webhook delivery retries, but attempts are not surfaced anywhere — dropped the 'dashboard shows every attempt' clause - '--json' scoped to the read commands that actually have it - network.mode is required, not defaulted — wording no longer implies you can omit it Two adjacent drifts the review surfaced: llm.go's in-binary reference said 'all 95 embedded' (it's 98 — number dropped so it can't drift again), and AGENTS.md's brew line lacked --cask (goreleaser ships a Cask; the plain form fails).
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.
Why
The README was feature-dense but section-light: "Transports & primitives" was one
bullet blob, Profiles (shipped in #68/#69) had a blurb instead of a section, and
"Status & roadmap" was frozen at v0.3.0 while we ship v0.52.0.
What
Full restructure with a TOC and a dedicated section per feature:
(
embedded:/ local /git:), per-service config, body caps.match/when/respondwalkthrough (globs, headers,chance/expr, latency, timeout behavior, inline|file|template bodies, faker).
rule bundles in stunt.yaml, adapter-authored
profile_active()modes, globalpresets), a driving section (CLI +
up --profile+ dashboard panel), and thesemantics people get bitten by (pre-dispatch precedence, WS/GraphQL not
intercepted, runtime-only, determinism + state-backed counter caveat).
Observability & lifecycle / Determinism — each with runnable snippets.
Verification
stunt planOK → healthy200 →
activate launch-day→ 4 of 12 curls 429 underchance: 30→ cleandeactivate. The transcript in the docs is the real CLI output.
stunt plan.--help(caught two fabrications on the way:snapshot restore→snapshot load,state <svc>→state collections <svc>).just readme-countsgate anchorline is intact and templating still passes. AGENTS.md drops its drifted
"91 adapters" count and binary size instead of renumbering them.