test(#762): classify_error_kind now covers all 23 classifier arms (was 8 of 23)

ROADMAP.md

@@ -7617,3 +7617,77 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 724. **DONE — ROADMAP duplicate-id validation guard for helper-era append collisions** — follow-up to #723 after dogfood showed `scripts/roadmap-next-id.sh` still printed 724 and exited 0 when a temp ROADMAP copy already contained a second `723. ...` line. This PR closes the gap for new optimistic-append collisions by adding `scripts/roadmap-check-ids.sh`, wiring it into docs CI and the local pre-push hook, documenting the pre-push command in CONTRIBUTING, and mentioning the guard from `roadmap-next-id.sh`. The guard defaults to ids >=723 so current historical roadmap content and old numbered lists do not block docs-only PRs; `--min-id 1` is available for a strict whole-file audit once legacy collisions are cleaned up. **Verification:** `scripts/roadmap-check-ids.sh` passes on current ROADMAP; a temp copy with an appended duplicate `723.` fails nonzero and lists duplicate id 723 with line numbers. Source: Jobdori dogfood follow-up on origin/main `922c2398`, 2026-05-25. [SCOPE: docs/scripts]
 
 725. **DONE — roadmap-next-id helper now fails closed on helper-era duplicate ids before printing a next id** — follow-up to #724 after dogfood on origin/main 25ee5f3d showed `scripts/roadmap-next-id.sh` could print `1000` and exit 0 when a temp ROADMAP copy already contained two `999.` helper-era entries. This PR makes `roadmap-next-id.sh` resolve `roadmap-check-ids.sh` by its own script directory, run the checker with default helper-era min-id semantics before computing `highest+1`, keep stdout reserved for the single next id on success, and fail closed with a useful error if the checker is unavailable. Added focused pytest coverage for clean next-id output, duplicate fail-fast behavior, and missing-checker fail-closed behavior. **Verification:** `scripts/roadmap-next-id.sh ROADMAP.md` prints `725`; `scripts/roadmap-check-ids.sh ROADMAP.md` passes; a temp ROADMAP with duplicate `999.` exits nonzero and lists duplicate id 999 without printing a next id; `bash -n scripts/roadmap-next-id.sh scripts/roadmap-check-ids.sh` passes; `python -m pytest tests/test_roadmap_helpers.py -q` passes. Source: Jobdori dogfood follow-up on origin/main 25ee5f3d. [SCOPE: docs/scripts]
+
+726. **`claw export` from a workspace with a cross-workspace legacy session emits `kind:"unknown", error_kind:"unknown"` instead of a typed error — `legacy session is missing workspace binding` error propagates through the generic error handler unclassified** — dogfooded 2026-05-26 on `d8a61090`. Reproduction: `claw export --output-format json` from a fresh `git init` workspace where the most-recent managed session was created in a different workspace root returns `{kind:"unknown", action:"abort", status:"error", error_kind:"unknown"}`. The error originates in `SessionControlError::Format(format_legacy_session_missing_workspace_root(...))` in `session_control.rs:313`; `classify_error_kind` had no branch for "legacy session is missing workspace binding" and fell through to "unknown". Fix: added `legacy_session_no_workspace_binding` branch to `classify_error_kind`. Remaining gap: `kind` still shows the error_kind value instead of `"export"` — root cause is the generic error path setting `kind = error_kind` rather than the subcommand name; this is the `#422` class and requires a separate structural fix. Source: Jobdori dogfood on `d8a61090`, 2026-05-26.
+
+727. **`branch_freshness.fresh: null` with `upstream: null` is ambiguous — automation checking `if .workspace.branch_freshness.fresh == true` treats "no upstream configured" identically to "behind by N commits", both returning falsy null** — dogfooded 2026-05-26 on `a0c6c8ba`. Reproduction: `claw status --output-format json` from a freshly `git init`'d repo with no remote returns `{upstream: null, fresh: null, ahead: 0, behind: 0}`. An automation script that gates on `.branch_freshness.fresh == true` before proceeding sees `null == true → false` and blocks — identical to the behind-by-N case. The JSON has no discriminator between "freshness unknown because no upstream" and "freshness unknown because git unavailable". Fix: added `has_upstream: bool` to `BranchFreshness.json_value()` — automation should check `has_upstream` before branching on `fresh`. Source: Jobdori dogfood on `a0c6c8ba`, 2026-05-26.
+
+728. **`claw agents list` and `agents show` JSON responses had no `path` field — callers could not determine which on-disk `.toml` file backs each agent without re-walking the same discovery directories** — dogfooded 2026-05-26 on `9757fef8`. `claw agents list --output-format json` returned `{name, description, model, source: {id, label, detail_label: null}}` with no disk path. `AgentSummary` had no `path` field; the `entry.path()` from the `fs::read_dir` loop was discarded after frontmatter parsing. Fix: added `path: Option<PathBuf>` to `AgentSummary`; populated from `entry.path()` in the discovery loop; exposed as `"path": string|null` in `agent_summary_json`. Agents now return e.g. `{path:"/Users/.../.codex/agents/codex-ultrawork-reviewer.toml"}`. Parity gap: `skills list` still lacks `path` — tracked as a follow-on (same fix needed in `SkillSummary`). Source: Jobdori dogfood on `9757fef8`, 2026-05-26.
+
+729. **`claw skills list/show --output-format json` had no `path` field — parity gap with `agents list` (#728): callers could not determine which on-disk directory backs each skill without re-walking discovery roots** — dogfooded 2026-05-26 on `fa29909f`. `SkillSummary` had no `path` field; both `SkillOrigin::SkillsDir` (returns `entry.path()`) and `SkillOrigin::LegacyCommandsDir` (returns `markdown_path`) push sites discarded the resolved path after parsing. Fix: added `path: Option<PathBuf>` to `SkillSummary`; `SkillsDir` branch populates `Some(entry.path())`, `LegacyCommandsDir` branch populates `Some(markdown_path)`; `skill_summary_json` exposes `"path": string|null`. Skills now return e.g. `{path:"/Users/.../.agents/skills/agent-browser"}`. Completes the path-discoverability trio started in #728 (agents) — plugins path is a remaining follow-on. Source: Jobdori dogfood on `fa29909f`, 2026-05-26.
+
+730. **`claw plugins list/show --output-format json` had no `path` field — parity gap completing the agents (#728) / skills (#729) trio: callers could not determine which on-disk directory backs each plugin without re-walking discovery roots** — dogfooded 2026-05-26 on `8f44ad30`. `plugin_summary_json` in `rusty-claude-cli/src/main.rs` rendered all `PluginMetadata` fields except `root: Option<PathBuf>`, which was already present in the struct. Fix: added `"path": plugin.metadata.root.as_ref().map(|p| p.display().to_string())` to `plugin_summary_json`. Plugins now return e.g. `{path:"/Users/.../.claw/plugins/installed/example-bundled-bundled"}`. Completes path-discoverability across all three extension surfaces (agents, skills, plugins). Source: Jobdori dogfood on `8f44ad30`, 2026-05-26.
+
+731. **`claw sandbox --output-format json` returned `status:"error"` when namespace isolation is unsupported on macOS but filesystem sandbox is active — automation treating `status != "ok"` as a hard error would block on a fully-functional degraded sandbox** — dogfooded 2026-05-26 on `425d94ee`. `sandbox_json_value` derived `status:"error"` when `!status.supported` regardless of whether `filesystem_active:true` (workspace-write containment working). On macOS the typical state is `{supported:false, filesystem_active:true, active_namespace:false}` — namespace isolation is unsupported but the filesystem sandbox IS active. This is degradation, not failure. Fix: added `else if status.filesystem_active { "warn" }` branch before the hard `"error"` arm — `status:"error"` is now reserved for the case where sandbox is enabled, unsupported, AND no filesystem containment is active either. macOS default now correctly returns `status:"warn"`. Source: Jobdori dogfood on `425d94ee`, 2026-05-26.
+
+732. **`claw status --output-format json` `allowed_tools.entries` was `null` when no `--allowed-tools` flag was passed — callers doing `.allowed_tools.entries | length > 0` or trying to iterate got a null-dereference instead of an empty array** — dogfooded 2026-05-26 on `29dcd478`. `allowed_tool_entries` was computed as `allowed_tools.map(|tools| tools.iter().cloned().collect())` — `None` when unrestricted, serialized to JSON `null`. Fix: `.unwrap_or_default()` so unrestricted invocations emit `entries: []` instead of `entries: null`. Callers can now use `.entries | length > 0` uniformly without a null guard. Source: Jobdori dogfood on `29dcd478`, 2026-05-26.
+
+733. **`claw diff --output-format json` returned no `changed_file_count` field — callers seeing `result:"changes"` had to parse the raw `staged`/`unstaged` diff text to count affected files** — dogfooded 2026-05-26 on `4c16a42f`. `render_diff_json_for` ran `git diff --cached` and `git diff` and exposed them as raw strings but didn't compute a file count. Fix: run two additional `git diff --name-only` passes (staged + unstaged), deduplicate across both sets using a `BTreeSet`, and expose `changed_file_count: usize` in the envelope. Clean repos emit `changed_file_count: 0`, dirty repos emit the true unique-file count. Source: Jobdori dogfood on `4c16a42f`, 2026-05-26.
+
+734. **`agents show <name>` and `plugins show <name>` error envelopes had no `message` field when the target was not found — `skills show` had `"message": "skill 'X' not found"` but the other two omitted it, leaving callers with only `error_kind` and `requested` and no human-readable explanation in the same field shape** — dogfooded 2026-05-26 on `cc86f54d`. Added `"message": "agent 'X' not found"` to the `agent_not_found` branch in `commands/src/lib.rs` and `"message": "plugin 'X' not found"` to the `plugin_not_found` branch in `rusty-claude-cli/src/main.rs`; both now match the `skills show` shape. Source: Jobdori dogfood on `cc86f54d`, 2026-05-26.
+
+735. **`claw /compact --output-format json` (and other interactive-only slash commands invoked outside a session) emitted `error_kind:"unknown"` instead of `error_kind:"interactive_only"` — `classify_error_kind` matched `"is a slash command"` and `"interactive_only:"` prefix but missed the `"slash command /X is interactive-only"` sentence pattern emitted by the interactive-only guard; automation branching on `error_kind` got `"unknown"` and couldn't distinguish "you called an interactive command outside a session" from a genuine unknown failure** — dogfooded 2026-05-26 on `d4494a8a`. Added `message.starts_with("slash command") && message.contains("interactive-only")` branch to `classify_error_kind` alongside the existing two matchers. Source: Jobdori dogfood on `d4494a8a`, 2026-05-26.
+
+736. **`claw doctor --output-format json` `boot_preflight` check `details[]` had `value: null` for `Required binary`, `Last failed boot`, `MCP eligible`, and `Plugin eligible` entries — all four used format strings with no double-space separator, so the prose-splitter that builds `{key, value}` objects (introduced in #701) could not split key from value and emitted the entire string as `key` with `value: null`** — dogfooded 2026-05-26 on `b3242e8c`. Fix: insert the two-space separator between the label and its value in each format string: `"Required binary {}  available={}"` → `key="Required binary claw"` / `value="available=true"`; `"Last failed boot  {}"` → `key="Last failed boot"` / `value="<none>"`; MCP/Plugin eligible compound values use `"  ·  "` intra-value separator since `splitn(2, "  ")` splits only on the first double-space run. Source: Jobdori dogfood on `b3242e8c`, 2026-05-26.
+
+737. **Test coverage gap: `doctor --output-format json` `boot_preflight` `details[]` had no assertion that entries are `{key,value}` objects with non-null `value` fields — the #736 double-space separator fix had no regression guard, so a revert or accidental prose-format change would silently re-introduce `value:null` entries** — filed 2026-05-26 on `ad982d20`. Added assertions to `doctor_and_resume_status_emit_json_when_requested` in `output_format_contract.rs`: iterate all `boot_preflight.details[]` entries and assert each has a string `key` and a non-null `value`. Source: Jobdori dogfood on `ad982d20`, 2026-05-26.
+
+738. **`claw /commit --output-format json` (and all other interactive-only slash commands invoked outside a session) emitted `hint: null` — the remediation text was in the `error` prose string but no newline separated the short error from the hint, so `split_error_hint` returned the entire message as `error` and `hint: null`** — dogfooded 2026-05-26 on `c592313d`. The format string `"slash command {cmd} is interactive-only. Start `claw`..."` had no newline, so `split_error_hint` (which splits on `\n`) could not extract the hint. Fix: add `\n` between the short error `"slash command X is interactive-only."` and the remediation text, so callers reading `.hint` get the actionable guidance directly. Source: Jobdori dogfood on `c592313d`, 2026-05-26.
+
+739. **`claw skills <unknown-subcommand> --output-format json` emitted two JSON objects on stdout: first the usage envelope (`action:"help", unexpected:"X"`), then a second error abort envelope (`kind:"unknown", error:"skills command failed"`) — the `print_skills` JSON path returned `Err` on `status:"error"` responses even when the response was a normal usage-display (`action:"help"`), causing the generic error serializer to emit the second envelope** — dogfooded 2026-05-26 on `4c3cb0f3`. Fix: skip the `return Err` path when `action == "help"`; usage envelopes are informational, not fatal errors. The root prompt-dispatch gap (`claw skills bogus` → `CliAction::Prompt` → `missing_credentials` in no-creds env) is a pre-existing auth-gate-on-local-surface issue (ROADMAP #431/#449) and not addressed here. Source: Jobdori dogfood on `4c3cb0f3`, 2026-05-26.
+
+740. **Test coverage gap for ROADMAP #733: `diff_json_has_status_and_result_field_702` did not assert `changed_file_count` contract** — dogfooded 2026-05-26 on `d5f0d6ed`. The test asserts `kind`, `status`, `result`, `action`, `working_directory` but not the new `changed_file_count` field added by #733. Coverage gap: (a) no assertion that the field exists, (b) no assertion of numeric type in git repos, (c) no regression guard for dedupe behavior (staged+unstaged to the same file = 1 changed file). Fix: extend the test to assert `changed_file_count: null` in non-git repos and `changed_file_count: u64` in git repos. Source: gaebal-gajae dogfood on `d5f0d6ed`, 2026-05-26.
+
+741. **`claw config list`, `claw config show`, `claw config bogus` --output-format json returned `hint: null` — the unsupported_config_section error envelope had no `hint` field populated, so callers reading `.hint` get null with no actionable guidance** — dogfooded 2026-05-26 on `5d072d21`. The `render_config_json` unsupported-section branch returned a JSON object with `error` (contains the section list) but no `hint` field. Notably `config list` and `config show` are natural verb patterns that users type expecting a list/show subcommand, but claw config uses `claw config` (no args) for list and `claw config <section>` for show — the error gave no indication of this. Fix: add `hint` field to unsupported_config_section error; verbs (`list`, `show`, `help`, `info`) get a hint explaining the correct idiom (`claw config` / `claw config <section>`); other unknown sections get a "not a config section" hint listing valid values. Source: Jobdori dogfood on `5d072d21`, 2026-05-26.
+
+742. **ROADMAP #740 test coverage gap: the new `changed_file_count` branch for git repos was unreachable — the fixture is a plain `unique_temp_dir` (no `git init`), so the test always exercises the `no_git_repo` path and never proves the numeric contract or deduplication behavior** — confirmed by gaebal-gajae on `5d072d21`, fixed on `6e78c1fc`. Fix: add `diff_json_changed_file_count_deduplication_733` test that (a) `git init`s a temp repo, (b) commits a file, (c) asserts `result:"clean"` + `changed_file_count:0`, (d) stages an edit + makes an unstaged edit to the same file, (e) asserts `result:"changes"` + `changed_file_count:1` — proving the BTreeSet deduplication actually works. Source: gaebal-gajae dogfood on `5d072d21`, 2026-05-26.
+
+743. **`claw plugins help --output-format json` returned `error_kind:"unknown_plugins_action"` with `hint:null` instead of the usage envelope (`action:"help", status:"ok", unexpected:null, usage:{...}`) that `agents help`, `mcp help`, and `skills help` all emit — schema drift within the same command family (ROADMAP #420)** — dogfooded 2026-05-26 on `2036f0bd`. Fix: (a) added `Some("help" | "-h" | "--help")` arm to `handle_plugins_slash_command` returning a text usage message (text path parity); (b) added early-return JSON help envelope in `print_plugins` JSON path matching shape of agents/mcp help: `{action:"help", kind:"plugin", status:"ok", unexpected:null, usage:{direct_cli, slash_command}}`. Source: Jobdori dogfood on `2036f0bd`, 2026-05-26.
+
+744. **ROADMAP #741 has no regression test: `claw config list/show/bogus --output-format json hint` field could silently regress to null** — confirmed by gaebal-gajae on `2036f0bd`. Pattern same as #736→#737 and #740→#742: implementation fix without a pinning test. Fix: add `config_unsupported_section_json_hint_741` test iterating `[list, show, bogus, help]` and asserting `kind:config`, `status:error`, `error_kind:unsupported_config_section`, `hint` is non-empty string, `supported_sections[]` is non-empty. Source: gaebal-gajae dogfood on `2036f0bd`, 2026-05-26.
+
+745. **`claw issue --output-format json` and all other direct-CLI slash commands (pr, commit, etc.) returned `hint: null` — the `bare_slash_command_guidance` message strings had no `\n` separator between short error and remediation text, so `split_error_hint` couldn't populate the hint field** — dogfooded 2026-05-26 on `92e053a1`. The #738 fix added `\n` to the `--resume SESSION /cmd` path but missed the direct-CLI path (e.g. `claw issue`, `claw pr`). The `bare_slash_command_guidance` function formats two message variants: resume-supported and non-resume; both lacked `\n`. Fix: add `\n` before the remediation text in both format strings. Source: Jobdori dogfood on `92e053a1`, 2026-05-26.
+
+746. **`claw --output-format json` (bare, no TTY, no prompt) returned `hint: null` — the non-TTY interactive-only guard error string had no `\n` separator, so `split_error_hint` couldn't extract the remediation text into `.hint`** — dogfooded 2026-05-26 on `3c5459a3`. The single-string message `"interactive_only: claw requires an interactive terminal (stdin is not a TTY and no prompt was provided \u2014 pipe a prompt or run in a TTY)"` contained the hint inline but no newline, so callers reading `.hint` got null and had to parse the prose `error` string. Fix: split at `\n` — short error `"interactive_only: claw requires an interactive terminal."` + hint `"Stdin is not a TTY…pipe a prompt with \`echo 'task' | claw\` or run \`claw\` in an interactive terminal."`. Source: Jobdori dogfood on `3c5459a3`, 2026-05-26.
+
+747. **ROADMAP #745 has no regression test: `claw issue/pr/commit --output-format json hint` could silently regress to null** — confirmed by gaebal-gajae on `3c5459a33`. Same pattern as #737, #742, #744. Fix: add `bare_slash_command_hint_745` test iterating `issue`, `pr`, `commit` and asserting `error_kind:"interactive_only"` + non-empty `hint` field. Source: gaebal-gajae dogfood on `3c5459a33`, fixed on `18e7744e`, 2026-05-26.
+
+748. **`claw mcp bogussubcmd --output-format json` returned `error_kind: null` when an unknown subcommand was passed — `render_mcp_usage_json(Some("bogus"))` set `status:"error"` but left `error_kind` absent — while `agents bogussubcmd` emits `error_kind:"unknown_agents_subcommand"`** — dogfooded 2026-05-26 on `04eb661e`. Fix: add `error_kind: "unknown_mcp_action"` to `render_mcp_usage_json` when `unexpected.is_some()`; remains `null` for the `help` path (`unexpected: null`). Source: Jobdori dogfood on `04eb661e`, 2026-05-26.
+
+749. **`claw compact --output-format json` returned `hint: null` — `compact_interactive_only_error()` returned a single-line string with no `\n` between short error and remediation text, so `split_error_hint` couldn't populate the hint field** — identified by gaebal-gajae on `04eb661e`. Same class as #738 / #745 / #746. Fix: add `\n` before the remediation text in `compact_interactive_only_error`. Regression guard: extended `compact_subcommand_json_help_fails_fast_when_stdin_closed` to also assert `hint` is non-empty and mentions `/compact` or `--resume`. Source: gaebal-gajae dogfood on `04eb661e`, 2026-05-26.
+
+750. **`claw prompt --output-format json` (no text argument) returned `error_kind:"unknown"` and `hint: null`** — dogfooded 2026-05-26 on `2dfb7af6`. The error string `"prompt subcommand requires a prompt string"` had no prefix prefix for classifier and no `\n` for hint extraction. Fix: (a) prefix with `"missing_prompt: "` + newline before usage hint; (b) add `message.starts_with("missing_prompt:")` → `"missing_prompt"` classifier arm. Result: `error_kind:"missing_prompt"`, `hint:"Usage: claw prompt <text>  or  echo '<text>' | claw"`. Source: Jobdori dogfood on `2dfb7af6`, 2026-05-26.
+
+751. **ROADMAP #750 has no regression test: `claw prompt --output-format json` no-arg `error_kind` and `hint` could silently regress** — confirmed by gaebal-gajae on `ac925ed4`. Fix: add `prompt_no_arg_json_error_kind_750` test asserting nonzero exit, `error_kind:"missing_prompt"`, non-empty `hint` mentioning `claw prompt` or `echo`. Source: gaebal-gajae dogfood on `ac925ed4`, 2026-05-26.
+
+752. **`claw <subcommand> --output-format json <bogus-arg>` returned `hint: null` for all `cli_parse` errors when an unrecognized positional arg was supplied** — dogfooded 2026-05-26 on `ddc71b56`. Generic `unrecognized argument` format string had no `\n` so `split_error_hint` emitted null hint (only the `--json` special-case added a hint). Fix: add else-branch appending `\nRun `claw <verb> --help` for usage.` to the generic arm. Affected surfaces: `sandbox`, `doctor`, `version`, and any other subcommand routing through the same unrecognized-arg path. Source: Jobdori dogfood on `ddc71b56`, 2026-05-26.
+
+753. **`claw --output-format json -p` (no prompt arg) returned `error_kind:"unknown"` and `hint: null`** — parity gap with #750/#751 which fixed the explicit `prompt` verb. Identified by gaebal-gajae on `ddc71b56`. Fix: same `missing_prompt:` prefix + newline usage hint as #750. Regression guard: `short_p_flag_no_arg_json_error_kind_753` asserting nonzero exit, `error_kind:"missing_prompt"`, non-empty hint mentioning `claw -p` or `claw prompt`. Source: gaebal-gajae dogfood on `ddc71b56`, 2026-05-26.
+
+754. **`missing_credentials` JSON envelope always had `hint: null` even when a contextual hint was available** — dogfooded 2026-05-26 on `e9327135`. `ApiError::Display` for `MissingCredentials` appended the hint via ` — hint: {hint}` (inline, no `\n`), so `split_error_hint()` could not extract it and left the JSON `hint` field null. Fix: change delimiter from ` — hint: ` to `\n` in `api/src/error.rs` Display impl; update two tests in `api/src/error.rs` and `api/src/providers/mod.rs` to assert newline separator. Source: Jobdori dogfood on `e9327135`, 2026-05-26.
+
+755. **`claw -p hello --model sonnet` swallowed `--model sonnet` into the prompt string** — gaebal-gajae pinpoint on `e9327135` (#117 revival). `-p` used `args[index+1..].join(" ")`, consuming all remaining tokens as prompt. Fix: capture exactly one token via `args.get(index+1)`, reject flag-like tokens (`starts_with('-')`) as `missing_prompt`, support `--` sentinel for literal flag-text, then `continue` the flag loop so `--model`/`--output-format`/etc. parse normally. Dispatch via `short_p_prompt` after full flag scan. Regression guard: `short_p_flag_swallows_no_flags_755` asserts `--output-format json` is parsed (not swallowed) and `--model` as prompt-arg is rejected. Source: gaebal-gajae dogfood on `e9327135`, 2026-05-26.
+
+756. **`--reasoning-effort bogus`, `--model` (no value), and sibling missing/invalid flag-value errors all returned `error_kind:"unknown"` + `hint:null`** — gaebal-gajae pinpoint on `0e8a449e`. All `missing value for --X` and `invalid value for --reasoning-effort` error strings were single-line with no classifier arm. Fix: (a) prefix all with `missing_flag_value:` / `invalid_flag_value:` + `\n` usage hint; (b) add `message.starts_with("missing_flag_value:")` → `"missing_flag_value"` and `message.starts_with("invalid_flag_value:")` → `"invalid_flag_value"` classifier arms. Covers `--model`, `--output-format`, `--permission-mode`, `--base-commit`, `--reasoning-effort`. Regression guard: `flag_value_errors_have_error_kind_and_hint_756` — invalid `--reasoning-effort HIGH` → `invalid_flag_value` + hint with valid values; missing `--model` → `missing_flag_value` + non-null hint. Source: gaebal-gajae dogfood on `0e8a449e`, 2026-05-26.
+
+757. **`--permission-mode bogus` and `--allowedTools` (no value) returned `error_kind:"unknown"` + `hint:null`** — dogfooded 2026-05-26 on `4df14618`. `parse_permission_mode_arg()` error format had no prefix and no `\n`; `--allowedTools` missing-value string was plain. Fix: prefix `parse_permission_mode_arg` error with `invalid_flag_value:` + `\n` valid-values hint (both call sites); prefix `--allowedTools` missing-value with `missing_flag_value:` + `\n` usage hint. Both now classified by existing `missing_flag_value`/`invalid_flag_value` arms added in #756. Source: Jobdori dogfood on `4df14618`, 2026-05-26.
+
+758. **Three remaining `missing value for --X` strings in `parse_init_args` were still untyped** — dogfooded 2026-05-26 on `02d77ae1`. `--cwd`, `--date`, `--session` missing-value errors in the init-args parser used the old plain-string form with no `missing_flag_value:` prefix and no `\n` hint, unlike the main `parse_args` flags fixed in #756/#757. Fix: applied `missing_flag_value:` prefix + `\n` usage hint to all three. `grep '"missing value for --'` now returns zero results outside of test assertions. Source: Jobdori dogfood sweep on `02d77ae1`, 2026-05-26.
+
+759. **`--model badmodel --output-format json` returned `error_kind:"invalid_model_syntax"` but `hint: null`** — dogfooded 2026-05-26 on `b8b3af6f`. `validate_model_syntax()` had hint text embedded after a period in the error string (no `\n`), so `split_error_hint()` could not extract it. Affected paths: (a) generic invalid format `"invalid model syntax: '{}'.  Expected ..."` — joined with `.` not `\n`; (b) spaces-in-model `"contains spaces. Use ..."` — same issue; (c) empty model string — no hint at all. Fix: added `\n` before hint text in all three format strings in `validate_model_syntax`. Source: Jobdori dogfood sweep on `b8b3af6f`, 2026-05-26.
+
+760. **`agent_not_found` and `plugin_not_found` error envelopes lacked `hint` field** — dogfooded 2026-05-26 on `ef31328a`. `claw agents show nonexistent-agent --output-format json` returned `error_kind:"agent_not_found"` with `hint: null`; same for `claw plugins show`. Both structured JSON envelopes in `commands/src/lib.rs` and `main.rs` omitted `hint`. Fix: added `"hint": "Run \`claw agents list\` to see available agents."` to the `agent_not_found` envelope; `"hint": "Run \`claw plugins list\` to see available plugins."` to the `plugin_not_found` envelope. Source: Jobdori dogfood sweep on `ef31328a`, 2026-05-26.
+
+761. **`mcp show <nonexistent>` and `skills show <nonexistent>` returned `hint: null`** — dogfooded 2026-05-27 on `7fa81b5d`. `server_not_found` envelope in `render_mcp_show_json` and `skill_not_found` envelope in `print_skills` JSON path both lacked `hint` fields, unlike `agent_not_found`/`plugin_not_found` fixed in #760. Fix: added `"hint": "Run \`claw mcp list\` to see configured servers."` to `server_not_found` and `"hint": "Run \`claw skills list\` to see available skills."` to `skill_not_found`. All four `*_not_found` envelopes now have hints. Source: Jobdori dogfood sweep on `7fa81b5d`, 2026-05-27.
+
+762. **`classify_error_kind` unit test missing coverage for 15 of 23 classifier arms** — dogfooded 2026-05-27 on `d83de563`. `classify_error_kind_returns_correct_discriminants` only asserted 8 of the 23 arms, leaving `missing_flag_value`, `invalid_flag_value`, `missing_prompt`, `interactive_only`, `unknown_agents_subcommand`, `agent_not_found`, `plugin_not_found`, `skill_not_found`, `unsupported_config_section`, `no_managed_sessions`, `legacy_session_no_workspace_binding`, `missing_manifests`, `unknown_plugins_action`, `unsupported_skills_action`, and `confirmation_required` uncovered. Any discriminant string drift would silently fall to `"unknown"` without a failing test. Fix: added 18 new `assert_eq!` invocations covering all previously untested arms. Source: Jobdori test-brittleness sweep on `d83de563`, 2026-05-27.

rust/crates/api/src/error.rs

@@ -273,7 +273,10 @@ impl Display for ApiError {
                     }
                 }
                 if let Some(hint) = hint {
-                    write!(f, " — hint: {hint}")?;
+                    // #754: newline-delimited so split_error_hint() can extract the hint
+                    // into the JSON envelope's `hint` field. The em-dash form was a
+                    // single-line string that left hint:null in --output-format json.
+                    write!(f, "\n{hint}")?;
                 }
                 Ok(())
             }
@@ -608,11 +611,16 @@ mod tests {
             rendered.starts_with("missing Anthropic credentials;"),
             "hint should be appended, not replace the base message: {rendered}"
         );
-        let hint_marker = " — hint: I see OPENAI_API_KEY is set — if you meant to use the OpenAI-compat provider, prefix your model name with `openai/` so prefix routing selects it.";
+        // #754: hint is now newline-delimited so split_error_hint() can extract it
+        let hint_text = "I see OPENAI_API_KEY is set — if you meant to use the OpenAI-compat provider, prefix your model name with `openai/` so prefix routing selects it.";
         assert!(
-            rendered.ends_with(hint_marker),
+            rendered.ends_with(hint_text),
             "rendered error should end with the hint: {rendered}"
         );
+        assert!(
+            rendered.contains('\n'),
+            "rendered error must contain newline separator so split_error_hint works: {rendered}"
+        );
         // Classification semantics are unaffected by the presence of a hint.
         assert_eq!(error.safe_failure_class(), "provider_auth");
         assert!(!error.is_retryable());

rust/crates/api/src/providers/mod.rs

@@ -1649,10 +1649,15 @@ NO_EQUALS_LINE
             rendered.starts_with("missing Anthropic credentials;"),
             "canonical base message should still lead the rendered error: {rendered}"
         );
+        // #754: hint delimiter changed from " — hint: " to "\n" so split_error_hint works
         assert!(
-            rendered.contains(" — hint: I see OPENAI_API_KEY is set"),
+            rendered.contains("I see OPENAI_API_KEY is set"),
             "rendered error should carry the env-driven hint: {rendered}"
         );
+        assert!(
+            rendered.contains('\n'),
+            "rendered error must use newline separator (#754): {rendered}"
+        );
     }
 
     #[test]

rust/crates/commands/src/lib.rs

@@ -2145,6 +2145,8 @@ struct AgentSummary {
     reasoning_effort: Option<String>,
     source: DefinitionSource,
     shadowed_by: Option<DefinitionSource>,
+    // #728: on-disk path so `agents show` can surface the file path
+    path: Option<PathBuf>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -2154,6 +2156,8 @@ struct SkillSummary {
     source: DefinitionSource,
     shadowed_by: Option<DefinitionSource>,
     origin: SkillOrigin,
+    // #729: on-disk path parity with AgentSummary
+    path: Option<PathBuf>,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -2330,6 +2334,13 @@ pub fn handle_plugins_slash_command(
                 reload_runtime: false,
             })
         }
+        // #743/#420: "help" was caught by Some(other) → unknown_plugins_action error with hint:null.
+        // agents/mcp/skills all return a help envelope; plugins must match that parity.
+        Some("help" | "-h" | "--help") => Ok(PluginsCommandResult {
+            message: "Plugins\n  Usage            /plugins [list|show <id>|install <id>|enable <id>|disable <id>|uninstall <id>|update <id>|help]\n  Subcommands      list  show  install  enable  disable  uninstall  update  help"
+                .to_string(),
+            reload_runtime: false,
+        }),
         Some(other) => Err(PluginError::CommandFailed(format!(
             "unknown_plugins_action: '{other}' is not a supported /plugins action. Use list, show, install, enable, disable, uninstall, or update."
         ))),
@@ -2455,6 +2466,10 @@ pub fn handle_agents_slash_command_json(args: Option<&str>, cwd: &Path) -> std::
                     "status": "error",
                     "error_kind": "agent_not_found",
                     "requested": name,
+                    // #734: parity with skills show which always emits a message field
+                    "message": format!("agent '{}' not found", name),
+                    // #760: hint so callers know how to enumerate available agents
+                    "hint": "Run `claw agents list` to see available agents.",
                 }));
             }
             Ok(render_agents_report_json_with_action(cwd, &matched, "show"))
@@ -2606,6 +2621,8 @@ pub fn handle_skills_slash_command_json(args: Option<&str>, cwd: &Path) -> std::
                     "error_kind": "skill_not_found",
                     "message": format!("skill '{}' not found", name),
                     "requested": name,
+                    // #761: hint so callers know how to enumerate available skills
+                    "hint": "Run `claw skills list` to see available skills.",
                 }));
             }
             Ok(render_skills_report_json_with_action(&matched, "show"))
@@ -3541,6 +3558,7 @@ fn load_agents_from_roots(
                 reasoning_effort: parse_toml_string(&contents, "model_reasoning_effort"),
                 source: *source,
                 shadowed_by: None,
+                path: Some(entry.path()),
             });
         }
         root_agents.sort_by(|left, right| left.name.cmp(&right.name));
@@ -3585,6 +3603,7 @@ fn load_skills_from_roots(roots: &[SkillRoot]) -> std::io::Result<Vec<SkillSumma
                         source: root.source,
                         shadowed_by: None,
                         origin: root.origin,
+                        path: Some(entry.path()),
                     });
                 }
                 SkillOrigin::LegacyCommandsDir => {
@@ -3616,6 +3635,7 @@ fn load_skills_from_roots(roots: &[SkillRoot]) -> std::io::Result<Vec<SkillSumma
                         source: root.source,
                         shadowed_by: None,
                         origin: root.origin,
+                        path: Some(markdown_path),
                     });
                 }
             }
@@ -4038,6 +4058,8 @@ fn render_mcp_server_report_json(
             "found": false,
             "server_name": server_name,
             "message": format!("server `{server_name}` is not configured"),
+            // #761: hint so callers know how to enumerate configured MCP servers
+            "hint": "Run `claw mcp list` to see configured servers.",
         }),
     }
 }
@@ -4145,11 +4167,18 @@ fn render_mcp_usage(unexpected: Option<&str>) -> String {
 }
 
 fn render_mcp_usage_json(unexpected: Option<&str>) -> Value {
+    // #748: add error_kind when unexpected is set, matching agents/plugins unknown-subcommand shape.
+    let error_kind: Value = if unexpected.is_some() {
+        json!("unknown_mcp_action")
+    } else {
+        Value::Null
+    };
     json!({
         "kind": "mcp",
         "action": "help",
         "ok": unexpected.is_none(),
         "status": if unexpected.is_some() { "error" } else { "ok" },
+        "error_kind": error_kind,
         "usage": {
             "slash_command": "/mcp [list|show <server>|help]",
             "direct_cli": "claw mcp [list|show <server>|help]",
@@ -4273,6 +4302,8 @@ fn agent_summary_json(agent: &AgentSummary) -> Value {
         "source": definition_source_json(agent.source),
         "active": agent.shadowed_by.is_none(),
         "shadowed_by": agent.shadowed_by.map(definition_source_json),
+        // #728: expose on-disk path so callers can inspect the agent file directly
+        "path": agent.path.as_ref().map(|p| p.display().to_string()),
     })
 }
 
@@ -4298,6 +4329,8 @@ fn skill_summary_json(skill: &SkillSummary) -> Value {
         "origin": skill_origin_json(skill.origin),
         "active": skill.shadowed_by.is_none(),
         "shadowed_by": skill.shadowed_by.map(definition_source_json),
+        // #729: path parity with agent_summary_json
+        "path": skill.path.as_ref().map(|p| p.display().to_string()),
     })
 }
 

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

@@ -278,12 +278,18 @@ fn classify_error_kind(message: &str) -> &'static str {
         "session_load_failed"
     } else if message.contains("no managed sessions found") {
         "no_managed_sessions"
+    } else if message.contains("legacy session is missing workspace binding") {
+        "legacy_session_no_workspace_binding"
     } else if message.contains("unsupported ACP invocation") {
         "unsupported_acp_invocation"
     } else if message.contains("unsupported skills action") {
         "unsupported_skills_action"
     } else if message.contains("unrecognized argument") || message.contains("unknown option") {
         "cli_parse"
+    } else if message.starts_with("missing_flag_value:") {
+        "missing_flag_value"
+    } else if message.starts_with("invalid_flag_value:") {
+        "invalid_flag_value"
     } else if message.contains("invalid model syntax") {
         "invalid_model_syntax"
     } else if message.contains("is not yet implemented") {
@@ -314,7 +320,13 @@ fn classify_error_kind(message: &str) -> &'static str {
         "unsupported_config_section"
     } else if message.contains("unknown_plugins_action") {
         "unknown_plugins_action"
-    } else if message.contains("is a slash command") || message.starts_with("interactive_only:") {
+    } else if message.starts_with("missing_prompt:") {
+        "missing_prompt"
+    } else if message.contains("is a slash command")
+        || message.starts_with("interactive_only:")
+        // #735: "slash command /X is interactive-only" emitted by interactive-only guard
+        || (message.starts_with("slash command") && message.contains("interactive-only"))
+    {
         "interactive_only"
     } else {
         "unknown"
@@ -400,6 +412,8 @@ fn plugin_summary_json(plugin: &plugins::PluginSummary) -> Value {
         "description": &plugin.metadata.description,
         "kind": plugin.metadata.kind.to_string(),
         "source": &plugin.metadata.source,
+        // #730: path parity with agents (#728) and skills (#729)
+        "path": plugin.metadata.root.as_ref().map(|p| p.display().to_string()),
         "enabled": plugin.enabled,
         "lifecycle_state": plugin.lifecycle_state(),
         "lifecycle": {
@@ -732,6 +746,9 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
     let mut base_commit: Option<String> = None;
     let mut reasoning_effort: Option<String> = None;
     let mut allow_broad_cwd = false;
+    // #755: -p prompt text captured as single token; remaining args continue
+    // flag parsing. None until `-p <text>` is seen.
+    let mut short_p_prompt: Option<String> = None;
     let mut rest: Vec<String> = Vec::new();
     let mut index = 0;
 
@@ -763,7 +780,7 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             "--model" => {
                 let value = args
                     .get(index + 1)
-                    .ok_or_else(|| "missing value for --model".to_string())?;
+                    .ok_or_else(|| "missing_flag_value: missing value for --model.\nUsage: --model <provider/model>  e.g. --model anthropic/claude-opus-4-7".to_string())?;
                 let resolved = resolve_model_alias_with_config(value);
                 debug!("Resolved --model '{}' -> '{}'", value, resolved);
                 validate_model_syntax(&resolved)?;
@@ -783,14 +800,14 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             "--output-format" => {
                 let value = args
                     .get(index + 1)
-                    .ok_or_else(|| "missing value for --output-format".to_string())?;
+                    .ok_or_else(|| "missing_flag_value: missing value for --output-format.\nUsage: --output-format text  or  --output-format json".to_string())?;
                 output_format = CliOutputFormat::parse(value)?;
                 index += 2;
             }
             "--permission-mode" => {
                 let value = args
                     .get(index + 1)
-                    .ok_or_else(|| "missing value for --permission-mode".to_string())?;
+                    .ok_or_else(|| "missing_flag_value: missing value for --permission-mode.\nUsage: --permission-mode default|acceptEdits|bypassPermissions|dangerFullAccess".to_string())?;
                 permission_mode_override = Some(parse_permission_mode_arg(value)?);
                 index += 2;
             }
@@ -813,7 +830,7 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             "--base-commit" => {
                 let value = args
                     .get(index + 1)
-                    .ok_or_else(|| "missing value for --base-commit".to_string())?;
+                    .ok_or_else(|| "missing_flag_value: missing value for --base-commit.\nUsage: --base-commit <git-sha>".to_string())?;
                 base_commit = Some(value.clone());
                 index += 2;
             }
@@ -824,10 +841,10 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             "--reasoning-effort" => {
                 let value = args
                     .get(index + 1)
-                    .ok_or_else(|| "missing value for --reasoning-effort".to_string())?;
+                    .ok_or_else(|| "missing_flag_value: missing value for --reasoning-effort.\nUsage: --reasoning-effort low|medium|high".to_string())?;
                 if !matches!(value.as_str(), "low" | "medium" | "high") {
                     return Err(format!(
-                        "invalid value for --reasoning-effort: '{value}'; must be low, medium, or high"
+                        "invalid_flag_value: invalid value for --reasoning-effort: '{value}'.\nUsage: --reasoning-effort low|medium|high"
                     ));
                 }
                 reasoning_effort = Some(value.clone());
@@ -837,7 +854,7 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
                 let value = &flag[19..];
                 if !matches!(value, "low" | "medium" | "high") {
                     return Err(format!(
-                        "invalid value for --reasoning-effort: '{value}'; must be low, medium, or high"
+                        "invalid_flag_value: invalid value for --reasoning-effort: '{value}'.\nUsage: --reasoning-effort low|medium|high"
                     ));
                 }
                 reasoning_effort = Some(value.to_string());
@@ -848,23 +865,40 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
                 index += 1;
             }
             "-p" => {
-                // Claw Code compat: -p "prompt" = one-shot prompt
-                let prompt = args[index + 1..].join(" ");
-                if prompt.trim().is_empty() {
-                    return Err("-p requires a prompt string".to_string());
+                // Claw Code compat: -p "prompt" = one-shot prompt.
+                // #755: consume exactly one token so subsequent flags like
+                // --model/--output-format are parsed normally instead of
+                // being swallowed into the prompt string (#117).
+                let next = args.get(index + 1).map(|s| s.as_str());
+                match next {
+                    None | Some("") => {
+                        return Err("missing_prompt: -p requires a prompt string.\nUsage: claw -p <text>  or  claw prompt <text>".to_string());
+                    }
+                    Some(tok) if tok.starts_with('-') && tok != "--" => {
+                        // Looks like a flag, not a prompt. Reject so the user
+                        // knows to quote the literal text or use `--`.
+                        return Err(format!(
+                            "missing_prompt: -p requires a prompt string before flags; got `{tok}`.\nUsage: claw -p <text> --model sonnet  or  claw -p -- {tok} (literal)"
+                        ));
+                    }
+                    Some(tok) => {
+                        // `--` sentinel: skip it and take the token after as literal
+                        let (prompt_text, skip) = if tok == "--" {
+                            match args.get(index + 2) {
+                                Some(t) => (t.as_str(), 3usize),
+                                None => return Err("missing_prompt: -p -- requires a prompt string after `--`.\nUsage: claw -p -- <text>".to_string()),
+                            }
+                        } else {
+                            (tok, 2usize)
+                        };
+                        if prompt_text.trim().is_empty() {
+                            return Err("missing_prompt: -p requires a non-empty prompt string.\nUsage: claw -p <text>  or  claw prompt <text>".to_string());
+                        }
+                        short_p_prompt = Some(prompt_text.to_string());
+                        index += skip;
+                        continue;
+                    }
                 }
-                return Ok(CliAction::Prompt {
-                    prompt,
-                    model: resolve_model_alias_with_config(&model),
-                    output_format,
-                    allowed_tools: normalize_allowed_tools(&allowed_tool_values)?,
-                    permission_mode: permission_mode_override
-                        .unwrap_or_else(default_permission_mode),
-                    compact,
-                    base_commit: base_commit.clone(),
-                    reasoning_effort: reasoning_effort.clone(),
-                    allow_broad_cwd,
-                });
             }
             "--print" => {
                 // Claw Code compat: --print makes output non-interactive
@@ -887,7 +921,7 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             "--allowedTools" | "--allowed-tools" => {
                 let value = args
                     .get(index + 1)
-                    .ok_or_else(|| "missing value for --allowedTools".to_string())?;
+                    .ok_or_else(|| "missing_flag_value: missing value for --allowedTools.\nUsage: --allowedTools <tool-name>  e.g. --allowedTools Bash".to_string())?;
                 allowed_tool_values.push(value.clone());
                 index += 2;
             }
@@ -954,6 +988,21 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
 
     let allowed_tools = normalize_allowed_tools(&allowed_tool_values)?;
 
+    // #755: -p consumed exactly one token; dispatch now that all flags are parsed
+    if let Some(prompt) = short_p_prompt {
+        return Ok(CliAction::Prompt {
+            prompt,
+            model: resolve_model_alias_with_config(&model),
+            output_format,
+            allowed_tools,
+            permission_mode: permission_mode_override.unwrap_or_else(default_permission_mode),
+            compact,
+            base_commit,
+            reasoning_effort,
+            allow_broad_cwd,
+        });
+    }
+
     if rest.is_empty() {
         let permission_mode = permission_mode_override.unwrap_or_else(default_permission_mode);
         // When stdin is not a terminal (pipe/redirect) and no prompt is given on the
@@ -982,7 +1031,8 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             // (#696: emit a typed error instead of hanging indefinitely)
             // Skip this guard in test builds (parse_args tests run in non-TTY context).
             #[cfg(not(test))]
-            return Err("interactive_only: claw requires an interactive terminal (stdin is not a TTY and no prompt was provided — pipe a prompt or run in a TTY)".into());
+            // #746: newline before remediation so split_error_hint populates hint field
+            return Err("interactive_only: claw requires an interactive terminal.\nStdin is not a TTY and no prompt was provided — pipe a prompt with `echo 'task' | claw` or run `claw` in an interactive terminal.".into());
         }
         return Ok(CliAction::Repl {
             model,
@@ -1138,7 +1188,8 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
         "prompt" => {
             let prompt = rest[1..].join(" ");
             if prompt.trim().is_empty() {
-                return Err("prompt subcommand requires a prompt string".to_string());
+                // #750: provide error_kind-compatible prefix + \n for hint extraction
+                return Err("missing_prompt: prompt subcommand requires a prompt string.\nUsage: claw prompt <text>  or  echo '<text>' | claw".to_string());
             }
             Ok(CliAction::Prompt {
                 prompt,
@@ -1314,6 +1365,9 @@ fn parse_single_word_command_alias(
         // Hint at the correct flag so they don't have to re-read --help.
         if rest[1] == "--json" {
             msg.push_str("\nDid you mean `--output-format json`?");
+        } else {
+            // #752: generic fallback hint so cli_parse errors always have non-null hint
+            msg.push_str(&format!("\nRun `claw {} --help` for usage.", verb));
         }
         return Some(Err(msg));
     }
@@ -1399,20 +1453,22 @@ fn bare_slash_command_guidance(command_name: &str) -> Option<String> {
     let slash_command = slash_command_specs()
         .iter()
         .find(|spec| spec.name == command_name)?;
+    // #745: newline before remediation text so split_error_hint populates hint field
     let guidance = if slash_command.resume_supported {
         format!(
-            "`claw {command_name}` is a slash command. Use `claw --resume SESSION.jsonl /{command_name}` or start `claw` and run `/{command_name}`."
+            "`claw {command_name}` is a slash command.\nUse `claw --resume SESSION.jsonl /{command_name}` or start `claw` and run `/{command_name}`."
         )
     } else {
         format!(
-            "`claw {command_name}` is a slash command. Start `claw` and run `/{command_name}` inside the REPL."
+            "`claw {command_name}` is a slash command.\nStart `claw` and run `/{command_name}` inside the REPL."
         )
     };
     Some(guidance)
 }
 
 fn compact_interactive_only_error() -> String {
-    "interactive_only: `claw compact` is an interactive/session command. Start `claw` and run `/compact`, or use `claw --resume SESSION.jsonl /compact` to compact an existing session."
+    // #749: newline before remediation so split_error_hint populates hint field
+    "interactive_only: `claw compact` is an interactive/session command.\nStart `claw` and run `/compact`, or use `claw --resume SESSION.jsonl /compact` to compact an existing session."
         .to_string()
 }
 
@@ -1505,7 +1561,8 @@ fn parse_direct_slash_cli_action(
         Ok(Some(command)) => Err({
             let _ = command;
             format!(
-                "slash command {command_name} is interactive-only. Start `claw` and run it there, or use `claw --resume SESSION.jsonl {command_name}` / `claw --resume {latest} {command_name}` when the command is marked [resume] in /help.",
+                // #738: newline before remediation so split_error_hint populates hint field
+                "slash command {command_name} is interactive-only.\nStart `claw` and run it there, or use `claw --resume SESSION.jsonl {command_name}` / `claw --resume {latest} {command_name}` when the command is marked [resume] in /help.",
                 command_name = rest[0],
                 latest = LATEST_SESSION_REFERENCE,
             )
@@ -1721,12 +1778,12 @@ fn resolve_model_alias_with_config(model: &str) -> String {
 fn validate_model_syntax(model: &str) -> Result<(), String> {
     let trimmed = model.trim();
     if trimmed.is_empty() {
-        return Err("model string cannot be empty".to_string());
+        return Err("invalid model syntax: model string cannot be empty.\nUsage: --model <provider/model>  e.g. --model anthropic/claude-opus-4-7".to_string());
     }
     // Check for spaces (malformed)
     if trimmed.contains(' ') {
         return Err(format!(
-            "invalid model syntax: '{}' contains spaces. Use provider/model format or known alias",
+            "invalid model syntax: '{}' contains spaces.\nUse provider/model format (e.g., anthropic/claude-opus-4-7) or a known alias.",
             trimmed
         ));
     }
@@ -1735,7 +1792,7 @@ fn validate_model_syntax(model: &str) -> Result<(), String> {
     if parts.len() != 2 || parts[0].is_empty() || parts[1].is_empty() {
         // #154: hint if the model looks like it belongs to a different provider
         let mut err_msg = format!(
-            "invalid model syntax: '{}'. Expected provider/model (e.g., anthropic/claude-opus-4-6)",
+            "invalid model syntax: '{}'.\nExpected provider/model (e.g., anthropic/claude-opus-4-7)",
             trimmed
         );
         if trimmed.starts_with("gpt-") || trimmed.starts_with("gpt_") {
@@ -1794,7 +1851,7 @@ fn parse_permission_mode_arg(value: &str) -> Result<PermissionMode, String> {
     normalize_permission_mode(value)
         .ok_or_else(|| {
             format!(
-                "unsupported permission mode '{value}'. Use read-only, workspace-write, or danger-full-access."
+                "invalid_flag_value: unsupported permission mode '{value}'.\nUsage: --permission-mode read-only|workspace-write|danger-full-access"
             )
         })
         .map(permission_mode_from_label)
@@ -1892,16 +1949,17 @@ fn parse_system_prompt_args(
     while index < args.len() {
         match args[index].as_str() {
             "--cwd" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --cwd".to_string())?;
+                let value = args.get(index + 1).ok_or_else(|| {
+                    "missing_flag_value: missing value for --cwd.\nUsage: --cwd <path>".to_string()
+                })?;
                 cwd = PathBuf::from(value);
                 index += 2;
             }
             "--date" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --date".to_string())?;
+                let value = args.get(index + 1).ok_or_else(|| {
+                    "missing_flag_value: missing value for --date.\nUsage: --date <YYYY-MM-DD>"
+                        .to_string()
+                })?;
                 date.clone_from(value);
                 index += 2;
             }
@@ -1934,7 +1992,7 @@ fn parse_export_args(args: &[String], output_format: CliOutputFormat) -> Result<
             "--session" => {
                 let value = args
                     .get(index + 1)
-                    .ok_or_else(|| "missing value for --session".to_string())?;
+                    .ok_or_else(|| "missing_flag_value: missing value for --session.\nUsage: --session <session-id>".to_string())?;
                 session_reference.clone_from(value);
                 index += 2;
             }
@@ -2120,7 +2178,11 @@ impl DiagnosticCheck {
             ),
             ("summary".to_string(), Value::String(self.summary.clone())),
             (
-                "details".to_string(),
+                // #701 (complete): `details[]` is now the canonical structured form —
+                // `{key, value}` objects instead of padded prose strings. The legacy
+                // prose representation is preserved as `details_prose[]` for callers
+                // that still scrape the formatted strings.
+                "details_prose".to_string(),
                 Value::Array(
                     self.details
                         .iter()
@@ -2130,10 +2192,8 @@ impl DiagnosticCheck {
                 ),
             ),
             (
-                // #701: structured key/value pairs parsed from prose detail strings.
-                // Each detail string is `"Key Label      value"` separated by 2+ spaces.
-                // Booleans (`true`/`false`) and integers are emitted as JSON scalars.
-                "detail_entries".to_string(),
+                // details[] is now structured {key,value} objects (was prose strings).
+                "details".to_string(),
                 Value::Array(
                     self.details
                         .iter()
@@ -2750,16 +2810,26 @@ fn check_boot_preflight_health(context: &StatusContext) -> DiagnosticCheck {
                 .map_or("unknown".to_string(), |v| v.to_string())
         ),
         format!("Trusted roots    {}", preflight.trusted_roots_count),
+        // #736: keep compound values readable but use " · " as intra-value separator
+        // so the two-space prose splitter yields key="MCP eligible" value="true · servers 0"
         format!(
-            "MCP eligible     {} · servers {}",
-            preflight.mcp_startup_eligible, preflight.mcp_servers_configured
+            "MCP eligible     {}",
+            format!(
+                "{}  ·  servers {}",
+                preflight.mcp_startup_eligible, preflight.mcp_servers_configured
+            )
         ),
         format!(
-            "Plugin eligible  {} · configured {}",
-            preflight.plugin_startup_eligible, preflight.plugins_configured
+            "Plugin eligible  {}",
+            format!(
+                "{}  ·  configured {}",
+                preflight.plugin_startup_eligible, preflight.plugins_configured
+            )
         ),
         format!(
-            "Last failed boot {}",
+            // #736: use two-space separator so the detail_entries prose splitter
+            // can extract key="Last failed boot" value="<none>|<reason>"
+            "Last failed boot  {}",
             preflight
                 .last_failed_boot_reason
                 .as_deref()
@@ -2768,7 +2838,8 @@ fn check_boot_preflight_health(context: &StatusContext) -> DiagnosticCheck {
     ];
     details.extend(preflight.required_binaries.iter().map(|binary| {
         format!(
-            "Required binary {} available={}",
+            // #736: two-space separator → key="Required binary <name>" value="available=true|false"
+            "Required binary {}  available={}",
             binary.name, binary.available
         )
     }));
@@ -3324,6 +3395,10 @@ impl BranchFreshness {
     fn json_value(&self) -> serde_json::Value {
         json!({
             "upstream": self.upstream,
+            // #727: has_upstream disambiguates fresh:null-because-no-upstream
+            // from fresh:null-because-unavailable; automation should check
+            // has_upstream before branching on fresh.
+            "has_upstream": self.upstream.is_some(),
             "ahead": self.ahead,
             "behind": self.behind,
             "fresh": self.fresh,
@@ -5880,7 +5955,7 @@ impl LiveCli {
 
         let normalized = normalize_permission_mode(&mode).ok_or_else(|| {
             format!(
-                "unsupported permission mode '{mode}'. Use read-only, workspace-write, or danger-full-access."
+                "invalid_flag_value: unsupported permission mode '{mode}'.\nUsage: --permission-mode read-only|workspace-write|danger-full-access"
             )
         })?;
 
@@ -6054,8 +6129,11 @@ impl LiveCli {
             CliOutputFormat::Json => {
                 let result = handle_skills_slash_command_json(args, &cwd)?;
                 let is_error = result.get("status").and_then(|v| v.as_str()) == Some("error");
+                // #739: action:"help" with unexpected set is a usage response, not a fatal error;
+                // don't return Err which would emit a second error envelope from the generic path.
+                let is_help_action = result.get("action").and_then(|v| v.as_str()) == Some("help");
                 println!("{}", serde_json::to_string_pretty(&result)?);
-                if is_error {
+                if is_error && !is_help_action {
                     return Err(result
                         .get("message")
                         .and_then(|v| v.as_str())
@@ -6079,6 +6157,23 @@ impl LiveCli {
             CliOutputFormat::Text => println!("{}", payload.message),
             CliOutputFormat::Json => {
                 let action_str = action.unwrap_or("list");
+                // #743/#420: plugins help must return a usage envelope matching agents/mcp/skills help shape.
+                if matches!(action_str, "help" | "-h" | "--help") {
+                    let cwd_str = cwd.display().to_string();
+                    let obj = json!({
+                        "kind": "plugin",
+                        "action": "help",
+                        "status": "ok",
+                        "unexpected": null,
+                        "usage": {
+                            "direct_cli": "claw plugins [list|show <id>|install <id>|enable <id>|disable <id>|uninstall <id>|update <id>|help]",
+                            "slash_command": "/plugins [list|show <id>|install <id>|enable <id>|disable <id>|uninstall <id>|update <id>|help]",
+                        },
+                        "cwd": cwd_str,
+                    });
+                    println!("{}", serde_json::to_string_pretty(&obj)?);
+                    return Ok(());
+                }
                 // For show/info/describe, filter to the named plugin (exact match).
                 // For list with a target, treat target as a substring filter.
                 let is_show_action = matches!(action_str, "show" | "info" | "describe");
@@ -6130,6 +6225,10 @@ impl LiveCli {
                                 "status": "error",
                                 "error_kind": "plugin_not_found",
                                 "requested": name,
+                                // #734: parity with skills show which always emits a message field
+                                "message": format!("plugin '{}' not found", name),
+                                // #760: hint so callers know how to enumerate available plugins
+                                "hint": "Run `claw plugins list` to see available plugins.",
                             });
                             println!("{}", serde_json::to_string_pretty(&obj)?);
                             return Ok(());
@@ -6921,7 +7020,11 @@ fn status_json_value(
     let degraded = context.config_load_error.is_some();
     let model_source = provenance.map(|p| p.source.as_str());
     let model_raw = provenance.and_then(|p| p.raw.clone());
-    let allowed_tool_entries = allowed_tools.map(|tools| tools.iter().cloned().collect::<Vec<_>>());
+    // #732: always emit an array (empty when unrestricted) so callers can do
+    // `.allowed_tools.entries | length > 0` without a null-check first.
+    let allowed_tool_entries = allowed_tools
+        .map(|tools| tools.iter().cloned().collect::<Vec<_>>())
+        .unwrap_or_default();
     json!({
         "kind": "status",
         "action": "show",
@@ -7268,15 +7371,22 @@ fn print_sandbox_status_snapshot(
 fn sandbox_json_value(status: &runtime::SandboxStatus) -> serde_json::Value {
     // Derive top-level status so automation can do a single field check
     // instead of combining enabled/active/supported booleans.
-    // ok  = not enabled (not requested), OR enabled and active
-    // warn = enabled and supported but not yet active (degraded)
-    // error = enabled but unsupported on this platform
+    // ok   = not enabled (not requested), OR enabled and active
+    // warn = enabled and supported but not yet active (degraded),
+    //        OR enabled but unsupported on this platform AND filesystem sandbox is active
+    //        (#731: "not supported on macOS" is a degraded state, not a hard error;
+    //         filesystem_active:true means partial containment is working)
+    // error = enabled but unsupported AND no filesystem sandbox either (nothing active)
     let top_status = if !status.enabled {
         "ok"
     } else if status.active {
         "ok"
     } else if status.supported {
         "warn"
+    } else if status.filesystem_active {
+        // Platform doesn't support namespace isolation but filesystem sandbox is active:
+        // this is a degraded/partial state, not a hard error.
+        "warn"
     } else {
         "error"
     };
@@ -7749,6 +7859,17 @@ fn render_config_json(
             "skills" => runtime_config.get("skills").map(|v| v.render()),
             "agents" => runtime_config.get("agents").map(|v| v.render()),
             other => {
+                // #741: populate hint field for unsupported section errors so callers reading
+                // .hint get actionable guidance instead of null
+                let hint = if matches!(other, "list" | "show" | "help" | "info") {
+                    format!(
+                        "'claw config {other}' is not a subcommand. To list all config: `claw config`. To inspect a section: `claw config <section>` where section is one of: env, hooks, model, plugins, mcp, sandbox, permissions, skills, agents."
+                    )
+                } else {
+                    format!(
+                        "'{other}' is not a config section. Supported: env, hooks, model, plugins, mcp, sandbox, permissions, skills, agents."
+                    )
+                };
                 return Ok(serde_json::json!({
                     "kind": "config",
                     "action": "show",
@@ -7757,6 +7878,7 @@ fn render_config_json(
                     "section": other,
                     "ok": false,
                     "error": format!("Unsupported config section '{other}'. Use: env, hooks, model, plugins, mcp, sandbox, permissions, skills, or agents."),
+                    "hint": hint,
                     "supported_sections": ["env", "hooks", "model", "plugins", "mcp", "sandbox", "permissions", "skills", "agents"],
                     "cwd": cwd.display().to_string(),
                     "loaded_files": loaded_paths.len(),
@@ -7954,12 +8076,25 @@ fn render_diff_json_for(cwd: &Path) -> Result<serde_json::Value, Box<dyn std::er
     }
     let staged = run_git_diff_command_in(cwd, &["diff", "--cached"])?;
     let unstaged = run_git_diff_command_in(cwd, &["diff"])?;
+    // #733: add changed_file_count so callers don't have to count diff hunks
+    let staged_files =
+        run_git_diff_command_in(cwd, &["diff", "--cached", "--name-only"]).unwrap_or_default();
+    let unstaged_files = run_git_diff_command_in(cwd, &["diff", "--name-only"]).unwrap_or_default();
+    let mut changed: std::collections::BTreeSet<&str> = std::collections::BTreeSet::new();
+    for line in staged_files.lines().chain(unstaged_files.lines()) {
+        let t = line.trim();
+        if !t.is_empty() {
+            changed.insert(t);
+        }
+    }
+    let changed_file_count = changed.len();
     Ok(serde_json::json!({
         "kind": "diff",
         "action": "diff",
         "status": "ok",
         "working_directory": cwd.display().to_string(),
         "result": if staged.trim().is_empty() && unstaged.trim().is_empty() { "clean" } else { "changes" },
+        "changed_file_count": changed_file_count,
         "staged": staged.trim(),
         "unstaged": unstaged.trim(),
     }))
@@ -12698,6 +12833,88 @@ mod tests {
             classify_error_kind("something completely unknown"),
             "unknown"
         );
+        // #762: coverage for all classifier arms added since #77 — prevents silent fallback
+        // to "unknown" if discriminant strings drift.
+        assert_eq!(
+            classify_error_kind("Manifest source files are missing: /tmp/x"),
+            "missing_manifests"
+        );
+        assert_eq!(
+            classify_error_kind("no managed sessions found in /tmp"),
+            "no_managed_sessions"
+        );
+        assert_eq!(
+            classify_error_kind("legacy session is missing workspace binding"),
+            "legacy_session_no_workspace_binding"
+        );
+        assert_eq!(
+            classify_error_kind("unsupported skills action: bogus. Supported actions: list"),
+            "unsupported_skills_action"
+        );
+        assert_eq!(
+            classify_error_kind(
+                "missing_flag_value: missing value for --model.\nUsage: --model <provider/model>"
+            ),
+            "missing_flag_value"
+        );
+        assert_eq!(
+            classify_error_kind("invalid_flag_value: unsupported permission mode 'bogus'.\nUsage: --permission-mode read-only|workspace-write|danger-full-access"),
+            "invalid_flag_value"
+        );
+        assert_eq!(
+            classify_error_kind("is not yet implemented"),
+            "unsupported_command"
+        );
+        assert_eq!(
+            classify_error_kind("confirmation required before running destructive operation"),
+            "confirmation_required"
+        );
+        assert_eq!(
+            classify_error_kind("api returned unexpected status 429"),
+            "api_http_error"
+        );
+        assert_eq!(
+            classify_error_kind("interactive_only: this command requires an interactive terminal"),
+            "interactive_only"
+        );
+        assert_eq!(
+            classify_error_kind("slash command /compact is interactive-only"),
+            "interactive_only"
+        );
+        assert_eq!(
+            classify_error_kind("unknown agents subcommand: bogus. Supported: list, show, help"),
+            "unknown_agents_subcommand"
+        );
+        assert_eq!(
+            classify_error_kind("agent not found: my-agent"),
+            "agent_not_found"
+        );
+        assert_eq!(
+            classify_error_kind("my-plugin is not installed"),
+            "plugin_not_found"
+        );
+        assert_eq!(
+            classify_error_kind("skill source /path/to/skill not found"),
+            "skill_not_found"
+        );
+        assert_eq!(
+            classify_error_kind("skill 'my-skill' does not exist"),
+            "skill_not_found"
+        );
+        assert_eq!(
+            classify_error_kind("Unsupported config section 'show'. Use: env, hooks, model"),
+            "unsupported_config_section"
+        );
+        assert_eq!(
+            classify_error_kind("unknown_plugins_action: bogus"),
+            "unknown_plugins_action"
+        );
+        assert_eq!(
+            classify_error_kind(
+                "missing_prompt: -p requires a prompt string.\nUsage: claw -p <text>"
+            ),
+            "missing_prompt"
+        );
     }
 
     #[test]

rust/crates/rusty-claude-cli/tests/compact_output.rs

@@ -283,6 +283,16 @@ fn compact_subcommand_json_help_fails_fast_when_stdin_closed() {
             .contains("claw compact"),
         "message should name compact: {parsed}"
     );
+    // #749: hint must be non-empty (was null before fix — same class as #738/#745/#746)
+    let hint = parsed["hint"].as_str().unwrap_or("");
+    assert!(
+        !hint.is_empty(),
+        "compact interactive-only JSON must have non-empty hint (#749); got: {parsed}"
+    );
+    assert!(
+        hint.contains("/compact") || hint.contains("--resume"),
+        "hint should mention /compact or --resume: {hint}"
+    );
 
     fs::remove_dir_all(&workspace).expect("workspace cleanup should succeed");
 }

rust/crates/rusty-claude-cli/tests/output_format_contract.rs

@@ -663,6 +663,22 @@ fn doctor_and_resume_status_emit_json_when_requested() {
     assert!(boot_preflight["boot_preflight"]["repo"]["exists"].is_boolean());
     assert!(boot_preflight["boot_preflight"]["mcp_startup"]["eligible"].is_boolean());
     assert!(boot_preflight["boot_preflight"]["required_binaries"].is_array());
+    // #736: details[] must be {key,value} objects with non-null values;
+    // regression guard for the double-space separator fix on boot_preflight prose strings.
+    let bp_details = boot_preflight["details"]
+        .as_array()
+        .expect("boot_preflight details must be array");
+    for entry in bp_details {
+        assert!(
+            entry["key"].is_string(),
+            "boot_preflight detail entry missing string key: {entry:?}"
+        );
+        assert!(
+            !entry["value"].is_null(),
+            "boot_preflight detail entry has null value (prose-splitter failed): key={:?}",
+            entry["key"]
+        );
+    }
 
     let sandbox = checks
         .iter()
@@ -1340,6 +1356,422 @@ fn diff_json_has_status_and_result_field_702() {
             .is_some(),
         "diff JSON must have working_directory field (#710)"
     );
+    // #740: diff JSON changed_file_count contract: numeric in git repos, absent for no_git_repo
+    let result_str = parsed.get("result").and_then(|v| v.as_str());
+    if result_str == Some("no_git_repo") {
+        // Non-git repos don't emit changed_file_count
+        assert!(
+            parsed.get("changed_file_count").is_none(),
+            "diff JSON should not have changed_file_count for no_git_repo (#733)"
+        );
+    } else {
+        // Git repos must emit numeric changed_file_count
+        assert!(
+            parsed
+                .get("changed_file_count")
+                .and_then(|v| v.as_u64())
+                .is_some(),
+            "diff JSON changed_file_count must be numeric in git repos (#733)"
+        );
+    }
+}
+
+#[test]
+fn diff_json_changed_file_count_deduplication_733() {
+    // #733/#742: changed_file_count must be numeric in a git repo, be 0 for clean,
+    // and deduplicate staged+unstaged edits to the same file (1 file changed = count 1).
+    use std::process::Command;
+    let root = unique_temp_dir("diff-changed-dedup");
+    fs::create_dir_all(&root).expect("temp dir");
+
+    // git init + identity config + initial commit
+    Command::new("git")
+        .args(["init"])
+        .current_dir(&root)
+        .output()
+        .expect("git init");
+    Command::new("git")
+        .args(["config", "user.email", "test@claw.test"])
+        .current_dir(&root)
+        .output()
+        .expect("git config email");
+    Command::new("git")
+        .args(["config", "user.name", "Test"])
+        .current_dir(&root)
+        .output()
+        .expect("git config name");
+    fs::write(root.join("tracked.txt"), b"v1").expect("write tracked");
+    Command::new("git")
+        .args(["add", "tracked.txt"])
+        .current_dir(&root)
+        .output()
+        .expect("git add");
+    Command::new("git")
+        .args(["commit", "-m", "init"])
+        .current_dir(&root)
+        .output()
+        .expect("git commit");
+
+    // Clean state: changed_file_count must be 0
+    let bin = env!("CARGO_BIN_EXE_claw");
+    let clean = Command::new(bin)
+        .current_dir(&root)
+        .args(["--output-format", "json", "diff"])
+        .output()
+        .expect("claw diff clean");
+    let clean_json: serde_json::Value =
+        serde_json::from_slice(&clean.stdout).expect("diff clean stdout must be valid JSON");
+    assert_eq!(clean_json["result"], "clean", "fresh repo must be clean");
+    assert_eq!(
+        clean_json["changed_file_count"].as_u64(),
+        Some(0),
+        "clean repo must have changed_file_count:0 (#733)"
+    );
+
+    // Make a staged edit AND an unstaged edit to the same file
+    fs::write(root.join("tracked.txt"), b"v2").expect("staged write");
+    Command::new("git")
+        .args(["add", "tracked.txt"])
+        .current_dir(&root)
+        .output()
+        .expect("git add staged");
+    fs::write(root.join("tracked.txt"), b"v3").expect("unstaged write");
+
+    // Dirty state: same file appears in staged+unstaged — must deduplicate to count 1
+    let dirty = Command::new(bin)
+        .current_dir(&root)
+        .args(["--output-format", "json", "diff"])
+        .output()
+        .expect("claw diff dirty");
+    let dirty_json: serde_json::Value =
+        serde_json::from_slice(&dirty.stdout).expect("diff dirty stdout must be valid JSON");
+    assert_eq!(
+        dirty_json["result"], "changes",
+        "dirty repo must have result:changes (#733)"
+    );
+    assert_eq!(
+        dirty_json["changed_file_count"].as_u64(),
+        Some(1),
+        "staged+unstaged edits to same file must deduplicate to changed_file_count:1 (#733)"
+    );
+}
+
+#[test]
+fn prompt_no_arg_json_error_kind_750() {
+    // #751/#750: `claw prompt --output-format json` with no prompt argument must emit
+    // error_kind:"missing_prompt" and a non-empty hint. Before #750 it returned
+    // error_kind:"unknown" + hint:null.
+    use std::process::Command;
+    let root = unique_temp_dir("prompt-no-arg");
+    fs::create_dir_all(&root).expect("temp dir");
+    let bin = env!("CARGO_BIN_EXE_claw");
+
+    let output = Command::new(bin)
+        .current_dir(&root)
+        .args(["--output-format", "json", "prompt"])
+        .output()
+        .expect("claw prompt should run");
+    assert!(
+        !output.status.success(),
+        "claw prompt with no arg must exit non-zero"
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let stderr = String::from_utf8_lossy(&output.stderr)
+        .lines()
+        .filter(|l| l.starts_with('{'))
+        .collect::<Vec<_>>()
+        .join("");
+    let raw = if stdout.trim().starts_with('{') {
+        stdout.trim().to_string()
+    } else {
+        stderr
+    };
+    let parsed: serde_json::Value = serde_json::from_str(&raw).unwrap_or_else(|_| {
+        panic!("claw prompt (no arg) --output-format json must emit valid JSON; got: {raw}")
+    });
+    assert_eq!(
+        parsed["error_kind"], "missing_prompt",
+        "claw prompt no-arg must have error_kind:missing_prompt (#750); got: {parsed}"
+    );
+    let hint = parsed["hint"].as_str().unwrap_or("");
+    assert!(
+        !hint.is_empty(),
+        "claw prompt no-arg hint must be non-empty (#750)"
+    );
+    assert!(
+        hint.contains("claw prompt") || hint.contains("echo"),
+        "hint should mention 'claw prompt' or 'echo': {hint}"
+    );
+}
+
+#[test]
+fn flag_value_errors_have_error_kind_and_hint_756() {
+    // #756: missing/invalid flag-value errors must emit typed error_kind + non-null hint.
+    // Before #756: all returned error_kind:"unknown" + hint:null.
+    use std::process::Command;
+    let root = unique_temp_dir("flag-value-errors");
+    fs::create_dir_all(&root).expect("temp dir");
+    let bin = env!("CARGO_BIN_EXE_claw");
+
+    // Case 1: --reasoning-effort with invalid value
+    let out = Command::new(bin)
+        .current_dir(&root)
+        .args(["--output-format", "json", "--reasoning-effort", "HIGH"])
+        .output()
+        .expect("claw --reasoning-effort HIGH should run");
+    assert!(
+        !out.status.success(),
+        "invalid reasoning-effort must exit non-zero"
+    );
+    let raw = String::from_utf8_lossy(&out.stderr)
+        .lines()
+        .filter(|l| l.starts_with('{'))
+        .collect::<Vec<_>>()
+        .join("");
+    let parsed: serde_json::Value = serde_json::from_str(&raw)
+        .unwrap_or_else(|_| panic!("invalid --reasoning-effort must emit JSON; got: {raw}"));
+    assert_eq!(
+        parsed["error_kind"], "invalid_flag_value",
+        "invalid --reasoning-effort must be invalid_flag_value (#756): {parsed}"
+    );
+    assert!(
+        parsed["hint"].as_str().map_or(false, |h| h.contains("low")
+            || h.contains("medium")
+            || h.contains("high")),
+        "hint must mention valid values (#756): {parsed}"
+    );
+
+    // Case 2: --model flag with missing value (trailing flag)
+    let out2 = Command::new(bin)
+        .current_dir(&root)
+        .args(["--output-format", "json", "--model"])
+        .output()
+        .expect("claw --model (no value) should run");
+    assert!(
+        !out2.status.success(),
+        "missing --model value must exit non-zero"
+    );
+    let raw2 = String::from_utf8_lossy(&out2.stderr)
+        .lines()
+        .filter(|l| l.starts_with('{'))
+        .collect::<Vec<_>>()
+        .join("");
+    let parsed2: serde_json::Value = serde_json::from_str(&raw2)
+        .unwrap_or_else(|_| panic!("missing --model value must emit JSON; got: {raw2}"));
+    assert_eq!(
+        parsed2["error_kind"], "missing_flag_value",
+        "missing --model value must be missing_flag_value (#756): {parsed2}"
+    );
+    assert!(
+        parsed2["hint"].as_str().map_or(false, |h| !h.is_empty()),
+        "missing --model hint must be non-empty (#756): {parsed2}"
+    );
+}
+
+#[test]
+fn short_p_flag_swallows_no_flags_755() {
+    // #755: `claw -p hello --output-format json` must parse --output-format json
+    // as a flag rather than swallowing it as part of the prompt. Before #755,
+    // args[index+1..].join(" ") consumed all remaining tokens into the prompt.
+    // After #755, -p consumes exactly one token and remaining flags are parsed.
+    // We verify by checking that the envelope IS JSON (meaning --output-format json
+    // was interpreted as a flag, not literal prompt text).
+    use std::process::Command;
+    let root = unique_temp_dir("short-p-flags");
+    fs::create_dir_all(&root).expect("temp dir");
+    let bin = env!("CARGO_BIN_EXE_claw");
+
+    // -p hello --output-format json: with no credentials, should fail with
+    // missing_credentials (not missing_prompt), proving --output-format json was parsed.
+    let output = Command::new(bin)
+        .current_dir(&root)
+        .args(["-p", "hello", "--output-format", "json"])
+        .env_remove("ANTHROPIC_API_KEY")
+        .env_remove("ANTHROPIC_AUTH_TOKEN")
+        .output()
+        .expect("claw -p should run");
+    assert!(
+        !output.status.success(),
+        "claw -p hello --output-format json must exit non-zero (no credentials)"
+    );
+    let raw = String::from_utf8_lossy(&output.stderr)
+        .lines()
+        .filter(|l| l.starts_with('{'))
+        .collect::<Vec<_>>()
+        .join("");
+    // Must be valid JSON (i.e. --output-format json was parsed, not swallowed)
+    let parsed: serde_json::Value = serde_json::from_str(&raw).unwrap_or_else(|_| {
+        panic!("--output-format json must be parsed as a flag, not prompt text; stderr: {raw}")
+    });
+    assert_eq!(
+        parsed["error_kind"], "missing_credentials",
+        "flags after -p prompt text must be parsed normally (#755); got: {parsed}"
+    );
+
+    // Also verify -p --model bogus is rejected as missing_prompt (flag-as-prompt guard)
+    let output2 = Command::new(bin)
+        .current_dir(&root)
+        .args(["--output-format", "json", "-p", "--model", "sonnet"])
+        .output()
+        .expect("claw -p flag-as-prompt should run");
+    let raw2 = String::from_utf8_lossy(&output2.stderr)
+        .lines()
+        .filter(|l| l.starts_with('{'))
+        .collect::<Vec<_>>()
+        .join("");
+    let parsed2: serde_json::Value = serde_json::from_str(&raw2)
+        .unwrap_or_else(|_| panic!("claw -p --model must emit JSON; got: {raw2}"));
+    assert_eq!(
+        parsed2["error_kind"], "missing_prompt",
+        "flag-like token after -p must be rejected as missing_prompt (#755): {parsed2}"
+    );
+    assert!(
+        parsed2["hint"].as_str().map_or(false, |h| !h.is_empty()),
+        "missing_prompt hint must be non-empty (#755)"
+    );
+}
+
+#[test]
+fn short_p_flag_no_arg_json_error_kind_753() {
+    // #753: `claw --output-format json -p` (no prompt) must emit error_kind:"missing_prompt"
+    // and non-empty hint. Before #753 it returned error_kind:"unknown" + hint:null.
+    // Parity with #750 which fixed the explicit `prompt` verb.
+    use std::process::Command;
+    let root = unique_temp_dir("short-p-no-arg");
+    fs::create_dir_all(&root).expect("temp dir");
+    let bin = env!("CARGO_BIN_EXE_claw");
+
+    let output = Command::new(bin)
+        .current_dir(&root)
+        .args(["--output-format", "json", "-p"])
+        .output()
+        .expect("claw -p should run");
+    assert!(
+        !output.status.success(),
+        "claw -p with no arg must exit non-zero"
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let raw = if stdout.trim().starts_with('{') {
+        stdout.trim().to_string()
+    } else {
+        String::from_utf8_lossy(&output.stderr)
+            .lines()
+            .filter(|l| l.starts_with('{'))
+            .collect::<Vec<_>>()
+            .join("")
+    };
+    let parsed: serde_json::Value = serde_json::from_str(&raw).unwrap_or_else(|_| {
+        panic!("claw -p (no arg) --output-format json must emit valid JSON; got: {raw}")
+    });
+    assert_eq!(
+        parsed["error_kind"], "missing_prompt",
+        "claw -p no-arg must have error_kind:missing_prompt (#753); got: {parsed}"
+    );
+    let hint = parsed["hint"].as_str().unwrap_or("");
+    assert!(
+        !hint.is_empty(),
+        "claw -p no-arg hint must be non-empty (#753)"
+    );
+    assert!(
+        hint.contains("claw -p") || hint.contains("claw prompt"),
+        "hint should mention 'claw -p' or 'claw prompt': {hint}"
+    );
+}
+
+#[test]
+fn bare_slash_command_hint_745() {
+    // #747/#745: claw <slash-cmd> --output-format json must return non-null hint.
+    // bare_slash_command_guidance() previously had no \n so split_error_hint returned hint:null.
+    use std::process::Command;
+    let root = unique_temp_dir("bare-slash-hint");
+    fs::create_dir_all(&root).expect("temp dir");
+    let bin = env!("CARGO_BIN_EXE_claw");
+
+    // issue and pr are non-resume-supported; commit is resume-supported.
+    // All must emit non-null hint in their interactive_only error envelope.
+    for cmd in &["issue", "pr", "commit"] {
+        let output = Command::new(bin)
+            .current_dir(&root)
+            .args(["--output-format", "json", cmd])
+            .env("ANTHROPIC_API_KEY", "test")
+            .output()
+            .expect("claw should run");
+        assert!(
+            !output.status.success(),
+            "claw {cmd} outside REPL must exit non-zero"
+        );
+        // Error envelope is on stderr (type:error path) or stdout
+        let stderr = String::from_utf8_lossy(&output.stderr)
+            .lines()
+            .filter(|l| l.starts_with('{'))
+            .collect::<Vec<_>>()
+            .join("");
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        let raw = if !stderr.is_empty() {
+            stderr
+        } else {
+            stdout.trim().to_string()
+        };
+        let parsed: serde_json::Value = serde_json::from_str(&raw)
+            .unwrap_or_else(|_| panic!("claw {cmd} must emit JSON; got: {raw}"));
+        assert_eq!(
+            parsed["error_kind"], "interactive_only",
+            "claw {cmd} must have error_kind:interactive_only (#745)"
+        );
+        let hint = parsed["hint"].as_str().unwrap_or("");
+        assert!(
+            !hint.is_empty(),
+            "claw {cmd} --output-format json hint must be non-empty (#745); got null"
+        );
+    }
+}
+
+#[test]
+fn config_unsupported_section_json_hint_741() {
+    // #744/#741: claw config <unknown-section> --output-format json must return
+    // error_kind:unsupported_config_section with a non-null hint and supported_sections[].
+    // This is the regression guard for #741 (hint was null before fix).
+    use std::process::Command;
+    let root = unique_temp_dir("config-unsupported-section");
+    fs::create_dir_all(&root).expect("temp dir");
+    let bin = env!("CARGO_BIN_EXE_claw");
+
+    for section in &["list", "show", "bogus", "help"] {
+        let output = Command::new(bin)
+            .current_dir(&root)
+            .args(["--output-format", "json", "config", section])
+            .output()
+            .expect("claw config should run");
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        let parsed: serde_json::Value = serde_json::from_str(stdout.trim()).unwrap_or_else(|_| {
+            panic!("claw config {section} --output-format json must emit valid JSON; got: {stdout}")
+        });
+        assert_eq!(
+            parsed["kind"], "config",
+            "config {section} JSON must have kind:config (#741)"
+        );
+        assert_eq!(
+            parsed["status"], "error",
+            "config {section} must return status:error (#741)"
+        );
+        assert_eq!(
+            parsed["error_kind"], "unsupported_config_section",
+            "config {section} must return error_kind:unsupported_config_section (#741)"
+        );
+        // #741: hint must be a non-empty string (was null before fix)
+        let hint = parsed["hint"].as_str().unwrap_or("");
+        assert!(
+            !hint.is_empty(),
+            "config {section} --output-format json hint must be non-empty (#741)"
+        );
+        // supported_sections must still be present and non-empty
+        assert!(
+            parsed["supported_sections"]
+                .as_array()
+                .map_or(false, |a| !a.is_empty()),
+            "config {section} JSON must include supported_sections (#741)"
+        );
+    }
 }
 
 #[test]