From 89b2ddd490f1fbd80c767876b369efba9cc59e5c Mon Sep 17 00:00:00 2001 From: zzstoatzz Date: Thu, 30 Jul 2026 05:05:00 -0500 Subject: [PATCH] docs: configuration.md pointed at the wrong file for flag declarations "Runtime flags are declared in src/main.zig" stopped being true when 5e81128 lifted serve configuration into internal/runtime/cli.zig and ac09654 made flag/env names comptime-derived from the options struct. main.zig holds 29 flag strings, cli.zig holds 110. Corrected, and recorded the derivation itself -- a field backfill_workers becomes --backfill-workers and JETSTREAM_BACKFILL_WORKERS via flagName/envName -- because it means the two spellings cannot drift from each other, only from this document. cli.md is accurate: all six commands and flags it documents exist. Its problem is scope. It is named cli.md but covers three inspection subcommands, with no pointer to where the serve options live, so a newcomer opening it to learn the CLI would conclude the binary only inspects things. Added that pointer and named all four subcommands. Neither cli.md nor configuration.md was reachable from architecture.md's "Where to look" index, which is the entry point; both are now listed. Co-Authored-By: Claude Opus 5 (1M context) --- docs/architecture.md | 2 ++ docs/cli.md | 7 +++++++ docs/configuration.md | 13 +++++++++++-- 3 files changed, 20 insertions(+), 2 deletions(-) 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. -- 2.51.2