fix(cli): #122 doctor invocation now checks stale-base condition — added run_stale_base_preflight(None) call to doctor action handler, matching Prompt + REPL dispatch ordering; closes inconsistency where doctor says 'ok' but prompt warns 'stale base'

Cycle #46 follow-up to cycle #45's #251 implementation. Closes #250's
implementation urgency by aligning docs with reality.

SCHEMAS.md Updates:
For each of the 4 session-management verbs, added:
1. Status marker (Implemented or Stub only)
2. Actual binary envelope (shape produced by the #251-fixed binary)
3. Aspirational (future) shape (original SCHEMAS.md content, preserved as target)
4. Gap notes where the two diverge

Per-verb status:
- list-sessions: Implemented, nested field layout
- load-session: Implemented, nested session object with local session_not_found error
- delete-session: Stub, emits not_yet_implemented (local error, not auth)
- flush-transcript: Stub, emits not_yet_implemented (local error, not auth)

ROADMAP.md Updates:
- #251 marked CLOSED: Full status with commit ref, test counts.
- #250 marked SCOPE-REDUCED: Option A resolved by #251, Option C moot,
  only Option B (doc alignment) remains as future cleanup.

Why this matters:
Every code change should close its documentation loop. #251 landed on
the branch, but SCHEMAS.md still described aspirational shapes without
marking which were implemented. Claws reading SCHEMAS.md would have
assumed full conformance and hit surprises. Now the document tells the
truth about which verbs work, which are stubs, and why.

Related:
- #251 implementation on feat/jobdori-251-session-dispatch branch
- #250 scope-reduced to Option B (field-name harmonization)
- #145/#146 parser fall-through fix precedent

ROADMAP.md

@@ -6794,6 +6794,8 @@ Natural bundle: **#247 + #248 + #249** — classifier/envelope completeness swee
 
 ## Pinpoint #250. CLI surface parity gap between Python audit harness and Rust binary — SCHEMAS.md documents `list-sessions`/`delete-session`/`load-session`/`flush-transcript` as CLAWABLE top-level subcommands, but the Rust `claw` binary routes these through the `_other => Prompt` fall-through arm, emitting `missing_credentials` instead of running the documented operation
 
+**STATUS: 🟡 SCOPE-REDUCED (cycle #46, 2026-04-23)** — #251's implementation work (Option A) is closed: the 4 verbs now route locally and do not emit `missing_credentials`. SCHEMAS.md updated cycle #46 to document the actual binary envelope shapes (with ⚠️ Stub markers on `delete-session`/`flush-transcript`). **Option C (reject-with-redirect) is moot** — no verbs to redirect away from. **Remaining work = Option B (documentation scope alignment)**: harmonize field names (`id` vs `session_id`, `updated_at_ms` vs `last_modified`, etc.) across actual and aspirational shapes, and add common-envelope fields (`timestamp`, `exit_code`, `output_format`, `schema_version`). This is a future cleanup, not blocking any user-visible behavior.
+
 **Gap.** SCHEMAS.md at the repo root defines a JSON envelope contract for 14 CLAWABLE top-level subcommands including `list-sessions`, `delete-session`, `load-session`, and `flush-transcript`. The Python audit harness at `src/main.py` implements all 14. The Rust `claw` binary at `rust/crates/rusty-claude-cli/` does NOT have these as top-level subcommands — session management lives behind `--resume <id> /session list` via the REPL slash command path.
 
 A claw following SCHEMAS.md as the canonical contract runs `claw list-sessions --output-format json` and hits the Rust binary's `_other => Prompt` fall-through arm (same code path as the now-closed parser-level trust gap quintet #108/#117/#119/#122/#127). The literal token `"list-sessions"` is sent as a prompt to the LLM, which immediately fails with `missing Anthropic credentials` because the prompt path requires auth.
@@ -6876,6 +6878,8 @@ Natural bundle: **#127 + #250** — parser-level fall-through pair with a class
 
 ## Pinpoint #251. Session-management verbs (`list-sessions`/`delete-session`/`load-session`/`flush-transcript`) fall through to Prompt dispatch at parse time before credential resolution — wrong error CLASS is emitted (auth) for what should be local session-store operations
 
+**STATUS: ✅ CLOSED (cycle #45, 2026-04-23)** — commit `dc274a0` on `feat/jobdori-251-session-dispatch`. 4 CliAction variants + 4 parser arms + 4 dispatcher arms. `list-sessions` and `load-session` fully functional; `delete-session` and `flush-transcript` stubbed with `not_yet_implemented` local errors (satisfies #251 acceptance criterion — no `missing_credentials` fall-through). All 180 binary tests + 466 library tests + 95 compat tests pass. Dogfood-verified on clean env (no credentials). Pushed for review.
+
 **Gap.** This is the **dispatch-order framing** of the parity symptom filed at #250. Where #250 says "the surface is missing on the canonical binary and SCHEMAS.md promises it," #251 says "the underlying mechanism is a top-level parser fall-through that happens BEFORE the dispatcher can intercept the verb, so callers get `missing_credentials` instead of any session-layer response at all."
 
 The two pinpoints describe the same observable failure from different layers:
@@ -6977,3 +6981,538 @@ No credential resolution is triggered for any of these paths.
 - #250 (surface parity framing of same failure)
 - §4.44 typed-envelope contract
 - SCHEMAS.md (specifies the 4 session-management verbs as top-level CLAWABLE surfaces)
+
+---
+
+## Pinpoint #130b. Filesystem errors discard context and collapse to generic errno strings
+
+**Concrete observation (cycle #47 dogfood, 2026-04-23 01:31 Seoul):**
+
+```bash
+$ claw export latest --output /private/nonexistent/path/file.jsonl --output-format json
+{"error":"No such file or directory (os error 2)","hint":null,"kind":"unknown","type":"error"}
+```
+
+**What's broken:**
+- Error is generic errno string with zero context
+- Doesn't say "export failed to write"
+- Doesn't mention the target path
+- Classifier defaults to "unknown" even though code path knows it's filesystem I/O
+
+**Root cause (traced at main.rs:6912):**
+The `run_export()` function does `fs::write(path, &markdown)?;`. When this fails:
+1. `io::Error` propagates via `?` to `main()`
+2. Converted to string via `.to_string()`, losing all context
+3. `classify_error_kind()` can't match "os error" or "No such file"
+4. Defaults to `"kind": "unknown"`
+
+**Fix strategy:**
+Wrap `fs::write()`, `fs::read()`, `fs::create_dir_all()` in custom error handlers that:
+1. Catch `io::Error`
+2. Enrich with operation name + target path + `io::ErrorKind`
+3. Format into recognizable message substrings (e.g., "export failed to write: /path/to/file")
+4. Allow `classify_error_kind()` to return specific kind (not "unknown")
+
+**Scope and next-cycle plan:**
+Family-extension work (filesystem domain). Implementation:
+1. New `filesystem_io_error()` helper wrapping `Result<T, io::Error>` with context
+2. Apply to all `fs::*` calls in I/O-heavy commands (export, diff, plugins, config, etc.)
+3. Add classifier branches for "export failed", "diff failed", etc.
+4. Regression test: export to nonexistent path, assert `kind` is NOT "unknown"
+
+**Acceptance criterion:**
+Filesystem operation errors must emit operation name + path in error message, enabling `classify_error_kind()` to return specific kind (not "unknown").
+
+---
+
+## Pinpoint #153b (follow-up). Add binary PATH setup guide to README
+
+**Concrete gap (from cycle #48 assessment):**
+
+#153 filed in cycle #30 but never landed. New users post-`cargo build --workspace` don't know:
+1. Where binary ends up (`rust/target/debug/claw` vs. `/usr/local/bin/claw`)
+2. How to verify build (e.g., `./rust/target/debug/claw --help`)
+3. How to add to PATH for shell integration
+
+**Real user friction (from #claw-code):**
+- "claw not found — did build fail?"
+- "do I need `cargo install`?"
+- "why is it at `rust/target/debug/claw` and not just `claw`?"
+
+**Fix shape (minimal, ~40 lines):**
+Add "Post-build: Add to PATH" section in README (after Quick start), covering:
+1. **Binary location:** `rust/target/debug/claw` (debug) or `rust/target/release/claw` (release)
+2. **Quick verification:** `./rust/target/debug/claw --help` (no install needed)
+3. **Optional PATH setup:**
+   ```bash
+   export PATH="$PWD/rust/target/debug:$PATH"
+   claw --help  # should work from anywhere
+   ```
+4. **Permanent setup:** Add the export to `.bashrc` / `.zshrc` if desired
+
+**Acceptance criterion:** After reading this section, a new user should be able to build and run `claw` without confusion about where the binary is or whether the build succeeded.
+
+**Next-cycle action:** Implement #153 (original gap) + #153b (this follow-up) as single 60-line README patch.
+
+---
+
+## Pinpoint #130c. `claw diff --help` rejected with "unexpected extra arguments" — no help available for pure-local introspection commands
+
+**Concrete observation (cycle #50 dogfood, 2026-04-23 01:43 Seoul):**
+
+```bash
+$ claw diff --help
+[error-kind: unknown]
+error: unexpected extra arguments after `claw diff`: --help
+
+$ claw config --help
+[error-kind: unknown]
+error: unexpected extra arguments after `claw config`: --help
+
+$ claw status --help
+[error-kind: unknown]
+error: unexpected extra arguments after `claw status`: --help
+```
+
+All three are **pure-local introspection commands** (no credentials needed, no API calls). Yet none accept `--help`, making them less discoverable than other top-level subcommands.
+
+**What's broken:**
+- User cannot do `claw diff --help` to learn what diff does
+- User cannot do `claw config --help`
+- User cannot do `claw status --help`
+- These commands are less discoverable than `claw export --help`, `claw submit --help`, which work fine
+- Violates §4.51 help consistency rule: "if a command exists, --help must work"
+
+**Root cause (traced at main.rs:1063):**
+
+The `"diff"` parser arm has a hard constraint:
+```rust
+"diff" => {
+    if rest.len() > 1 {
+        return Err(format!(
+            "unexpected extra arguments after `claw diff`: {}",
+            rest[1..].join(" ")
+        ));
+    }
+    Ok(CliAction::Diff { output_format })
+}
+```
+
+When parsing `["diff", "--help"]`, the code sees `rest.len() > 1` and rejects `--help` as an extra argument. Similar patterns exist for `config` (line 1131) and `status` (line 1119).
+
+The help-detection code at main.rs:~850 has an early check: `if rest.is_empty()` before treating `--help` as "wants help". By the time `--help` reaches the individual command arms, it's treated as a positional argument.
+
+**Fix strategy:**
+
+Two options:
+
+**Option A (preferred): Unified help-before-subcommand parsing**
+Move `--help` and `--version` detection to happen **after** the first positional (`rest[0]`) is identified but **before** the individual command arms validate arguments. Allows `claw diff --help` to map to `CliAction::HelpTopic("diff")` instead of hitting the "extra args" error.
+
+**Option B: Individual arm fixes**
+Add `--help` / `-h` checks in each pure-local command arm (`diff`, `config`, `status`, etc.) before the "extra args" check. Repeats the same guard in ~6 places.
+
+Option A is cleaner (single fix, helps all commands). Option B is surgical (exact fix locus, lower risk of regression).
+
+**Scope and next-cycle plan:**
+File as a **consistency/discoverability gap**, not a blocker. Can ship as part of #141 help-consistency audit, or as standalone small PR.
+
+**Acceptance criterion:**
+- `claw diff --help` → emits help for diff command (not error)
+- `claw config --help` → emits help for config command
+- `claw status --help` → emits help for status command
+- Bonus: `claw export --help`, `claw submit --help` continue to work (regression test)
+
+---
+
+## Pinpoint #130d. `claw config --help` silently ignores help flag and runs config display
+
+**Concrete observation (cycle #52 dogfood, 2026-04-23 01:53 Seoul):**
+
+```bash
+$ claw config --help
+Config
+  Working directory /private/tmp/dogfood-probe-47
+  Loaded files      0
+  Merged keys       0
+  ...
+  (displays full config, ignores --help)
+```
+
+Expected: help for the config command. Actual: runs the config command, silent acceptance of `--help`.
+
+**Comparison (help inconsistency family):**
+- `claw diff --help` → error (rejects as extra arg) [#130c — FIXED]
+- `claw config --help` → silent ignore, runs command ⚠️
+- `claw status --help` → shows help ✅
+- `claw mcp --help` → shows help ✅
+
+**What's broken:**
+- User expecting `claw config --help` to show help gets the config dump instead
+- Silent behavior: no error, no help, just unexpected output
+- Violates help-parity contract (other local commands honor `--help`)
+
+**Root cause (traced at main.rs:1131):**
+
+The `"config"` parser arm accepts all trailing args:
+```rust
+"config" => {
+    let cwd = rest.get(1).and_then(|arg| {
+        if arg == "--cwd" {
+            rest.get(2).map(|p| p.as_str())
+        } else {
+            None
+        }
+    });
+    // ... rest of parsing, `--help` falls through silently
+    Ok(CliAction::Config { ... })
+}
+```
+
+Unlike the `diff` arm (which explicitly checks `rest.len() > 1`), the `config` arm parses arguments positionally (`--cwd VALUE`) and silently ignores unrecognized args like `--help`.
+
+**Fix strategy:**
+
+Similar to #130c but with different validation:
+1. Add `Config` variant to `LocalHelpTopic` enum
+2. Extend `parse_local_help_action()` to map `"config" => LocalHelpTopic::Config`
+3. Add help-flag check early in the `"config"` arm:
+   ```rust
+   "config" => {
+       if rest.len() >= 2 && is_help_flag(&rest[1]) {
+           return Ok(CliAction::HelpTopic(LocalHelpTopic::Config));
+       }
+       // ... existing parsing
+   }
+   ```
+4. Add help topic renderer for config
+
+**Scope:**
+Low-risk, high-clarity UX fix. Same pattern as #130c. Completes the help-parity sweep for local introspection commands.
+
+**Acceptance criterion:**
+- `claw config --help` → emits help for config command (not config dump)
+- `claw config -h` → same
+- `claw config` (no args) → still displays config dump
+- `claw config --cwd /some/path` (valid flag) → still works
+
+**Next-cycle plan:**
+Implement #130d to close the help-parity family. Stack on top of #130c branch for coherence.
+
+---
+
+## Pinpoint #130e. Help-parity sweep reveals 5 additional anomalies; 3 are dispatch-order bugs (#251-family)
+
+**Concrete observation (cycle #53 dogfood, 2026-04-23 02:00 Seoul):**
+
+Systematic help-parity sweep of all 22 top-level subcommands revealed 5 additional anomalies beyond #130c/#130d:
+
+### Category A: Dispatch-order bugs (#251-family, CRITICAL)
+
+**`claw help --help` → `missing_credentials` error**
+```bash
+$ claw help --help
+[error-kind: missing_credentials]
+error: missing Anthropic credentials; export ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY...
+```
+The `help` verb with `--help` is NOT intercepted at parse time; falls through to credential check before dispatch. Should emit meta-help (explain what `claw help` does), not cred error.
+
+**`claw submit --help` → `missing_credentials` error**
+```bash
+$ claw submit --help
+[error-kind: missing_credentials]
+error: missing Anthropic credentials...
+```
+Same dispatch-order class as #251 (session verbs). `submit --help` should show help for the submit command, not attempt credential check. This is a critical discoverability gap — users cannot learn what `submit` does without credentials.
+
+**`claw resume --help` → `missing_credentials` error**
+```bash
+$ claw resume --help
+[error-kind: missing_credentials]
+error: missing Anthropic credentials...
+```
+Same pattern. `resume --help` should show help, not require credentials.
+
+### Category B: Help-surface outliers (like #130c/#130d)
+
+**`claw plugins --help` → "Unknown /plugins action '--help'"**
+```bash
+$ claw plugins --help
+Unknown /plugins action '--help'. Use list, install, enable, disable, uninstall, or update.
+```
+Treats `--help` as a subaction of plugins (list/install/enable/etc.) rather than a help flag. At least the error is specific, but wrong.
+
+**`claw prompt --help` → silent passes through, shows version + top-level help**
+```bash
+$ claw prompt --help
+claw v0.1.0
+
+Usage:
+  claw [OPTIONS]
+  ...
+```
+Shows top-level help instead of prompt-specific help. Different failure mode from silent-ignore (#130d) — this actually prints help but the wrong help.
+
+### Summary Table
+
+| Command | Observed | Expected | Class |
+|---|---|---|---|
+| `help --help` | missing_credentials | meta-help | Dispatch-order (#251) |
+| `submit --help` | missing_credentials | submit help | Dispatch-order (#251) |
+| `resume --help` | missing_credentials | resume help | Dispatch-order (#251) |
+| `plugins --help` | "Unknown action" | plugins help | Surface-parity |
+| `prompt --help` | top-level help | prompt help | Wrong help shown |
+
+### Fix Scope
+
+**Category A (dispatch-order)**: Follow #251 pattern. Add `help`, `submit`, `resume` to the parse-time help-flag interception, same as how `diff` (#130c) and `config` (#130d) handle it. This is the SAME BUG CLASS as #251 (session verbs) — parser arm dispatches before help flag is checked.
+
+**Category B (surface-parity)**: Follow #130c/#130d pattern. Add `--help` handling in the specific arms for `plugins` and `prompt`, routing to dedicated help topics.
+
+### Acceptance Criterion
+
+All 22 top-level subcommands must accept `--help` and `-h`, routing to a help topic specific to that command. No `missing_credentials` errors for help flags. No "Unknown action" errors for help flags.
+
+### Next-Cycle Plan
+
+Split into two implementations:
+- **#130e-A** (dispatch-order): fix `help`, `submit`, `resume` — high-priority, same class as #251
+- **#130e-B** (surface-parity): fix `plugins`, `prompt` — follow #130c/#130d pattern
+
+Estimated: 10-15 min each for implementation, dogfood, tests, push.
+
+---
+
+## Cluster Closure Note: Help-Parity Family (#130c, #130d, #130e) — COMPLETE
+
+**Timeline: Cycles #47-#54, ~95 minutes**
+
+### What the Family Solved
+
+Universal help-surface contract: **every top-level subcommand accepts `--help` and emits scoped help topics** instead of errors, silent ignores, wrong help, or credential leaks.
+
+### Framing Refinement (Gaebal-gajae, Cycle #53-#54)
+
+Two distinct failure classes discovered during systematic sweep:
+
+**Class A (Dispatch-Order / Credential Misdirection — HIGHER PRIORITY):**
+- `claw help --help` → `missing_credentials` (fell through to cred check)
+- `claw submit --help` → `missing_credentials` (same dispatch-order bug as #251)
+- `claw resume --help` → `missing_credentials` (session verb, same class)
+
+**Class B (Surface-Level Help Routing — LOWER PRIORITY):**
+- `claw plugins --help` → "Unknown /plugins action '--help'" (action parser treated help as subaction)
+- `claw prompt --help` → top-level help (early `wants_help` interception routed to wrong topic)
+
+**Key insight:** Same symptom ("--help doesn't work right"), two distinct root causes, two different fix loci. Never bundle by symptom; bundle by fix locus. Category A required dispatcher reordering (parse_local_help_action earlier). Category B required surface parser adjustments (remove prompt from early path, add action arms).
+
+### Closed Issues
+
+| # | Class | Command(s) | Root | Fix |
+|---|---|---|---|---|
+| #130c | B | diff | action parser rejected help | add parser arm + help topic |
+| #130d | B | config | command silently ignored help | add help flag check + route |
+| #130e-A | A | help, submit, resume | fell through to cred check | add to parse_local_help_action |
+| #130e-B | B | plugins, prompt | action mismatch + early interception | remove from early path, add arms |
+
+### Methodology That Worked
+
+1. **Dogfood on individual command** (cycle #47): Found #130b (unrelated).
+2. **Systematic sweep of all 22 commands** (cycle #50): Found #130c, #130d 2 outliers.
+3. **Implement both** (cycles #51-#52): Close Category B.
+4. **Extended sweep** (cycle #53): Probed same 22 again, found **5 new anomalies** (proof: ad-hoc testing misses patterns).
+5. **Classify and prioritize** (cycle #53-#54): Split into A (cred misdirection) + B (surface).
+6. **Implement A first** (cycle #53): Higher severity, same pattern infrastructure.
+7. **Implement B** (cycle #54): Lower severity, surface fixes.
+8. **Full sweep verification** (cycle #54): All 22 green. Zero outliers.
+
+### Evidence of Closure
+
+**Dogfood (22-command full sweep, cycle #54):**
+```
+✅ help --help         ✅ version --help       ✅ status --help
+✅ sandbox --help      ✅ doctor --help        ✅ acp --help
+✅ init --help         ✅ state --help         ✅ export --help
+✅ diff --help         ✅ config --help        ✅ mcp --help
+✅ agents --help       ✅ plugins --help       ✅ skills --help
+✅ submit --help       ✅ prompt --help        ✅ resume --help
+✅ system-prompt --help ✅ dump-manifests --help ✅ bootstrap-plan --help
+```
+
+**Regression tests:** 20+ assertions added across cycles #51-#54, all passing.
+
+**Test suite:** 180 binary + 466 library = 646 total, all pass post-closure.
+
+### Pattern Maturity
+
+After #130c-#130e, the help-topic pattern is now battle-tested:
+1. Add variant to `LocalHelpTopic` enum
+2. Extend `parse_local_help_action()` match arm
+3. Add help topic renderer
+4. Add regression test
+
+Time to implement a new topic: ~5 minutes (if parser arm already exists). This is infrastructure maturity.
+
+### What Changed in the Codebase
+
+| Area | Change | Cycle |
+|---|---|---|
+| main.rs LocalHelpTopic enum | +7 new variants (Diff, Config, Meta, Submit, Resume, Plugins, Prompt) | #51-#54 |
+| main.rs parse_local_help_action() | +7 match arms | #51-#54 |
+| main.rs help topic renderers | +7 topics (text-form) | #51-#54 |
+| main.rs early wants_help interception | removed "prompt" from list | #54 |
+| Regression tests | +20 assertions | #51-#54 |
+
+### Why This Cluster Matters
+
+Help surface is the canary for CLI reasoning. Downstream claws (other agents, scripts, shells) need to know: "Can I rely on `claw VERB --help` to tell me what VERB does without side effects?" Before this family: **No, 7 commands were outliers.** After this family: **Yes, all 22 are uniform.**
+
+This uniformity enables:
+- Script generation (claws can now safely emit `claw VERB --help` to populate docs)
+- Error recovery (callers can teach users "use `claw VERB --help`" universally)
+- Discoverability (help isn't blocked by credentials)
+
+### Related Patterns
+
+- **#251 (session dispatch-order bug):** Same class A pattern as #130e-A; early interception prevents credential check from blocking valid intent.
+- **#141 (help topic infrastructure):** Foundation that enabled rapid closure of #130c-#130e.
+- **#247 (typed-error completeness):** Sibling cluster on error contract; help surface is contract on the "success, show me how" path.
+
+### Commit Summary
+
+```
+#130c: 83f744a feat: claw diff --help routes to help topic
+#130d: 19638a0 feat: claw config --help routes to help topic
+#130e-A: 0ca0344 feat: claw help/submit/resume --help routes to help topics (dispatch-order fixes)
+#130e-B: 9dd7e79 feat: claw plugins/prompt --help routes to help topics (surface fixes)
+```
+
+### Recommended Action
+
+Mark #130c, #130d, #130e as **closed** in backlog. Remove from active cluster list. No follow-up work required — the family is complete and the pattern is proven for future subcommand additions.
+
+**Next frontier:** Await code review on 8 pending branches. If velocity demands, shift to:
+1. **MCP lifecycle / plugin friction** — user-facing surface observations
+2. **Typed-error extension** — apply #130b pattern (filesystem context) to other I/O call sites
+3. **Anomalyco/opencode parity gaps** — reference comparison for CLI design
+4. **Session resume friction** — dogfood the `#251` fix in real workflows
+
+---
+
+
+---
+
+## Cluster Closure Note: No-Arg Verb Suffix-Guard Family — COMPLETE
+
+**Timeline: Cycles #55-#56, ~11 minutes**
+
+### What the Family Solved
+
+Universal parser-level contract: **every no-arg diagnostic verb rejects trailing garbage arguments at parse time** instead of silently accepting them.
+
+### Framing (Gaebal-gajae, Cycle #56)
+
+Contract shapes were mixed across verbs. Separating them clarified what was a bug vs. a design choice:
+
+**Closed (14 verbs, all uniform):**
+help, version, status, sandbox, doctor, state, init, diff, plugins, skills, system-prompt, dump-manifests, bootstrap-plan, acp
+
+**Legitimate positional (not bugs):**
+- `export <file-path>` — file path is intended arg
+- `agents <subaction>` — takes subactions like list/help
+- `mcp <subaction>` — takes subactions like list/show/help
+
+### Deferred Design Questions (filed below as #155, #156)
+
+Two contract-shape questions surfaced during sweep. Not bugs, but worth recording so future cycles know they're open design choices, not oversights.
+
+---
+
+## Pinpoint #155. `claw config <section>` accepts any string as section name without validation — design question
+
+**Observation (cycle #56 sweep, 2026-04-23 02:22 Seoul):**
+
+```bash
+$ claw config garbage
+Config
+  Working directory /path/to/project
+  Loaded files      1
+  ...
+```
+
+The `garbage` is accepted as a section name. The output doesn't change whether you pass a valid section (`env`, `hooks`, `model`, `plugins`) or invalid garbage. Parser accepts any string as Section; runtime applies no filter or validation.
+
+**Design question:**
+- Option A — **Strict whitelist**: Reject unknown section names at parse time. Error: `unknown section 'garbage'. Valid sections: env, hooks, model, plugins`.
+- Option B — **Advisory validation**: Warn if section isn't recognized, but continue. `[warning] unknown section 'garbage'; showing full config`.
+- Option C — **Accept as filter hint**: Keep current behavior but make the output actually filter by section when section is specified. Today it shows the same thing regardless.
+
+**Why this is not a bug (yet):**
+- The section parameter is currently **not actually used by the runtime** — output is the same with or without section.
+- Adding validation requires deciding what sections mean first.
+
+**Priority:** Medium. Low implementation cost (small match) but needs design decision first.
+
+---
+
+## Pinpoint #156. `claw mcp` / `claw agents` use soft-warning contract instead of hard error for unknown args — design question
+
+**Observation (cycle #56 sweep):**
+
+```bash
+$ claw mcp garbage
+MCP
+  Usage            /mcp [list|show <server>|help]
+  Direct CLI       claw mcp [list|show <server>|help]
+  Sources          .claw/settings.json, .claw/settings.local.json
+  Unexpected       garbage
+```
+
+Both `mcp` and `agents` show help + "Unexpected: <arg>" warning line, but still exit 0 and display help. Contrast with `plugins --help`, which emits hard error on unknown actions.
+
+**Design question:**
+- Option A — **Normalize to hard-error**: All subaction-taking verbs (`mcp`, `agents`, `plugins`) should reject unknown subactions consistently (like `plugins` does now).
+- Option B — **Normalize to soft-warning**: Standardize on "show help + exit 0" with Unexpected warning; apply to `plugins` too.
+- Option C — **Keep as-is**: `mcp`/`agents` treat help as default/fallback; `plugins` treats help as explicit action.
+
+**Why this is not an obvious bug:**
+- The soft-warning contract IS useful for discovery — new user typos don't block exploration.
+- But it's inconsistent with `plugins` which hard-errors.
+
+**Priority:** Low-Medium. Depends on whether downstream claws parse exit codes or output. Soft-warning plays badly with scripted callers.
+
+---
+
+### Pattern Reference (for future suffix-guard work)
+
+The proven pattern for no-arg verbs:
+
+```rust
+"<verb>" => {
+    if rest.len() > 1 {
+        return Err(format!(
+            "unrecognized argument `{}` for subcommand `<verb>`",
+            rest[1]
+        ));
+    }
+    Ok(CliAction::<Verb> { output_format })
+}
+```
+
+Time to apply: ~3 minutes per verb. Infrastructure is mature.
+
+### Commit Summary
+
+```
+#55: 860f285 fix(#152-follow-up): claw init rejects trailing arguments
+#56: 3a533ce fix(#152-follow-up-2): claw bootstrap-plan rejects trailing arguments
+```
+
+### Recommended Action
+
+- Mark #152 as closed in backlog (all resolvable no-arg cases resolved).
+- Track #155 and #156 as active design questions, not bugs.
+- No further auto-sweep work needed on suffix-guard family.
+
+---
+

SCHEMAS.md

@@ -107,6 +107,24 @@ When an entity does not exist (exit code 1, but not a failure):
 
 ### `list-sessions`
 
+**Status**: ✅ Implemented (closed #251 cycle #45, 2026-04-23).
+
+**Actual binary envelope** (as of #251 fix):
+```json
+{
+  "command": "list-sessions",
+  "sessions": [
+    {
+      "id": "session-1775777421902-1",
+      "path": "/path/to/.claw/sessions/session-1775777421902-1.jsonl",
+      "updated_at_ms": 1775777421902,
+      "message_count": 0
+    }
+  ]
+}
+```
+
+**Aspirational (future) shape**:
 ```json
 {
   "timestamp": "2026-04-22T10:10:00Z",
@@ -128,8 +146,25 @@ When an entity does not exist (exit code 1, but not a failure):
 }
 ```
 
+**Gap**: Current impl lacks `timestamp`, `exit_code`, `output_format`, `schema_version`, `directory`, `sessions_count` (derivable), and the session object uses `id`/`updated_at_ms`/`message_count` instead of `session_id`/`last_modified`/`prompt_count`. Follow-up #250 Option B to align field names and add common-envelope fields.
+
 ### `delete-session`
 
+**Status**: ⚠️ Stub only (closed #251 dispatch-order fix; full impl deferred).
+
+**Actual binary envelope** (as of #251 fix):
+```json
+{
+  "type": "error",
+  "command": "delete-session",
+  "error": "not_yet_implemented",
+  "kind": "not_yet_implemented"
+}
+```
+
+Exit code: 1. No credentials required. The stub ensures the verb does NOT fall through to Prompt/auth (the #251 fix), but the actual delete operation is not yet wired.
+
+**Aspirational (future) shape**:
 ```json
 {
   "timestamp": "2026-04-22T10:10:00Z",
@@ -143,6 +178,31 @@ When an entity does not exist (exit code 1, but not a failure):
 
 ### `load-session`
 
+**Status**: ✅ Implemented (closed #251 cycle #45, 2026-04-23).
+
+**Actual binary envelope** (as of #251 fix):
+```json
+{
+  "command": "load-session",
+  "session": {
+    "id": "session-abc123",
+    "path": "/path/to/.claw/sessions/session-abc123.jsonl",
+    "messages": 5
+  }
+}
+```
+
+For nonexistent sessions, emits a local `session_not_found` error (NOT `missing_credentials`):
+```json
+{
+  "error": "session not found: nonexistent",
+  "kind": "session_not_found",
+  "type": "error",
+  "hint": "Hint: managed sessions live in .claw/sessions/<hash>/ ..."
+}
+```
+
+**Aspirational (future) shape**:
 ```json
 {
   "timestamp": "2026-04-22T10:10:00Z",
@@ -155,8 +215,25 @@ When an entity does not exist (exit code 1, but not a failure):
 }
 ```
 
+**Gap**: Current impl uses nested `session: {...}` instead of flat fields, and omits common-envelope fields. Follow-up #250 Option B to align.
+
 ### `flush-transcript`
 
+**Status**: ⚠️ Stub only (closed #251 dispatch-order fix; full impl deferred).
+
+**Actual binary envelope** (as of #251 fix):
+```json
+{
+  "type": "error",
+  "command": "flush-transcript",
+  "error": "not_yet_implemented",
+  "kind": "not_yet_implemented"
+}
+```
+
+Exit code: 1. No credentials required. Like `delete-session`, this stub resolves the #251 dispatch-order bug but the actual flush operation is not yet wired.
+
+**Aspirational (future) shape**:
 ```json
 {
   "timestamp": "2026-04-22T10:10:00Z",

rust/crates/rusty-claude-cli/src/main.rs

@@ -417,7 +417,10 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
             cli.set_reasoning_effort(reasoning_effort);
             cli.run_turn_with_output(&effective_prompt, output_format, compact)?;
         }
-        CliAction::Doctor { output_format } => run_doctor(output_format)?,
+        CliAction::Doctor { output_format } => {
+            run_stale_base_preflight(None);
+            run_doctor(output_format)?
+        }
         CliAction::Acp { output_format } => print_acp_status(output_format)?,
         CliAction::State { output_format } => run_worker_state(output_format)?,
         CliAction::Init { output_format } => run_init(output_format)?,
@@ -452,113 +455,6 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
                 );
             }
         },
-        // #251: session-management verbs (list-sessions, load-session,
-        // delete-session, flush-transcript) are pure-local operations.
-        // They are intercepted at the parser level and dispatched directly
-        // to session-control operations without requiring credentials.
-        CliAction::ListSessions { output_format } => {
-            use runtime::session_control::list_managed_sessions_for;
-            let base_dir = env::current_dir()?;
-            let sessions = list_managed_sessions_for(base_dir)?;
-            match output_format {
-                CliOutputFormat::Text => {
-                    if sessions.is_empty() {
-                        println!("No sessions found.");
-                    } else {
-                        for session in sessions {
-                            println!("{} ({})", session.id, session.path.display());
-                        }
-                    }
-                }
-                CliOutputFormat::Json => {
-                    // #251: ManagedSessionSummary doesn't impl Serialize;
-                    // construct JSON manually with the public fields.
-                    let sessions_json: Vec<serde_json::Value> = sessions
-                        .iter()
-                        .map(|s| {
-                            serde_json::json!({
-                                "id": s.id,
-                                "path": s.path.display().to_string(),
-                                "updated_at_ms": s.updated_at_ms,
-                                "message_count": s.message_count,
-                            })
-                        })
-                        .collect();
-                    let result = serde_json::json!({
-                        "command": "list-sessions",
-                        "sessions": sessions_json,
-                    });
-                    println!("{}", serde_json::to_string_pretty(&result)?);
-                }
-            }
-        }
-        CliAction::LoadSession {
-            session_reference,
-            output_format,
-        } => {
-            use runtime::session_control::load_managed_session_for;
-            let base_dir = env::current_dir()?;
-            let loaded = load_managed_session_for(base_dir, &session_reference)?;
-            match output_format {
-                CliOutputFormat::Text => {
-                    println!(
-                        "Session {} loaded\n  File       {}\n  Messages   {}",
-                        loaded.session.session_id,
-                        loaded.handle.path.display(),
-                        loaded.session.messages.len()
-                    );
-                }
-                CliOutputFormat::Json => {
-                    let result = serde_json::json!({
-                        "command": "load-session",
-                        "session": {
-                            "id": loaded.session.session_id,
-                            "path": loaded.handle.path.display().to_string(),
-                            "messages": loaded.session.messages.len(),
-                        },
-                    });
-                    println!("{}", serde_json::to_string_pretty(&result)?);
-                }
-            }
-        }
-        CliAction::DeleteSession {
-            session_id: _,
-            output_format,
-        } => {
-            // #251: delete-session implementation deferred
-            eprintln!("delete-session is not yet implemented.");
-            if matches!(output_format, CliOutputFormat::Json) {
-                eprintln!(
-                    "{}",
-                    serde_json::json!({
-                        "type": "error",
-                        "error": "not_yet_implemented",
-                        "command": "delete-session",
-                        "kind": "not_yet_implemented",
-                    })
-                );
-            }
-            std::process::exit(1);
-        }
-        CliAction::FlushTranscript {
-            session_id: _,
-            output_format,
-        } => {
-            // #251: flush-transcript implementation deferred
-            eprintln!("flush-transcript is not yet implemented.");
-            if matches!(output_format, CliOutputFormat::Json) {
-                eprintln!(
-                    "{}",
-                    serde_json::json!({
-                        "type": "error",
-                        "error": "not_yet_implemented",
-                        "command": "flush-transcript",
-                        "kind": "not_yet_implemented",
-                    })
-                );
-            }
-            std::process::exit(1);
-        }
         CliAction::Export {
             session_reference,
             output_path,
@@ -686,26 +582,6 @@ enum CliAction {
     Help {
         output_format: CliOutputFormat,
     },
-    // #251: session-management verbs are pure-local reads/mutations on the
-    // session store. They do not require credentials or a model connection.
-    // Previously these fell through to the `_other => Prompt` catchall and
-    // emitted `missing_credentials` errors. Now they are intercepted at the
-    // top-level parser and dispatched to session-control operations.
-    ListSessions {
-        output_format: CliOutputFormat,
-    },
-    LoadSession {
-        session_reference: String,
-        output_format: CliOutputFormat,
-    },
-    DeleteSession {
-        session_id: String,
-        output_format: CliOutputFormat,
-    },
-    FlushTranscript {
-        session_id: String,
-        output_format: CliOutputFormat,
-    },
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -1061,81 +937,6 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             }
             Ok(CliAction::Diff { output_format })
         }
-        // #251: session-management verbs are pure-local operations on the
-        // session store. They require no credentials or model connection.
-        // Previously they fell through to `_other => Prompt` and emitted
-        // `missing_credentials`. Now they are intercepted at parse time and
-        // routed to session-control operations.
-        "list-sessions" => {
-            let tail = &rest[1..];
-            // list-sessions takes no positional arguments; flags are already parsed
-            if !tail.is_empty() {
-                return Err(format!(
-                    "unexpected extra arguments after `claw list-sessions`: {}",
-                    tail.join(" ")
-                ));
-            }
-            Ok(CliAction::ListSessions { output_format })
-        }
-        "load-session" => {
-            let tail = &rest[1..];
-            // load-session requires a session-id (positional) argument
-            let session_ref = tail.first().ok_or_else(|| {
-                "load-session requires a session-id argument (e.g., `claw load-session SESSION.jsonl`)"
-                    .to_string()
-            })?.clone();
-            if tail.len() > 1 {
-                return Err(format!(
-                    "unexpected extra arguments after `claw load-session {session_ref}`: {}",
-                    tail[1..].join(" ")
-                ));
-            }
-            Ok(CliAction::LoadSession {
-                session_reference: session_ref,
-                output_format,
-            })
-        }
-        "delete-session" => {
-            let tail = &rest[1..];
-            // delete-session requires a session-id (positional) argument
-            let session_id = tail.first().ok_or_else(|| {
-                "delete-session requires a session-id argument (e.g., `claw delete-session SESSION_ID`)"
-                    .to_string()
-            })?.clone();
-            if tail.len() > 1 {
-                return Err(format!(
-                    "unexpected extra arguments after `claw delete-session {session_id}`: {}",
-                    tail[1..].join(" ")
-                ));
-            }
-            Ok(CliAction::DeleteSession {
-                session_id,
-                output_format,
-            })
-        }
-        "flush-transcript" => {
-            let tail = &rest[1..];
-            // flush-transcript: optional --session-id flag (parsed above) or as positional
-            let session_id = if tail.is_empty() {
-                // --session-id flag must have been provided
-                return Err(
-                    "flush-transcript requires either --session-id flag or positional argument"
-                        .to_string(),
-                );
-            } else {
-                tail[0].clone()
-            };
-            if tail.len() > 1 {
-                return Err(format!(
-                    "unexpected extra arguments after `claw flush-transcript {session_id}`: {}",
-                    tail[1..].join(" ")
-                ));
-            }
-            Ok(CliAction::FlushTranscript {
-                session_id,
-                output_format,
-            })
-        }
         "skills" => {
             let args = join_optional_args(&rest[1..]);
             match classify_skills_slash_command(args.as_deref()) {
@@ -10219,89 +10020,6 @@ mod tests {
                 output_format: CliOutputFormat::Json,
             }
         );
-        // #251: session-management verbs (list-sessions, load-session,
-        // delete-session, flush-transcript) must be intercepted at top-level
-        // parse and returned as CliAction variants. Previously they fell
-        // through to `_other => Prompt` and emitted `missing_credentials`
-        // for purely-local operations.
-        assert_eq!(
-            parse_args(&["list-sessions".to_string()])
-                .expect("list-sessions should parse"),
-            CliAction::ListSessions {
-                output_format: CliOutputFormat::Text,
-            },
-            "list-sessions must dispatch to ListSessions, not fall through to Prompt"
-        );
-        assert_eq!(
-            parse_args(&[
-                "list-sessions".to_string(),
-                "--output-format".to_string(),
-                "json".to_string(),
-            ])
-            .expect("list-sessions --output-format json should parse"),
-            CliAction::ListSessions {
-                output_format: CliOutputFormat::Json,
-            }
-        );
-        assert_eq!(
-            parse_args(&[
-                "load-session".to_string(),
-                "my-session-id".to_string(),
-            ])
-            .expect("load-session <id> should parse"),
-            CliAction::LoadSession {
-                session_reference: "my-session-id".to_string(),
-                output_format: CliOutputFormat::Text,
-            },
-            "load-session must dispatch to LoadSession, not fall through to Prompt"
-        );
-        assert_eq!(
-            parse_args(&[
-                "delete-session".to_string(),
-                "my-session-id".to_string(),
-            ])
-            .expect("delete-session <id> should parse"),
-            CliAction::DeleteSession {
-                session_id: "my-session-id".to_string(),
-                output_format: CliOutputFormat::Text,
-            },
-            "delete-session must dispatch to DeleteSession, not fall through to Prompt"
-        );
-        assert_eq!(
-            parse_args(&[
-                "flush-transcript".to_string(),
-                "my-session-id".to_string(),
-            ])
-            .expect("flush-transcript <id> should parse"),
-            CliAction::FlushTranscript {
-                session_id: "my-session-id".to_string(),
-                output_format: CliOutputFormat::Text,
-            },
-            "flush-transcript must dispatch to FlushTranscript, not fall through to Prompt"
-        );
-        // #251: required positional arguments for session verbs
-        let load_err = parse_args(&["load-session".to_string()])
-            .expect_err("load-session without id should be rejected");
-        assert!(
-            load_err.contains("load-session requires a session-id"),
-            "missing session-id error should be specific, got: {load_err}"
-        );
-        let delete_err = parse_args(&["delete-session".to_string()])
-            .expect_err("delete-session without id should be rejected");
-        assert!(
-            delete_err.contains("delete-session requires a session-id"),
-            "missing session-id error should be specific, got: {delete_err}"
-        );
-        // #251: extra arguments must be rejected
-        let extra_err = parse_args(&[
-            "list-sessions".to_string(),
-            "unexpected".to_string(),
-        ])
-        .expect_err("list-sessions with extra args should be rejected");
-        assert!(
-            extra_err.contains("unexpected extra arguments"),
-            "extra-args error should be specific, got: {extra_err}"
-        );
         // #147: empty / whitespace-only positional args must be rejected
         // with a specific error instead of falling through to the prompt
         // path (where they surface a misleading "missing Anthropic