diff --git a/docs/architecture.md b/docs/architecture.md
index f2f5937..a3b6f23 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -143,6 +143,8 @@ Unusually central, and worth knowing even if you are not touching tests.
 | Repair | `docs/live-repair.md`, `repair.zig` |
 | The subscribe protocol | `docs/upstream-subscribe-protocol.md`, `server.zig` |
 | Timestamp import | `docs/timestamp-import.md`, `timestamp/` |
+| Running it — flags and env vars | `docs/configuration.md`, `runtime/cli.zig` |
+| The offline inspection subcommands | `docs/cli.md` |
 | Deploying | `docs/deployment-runbook.md`, `deploy/README.md`, `scripts/admit` |
 | Performance | `docs/benchmarks.md`, `just bench` |
 | Accepted limitations and traps | `docs/gotchas.md` |
diff --git a/docs/cli.md b/docs/cli.md
index 265608d..fa12d16 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,5 +1,12 @@
 # Offline operator commands
 
+**This file covers the inspection subcommands only.** The binary's primary
+command is `serve`, which runs the actual system; its options are documented in
+[`configuration.md`](configuration.md) and audited in
+[`configuration-parity.md`](configuration-parity.md). If you came here looking
+for how to run Stream, that is where to go — the four subcommands are
+`version`, `inspect-segment`, `inspect-all`, and `serve`.
+
 The binary exposes upstream's offline inspection commands. They do not start
 the server or open RocksDB, so they are safe against a data directory a live
 process owns.
diff --git a/docs/configuration.md b/docs/configuration.md
index b5b059c..aa5d55c 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -3,8 +3,17 @@
 What each runtime control does and what its defaults are. This is the operator
 reference; [`configuration-parity.md`](configuration-parity.md) is the audit of
 how well each one is *proved*, and [`semantic-parity.md`](semantic-parity.md)
-is the deployment gate. Runtime flags are declared in `src/main.zig`; deploy
-notes live in `deploy/README.md`.
+is the deployment gate. Serve flags are declared in
+`internal/runtime/cli.zig` — the offline subcommands are still dispatched from
+`src/main.zig`, but the serve option surface moved out of it. Deploy notes live
+in `deploy/README.md`.
+
+Flag and environment names are **derived from the options struct at comptime**
+rather than written out by hand: a field `backfill_workers` becomes
+`--backfill-workers` and `JETSTREAM_BACKFILL_WORKERS` via `flagName` /
+`envName`. So adding an option to the struct creates both spellings, and a
+mismatch between this document and the code is a documentation bug rather than
+two lists that drifted apart.
 
 Stream uses Jetstream V2's canonical names. Every canonical flag also reads the
 same `JETSTREAM_*` environment variable as the pinned upstream command.