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

package/dist/src/commands/_cli-format.js

@@ -25,21 +25,39 @@ function pad(value, width) {
 }
 function statusColor(status) {
   const normalized = status.toLowerCase();
-  if (["completed", "merged", "closed", "done", "accepted"].includes(normalized))
+  if (["completed", "merged", "closed", "done", "accepted", "pass", "selected"].includes(normalized))
     return pc.green;
-  if (["failed", "needs_attention", "needs-attention", "blocked"].includes(normalized))
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error"].includes(normalized))
     return pc.red;
-  if (["running", "reviewing", "validating", "in_progress", "in-progress"].includes(normalized))
+  if (["running", "reviewing", "validating", "in_progress", "in-progress", "remote"].includes(normalized))
     return pc.cyan;
-  if (["ready", "open", "queued", "created", "preparing"].includes(normalized))
+  if (["ready", "open", "queued", "created", "preparing", "local"].includes(normalized))
     return pc.yellow;
   return pc.dim;
 }
+function formatStatusPill(status) {
+  const label = status || "unknown";
+  return statusColor(label)(`\u25CF ${label}`);
+}
+function formatSection(title, subtitle) {
+  return `${pc.bold(pc.cyan("\u25C6"))} ${pc.bold(title)}${subtitle ? pc.dim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatSuccessCard(title, rows = []) {
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${pc.dim("\u2502")} ${pc.dim(key.padEnd(9))} ${value}`);
+  return [formatSection(title), ...body].join(`
+`);
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc.bold("Next"), ...steps.map((step) => `${pc.dim("\u203A")} ${step}`)];
+}
 function formatTaskList(tasks, options = {}) {
-  if (tasks.length === 0)
-    return pc.dim("No matching tasks.");
   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);
@@ -62,12 +80,18 @@ function formatTaskList(tasks, options = {}) {
       `${row.title}${labels}${source}`
     ].join("  ");
   });
-  return [pc.bold("Rig tasks"), header, ...body].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 pc.dim(options.source === "server" ? "No runs recorded on the selected Rig server." : "No runs recorded in .rig/runs.");
+    return [
+      formatSection("Runs", "none recorded"),
+      options.source === "server" ? pc.dim("No runs recorded on the selected Rig server.") : pc.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)"));
@@ -85,22 +109,56 @@ function formatRunList(runs, options = {}) {
     statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
     `${row.title}${row.runtime ? pc.dim(`  ${row.runtime}`) : ""}`
   ].join("  "));
-  return [pc.bold(options.source === "server" ? "Rig runs (server)" : "Rig runs"), header, ...body].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 lines = [`${pc.green("Run submitted")}: ${pc.bold(input.runId)}`];
+  const rows = [["run", pc.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(`${pc.dim("task")} ${pc.bold(id)} ${statusColor(status)(status)} ${title}`);
+    rows.push(["task", `${pc.bold(id)} ${formatStatusPill(status)} ${title}`]);
   }
-  return lines.join(`
+  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]) => [
+    pc.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`), `${pc.bold(pad("ALIAS", aliasWidth))}  ${pc.bold("KIND")}  ${pc.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"),
+    `${pc.dim("\u2502")} ${pc.dim("selected ")} ${pc.bold(selected)}`,
+    `${pc.dim("\u2502")} ${pc.dim("kind     ")} ${formatStatusPill(connection?.kind ?? "unknown")}`,
+    `${pc.dim("\u2502")} ${pc.dim("target   ")} ${target ?? "not configured"}`,
+    "",
+    ...formatNextSteps(["Change: `rig server use <alias|local>`", "List saved servers: `rig server list`"])
+  ].join(`
 `);
 }
 export {
   formatTaskList,
+  formatSuccessCard,
   formatSubmittedRun,
-  formatRunList
+  formatStatusPill,
+  formatSection,
+  formatRunList,
+  formatNextSteps,
+  formatConnectionStatus,
+  formatConnectionList
 };

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

@@ -0,0 +1,174 @@
+// @bun
+// packages/cli/src/commands/_help-catalog.ts
+import pc from "picocolors";
+var PRIMARY_GROUPS = [
+  {
+    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: "init", summary: "Initialize or repair Rig project state.", usage: ["rig init [options]"], commands: [{ command: "init", description: "Configure project/server/GitHub integration." }] },
+  { 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 pc.bold(pc.cyan(title));
+}
+function commandLine(command, description) {
+  const commandColumn = command.length >= 34 ? `${command}  ` : command.padEnd(34);
+  return `  ${pc.bold(commandColumn)} ${description}`;
+}
+function renderGroup(group) {
+  const lines = [
+    `${heading(`rig ${group.name}`)} \u2014 ${group.summary}`,
+    "",
+    pc.bold("Usage"),
+    ...group.usage.map((line) => `  ${line}`),
+    "",
+    pc.bold("Commands"),
+    ...group.commands.map((entry) => commandLine(entry.command, entry.description))
+  ];
+  if (group.examples?.length) {
+    lines.push("", pc.bold("Examples"), ...group.examples.map((line) => `  ${pc.dim("$")} ${line}`));
+  }
+  if (group.next?.length) {
+    lines.push("", pc.bold("Next steps"), ...group.next.map((line) => `  ${pc.dim("\u203A")} ${line}`));
+  }
+  if (group.advanced?.length) {
+    lines.push("", pc.bold("Compatibility / advanced"), ...group.advanced.map((line) => `  ${pc.dim("\u203A")} ${line}`));
+  }
+  return lines.join(`
+`);
+}
+function renderTopLevelHelp() {
+  return [
+    `${heading("rig")} \u2014 server-owned task/run control plane`,
+    "",
+    pc.bold("Common workflows"),
+    "  rig server status                 Show selected local/remote server",
+    "  rig task list                     List available work",
+    "  rig task run --next               Start next task and attach with native Pi",
+    "  rig run list                      List recent runs",
+    "  rig run attach <run-id> --follow  Rejoin a live run",
+    "",
+    pc.bold("Primary groups"),
+    ...PRIMARY_GROUPS.map((group) => commandLine(group.name, group.summary)),
+    "",
+    pc.bold("Help"),
+    "  rig <group> --help                Rich help for server, task, run, and other groups",
+    "  rig help --advanced               Legacy/dev/compat command surface",
+    "  rig --version                     Print version",
+    "",
+    pc.bold("Global options"),
+    "  --project <path>                  Use a project root instead of auto-discovery",
+    "  --json                            Output structured JSON",
+    "  --dry-run                         Print command execution plan only"
+  ].join(`
+`);
+}
+function renderAdvancedHelp() {
+  return [
+    `${heading("rig advanced")} \u2014 legacy, dev, and compatibility groups`,
+    "",
+    pc.bold("Primary groups are still"),
+    "  server, task, run",
+    "",
+    pc.bold("Advanced groups"),
+    ...ADVANCED_GROUPS.map((group) => commandLine(group.name, group.summary)),
+    "",
+    pc.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;
+}
+function listHelpGroups() {
+  return ALL_GROUPS.map((group) => group.name);
+}
+export {
+  renderTopLevelHelp,
+  renderGroupHelp,
+  renderAdvancedHelp,
+  listHelpGroups
+};

package/dist/src/commands/connect.js

@@ -1,4 +1,7 @@
 // @bun
+// packages/cli/src/commands/connect.ts
+import { cancel, isCancel, select } from "@clack/prompts";
+
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
 import { CliError } from "@rig/runtime/control-plane/errors";
@@ -103,12 +106,81 @@ function writeRepoConnection(projectRoot, state) {
   writeJsonFile(resolveRepoConnectionPath(projectRoot), state);
 }
 
+// packages/cli/src/commands/_cli-format.ts
+import pc from "picocolors";
+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 pc.green;
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error"].includes(normalized))
+    return pc.red;
+  if (["running", "reviewing", "validating", "in_progress", "in-progress", "remote"].includes(normalized))
+    return pc.cyan;
+  if (["ready", "open", "queued", "created", "preparing", "local"].includes(normalized))
+    return pc.yellow;
+  return pc.dim;
+}
+function formatStatusPill(status) {
+  const label = status || "unknown";
+  return statusColor(label)(`\u25CF ${label}`);
+}
+function formatSection(title, subtitle) {
+  return `${pc.bold(pc.cyan("\u25C6"))} ${pc.bold(title)}${subtitle ? pc.dim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatSuccessCard(title, rows = []) {
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${pc.dim("\u2502")} ${pc.dim(key.padEnd(9))} ${value}`);
+  return [formatSection(title), ...body].join(`
+`);
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc.bold("Next"), ...steps.map((step) => `${pc.dim("\u203A")} ${step}`)];
+}
+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]) => [
+    pc.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`), `${pc.bold(pad("ALIAS", aliasWidth))}  ${pc.bold("KIND")}  ${pc.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"),
+    `${pc.dim("\u2502")} ${pc.dim("selected ")} ${pc.bold(selected)}`,
+    `${pc.dim("\u2502")} ${pc.dim("kind     ")} ${formatStatusPill(connection?.kind ?? "unknown")}`,
+    `${pc.dim("\u2502")} ${pc.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 parseConnection(alias, value) {
+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);
@@ -127,54 +199,90 @@ function printJsonOrText(context, payload, text) {
     console.log(text);
   }
 }
-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 select({
+    message: "Select Rig server for this repo",
+    initialValue: repo?.selected ?? "local",
+    options
+  });
+  if (isCancel(answer)) {
+    cancel("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" });
+}
 export {
+  executeConnectionCommand,
   executeConnect
 };

package/dist/src/commands/run.js

@@ -1236,19 +1236,33 @@ function pad(value, width) {
 }
 function statusColor(status) {
   const normalized = status.toLowerCase();
-  if (["completed", "merged", "closed", "done", "accepted"].includes(normalized))
+  if (["completed", "merged", "closed", "done", "accepted", "pass", "selected"].includes(normalized))
     return pc.green;
-  if (["failed", "needs_attention", "needs-attention", "blocked"].includes(normalized))
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error"].includes(normalized))
     return pc.red;
-  if (["running", "reviewing", "validating", "in_progress", "in-progress"].includes(normalized))
+  if (["running", "reviewing", "validating", "in_progress", "in-progress", "remote"].includes(normalized))
     return pc.cyan;
-  if (["ready", "open", "queued", "created", "preparing"].includes(normalized))
+  if (["ready", "open", "queued", "created", "preparing", "local"].includes(normalized))
     return pc.yellow;
   return pc.dim;
 }
+function formatSection(title, subtitle) {
+  return `${pc.bold(pc.cyan("\u25C6"))} ${pc.bold(title)}${subtitle ? pc.dim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc.bold("Next"), ...steps.map((step) => `${pc.dim("\u203A")} ${step}`)];
+}
 function formatRunList(runs, options = {}) {
   if (runs.length === 0) {
-    return pc.dim(options.source === "server" ? "No runs recorded on the selected Rig server." : "No runs recorded in .rig/runs.");
+    return [
+      formatSection("Runs", "none recorded"),
+      options.source === "server" ? pc.dim("No runs recorded on the selected Rig server.") : pc.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)"));
@@ -1266,7 +1280,7 @@ function formatRunList(runs, options = {}) {
     statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
     `${row.title}${row.runtime ? pc.dim(`  ${row.runtime}`) : ""}`
   ].join("  "));
-  return [pc.bold(options.source === "server" ? "Rig runs (server)" : "Rig runs"), header, ...body].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(`
 `);
 }