docs: extract CLI reference + run recipes into a runbook; slim README#35
Merged
Conversation
Mirrors the layout that v0.3.4's `agent-gate run --help` actually prints. The everyday flags (--mode, --enforce-allowlist, --config) stay together; --upstream-ca, --upstream-insecure-skip-verify, and --hijack-host move into a clearly labeled "advanced flags" block at the bottom so first-time readers see the common surface first. Drive-by: dropped the "advanced — most users don't need this" preamble from --hijack-host's description since the section heading now does that work, matching what we already shipped in the binary's help text. Added a one-liner pointing readers at `agent-gate run --help` so the README and the binary stay in sync as the source of truth.
The README had grown to 451 lines, with a long flag block, a CLI summary, a workflow section, a where-things-live list, and a limitations list — all reference material that buried the actual "what is this and why would I use it" front door. Split the reference material into `docs/RUNBOOK.md` (293 lines): * Full command list * Per-subcommand flag reference (run, init, doctor) with the same layout the binary's --help prints * "Picking a mode" + "When to reach for the advanced flags" tables that explain the rare-but-needed flags in plain English * Recommended / standalone / self-hosted-endpoint workflow recipes * Install variants (brew, binary download, build from source) * On-disk layout * Operational caveats (HTTP/2 transparency, OS-specific limitations, pinned upstreams, etc.) The README (now 255 lines, -44%) keeps the product overview, support matrix, agent table, features list, screenshots, How-It-Works diagram, threat model, three-list policy summary, built-in policy rules table, what's-next, and the contributor sections. Each formerly-extracted section gets a one-line pointer to the runbook. Quick Start is now a single 4-line code block (brew tap / install / init / run) plus a runbook link, instead of three separate code blocks for macOS / non-Homebrew / headless. Pure docs reorganization. No code, no behavior change. Verified section anchors in the runbook match what README links target.
* Install — runbook already has the full Install section (brew, binary download, build from source). The Quick Start above already shows `brew tap WZ/tap && brew install agent-gate`, so the duplicate README block was carrying no extra information for users who'd follow the runbook link anyway. * What's next — release-history paragraphs that drift the moment a new tag ships. TODOS.md and the GitHub Releases page are the live source. * Project layout — directory listing aimed at contributors. CLAUDE.md has the same map for AI assistants; humans wanting to navigate the source can read the source. Removing this from the README keeps the front door focused on "what does agent-gate do for me." README is now 212 lines (down from 451 before the runbook split, -53%). The remaining sections are all things a first-time visitor benefits from seeing inline: support matrix, features, quick start, the three dashboard screenshots, airtight + threat model, three-list policy summary, built-in rules table, what-we-don't-do, dev / license.
Runbook restructure: lead with Install (one-time setup) and Run an agent (the everyday command), since those are what readers actually arrive looking for. The per-subcommand flag reference and the full command list move below the recipes; the command list is now an appendix at the very bottom. Install + Run are visually leaner: each opens with the one-line command and follows with a short paragraph. The "Want the dashboard always on?" subsection makes the reuse behavior introduced in v0.3.3 discoverable instead of tucked inside a flag-table footnote. README feature list is also trimmed: each bullet was a 2-3 sentence description that read like release notes. Replaced with one-line hooks that name the capability and the user-visible win, leaving mechanism details for the runbook + threat-model sections.
The "What is rich today" and "TODO" columns were 2-4 sentence prose blocks each. Hard to scan at the table level — eye couldn't pick out "what does agent-gate actually parse for this agent" from the narrative around it. Replaced the prose with HTML <ul> bullet lists inside each cell. GitHub renders them as proper bullets inside table cells, so the table reads like "agent → here are the bullets of what works, here are the bullets of what's left." Same information, easier to scan column-by-column. Codex row gains an explicit "WS pins TLS → ws_pinned_upstream flag" bullet, surfacing the pinning advisory at the top-of-funnel doc instead of burying it in the operational caveats further down.
Same treatment as the previous commit on the Agents table — convert the prose-heavy Current behavior / TODO columns into <ul> bullet lists so each cell scans column-by-column instead of as a paragraph. Same information, easier to compare across rows.
* Airtight launcher — tighten the intro from two sentences to one;
Notes column gets <ul> bullets to match the Platforms / Agents
table treatment from the previous commits.
* Threat model — promoted from H3-under-airtight to its own H2.
It's about agent-gate's overall security posture (network audit,
not sandbox/RBAC), not just the airtight launcher mode. Lead with
the one-liner that sets the right mental model. "Defends against"
/ "Does NOT defend against" stay as bullet lists but with a
pithier framing and a closing recommendation to pair with OS-level
sandboxing if the user needs filesystem isolation.
* Three-list policy model — lead with the resolution order (the
mental model the user actually needs to internalize). The table
follows as concrete reference. The middle column is now "Add a
host when…" instead of "Effect", since the effect is already
visible in the resolution-order block above and "when would I
use this list" is the question users are actually trying to
answer.
* Built-in policy rules — split the single nine-row table into
four severity-grouped tables (high / medium / low / info) with a
one-line framing for each group ("likely worth a look", "usually
benign but unusual", "noise tracking", "context not concern").
Severity is now scannable at a glance instead of buried in a
middle column. Added a closing one-liner about per-flag dismiss
to surface that workflow.
WZ
added a commit
that referenced
this pull request
May 8, 2026
Re-application of 0ad20f4 from PR #35 — that commit didn't make the merge because the Platforms / Agents tables moved location in 8eb9b71 between my push and the merge. Cuts the 'init detects X and seeds Y' phrasing to 'Auto-detected; HOST seeded', and stops paraphrasing what the agent column already says. Same information; ~half the visual weight per row.
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
README had grown to 451 lines, with reference material (full flag block, CLI summary, workflow recipes, where-things-live list, limitations list) competing with the front-door product overview. New users hit a wall of detail before they got to "what is this and why would I use it."
What changes
New: `docs/RUNBOOK.md` (293 lines)
Operational reference. Covers:
Slimmed: `README.md` (451 → 255 lines, -44%)
Keeps the front door:
Each formerly-extracted section gets a one-line pointer to the runbook for full detail.
Test plan