diff --git a/CLAUDE.md b/CLAUDE.md
index 0d52833..e3c9729 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -69,6 +69,13 @@ e2e/                 black-box tests driving the real binary as a subprocess
 3. Add `cmd/frob.go` — a thin adapter that parses flags and calls
    `mutate("frob", asJSON, func(env stack.Env, s *stack.State) (*stack.OpResult, error) { return stack.Frobnicate(env, s, arg) })`,
    self-registering via `init()` → `register(&Command{...})`. Add a `--json` flag.
+   If `frob` parses any flag beyond `--json`, also add a `frobFlagSet()` constructor
+   to `cmd/flagsets.go` declaring those flags, set `NewFlagSet: frobFlagSet` in its
+   `register(&Command{...})`, and list `frob`'s flags in `TestCommandFlagsMatchExpected`
+   (`cmd/execute_test.go`). `Run` parses the flags either way; this wiring keeps
+   `st help --json` (and the declared-flags contract in `docs/AGENT.md`) reporting
+   exactly what `Run` accepts — skip it and `make ci` fails with "update flagsets.go
+   or this table".
 4. If it has interesting CLI output, add a golden test (`cmd/golden_test.go`,
    regenerate with `go test ./cmd -run Golden -update`).
 5. `make ci`. Adding the command shifts the help golden — regenerate it deliberately.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b4c7d11..f8d42b2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,7 +41,11 @@ interface (JSON, exit codes).
    the fake git (`mkBranch`). Microseconds, no real git.
 3. **Adapter** — `cmd/frob.go`, a thin wrapper that self-registers and calls
    `mutate("frob", asJSON, func(env stack.Env, s *stack.State) (*stack.OpResult, error) { return stack.Frobnicate(env, s, arg) })`.
-   Add a `--json` flag (see `docs/AGENT.md` — every command speaks JSON).
+   Add a `--json` flag (see `docs/AGENT.md` — every command speaks JSON). For any
+   flag beyond `--json`, also add a `frobFlagSet()` to `cmd/flagsets.go`, set
+   `NewFlagSet: frobFlagSet` in `register()`, and list `frob`'s flags in
+   `TestCommandFlagsMatchExpected` — this keeps `help --json` reporting exactly
+   what `Run` accepts (or `make ci` fails with "update flagsets.go or this table").
 4. **Golden output** (optional) — `cmd/golden_test.go`; regenerate with
    `go test ./cmd -run Golden -update`.
 5. `make ci`. Adding a command shifts the `--help` golden — regenerate it