@h-rig/cli 0.0.6-alpha.64 → 0.0.6-alpha.66

package/dist/src/commands/_connection-state.js

@@ -6,10 +6,19 @@ import { dirname, resolve } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 
 // packages/cli/src/commands/_connection-state.ts
 function resolveGlobalConnectionsPath(env = process.env) {
@@ -30,7 +39,7 @@ function readJsonFile(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
   } catch (error) {
-    throw new CliError2(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1);
+    throw new CliError(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1, { hint: "Fix or delete that file, then re-select a server with `rig server use <alias|local>`." });
   }
 }
 function writeJsonFile(path, value) {
@@ -73,7 +82,7 @@ function writeGlobalConnections(state, options = {}) {
 function upsertGlobalConnection(alias, connection, options = {}) {
   const cleanAlias = alias.trim();
   if (!cleanAlias)
-    throw new CliError2("Connection alias is required.", 1);
+    throw new CliError("Connection alias is required.", 1, { hint: "Save a server with `rig server add <alias> <url>`." });
   const state = readGlobalConnections(options);
   state.connections[cleanAlias] = connection;
   writeGlobalConnections(state, options);
@@ -106,7 +115,7 @@ function resolveSelectedConnection(projectRoot, options = {}) {
   const global = readGlobalConnections(options);
   const connection = global.connections[repo.selected];
   if (!connection) {
-    throw new CliError2(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
+    throw new CliError(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
   }
   return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
 }

package/dist/src/commands/_doctor-checks.js

@@ -7,10 +7,19 @@ import { resolve as resolve4 } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 
 // packages/cli/src/commands/_doctor-checks.ts
 import { isSupportedBunVersion, MIN_SUPPORTED_BUN_VERSION } from "@rig/runtime/control-plane/setup-version";
@@ -37,7 +46,7 @@ function readJsonFile(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
   } catch (error) {
-    throw new CliError2(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1);
+    throw new CliError(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1, { hint: "Fix or delete that file, then re-select a server with `rig server use <alias|local>`." });
   }
 }
 function writeJsonFile(path, value) {
@@ -101,7 +110,7 @@ function resolveSelectedConnection(projectRoot, options = {}) {
   const global = readGlobalConnections(options);
   const connection = global.connections[repo.selected];
   if (!connection) {
-    throw new CliError2(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
+    throw new CliError(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
   }
   return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
 }
@@ -177,7 +186,7 @@ async function ensureServerForCli(projectRoot) {
     };
   } catch (error) {
     if (error instanceof Error) {
-      throw new CliError2(error.message, 1);
+      throw new CliError(error.message, 1);
     }
     throw error;
   }
@@ -227,15 +236,64 @@ function diagnosticMessage(payload) {
   });
   return messages.length > 0 ? messages.join("; ") : null;
 }
+var serverReachabilityCache = new Map;
+async function probeServerReachability(baseUrl, authToken) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/api/server/status`, {
+      headers: mergeHeaders(undefined, authToken),
+      signal: AbortSignal.timeout(1500)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+function cachedServerReachability(projectRoot, baseUrl, authToken) {
+  const key = resolve2(projectRoot);
+  const cached = serverReachabilityCache.get(key);
+  if (cached)
+    return cached;
+  const probe = probeServerReachability(baseUrl, authToken);
+  serverReachabilityCache.set(key, probe);
+  return probe;
+}
+function describeSelectedServer(projectRoot, server) {
+  try {
+    const selected = resolveSelectedConnection(projectRoot);
+    if (selected) {
+      return {
+        alias: selected.alias,
+        target: selected.connection.kind === "remote" ? selected.connection.baseUrl : server.baseUrl
+      };
+    }
+  } catch {}
+  return { alias: server.connectionKind === "remote" ? "remote" : "local", target: server.baseUrl };
+}
+async function buildServerFailureContext(projectRoot, server) {
+  const { alias, target } = describeSelectedServer(projectRoot, server);
+  const reachable = await cachedServerReachability(projectRoot, server.baseUrl, server.authToken);
+  const reachability = reachable ? "server is reachable" : "server is unreachable";
+  return {
+    contextLine: `Currently connected to: ${alias} at ${target} (${reachability}).`,
+    hint: "Check the selected server with `rig server status`, or switch with `rig server use <alias|local>`."
+  };
+}
 async function requestServerJson(context, pathname, init = {}) {
   const server = await ensureServerForCli(context.projectRoot);
   const headers = mergeHeaders(init.headers, server.authToken);
   if (server.serverProjectRoot)
     headers.set("x-rig-project-root", server.serverProjectRoot);
-  const response = await fetch(`${server.baseUrl}${pathname}`, {
-    ...init,
-    headers
-  });
+  let response;
+  try {
+    response = await fetch(`${server.baseUrl}${pathname}`, {
+      ...init,
+      headers
+    });
+  } catch (error) {
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed: ${error instanceof Error ? error.message : String(error)}
+${failure.contextLine}`, 1, { hint: failure.hint });
+  }
   const text = await response.text();
   const payload = text.trim().length > 0 ? (() => {
     try {
@@ -247,7 +305,9 @@ async function requestServerJson(context, pathname, init = {}) {
   if (!response.ok) {
     const diagnostics = diagnosticMessage(payload);
     const detail = diagnostics ?? (text || response.statusText);
-    throw new CliError2(`Rig server request failed (${response.status}): ${detail}`, 1);
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed (${response.status}): ${detail}
+${failure.contextLine}`, 1, { hint: failure.hint });
   }
   return payload;
 }
@@ -553,7 +613,7 @@ function countDoctorFailures(checks) {
 function throwIfDoctorFailed(checks) {
   const failures = countDoctorFailures(checks);
   if (failures > 0) {
-    throw new CliError2(`Doctor failed (${failures} failing check${failures === 1 ? "" : "s"}).`, 1);
+    throw new CliError(`Doctor failed (${failures} failing check${failures === 1 ? "" : "s"}).`, 1);
   }
 }
 export {

package/dist/src/commands/_help-catalog.js

@@ -5,49 +5,47 @@ import pc from "picocolors";
 var TOP_LEVEL_SECTIONS = [
   {
     title: "Start here",
-    subtitle: "one-time setup for a repo",
+    subtitle: "one-time setup, pick a server",
     commands: [
       { command: "rig init", description: "Wizard: config, GitHub auth, task source, server, Pi wiring." },
-      { command: "rig doctor", description: "Check every part of the wiring \u2014 run this when anything feels off." },
-      { command: "rig server use <alias|local>", description: "Pick which Rig server owns this repo (`rig server list` to see them)." }
+      { command: "rig server use <alias|local>", description: "Pick which Rig server owns this repo (`rig server list` to see them)." },
+      { command: "rig server status", description: "Show the selected server for this repo." }
     ]
   },
   {
     title: "Work",
-    subtitle: "find a task and put an agent on it",
+    subtitle: "find a task, put an agent on it, answer what it asks",
     commands: [
       { command: "rig task list", description: "What's on the board (from the selected source/server)." },
-      { command: "rig task next", description: "The next ready task, as a card." },
       { command: "rig task run --next", description: "Dispatch an agent; interactive mode opens the native Pi session." },
-      { command: "rig task run <id> --detach", description: "Fire-and-forget a specific task." }
+      { command: "rig run status", description: "Active and recent runs at a glance." },
+      { command: "rig run attach <id> --follow", description: "Join the live Pi session (worker keeps running if you /detach)." },
+      { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." }
     ]
   },
   {
-    title: "Watch & steer",
-    subtitle: "live runs are observable and steerable, attached or not",
+    title: "Watch",
+    subtitle: "fleet metrics and per-task forensics",
     commands: [
-      { command: "rig run status", description: "Active and recent runs at a glance." },
-      { command: "rig run attach <id> --follow", description: "Join the live Pi session (worker keeps running if you /detach)." },
-      { command: "rig run steer <id> -m <text>", description: "Drop a message into a live worker without attaching." },
-      { command: "rig run stop <id>", description: "Cancel a running worker." }
+      { command: "rig stats [--since 7d]", description: "Fleet metrics: completion/failure rates, median run time, steering, stalls." },
+      { command: "rig inspect logs --task <id>", description: "Latest run log for a task." },
+      { command: "rig inspect diff --task <id>", description: "Changed files for a task." }
     ]
   },
   {
-    title: "Unblock & gate",
-    subtitle: "answer what workers ask; control what merges",
+    title: "Unblock",
+    subtitle: "diagnose wiring, fix auth",
     commands: [
-      { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." },
-      { command: "rig inbox inputs", description: "Questions workers asked (then `rig inbox respond \u2026`)." },
-      { command: "rig review show|set", description: "The completion review gate (Greptile is mandatory on merges)." }
+      { command: "rig doctor", description: "Check every part of the wiring \u2014 run this when anything feels off." },
+      { command: "rig github auth status", description: "GitHub auth state on the selected server." }
     ]
   },
   {
     title: "Extend",
-    subtitle: "more Pi, more plugins",
+    subtitle: "plugins contribute validators, hooks, task sources, commands",
     commands: [
-      { command: "rig pi search <term>", description: "Discover community Pi extensions on npm." },
-      { command: "rig pi add <pkg>", description: "Add a Pi extension to this project (workers pick it up too)." },
-      { command: "rig plugin list", description: "What the rig.config.ts plugins contribute." }
+      { command: "rig plugin list", description: "What the rig.config.ts plugins contribute." },
+      { command: "rig plugin run <command-id>", description: "Execute a plugin-contributed CLI command." }
     ]
   }
 ];
@@ -71,22 +69,20 @@ var PRIMARY_GROUPS = [
       "rig server use local",
       "rig server start --port 3773"
     ],
-    next: ["Use `rig task list` to see server-owned work.", "Use `rig run list` or `rig run attach <id> --follow` to monitor runs."],
-    advanced: ["Compatibility alias: `rig connect ...` remains callable."]
+    next: ["Use `rig task list` to see server-owned work.", "Use `rig run list` or `rig run attach <id> --follow` to monitor runs."]
   },
   {
     name: "task",
     summary: "Find work, start Pi-backed runs, and validate task results.",
     usage: ["rig task <list|next|show|run> [options]"],
     commands: [
-      { command: "list [--assignee <login|@me>] [--state open|closed]", description: "List tasks from the selected server/source.", primary: true },
+      { command: "list [--assignee <login|me|@me>] [--state open|closed]", description: "List tasks from the selected server/source.", primary: true },
       { command: "next [filters]", description: "Render the next matching task as a selected-task card.", primary: true },
       { command: "show <id>|--task <id> [--raw]", description: "Show a human task summary; --raw prints the full payload.", primary: true },
       { command: "run [#<issue>|<task-id>|--next|--task <id>]", description: "Submit a task run; interactive follows with bundled Pi.", primary: true },
       { command: "validate|verify [--task <id>]", description: "Run configured task checks/review gates." },
       { command: "details --task <id>", description: "Show full task info from the configured source." },
       { command: "reopen [--task <id> | --all] [--reason <text>]", description: "Reopen closed task(s) in the configured source." },
-      { command: "reset --task <id>", description: "Compatibility spelling of `reopen --task <id>`." },
       { command: "artifacts|artifact-dir|artifact-write", description: "Inspect or write task artifacts." },
       { command: "report-bug", description: "Create a structured bug report/task." }
     ],
@@ -144,15 +140,54 @@ var PRIMARY_GROUPS = [
     next: ["Rejoin the run after resolving a block: `rig run attach <run-id> --follow`."]
   },
   {
-    name: "review",
-    summary: "Inspect or change completion review gate policy.",
-    usage: ["rig review <show|set>"],
+    name: "stats",
+    summary: "Fleet metrics computed from on-disk run journals (no server required).",
+    usage: ["rig stats [show] [--since <7d|30d|ISO date>]"],
     commands: [
-      { command: "show", description: "Show current review gate settings.", primary: true },
-      { command: "set <off|advisory|required> [--provider greptile]", description: "Change review strictness/provider.", primary: true }
+      { command: "show [--since <window>]", description: "Total runs, completion/failure/needs-attention rates, median run time, steering, stalls, approvals.", primary: true }
     ],
-    examples: ["rig review show", "rig review set required --provider greptile"],
-    next: ["Use `rig inbox approvals` for blocked run handoffs."]
+    examples: [
+      "rig stats",
+      "rig stats --since 7d",
+      "rig stats --since 2026-06-01 --json"
+    ],
+    next: ["Inspect outliers with `rig run list` and `rig run show <run-id>`.", "Use `--json` for the schema'd envelope (see docs/cli-json.md)."]
+  },
+  {
+    name: "inspect",
+    summary: "Inspect logs, artifacts, graphs, failures for a task.",
+    usage: ["rig inspect <logs|artifacts|failures|graph|audit|diff> --task <id>"],
+    commands: [
+      { command: "logs --task <id>", description: "Latest run log for a task (local or selected server).", primary: true },
+      { command: "artifacts --task <id>", description: "List the task's completion artifacts.", primary: true },
+      { command: "failures --task <id>", description: "Recorded failures for a task.", primary: true },
+      { command: "diff --task <id>", description: "Changed files for a task.", primary: true },
+      { command: "graph", description: "Task dependency graph." },
+      { command: "audit", description: "Controlled-command audit trail." }
+    ],
+    examples: ["rig inspect logs --task <id>", "rig inspect diff --task <id>"],
+    next: ["Use `rig stats` for fleet-level metrics across runs."]
+  },
+  {
+    name: "repo",
+    summary: "Repository sync/baseline helpers for the Rig-managed checkout.",
+    usage: ["rig repo <sync|reset-baseline>"],
+    commands: [
+      { command: "sync", description: "Sync project repository state.", primary: true },
+      { command: "reset-baseline", description: "Reset the managed baseline for the repo." }
+    ],
+    examples: ["rig repo sync"]
+  },
+  {
+    name: "plugin",
+    summary: "Plugin listing, validation, and plugin-contributed commands.",
+    usage: ["rig plugin <list|validate|run> [options]"],
+    commands: [
+      { command: "list", description: "List plugins declared in rig.config.ts and their contributions.", primary: true },
+      { command: "validate --task <id>", description: "Run plugin-contributed validators for a task.", primary: true },
+      { command: "run <command-id> [args...]", description: "Execute a plugin-contributed CLI command (also callable as `rig <command-id>`)." }
+    ],
+    examples: ["rig plugin list", "rig plugin run <command-id>"]
   },
   {
     name: "init",
@@ -160,12 +195,14 @@ var PRIMARY_GROUPS = [
     usage: ["rig init [--yes] [--server local|remote] [--repo owner/repo] [--remote-url <url>]"],
     commands: [
       { command: "init", description: "Interactive setup wizard for a new or existing Rig repo.", primary: true },
+      { command: "init --demo", description: "Offline demo project: files task source + 3 sample tasks, zero GitHub.", primary: true },
       { command: "init --yes", description: "Non-interactive setup using detected/default settings.", primary: true },
       { command: "init --server remote --remote-url <url>", description: "Link this repo to a remote Rig server.", primary: true },
       { command: "init --repair", description: "Repair missing private state without replacing project config." }
     ],
     examples: [
       "rig init",
+      "rig init --demo",
       "rig init --yes --repo humanity-org/humanwork",
       "rig init --server remote --remote-url https://where.rig-does.work --repo owner/repo"
     ],
@@ -196,23 +233,19 @@ var PRIMARY_GROUPS = [
   }
 ];
 var ADVANCED_GROUPS = [
-  { name: "connect", summary: "Compatibility alias for `rig server` selection commands.", usage: ["rig connect <status|list|add|use>"], commands: [{ command: "status|list|add|use", description: "Use `rig server ...` for the primary UX." }] },
   { name: "setup", summary: "Bootstrap/check local setup.", usage: ["rig setup <bootstrap|check|preflight>"], commands: [{ command: "bootstrap|check|preflight", description: "Setup helpers." }] },
+  { name: "profile", summary: "Runtime profile/model defaults.", usage: ["rig profile <show|set>"], commands: [{ command: "show", description: "Show active profile." }] },
   {
-    name: "inspect",
-    summary: "Inspect logs, artifacts, graphs, failures for a task.",
-    usage: ["rig inspect <logs|artifacts|failures|graph|audit|diff> --task <id>"],
+    name: "review",
+    summary: "Inspect or change completion review gate policy.",
+    usage: ["rig review <show|set>"],
     commands: [
-      { command: "logs --task <id>", description: "Latest run log for a task (local or selected server)." },
-      { command: "artifacts --task <id>", description: "List the task's completion artifacts." },
-      { command: "failures --task <id>", description: "Recorded failures for a task." },
-      { command: "graph", description: "Task dependency graph." },
-      { command: "audit", description: "Controlled-command audit trail." },
-      { command: "diff --task <id>", description: "Changed files for a task." }
-    ]
+      { command: "show", description: "Show current review gate settings." },
+      { command: "set <off|advisory|required> [--provider greptile]", description: "Change review strictness/provider." }
+    ],
+    examples: ["rig review show", "rig review set required --provider greptile"],
+    next: ["Use `rig inbox approvals` for blocked run handoffs."]
   },
-  { name: "repo", summary: "Repository sync/baseline helpers.", usage: ["rig repo <sync|reset-baseline>"], commands: [{ command: "sync", description: "Sync project repository state." }] },
-  { name: "profile", summary: "Runtime profile/model defaults.", usage: ["rig profile <show|set>"], commands: [{ command: "show", description: "Show active profile." }] },
   {
     name: "browser",
     summary: "Browser/app diagnostics for browser-required tasks.",
@@ -238,16 +271,6 @@ var ADVANCED_GROUPS = [
     examples: ["rig pi search subagents", "rig pi add pi-subagents", "rig pi list"],
     next: ["Config-managed extensions: declare `runtime: { pi: { packages: [...] } }` in rig.config.ts \u2014 workers pick them up automatically."]
   },
-  {
-    name: "plugin",
-    summary: "Plugin listing, validation, and plugin-contributed commands.",
-    usage: ["rig plugin <list|validate|run> [options]"],
-    commands: [
-      { command: "list", description: "List plugins declared in rig.config.ts and their contributions." },
-      { command: "validate --task <id>", description: "Run plugin-contributed validators for a task." },
-      { command: "run <command-id> [args...]", description: "Execute a plugin-contributed CLI command (also callable as `rig <command-id>`)." }
-    ]
-  },
   { name: "queue", summary: "Run task queues locally.", usage: ["rig queue run [options]"], commands: [{ command: "run", description: "Process queue work." }] },
   { name: "agent", summary: "Runtime agent workspace helpers.", usage: ["rig agent <list|prepare|run|cleanup>"], commands: [{ command: "list", description: "List prepared agents." }] },
   { name: "inspector", summary: "Event stream and drift scanners.", usage: ["rig inspector <stream|scan-upstream-drift>"], commands: [{ command: "stream", description: "Stream events." }] },
@@ -320,7 +343,7 @@ function renderGroup(group) {
 function renderTopLevelHelp() {
   return [
     `${heading("rig")} ${pc.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
-    pc.dim("Current path: select a server, choose a task, submit a run, attach with native Pi, clear inbox/review gates."),
+    pc.dim("Current path: select a server, choose a task, submit a run, attach with native Pi, clear inbox gates."),
     "",
     ...TOP_LEVEL_SECTIONS.flatMap((section) => [
       `${pc.bold(pc.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc.dim(section.subtitle)}`,
@@ -341,7 +364,7 @@ function renderAdvancedHelp() {
     `${heading("rig advanced")} \u2014 compatibility, diagnostics, and internal surfaces`,
     "",
     pc.bold("Primary groups"),
-    "  server, task, run, inbox, review, init, doctor, github",
+    "  init, server, task, run, inbox, repo, plugin, inspect, stats, doctor, github",
     "",
     pc.bold("Advanced commands"),
     ...ADVANCED_COMMANDS.map((entry) => commandLine(entry.command, entry.description)),
@@ -349,7 +372,7 @@ function renderAdvancedHelp() {
     pc.bold("Advanced groups"),
     ...ADVANCED_GROUPS.map((group) => commandLine(group.name, group.summary)),
     "",
-    pc.dim("All groups remain callable. Prefer `rig server`, `rig task`, `rig run`, `rig inbox`, and `rig review` for day-to-day work.")
+    pc.dim("All groups remain callable. Prefer `rig server`, `rig task`, `rig run`, and `rig inbox` for day-to-day work.")
   ].join(`
 `);
 }
@@ -360,6 +383,21 @@ function renderGroupHelp(groupName) {
 function listHelpGroups() {
   return ALL_GROUPS.map((group) => group.name);
 }
+function suggestGroupCommandForWord(word) {
+  const normalized = word.trim().toLowerCase();
+  if (!normalized)
+    return null;
+  for (const group of ALL_GROUPS) {
+    for (const entry of group.commands) {
+      const firstToken = entry.command.split(/\s+/)[0] ?? "";
+      const names = firstToken.split("|").map((name) => name.trim().toLowerCase());
+      if (names.includes(normalized)) {
+        return `rig ${group.name} ${normalized}`;
+      }
+    }
+  }
+  return null;
+}
 function shouldUseClackOutput() {
   return Boolean(process.stdout.isTTY) && process.env.RIG_CLI_PLAIN_HELP !== "1";
 }
@@ -392,7 +430,7 @@ function printTopLevelHelp(state = {}) {
     commandLine("--dry-run", "Print the command plan without mutating state.")
   ].join(`
 `), "Global options");
-  outro("init \u2192 task run \u2192 watch/steer \u2192 inbox/review \u2192 merged.");
+  outro("init \u2192 task run \u2192 watch \u2192 inbox \u2192 merged.");
 }
 function printAdvancedHelp() {
   if (!shouldUseClackOutput()) {
@@ -404,7 +442,7 @@ function printAdvancedHelp() {
 `), "Advanced commands");
   note(ADVANCED_GROUPS.map((group) => commandLine(group.name, group.summary)).join(`
 `), "Advanced groups");
-  outro("Primary daily flow: rig server \xB7 rig task \xB7 rig run \xB7 rig inbox \xB7 rig review.");
+  outro("Primary daily flow: rig server \xB7 rig task \xB7 rig run \xB7 rig inbox.");
 }
 function printGroupHelpDocument(groupName) {
   const rendered = renderGroupHelp(groupName) ?? renderTopLevelHelp();
@@ -435,6 +473,7 @@ function printGroupHelpDocument(groupName) {
   outro("Run with --json when scripts need structured output.");
 }
 export {
+  suggestGroupCommandForWord,
   renderTopLevelHelp,
   renderRigBanner,
   renderGroupHelp,

package/dist/src/commands/_json-output.js

@@ -0,0 +1,56 @@
+// @bun
+// packages/cli/src/commands/_json-output.ts
+import { Schema } from "effect";
+import {
+  RigDoctorCheckOutput,
+  RigInboxApprovalsOutput,
+  RigInboxInputsOutput,
+  RigRunListOutput,
+  RigRunShowOutput,
+  RigServerStatusOutput,
+  RigStatsOutput,
+  RigTaskListOutput,
+  RigTaskShowOutput
+} from "@rig/contracts";
+var CLI_OUTPUT_SCHEMAS = {
+  "task list": RigTaskListOutput,
+  "task show": RigTaskShowOutput,
+  "run list": RigRunListOutput,
+  "run show": RigRunShowOutput,
+  "server status": RigServerStatusOutput,
+  "inbox approvals": RigInboxApprovalsOutput,
+  "inbox inputs": RigInboxInputsOutput,
+  "doctor check": RigDoctorCheckOutput,
+  "stats show": RigStatsOutput
+};
+function isCommandOutcomeLike(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const record = value;
+  return typeof record.group === "string" && typeof record.command === "string";
+}
+function buildCliJsonEnvelope(outcome, options = {}) {
+  if (!isCommandOutcomeLike(outcome))
+    return null;
+  const commandKey = `${outcome.group} ${outcome.command}`;
+  const schema = CLI_OUTPUT_SCHEMAS[commandKey];
+  if (!schema)
+    return null;
+  const warn = options.warn ?? ((message) => console.error(message));
+  const envelope = { v: 1, command: commandKey, data: outcome.details ?? {} };
+  try {
+    Schema.decodeUnknownSync(schema)(JSON.parse(JSON.stringify(envelope)));
+    return envelope;
+  } catch (error) {
+    warn(`[rig] --json output for "${commandKey}" failed schema validation; printing legacy payload. ` + `(${error instanceof Error ? error.message.split(`
+`)[0] : String(error)})`);
+    return null;
+  }
+}
+function listSchematizedCliCommands() {
+  return Object.keys(CLI_OUTPUT_SCHEMAS).sort();
+}
+export {
+  listSchematizedCliCommands,
+  buildCliJsonEnvelope
+};