@h-rig/contracts 0.0.6-alpha.100 → 0.0.6-alpha.103

package/dist/index.mjs

@@ -4956,109 +4956,269 @@ var TOP_LEVEL_SECTIONS = [
     title: "Open Rig",
     subtitle: "the cockpit \u2014 bare rig opens the Rig Cockpit inside an OMP collab session",
     commands: [
-      { command: "rig", description: "Open the Rig Cockpit (OMP collaboration substrate) for the current workspace." },
-      { command: "rig --workspace <path>", description: "Open the cockpit for another workspace instead of the current dir." },
-      { command: "rig join <link>", description: "Join an encrypted OMP collaborative session from another operator." },
-      { command: "/rig", description: "From inside an OMP session, (re)open the Rig Cockpit screen." },
-      { command: "rig --version", description: "Print the installed Rig CLI version." }
+      {
+        command: "rig",
+        description: "Open the Rig Cockpit (OMP collaboration substrate) for the current workspace.",
+        usecase: "Day-to-day entry point: drive everything (tasks, runs, inbox) from the board.",
+        examples: ["cd my-project && rig", "rig            # in a repo with rig.config.ts"]
+      },
+      {
+        command: "rig --workspace <path>",
+        description: "Open the cockpit for another workspace instead of the current dir.",
+        usecase: "Operate a project without cd-ing into it.",
+        examples: ["rig --workspace ~/work/humanwork", "rig --workspace ../other-repo"]
+      },
+      {
+        command: "rig join <link>",
+        description: "Join an encrypted OMP collaborative session from another operator.",
+        usecase: "Pair on a teammate's live run from the join link they shared.",
+        examples: ["rig join where.rig-does.work/r/AbC123\u2026"]
+      },
+      { command: "/rig", description: "From inside an OMP session, (re)open the Rig Cockpit screen.", usecase: "Jump back to the board after dropping into the raw agent session." },
+      { command: "rig --version", description: "Print the installed Rig CLI version.", examples: ["rig --version"] }
     ]
   },
   {
     title: "Runs \u2014 dispatch & control task runs",
     subtitle: "every run is an isolated, collaborative OMP session on the selected target",
     commands: [
-      { command: "rig run start <task|#issue|--next>", description: "Dispatch a run for a task (refuses if one is already active; --force overrides)." },
-      { command: "rig run start-parallel [--limit n]", description: "Dispatch all ready tasks concurrently up to the limit." },
-      { command: "rig run start-serial", description: "Dispatch the next ready task; re-run to continue the serial queue." },
-      { command: "rig run list", description: "List every discoverable run (live registry + local) with status and links." },
-      { command: "rig run status", description: "Active vs recent runs at a glance." },
-      { command: "rig run show <id>", description: "Run card: status, task, PR, join link, pending approvals/inputs, error summary." },
-      { command: "rig run attach <id>", description: "Attach to a run's live OMP collab session (write access)." },
-      { command: "rig run steer <id> --message <text>", description: "Send a steering message into a running session (remote routes to its host)." },
-      { command: "rig run stop <id> [--reason <text>]", description: "Request a graceful stop of a run." },
-      { command: "rig run resume|restart <id>", description: "Re-dispatch a task (detached runs start fresh)." },
-      { command: "rig run timeline|replay <id>", description: "Inspect a run's folded timeline / replay its journal." },
-      { command: "rig run cleanup", description: "Prune dead/stale run state." }
+      {
+        command: "rig run start <task|#issue|--next>",
+        description: "Dispatch a run for a task (refuses if one is already active; --force overrides).",
+        usecase: "Kick off work on a specific issue, or let Rig pick the next ready one.",
+        examples: [
+          "rig run start 204            # by task/issue id",
+          "rig run start --next         # next ready task by deps/priority",
+          "rig run start 204 --force    # dispatch even if a run is already active",
+          "rig run start 204 --model opus-4.8   # override the agent model"
+        ]
+      },
+      {
+        command: "rig run start-parallel [--limit n]",
+        description: "Dispatch all ready tasks concurrently up to the limit.",
+        usecase: "Burn down a backlog of independent tasks at once.",
+        examples: ["rig run start-parallel", "rig run start-parallel --limit 3"]
+      },
+      {
+        command: "rig run start-serial",
+        description: "Dispatch the next ready task; re-run to continue the serial queue.",
+        usecase: "Work a queue one-at-a-time (e.g. dependent tasks, limited capacity).",
+        examples: ["rig run start-serial"]
+      },
+      {
+        command: "rig run list",
+        description: "List every discoverable run (live registry + local) with status and links.",
+        usecase: "See what's running anywhere (local + remote) and grab ids/join links.",
+        examples: ["rig run list", "rig run list | grep running"]
+      },
+      { command: "rig run status", description: "Active vs recent runs at a glance.", examples: ["rig run status"] },
+      {
+        command: "rig run show <id>",
+        description: "Run card: status, task, PR, join link, pending approvals/inputs, error summary.",
+        usecase: "Get the full picture of one run before attaching or steering.",
+        examples: ["rig run show 019ee11f", "rig run show 019ee11f   # copy the join link"]
+      },
+      {
+        command: "rig run attach <id>",
+        description: "Attach to a run's live OMP collab session (write access).",
+        usecase: "Watch/drive a run interactively \u2014 type to the agent, see its work live.",
+        examples: ["rig run attach 019ee11f"]
+      },
+      {
+        command: "rig run steer <id> --message <text>",
+        description: "Send a steering message into a running session (remote routes to its host).",
+        usecase: "Course-correct an autonomous run without attaching.",
+        examples: [
+          "rig run steer 019ee11f --message 'focus on the API first'",
+          "rig run steer 019ee11f --message 'stop and open the PR now'"
+        ]
+      },
+      {
+        command: "rig run stop <id> [--reason <text>]",
+        description: "Request a graceful stop of a run.",
+        usecase: "Halt a run that's off-track or no longer needed.",
+        examples: ["rig run stop 019ee11f", "rig run stop 019ee11f --reason 'superseded by #210'"]
+      },
+      {
+        command: "rig run resume|restart <id>",
+        description: "Re-dispatch a task (detached runs start fresh).",
+        usecase: "Retry a failed/stopped run from a clean slate.",
+        examples: ["rig run restart 019ee11f", "rig run resume 019ee11f"]
+      },
+      {
+        command: "rig run timeline|replay <id>",
+        description: "Inspect a run's folded timeline / replay its journal.",
+        usecase: "Audit what an agent did, step by step, after the fact.",
+        examples: ["rig run timeline 019ee11f", "rig run replay 019ee11f"]
+      },
+      { command: "rig run cleanup", description: "Prune dead/stale run state.", usecase: "Clear out finished/orphaned run entries cluttering the board.", examples: ["rig run cleanup"] }
     ]
   },
   {
     title: "Tasks \u2014 the configured task source",
     subtitle: "github-issues / files task sources feed dispatch",
     commands: [
-      { command: "rig task list [--search <t>] [--status <s>]", description: "List tasks from the configured source, with filters." },
-      { command: "rig task next", description: "Show the next ready task by dependency/priority." },
-      { command: "rig task show|info <id>", description: "Task detail: title, body, status, labels, scope, deps, URL." },
-      { command: "rig task scope|deps|status <id>", description: "Inspect a task's scope globs, dependencies, or lifecycle status." },
-      { command: "rig task lookup <term>", description: "Find a task by id/title substring." },
-      { command: "rig task record \u2026", description: "Write task state/metadata back to the source." },
-      { command: "rig task artifacts <id>", description: "List/inspect a task's run artifacts." },
-      { command: "rig triage", description: "Run the configured issueAnalysis pass once (schedule via cron/CI for continuous)." }
+      {
+        command: "rig task list [--search <t>] [--status <s>]",
+        description: "List tasks from the configured source, with filters.",
+        usecase: "Find what's available to dispatch; filter by text or lifecycle status.",
+        examples: [
+          "rig task list",
+          "rig task list --status open",
+          "rig task list --search 'auth'"
+        ]
+      },
+      { command: "rig task next", description: "Show the next ready task by dependency/priority.", usecase: "Decide what to run next without scanning the whole list.", examples: ["rig task next"] },
+      {
+        command: "rig task show|info <id>",
+        description: "Task detail: title, body, status, labels, scope, deps, URL.",
+        usecase: "Read the full issue before dispatching a run for it.",
+        examples: ["rig task show 204", "rig task info 204"]
+      },
+      {
+        command: "rig task scope|deps|status <id>",
+        description: "Inspect a task's scope globs, dependencies, or lifecycle status.",
+        usecase: "Check what files a run may touch / what's blocking it.",
+        examples: ["rig task scope 204", "rig task deps 204", "rig task status 204"]
+      },
+      { command: "rig task lookup <term>", description: "Find a task by id/title substring.", examples: ["rig task lookup revoke-invite"] },
+      { command: "rig task record \u2026", description: "Write task state/metadata back to the source.", usecase: "Programmatically update task lifecycle from scripts/CI." },
+      { command: "rig task artifacts <id>", description: "List/inspect a task's run artifacts.", examples: ["rig task artifacts 204"] },
+      { command: "rig triage", description: "Run the configured issueAnalysis pass once (schedule via cron/CI for continuous).", usecase: "Auto-classify/label/scope new issues in a batch.", examples: ["rig triage"] }
     ]
   },
   {
     title: "Config \u2014 everything through rig.config.ts",
     subtitle: "resolution: ambient env \u2192 rig.config.ts \u2192 computed default",
     commands: [
-      { command: "rig config get [<key>]", description: "Effective value(s) + which layer won (env / rig.config.ts / default)." },
-      { command: "rig config set <key> <value>", description: "Write an override (relayUrl/registryUrl/registrySecret/sshTarget or any RIG_*) into rig.config.ts." },
-      { command: "rig init", description: "Create rig.config.ts (project, task source, placement/sshTarget) interactively." },
-      { command: "runtime.server in rig.config.ts", description: "Backbone (relay/registry/secret) + remote placement (sshTarget); defaults under the hood." }
+      {
+        command: "rig config get [<key>]",
+        description: "Effective value(s) + which layer won (env / rig.config.ts / default).",
+        usecase: "Debug why a value is what it is \u2014 see the winning layer.",
+        examples: [
+          "rig config get                 # all effective values + sources",
+          "rig config get sshTarget       # one key + winning layer",
+          "rig config get relayUrl"
+        ]
+      },
+      {
+        command: "rig config set <key> <value>",
+        description: "Write an override (relayUrl/registryUrl/registrySecret/sshTarget or any RIG_*) into rig.config.ts.",
+        usecase: "Persist a setting so it survives across runs without env vars.",
+        examples: [
+          "rig config set sshTarget ubuntu@host        # remote placement",
+          "rig config set relayUrl wss://my-relay",
+          "rig config set RIG_ANYTHING value           # any RIG_* knob"
+        ]
+      },
+      {
+        command: "rig init",
+        description: "Create rig.config.ts (project, task source, placement/sshTarget) interactively.",
+        usecase: "First-time setup of a repo for Rig.",
+        examples: ["rig init"]
+      },
+      {
+        command: "runtime.server in rig.config.ts",
+        description: "Backbone (relay/registry/secret) + remote placement (sshTarget); defaults under the hood.",
+        usecase: "Pin a project's relay/registry and remote host in code.",
+        examples: [
+          "runtime: { server: { sshTarget: 'ubuntu@host' } }   // remote placement",
+          "runtime: { server: { relayUrl: 'wss://\u2026', registryUrl: 'https://\u2026/registry' } }"
+        ]
+      }
     ]
   },
   {
     title: "Placement & target \u2014 local vs remote execution",
     subtitle: "where runs execute; the backbone relay/registry is shared",
     commands: [
-      { command: "rig server status", description: "Show the selected placement (local/remote) and project-root link." },
-      { command: "rig server list", description: "List configured server targets." },
-      { command: "rig server use <alias>", description: "Select a server target (execution placement)." },
-      { command: "rig server add|remove <alias>", description: "Configure or remove a remote server target." },
-      { command: "rig server repair-link", description: "Repair the project-root link for the selected target." },
-      { command: "rig remote <list|add|test|status|\u2026>", description: "Lower-level remote endpoint management + run control over a remote." }
+      { command: "rig server status", description: "Show the selected placement (local/remote) and project-root link.", examples: ["rig server status"] },
+      { command: "rig server list", description: "List configured server targets.", examples: ["rig server list"] },
+      {
+        command: "rig server use <alias>",
+        description: "Select a server target (execution placement).",
+        usecase: "Switch a repo between local and a remote host for run execution.",
+        examples: ["rig server use local", "rig server use prod-box"]
+      },
+      {
+        command: "rig server add|remove <alias>",
+        description: "Configure or remove a remote server target.",
+        examples: ["rig server add prod-box ubuntu@host", "rig server remove prod-box"]
+      },
+      { command: "rig server repair-link", description: "Repair the project-root link for the selected target.", usecase: "Fix a remote that shows unavailable after a host/checkout change.", examples: ["rig server repair-link"] },
+      {
+        command: "rig remote <list|add|test|status|\u2026>",
+        description: "Lower-level remote endpoint management + run control over a remote.",
+        examples: ["rig remote list", "rig remote test prod-box", "rig remote status"]
+      }
     ]
   },
   {
     title: "Inbox & Doctor \u2014 approvals and health",
     subtitle: "answer pending workflow entries; probe setup",
     commands: [
-      { command: "rig inbox approvals|inputs", description: "List pending approval / user-input workflow entries." },
-      { command: "rig inbox approve <id> | respond <id> <text>", description: "Approve an entry or answer a user-input prompt." },
-      { command: "rig inbox watch", description: "Stream inbox changes live." },
-      { command: "rig doctor", description: "Cheap health checks: session discovery, registry, selected target, workflow entries." }
+      {
+        command: "rig inbox approvals|inputs",
+        description: "List pending approval / user-input workflow entries.",
+        usecase: "See what a run is blocked on waiting for you.",
+        examples: ["rig inbox approvals", "rig inbox inputs"]
+      },
+      {
+        command: "rig inbox approve <id> | respond <id> <text>",
+        description: "Approve an entry or answer a user-input prompt.",
+        usecase: "Unblock a paused run from the CLI.",
+        examples: ["rig inbox approve abc123", "rig inbox respond abc123 'use option B'"]
+      },
+      { command: "rig inbox watch", description: "Stream inbox changes live.", examples: ["rig inbox watch"] },
+      { command: "rig doctor", description: "Cheap health checks: session discovery, registry, selected target, workflow entries.", usecase: "First thing to run when something seems off.", examples: ["rig doctor"] }
     ]
   },
   {
     title: "Inspect & stats \u2014 observability",
     subtitle: "logs, artifacts, diffs, failure analysis",
     commands: [
-      { command: "rig inspect run-logs|logs --run <id>", description: "Tail a run's process / session logs." },
-      { command: "rig inspect runs", description: "List runs from on-disk runtime state." },
-      { command: "rig inspect artifact(s) --task <id>", description: "Inspect a task/run's artifacts." },
-      { command: "rig inspect diff|graph", description: "Run diff / task dependency graph." },
-      { command: "rig inspect failures --task <id>", description: "Classified failure diagnostics for a task's runs." },
-      { command: "rig stats", description: "Aggregate run stats over a window." }
+      {
+        command: "rig inspect run-logs|logs --run <id>",
+        description: "Tail a run's process / session logs.",
+        usecase: "Debug why a run failed or stalled.",
+        examples: ["rig inspect run-logs --run 019ee11f", "rig inspect logs --run 019ee11f"]
+      },
+      { command: "rig inspect runs", description: "List runs from on-disk runtime state.", examples: ["rig inspect runs"] },
+      { command: "rig inspect artifact(s) --task <id>", description: "Inspect a task/run's artifacts.", examples: ["rig inspect artifacts --task 204"] },
+      { command: "rig inspect diff|graph", description: "Run diff / task dependency graph.", examples: ["rig inspect diff", "rig inspect graph"] },
+      { command: "rig inspect failures --task <id>", description: "Classified failure diagnostics for a task's runs.", usecase: "Triage repeated failures on one task.", examples: ["rig inspect failures --task 204"] },
+      { command: "rig stats", description: "Aggregate run stats over a window.", examples: ["rig stats", "rig stats --since 7d"] }
     ]
   },
   {
     title: "Setup & integrations",
     subtitle: "initialize, authenticate, and wire the project",
     commands: [
-      { command: "rig init", description: "Set up a new repo: rig.config.ts, task source, placement, state." },
-      { command: "rig setup", description: "Run/repair the full setup wizard (repo, placement, GitHub auth, labels, verify)." },
-      { command: "rig github status|token|import-gh", description: "GitHub auth status, token management, issue import." },
-      { command: "rig repo|git \u2026", description: "Repo/source helpers (clone, credentials, git ops)." },
-      { command: "rig review", description: "Inspect or change the completion-review (Greptile) gate policy." }
+      { command: "rig init", description: "Set up a new repo: rig.config.ts, task source, placement, state.", examples: ["rig init"] },
+      { command: "rig setup", description: "Run/repair the full setup wizard (repo, placement, GitHub auth, labels, verify).", usecase: "Re-run when auth/labels/placement drift or after onboarding.", examples: ["rig setup"] },
+      {
+        command: "rig github status|token|import-gh",
+        description: "GitHub auth status, token management, issue import.",
+        examples: ["rig github status", "rig github import-gh"]
+      },
+      { command: "rig repo|git \u2026", description: "Repo/source helpers (clone, credentials, git ops).", examples: ["rig repo status", "rig git \u2026"] },
+      { command: "rig review", description: "Inspect or change the completion-review (Greptile) gate policy.", examples: ["rig review"] }
     ]
   },
   {
     title: "Extend & build",
     subtitle: "plugins, OMP/Pi packages, binaries, workspaces",
     commands: [
-      { command: "rig plugin list|validate|run", description: "Inspect and exercise plugin-contributed channels." },
-      { command: "rig pi list|add|remove|search", description: "Manage OMP/Pi extension packages for sessions/workers." },
-      { command: "rig dist build|install", description: "Build/install the self-contained rig binary distribution." },
-      { command: "rig workspace summary|topology", description: "Multi-root workspace inspection." },
-      { command: "rig.config.ts plugins / runtime.pi.packages", description: "Declare task sources, validators, hooks, skills, roles + team OMP/Pi packages." }
+      { command: "rig plugin list|validate|run", description: "Inspect and exercise plugin-contributed channels.", examples: ["rig plugin list", "rig plugin validate", "rig plugin run <name>"] },
+      { command: "rig pi list|add|remove|search", description: "Manage OMP/Pi extension packages for sessions/workers.", examples: ["rig pi list", "rig pi add <pkg>", "rig pi search <term>"] },
+      {
+        command: "rig dist build|install",
+        description: "Build/install the self-contained rig binary distribution.",
+        usecase: "Produce/refresh the single-file rig binary.",
+        examples: ["rig dist build", "rig dist install"]
+      },
+      { command: "rig workspace summary|topology", description: "Multi-root workspace inspection.", examples: ["rig workspace summary", "rig workspace topology"] },
+      { command: "rig.config.ts plugins / runtime.pi.packages", description: "Declare task sources, validators, hooks, skills, roles + team OMP/Pi packages.", examples: ["plugins: [standard()]", "runtime: { pi: { packages: ['@me/my-ext'] } }"] }
     ]
   }
 ];