@wrongstack/cli 0.317.2 → 0.319.0

package/dist/chunk-P2OKBDCH.js

@@ -0,0 +1,1166 @@
+import {
+  renderAuthLocalHelpToString
+} from "./chunk-2VMJ3E5Z.js";
+
+// src/subcommands/handlers/per-subcommand-help.ts
+import { color as color3 } from "@wrongstack/core/utils";
+
+// src/subcommands/handlers/bench-run-help.ts
+import { color } from "@wrongstack/core/utils";
+var BENCH_RUN_FLAGS = [
+  // -- Suite selection ------------------------------------------------
+  {
+    name: "suite",
+    flag: "--suite <id>",
+    description: "Benchmark suite id (`polyglot` or `swebench`).",
+    group: "suite",
+    kind: "value",
+    defaultValue: "polyglot"
+  },
+  {
+    name: "polyglot-dir",
+    flag: "--polyglot-dir <path>",
+    description: "Path to the Aider polyglot dataset (required when --suite polyglot).",
+    group: "suite",
+    kind: "value",
+    required: true
+  },
+  {
+    name: "languages",
+    flag: "--languages <csv>",
+    description: "Comma-separated language list to filter the polyglot suite (e.g. `python,go`).",
+    group: "suite",
+    kind: "value"
+  },
+  {
+    name: "dataset-dir",
+    flag: "--dataset-dir <path>",
+    description: "Path to the SWE-bench Verified dataset (optional, defaults to the official cache).",
+    group: "suite",
+    kind: "value"
+  },
+  {
+    name: "docker",
+    flag: "--docker",
+    description: "Enable the SWE-bench Docker runtime (required for live grading).",
+    group: "suite",
+    kind: "boolean"
+  },
+  // -- Model matrix ---------------------------------------------------
+  {
+    name: "models",
+    flag: "--models <config>",
+    description: "Path to the model-cells config (JSON).",
+    group: "models",
+    kind: "value",
+    defaultValue: "bench.config.json"
+  },
+  // -- Run control ----------------------------------------------------
+  {
+    name: "limit",
+    flag: "--limit <N>",
+    description: "Cap the number of tasks per cell (useful for smoke tests).",
+    group: "control",
+    kind: "value"
+  },
+  {
+    name: "out",
+    flag: "--out <dir>",
+    description: "Base directory for run output (each run gets a timestamped subdir).",
+    group: "control",
+    kind: "value",
+    defaultValue: "bench-results"
+  },
+  {
+    name: "concurrency",
+    flag: "--concurrency <N>",
+    description: "Override the per-cell concurrency from the model config.",
+    group: "control",
+    kind: "value"
+  }
+];
+var BENCH_RUN_BOOLEAN_FLAG_NAMES = BENCH_RUN_FLAGS.filter(
+  (f) => f.kind === "boolean"
+).map((f) => f.name);
+var BENCH_RUN_VALUE_FLAG_NAMES = BENCH_RUN_FLAGS.filter(
+  (f) => f.kind === "value"
+).map((f) => f.name);
+var BENCH_RUN_FLAG_COLUMN_WIDTH = 28;
+function renderBenchRunHelpToString() {
+  const lines = [
+    color.bold("wstack bench run \u2014 execute a benchmark suite across a model matrix"),
+    color.dim("  Runs a benchmark suite (polyglot or swebench) across every model cell"),
+    color.dim("  in the config. Output is a per-run directory with `report.md`, JSON"),
+    color.dim("  artifacts, and (for swebench) per-cell predictions for the official"),
+    color.dim("  harness."),
+    "",
+    color.bold("Usage"),
+    `  ${buildUsageLine()}`,
+    "",
+    color.bold("Flags"),
+    ...buildFlagBlock(),
+    "",
+    color.dim(
+      "See also: wstack bench list (show available suites + cells); wstack bench report <dir>"
+    )
+  ];
+  return lines.join("\n") + "\n";
+}
+function buildUsageLine() {
+  const parts = ["wstack bench run"];
+  for (const f of BENCH_RUN_FLAGS) {
+    if (f.kind === "value") {
+      parts.push(`[${f.flag}]`);
+    } else {
+      parts.push(`[${f.flag}]`);
+    }
+  }
+  return parts.join(" ");
+}
+function buildFlagBlock() {
+  const rows = [];
+  let currentGroup;
+  for (const f of BENCH_RUN_FLAGS) {
+    if (f.group !== currentGroup) {
+      const header = f.group === "suite" ? "Suite selection:" : f.group === "models" ? "Model matrix:" : "Run control:";
+      rows.push(color.dim(`  ${header}`));
+      currentGroup = f.group;
+    }
+    const paddedFlag = f.flag.padEnd(BENCH_RUN_FLAG_COLUMN_WIDTH, " ");
+    let desc = f.description;
+    if (f.required) {
+      desc = desc + " " + color.bold("(required)");
+    } else if (f.defaultValue !== void 0) {
+      desc = desc + " " + color.dim(`(default: ${f.defaultValue})`);
+    }
+    rows.push(`  ${paddedFlag} ${desc}`);
+  }
+  return rows;
+}
+
+// src/subcommands/handlers/models-add-help.ts
+import { color as color2 } from "@wrongstack/core/utils";
+var MODELS_ADD_FLAGS = [
+  // -- Identity --------------------------------------------------------
+  {
+    name: "provider",
+    flag: "--provider <id>",
+    description: "Provider id the model belongs to (defaults to the saved alias).",
+    group: "identity",
+    kind: "value"
+  },
+  {
+    name: "name",
+    flag: "--name <name>",
+    description: "Human-readable display name (defaults to <mid>).",
+    group: "identity",
+    kind: "value"
+  },
+  // -- Capabilities ---------------------------------------------------
+  {
+    name: "max-context",
+    flag: "--max-context <N>",
+    description: "Context window in tokens (e.g. 200000 for 200k, or `128k`).",
+    group: "capabilities",
+    kind: "value"
+  },
+  {
+    name: "max-output",
+    flag: "--max-output <N>",
+    description: "Max output tokens per request.",
+    group: "capabilities",
+    kind: "value"
+  },
+  {
+    name: "tools",
+    flag: "--tools / --no-tools",
+    description: "Toggle tool/function-calling support.",
+    group: "capabilities",
+    kind: "boolean"
+  },
+  {
+    name: "vision",
+    flag: "--vision / --no-vision",
+    description: "Toggle image-input support.",
+    group: "capabilities",
+    kind: "boolean"
+  },
+  {
+    name: "reasoning",
+    flag: "--reasoning / --no-reasoning",
+    description: "Mark the model as a reasoning model.",
+    group: "capabilities",
+    kind: "boolean"
+  },
+  {
+    name: "streaming",
+    flag: "--streaming / --no-streaming",
+    description: "Toggle streaming response support.",
+    group: "capabilities",
+    kind: "boolean"
+  },
+  {
+    name: "json-mode",
+    flag: "--json-mode",
+    description: "Mark the model as supporting native JSON output.",
+    group: "capabilities",
+    kind: "boolean"
+  }
+];
+var MODELS_ADD_BOOLEAN_FLAG_NAMES = MODELS_ADD_FLAGS.filter(
+  (f) => f.kind === "boolean"
+).map((f) => f.name);
+var MODELS_ADD_VALUE_FLAG_NAMES = MODELS_ADD_FLAGS.filter(
+  (f) => f.kind === "value"
+).map((f) => f.name);
+var MODELS_ADD_FLAG_COLUMN_WIDTH = 30;
+function renderModelsAddHelpToString() {
+  const lines = [
+    color2.bold("wstack models add <mid> \u2014 register a custom model"),
+    color2.dim("  Add or override a custom model (for self-hosted endpoints, fine-tuned"),
+    color2.dim("  weights, or models not in the public models.dev catalog). The flags are"),
+    color2.dim("  organized into two groups: identity (`--provider`, `--name`) and"),
+    color2.dim("  capabilities (`--max-context`, `--tools`, `--vision`, etc.)."),
+    "",
+    color2.bold("Usage"),
+    `  ${buildUsageLine2()}`,
+    "",
+    color2.bold("Flags"),
+    ...buildFlagBlock2(),
+    "",
+    color2.dim("See also: wstack models list (verify the entry); wstack models remove")
+  ];
+  return lines.join("\n") + "\n";
+}
+function buildUsageLine2() {
+  const parts = ["wstack models add <mid>"];
+  for (const f of MODELS_ADD_FLAGS) {
+    if (f.kind === "value") {
+      parts.push(`[${f.flag}]`);
+    } else {
+      parts.push(`[${f.flag}]`);
+    }
+  }
+  return parts.join(" ");
+}
+function buildFlagBlock2() {
+  const rows = [];
+  let currentGroup;
+  for (const f of MODELS_ADD_FLAGS) {
+    if (f.group !== currentGroup) {
+      const header = f.group === "identity" ? "Identity:" : "Capabilities:";
+      rows.push(color2.dim(`  ${header}`));
+      currentGroup = f.group;
+    }
+    const paddedFlag = f.flag.padEnd(MODELS_ADD_FLAG_COLUMN_WIDTH, " ");
+    rows.push(`  ${paddedFlag} ${f.description}`);
+  }
+  return rows;
+}
+
+// src/subcommands/handlers/per-subcommand-deep-help-table.ts
+var deepHelpTable = {
+  // -- mcp -----------------------------------------------------------------
+  "mcp:add": {
+    name: "mcp:add",
+    title: "wstack mcp add <name> \u2014 register a built-in MCP server",
+    description: "Register a built-in MCP server by alias (e.g. `github`, `playwright`) and write the entry to the global config. The server is added in `disabled` state by default; pass `--enable` to register it active immediately.",
+    usage: "wstack mcp add <name> [--enable]",
+    subcommands: [
+      {
+        name: "<name>",
+        description: "The built-in server alias (run `wstack mcp add` for the list)."
+      },
+      {
+        name: "--enable / -e",
+        description: "Register the server enabled (default: disabled until you opt in)."
+      }
+    ],
+    seeAlso: "wstack mcp list (verify the entry landed); wstack mcp remove"
+  },
+  "mcp:remove": {
+    name: "mcp:remove",
+    title: "wstack mcp remove <name> \u2014 unregister an MCP server",
+    description: "Unregister an MCP server by alias. Removes the entry from the global config; the server process is not killed (REPL restart required to fully tear down the running process).",
+    usage: "wstack mcp remove <name>",
+    subcommands: [{ name: "<name>", description: "The server alias to unregister." }]
+  },
+  // -- plugin --------------------------------------------------------------
+  "plugin:add": {
+    name: "plugin:add",
+    title: "wstack plugin add <spec> \u2014 install a tool plugin",
+    description: "Add a tool plugin by specifier (npm package name) or official alias (`telegram`, `lsp`). Pass `--disabled` to install the plugin but leave it off until you explicitly enable it. The plugin requires a restart of the wrongstack process to take effect.",
+    usage: "wstack plugin add <spec|alias> [--disabled]",
+    subcommands: [
+      {
+        name: "<spec|alias>",
+        description: "NPM specifier (e.g. `@org/wrongstack-x`) or official alias."
+      },
+      {
+        name: "--disabled",
+        description: "Install the plugin but leave it disabled until you enable it."
+      }
+    ],
+    seeAlso: "wstack plugin official (list the official registry); wstack plugin enable"
+  },
+  "plugin:remove": {
+    name: "plugin:remove",
+    title: "wstack plugin remove <spec> \u2014 uninstall a tool plugin",
+    description: "Remove a tool plugin from the config. The plugin requires a restart of the wrongstack process to take effect. Aliases: `rm`, `uninstall`.",
+    usage: "wstack plugin remove <spec|alias>",
+    subcommands: [
+      { name: "<spec|alias>", description: "The specifier or official alias to remove." }
+    ]
+  },
+  "plugin:enable": {
+    name: "plugin:enable",
+    title: "wstack plugin enable <spec> \u2014 re-enable a previously-disabled plugin",
+    description: "Re-enable a plugin that was installed with `--disabled` or toggled off with `wstack plugin disable`. Requires a restart.",
+    usage: "wstack plugin enable <spec|alias>",
+    subcommands: [
+      { name: "<spec|alias>", description: "The specifier or official alias to enable." }
+    ]
+  },
+  "plugin:disable": {
+    name: "plugin:disable",
+    title: "wstack plugin disable <spec> \u2014 temporarily disable a plugin",
+    description: "Temporarily disable a plugin without removing it from the config. Use `wstack plugin enable` to re-enable. Requires a restart.",
+    usage: "wstack plugin disable <spec|alias>",
+    subcommands: [
+      { name: "<spec|alias>", description: "The specifier or official alias to disable." }
+    ]
+  },
+  "plugin:toggle": {
+    name: "plugin:toggle",
+    title: "wstack plugin toggle <name> \u2014 toggle an audit-list plugin row",
+    description: "Toggle one built-in audit-list plugin by its runtime name. Default-active plugins are disabled by writing `{ enabled: false }` overrides; enabling them again removes that override. All bundled audit-list rows are toggleable; future non-toggleable rows are reported as locked. Requires a restart for loaded plugin code to change in the current session.",
+    usage: "wstack plugin toggle <name>",
+    subcommands: [
+      { name: "<name>", description: "Audit-list runtime name, e.g. `format-on-save`." }
+    ],
+    seeAlso: "wstack plugin report (see effective state and toggle policy)"
+  },
+  "plugin:report": {
+    name: "plugin:report",
+    title: "wstack plugin report \u2014 show the plugin audit table",
+    description: "Print the built-in plugin audit table. Each row shows effective state, whether that state came from config or default boot behavior, risk, and the toggle policy for that row.",
+    usage: "wstack plugin report (alias: wstack plugin audit)",
+    seeAlso: "wstack plugin toggle <name> (toggle audit-list rows); wstack plugin list"
+  },
+  "plugin:menu": {
+    name: "plugin:menu",
+    title: "wstack plugin menu \u2014 open or describe the plugin picker",
+    description: "In the TUI, `/plugin menu` opens the interactive plugin picker. From the non-interactive `wstack plugin menu` surface, the command prints the same audit report as `wstack plugin report`.",
+    usage: "wstack plugin menu",
+    seeAlso: "/plugin menu (interactive picker in the TUI); wstack plugin report"
+  },
+  // -- models --------------------------------------------------------------
+  // The `models:add` deep entry delegates its body to
+  // `models-add-help.ts` via the `customBody` field. The flag
+  // list lives in exactly one place (`MODELS_ADD_FLAGS`), and
+  // every surface that renders the help — `wstack models add --help`,
+  // `/models add help`, `/help models add` — produces the same
+  // string. The `title` / `description` / `usage` / `seeAlso`
+  // fields below are required by the `PerSubcommandHelp` shape
+  // but never rendered (the `customBody` thunk owns the full
+  // layout). They're filled in with sensible defaults so a
+  // future refactor that drops `customBody` (e.g. to use the
+  // standard layout) still has a coherent fallback.
+  "models:add": {
+    name: "models:add",
+    title: "wstack models add <mid> \u2014 register a custom model",
+    description: "See renderModelsAddHelpToString() in models-add-help.ts for the full block.",
+    usage: "wstack models add <mid> [...flags]",
+    customBody: renderModelsAddHelpToString
+  },
+  "models:remove": {
+    name: "models:remove",
+    title: "wstack models remove <mid> \u2014 unregister a custom model",
+    description: "Remove a custom model from the config. The catalog is unaffected (catalog models are managed by `wstack models refresh`).",
+    usage: "wstack models remove <mid>",
+    subcommands: [{ name: "<mid>", description: "The model id to remove." }]
+  },
+  // -- audit / replay (--list deep-subcommand) ---------------------------
+  "audit:list": {
+    name: "audit:list",
+    title: "wstack audit --list \u2014 list every session with an audit log",
+    description: "Scan the project sessions dir for `.audit.jsonl` sidecars and print a one-line summary per session (entry count + chain status). Useful for finding a session to inspect with `wstack audit <id>`.",
+    usage: "wstack audit --list / wstack audit -l",
+    seeAlso: "wstack audit <id> (inspect a single session's chain)"
+  },
+  "replay:list": {
+    name: "replay:list",
+    title: "wstack replay --list \u2014 list every session with a replay log",
+    description: "Scan the project sessions dir for `.replay.jsonl` sidecars and print a one-line summary per session (entry count + log path). Useful for finding a session to inspect with `wstack replay <id>`.",
+    usage: "wstack replay --list / wstack replay -l",
+    seeAlso: "wstack replay <id> (inspect a single session's recorded responses)"
+  },
+  // -- sessions (deep subcommands) ---------------------------------------
+  "sessions:resume": {
+    name: "sessions:resume",
+    title: "wstack sessions resume [<id>] \u2014 resume a prior session",
+    description: `Resume a session by id, or the most recent one if no id is given. The REPL replays the session's history into the new run so context is preserved. Use the most recent id when the user just asked "pick up where we left off" without naming a specific session.`,
+    usage: "wstack sessions resume [<id>]",
+    subcommands: [
+      { name: "[<id>]", description: "Session id to resume (defaults to the most recent)." }
+    ],
+    seeAlso: "wstack sessions list (find a recent id); wstack sessions show <id> (preview before resuming)"
+  },
+  "sessions:fork": {
+    name: "sessions:fork",
+    title: "wstack sessions fork [<id>] [--to N] \u2014 branch a session journal",
+    description: "Create a non-destructive child JSONL journal from the latest persisted boundary or checkpoint N. The parent is unchanged and the returned checkpoint hash identifies the exact parent event prefix. New Git-backed checkpoints also report a content-addressed workspace manifest, but the fork command does not apply it automatically: files remain shared until a host materializes that manifest into a separate clean checkout.",
+    usage: "wstack sessions fork [<id>] [--to N]",
+    subcommands: [
+      { name: "[<id>]", description: "Parent session id (defaults to the most recent)." },
+      { name: "--to N", description: "Fork at checkpoint prompt index N." }
+    ],
+    seeAlso: "wstack rewind --list (find checkpoints); wstack sessions resume <child-id>"
+  },
+  "sessions:fleet": {
+    name: "sessions:fleet",
+    title: "wstack sessions fleet \u2014 list the active fleet of sessions",
+    description: "List the active multi-agent fleet runs (the director, the subagent set, the iteration count, the journal size). Distinct from `wstack sessions list` which only shows single-agent sessions.",
+    usage: "wstack sessions fleet",
+    seeAlso: "wstack sessions list (single-agent sessions); /fleet (the in-REPL equivalent)"
+  },
+  "sessions:show": {
+    name: "sessions:show",
+    title: "wstack sessions show <id> \u2014 preview a session in detail",
+    description: "Print the session metadata, the first N turns, the token/cost totals, and any errors. Use this to decide whether to resume a session before committing to it.",
+    usage: "wstack sessions show <id>",
+    subcommands: [{ name: "<id>", description: "The session id to show." }]
+  },
+  "sessions:list": {
+    name: "sessions:list",
+    title: "wstack sessions list \u2014 list recent single-agent sessions",
+    description: "Print a one-line summary per recorded session (id, timestamp, last prompt, model, token totals). Distinct from `wstack sessions fleet` which shows active multi-agent runs. Use this to find a session id to resume, show, or export.",
+    usage: "wstack sessions list",
+    seeAlso: "wstack sessions fleet (active runs); wstack sessions resume <id> (resume one)"
+  },
+  "sessions:config": {
+    name: "sessions:config",
+    title: "wstack sessions config \u2014 session-specific config",
+    description: "Show or edit the session-specific config overrides (e.g. per-session provider + model). Subcommand: see the underlying config-history commands for the full surface \u2014 this is the shortcut alias.",
+    usage: "wstack sessions config"
+  },
+  // -- config (subcommands of the top-level config) ---------------------
+  "config:show": {
+    name: "config:show",
+    title: "wstack config show \u2014 print the resolved config",
+    description: "Print the resolved config (active profile plus all on-disk overrides applied) to stdout. Secrets are masked. The default subcommand \u2014 `wstack config` without a sub invokes this.",
+    usage: "wstack config show",
+    seeAlso: "wstack config edit (interactive); wstack auth (most config edits are auth/key changes)"
+  },
+  "config:edit": {
+    name: "config:edit",
+    title: "wstack config edit \u2014 open the active profile config in $EDITOR",
+    description: "Print the active profile config path (typically `~/.wrongstack/profiles/default/config.json`) and the command to open it. Does not spawn the editor itself \u2014 the user runs the printed command (or sets `$EDITOR` and re-runs). Useful for offline edits when you want to see the full file at once.",
+    usage: "wstack config edit",
+    seeAlso: "wstack config show (verify after edit); wstack config history (audit trail)"
+  },
+  "config:history": {
+    name: "config:history",
+    title: "wstack config history \u2014 list recent config-history entries",
+    description: "List every recent change to the active profile config, with a one-line description and a snapshot id. Pass `--id <id>` to see the full diff + masked snapshot. The audit trail is append-only (entries are never modified post-creation).",
+    usage: "wstack config history [--id <id>]",
+    subcommands: [
+      { name: "<no subcommand>", description: "List every history entry (newest first)." },
+      { name: "--id <id>", description: "Show the full diff + masked snapshot for one entry." }
+    ],
+    seeAlso: "wstack config restore <id>|--latest (revert); wstack config show (current state)"
+  },
+  "config:restore": {
+    name: "config:restore",
+    title: "wstack config restore <id>|--latest \u2014 revert to a prior config",
+    description: "Restore a previous config-history entry. Pass either the history id (from `wstack config history`) or `--latest` to revert to the most recent prior version. A backup of the current config is created before the restore, so the change is itself recorded in the history (a history of histories).",
+    usage: "wstack config restore <id> | --latest / -l",
+    subcommands: [
+      {
+        name: "<id>",
+        description: "The history id to restore (from `wstack config history` output)."
+      },
+      {
+        name: "--latest / -l",
+        description: "Restore to the most recent prior version (without naming an id)."
+      }
+    ],
+    seeAlso: "wstack config history (list entries); wstack config show (verify the restore)"
+  },
+  // -- rewind (flag-shaped deep subcommands) ----------------------------
+  "rewind:list": {
+    name: "rewind:list",
+    title: "wstack rewind --list \u2014 list rewind checkpoints for a session",
+    description: "Print every checkpoint for the session (default: latest). Each checkpoint is a snapshot of the working tree + session history at a given prompt index. Use the checkpoint index as the value for `--to <idx>` when rewinding. Default `wstack rewind` (no flags) is an error \u2014 pair `--list` with a session id (positional) to discover available checkpoints first.",
+    usage: "wstack rewind [<sessionId>] --list",
+    seeAlso: "wstack rewind --to <idx> (rewind to a specific checkpoint); wstack rewind --all"
+  },
+  "rewind:all": {
+    name: "rewind:all",
+    title: "wstack rewind --all \u2014 rewind to the start of the session",
+    description: "Rewind the working tree + session state to the very start of the session (the first prompt). Every file modified since the start is reverted. Pair with `--resume` to also truncate the session history at the start (so a fresh `wstack` invocation begins from there).",
+    usage: "wstack rewind [<sessionId>] --all [--resume]",
+    seeAlso: "wstack rewind --last N (rewind fewer steps); wstack rewind --to <idx> (specific checkpoint)"
+  },
+  "rewind:last": {
+    name: "rewind:last",
+    title: "wstack rewind --last N \u2014 rewind the last N prompts",
+    description: "Rewind the last `N` prompts. For a session that was on track for prompts 1..10 and went off the rails at 11..15, `--last 5` rewinds to the state at the end of prompt 10. Pair with `--resume` to truncate the history at the rewound point.",
+    usage: "wstack rewind [<sessionId>] --last <N> [--resume]",
+    subcommands: [
+      { name: "<N>", description: "Number of recent prompts to rewind (must be \u2265 1)." }
+    ],
+    seeAlso: "wstack rewind --all (rewind further); wstack rewind --to <idx> (precise checkpoint)"
+  },
+  "rewind:to": {
+    name: "rewind:to",
+    title: "wstack rewind --to <idx> \u2014 rewind to a specific checkpoint",
+    description: "Rewind to checkpoint at the given prompt index (from `wstack rewind --list`). The most precise rewind form \u2014 lets you step back to exactly the state at a specific prompt rather than the bulk `--all` or approximate `--last N`.",
+    usage: "wstack rewind [<sessionId>] --to <idx> [--resume]",
+    subcommands: [
+      {
+        name: "<idx>",
+        description: "Prompt index to rewind to (must be \u2265 0). Use `wstack rewind --list` to find indices."
+      }
+    ],
+    seeAlso: "wstack rewind --list (find checkpoint indices); wstack rewind --resume (truncate history at the checkpoint)"
+  },
+  "rewind:resume": {
+    name: "rewind:resume",
+    title: "wstack rewind --resume \u2014 truncate session history at the checkpoint",
+    description: "After the rewind (any of `--all` / `--last N` / `--to N`), also truncate the session's recorded history at the rewound checkpoint so the next `wstack` invocation begins fresh from there. Without `--resume`, the rewind only reverts the working tree \u2014 the session history is preserved (you'd see the rewind point as a checkpoint in subsequent runs).",
+    usage: "wstack rewind [<sessionId>] {--all|--last <N>|--to <idx>} --resume",
+    seeAlso: "wstack rewind --list (find checkpoints); wstack sessions resume <id> (resume a rewound session)"
+  },
+  // -- mcp:restart (REPL-only) -----------------------------------------
+  "mcp:restart": {
+    name: "mcp:restart",
+    title: "wstack mcp restart \u2014 restart a running MCP server (REPL only)",
+    description: "Restart a single running MCP server by alias. This subcommand is only meaningful inside the REPL (`wstack` with no `<task>` argument) \u2014 from the top-level CLI it prints a warning and exits 0 because there's no live process to restart. Use the `/mcp restart <name>` slash command from inside the REPL.",
+    usage: "wstack mcp restart <name> (REPL only)",
+    seeAlso: "/mcp restart <name> (the in-REPL slash command); wstack mcp remove + wstack mcp add (replace the server config)"
+  },
+  // -- plugin (list / official) -----------------------------------------
+  "plugin:list": {
+    name: "plugin:list",
+    title: "wstack plugin list \u2014 list configured plugins",
+    description: "Print every plugin registered in the config, grouped by enabled vs disabled. Alias: `plugin status`. For the official registry (a curated list maintained by the WrongStack project), use `wstack plugin official` instead.",
+    usage: "wstack plugin list (alias: wstack plugin status)",
+    seeAlso: "wstack plugin official (curated registry); wstack plugin enable / disable (toggle state)"
+  },
+  "plugin:official": {
+    name: "plugin:official",
+    title: "wstack plugin official \u2014 list the curated official registry",
+    description: "Print every plugin in the official registry (currently `telegram` and `lsp`). Each row shows the alias (for shorthand on the command line) and the full NPM specifier (what `wstack plugin add <spec>` actually installs). Aliases: `plugin officials` (plural).",
+    usage: "wstack plugin official (alias: wstack plugin officials)",
+    seeAlso: "wstack plugin add <alias> (install one); wstack plugin list (what you have)"
+  },
+  "plugin:officials": {
+    // The plural form `plugin officials` is accepted as an
+    // alias of `plugin official` in the underlying dispatch
+    // (`plugin-management.ts`). The deep-help table mirrors
+    // the alias so `wstack plugin officials --help` and
+    // `wstack plugin official --help` both render the same
+    // focused block.
+    name: "plugin:officials",
+    title: "wstack plugin officials \u2014 list the curated official registry (plural alias)",
+    description: "Alias of `wstack plugin official`. Prints every plugin in the official registry. Same output as the singular form.",
+    usage: "wstack plugin officials (plural alias of `wstack plugin official`)",
+    seeAlso: "wstack plugin official (the singular form)"
+  },
+  // -- models (refresh + list) -----------------------------------------
+  "models:refresh": {
+    name: "models:refresh",
+    title: "wstack models refresh \u2014 force-refresh the models.dev cache",
+    description: "Re-fetch the models.dev catalog and replace the cached `models.json` in the global config dir. Useful when a new model is published mid-session and you want to see it in `wstack providers` / `wstack models` without restarting. The cache age is shown in the footer of every `wstack models` listing so you know when to refresh.",
+    usage: "wstack models refresh",
+    seeAlso: "wstack models <provider> (list models after refresh); wstack providers (force-refresh the provider catalog)"
+  },
+  "models:list": {
+    name: "models:list",
+    title: "wstack models list \u2014 list custom models registered locally",
+    description: "Print every model that's been added via `wstack models add` (i.e. the entries in `config.json`'s `models` section, not the catalog). Distinct from `wstack models <provider>` which lists the catalog for a specific provider. The list is the audit surface for self-hosted / fine-tuned / overridden models.",
+    usage: "wstack models list",
+    seeAlso: "wstack models <provider> (catalog); wstack models add <mid> (register a custom model)"
+  },
+  // -- auth (list / status / remove) -------------------------------------
+  // The top-level `wstack auth` entry in `helpTable` lists the
+  // subcommands; these deep entries give each one its own focused
+  // block so `wstack auth list --help`, `/help auth status`, and
+  // `/auth status help` all render the same string the underlying
+  // handler would emit. The descriptions match the actual
+  // handler behavior in `packages/cli/src/subcommands/handlers/auth.ts`
+  // — note that the `remove` subcommand is always interactive
+  // (prompts for confirmation); the `[--force]` token in the
+  // handler's error message is a documented hint that is not
+  // yet wired up in the parser.
+  "auth:list": {
+    name: "auth:list",
+    title: "wstack auth list \u2014 list saved providers and key status",
+    description: "Read-only listing of every provider in the active profile config. Each provider block shows the family, baseUrl, model-allowlist size, and the saved API keys (the active key is marked with a green `\u25CF`, inactive keys with a dim `\u25CB`; all values are masked). Alias: `wstack auth ls`.",
+    usage: "wstack auth list (alias: wstack auth ls)",
+    subcommands: [
+      { name: "list", description: "List every saved provider (this command)." },
+      { name: "ls", description: "Alias of list." }
+    ],
+    seeAlso: "wstack auth status <id> (detail for one provider); wstack auth remove <id> (delete one)"
+  },
+  "auth:status": {
+    name: "auth:status",
+    title: "wstack auth status <provider> \u2014 show detail for one provider",
+    description: "Print the full `config.json` entry for a single provider: type, family, baseUrl, the `models` allowlist, the `envVars` list, and every saved key (active key marked with a green `\u25CF`, masked value, ISO timestamp). The provider id is required as a positional \u2014 `wstack auth status` with no id prints the usage hint and exits 1.",
+    usage: "wstack auth status <provider>",
+    subcommands: [
+      {
+        name: "<provider>",
+        description: "The provider id to inspect (e.g. `openai`, `anthropic`)."
+      }
+    ],
+    seeAlso: "wstack auth list (find the id); wstack auth remove <id> (delete it); wstack auth (interactive edit)"
+  },
+  "auth:remove": {
+    name: "auth:remove",
+    title: "wstack auth remove <provider> \u2014 delete a provider and its keys",
+    description: "Remove a provider entry and all its saved API keys from the active profile config. The flow is always interactive: after printing a confirmation prompt the handler waits for a `y` / `yes` answer (default `N`). The active session's in-memory provider is NOT reloaded \u2014 restart the REPL to fully tear down a running provider. Alias: `wstack auth rm`.",
+    usage: "wstack auth remove <provider> (alias: wstack auth rm <provider>)",
+    subcommands: [
+      { name: "<provider>", description: "The provider id to remove." },
+      { name: "rm", description: "Alias of remove." }
+    ],
+    seeAlso: "wstack auth list (find the id); wstack auth status <id> (inspect before removing); wstack auth <provider> (re-add a different one)"
+  },
+  // The `auth:local` deep entry delegates its body to
+  // `auth-local-help.ts` via the `customBody` field. The flag
+  // list lives in exactly one place (`LOCAL_AUTH_FLAGS`), and
+  // every surface that renders the help — `wstack auth local --help`,
+  // `/auth local help`, `/help auth local` — produces the same
+  // string. The `title` / `description` / `usage` / `seeAlso` fields
+  // below are required by the `PerSubcommandHelp` shape but
+  // never rendered (the `customBody` thunk owns the full layout).
+  // They're filled in with sensible defaults so a future refactor
+  // that drops `customBody` (e.g. to use the standard layout)
+  // still has a coherent fallback.
+  "auth:local": {
+    name: "auth:local",
+    title: "wstack auth local \u2014 quick-add Ollama / vLLM / LM Studio",
+    description: "Pre-fills the base URL, runs a health probe, and persists the allowlist so you can `wstack --provider <id>` right away. Use `--no-probe` to skip the probe when the server is not running yet; `--audit <file>` captures the save lifecycle as JSONL.",
+    usage: "wstack auth local [--name <id>] [--base-url <url>] [--no-key] [--no-probe|--probe-only] [--model <spec>] [--audit [target]]",
+    seeAlso: "wstack auth (interactive menu); wstack auth <provider> (catalog add)",
+    customBody: renderAuthLocalHelpToString
+  },
+  // -- bench (run — delegated to bench-run-help.ts via customBody) ------
+  // The `bench:run` deep entry delegates its body to
+  // `bench-run-help.ts` via the `customBody` field. The flag
+  // list lives in exactly one place (`BENCH_RUN_FLAGS`), and
+  // every surface that renders the help — `wstack bench run --help`,
+  // `/bench run help`, `/help bench run` — produces the same
+  // string. The `title` / `description` / `usage` / `seeAlso`
+  // fields below are required by the `PerSubcommandHelp` shape
+  // but never rendered (the `customBody` thunk owns the full
+  // layout). They're filled in with sensible defaults so a
+  // future refactor that drops `customBody` (e.g. to use the
+  // standard layout) still has a coherent fallback.
+  "bench:run": {
+    name: "bench:run",
+    title: "wstack bench run \u2014 execute a benchmark suite across a model matrix",
+    description: "See renderBenchRunHelpToString() in bench-run-help.ts for the full block.",
+    usage: "wstack bench run [...flags]",
+    customBody: renderBenchRunHelpToString
+  }
+};
+
+// src/subcommands/handlers/per-subcommand-help-table.ts
+var helpTable = {
+  init: {
+    name: "init",
+    title: "wstack init \u2014 DEPRECATED (use wstack auth)",
+    description: "\u26A0 This command is deprecated. Use wstack auth for setup, key management, and model selection in one interactive workflow.",
+    usage: "wstack init (deprecated)",
+    seeAlso: "wstack auth (interactive setup + key manager)"
+  },
+  version: {
+    name: "version",
+    title: "wstack version \u2014 print the CLI version",
+    description: "Prints the WrongStack CLI version, the apiVersion, the Node.js version, and the host platform. Useful for bug reports and CI logs.",
+    usage: "wstack version"
+  },
+  mcp: {
+    name: "mcp",
+    title: "wstack mcp \u2014 manage Model Context Protocol servers",
+    description: "List, add, remove, restart, and serve MCP servers registered in the global config. Servers are referenced by id and use the stdio, SSE, or streamable-HTTP transports.",
+    usage: "wstack mcp [list|add|remove|restart|serve] [...]",
+    subcommands: [
+      { name: "list", description: "List all configured MCP servers." },
+      { name: "add <id> <command>", description: "Register a new stdio MCP server." },
+      { name: "remove <id>", description: "Unregister an MCP server." },
+      { name: "restart <id>", description: "Restart a running MCP server." },
+      {
+        name: "serve",
+        description: "Run the wstack MCP server; --resources/--prompts explicitly expose selected files."
+      }
+    ],
+    seeAlso: "wstack plugin (manage tool plugins similarly)"
+  },
+  plugin: {
+    name: "plugin",
+    title: "wstack plugin \u2014 manage tool plugins",
+    description: "List, inspect, install, add, remove, enable, disable, and toggle tool plugins. Plugins extend the agent with custom tool packs (e.g. GitHub, Playwright, project-local helpers).",
+    usage: "wstack plugin [list|status|report|menu|official|add|install|toggle|remove|enable|disable|manager] [...]",
+    subcommands: [
+      { name: "list", description: "List installed plugins (alias: status)." },
+      { name: "report", description: "Show effective state, risk, and lock/toggle policy." },
+      { name: "menu", description: "Print the audit report outside the TUI plugin picker." },
+      { name: "official", description: "List plugins from the official registry." },
+      { name: "add <id>", description: "Add a plugin by id (alias: install)." },
+      { name: "toggle <id>", description: "Toggle a safe audit-list plugin row." },
+      { name: "remove <id>", description: "Remove an installed plugin (aliases: rm, uninstall)." },
+      { name: "enable <id>", description: "Re-enable a previously-disabled plugin." },
+      { name: "disable <id>", description: "Temporarily disable a plugin without removing it." },
+      {
+        name: "manager [lock|unlock] <id|*>",
+        description: "Control whether the LLM may enable/disable individual plugins."
+      }
+    ],
+    seeAlso: "wstack mcp (MCP servers are registered as tool plugins)"
+  },
+  models: {
+    name: "models",
+    title: "wstack models \u2014 list and override models",
+    description: "List models from the models.dev catalog, or override the default model for a provider with a custom id (for self-hosted or fine-tuned models not in the public catalog).",
+    usage: "wstack models [<provider>] [add|remove|list|refresh] [...]",
+    subcommands: [
+      { name: "<no-subcommand>", description: "List models for the default provider." },
+      { name: "<provider>", description: "List models for a specific provider." },
+      {
+        name: "add <mid>",
+        description: "Add or override a custom model (--max-context, --tools, --vision, \u2026)."
+      },
+      { name: "remove <mid>", description: "Remove a custom model." },
+      { name: "list", description: "List all custom models registered locally." },
+      { name: "refresh", description: "Force-refresh the models.dev cache." }
+    ],
+    seeAlso: "wstack providers (list provider families and their defaults)"
+  },
+  config: {
+    name: "config",
+    title: "wstack config \u2014 show or edit effective config",
+    description: "Print the resolved config (with the on-disk overrides merged on top), or open the active profile config in $EDITOR for interactive edits. Also exposes a small audit log of recent config-history changes for diagnostics.",
+    usage: "wstack config [show|edit|history|restore] [...]",
+    subcommands: [
+      { name: "show", description: "Print the resolved config to stdout (default)." },
+      { name: "edit", description: "Open the active profile config in $EDITOR." },
+      { name: "history", description: "List recent config-history entries." },
+      { name: "restore <id>", description: "Restore a previous config-history entry." }
+    ],
+    seeAlso: "wstack auth (most config edits are auth/key changes)"
+  },
+  // -- API key / auth management -----------------------------------------
+  auth: {
+    name: "auth",
+    title: "wstack auth \u2014 manage API keys and provider credentials",
+    description: "Add, view, and remove provider API keys. The interactive menu supports a custom-URL path for self-hosted / local servers, a quick-shortcut path for Ollama / vLLM / LM Studio, and a catalog path for the well-known providers.",
+    usage: "wstack auth [list|status|remove] [...] | wstack auth <provider> | wstack auth local [...]",
+    subcommands: [
+      { name: "list", description: "List saved providers and key status." },
+      { name: "status <id>", description: "Show detail for one provider." },
+      { name: "remove <id>", description: "Remove a provider and its keys." },
+      { name: "<provider>", description: "Add a key for a named provider (--label, --family, \u2026)." },
+      {
+        name: "local",
+        description: "Pre-fill Ollama / vLLM / LM Studio (--name, --base-url, --no-probe, --model, --audit \u2026)."
+      },
+      {
+        name: "login <chatgpt|claude|copilot>",
+        description: "Subscription OAuth login: chatgpt (\u2192 openai-codex), claude (\u2192 anthropic-oauth), or copilot (\u2192 github-copilot). Opens browser; no API key. \u26A0 Using subscriptions outside official clients may violate provider ToS (account ban risk); an API key is the sanctioned path."
+      }
+    ],
+    seeAlso: "wstack auth local (pre-fill Ollama / vLLM / LM Studio)"
+  },
+  // -- Session list / resume / show / fork --------------------------------
+  sessions: {
+    name: "sessions",
+    title: "wstack sessions \u2014 list and resume recent sessions",
+    description: "List recent sessions, show one session in detail, resume a session, or inspect a session's audit log. The audit log is stored as JSONL next to each session's recording.",
+    usage: "wstack sessions [list|show|resume|fork|doctor|config|fleet] [...]",
+    subcommands: [
+      { name: "list", description: "List the most recent sessions." },
+      {
+        name: "doctor [--fix] [--json] [--limit N]",
+        description: "Diagnose every journal in this project: unparsable lines, truncated tails, sessions that died mid-turn, missing or stale summary sidecars, and journals large enough to be slow to open. --fix rebuilds only derived artifacts (summary sidecars + the catalog index); journals are never edited."
+      },
+      { name: "show <id>", description: "Show one session in detail." },
+      { name: "resume [<id>]", description: "Resume a session (latest if no id given)." },
+      {
+        name: "fork [<id>] [--to N]",
+        description: "Create an isolated child journal at a persisted boundary."
+      },
+      { name: "config", description: "Show or edit session-specific config." },
+      { name: "fleet", description: "List the active fleet of sessions." }
+    ],
+    seeAlso: "wstack audit (the session-level audit log reader)"
+  },
+  // -- Diagnostics --------------------------------------------------------
+  doctor: {
+    name: "doctor",
+    title: "wstack doctor \u2014 health checks",
+    description: "Run a series of health checks (provider + key + models cache + secret vault + sessions dir + MCP server config) and exit non-zero if any check fails. Use as a CI gate or a post-install smoke test. With --daemons, inspect this project\u2019s IPC daemons instead: each is reported live, stale, or stopped. A stale endpoint is one whose owner died without releasing it; daemons reclaim it on their next start, or --clear-stale removes it now. Listing never spawns a daemon.",
+    usage: "wstack doctor [--daemons [--clear-stale]]",
+    seeAlso: "wstack diag (read-only environment dump for bug reports)"
+  },
+  diag: {
+    name: "diag",
+    title: "wstack diag \u2014 read-only environment dump",
+    description: "Print a key=value environment snapshot (apiVersion, cwd, project info, paths, cache age, configured provider + model, tool/plugin counts, MCP server count). Never modifies state \u2014 safe to paste into bug reports.",
+    usage: "wstack diag",
+    seeAlso: "wstack doctor (pass/fail health checks vs. this is a dump)"
+  },
+  // -- Session audit / replay / rewind -----------------------------------
+  audit: {
+    name: "audit",
+    title: "wstack audit \u2014 inspect a session's tamper-evident audit log",
+    description: "Show the chained-hash entries for a recorded session and run a verification pass to surface any post-hoc modification. Each entry is SHA-256-chained to the previous; any tampering breaks the chain and is reported.",
+    usage: "wstack audit [<sessionId>] [--list]",
+    subcommands: [
+      { name: "<sessionId>", description: "Show entries + verify chain (positional)." },
+      { name: "--list / -l", description: "List every session that has an audit log." }
+    ],
+    seeAlso: "wstack replay (the corresponding provider-response log)"
+  },
+  replay: {
+    name: "replay",
+    title: "wstack replay \u2014 inspect a session's recorded provider responses",
+    description: "Show the recorded request/response pairs for a session \u2014 the frozen inputs the agent saw, in order. This is the inspection surface; to actually re-run the agent with those responses, use `wstack --replay <sessionId>`.",
+    usage: "wstack replay [<sessionId>] [--list]",
+    subcommands: [
+      { name: "<sessionId>", description: "Show the recorded entries (positional)." },
+      { name: "--list / -l", description: "List every session that has a replay log." }
+    ],
+    seeAlso: "wstack audit (the tamper-evident tool-call log)"
+  },
+  rewind: {
+    name: "rewind",
+    title: "wstack rewind \u2014 rewind a session to an earlier state",
+    description: "Restore a session's in-memory state to a previous point in its recording. The rewind is non-destructive: the original session is preserved, and a new resumed session picks up from the rewound point. Useful for re-running a fork of an exploration without losing the original.",
+    usage: "wstack rewind [<sessionId>] [--all|--last <n>|--to <id>] [--list] [--resume]",
+    subcommands: [
+      { name: "<sessionId>", description: "Session id (positional; defaults to the latest)." },
+      { name: "--all", description: "Rewind to the start of the session." },
+      { name: "--last <n>", description: "Rewind to `n` steps back from the end." },
+      { name: "--to <id>", description: "Rewind to a specific step id." },
+      { name: "--list", description: "List available rewind points for the session." },
+      { name: "--resume", description: "Resume the rewound session after the rewind." }
+    ],
+    seeAlso: "wstack replay (the underlying provider-response log)"
+  },
+  // -- Export & usage ----------------------------------------------------
+  export: {
+    name: "export",
+    title: "wstack export \u2014 render a session to a portable format",
+    description: "Render a recorded session to Markdown, JSON, or plain text. Use Markdown for human-readable share/audit artifacts, JSON for downstream tooling, or text for grep-friendly search. Tools and diagnostics are included by default; toggle either off with `--no-tools` or `--no-diagnostics`.",
+    usage: "wstack export <sessionId> [--format markdown|json|text] [--out <file>] [--no-tools] [--no-diagnostics]",
+    subcommands: [
+      { name: "<sessionId>", description: "The session id to render (positional)." },
+      {
+        name: "--format <f> / -f <f>",
+        description: "Output format: markdown (default), json, or text."
+      },
+      { name: "--out <file> / -o <file>", description: "Write to <file> instead of stdout." },
+      { name: "--no-tools", description: "Omit tool-call entries from the output." },
+      {
+        name: "--no-diagnostics",
+        description: "Omit diagnostic entries (errors, retries) from the output."
+      }
+    ],
+    seeAlso: "wstack replay (the recorded provider-response log)"
+  },
+  usage: {
+    name: "usage",
+    title: "wstack usage \u2014 token + cost summary",
+    description: "Print a per-session token + cost summary from the audit log. Useful for cost reviews and the post-session billing recap. Aggregates input/output tokens and the per-model cost; requires the session to have been recorded with audit enabled.",
+    usage: "wstack usage",
+    seeAlso: "wstack export (full session render for archival)"
+  },
+  // -- Listing subcommands -----------------------------------------------
+  providers: {
+    name: "providers",
+    title: "wstack providers \u2014 list providers from models.dev",
+    description: "List provider families from the live models.dev catalog. Default view shows the popular three (Anthropic, OpenAI, Google); pass `--all` to include every supported family, or `--unsupported` to surface the ones without a built-in transport (which require a plugin).",
+    usage: "wstack providers [--all] [--unsupported]",
+    subcommands: [
+      { name: "--all", description: "Include every supported family, not just the popular three." },
+      {
+        name: "--unsupported",
+        description: "Include families without a built-in transport (need a plugin)."
+      }
+    ],
+    seeAlso: "wstack models (list models within a provider)"
+  },
+  tools: {
+    name: "tools",
+    title: "wstack tools \u2014 list registered tools",
+    description: "List every tool the agent can invoke, with its owner (built-in / plugin) and permission level. Useful for auditing what a session can do, especially after installing a new plugin.",
+    usage: "wstack tools",
+    seeAlso: "wstack skills (list skills; tools + skills are the two extension surfaces)"
+  },
+  skills: {
+    name: "skills",
+    title: "wstack skills \u2014 list discovered skills",
+    description: "List every skill the agent can invoke, grouped by source (bundled / user-installed / project-local). Skills are on-demand context packs that load only when triggered.",
+    usage: "wstack skills",
+    seeAlso: "wstack tools (tools are always-loaded; skills are on-demand)"
+  },
+  projects: {
+    name: "projects",
+    title: "wstack projects \u2014 list tracked projects",
+    description: "List every project WrongStack has seen (tracked by a hashed root). Each entry shows the project root and the last-seen timestamp. Useful for cleaning up the global projects dir after a workspace migration.",
+    usage: "wstack projects"
+  },
+  // -- Lifecycle ---------------------------------------------------------
+  update: {
+    name: "update",
+    title: "wstack update \u2014 self-update the CLI",
+    description: "Check the latest npm version and update the globally-installed `wrongstack` package. Use `--check-only` to just print the current/latest without installing. Pass `--pm <manager>` (or its shorthand `--npm`, `--pnpm`, `--yarn`, `--bun`) to force a specific package manager; pass `--allow-scripts` (alias `--lifecycle-scripts`) to opt into package lifecycle scripts during the update (off by default). The update is global; run from any project root.",
+    usage: "wstack update [--check-only] [--pm <manager>] [--allow-scripts (alias: --lifecycle-scripts)]",
+    seeAlso: "wstack version (read-only version info)"
+  },
+  // -- ACP (Agent Client Protocol) --------------------------------------
+  acp: {
+    name: "acp",
+    title: "wstack acp \u2014 Agent Client Protocol (ACP) integration",
+    description: "Run WrongStack as an ACP server (stdio) for editor clients (Zed, JetBrains, VS Code ACP), or orchestrate external ACP agents through spawn, probe, bench, and parallel fan-out.",
+    usage: "wstack acp [server|list|sync|spawn|parallel|probe|bench] [...]",
+    subcommands: [
+      { name: "server / serve", description: "Start WrongStack as an ACP stdio server (default)." },
+      { name: "list", description: "List available ACP agents from the cache." },
+      { name: "sync", description: "Sync the official ACP agent registry into local cache." },
+      { name: "spawn <id> <task>", description: "Spawn an ACP agent and wait for results." },
+      {
+        name: "parallel <csv> <task>",
+        description: "Fan a task out to multiple ACP agents in parallel."
+      },
+      { name: "probe [csv]", description: "Handshake-test installed ACP agents." },
+      { name: "bench [csv] [--fs]", description: "End-to-end benchmark and grade ACP agents." }
+    ],
+    seeAlso: "wstack mcp serve (the MCP equivalent; pick the protocol your client speaks)"
+  },
+  // -- Model diagnostics (read-only) -----------------------------------
+  modeldiag: {
+    name: "modeldiag",
+    title: "wstack modeldiag \u2014 model benchmarks + heuristic diagnostics",
+    description: "Read-only diagnostics for the configured model: key check, capability scan (vision / tools / context window), heuristic strengths/weaknesses (bestFor / avoidFor), sequential live provider/model smoke tests, and real benchmarks against a small prompt suite. Smoke tests use tiny prompts and never print credentials.",
+    usage: "wstack modeldiag [test|eval] [...]",
+    subcommands: [
+      {
+        name: "<no subcommand>",
+        description: "Print configured model capabilities, context limits, and recommendations."
+      },
+      {
+        name: "test [--plan|--all-models|--json]",
+        description: "Run live sequential smoke tests across configured models."
+      },
+      {
+        name: "eval [--providers <csv>]",
+        description: "Run model competency matrix evaluation across tasks."
+      }
+    ],
+    seeAlso: "wstack modeldiag test --plan; wstack modeldiag test; wstack modeldiag test --all-models"
+  },
+  // -- Bench (developer / CI only) -------------------------------------
+  bench: {
+    name: "bench",
+    title: "wstack bench \u2014 run model-independent agentic benchmarks",
+    description: "Run WrongStack against the Aider polyglot or SWE-bench Verified suites with deterministic graders. Used internally to compare model quality across releases; also useful for evaluating a new model before adopting it.",
+    usage: "wstack bench [run|report|list] [...]",
+    subcommands: [
+      { name: "run", description: "Run a benchmark suite (--suite <id> --models <config>)." },
+      { name: "report <dir>", description: "Render the Markdown report for a prior run." },
+      { name: "list", description: "List available suites and the model configs in the catalog." }
+    ],
+    seeAlso: "wstack modeldiag (read-only diagnostics; bench actually runs the model)"
+  },
+  // -- Quick launch ------------------------------------------------------
+  quick: {
+    name: "quick",
+    title: "wstack quick \u2014 launch the TUI with sensible defaults",
+    description: "Accept every default, list installed plugins, and open the TUI with the agents-monitor panel pre-shown. Equivalent to `wstack --tui --quick`; the dedicated subcommand is for discoverability and tab-completion. The actual TUI launch is intercepted in `boot()` before this handler runs.",
+    usage: "wstack quick",
+    seeAlso: "wstack --tui (the underlying flag; quick is just a shortcut)"
+  },
+  // -- Aliases and meta commands ───────────────────────────────────────
+  plugins: {
+    name: "plugins",
+    title: "wstack plugins \u2014 alias for wstack plugin",
+    description: "Alias for `wstack plugin`. See `wstack plugin --help` for the full set of subcommands.",
+    usage: "wstack plugins (alias for wstack plugin)",
+    seeAlso: "wstack plugin (the canonical command)"
+  },
+  help: {
+    name: "help",
+    title: "wstack help \u2014 print top-level help",
+    description: "Print the top-level help text listing every subcommand with a one-line summary. Equivalent to `wstack --help`.",
+    usage: "wstack help",
+    seeAlso: "wstack --help"
+  },
+  // -- HQ (dashboard server) ──────────────────────────────────────────
+  hq: {
+    name: "hq",
+    title: "wstack hq \u2014 start HQ command center or manage tokens",
+    description: "Start the HQ server \u2014 a web dashboard for monitoring sessions, fleet status, and agent activity across projects \u2014 or manage browser and client authentication tokens.",
+    usage: "wstack hq [serve] [--port <n>] [--password <secret>] [--tunnel] [--open] | wstack hq token [create|list|revoke]",
+    subcommands: [
+      { name: "serve", description: "Start the HQ dashboard server (default)." },
+      {
+        name: "token create [label]",
+        description: "Mint a browser or client authentication token."
+      },
+      { name: "token list", description: "List active HQ authentication tokens." },
+      { name: "token revoke <id>", description: "Revoke an issued HQ authentication token." }
+    ],
+    seeAlso: "wstack sessions fleet (CLI equivalent for fleet status)"
+  },
+  // -- Mailbox (external agent bridge) ────────────────────────────────
+  mailbox: {
+    name: "mailbox",
+    title: "wstack mailbox \u2014 serve the external-agent mailbox HTTP bridge",
+    description: "Start the mailbox HTTP bridge that lets external coding agents (Claude Code, Aider, custom scripts) communicate with the shared project mailbox. The server exposes a REST + SSE API for sending, checking, and acknowledging messages. Use `wstack mailbox serve` to start the listener.",
+    usage: "wstack mailbox serve [--port <n>]",
+    subcommands: [{ name: "serve", description: "Start the mailbox HTTP bridge listener." }],
+    seeAlso: "wstack hq (the HQ server includes mailbox routing)"
+  },
+  // -- Permissions ────────────────────────────────────────────────────
+  permissions: {
+    name: "permissions",
+    title: "wstack permissions \u2014 explain tool permission decisions",
+    description: "Side-effect-free permission decision explainer. Evaluates the effective permission rules for a tool and input arguments without prompting, modifying trust files, or mutating state.",
+    usage: "wstack permissions explain <tool> [--input '<json>'] [--json]",
+    subcommands: [
+      {
+        name: "explain <tool>",
+        description: "Explain how the permission policy evaluates a tool call."
+      }
+    ],
+    seeAlso: "wstack tools (list available tools)"
+  },
+  // -- Project management ─────────────────────────────────────────────
+  project: {
+    name: "project",
+    title: "wstack project \u2014 manage committed repository identity",
+    description: "Manage the committed repository identity (project.json) used to scope HQ dashboards, Kanban state, and multi-agent coordination. Commit the generated ID file so every clone shares the same project.",
+    usage: "wstack project [id|init|rekey] [--yes]",
+    subcommands: [
+      { name: "id", description: "Show the current project ID and config path (default)." },
+      { name: "init", description: "Initialize a project ID if not already present." },
+      { name: "rekey", description: "Generate a new project ID for a fork (requires --yes)." }
+    ],
+    seeAlso: "wstack projects (list all tracked projects)"
+  },
+  governance: {
+    name: "governance",
+    title: "wstack governance \u2014 inspect deterministic project-daemon health",
+    description: "Read token-free attachment-broker health from the current project daemon. Warnings are advisory: they surface deterministic operator escalation signals without stopping active tasks or model execution.",
+    usage: "wstack governance status [--json]",
+    subcommands: [{ name: "status", description: "Show daemon and attachment-broker health." }],
+    seeAlso: "wstack doctor (broader environment diagnostics)"
+  },
+  // -- Chronicle ──────────────────────────────────────────────────────
+  chronicle: {
+    name: "chronicle",
+    title: "wstack chronicle \u2014 query cross-session provenance ledger",
+    description: "Query the cross-session event ledger, inspect daemon status, compute facet aggregations, view token/cost metrics, or purge old retention entries.",
+    usage: "wstack chronicle [query|status|facet|metrics|prune|compact] [...]",
+    subcommands: [
+      { name: "query [field=value ...]", description: "Query recorded provenance events." },
+      { name: "status", description: "Check the Chronicle daemon and pipeline status." },
+      { name: "facet <field>", description: "Group and count events across a facet." },
+      {
+        name: "metrics [providers|tasks|files|summary]",
+        description: "Query aggregated metrics from metrics.db."
+      },
+      {
+        name: "prune [--days N] [--dry-run]",
+        description: "Purge journal entries older than N days."
+      },
+      { name: "compact", description: "Defragment and compact SQLite ledger." }
+    ],
+    seeAlso: "wstack audit (per-session audit log); wstack usage (cost summary)"
+  }
+};
+
+// src/subcommands/handlers/per-subcommand-help.ts
+var COLUMN_WIDTH = 28;
+function renderBlockToString(help) {
+  if (help.customBody) {
+    return help.customBody();
+  }
+  const lines = [
+    color3.bold(help.title),
+    color3.dim(`  ${help.description}`),
+    "",
+    color3.bold("Usage"),
+    `  ${help.usage}`
+  ];
+  if (help.subcommands && help.subcommands.length > 0) {
+    lines.push("");
+    lines.push(color3.bold("Subcommands"));
+    for (const { name, description } of help.subcommands) {
+      const padded = name.padEnd(COLUMN_WIDTH, " ");
+      lines.push(`  ${color3.cyan(padded)}${description}`);
+    }
+  }
+  if (help.seeAlso) {
+    lines.push("");
+    lines.push(color3.dim(`  See also: ${help.seeAlso}`));
+  }
+  lines.push("");
+  lines.push(color3.dim("  Tip: `wstack --help` lists every top-level command."));
+  return lines.join("\n") + "\n";
+}
+function renderBlock(help, renderer) {
+  renderer.write(renderBlockToString(help));
+}
+function renderDeepHelp(key, renderer) {
+  const help = deepHelpTable[key];
+  if (!help) return false;
+  renderBlock(help, renderer);
+  return true;
+}
+function renderDeepHelpToString(key) {
+  const help = deepHelpTable[key];
+  return help ? renderBlockToString(help) : void 0;
+}
+var deepSubcommandsWithFocusedHelp = Object.keys(deepHelpTable);
+function renderFocusedHelp(subcommand, renderer) {
+  const help = helpTable[subcommand];
+  if (!help) return false;
+  renderBlock(help, renderer);
+  return true;
+}
+function renderFocusedHelpToString(subcommand) {
+  const help = helpTable[subcommand];
+  return help ? renderBlockToString(help) : void 0;
+}
+var subcommandsWithFocusedHelp = Object.keys(helpTable);
+function renderGenericHelp(subcommand, renderer) {
+  const lines = [
+    color3.bold(`wstack ${subcommand}`),
+    color3.dim(
+      `  No focused help block is registered for this subcommand. Run \`wstack ${subcommand}\` for the interactive surface, or \`wstack --help\` for the top-level command list.`
+    ),
+    "",
+    color3.dim("  Tip: each subcommand's help is data-driven; see"),
+    color3.dim("  `per-subcommand-help.ts` for the focused entries.")
+  ];
+  renderer.write(lines.join("\n") + "\n");
+}
+
+export {
+  renderBlockToString,
+  renderDeepHelp,
+  renderDeepHelpToString,
+  deepSubcommandsWithFocusedHelp,
+  renderFocusedHelp,
+  renderFocusedHelpToString,
+  subcommandsWithFocusedHelp,
+  renderGenericHelp
+};
+//# sourceMappingURL=chunk-P2OKBDCH.js.map