feat(capabilities): turn cass capabilities into a first-stop agent self-description

Reframes `cass capabilities --json` from "feature discovery" to a
single self-describing entry point that hands an agent everything it
needs to drive cass without reading help text or external docs.

Payload additions (the schema is additive — old keys are preserved):

- `workflows[]` — named recipes (`bounded-search`, etc.) showing the
  canonical command sequence for an intent, plus the exit codes and
  output shapes a caller should branch on.
- `mistake_recoveries[]` — paired "common mistake" → "what to do
  next" entries, lifted from the existing `get_common_mistakes`
  table so an agent can recover without re-querying.
- `commands[]` — full command list with `name`, `summary`,
  `arguments[]` (positional vs option, required, value_type,
  default, possible_values), and `subcommands[]` for two-level
  paths like `robot-docs guide`.
- `global_flags[]` — typed schemas for `--robot-help`, `--color`,
  `--no-color`, `--quiet`, `--max-tokens`, etc., with `value_type`
  ("enum" | "string" | …) and defaults so callers don't guess.
- `exit_codes[]` — every exit code the binary can return, with
  `meaning`, `retryable` ("yes" | "no" | "after-recovery"), and
  `agent_action` text the caller can act on (e.g. exit 2 → "Fix
  argv and retry"; exit 15 → semantic-fallback guidance).
- `env_vars[]` — `CASS_DATA_DIR`, `CASS_OUTPUT_FORMAT`,
  `CASS_TRACE_FILE`, etc. with default values.
- New feature flag `self_describing_capabilities` advertises the
  upgrade so callers can detect it.

Argv recovery improvements (in `heuristic_parse_recovery` /
`normalize_args`):

- New `CANONICAL_TOP_LEVEL_COMMANDS` table backs a Levenshtein
  typo corrector (`closest_top_level_command`) so a misspelt
  subcommand like `cass searh` is rewritten to `cass search` with
  a structured correction note rather than re-routing through the
  generic "implicit search" fallback. Distance ≤2; minimum length 3.
- `cass robot-docs` (no subtopic) now defaults to `robot-docs guide`
  with a recorded correction; redundant `--robot` / `--json` flags
  on robot-docs are stripped (those outputs are already
  machine-readable).

Surface adjustments:

- `Commands::Capabilities` doc string updated from "Discover
  features, versions, and limits" to "First-stop agent
  self-description: workflows, mistake recoveries, commands,
  flags, env vars, exit codes, and limits".
- `print_robot_help` section header renamed
  `Subcommands:` → `Core subcommands:` so the help output
  matches the new `commands[]` framing.
- README + docs/ROBOT_MODE.md prose updated to the new framing.

Tests + goldens:

- `capabilities_are_self_describing_for_agents` exercises every
  new section: features list contains the new flag, global_flags
  has typed entries, commands include arguments/subcommands,
  exit_codes include retryability + agent_action, env_vars cover
  the documented list, and the `bounded-search` workflow is
  present.
- New helper `recommended_command(json, id)` for asserting
  recommended-command shape across cli_robot tests.
- Goldens regenerated:
    - `tests/golden/robot/capabilities.json.golden` (full payload,
      ~2882 lines)
    - `tests/golden/robot/capabilities_shape.json.golden` (new
      shape-only snapshot — order-insensitive structure)
    - `tests/golden/robot/introspect{,_shape}.json.golden`
    - `tests/golden/robot/diag*.json.golden` (api_version field
      threaded through)
    - `tests/golden/robot_docs/{commands,examples,guide,robot_help,schemas}.txt.golden`
- `tests/golden_robot_docs.rs` / `tests/golden_robot_json.rs`
  drivers refreshed for the new sections.

Drive-by formatting:

- `src/connectors/codex.rs`: re-ordered the `super::*` import list
  alphabetically (rustfmt drift; no behaviour change).
- `src/ui/app.rs`: collapsed three multi-line method-chain Paragraph
  styles per rustfmt; also a single `paragraph.style(...).render(...)`
  flattened. No behaviour change.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Dicklesworthstone

README.md

@@ -727,9 +727,9 @@ This cross-pollination of knowledge across different AI agents is transformative
 `cass` teaches agents how to use it—no external documentation required:
 
 ```bash
-# Quick capability check: what features exist?
+# First-stop capability contract for agents
 cass capabilities --json
-# → {"features": ["json_output", "cursor_pagination", "highlight_matches", ...], "connectors": [...], "limits": {...}}
+# → {"version": "...", "workflows": [...], "mistake_recoveries": [...], "commands": [...], "exit_codes": [...], "env_vars": [...]}
 
 # Full API schema with argument types, defaults, and response shapes
 cass introspect --json
@@ -1158,7 +1158,7 @@ cass introspect --json
  cass expand /path/to/session.jsonl -n 42 -C 3 --json
 
  # Learn the full API
- cass capabilities --json # Feature discovery
+ cass capabilities --json # First-stop agent self-description
  cass robot-docs guide # LLM-optimized docs
 
  Why Use It
@@ -2425,7 +2425,7 @@ cass pack "query" --robot --max-tokens 4000 --max-evidence 8 --max-sessions 3 --
 # Inspection & Health
 cass status --json                    # Quick health snapshot
 cass health                           # Minimal pre-flight check (<50ms)
-cass capabilities --json              # Feature discovery
+cass capabilities --json              # First-stop agent self-description
 cass introspect --json                # Full API schema
 cass context /path/to/session --json  # Find related sessions
 cass view /path/to/file -n 42 --json  # View source at line
@@ -2458,7 +2458,7 @@ cass completions bash > ~/.bash_completion.d/cass
 | `pack --robot` | Deterministic cited answer packs for agent/human handoffs; reports health, freshness, privacy, and warnings |
 | `status` / `state` | Health snapshot: index freshness, DB stats, recommended action |
 | `health` | Minimal health check (<50ms), exit 0=healthy, 1=unhealthy |
-| `capabilities` | Discover features, versions, limits (for agent introspection) |
+| `capabilities` | First-stop agent self-description: workflow recipes, mistake recoveries, commands, global flags, exit codes, env vars, and limits |
 | `introspect` | Full API schema: commands, arguments, response shapes |
 | `sessions [--workspace DIR] [--current]` | Discover recent session files for follow-up actions |
 | `context <path>` | Find related sessions by workspace, day, or agent |

docs/ROBOT_MODE.md

@@ -27,7 +27,7 @@ Updated: 2026-04-22
 | Truncate content | `--max-content-length 400` or budgeted `--max-tokens 200` |
 | Metadata | `--robot-meta` (elapsed_ms, cache stats, index freshness, cursor, warnings) |
 | Health snapshot | `cass state --json` (alias `status`) |
-| Capabilities | `cass capabilities --json` |
+| Capabilities | `cass capabilities --json` (first-stop workflows, mistake recoveries, commands, flags, env vars, exit codes, limits) |
 | Introspection | `cass introspect --json` (schemas for responses) |
 
 ## Search asset contract
@@ -177,4 +177,4 @@ cass search "panic" --robot --fields minimal --robot-meta \
 - 0.1.30: `_meta.index_freshness` + `_warning` in search robot output; capabilities limits enforced; cursor/request-id exposed.
 
 ---
-For deeper schemas: `cass introspect --json` and `cass capabilities --json`.
+For first-stop discovery use `cass capabilities --json`; for deeper response schemas use `cass introspect --json`.

src/connectors/codex.rs

@@ -5,8 +5,8 @@ use anyhow::Result;
 use serde_json::Value;
 
 use super::{
-    parse_timestamp, reindex_messages, Connector, DetectionResult, DiscoveredSourceFile,
-    NormalizedConversation, NormalizedMessage, ScanContext,
+    Connector, DetectionResult, DiscoveredSourceFile, NormalizedConversation, NormalizedMessage,
+    ScanContext, parse_timestamp, reindex_messages,
 };
 
 const MAX_INDEXED_TOOL_OUTPUT_CHARS: usize = 128 * 1024;