@h-rig/cli 0.0.6-alpha.25 → 0.0.6-alpha.27

package/dist/src/commands.js

@@ -5109,11 +5109,170 @@ Usage: rig init`, 1);
 }
 
 // packages/cli/src/commands/connect.ts
-function parseConnection(alias, value) {
+import { cancel as cancel2, isCancel as isCancel2, select as select2 } from "@clack/prompts";
+
+// packages/cli/src/commands/_cli-format.ts
+import pc3 from "picocolors";
+function stringField(record, key, fallback = "") {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+function arrayField(record, key) {
+  const value = record[key];
+  return Array.isArray(value) ? value.flatMap((entry) => typeof entry === "string" && entry.trim() ? [entry.trim()] : []) : [];
+}
+function rawObject(record) {
+  const raw = record.raw;
+  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+}
+function truncate(value, width) {
+  if (value.length <= width)
+    return value;
+  if (width <= 1)
+    return "\u2026";
+  return `${value.slice(0, width - 1)}\u2026`;
+}
+function pad(value, width) {
+  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+}
+function statusColor(status) {
+  const normalized = status.toLowerCase();
+  if (["completed", "merged", "closed", "done", "accepted", "pass", "selected"].includes(normalized))
+    return pc3.green;
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error"].includes(normalized))
+    return pc3.red;
+  if (["running", "reviewing", "validating", "in_progress", "in-progress", "remote"].includes(normalized))
+    return pc3.cyan;
+  if (["ready", "open", "queued", "created", "preparing", "local"].includes(normalized))
+    return pc3.yellow;
+  return pc3.dim;
+}
+function formatStatusPill(status) {
+  const label = status || "unknown";
+  return statusColor(label)(`\u25CF ${label}`);
+}
+function formatSection(title, subtitle) {
+  return `${pc3.bold(pc3.cyan("\u25C6"))} ${pc3.bold(title)}${subtitle ? pc3.dim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatSuccessCard(title, rows = []) {
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${pc3.dim("\u2502")} ${pc3.dim(key.padEnd(9))} ${value}`);
+  return [formatSection(title), ...body].join(`
+`);
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc3.bold("Next"), ...steps.map((step) => `${pc3.dim("\u203A")} ${step}`)];
+}
+function formatTaskList(tasks, options = {}) {
+  if (options.raw)
+    return tasks.map((task) => JSON.stringify(task)).join(`
+`);
+  if (tasks.length === 0)
+    return [formatSection("Tasks", "none found"), ...formatNextSteps(["Try `rig server status` to confirm the selected server.", "Relax filters or run `rig task run --title ... --initial-prompt ...` for ad hoc work."])].join(`
+`);
+  const rows = tasks.map((task) => {
+    const raw = rawObject(task);
+    const id = stringField(task, "id", "<unknown>");
+    const status = stringField(task, "status", "unknown");
+    const title = stringField(task, "title", "Untitled task");
+    const source = stringField(task, "source", stringField(raw, "source", ""));
+    const labels = arrayField(task, "labels").length > 0 ? arrayField(task, "labels") : arrayField(raw, "labels");
+    return { id, status, title, source, labels };
+  });
+  const idWidth = Math.min(18, Math.max(4, ...rows.map((row) => row.id.length)));
+  const statusWidth = Math.min(16, Math.max(6, ...rows.map((row) => row.status.length)));
+  const header = `${pc3.bold(pad("TASK", idWidth))}  ${pc3.bold(pad("STATUS", statusWidth))}  ${pc3.bold("TITLE")}`;
+  const body = rows.map((row) => {
+    const labels = row.labels.length > 0 ? pc3.dim(`  ${row.labels.slice(0, 4).map((label) => `#${label}`).join(" ")}`) : "";
+    const source = row.source ? pc3.dim(`  ${row.source}`) : "";
+    return [
+      pc3.bold(pad(truncate(row.id, idWidth), idWidth)),
+      statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
+      `${row.title}${labels}${source}`
+    ].join("  ");
+  });
+  return [formatSection("Tasks", `${rows.length} shown`), header, ...body, "", ...formatNextSteps(["Run one: `rig task run <id>` or `rig task run --next`", "Attach later: `rig run attach <run-id> --follow`"])].join(`
+`);
+}
+function formatRunList(runs, options = {}) {
+  if (runs.length === 0) {
+    return [
+      formatSection("Runs", "none recorded"),
+      options.source === "server" ? pc3.dim("No runs recorded on the selected Rig server.") : pc3.dim("No runs recorded in .rig/runs."),
+      "",
+      ...formatNextSteps(["Start one: `rig task run --next`", "Check server: `rig server status`"])
+    ].join(`
+`);
+  }
+  const rows = runs.map((run) => {
+    const runId = stringField(run, "runId", stringField(run, "id", "(unknown-run)"));
+    const status = stringField(run, "status", "unknown");
+    const taskId = stringField(run, "taskId", "");
+    const title = stringField(run, "title", taskId || "(untitled)");
+    const runtime = stringField(run, "runtimeAdapter", "");
+    return { runId, status, title, runtime };
+  });
+  const idWidth = Math.min(36, Math.max(6, ...rows.map((row) => row.runId.length)));
+  const statusWidth = Math.min(16, Math.max(6, ...rows.map((row) => row.status.length)));
+  const header = `${pc3.bold(pad("RUN", idWidth))}  ${pc3.bold(pad("STATUS", statusWidth))}  ${pc3.bold("TITLE")}`;
+  const body = rows.map((row) => [
+    pc3.bold(pad(truncate(row.runId, idWidth), idWidth)),
+    statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
+    `${row.title}${row.runtime ? pc3.dim(`  ${row.runtime}`) : ""}`
+  ].join("  "));
+  return [formatSection("Runs", options.source === "server" ? "selected server" : "local state"), header, ...body, "", ...formatNextSteps(["Follow live: `rig run attach <run-id> --follow`", "Details: `rig run show --run <run-id>`"])].join(`
+`);
+}
+function formatSubmittedRun(input) {
+  const rows = [["run", pc3.bold(input.runId)]];
+  if (input.task) {
+    const id = stringField(input.task, "id", "<unknown>");
+    const status = stringField(input.task, "status", "unknown");
+    const title = stringField(input.task, "title", "Untitled task");
+    rows.push(["task", `${pc3.bold(id)} ${formatStatusPill(status)} ${title}`]);
+  }
+  return [
+    formatSuccessCard("Run submitted", rows),
+    "",
+    ...formatNextSteps([`Attach: \`rig run attach ${input.runId} --follow\``, `Inspect: \`rig run show --run ${input.runId}\``])
+  ].join(`
+`);
+}
+function formatConnectionList(connections) {
+  const rows = [["local", { kind: "local", mode: "auto" }], ...Object.entries(connections)];
+  const aliasWidth = Math.min(24, Math.max(5, ...rows.map(([alias]) => alias.length)));
+  const lines = rows.map(([alias, connection]) => [
+    pc3.bold(pad(truncate(alias, aliasWidth), aliasWidth)),
+    formatStatusPill(connection.kind),
+    connection.kind === "remote" ? connection.baseUrl ?? "" : connection.mode ?? "local"
+  ].join("  "));
+  return [formatSection("Rig servers", `${rows.length} available`), `${pc3.bold(pad("ALIAS", aliasWidth))}  ${pc3.bold("KIND")}  ${pc3.bold("TARGET")}`, ...lines, "", ...formatNextSteps(["Select one: `rig server use <alias|local>`"])].join(`
+`);
+}
+function formatConnectionStatus(selected, connections) {
+  const connection = selected === "local" ? { kind: "local", mode: "auto" } : connections[selected];
+  const target = !connection ? "not configured" : connection.kind === "remote" ? connection.baseUrl : "local";
+  return [
+    formatSection("Rig server", "selected for this repo"),
+    `${pc3.dim("\u2502")} ${pc3.dim("selected ")} ${pc3.bold(selected)}`,
+    `${pc3.dim("\u2502")} ${pc3.dim("kind     ")} ${formatStatusPill(connection?.kind ?? "unknown")}`,
+    `${pc3.dim("\u2502")} ${pc3.dim("target   ")} ${target ?? "not configured"}`,
+    "",
+    ...formatNextSteps(["Change: `rig server use <alias|local>`", "List saved servers: `rig server list`"])
+  ].join(`
+`);
+}
+
+// packages/cli/src/commands/connect.ts
+function usageName(options) {
+  return `rig ${options.group}`;
+}
+function parseConnection(alias, value, options) {
   if (alias === "local" && !value)
     return { kind: "local", mode: "auto" };
   if (!value)
-    throw new CliError2("Missing remote server URL. Usage: rig connect add <alias> <url>", 1);
+    throw new CliError2(`Missing remote server URL. Usage: ${usageName(options)} add <alias> <url>`, 1);
   let parsed;
   try {
     parsed = new URL(value);
@@ -5132,54 +5291,89 @@ function printJsonOrText(context, payload, text2) {
     console.log(text2);
   }
 }
-async function executeConnect(context, args) {
+async function promptForConnectionAlias(context) {
+  const state = readGlobalConnections();
+  const repo = readRepoConnection(context.projectRoot);
+  const options = [
+    { value: "local", label: "local", hint: "Use/start a local Rig server" },
+    ...Object.entries(state.connections).map(([alias, connection]) => ({
+      value: alias,
+      label: alias,
+      hint: connection.kind === "remote" ? connection.baseUrl : "local"
+    }))
+  ].filter((option, index, all) => all.findIndex((candidate) => candidate.value === option.value) === index);
+  const answer = await select2({
+    message: "Select Rig server for this repo",
+    initialValue: repo?.selected ?? "local",
+    options
+  });
+  if (isCancel2(answer)) {
+    cancel2("No server selected.");
+    throw new CliError2("No server selected.", 3);
+  }
+  return String(answer);
+}
+async function executeConnectionCommand(context, args, options) {
   const [command, ...rest] = args;
   switch (command ?? "status") {
     case "list": {
-      requireNoExtraArgs(rest, "rig connect list");
+      requireNoExtraArgs(rest, `${usageName(options)} list`);
       const state = readGlobalConnections();
-      printJsonOrText(context, state, Object.entries(state.connections).map(([alias, connection]) => `${alias}	${connection.kind === "remote" ? connection.baseUrl : "local"}`).join(`
-`) || "No Rig connections configured.");
-      return { ok: true, group: "connect", command: "list", details: state };
+      printJsonOrText(context, state, formatConnectionList(state.connections));
+      return { ok: true, group: options.group, command: "list", details: state };
     }
     case "add": {
       const [alias, url, ...extra] = rest;
       if (!alias)
-        throw new CliError2("Missing alias. Usage: rig connect add <alias> <url>", 1);
-      requireNoExtraArgs(extra, "rig connect add <alias> <url>");
-      const connection = parseConnection(alias, url);
+        throw new CliError2(`Missing alias. Usage: ${usageName(options)} add <alias> <url>`, 1);
+      requireNoExtraArgs(extra, `${usageName(options)} add <alias> <url>`);
+      const connection = parseConnection(alias, url, options);
       const state = upsertGlobalConnection(alias, connection);
-      printJsonOrText(context, { alias, connection }, `Added Rig connection ${alias}.`);
-      return { ok: true, group: "connect", command: "add", details: { alias, connection, count: Object.keys(state.connections).length } };
+      printJsonOrText(context, { alias, connection }, formatSuccessCard("Rig server saved", [
+        ["alias", alias],
+        ["target", connection.kind === "remote" ? connection.baseUrl : "local"],
+        ["next", `${usageName(options)} use ${alias}`]
+      ]));
+      return { ok: true, group: options.group, command: "add", details: { alias, connection, count: Object.keys(state.connections).length } };
     }
     case "use": {
-      const [alias, ...extra] = rest;
+      let [alias, ...extra] = rest;
+      requireNoExtraArgs(extra, `${usageName(options)} use <alias|local>`);
+      if (!alias && options.interactiveUse && context.outputMode === "text" && process.stdin.isTTY) {
+        alias = await promptForConnectionAlias(context);
+      }
       if (!alias)
-        throw new CliError2("Missing alias. Usage: rig connect use <alias|local>", 1);
-      requireNoExtraArgs(extra, "rig connect use <alias|local>");
+        throw new CliError2(`Missing alias. Usage: ${usageName(options)} use <alias|local>`, 1);
       if (alias !== "local") {
         const state = readGlobalConnections();
         if (!state.connections[alias])
-          throw new CliError2(`Unknown Rig connection: ${alias}`, 1);
+          throw new CliError2(`Unknown Rig server: ${alias}`, 1);
       }
       const repoState = { selected: alias, linkedAt: new Date().toISOString() };
       writeRepoConnection(context.projectRoot, repoState);
-      printJsonOrText(context, repoState, `Selected Rig connection ${alias} for this repo.`);
-      return { ok: true, group: "connect", command: "use", details: repoState };
+      printJsonOrText(context, repoState, formatSuccessCard("Rig server selected", [
+        ["selected", alias],
+        ["scope", "this repo"],
+        ["next", "rig task list"]
+      ]));
+      return { ok: true, group: options.group, command: "use", details: repoState };
     }
     case "status": {
-      requireNoExtraArgs(rest, "rig connect status");
+      requireNoExtraArgs(rest, `${usageName(options)} status`);
       const repo = readRepoConnection(context.projectRoot);
       const global = readGlobalConnections();
       const details = { selected: repo?.selected ?? "local", repo, connections: global.connections };
-      printJsonOrText(context, details, `Selected Rig connection: ${details.selected}`);
-      return { ok: true, group: "connect", command: "status", details };
+      printJsonOrText(context, details, formatConnectionStatus(details.selected, global.connections));
+      return { ok: true, group: options.group, command: "status", details };
     }
     default:
-      throw new CliError2(`Unknown connect command: ${String(command)}
-Usage: rig connect <list|add|use|status>`, 1);
+      throw new CliError2(`Unknown ${options.group} command: ${String(command)}
+Usage: ${usageName(options)} <list|add|use|status>`, 1);
   }
 }
+async function executeConnect(context, args) {
+  return executeConnectionCommand(context, args, { group: "connect" });
+}
 
 // packages/cli/src/commands/github.ts
 import { spawnSync as spawnSync2 } from "child_process";
@@ -7114,107 +7308,6 @@ async function attachRunOperatorView(context, input) {
   return { ...snapshot, steered, detached };
 }
 
-// packages/cli/src/commands/_cli-format.ts
-import pc3 from "picocolors";
-function stringField(record, key, fallback = "") {
-  const value = record[key];
-  return typeof value === "string" && value.trim() ? value.trim() : fallback;
-}
-function arrayField(record, key) {
-  const value = record[key];
-  return Array.isArray(value) ? value.flatMap((entry) => typeof entry === "string" && entry.trim() ? [entry.trim()] : []) : [];
-}
-function rawObject(record) {
-  const raw = record.raw;
-  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
-}
-function truncate(value, width) {
-  if (value.length <= width)
-    return value;
-  if (width <= 1)
-    return "\u2026";
-  return `${value.slice(0, width - 1)}\u2026`;
-}
-function pad(value, width) {
-  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
-}
-function statusColor(status) {
-  const normalized = status.toLowerCase();
-  if (["completed", "merged", "closed", "done", "accepted"].includes(normalized))
-    return pc3.green;
-  if (["failed", "needs_attention", "needs-attention", "blocked"].includes(normalized))
-    return pc3.red;
-  if (["running", "reviewing", "validating", "in_progress", "in-progress"].includes(normalized))
-    return pc3.cyan;
-  if (["ready", "open", "queued", "created", "preparing"].includes(normalized))
-    return pc3.yellow;
-  return pc3.dim;
-}
-function formatTaskList(tasks, options = {}) {
-  if (tasks.length === 0)
-    return pc3.dim("No matching tasks.");
-  if (options.raw)
-    return tasks.map((task) => JSON.stringify(task)).join(`
-`);
-  const rows = tasks.map((task) => {
-    const raw = rawObject(task);
-    const id = stringField(task, "id", "<unknown>");
-    const status = stringField(task, "status", "unknown");
-    const title = stringField(task, "title", "Untitled task");
-    const source = stringField(task, "source", stringField(raw, "source", ""));
-    const labels = arrayField(task, "labels").length > 0 ? arrayField(task, "labels") : arrayField(raw, "labels");
-    return { id, status, title, source, labels };
-  });
-  const idWidth = Math.min(18, Math.max(4, ...rows.map((row) => row.id.length)));
-  const statusWidth = Math.min(16, Math.max(6, ...rows.map((row) => row.status.length)));
-  const header = `${pc3.bold(pad("TASK", idWidth))}  ${pc3.bold(pad("STATUS", statusWidth))}  ${pc3.bold("TITLE")}`;
-  const body = rows.map((row) => {
-    const labels = row.labels.length > 0 ? pc3.dim(`  ${row.labels.slice(0, 4).map((label) => `#${label}`).join(" ")}`) : "";
-    const source = row.source ? pc3.dim(`  ${row.source}`) : "";
-    return [
-      pc3.bold(pad(truncate(row.id, idWidth), idWidth)),
-      statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
-      `${row.title}${labels}${source}`
-    ].join("  ");
-  });
-  return [pc3.bold("Rig tasks"), header, ...body].join(`
-`);
-}
-function formatRunList(runs, options = {}) {
-  if (runs.length === 0) {
-    return pc3.dim(options.source === "server" ? "No runs recorded on the selected Rig server." : "No runs recorded in .rig/runs.");
-  }
-  const rows = runs.map((run) => {
-    const runId = stringField(run, "runId", stringField(run, "id", "(unknown-run)"));
-    const status = stringField(run, "status", "unknown");
-    const taskId2 = stringField(run, "taskId", "");
-    const title = stringField(run, "title", taskId2 || "(untitled)");
-    const runtime = stringField(run, "runtimeAdapter", "");
-    return { runId, status, title, runtime };
-  });
-  const idWidth = Math.min(36, Math.max(6, ...rows.map((row) => row.runId.length)));
-  const statusWidth = Math.min(16, Math.max(6, ...rows.map((row) => row.status.length)));
-  const header = `${pc3.bold(pad("RUN", idWidth))}  ${pc3.bold(pad("STATUS", statusWidth))}  ${pc3.bold("TITLE")}`;
-  const body = rows.map((row) => [
-    pc3.bold(pad(truncate(row.runId, idWidth), idWidth)),
-    statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
-    `${row.title}${row.runtime ? pc3.dim(`  ${row.runtime}`) : ""}`
-  ].join("  "));
-  return [pc3.bold(options.source === "server" ? "Rig runs (server)" : "Rig runs"), header, ...body].join(`
-`);
-}
-function formatSubmittedRun(input) {
-  const lines = [`${pc3.green("Run submitted")}: ${pc3.bold(input.runId)}`];
-  if (input.task) {
-    const id = stringField(input.task, "id", "<unknown>");
-    const status = stringField(input.task, "status", "unknown");
-    const title = stringField(input.task, "title", "Untitled task");
-    lines.push(`${pc3.dim("task")} ${pc3.bold(id)} ${statusColor(status)(status)} ${title}`);
-  }
-  return lines.join(`
-`);
-}
-
 // packages/cli/src/commands/run.ts
 function normalizeRemoteRunDetails(payload) {
   const run = payload.run;
@@ -7617,7 +7710,10 @@ async function executeRun(context, args) {
 
 // packages/cli/src/commands/server.ts
 async function executeServer(context, args, options) {
-  const [command = "start", ...rest] = args;
+  const [command = "status", ...rest] = args;
+  if (["status", "list", "add", "use"].includes(command)) {
+    return executeConnectionCommand(context, [command, ...rest], { group: "server", interactiveUse: true });
+  }
   switch (command) {
     case "start": {
       let pending = rest;
@@ -7629,7 +7725,7 @@ async function executeServer(context, args, options) {
       pending = pollResult.rest;
       const authTokenResult = takeOption(pending, "--auth-token");
       pending = authTokenResult.rest;
-      requireNoExtraArgs(pending, "bun run rig server start [--host <host>] [--port <n>] [--poll-ms <n>] [--auth-token <token>]");
+      requireNoExtraArgs(pending, "rig server start [--host <host>] [--port <n>] [--poll-ms <n>] [--auth-token <token>]");
       const commandParts = ["rig-server", "start"];
       if (hostResult.value) {
         commandParts.push("--host", hostResult.value);
@@ -7652,7 +7748,7 @@ async function executeServer(context, args, options) {
       let pending = rest;
       const eventResult = takeOption(pending, "--event");
       pending = eventResult.rest;
-      requireNoExtraArgs(pending, "bun run rig server notify-test [--event <type>]");
+      requireNoExtraArgs(pending, "rig server notify-test [--event <type>]");
       const commandParts = ["rig-server", "notify-test"];
       if (eventResult.value) {
         commandParts.push("--event", eventResult.value);
@@ -7680,7 +7776,7 @@ async function executeServer(context, args, options) {
       pending = dirtyBaselineResult.rest;
       const prResult = takeOption(pending, "--pr");
       pending = prResult.rest;
-      requireNoExtraArgs(pending, "bun run rig --run-id <run-id> server task-run [--task <id>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>] [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>] [--dirty-baseline head|dirty-snapshot] [--pr auto|ask|off]");
+      requireNoExtraArgs(pending, "rig --run-id <run-id> server task-run [--task <id>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>] [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>] [--dirty-baseline head|dirty-snapshot] [--pr auto|ask|off]");
       if (!taskResult.value && !initialPromptResult.value && !titleResult.value) {
         throw new CliError2("server task-run requires either --task <id> or --initial-prompt/--title for an ad hoc run.", 2);
       }
@@ -7717,7 +7813,7 @@ async function executeServer(context, args, options) {
 import { readFileSync as readFileSync9 } from "fs";
 import { spawnSync as spawnSync3 } from "child_process";
 import { resolve as resolve19 } from "path";
-import { cancel as cancel3, confirm as confirm2, isCancel as isCancel3 } from "@clack/prompts";
+import { cancel as cancel4, confirm as confirm2, isCancel as isCancel4 } from "@clack/prompts";
 import {
   taskArtifactDir,
   taskArtifacts,
@@ -7735,7 +7831,7 @@ import {
 } from "@rig/runtime/control-plane/native/task-ops";
 
 // packages/cli/src/commands/_task-picker.ts
-import { cancel as cancel2, isCancel as isCancel2, select as select2 } from "@clack/prompts";
+import { cancel as cancel3, isCancel as isCancel3, select as select3 } from "@clack/prompts";
 function taskId2(task) {
   return typeof task.id === "string" && task.id.trim() ? task.id : "<unknown>";
 }
@@ -7769,12 +7865,12 @@ async function selectTaskWithTextPicker(tasks, io = {}) {
     label: `${taskId2(task)} \xB7 ${typeof task.title === "string" && task.title.trim() ? task.title.trim() : "Untitled task"}`,
     hint: typeof task.status === "string" && task.status.trim() ? task.status.trim() : undefined
   }));
-  const answer = await select2({
+  const answer = await select3({
     message: "Select Rig task",
     options
   });
-  if (isCancel2(answer)) {
-    cancel2("No task selected.");
+  if (isCancel3(answer)) {
+    cancel3("No task selected.");
     return null;
   }
   const index = Number.parseInt(String(answer), 10);
@@ -7894,8 +7990,8 @@ async function resolveDirtyBaselineForTaskRun(context, explicit) {
       message: "Include current uncommitted changes in run baseline?",
       initialValue: false
     });
-    if (isCancel3(answer)) {
-      cancel3("Run cancelled.");
+    if (isCancel4(answer)) {
+      cancel4("Run cancelled.");
       throw new CliError2("Run cancelled by user.", 1);
     }
     return { mode: answer ? "dirty-snapshot" : "head", state };
@@ -10481,6 +10577,200 @@ Warnings:`);
   }
 }
 
+// packages/cli/src/commands/_help-catalog.ts
+import pc4 from "picocolors";
+var PRIMARY_GROUPS = [
+  {
+    name: "init",
+    summary: "Set up Rig for this repo: server, GitHub auth, checkout strategy, task source, and Pi wiring.",
+    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 --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 --yes --repo humanity-org/humanwork",
+      "rig init --server remote --remote-url https://where.rig-does.work --repo owner/repo"
+    ],
+    next: ["After init, run `rig server status`.", "Then use `rig task list` and `rig task run --next` for day-to-day work."]
+  },
+  {
+    name: "server",
+    summary: "Choose, inspect, and start the Rig server that owns tasks and runs.",
+    usage: ["rig server <status|list|add|use|start> [options]"],
+    commands: [
+      { command: "status", description: "Show the selected server for this repo.", primary: true },
+      { command: "list", description: "List saved local/remote server aliases.", primary: true },
+      { command: "add <alias> <url>", description: "Save a remote Rig server URL.", primary: true },
+      { command: "use [alias|local]", description: "Select a server; prompts in an interactive TTY.", primary: true },
+      { command: "start [--host <host>] [--port <n>]", description: "Start a local rig-server process.", primary: true }
+    ],
+    examples: [
+      "rig server status",
+      "rig server add prod https://where.rig-does.work",
+      "rig server use prod",
+      "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."]
+  },
+  {
+    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: "next [filters]", description: "Pick the next matching task.", primary: true },
+      { command: "show <id>|--task <id>", description: "Show task details.", 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: "artifacts|artifact-dir|artifact-write", description: "Inspect or write task artifacts." },
+      { command: "report-bug", description: "Create a structured bug report/task." }
+    ],
+    examples: [
+      "rig task list --assignee @me --limit 20",
+      "rig task run --next",
+      "rig task run #123 --runtime-adapter pi",
+      "rig task run --title 'Investigate deploy drift' --initial-prompt 'Check server health'"
+    ],
+    next: ["Use `--detach` to submit without attaching.", "Use `rig run attach <run-id> --follow` to rejoin a live run."]
+  },
+  {
+    name: "run",
+    summary: "Observe, attach to, and control Rig runs.",
+    usage: ["rig run <list|status|show|attach|stop> [options]"],
+    commands: [
+      { command: "list", description: "List recent runs from the selected server or local state.", primary: true },
+      { command: "status", description: "Summarize active and recent runs.", primary: true },
+      { command: "show --run <id>", description: "Show one run record.", primary: true },
+      { command: "attach <run-id>|--run <id> [--follow]", description: "Attach to the run; `--follow` launches native bundled Pi for live Pi runs.", primary: true },
+      { command: "stop [<run-id>|--run <id>]", description: "Request stop for one run or local active runs.", primary: true },
+      { command: "timeline --run <id> [--follow]", description: "Stream raw run timeline events." },
+      { command: "delete|cleanup", description: "Remove completed run records/artifacts." }
+    ],
+    examples: [
+      "rig run list",
+      "rig run attach 01234567-89ab-cdef-0123-456789abcdef --follow",
+      "rig run show --run <run-id>",
+      "rig run stop <run-id>"
+    ],
+    next: ["Use `rig task run --next` to create a new run.", "Use `--json` when scripts need the full structured record."]
+  }
+];
+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: "github", summary: "GitHub auth helpers.", usage: ["rig github auth <status|import-gh|token>"], commands: [{ command: "auth status", description: "Show GitHub auth state." }] },
+  { name: "doctor", summary: "Diagnostics for project/server/GitHub/Pi state.", usage: ["rig doctor [check|run|shared|...]"], commands: [{ command: "check", description: "Run diagnostics." }] },
+  { name: "setup", summary: "Bootstrap/check local setup.", usage: ["rig setup <bootstrap|check|preflight>"], commands: [{ command: "bootstrap|check|preflight", description: "Setup helpers." }] },
+  { name: "inspect", summary: "Inspect logs, artifacts, graphs, failures.", usage: ["rig inspect <logs|artifacts|failures|graph|audit|diff>"], commands: [{ command: "logs --task <id>", description: "Inspect task logs." }] },
+  { 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: "review", summary: "Review policy configuration.", usage: ["rig review <show|set>"], commands: [{ command: "show", description: "Show review settings." }] },
+  { name: "browser", summary: "Browser/app diagnostics.", usage: ["rig browser <help|explain|demo|app>"], commands: [{ command: "help", description: "Browser command help." }] },
+  { name: "plugin", summary: "Plugin validation/listing.", usage: ["rig plugin <list|validate>"], commands: [{ command: "list", description: "List plugins." }] },
+  { 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." }] },
+  { name: "dist", summary: "Build/install packaged Rig CLI.", usage: ["rig dist <build|install|doctor>"], commands: [{ command: "build", description: "Build distribution." }] },
+  { name: "workspace", summary: "Workspace topology/service helpers.", usage: ["rig workspace <summary|topology|remote-hosts>"], commands: [{ command: "summary", description: "Show workspace summary." }] },
+  { name: "remote", summary: "Legacy remote orchestration controls.", usage: ["rig remote <status|watch|pause|resume|...>"], commands: [{ command: "status", description: "Show remote state." }] },
+  { name: "inbox", summary: "Approval/input inbox for blocked runs.", usage: ["rig inbox <approvals|approve|inputs|respond>"], commands: [{ command: "approvals", description: "List pending approvals." }] },
+  { name: "git", summary: "Pass through to Rig git-flow helper.", usage: ["rig git <args...>"], commands: [{ command: "<args...>", description: "Advanced git flow operations." }] },
+  { name: "harness", summary: "Pass through to runtime harness CLI.", usage: ["rig harness <args...>"], commands: [{ command: "<args...>", description: "Advanced harness operations." }] },
+  { name: "test", summary: "Project test wrappers.", usage: ["rig test <unit|e2e|all>"], commands: [{ command: "all", description: "Run configured project tests." }] }
+];
+var ALL_GROUPS = [...PRIMARY_GROUPS, ...ADVANCED_GROUPS];
+function heading(title) {
+  return pc4.bold(pc4.cyan(title));
+}
+function commandLine(command, description) {
+  const commandColumn = command.length >= 34 ? `${command}  ` : command.padEnd(34);
+  return `${pc4.dim("\u2502")} ${pc4.bold(commandColumn)} ${description}`;
+}
+function renderGroup(group) {
+  const lines = [
+    `${heading(`rig ${group.name}`)} \u2014 ${group.summary}`,
+    "",
+    pc4.bold("Usage"),
+    ...group.usage.map((line) => `  ${line}`),
+    "",
+    pc4.bold("Commands"),
+    ...group.commands.map((entry) => commandLine(entry.command, entry.description))
+  ];
+  if (group.examples?.length) {
+    lines.push("", pc4.bold("Examples"), ...group.examples.map((line) => `  ${pc4.dim("$")} ${line}`));
+  }
+  if (group.next?.length) {
+    lines.push("", pc4.bold("Next steps"), ...group.next.map((line) => `  ${pc4.dim("\u203A")} ${line}`));
+  }
+  if (group.advanced?.length) {
+    lines.push("", pc4.bold("Compatibility / advanced"), ...group.advanced.map((line) => `  ${pc4.dim("\u203A")} ${line}`));
+  }
+  return lines.join(`
+`);
+}
+function renderTopLevelHelp() {
+  return [
+    `${heading("rig")} ${pc4.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
+    pc4.dim("A repo-local CLI for setup, server selection, task runs, live attach, and completion review."),
+    "",
+    `${pc4.bold(pc4.magenta("\u25C7 Start here"))} \u2014 ${pc4.dim("bootstrap a repo and choose where Rig runs")}`,
+    commandLine("rig init", "Interactive setup: project config, GitHub auth, task source, server, checkout, Pi."),
+    commandLine("rig init --yes", "Non-interactive setup using detected defaults; good for repeatable installs."),
+    commandLine("rig server status", "Show whether this repo is using local Rig or a remote server."),
+    commandLine("rig server use <alias|local>", "Switch the server that owns task/run state for this repo."),
+    "",
+    `${pc4.bold(pc4.magenta("\u25C7 Daily task loop"))} \u2014 ${pc4.dim("find work, start a worker, and rejoin it later")}`,
+    commandLine("rig task list", "List tasks from the selected task source/server with status, labels, and source."),
+    commandLine("rig task next", "Pick the next matching task without starting it."),
+    commandLine("rig task run --next", "Start the next task and attach to the live bundled Pi frontend."),
+    commandLine("rig task run #123 --detach", "Submit a specific issue/task and return immediately."),
+    "",
+    `${pc4.bold(pc4.magenta("\u25C7 Live run control"))} \u2014 ${pc4.dim("observe, steer, stop, or inspect active runs")}`,
+    commandLine("rig run list", "Show recent/active runs from the selected server or local state."),
+    commandLine("rig run attach <run-id> --follow", "Open the native Pi live view for a worker-backed run."),
+    commandLine("rig run show --run <id>", "Print one run record; add `--json` for automation."),
+    commandLine("rig run stop <run-id>", "Request cancellation for a running worker."),
+    "",
+    `${pc4.bold(pc4.magenta("\u25C7 Core groups"))} \u2014 ${pc4.dim("run `rig <group> --help` for detailed commands and examples")}`,
+    ...PRIMARY_GROUPS.map((group) => commandLine(group.name, group.summary)),
+    commandLine("doctor", "Diagnose project/server/GitHub/task/Pi wiring when setup or runs misbehave."),
+    "",
+    `${pc4.bold(pc4.magenta("\u25C7 More"))}`,
+    commandLine("rig help --advanced", "Legacy, dev, diagnostics, browser, queue, agent, remote, git, harness commands."),
+    commandLine("rig <group> --help", "Rich per-group help with usage, descriptions, examples, and next steps."),
+    commandLine("rig --version", "Print the installed Rig CLI version."),
+    "",
+    `${pc4.bold(pc4.magenta("\u25C7 Global options"))}`,
+    commandLine("--project <path>", "Use a project root instead of auto-discovery."),
+    commandLine("--json", "Emit structured output for scripts/agents."),
+    commandLine("--dry-run", "Print the command plan without mutating state.")
+  ].join(`
+`);
+}
+function renderAdvancedHelp() {
+  return [
+    `${heading("rig advanced")} \u2014 legacy, dev, and compatibility groups`,
+    "",
+    pc4.bold("Primary groups are still"),
+    "  init, server, task, run",
+    "",
+    pc4.bold("Advanced groups"),
+    ...ADVANCED_GROUPS.map((group) => commandLine(group.name, group.summary)),
+    "",
+    pc4.dim("All groups remain callable. Prefer `rig server`, `rig task`, and `rig run` for day-to-day work.")
+  ].join(`
+`);
+}
+function renderGroupHelp(groupName) {
+  const group = ALL_GROUPS.find((candidate) => candidate.name === groupName);
+  return group ? renderGroup(group) : null;
+}
+
 // packages/cli/src/commands.ts
 import { ensureProjectMainFreshBeforeRun as ensureProjectMainFreshBeforeRun2 } from "@rig/runtime/control-plane/project-main-pre-run-sync";
 var TOP_LEVEL_ALIASES = {
@@ -10548,102 +10838,13 @@ var GROUPS = new Set([
   "test"
 ]);
 function printGroupHelp(group) {
-  const lines = helpText().split(`
-`);
-  const groupLineRe = new RegExp(`^  ${group}\\b`);
-  const out = [`rig ${group} \u2014 command group`, ""];
-  let inGroup = false;
-  for (const line of lines) {
-    if (groupLineRe.test(line)) {
-      inGroup = true;
-      out.push(line);
-      continue;
-    }
-    if (inGroup) {
-      if (line.startsWith("          ") || line.startsWith("                  ")) {
-        out.push(line);
-      } else {
-        break;
-      }
-    }
-  }
-  if (out.length === 2) {
-    console.log(helpText());
-    return;
-  }
-  console.log(out.join(`
-`));
+  console.log(renderGroupHelp(group) ?? helpText());
 }
 function isHelpArg(arg) {
   return arg === "--help" || arg === "-h" || arg === "help";
 }
 function helpText() {
-  return [
-    "rig - Event-driven Bun control plane for Project Rig",
-    "",
-    "Usage:",
-    "  rig <group> <command> [options]",
-    "  rig <alias-command> [options]",
-    "  (compat: bun run rig ...)",
-    "",
-    "Groups:",
-    "  init    [--server local|remote] [--remote-url <url>] [--repo owner/repo] [--github-auth gh|token|device|skip]",
-    "          [--github-token <token>] [--github-project off|<project-id>] [--github-project-status-field <id>]",
-    "          [--remote-checkout managed-clone|current-ref|uploaded-snapshot|existing-path] [--existing-path <path>] [--repair|--private-state-only] [--yes]",
-    "  connect list | add <alias> <url> | use <alias|local> | status",
-    "  github auth status | auth import-gh | auth token --token <token>",
-    "  doctor run shared server/project/GitHub/Projects/projection/labels/Pi/pi-rig/PR/checkout diagnostics",
-    "  setup   bootstrap | check | setup | preflight | install-agent-shell",
-    "  run     status | attach <run-id> [--message <text>] [--once|--follow] | start | start-parallel | start-serial | resume | stop | list | show --run <id> | timeline --run <id> [--follow]",
-    "          delete --run <id> [--purge-artifacts] | cleanup --all [--keep-artifacts] [--keep-runtimes] [--keep-queue]",
-    "          start flags: [--epic <id>] [--prompt-epic|--no-epic-prompt] [--ws-port <n>] [--server-host <host>] [--server-port <n>] [--poll-ms <n>] [--no-server]",
-    "  task    list|next [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state <state>] [--status <status>] [--limit <n>]",
-    "          run [#<issue>|<task-id>|--next|--task <id>] [--detach] [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state <state>] [--status <status>] [--limit <n>] [--skip-project-sync]",
-    "          info | scope [--files] | deps | ready | validate [--task <id>] | verify [--task <id>]",
-    "          lookup <id> | record <decision|failure> <text> | artifacts | reset --task <id> | details --task <id>",
-    "          artifact-dir | artifact-write <filename> [--file <path>]",
-    "          report-bug [--no-prompt] [--no-beads] [--browser|--no-browser] [--title <text>] [--url <url>] [--environment local|shared-dev|staging|production|custom]",
-    "          report-bug flags: [--summary <text>] [--steps <a;b>] [--expected <text>] [--actual <text>] [--evidence <a;b>] [--asset <dragged-file>] [--video <dragged-file>] [--screenshot <path>]",
-    "                            [--priority P0-P4] [--labels <a,b>] [--parent <task-id>] [--assignee <name>] [--owner <email>]",
-    "                            [--preset <name>] [--profile <name>] [--attach-url <url>] [--state-dir <path>] [--mode <mode>] [--viewport <WxH>]",
-    "                            [--output-dir <path>] [--slug <slug>] [--overwrite]",
-    "          reopen [--task <id> | --all] [--reason <text>]",
-    "  inspect logs --task <id> | artifacts --task <id> | artifact --task <id> --file <name> | failures | graph | audit | diff [--task <id>]",
-    "  repo    sync [--task <id>] | reset-baseline [--keep-task-status]",
-    "  profile show | set <claude-code|codex-cli|pi> | set [--model ...] [--runtime ...] [--plugin ...]",
-    "  review  show | set <off|advisory|required> [--provider greptile]",
-    "  browser help | explain | demo | app <dev|start|check|e2e|reset> (set RIG_BROWSER_APP=<slug>) | cdp-probe | profile-persistence | profile-lock-check",
-    "  plugin  list | validate --task <id>",
-    "  queue   run [--workers <n>] [--max-tasks <n>] [--action validate|verify|pipeline] [--isolation off|worktree] [--no-runtime-reuse] [--fail-fast] [--skip-project-sync]",
-    "  agent   list | prepare [--id <id>] [--mode worktree] | run [--id <id>] [--mode worktree] [--skip-project-sync] -- <command...> | cleanup (--id <id> | --all)",
-    "          cleanup is runtime-only; use run cleanup to remove authority runs, logs, artifacts, and queue state",
-    "  inspector stream [--once] [--seconds <n>] [--poll-ms <n>] | scan-upstream-drift [--scan-id <id>]",
-    "  server  start [--host <host>] [--port <n>] [--poll-ms <n>] [--auth-token <token>]",
-    "          notify-test [--event <type>] | task-run [--task <id>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>]",
-    "                   [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>]",
-    "  dist    build [--output-dir <dir>] | install [--scope user|system] [--path <dir>] | doctor | rebuild-agent",
-    "  workspace summary | topology | remote-hosts | service-fabric <status|up|verify|down> [--service <name>]",
-    "  remote  test | status | tasks | watch [--seconds <n>] [--event <type>] | pause | resume | stop | continue | refresh",
-    "          add-iterations --count <n> | remove-iterations --count <n> | prompt-preview --task <id> | iteration-output --task <id>",
-    "          orchestrate-start [--max-workers <n>] [--max-iterations <n>] [--direct-merge]",
-    "          orchestrate-pause --id <id> | orchestrate-resume --id <id> | orchestrate-stop --id <id> | orchestrate-state --id <id>",
-    "          endpoint list | endpoint add --alias <a> --host <h> --port <n> --token <t> | endpoint update --id <id> [--alias <a>] [--host <h>] [--port <n>] [--token <t>] | endpoint remove --alias <a> | endpoint test --alias <a> | endpoint migrate | endpoint doctor",
-    "          endpoint flags: [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]",
-    "  inbox   approvals [--run <id>] [--task <id>] | approve --run <id> --request <id> --decision approve|reject [--note <text>]",
-    "          inputs [--run <id>] [--task <id>] | respond --run <id> --request <id> --answer key=value [--answer key=value]",
-    "  git     <git-flow args...>",
-    "  harness <harness args...>",
-    "  test    unit | e2e | all",
-    "",
-    "Global Options:",
-    "  --version, -V      Print rig version and exit",
-    "  --help, -h         Print this help (or `rig <group> --help` for group help)",
-    "  --project <path>   Use this server/project root instead of auto-discovery or PROJECT_RIG_ROOT",
-    "  --dry-run          Print command execution plan without running commands",
-    "  --json             Output structured JSON result",
-    "  --policy-mode <m>  Override policy mode: off|observe|enforce"
-  ].join(`
-`);
+  return renderTopLevelHelp();
 }
 async function execute(context, args) {
   if (args.length === 0) {
@@ -10657,6 +10858,14 @@ async function execute(context, args) {
 ${helpText()}`);
   }
   if (first === "help" || first === "--help" || first === "-h") {
+    if (rest[0] === "--advanced") {
+      console.log(renderAdvancedHelp());
+      return { ok: true, group: "help", command: "advanced" };
+    }
+    if (rest[0]) {
+      console.log(renderGroupHelp(rest[0]) ?? helpText());
+      return { ok: true, group: "help", command: rest[0] };
+    }
     console.log(helpText());
     return { ok: true, group: "help", command: "show" };
   }