openrig-user — Claude Code skill: exact rig CLI syntax

---
name: openrig-user
description: >-
  Use when a specific `rig` command, subcommand, or flag is already known and you need its exact
  syntax, JSON shape, defaults, or error meaning. NOT for natural capability discovery, open-ended
  how-do-I questions, or choosing which OpenRig move applies.
---

# OpenRig User

This is an as-built guide to the shipped `rig` CLI.
Use current code and `rig ... --help` as ground truth if anything here ever conflicts with older planning docs.

Use the OpenRig builder guidance when changing OpenRig behavior, doctrine, or release posture.


## Coordination trust boundary

Coordinate as openly as the trust boundary you actually control allows. Within a set of machines you
own that already trust each other — they can reach each other's daemon URLs and the daemon itself
requires no authentication — direct `rig send`, `rig capture`, and `rig queue` should just work.
Don't invent bearer placeholders, allowlists, trust handshakes, or guest-reach restrictions the
environment doesn't require.

Do not add or defend a restriction without naming the protected asset, the actual adversary, the
blocked attack path, and the concrete consequence. Missing capability is not protection — repair the
route, registration, runtime posture, or product defect directly. Arbitrary boundaries create
constraint-induced circumvention: under goal pressure, agents build shadow transports, alternate
credentials, and weaker proof instead of the direct authorized path. Keep only explicitly stated
external or irreversible boundaries — public push / PR / publish, and destruction of canonical data.

## Coordination primitives — when to use which

Three coordination surfaces, used together for forward-momentum work. Internalize this
on first read — it shapes every turn you take in a rig.

### `rig send <seat> "<text>"` — intra-pod direct messaging / nudges

Use when you need to ask a quick question or give a teammate context that does not
carry handoff semantics. **NOT for durable work.** NOT for state that must survive
across turns. The message lands in the target's pane; there is no durable queue
record. The CLI prints `Sent to ...` (and `Verified: yes/no` with `--verify`); read
the receipt and move on.

Example:

```bash
rig send dev-reviewer@example-project "The import report is ready; the durable handoff names its evidence." --verify
```

### `rig queue create --destination <Y> --tags <...> --body-file <path>` — durable work item

Use for any substantive work that must not fall through chat — slice handoffs,
guard verdicts, QA results, full-tip reviews, multi-item batches. Survives agent
restarts. Tracked in the daemon SQLite schema. Surfaces in Project / queue views
+ in the destination seat's inbox. Tag with mission / slice / gate / checkpoint
so future-you (and any peer) can find it. Give the row a `--summary` (its subject, wherever the row is listed)
and the `project:`, `mission:` and `slice:` tags when it is project work.

Body discipline: substantive bodies go through **`--body-file <path>`** (or `-` for stdin) — the
purpose-built, corruption-safe surface (it kills the backtick-shell-corruption class for multi-line
bodies). Do NOT inline a backtick-heavy or multi-line body via `--body`: `rig queue create` body
parsing breaks on unescaped backticks and rejects flag-like tokens.

Example:

```bash
rig queue create \
  --destination dev-reviewer@example-project \
  --summary "Review the import report: it changes how rows are deduplicated" \
  --tags "project:example-project,mission:data-import,slice:import-report" \
  --body-file /tmp/import-report-handoff.md
```

### `rig queue handoff <qitem-id> --to <next> ...` — hot-potato handoff

Use when you have completed your turn on a qitem and the work moves to the next
owner. **This is forward momentum.** The ball passes to the destination seat;
chain-of-record (the prior qitem id) is preserved so the verdict trail is intact;
tags carry the selected work context forward. Gate tags describe checks actually
selected for that work; they do not require a fixed sequence of roles.

Example:

```bash
rig queue handoff <qitem-id> \
  --to dev-reviewer@example-project \
  --summary "Review the import report: it changes how rows are deduplicated" \
  --tags "project:example-project,mission:data-import,slice:import-report" \
  --body-file /tmp/import-report-handoff.md
```

### After a queue write — use the response; read back only when it doesn't show what you need

A queue write (`create`, `claim`, `update`, `handoff`, `handoff-and-complete`) answers with the row it wrote; a
handoff answers with the closed row and its successor. When that answer shows what you need to establish, use it.

`create` also prints `Queue create request ID: <id> (not proof of persistence)` on stderr *before* it sends the write,
so an interrupted create can be reconciled. That ID names a request, not a row. The row is the `qitemId` on stdout
when the command exits 0. A non-zero exit means no row was confirmed, even when stdout carries a `qitemId`: an
indeterminate answer repeats the request ID so you can reconcile by it. Don't merge stderr into stdout and keep the
first `qitem-…` you find there; a refused create prints its request ID first, too.

Read back (`rig queue show <id> --full --json`, or `rig queue transitions <id>`) when the answer doesn't show what you
need, for example:

- the outcome was INDETERMINATE (a transport failure, or a 502 `remote_queue_write_failed` that may have reached the
  other host), or the write warned `qitem_body_not_saved` (an existing row came back). Reconcile by the original ID
  before any retry. A 502 whose `failureClass` is `unknown-host`, `unsupported-transport` or `registry` isn't
  indeterminate: the daemon refused before contacting any host and wrote nothing (`create` says "No row was
  created"). `unsupported-transport` means that host entry is SSH-declared. Use the http entry for the same machine
  from `rig host list`; if there isn't one, add it with that machine's daemon URL (`rig host add --id <id>
  --transport http --url <daemon-url>`), asking whoever runs that host for the URL;
- the output was compact or truncated and the field you need isn't in it (the compact receipt shows `bodyBytes`, not
  the body, and its footer names what it left out);
- you need a transition note, a closure or blocker detail, or a successor that the output you saw omits;
- you need evidence from downstream of the write: the recipient's wake (`create --verify` waits for it), or its
  pickup or claim (a later read);
- your team's custody rule asks for a separate read-back.

Don't read back only to see again a field the response already showed you.

### §1b doctrine — turn ends by passing the ball

**A turn ends by passing the ball, never by going idle holding the slice waiting
on a confirmation the selected process does not include.** Follow the current
`mission-slice-sop`: proportional owner checks are the default; independent review
runs when selected, at the authored work boundary. Role names do not add per-commit
guard, QA, or orchestration gates. Do the authorized work, run its selected checks,
and return the outcome through durable custody.

Valid pauses are only:

- A genuine blocker — file a blocked-state qitem against the blocking peer or
  surface explicitly to orch.
- A scope-or-architecture question that requires owner input and changes the
  plan — surface to orch with the specific decision needed.

Implementing already-authorized work is neither of these. Proceed without
phantom-gating on an imagined "next prompt" or "operator confirmation" that the
process does not require.

### Anti-patterns

- Using `rig send` for durable work → use `rig queue create` instead. Sends do
  not survive restarts and do not show up in queue/project views.
- Idle-holding a slice for an imagined "next prompt" or "operator confirmation"
  that the process does not require → pass the ball via `rig queue handoff` and
  proceed to the next slice or stand by for the inbound verdict. See the §1b
  doctrine above.
- Inlining a multi-line / backtick-heavy body into `rig queue create --body`
  → use `--body-file /tmp/<descriptive-name>.txt` (or `-` for stdin), the
  corruption-safe surface. The body parser does not tolerate raw backticks or
  flag-like tokens inline.

## Runtime-Gated Coordination Primitives

OpenRig v0.3.1 is published publicly as `@openrig/[email protected]` and GitHub Release
`v0.3.1`. It includes the bundled PL-004 Coordination Primitive System: Phase A
`rig stream` / `rig queue`, Phase B `rig project` / `rig view`, Phase C
`rig watchdog`, and Phase D `rig workflow` / `workflow-keepalive`.

These are shipped product surfaces in v0.3.x, but they require a compatible
v0.3.x daemon and matching SQLite schema at runtime — the installed package
version is not automatically the version of the daemon serving you. If a
coordination command behaves unexpectedly, confirm the running daemon with
`rig whoami --json` and daemon status before assuming a product bug.

Default posture:

- Treat daemon `rig queue`, `rig stream`, `rig project`, `rig view`, `rig watchdog`, and
  `rig workflow` as the product coordination surfaces when the active daemon is v0.2.0 or newer.
- Use daemon-backed `rig queue` for durable routing. `update / show / list`
  complement `create / handoff` for inspection and state changes; records in an
  unrelated store are not evidence that this daemon owns the work.
- If a daemon-backed coordination command fails, debug the command/runtime/schema edge directly;
  do not assume the right workaround is to drop back to a config-layer primitive.
- Do not perform daemon stop/start, production DB copy/mutation, release, publish, or other
  consequence-boundary actions unless the operator/workstream has granted that specific gate.

## First-user workspace setup

When booting into a rig on a host where the workspace is unset, gap-ridden, or
points at a stale layout, address that before substantive project work. The
shipped surface is small + bounded — reach for the canonical commands rather
than improvising.

### Detect workspace state at boot

Agent-actionable when the daemon is reachable.

```bash
rig workspace validate --json
rig workspace validate <path> --kind <user|project|knowledge|lab|delivery> --json
```

`rig workspace validate` walks the workspace root and emits a structured
frontmatter-gap report against the v0 contract. Exit code is non-zero when
gaps exist (operators chain into hygiene fix loops). Default root is the
current directory; pass a positional path to validate elsewhere. `--kind`
scopes the contract to a specific workspace kind; omit for a kind-agnostic
structural check.

If `rig workspace validate` reports a non-zero `gapCount` OR the workspace
root is unset / unwritable, the workspace needs instantiation — see the next
section.

### Instantiate the canonical workspace scaffold

Agent-actionable. The operation is additive and preserves existing files.

```bash
rig config init-workspace
rig config init-workspace --root <path>
rig config init-workspace --dry-run --json
```

`rig config init-workspace` scaffolds the canonical workspace layout at the
configured `workspace.root` (default `~/.openrig/workspace`):

- `missions/` — release missions + slices
- `exhaust/` — project-local coordination exhaust
- `SPEC.md` — project intent
- `project.yaml` — project catalog selections and mission root
- `workspace.yaml` — project registration
- `.gitignore` — local OpenRig state and exhaust exclusions

`--root <path>` targets a non-default root for this call; `--dry-run` reports
what would be created without writing. `--force` is deprecated compatibility
and still preserves existing files.

### Redirect the workspace root

Operator-gated when persistent. Agent-actionable when one-shot via env-var.

For a single command:

```bash
OPENRIG_WORKSPACE_ROOT=<path> rig <command> ...
```

For a persistent host-level redirect, the operator changes the config file or
runs the setter:

```bash
rig config set workspace.root <path>
```

ConfigStore precedence: `OPENRIG_WORKSPACE_ROOT` env > config-file
`workspace.root` > built-in default `~/.openrig/workspace`. The same
precedence governs `OPENRIG_WORKSPACE_SPECS_ROOT` → `workspace.specs_root`
(default `<workspace_root>/specs`).

Prefer the env-var form for one-shot redirects (transparent to operators);
reserve `rig config set` for changes the operator owns.

### Build a workspace from scratch

Agent-actionable. Same surface as the canonical scaffold above; the
`workspace.root` cascade handles non-existent host paths.

```bash
rig config init-workspace --root /path/to/new/workspace
```

The command additively creates any missing canonical entries and preserves
every existing one; only a complete six-entry scaffold is a no-op. Run
`rig workspace validate /path/to/new/workspace --json` after to confirm the
contract holds.

### Create a workflow inside an existing workspace

Authoring is operator-or-agent; validation + instantiation are
agent-actionable.

Workflow spec files live at:

```
<workspace_root>/specs/workflows/<name>.yaml
```

`<workspace_root>` resolves via the ConfigStore precedence named above.
There is no `rig workflow create` verb in v0.3.x — the spec YAML is authored
directly. Template by hand from the documented schema, or copy a built-in
starter from `<openrig install>/dist/builtins/workflow-specs/` and adapt.
Once written:

```bash
rig workflow validate <workspace_root>/specs/workflows/<name>.yaml --json

rig workflow instantiate <workspace_root>/specs/workflows/<name>.yaml \
  --root-objective "<one-line objective for the run>" \
  --created-by <your-session>@<your-rig> \
  --json
```

Both `--root-objective <text>` and `--created-by <session>` are REQUIRED
on `instantiate` — omitting either yields a Commander required-option
error before the daemon is contacted. `--entry-owner <session>` is an
optional override for the entry-step owner; default routing is per the
workflow spec.

`validate` returns a structured ok/error report; `instantiate` creates a
workflow instance + entry-step qitem. Inspect existing surface state with:

```bash
rig workflow specs --json              # list registered specs (built-in + operator-authored)
rig workflow list --json               # list active workflow instances
rig workflow show <instanceId> --json  # inspect one instance
rig workflow project <instanceId>      # ADVANCE an instance — projects the next-step packet
rig workflow continue <instanceId>     # read-only inspector of an instance (does NOT advance it)
```

*(Surface note — the current `rig workflow` command group registers **13** subcommands: `validate`, `instantiate`, `project`, `list`, `specs`, `show`, `trace`, `continue`, `run`, `watch`, `route`, `resume`, `status`. There is still no `create` verb — the spec YAML is authored on disk. `project` is the advancing verb (it projects the next-step packet); `continue` is a read-only inspector, NOT an advance — do not conflate them. The 13-verb set and the project-vs-continue semantics are verified against current product main `d37a08ad` (`packages/cli/src/commands/workflow.ts`, 13 registered `.command(...)` entries; the earlier "6-verb surface / continue-advances" claim here was stale). Verify individual subcommand flags with `rig workflow --help`.)*

## Permission policy — pick one at setup (onboarding)

OpenRig sets only a **minimal usability floor** on your harness permissions and otherwise stays out of the way — then it ships **recommended policies you opt into**. It never bakes a permission policy for you. On install / onboarding this is a required choice, presented as a top-level pick:

- **POLICY MODE** — pick a built-in policy and have it applied:
  - **Locked** — deny-by-default whitelist; untrusted rigs/work.
  - **Standard** ⭐ (recommended) — routine development including push is allowed; PR creation, publication, merge/release, force-push and destructive actions ask.
  - **Open** — allow-by-default; everything except explicitly-destructive, which ask.

  The built-in definitions ship as read-only policy spec files (Locked / Standard / Open); applying your pick is the job of the **`applying-a-permission-policy`** skill — it translates the chosen spec into your live harness config (Claude `settings.json` / Codex `config.toml`), interactively, showing the diff before it writes.
- **YOLO MODE** — done with permissions, just want it to work: OpenRig boots every seat with the harness full-bypass launch flag. No config policy is applied (the bypass overrides it). This is a deterministic OpenRig setting, not a skill.
- **No choice = the floor** — the minimal usability baseline (Claude `acceptEdits` / Codex workspace-only / Pi `--no-approve`), one consistent minimum, nothing more.

The floor and YOLO are **launch flags** OpenRig sets deterministically; the Locked / Standard / Open policies are **config-file** policies the skill applies (agent-driven, because harness config formats drift). A rig **carries** its chosen policy on its spec and boots with it — see Lifecycle → Bring a rig up. To (re)apply or change a policy, open **`applying-a-permission-policy`**.

## v0.3.x Starter, Workspace, And Plugin Surfaces

OpenRig v0.3.0 adds `rig agent-image`, `rig context-pack`, `rig workspace`, and
`rig config init-workspace`. *(0.5.0: the `rig context-pack` alias is retired — the store + compose library is the single `rig context` noun; see "Context packs and paced delivery (0.5.0)".)* It also shifts fresh-user starter guidance toward
`product-team` for human-directed work and `conveyor` for workflow-oriented
work. Treat `demo` as legacy/test content unless a task specifically asks for
the old demo spec. *(0.6.6: the built-in teams are `starter` and `factory`, plus the
specialist teams `code-review`, `research` and `pm`. `product-team`, `conveyor` and
`demo` are gone, and `first-project` is starter's old name. `workshop` is a rig
bundle.)*

OpenRig v0.3.1 adds public package/source surfaces for Plugin Primitive v0,
Claude Auto-Compaction Policy, migration `040_workflow_specs_diagnostic`,
Library Explorer finishing, Settings Destination Explorer, Dashboard/For You
vellum refresh, storytelling adapter, and action outcome + inline error UX.

`rig plugin` is read-only at v0:

```bash
rig plugin list
rig plugin show <id>
rig plugin used-by <id>
rig plugin validate <path>
```

There is no `rig plugin install` verb in v0.3.1. Plugin installation remains
explicit operator copy/symlink to `$OPENRIG_HOME/plugins/<plugin-id>/`.

The v0.3.1 package introduced opt-in Claude auto-compaction policy through
`policies.claude_compaction.*` ConfigStore keys. A package version alone says
nothing about a running daemon's configuration; inspect the selected instance
before relying on a policy or its default.

Compatibility checks:
- `rig down` accepts a rig name or id. An ambiguous name matching more than one
  active rig is refused with matching ids; use the intended id. It ends every
  agent's session and any work in progress, so check `rig ps --nodes --rig <rig>`
  and that the person asked; `rig up <rig> --existing` restores it.
- For queue/view JSON or limit differences, compare the installed command's help,
  the running daemon version and the actual response. A wrapper mismatch is not
  by itself a daemon-health failure, and historical workarounds are not current
  behavior guarantees.
- After a startup timeout, inspect status and logs before retrying; a timeout
  does not establish whether the underlying operation completed.

## Recovery and Resilience (v0.3.4+)

v0.3.4's theme is Recovery + Resilience. The surfaces below compose into a
single boot-to-running-rig path that survives crashes, hand-resumed sessions,
profile-load drift, and partial workspace state without silently fudging
status.

### `rig start` — recovery entrypoint

`rig start` is the top-level recovery sequencer. It does not invent recovery;
it composes existing primitives (daemon start + kernel verify + per-rig
restore) into one call.

```bash
rig start                    # interactive: daemon + kernel + pick-and-restore
rig start --last             # headless: restore rigs that were last running; a rig stopped on purpose stays down
rig start --all              # headless: restore all rigs with restore-usable snapshots
rig start --rigs <name> [<name>...]   # headless: restore only the named rigs
rig start --json             # JSON output for agents
```

`rig start --last` keeps down a rig that was stopped on purpose (`rig down` or `rig seat stop`).
Bring it back with `rig start --rigs <rig>`. A rig whose seat statuses can't be read is still
attempted, with a warning (`seat_status_unreadable`).

Framing: `rig start` is the RECOVERY entry point, not the getting-started
hero. The fresh-user boot hero remains `rig up <team>` (typically
`rig up starter` for a first change, or `rig up factory`). Reach for `rig start` after a host reboot, daemon
restart, or any "bring my rigs back" moment.

### `rig reconcile-session` — no-launch adopt of a hand-resumed session

When an operator has externally resumed an agent session (e.g. attached a
shell, restarted a runtime by hand) and you want OpenRig to reconcile its
lifecycle state without re-launching or sending input, use:

```bash
rig reconcile-session <session>
rig reconcile-session <session> --rig <rigId> --node <logicalId>
rig reconcile-session <session> --no-launch
rig reconcile-session <session> --json
rig reconcile-session <session> --repair-missing-pane --no-launch
```

This is a no-launch, no-input adopt: it records a new claimed session row for
the seat (any running row is superseded); it re-captures the resume token if
it can, and conversation continuity stays unverified. `--rig`/`--node`
disambiguate when the canonical session name does not uniquely resolve.
`--no-launch` is accepted for explicitness.

`--repair-missing-pane --no-launch` is different: for a running launched seat
whose tmux pane was never recorded, it fills in the pane and keeps the
session, resume token and generation. It never adopts. Both forms refuse
while the seat's typing protection is on.

### Five-term restore status vocabulary

The shipped restore vocabulary is intentionally honest. It surfaces in
`rig up` / `rig restore` / `rig ps`. Use the term that fits — do not collapse
to a generic "ok/failed":

- `resumed` — seat resumed from its original session/snapshot and is live.
- `fresh-primed` — seat opted into `--fresh` and was freshly started.
- `awaiting-decision` — zero-session honest state. There is no resumable
  session AND no `--fresh` opt-in was given; the seat is waiting for an
  operator decision. Previously fudged as `failed`; that was wrong — nothing
  is broken, the system is asking for input.
- `attention_required` — seat is in a state needing operator attention; not
  a transport failure. Clear via `rig seat clear-attention` once the
  attention has been resolved.
- `failed` — the send transport or launch genuinely failed.

This replaces the prior collapsed model (the v0.3.3 four-term vocabulary, in
which `rebuilt` was a term, is retired).

### `rig seat clear-attention` — audited reconcile of stuck attention

When a seat is stuck in `attention_required`, do NOT hand-edit SQLite to
fake-clear the state. Use the evidence-gated, operator-attested, audited
reconcile:

```bash
rig seat clear-attention <session>
rig seat clear-attention <session> --reason "operator attested: the operator re-authed, confirmed live"
rig seat clear-attention <session> --json
```

`--reason <text>` can acknowledge startup-status and subset-restore attention.
It does not bypass full-restore continuity checks or an active pane-identity
mismatch/missing-pane check; those run first. Successful identity re-verification
can also clear coexisting startup or subset-restore attention. If neither earlier
path clears attention, omitting `--reason` requires activity or send evidence.
Startup and restore clears write their corresponding audit events; an identity-only
clear updates the current binding and identity verdict without a clear event.
Acknowledgment or responsiveness alone does not prove that the original
conversation resumed.

Two startup cases also end in `attention_required`, and the result says what to do:
- **Assisted startup** (a community harness preset with `startup_assisted: true`): the startup text and Enter were
  sent but submission isn't confirmed. Check the pane and submit any staged text, don't resend it, then run the
  reported `rig seat clear-attention <session> --reason "..."` once the seat has responded.
- **A refused startup turn** (Claude answered a startup turn with a refusal such as an expired login): nothing more is
  typed into the seat, and the result names how many later startup inputs weren't sent. A fresh start that ran no
  one-shot action stays continuable: `rig seat continue <seat>` delivers the whole startup again, the refused turn
  included. A resumed or forked seat keeps its conversation and isn't offered continue; a fresh start that can't
  continue names `rig seat launch <seat> --fresh --stop --reason "<why>"`.

A 422 response names the uncleared class and its failed check. If the recorded
native token needs correction and you know the actual token, use
`rig seat set-resume-token <session> --token-stdin --reason <explanation>`, then
rerun `rig seat clear-attention <session>` to check the live evidence. The token
update records operator provenance; it does not itself prove continuity.
Stopping/relaunching a working seat is a separate disruptive operation, not a
required cleanup or proof of resumed lineage.

### Periodic snapshots — crash-insurance floor

The daemon ships a periodic-snapshot scheduler. It runs independently of
teardown events and provides the crash-insurance floor that prior
event-only/teardown-only snapshots could not provide on hard crashes.

Config keys (SettingsStore):
- `snapshots.periodic.enabled` — default `true`
- `snapshots.periodic.interval_seconds` — default `300`
- `snapshots.periodic.retention_keep` — default `10`

Newest-wins semantics: when both `auto-periodic` and `auto-pre-down`
snapshots exist for a rig, the freshest of the two is selected for restore.
A newer `auto-periodic` beats a stale `auto-pre-down` (the crash fix); a
genuinely-fresher `auto-pre-down` still wins on graceful cycles. Manual
snapshots are handled separately. See
`packages/daemon/src/domain/snapshot-repository.ts` for the ordering rule.

The last-snapshot floor surfaces in `rig ps` / status output so an operator
can see at a glance how recent the crash-insurance floor is.

### Codex profile-v2 preflight

Profile-bearing launch/restore surfaces run a profile-load preflight. When
profile-load issues are detected, the failure is honest and actionable
(named error + remediation pointer) instead of a silent partial launch that
would later look like an attention_required seat with no explanation.

### cmux launch readiness

cmux-backed launches no longer produce silent partial workspace state. When
parts of the workspace are missing, the launch surfaces partial state
honestly and the UI exposes a one-click open-missing affordance.

(See also `## Token-Efficient Defaults (v0.4.0+)` below for the compact-by-default read-command surface that lands in 0.4.0.)

## Token-Efficient Defaults (v0.4.0+)

v0.4.0 flips the five most frequently invoked read-commands from firehose-by-default to compact-by-default, and `rig queue list` adopts the docker / kubectl read-command grammar. **All defaults preserve breadth and capability — the firehose is one explicit flag away.**

### `rig ps` — scope-aware: bare `rig ps` = ALL rigs; `--nodes` = your rig only

```bash
rig ps                      # ALL active rigs on the host, one compact row each — RUN FIRST to know the world
rig ps --rig <name>         # one named rig's summary
rig ps --nodes --rig <name> # per-node (seat) detail for a NAMED rig — the normal drill-in
rig ps --nodes              # per-node detail — CURRENT rig ONLY (deliberately narrow; NOT the whole host)
rig ps --json               # compact JSON (default = a bare array of ALL non-archived rigs)
rig ps --nodes -A           # cross-rig node inventory (was v0.3.4 default)
rig ps --nodes --full       # complete record (the v0.3.4 per-node default shape; resumeToken VALUE retained here for downstream consumers)
rig ps --nodes --session <sess>  # narrow to one canonical session
rig ps --active             # opt-in active-state filter (does NOT change the all-states default — ps surfaces topology/readiness, where stopped/recoverable/attention IS the actionable signal)
```

**v0.4.0 breadth + projection changes**:
- **Rig-level `rig ps` lists ALL active rigs** (one row each — the cheap "know the world" view). The **`--nodes` (per-seat) view defaults to your CURRENT rig only** (from `OPENRIG_SESSION_NAME`'s `@<rig>` suffix); `--rig <name>` picks another rig, `-A` widens `--nodes` to the whole host (expensive — prefer `--fields`/`--limit`).
- **Per-node TL;DR projection (compact) is the default**; `--full` returns the raw byte-equivalent passthrough. Daemon-side `recoveryGuidance` relocated to a guidance-by-reference map (no longer duplicated per-node) — even `--full` benefits.
- **All-states stays default** (different from `rig queue list` which defaults to active-only) — for `ps`, non-running states ARE often the actionable signal.
- **Resume-token security**: `--full` JSON emits `resumeTokenPresent` (boolean) — the actual `resumeToken` value also remains in `--full` for downstream consumers that legitimately need it, but the compact default never carries it (an orch glance never accidentally leaks token material).

**⚠ SCOPE-AWARENESS — the one that bites:** `rig ps --nodes` (and `--nodes --json`) show ONLY your current rig's seats, by design — the narrow default protects your context window. **Narrow...