[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DMQGEJEZCFJZSFG1P4X3CC":3,"skill-same:01M7DMQGEJEZCFJZSFG1P4X3CC":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7DMQGEJEZCFJZSFG1P4X3CC","openrig-user",null,"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.","mvschwarz\u002Fopenrig-world","mvschwarz","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F171890339?v=4","01M7DM95A4N5936P8G2FTSPMY7","Mike Schwarz","01M7DM95AX80NY8HZA7XXDYAZR",16,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world\u002Fblob\u002Fmain\u002Frigs\u002Fworkshop\u002Fagents\u002Fworkshop\u002Fskills\u002Fopenrig-user\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: openrig-user\ndescription: >-\n  Use when a specific `rig` command, subcommand, or flag is already known and you need its exact\n  syntax, JSON shape, defaults, or error meaning. NOT for natural capability discovery, open-ended\n  how-do-I questions, or choosing which OpenRig move applies.\n---\n\n# OpenRig User\n\nThis is an as-built guide to the shipped `rig` CLI.\nUse current code and `rig ... --help` as ground truth if anything here ever conflicts with older planning docs.\n\nUse the OpenRig builder guidance when changing OpenRig behavior, doctrine, or release posture.\n\n\n## Coordination trust boundary\n\nCoordinate as openly as the trust boundary you actually control allows. Within a set of machines you\nown that already trust each other — they can reach each other's daemon URLs and the daemon itself\nrequires no authentication — direct `rig send`, `rig capture`, and `rig queue` should just work.\nDon't invent bearer placeholders, allowlists, trust handshakes, or guest-reach restrictions the\nenvironment doesn't require.\n\nDo not add or defend a restriction without naming the protected asset, the actual adversary, the\nblocked attack path, and the concrete consequence. Missing capability is not protection — repair the\nroute, registration, runtime posture, or product defect directly. Arbitrary boundaries create\nconstraint-induced circumvention: under goal pressure, agents build shadow transports, alternate\ncredentials, and weaker proof instead of the direct authorized path. Keep only explicitly stated\nexternal or irreversible boundaries — public push \u002F PR \u002F publish, and destruction of canonical data.\n\n## Coordination primitives — when to use which\n\nThree coordination surfaces, used together for forward-momentum work. Internalize this\non first read — it shapes every turn you take in a rig.\n\n### `rig send \u003Cseat> \"\u003Ctext>\"` — intra-pod direct messaging \u002F nudges\n\nUse when you need to ask a quick question or give a teammate context that does not\ncarry handoff semantics. **NOT for durable work.** NOT for state that must survive\nacross turns. The message lands in the target's pane; there is no durable queue\nrecord. The CLI prints `Sent to ...` (and `Verified: yes\u002Fno` with `--verify`); read\nthe receipt and move on.\n\nExample:\n\n```bash\nrig send dev-reviewer@example-project \"The import report is ready; the durable handoff names its evidence.\" --verify\n```\n\n### `rig queue create --destination \u003CY> --tags \u003C...> --body-file \u003Cpath>` — durable work item\n\nUse for any substantive work that must not fall through chat — slice handoffs,\nguard verdicts, QA results, full-tip reviews, multi-item batches. Survives agent\nrestarts. Tracked in the daemon SQLite schema. Surfaces in Project \u002F queue views\n+ in the destination seat's inbox. Tag with mission \u002F slice \u002F gate \u002F checkpoint\nso future-you (and any peer) can find it. Give the row a `--summary` (its subject, wherever the row is listed)\nand the `project:`, `mission:` and `slice:` tags when it is project work.\n\nBody discipline: substantive bodies go through **`--body-file \u003Cpath>`** (or `-` for stdin) — the\npurpose-built, corruption-safe surface (it kills the backtick-shell-corruption class for multi-line\nbodies). Do NOT inline a backtick-heavy or multi-line body via `--body`: `rig queue create` body\nparsing breaks on unescaped backticks and rejects flag-like tokens.\n\nExample:\n\n```bash\nrig queue create \\\n  --destination dev-reviewer@example-project \\\n  --summary \"Review the import report: it changes how rows are deduplicated\" \\\n  --tags \"project:example-project,mission:data-import,slice:import-report\" \\\n  --body-file \u002Ftmp\u002Fimport-report-handoff.md\n```\n\n### `rig queue handoff \u003Cqitem-id> --to \u003Cnext> ...` — hot-potato handoff\n\nUse when you have completed your turn on a qitem and the work moves to the next\nowner. **This is forward momentum.** The ball passes to the destination seat;\nchain-of-record (the prior qitem id) is preserved so the verdict trail is intact;\ntags carry the selected work context forward. Gate tags describe checks actually\nselected for that work; they do not require a fixed sequence of roles.\n\nExample:\n\n```bash\nrig queue handoff \u003Cqitem-id> \\\n  --to dev-reviewer@example-project \\\n  --summary \"Review the import report: it changes how rows are deduplicated\" \\\n  --tags \"project:example-project,mission:data-import,slice:import-report\" \\\n  --body-file \u002Ftmp\u002Fimport-report-handoff.md\n```\n\n### After a queue write — use the response; read back only when it doesn't show what you need\n\nA queue write (`create`, `claim`, `update`, `handoff`, `handoff-and-complete`) answers with the row it wrote; a\nhandoff answers with the closed row and its successor. When that answer shows what you need to establish, use it.\n\n`create` also prints `Queue create request ID: \u003Cid> (not proof of persistence)` on stderr *before* it sends the write,\nso an interrupted create can be reconciled. That ID names a request, not a row. The row is the `qitemId` on stdout\nwhen the command exits 0. A non-zero exit means no row was confirmed, even when stdout carries a `qitemId`: an\nindeterminate answer repeats the request ID so you can reconcile by it. Don't merge stderr into stdout and keep the\nfirst `qitem-…` you find there; a refused create prints its request ID first, too.\n\nA timed-out write can still land late. To retry a `create` or `rig stream emit` safely, repeat it unchanged with the\nsame `--id` (create's request ID, or the emit's own), since the daemon keeps one row or item per ID; an emit sent\nwithout `--id` has no ID to reuse, so look for it with `rig stream list --source \u003Cseat>` before emitting again.\n\nRead back (`rig queue show \u003Cid> --full --json`, or `rig queue transitions \u003Cid>`) when the answer doesn't show what you\nneed, for example:\n\n- the outcome was INDETERMINATE (a transport failure, or a 502 `remote_queue_write_failed` that may have reached the\n  other host), or the write warned `qitem_body_not_saved` (an existing row came back). Reconcile by the original ID\n  before any retry. A 502 whose `failureClass` is `unknown-host`, `unsupported-transport` or `registry` isn't\n  indeterminate: the daemon refused before contacting any host and wrote nothing (`create` says \"No row was\n  created\"). `unsupported-transport` means that host entry is SSH-declared. Use the http entry for the same machine\n  from `rig host list`; if there isn't one, add it with that machine's daemon URL (`rig host add --id \u003Cid>\n  --transport http --url \u003Cdaemon-url>`), asking whoever runs that host for the URL;\n- the output was compact or truncated and the field you need isn't in it (the compact receipt shows `bodyBytes`, not\n  the body, and its footer names what it left out);\n- you need a transition note, a closure or blocker detail, or a successor that the output you saw omits;\n- you need evidence from downstream of the write: the recipient's wake (`create --verify` waits for it), or its\n  pickup or claim (a later read);\n- your team's custody rule asks for a separate read-back.\n\nDon't read back only to see again a field the response already showed you.\n\n### §1b doctrine — turn ends by passing the ball\n\n**A turn ends by passing the ball, never by going idle holding the slice waiting\non a confirmation the selected process does not include.** Follow the current\n`mission-slice-sop`: proportional owner checks are the default; independent review\nruns when selected, at the authored work boundary. Role names do not add per-commit\nguard, QA, or orchestration gates. Do the authorized work, run its selected checks,\nand return the outcome through durable custody.\n\nValid pauses are only:\n\n- A genuine blocker — file a blocked-state qitem against the blocking peer or\n  surface explicitly to orch.\n- A scope-or-architecture question that requires owner input and changes the\n  plan — surface to orch with the specific decision needed.\n\nImplementing already-authorized work is neither of these. Proceed without\nphantom-gating on an imagined \"next prompt\" or \"operator confirmation\" that the\nprocess does not require.\n\n### Anti-patterns\n\n- Using `rig send` for durable work → use `rig queue create` instead. Sends do\n  not survive restarts and do not show up in queue\u002Fproject views.\n- Idle-holding a slice for an imagined \"next prompt\" or \"operator confirmation\"\n  that the process does not require → pass the ball via `rig queue handoff` and\n  proceed to the next slice or stand by for the inbound verdict. See the §1b\n  doctrine above.\n- Inlining a multi-line \u002F backtick-heavy body into `rig queue create --body`\n  → use `--body-file \u002Ftmp\u002F\u003Cdescriptive-name>.txt` (or `-` for stdin), the\n  corruption-safe surface. The body parser does not tolerate raw backticks or\n  flag-like tokens inline.\n\n## Runtime-Gated Coordination Primitives\n\nOpenRig v0.3.1 is published publicly as `@openrig\u002Fcli@0.3.1` and GitHub Release\n`v0.3.1`. It includes the bundled PL-004 Coordination Primitive System: Phase A\n`rig stream` \u002F `rig queue`, Phase B `rig project` \u002F `rig view`, Phase C\n`rig watchdog`, and Phase D `rig workflow` \u002F `workflow-keepalive`.\n\nThese are shipped product surfaces in v0.3.x, but they require a compatible\nv0.3.x daemon and matching SQLite schema at runtime — the installed package\nversion is not automatically the version of the daemon serving you. If a\ncoordination command behaves unexpectedly, confirm the running daemon with\n`rig whoami --json` and daemon status before assuming a product bug.\n\nDefault posture:\n\n- Treat daemon `rig queue`, `rig stream`, `rig project`, `rig view`, `rig watchdog`, and\n  `rig workflow` as the product coordination surfaces when the active daemon is v0.2.0 or newer.\n- Use daemon-backed `rig queue` for durable routing. `update \u002F show \u002F list`\n  complement `create \u002F handoff` for inspection and state changes; records in an\n  unrelated store are not evidence that this daemon owns the work.\n- If a daemon-backed coordination command fails, debug the command\u002Fruntime\u002Fschema edge directly;\n  do not assume the right workaround is to drop back to a config-layer primitive.\n- Do not perform daemon stop\u002Fstart, production DB copy\u002Fmutation, release, publish, or other\n  consequence-boundary actions unless the operator\u002Fworkstream has granted that specific gate.\n\n## First-user workspace setup\n\nWhen booting into a rig on a host where the workspace is unset, gap-ridden, or\npoints at a stale layout, address that before substantive project work. The\nshipped surface is small + bounded — reach for the canonical commands rather\nthan improvising.\n\n### Detect workspace state at boot\n\nAgent-actionable when the daemon is reachable.\n\n```bash\nrig workspace validate --json\nrig workspace validate \u003Cpath> --kind \u003Cuser|project|knowledge|lab|delivery> --json\n```\n\n`rig workspace validate` walks the workspace root and emits a structured\nfrontmatter-gap report against the v0 contract. Exit code is non-zero when\ngaps exist (operators chain into hygiene fix loops). Default root is the\ncurrent directory; pass a positional path to validate elsewhere. `--kind`\nscopes the contract to a specific workspace kind; omit for a kind-agnostic\nstructural check.\n\nIf `rig workspace validate` reports a non-zero `gapCount` OR the workspace\nroot is unset \u002F unwritable, the workspace needs instantiation — see the next\nsection.\n\n### Instantiate the canonical workspace scaffold\n\nAgent-actionable. The operation is additive and preserves existing files.\n\n```bash\nrig config init-workspace\nrig config init-workspace --root \u003Cpath>\nrig config init-workspace --dry-run --json\n```\n\n`rig config init-workspace` scaffolds the canonical workspace layout at the\nconfigured `workspace.root` (default `~\u002F.openrig\u002Fworkspace`):\n\n- `missions\u002F` — release missions + slices\n- `exhaust\u002F` — project-local coordination exhaust\n- `SPEC.md` — project intent\n- `project.yaml` — project catalog selections and mission root\n- `workspace.yaml` — project registration\n- `.gitignore` — local OpenRig state and exhaust exclusions\n\n`--root \u003Cpath>` targets a non-default root for this call; `--dry-run` reports\nwhat would be created without writing. `--force` is deprecated compatibility\nand still preserves existing files.\n\n### Redirect the workspace root\n\nOperator-gated when persistent. Agent-actionable when one-shot via env-var.\n\nFor a single command:\n\n```bash\nOPENRIG_WORKSPACE_ROOT=\u003Cpath> rig \u003Ccommand> ...\n```\n\nFor a persistent host-level redirect, the operator changes the config file or\nruns the setter:\n\n```bash\nrig config set workspace.root \u003Cpath>\n```\n\nConfigStore precedence: `OPENRIG_WORKSPACE_ROOT` env > config-file\n`workspace.root` > built-in default `~\u002F.openrig\u002Fworkspace`. The same\nprecedence governs `OPENRIG_WORKSPACE_SPECS_ROOT` → `workspace.specs_root`\n(default `\u003Cworkspace_root>\u002Fspecs`).\n\nPrefer the env-var form for one-shot redirects (transparent to operators);\nreserve `rig config set` for changes the operator owns.\n\n### Build a workspace from scratch\n\nAgent-actionable. Same surface as the canonical scaffold above; the\n`workspace.root` cascade handles non-existent host paths.\n\n```bash\nrig config init-workspace --root \u002Fpath\u002Fto\u002Fnew\u002Fworkspace\n```\n\nThe command additively creates any missing canonical entries and preserves\nevery existing one; only a complete six-entry scaffold is a no-op. Run\n`rig workspace validate \u002Fpath\u002Fto\u002Fnew\u002Fworkspace --json` after to confirm the\ncontract holds.\n\n### Create a workflow inside an existing workspace\n\nAuthoring is operator-or-agent; validation + instantiation are\nagent-actionable.\n\nWorkflow spec files live at:\n\n```\n\u003Cworkspace_root>\u002Fspecs\u002Fworkflows\u002F\u003Cname>.yaml\n```\n\n`\u003Cworkspace_root>` resolves via the ConfigStore precedence named above.\nThere is no `rig workflow create` verb in v0.3.x — the spec YAML is authored\ndirectly. Template by hand from the documented schema, or copy a built-in\nstarter from `\u003Copenrig install>\u002Fdist\u002Fbuiltins\u002Fworkflow-specs\u002F` and adapt.\nOnce written:\n\n```bash\nrig workflow validate \u003Cworkspace_root>\u002Fspecs\u002Fworkflows\u002F\u003Cname>.yaml --json\n\nrig workflow instantiate \u003Cworkspace_root>\u002Fspecs\u002Fworkflows\u002F\u003Cname>.yaml \\\n  --root-objective \"\u003Cone-line objective for the run>\" \\\n  --created-by \u003Cyour-session>@\u003Cyour-rig> \\\n  --json\n```\n\nBoth `--root-objective \u003Ctext>` and `--created-by \u003Csession>` are REQUIRED\non `instantiate` — omitting either yields a Commander required-option\nerror before the daemon is contacted. `--entry-owner \u003Csession>` is an\noptional override for the entry-step owner; default routing is per the\nworkflow spec.\n\n`validate` returns a structured ok\u002Ferror report; `instantiate` creates a\nworkflow instance + entry-step qitem. Inspect existing surface state with:\n\n```bash\nrig workflow specs --json              # list registered specs (built-in + operator-authored)\nrig workflow list --json               # list active workflow instances\nrig workflow show \u003CinstanceId> --json  # inspect one instance\nrig workflow project \u003CinstanceId>      # ADVANCE an instance — projects the next-step packet\nrig workflow continue \u003CinstanceId>     # read-only inspector of an instance (does NOT advance it)\n```\n\n*(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\u002Fcli\u002Fsrc\u002Fcommands\u002Fworkflow.ts`, 13 registered `.command(...)` entries; the earlier \"6-verb surface \u002F continue-advances\" claim here was stale). Verify individual subcommand flags with `rig workflow --help`.)*\n\n## Permission policy — pick one at setup (onboarding)\n\nOpenRig 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 \u002F onboarding this is a required choice, presented as a top-level pick:\n\n- **POLICY MODE** — pick a built-in policy and have it applied:\n  - **Locked** — deny-by-default whitelist; untrusted rigs\u002Fwork.\n  - **Standard** ⭐ (recommended) — routine development including push is allowed; PR creation, publication, merge\u002Frelease, force-push and destructive actions ask.\n  - **Open** — allow-by-default; everything except explicitly-destructive, which ask.\n\n  The built-in definitions ship as read-only policy spec files (Locked \u002F Standard \u002F 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` \u002F Codex `config.toml`), interactively, showing the diff before it writes.\n- **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.\n- **No choice = the floor** — the minimal usability baseline (Claude `acceptEdits` \u002F Codex workspace-only \u002F Pi `--no-approve`), one consistent minimum, nothing more.\n\nThe floor and YOLO are **launch flags** OpenRig sets deterministically; the Locked \u002F Standard \u002F 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`**.\n\n## v0.3.x Starter, Workspace, And Plugin Surfaces\n\nOpenRig v0.3.0 adds `rig agent-image`, `rig context-pack`, `rig workspace`, and\n`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\n`product-team` for human-directed work and `conveyor` for workflow-oriented\nwork. Treat `demo` as legacy\u002Ftest content unless a task specifically asks for\nthe old demo spec. *(0.6.6: the built-in teams are `starter` and `factory`, plus the\nspecialist teams `code-review`, `research` and `pm`. `product-team`, `conveyor` and\n`demo` are gone, and `first-project` is starter's old name. `workshop` is a rig\nbundle.)*\n\nOpenRig v0.3.1 adds public package\u002Fsource surfaces for Plugin Primitive v0,\nClaude Auto-Compaction Policy, migration `040_workflow_specs_diagnostic`,\nLibrary Explorer finishing, Settings Destination Explorer, Dashboard\u002FFor You\nvellum refresh, storytelling adapter, and action outcome + inline error UX.\n\n`rig plugin` is read-only at v0:\n\n```bash\nrig plugin list\nrig plugin show \u003Cid>\nrig plugin used-by \u003Cid>\nrig plugin validate \u003Cpath>\n```\n\nThere is no `rig plugin install` verb in v0.3.1. Plugin installation remains\nexplicit operator copy\u002Fsymlink to `$OPENRIG_HOME\u002Fplugins\u002F\u003Cplugin-id>\u002F`.\n\nThe v0.3.1 package introduced opt-in Claude auto-compaction policy through\n`policies.claude_compaction.*` ConfigStore keys. A package version alone says\nnothing about a running daemon's configuration; inspect the selected instance\nbefore relying on a policy or its default.\n\nCompatibility checks:\n- `rig down` accepts a rig name or id. An ambiguous name matching more than one\n  active rig is refused with matching ids; use the intended id. It ends every\n  agent's session and any work in progress, so check `rig ps --nodes --rig \u003Crig>`\n  and that the person asked; `rig up \u003Crig> --existing` restores it.\n- For queue\u002Fview JSON or limit differences, compare the installed command's help,\n  the running daemon version and the actual response. A wrapper mismatch is not\n  by itself a daemon-health failure, and historical workarounds are not current\n  behavior guarantees.\n- After a startup timeout, inspect status and logs before retrying; a timeout\n  does not establish whether the underlying operation completed.\n\n## Recovery and Resilience (v0.3.4+)\n\nv0.3.4's theme is Recovery + Resilience. The surfaces below compose into a\nsingle boot-to-running-rig path that survives crashes, hand-resumed sessions,\nprofile-load drift, and partial workspace state without silently fudging\nstatus.\n\n### `rig start` — recovery entrypoint\n\n`rig start` is the top-level recovery sequencer. It does not invent recovery;\nit composes existing primitives (daemon start + kernel verify + per-rig\nrestore) into one call.\n\n```bash\nrig start                    # interactive: daemon + kernel + pick-and-restore\nrig start --last             # headless: restore rigs that were last running; a rig stopped on purpose stays down\nrig start --all              # headless: restore all rigs with restore-usable snapshots\nrig start --rigs \u003Cname> [\u003Cname>...]   # headless: restore only the named rigs\nrig start --json             # JSON output for agents\n```\n\n`rig start --last` keeps down a rig that was stopped on purpose (`rig down` or `rig seat stop`).\nBring it back with `rig start --rigs \u003Crig>`. A rig whose seat statuses can't be read is still\nattempted, with a warning (`seat_status_unreadable`).\n\nFraming: `rig start` is the RECOVERY entry point, not the getting-started\nhero. The fresh-user boot hero remains `rig up \u003Cteam>` (typically\n`rig up starter` for a first change, or `rig up factory`). Reach for `rig start` after a host reboot, daemon\nrestart, or any \"bring my rigs back\" moment.\n\n### `rig reconcile-session` — no-launch adopt of a hand-resumed session\n\nWhen an operator has externally resumed an agent session (e.g. attached a\nshell, restarted a runtime by hand) and you want OpenRig to reconcile its\nlifecycle state without re-launching or sending input, use:\n\n```bash\nrig reconcile-session \u003Csession>\nrig reconcile-session \u003Csession> --rig \u003CrigId> --node \u003ClogicalId>\nrig reconcile-session \u003Csession> --no-launch\nrig reconcile-session \u003Csession> --json\nrig reconcile-session \u003Csession> --repair-missing-pane --no-launch\n```\n\nThis is a no-launch, no-input adopt: it records a new claimed session row for\nthe seat (any running row is superseded); it re-captures the resume token if\nit can, and conversation continuity stays unverified. `--rig`\u002F`--node`\ndisambiguate when the canonical session name does not uniquely resolve.\n`--no-launch` is accepted for explicitness.\n\n`--repair-missing-pane --no-launch` is different: for a running launched seat\nwhose tmux pane was never recorded, it fills in the pane and keeps the\nsession, resume token and generation. It never adopts. Both forms refuse\nwhile the seat's typing protection is on.\n\n### Five-term restore status vocabulary\n\nThe shipped restore vocabulary is intentionally honest. It surfaces in\n`rig up` \u002F `rig restore` \u002F `rig ps`. Use the term that fits — do not collapse\nto a generic \"ok\u002Ffailed\":\n\n- `resumed` — seat resumed from its original session\u002Fsnapshot and is live.\n- `fresh-primed` — seat opted into `--fresh` and was freshly started.\n- `awaiting-decision` — zero-session honest state. There is no resumable\n  session AND no `--fresh` opt-in was given; the seat is waiting for an\n  operator decision. Previously fudged as `failed`; that was wrong — nothing\n  is broken, the system is asking for input.\n- `attention_required` — seat is in a state needing operator attention; not\n  a transport failure. Clear via `rig seat clear-attention` once the\n  attention has been resolved.\n- `failed` — the send transport or launch genuinely failed.\n\nThis replaces the prior collapsed model (the v0.3.3 four-term vocabulary, in\nwhich `rebuilt` was a term, is retired).\n\n### `rig seat clear-attention` — audited reconcile of stuck attention\n\nWhen a seat is stuck in `attention_required`, do NOT hand-edit SQLite to\nfake-clear the state. Use the evidence-gated, operator-attested, audited\nreconcile:\n\n```bash\nrig seat clear-attention \u003Csession>\nrig seat clear-attention \u003Csession> --reason \"operator attested: the operator re-authed, confirmed live\"\nrig seat clear-attention \u003Csession> --json\n```\n\n`--reason \u003Ctext>` can acknowledge startup-status and subset-restore attention.\nIt does not bypass full-restore continuity checks or an active pane-identity\nmismatch\u002Fmissing-pane check; those run first. Successful identity re-verification\ncan also clear coexisting startup or subset-restore attention. If neither earlier\npath clears attention, omitting `--reason` requires activity or send evidence.\nStartup and restore clears write their corresponding audit events; an identity-only\nclear updates the current binding and identity verdict without a clear event.\nAcknowledgment or responsiveness alone does not prove that the original\nconversation resumed.\n\nTwo startup cases also end in `attention_required`, and the result says what to do:\n- **Assisted startup** (a community harness preset with `startup_assisted: true`): the startup text and Enter were\n  sent but submission isn't confirmed. Check the pane and submit any staged text, don't resend it, then run the\n  reported `rig seat clear-attention \u003Csession> --reason \"...\"` once the seat has responded.\n- **A refused startup turn** (Claude answered a startup turn with a refusal such as an expired login): nothing more is\n  typed into the seat, and the result names how many later startup inputs weren't sent. A fresh start that ran no\n  one-shot action stays continuable: `rig seat continue \u003Cseat>` delivers the whole startup again, the refused turn\n  included. A resumed or forked seat keeps its conversation and isn't offered continue; a fresh start that can't\n  continue names `rig seat launch \u003Cseat> --fresh --stop --reason \"\u003Cwhy>\"`.\n\nA 422 response names the uncleared class and its failed check. If the recorded\nnative token needs correction and you know the actual token, use\n`rig seat set-resume-token \u003Csession> --token-stdin --reason \u003Cexplanation>`, then\nrerun `rig seat clear-attention \u003Csession>` to check the live evidence. The token\nupdate records operator provenance; it does not itself prove continuity.\nStopping\u002Frelaunching a working seat is a separate disruptive operation, not a\nrequired cleanup or proof of resumed lineage.\n\n### Periodic snapshots — crash-insurance floor\n\nThe daemon ships a periodic-snapshot scheduler. It runs independently of\nteardown events and provides the crash-insurance floor that prior\nevent-only\u002Fteardown-only snapshots could not provide on hard crashes.\n\nConfig keys (SettingsStore):\n- `snapshots.periodic.enabled` — default `true`\n- `snapshots.periodic.interval_seconds` — default `300`\n- `snapshots.periodic.retention_keep` — default `10`\n\nNewest-wins semantics: when both `auto-periodic` and `auto-pre-down`\nsnapshots exist for a rig, the freshest of the two is selected for restore.\nA newer `auto-periodic` beats a stale `auto-pre-down` (the crash fix); a\ngenuinely-fresher `auto-pre-down` still wins on graceful cycles. Manual\nsnapshots are handled separately. See\n`packages\u002Fdaemon\u002Fsrc\u002Fdomain\u002Fsnapshot-repository.ts` for the ordering rule.\n\nThe last-snapshot floor surfaces in `rig ps` \u002F status output so an operator\ncan see at a glance how recent the crash-insurance floor is.\n\n### Codex profile-v2 preflight\n\nProfile-bearing launch\u002Frestore surfaces run a profile-load preflight. When\nprofile-load issues are detected, the failure is honest and actionable\n(named error + remediation pointer) instead of a silent partial launch that\nwould later look like an attention_required seat with no explanation.\n\n### cmux launch readiness\n\ncmux-backed launches no longer produce silent partial workspace state. When\nparts of the workspace are missing, the launch surfaces partial state\nhonestly and the UI exposes a one-click open-missing affordance.\n\n(See also `## Token-Efficient Defaults (v0.4.0+)` below for the compact-by-default read-command surface that lands in 0.4.0.)\n\n## Token-Efficient Defaults (v0.4.0+)\n\nv0.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 \u002F kubectl read-command grammar. **All defaults preserve breadth and capability — the firehose is one explicit flag away.**\n\n### `rig ps` — scope-aware: bare `rig ps` = ALL rigs; `--nodes` = your rig only\n\n```bash\nrig ps                      # ALL active rigs on the host, one compact row each — RUN FIRST to know the world\nrig ps --rig \u003Cname>         # one named rig's summary\nrig ps --nodes --rig \u003Cname> # per-node (seat) detail for a NAMED rig — the normal drill-in\nrig ps --nodes              # per-node detail — CURRENT rig ONLY (deliberately narrow; NOT the whole host)\nrig ps --json               # compact JSON (default = a bare array of ALL non-archived rigs)\nrig ps --nodes -A           # cross-rig node inventory (was v0.3.4 default)\nrig ps --nodes --full       # complete record (the v0.3.4 per-node default shape; resumeToken VALUE retained here for downstream consumers)\nrig ps --nodes --session \u003Csess>  # narrow to one canonical session\nrig ps --active             # opt-in active-state filter (does NOT change the all-states default — ps surfaces topology\u002Freadiness, where stopped\u002Frecoverable\u002Fattention IS the actionable signal)\n```\n\n**v0.4.0 breadth + projection changes**:\n- **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 `@\u003Crig>` suffix); `--rig \u003Cname>` picks another rig, `-A` widens `--nodes` to the whole host (expensive — prefer `--fields`\u002F`--limit`).\n- **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.\n- **All-states stays default** (different from `rig queue list` which defaults to active-only) — for `ps`, non-running states ARE often the actionable signal.\n- **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).\n\n**⚠ 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 output is not the whole world.** Never conclude \"my rig is the only rig on the host\" from a `--nodes` read — run bare `rig ps` FIRST (cheap; it lists every rig), then `rig ps --nodes --rig \u003Cname>` for the one you need. (`-A` widens to the whole-host node view; choose it when that breadth is needed.)\n\n### `rig whoami` — compact-by-default + `--full` (`--verbose` alias)\n\n```bash\nrig whoami                  # compact: identity + peers names + edges + transcript path\nrig whoami --json           # compact JSON\nrig whoami --json --all-peers  # compact JSON with every peer, when output.compact bounds the list\nrig whoami --full           # complete payload (v0.3.4 default shape)\nrig whoami --verbose        # alias of --full\n```\n\nThe first command every agent runs on boot AND every compaction-restore. The compact default keeps identity-recovery essentials (`identity`, `peers` names + sessionNames, `peersNote`, `edges` directional `kind` + `to.sessionName`, the transcript path). `--full` adds `contextUsage`, `commands`, `runtimeContext` and `workspace`. With `output.compact` on, compact JSON lists at most `output.whoami_peers` peers (default 8): edge peers first, then your pod, then roster order. `peersNote` and `peersOmitted` then say how many were left out, and `--all-peers` lists every one; `edges` stays complete. The compact-default is an ALLOWLIST projection — future payload fields default to `--full` and cannot silently re-bloat the every-boot path.\n\n### `rig queue list` — active-frontier + docker\u002Fkubectl grammar\n\n```bash\nrig queue list                       # active, compact, CURRENT-rig (docker-ps default)\nrig queue list -a                    # + closed\u002Fdone history within current breadth (docker -a)\nrig queue list -A                    # cross-rig breadth (kubectl -A)\nrig queue list --full                # add body + chain-of-record + transition history\nrig queue list -o json               # compact JSON (token-safe, machine-parseable)\nrig queue list --full -o json        # full JSON\nrig queue list --mine                # just the caller's items\nrig queue list --destination \u003Cs>     # destined to \u003Cs>\nrig queue list --source \u003Cs>          # sourced by \u003Cs>\nrig queue show \u003CqitemId>             # bounded single-item body preview\nrig queue show \u003CqitemId> --full      # complete body and chain fields; a closed row adds closingTransition (the close's state, reason, target, actor, time and note)\n```\n\nFour orthogonal axes (scope × history × field-breadth × encoding), all composable. **STOP using bare `rig queue list` as the cross-rig firehose.** Default is now active + compact + current-rig. Cross-rig history with full bodies is opt-in via `-A -a --full`; request only the breadth and fields needed for the question.\n\n### `rig restore-check` — summary + not-ready-only default + `--full`\n\n```bash\nrig restore-check               # summary counts + not-ready seats (with reasons) only\nrig restore-check --full        # complete per-seat readiness across the fleet (v0.3.4 default)\nrig restore-check --rig \u003Cname>  # narrow\nrig restore-check --as \u003Csession>  # narrow to one seat\n```\n\nThe summary retains not-ready seats and their reasons; `--full` adds ready-seat detail when needed. Scope the query before expanding its payload.\n\n### `rig context` — context-window usage viewer (0.4.x; REMOVED in 0.5.0)\n\n```bash\nrig context                # compact summary        (0.4.x only)\nrig context --full         # complete current payload\nrig context --rig \u003Cname>   # narrow to one rig\nrig context --threshold 80 # filter to seats at\u002Fabove 80%\n```\n\nLower leverage than the others; keeps the read-command surface compact-by-default after the 0.4.0 upgrade. **⚠ 0.5.0: this usage viewer is removed entirely and the `rig context` name is reassigned to the context library (store + compose) — see \"Context packs and paced delivery (0.5.0)\" below. On a 0.5.0 host, bare `rig context` is the library, not this viewer.**\n\n### Keep routine reads bounded\n\nChoose scope, active\u002Fhistory breadth and fields before expanding a result. A\nstatus question usually needs identifiers, owner, state and reason; open the full\nbody or artifact when it is relevant. Preserve full evidence on disk instead of\nrepeatedly loading unchanged output. Compact defaults reduce reading cost; they\ndo not remove the full-detail path or prove that nothing exists outside the scope.\n\n### `rig scope mission|slice progress` — deterministic progress updates\n\n```bash\nrig scope mission progress \u003Cmission> --add \"\u003Cline>\"   # append a progress line; --set replaces; --section \u003Cheading> (default Rail); --status active|done|blocked\nrig scope slice progress \u003Cslice-path> --add \"\u003Cline>\"  # same flags: --add \u002F --set, --section \u003Cheading>, --status active|done|blocked\n```\n\nReplaces hand-editing `PROGRESS.md` with markdown. Writes the canonical structure the OpenRig PROGRESS UI page reads. `rig scope mission create` + `rig scope slice create` now scaffold `PROGRESS.md` automatically.\n\n### `rig scope mission|slice stage \u002F verified \u002F repair` — deterministic maturity vocabulary\n\n```bash\nrig scope slice stage \u003Cslice> \u003Cnew-stage>             # wip \u002F provisional \u002F established \u002F canonical \u002F superseded \u002F retired\nrig scope slice stage \u003Cslice> superseded --successor \u003Cid>  # superseded REQUIRES --successor (rejected otherwise)\nrig scope mission stage \u003Cmission> \u003Cnew-stage>         # same enum + rules at mission tier\n\nrig scope slice verified \u003Cslice> --against \"\u003Csource>\" # stamp `verified: \u003Ctoday> against \u003Csource>`; --against MANDATORY\nrig scope mission verified \u003Cmission> --against \"\u003Csource>\"\n\nrig scope slice repair \u003Cslice>                        # idempotent repair: backfill PROGRESS.md, conform id\u002Fstage\u002Fverified, repair ghosts\nrig scope mission repair \u003Cmission>                    # mission-tier idempotent repair\n\nrig scope slice show \u003Cslice>                          # derives read-time effective-reliability from (stage × verified)\n                                                      # — stale-`verified` `canonical` reported as effectively `provisional`\n```\n\nComposes with the `progress` command + scaffolding to update scope IDs and maturity vocabulary through `rig scope`. Agents update `stage` \u002F `verified` \u002F `id` through commands rather than hand-editing markdown and drifting. The `--against` MANDATORY rule on `verified` is the anti-stale keystone: bare timestamps are rejected because a bare timestamp is exactly what lets stale trackers lie while looking fresh. **STOP hand-editing the `stage` \u002F `verified` \u002F `id` fields in scope frontmatter; use the new verbs.** Existing missions \u002F slices with `id:null` ghosts or missing `PROGRESS.md` are repaired idempotently via `repair`.\n\n### `rig skill audit` — skill cascade provenance\n\n```bash\nrig skill audit                  # human report of findings\nrig skill audit --json           # structured findings\nrig skill audit --severity warn  # stale + mirror-drift only\nrig skill audit --rig \u003Cname>     # narrow to embedded skill copies for one rig\n```\n\nRead-only audit of the skill cascade. Detects `missing` \u002F `stale` \u002F `self-referential` \u002F `invalid-date` \u002F `mirror-drift` across the canonical skills workspace → product mirror → hub cwd → installed plugin chain. Findings route back to the lifecycle for shaped propagation runs. **False-green prevention**: when audit evidence is unavailable, the CLI emits `unable-to-audit` with exit code `2` rather than reporting `clean`.\n\n### `rig seat clear-attention` — extended to derived projection staleness\n\n`clear-attention` also reaches restore-derived attention even when\n`startupStatus=ready` and `sessionStatus=running`. Full-restore attention requires\nthe restore reconciler's exact native-token and usable-pane checks; `--reason`\ncannot replace them. Subset-restore attention can reach the attestation path\nwhen no active pane-identity class takes precedence. That path records\n`operator_recovered` with `runtimeCwdVerified:false`; it is an acknowledgment,\nnot proof of resumed lineage. Without an explicit stored continuity outcome,\ninventory leaves continuity null (`unverified` in `rig seat status`) unless the\nsame restore attempt has a matching receipt and reconciliation with strict\nnative-token and usable-pane proof. Explicit stored outcomes remain historical\nfacts; acknowledgment or responsiveness alone cannot infer `resumed`.\n\n### Native Codex session id capture\n\nCodex seats can now record the real native session id from the Codex\n`SessionStart` hook instead of relying on scrape-shaped identity. Corroborate the id across the current hook payload, provider history and\nmanaged record before relying on it. A release introducing native capture does\nnot prove that every existing seat uses it; retain any unavailable or conflicting\nidentity evidence explicitly.\n\n### Codex resume preserves approval posture\n\nResuming a Codex seat preserves the launching seat's approval\u002Fsandbox posture\nand profile flags. Product-emitted resume commands carry the posture flags\ninstead of silently falling back to implicit-deny or an unrelated profile.\n\nDo not \"fix\" a resumed Codex seat by relaunching it with broader approvals\nunless the operator explicitly grants a bounded window. Verify the seat's\nactive posture first, and preserve it when composing recovery commands.\n\n### `rig seat set-resume-token --token-stdin`\n\n```bash\nprintf '%s' \"$RESUME_TOKEN\" | rig seat set-resume-token \u003Csession> --token-stdin\n```\n\nUse this command to set or restore a seat resume token. It replaces direct\nSQLite edits, rejects unauthorized writes and bad\u002Fnull token false-ready paths,\nrecords redacted audit\u002Fprovenance, and keeps token material out of command\narguments, stdout, logs, and normal status rows. Use stdin, not an inline flag,\nwhen passing token material.\n\n## Core Loop\n\nMost work in OpenRig reduces to this loop:\n- recover identity: `rig whoami` (compact default; add `--full` only when you need the heavy payload)\n- inspect inventory: `rig ps --nodes` (compact default; add `--full` only when you need the firehose)\n- read context: `rig transcript ...`, `rig ask ...`, `rig chatroom history ...`\n- act: `rig send`, `rig capture`, `rig broadcast`, lifecycle commands\n\n## Agent-Managed Apps\n\nAn agent-managed app is a deployable OpenRig unit made of:\n- the software or service\n- one specialist agent dedicated to that software\n\nTreat the specialist as the domain delegate for that app.\nThe current canonical example is:\n- rig: `secrets-manager`\n- pod: `vault`\n- member: `specialist`\n- logical ID: `vault.specialist`\n- session: `vault-specialist@secrets-manager`\n\nTypical operator loop:\n\n```bash\nrig up secrets-manager --cwd \u002Fpath\u002Fto\u002Fproject\nrig ps --nodes --json\nrig send vault-specialist@secrets-manager \"Check Vault health and report back.\" --verify\nrig env status secrets-manager\nrig env logs secrets-manager\n```\n\nCross-rig communication is valid when the target session resolves uniquely.\nExample:\n\n```bash\nrig send vault-specialist@secrets-manager \"Read secret\u002Fdata\u002Fdogfood and report the value.\" --verify\n```\n\nUse the specialist instead of teaching every peer the same app-specific toolchain.\nFor Vault, ask `vault.specialist` to do secrets-domain work rather than improvising curl or Vault CLI usage in unrelated agents.\n\n## Identity and Recovery\n\nStart here after launch, compaction, or confusion:\n\n```bash\nrig whoami --json\n```\n\nWhat it gives you today:\n- identity: rig, logical ID, pod\u002Fmember, session name, runtime\n- peers and directional edges\n- transcript info\n- `contextUsage` when available\n\nFlags:\n```bash\nrig whoami --session \u003Cname>\nrig whoami --node-id \u003Cid>\n```\n\nIf the daemon is unreachable but identity can still be inferred, `--json` may return a partial result instead of crashing.\n\n`WhoamiResult` (v0.3.3+) carries a required `peersNote` field with three pointers\nthe agent can use to navigate the rest of the rig from a cold start. The\nhuman-formatted CLI output preserves the literal `Peers:` line prefix verbatim\n(parser\u002Ftest compatibility) and surfaces the clarifier in-band beneath it; the\nJSON form exposes `peersNote` directly for programmatic consumers.\n\n## Inventory and Monitoring\n\n```bash\nrig ps                      # ALL active rigs on the host, one compact row each (run FIRST to know the world)\nrig ps --nodes              # compact node inventory (current rig)\nrig ps -A                   # all-rigs breadth (was the pre-0.4.0 default)\nrig ps --nodes --full       # complete per-node record (the firehose — opt-in)\nrig ps --nodes --json       # compact JSON node inventory (add --full for the full record)\n```\n\n**v0.4.0 flipped these to compact-by-default — see the `rig ps` compact-defaults section above; STOP using bare `rig ps --nodes --json` as a fleet-wide firehose (scope and detail are separate choices).** The compact `rig ps --nodes` node inventory (add `--full` only when you need the complete record, `-A` for cross-rig breadth) carries, per node:\n- session name\n- runtime\n- session\u002Fstartup status\n- restore outcome (compact: `resumeTokenPresent` boolean; the token VALUE is in `--full`)\n- attach\u002Fresume commands\n- latest error\n\nOther health surfaces:\n\n```bash\nrig status\nrig daemon status\nrig config\nrig preflight\nrig doctor\nrig env status \u003Crig>\nrig env logs \u003Crig>\nrig env down \u003Crig>\n```\n\n### Bounded agent self-scout\n\nUse the typed health projection before reading raw coordination history. The\ndefault query is the current seat; widen deliberately when the evidence points\nbeyond it:\n\n```bash\nrig health --json\nrig health --rig \u003Crig-id> --json\nrig health --instance --json\nrig health explain \u003Cfinding-id> --json\n```\n\nFollow the returned stable finding ID and `suggestedInspection`. Use `explain`\nwhen the summary matters: it returns the same canonical record with its bounded\nwindow, freshness, literal detector rule, evidence references, and next\ninspection. Human output projects those same fields; it does not calculate a\nsecond score.\n\nAn empty result means only that no records matched the bounded query. It is\n**not a healthy assertion**. Stale, unavailable, contradictory, and\nindeterminate evidence stays explicit. Never read raw SQLite for a self-scout,\nand never turn a finding into an acknowledgement, notification, queue row, or\nremediation automatically: `rig health` is strictly read-only.\n\n## Transcript and Communication\n\n### Transcript access\n\n```bash\nrig transcript \u003Csession> --tail 100\nrig transcript \u003Csession> --grep \"pattern\"\nrig transcript \u003Csession> --json\n```\n\n### Send to one session\n\n```bash\nrig send \u003Csession> \"message\"\nrig send \u003Csession> \"message\" --verify\nrig send \u003Csession> \"message\" --wait-for-idle \u003Cseconds>\nrig send \u003Csession> \"message\" --raw\nrig send \u003Csession> \"message\" --dangerously-interact --reason \"\u003Cwhy>\"\nrig send \u003Csession> \"message\" --host \u003Cid>\nrig send \u003Csession> \"message\" --json\n```\n\n**The send-guard (v0.4.0) — the default is SAFE.** A default `rig send` is guarded: it will NOT submit into an interactive prompt \u002F permission block on the target pane. That includes Claude's MCP server approval menu (`N new MCP servers found in .mcp.json`, ending `Space to select · Enter to confirm · Esc to reject all`) while it is the current screen: the send is refused with reason `target_needs_input` and `Refused: '\u003Csession>' is at an interactive prompt (selection_prompt). A message must not select or approve it. … No text was sent.` Approving or rejecting those servers is the person's call; `--dangerously-interact` drives it only deliberately. Flags:\n- `--verify` — delivery evidence.\n- `--force` — **a back-compat no-op on the send DECISION**: it never bypasses the interactive-prompt\u002Fpermission guard and never changes whether a message is delivered (a mid-task\u002Fbusy pane already sends-with-advisory by default). *(It does NOT \"bypass activity-risk checks\" — that earlier teaching is retired.)* It is **not fully inert**, though — it is still parsed solely to be **rejected in combination with `--wait-for-idle`**: `rig send … --force --wait-for-idle \u003Cn>` prints `--wait-for-idle cannot be combined with --force`, exits 1, and sends nothing. So do not read \"no-op\" as \"`--force --wait-for-idle` is harmless\"; that pairing errors. *(Verified against current product main `d37a08ad`: the guard-bypass no-op is declared at `send.ts` and confirmed by runtime capture — a plain `--force` send delivers through the ordinary path; the `--wait-for-idle` rejection is enforced at `send.ts`, `routes\u002Ftransport.ts`, and `session-transport.ts`, and confirmed by runtime capture — exit 1, nothing sent.)*\n- `--wait-for-idle \u003Cseconds>` — wait until the target is explicitly idle before sending. **Cannot be combined with `--force`** (that pairing is rejected: exit 1, nothing sent).\n- `--raw` — send exact text\u002Fkeystrokes without the From\u002FTo messaging envelope (still guarded against interactive prompts).\n- `--dangerously-interact --reason \"\u003Cwhy>\"` — the ONLY override of the prompt\u002Fpermission guard: deliberately drive an interactive prompt\u002Fpermission block (implies `--raw`, requires `--reason`, audit-logged).\n  On a guard-attached managed seat, a non-menu override stops and shows existing typed\u002Fpasted input (author unknown) with `override_input_present`. Input it can't read doesn't stop the override: the answer is typed, nothing is cleared, and the result reports the input as unreadable (never empty) with a warning that the answer may join or submit existing text. Recognized dim suggestions are shown separately and count as empty; a collapsed paste shows only its label, not hidden contents.\n  Inspect the input, deliberately clear the native prompt with native\u002Ftmux controls, then retry. Manual clearing is outside OpenRig's lease and observation checks and is not recorded; human typing can still race a read and paste.\n  When you deliberately need to type without that composer check (for example an unsupported input you inspected yourself), add `--type-without-checking` with `--dangerously-interact --reason \"\u003Cwhy>\"`. It does not clear input and may join or submit existing text. Ordinary sends and wakes keep their current rules.\n- `--host \u003Cid>` — send on a remote host declared in `~\u002F.openrig\u002Fhosts.yaml` (ssh hosts shell out; http hosts go CLI-direct to the remote daemon).\n- `--from \u003Csession>` — deprecated and ignored; it does not select the sender. Sender identity comes from the current seat and transport provenance; cross-host envelopes use the durable local origin, not the supplied flag or a relay identity.\n- `--context \u003Cref>` **(0.5.0)** — attach a composed context pack\u002Fpiece by ref (see \"Context packs and paced delivery\"). Small piece → `send --context`; a real pack → `rig walk`. The noun `rig context` composes the ref; the verb delivers it.\n\n> **Durable work goes to the QUEUE, not `send`.** `rig send` is an *ephemeral* message to a pane — it can be missed, and its delivery status is pane-render, not receipt. If you are **assigning work, or the message is important enough that losing it would be a real bummer**, use `rig queue` (below): it's durable, owned, tracked, and survives compaction and restart. Reach for `send` for a quick conversational nudge; reach for the **queue** for anything that must not get lost. Do not default to `send` for work — that's the most common mistake.\n\nAs of v0.3.3, content beginning with `--` or `-` is safe:\n`rig send \u003Csession> \"content starting with -- or - is now safe\"` delivers\nliterally. The daemon's `send_text` path carries an explicit `--`\nend-of-options sentinel so tmux no longer parses dash-prefixed content\nas its own flags. The CLI surface itself is unchanged. For multi-line\nor large bodies handed off as durable work, use\n`rig queue create --body-file \u003Cpath>` (`-` for stdin) — that's the\nqueue-side surface, not `rig send`.\n\n`--verify` delivery outcomes (v0.3.3+):\n- `delivered` — text + Enter both succeeded and capture re-confirmed the body landed.\n- `rendered-unconfirmed` — text + Enter both succeeded but capture could not re-confirm the body (TUI redraw race or scroll). The message landed; the post-send re-check could not prove it. Treat as landed-but-unconfirmable, NOT failure.\n- `failed` — the send transport itself failed.\n\nThe legacy `Verified: yes\u002Fno` line is preserved verbatim (parser\u002Ftest\ncompatibility). A new `Delivery: \u003Coutcome>` line carries the named outcome\nabove.\n\nObserved operator nuance for `--verify`:\n- `Sent to ...` + `Verified: yes` (`Delivery: delivered`) = strong positive delivery evidence.\n- `Sent to ...` + `Verified: no` + `Delivery: rendered-unconfirmed` = the message landed; capture could not re-prove it. Don't blind-retry — check reply \u002F `rig capture` \u002F transcript before sending again.\n- `Sent to ...` + `Verified: no` + `Delivery: failed` = send-transport failure.\n- no `Sent to ...` line or a hard error = send failure.\n\nWhen you get `Verified: no`, do not immediately retry blindly. First check one of:\n- a direct reply from the target\n- `rig capture \u003Csession>`\n- transcript evidence\n- queue\u002Foutbox state if the message asked for a durable handoff\n\n### Capture terminal output\n\n```bash\nrig capture \u003Csession>\nrig capture \u003Csession> --lines 50\nrig capture --rig \u003Cname>\nrig capture --pod \u003Cname> --rig \u003Cname>\nrig capture --rig \u003Cname> --json\n```\n\n### Broadcast\n\n```bash\nrig broadcast --rig \u003Cname> \"message\"\nrig broadcast --pod \u003Cname> \"message\"\nrig broadcast \"message\"\nrig broadcast --rig \u003Cname> \"message\" --json\n```\n\n**Use `rig broadcast` sparingly — prefer `rig send` fan-out.** Without `--rig` or `--pod`, broadcast targets\n**every running session across ALL rigs** (plus attached external_cli nodes) — the fastest way to cause a\nbroadcast storm. Reserve `rig broadcast` for small rigs or a genuine all-hands emergency. For the normal\n\"message several seats at once\" case, use `rig send`, which scopes the fan-out and keeps the messaging\nenvelope, the delivery\u002Finteractive-prompt guards, and per-recipient results:\n\n```bash\nrig send --to dev-impl@my-rig,dev-qa@my-rig \"message to specific seats\"   # named seats (comma-list or repeat --to)\nrig send --pod dev \"message to one pod\"                                    # scoped fan-out\nrig send --rig my-rig \"message to one rig\"                                 # scoped fan-out\n```\n\n### Chatroom\n\n```bash\nrig chatroom send \u003Crig> \u003Cmessage> [--sender \u003Cname>]\nrig chatroom history \u003Crig> [--topic \u003Cname>] [--after \u003Cid>] [--since \u003Cts>] [--sender \u003Cname>] [--limit \u003Cn>] [--json]\nrig chatroom wait \u003Crig> [--after \u003Cid>] [--topic \u003Cname>] [--sender \u003Cname>] [--timeout \u003Cseconds>] [--json]\nrig chatroom clear \u003Crig>\nrig chatroom topic \u003Crig> \u003Ctopic-name> [--body \u003Ctext>] [--sender \u003Cname>]\nrig chatroom watch \u003Crig> [--tmux]\n```\n\n**Key commands:**\n- `send` — post a message\n- `history` — retrieve with composable filters (sender, since, after, topic)\n- `wait` — block until new matching messages arrive (polls history, times out honestly)\n- `clear` — delete all messages for the rig (destructive, rig-scoped)\n\n## See something, say something\n\nOpenRig has an **observation stream** — the fleet's zero-friction institutional memory, mined for\nreal product improvements. When you notice **anything worth externalizing**, say something and keep\nworking:\n\n- a **bug**, a rough edge, or something that needs fixing\n- a **feature idea** or an improvement\n- something that **worked really well** — a technique, tool, or pattern worth spreading\n- an **observation**, positive or negative feedback, or something genuinely cool, productive, or funny\n\n```bash\nrig stream emit --source \u003Cyour-session> --body \"what you noticed\"\n```\n\nThat's the whole reflex. **Don't** decide where it goes or who it's for — the intake router triages\n(destination\u002Ftype\u002Furgency\u002Ftags are optional hints — `--hint-type review|handoff|idea`,\n`--hint-urgency routine|urgent|critical`, `--hint-tags` — never required). One command, then carry\non; the value is the habit, not the polish. **Don't overdo it, either:** stream real signal, not\nnarration — a good observation beats ten noisy ones. It's a passing thought you externalize, not a chore.\n- `topic` — set a topic marker\n- `watch` — SSE or tmux-based live stream\n\n**Roundtable protocol:**\n1. Inspect old room: `rig chatroom history my-rig --limit 5`\n2. Save if needed: `rig chatroom history my-rig --json > \u002Ftmp\u002Fold-room.json`\n3. Clear if needed: `rig chatroom clear my-rig`\n4. Set topic: `rig chatroom topic my-rig \"ROUND START\"`\n5. Post: `rig chatroom send my-rig \"position...\" --sender \u003Csession>`\n6. Monitor: `rig chatroom wait my-rig --timeout 120`\n7. Close: `rig chatroom topic my-rig \"ROUND CLOSED\"`\n\n### `rig ask`\n\n```bash\nrig ask \u003Crig> \"question\"\nrig ask \u003Crig> \"question\" --json\n```\n\nCurrent shipped behavior:\n- queries the daemon for evidence\n- returns rig summary\n- returns transcript excerpts\n- may return chat excerpts\n- returns insufficiency state and optional guidance\n\nThis is an evidence\u002Fcontext command. It is not a hidden second-LLM call.\n\n### `rig auth` — agent auth-profile management (v0.4.1, product-native)\n\nProduct-native switching of agent auth profiles from the CLI. The runtime is a **flag** (`--runtime \u003Ccodex>`), not a command noun — never `rig codex-auth`.\n\n```bash\nrig auth status --runtime codex          # presence \u002F mode \u002F parseability \u002F login-state (never prints token contents)\nrig auth list --runtime codex            # saved profiles\nrig auth save \u003Cprofile> --runtime codex  # snapshot the auth FILE (mode-guarded), never echoes contents\nrig auth switch \u003Cprofile> --runtime codex\nrig auth validate \u003Cprofile> --runtime codex\nrig auth seats … --runtime codex         # seat -> profile registry (metadata only; NOT proof of a live account)\n```\n\n**Hard secret boundary:** no token value is ever printed, logged, queued, streamed, or committed; status\u002Fvalidate report presence\u002Fmode\u002Flogin-state only; seat labels are metadata, not live-account proof. MVP is `--runtime codex`; other runtimes use the same surface with a different `--runtime`, never a parallel command.\n\n### Give a seat its own Claude or Codex account\n\nA runtime's login lives in its home: Claude Code's in its config dir (`CLAUDE_CONFIG_DIR`, default `~\u002F.claude`), Codex's\nin `CODEX_HOME` (default `~\u002F.codex`). A seat that names its own home in `env:` runs on that home's login.\n\n1. **Prepare the home once, natively,** in a terminal: `CLAUDE_CONFIG_DIR=\u002Fabs\u002Fpath claude`, then `\u002Flogin`; or\n   `CODEX_HOME=\u002Fabs\u002Fpath codex login`. The person signs in; never copy credential files between homes.\n2. **Name it in the member's `env:`** in `rig.yaml`, not with `rig up --env`, which leaves these two out\n   (`CLAUDE_CONFIG_DIR: \u002Fabs\u002Fpath` or `CODEX_HOME: \u002Fabs\u002Fpath`), or in\n   the rig's `env:` for every seat of that runtime. The member's value wins. It must be an absolute path: any other\n   value is reported and ignored, and the seat keeps the daemon's home.\n3. **It takes effect at the seat's next launch** (a fresh launch, restore or handover); a running seat keeps the home\n   it started with. A conversation saved under the old home doesn't resume from the new one.\n4. **Check it:** `rig seat status \u003Cseat>` shows the home and where it came from, and `rig provider status` lists it as\n   the seat's configured account. Both say what's configured, not which login a running session holds.\n\nSeats may share a home. OpenRig writes its own settings (Codex hooks, managed `config.toml` and plugin; Claude's\nfirst-run trust settings) into the seat's home.\n\n### Move one Codex seat to another login\n\nFor a Codex seat on Linux. The login must already be saved in the Codex home the seat runs on (`rig seat status \u003Cseat>`\nshows it). Other operating systems, and moving a seat to another home, aren't supported by this command yet: say so instead\nof improvising. A Claude seat moves differently; see the next section.\n\n1. **Save each login once, in that home:** `CODEX_HOME=\u003Chome> codex login` (the person signs in), then\n   `CODEX_HOME=\u003Chome> rig auth save \u003Cname>`. `rig auth list --codex-home \u003Chome>` lists them.\n2. **Check:** `rig provider precheck --seat \u003Cseat> --to-account \u003Cname>` shows the home, what the seat is doing, and every\n   peer on that home. A refusal says what's missing, and nothing changes.\n3. **Move:** `rig provider switch --seat \u003Cseat> --to-account \u003Cname>`. It saves the home's current login as\n   `before-switch-\u003Ctime>`, activates the chosen one, and restarts the seat in place on the same conversation. If the\n   current login can't be saved first, nothing changes. Peers on the home aren't restarted. Each keeps its current login\n   only until its next token refresh, when Codex stops it with \"signed in to another account\". Run the printed\n   `rig seat restart \u003Cpeer> --keep-conversation --reason \"...\"` for each to move it too. Don't sign in again in that home: that replaces\n   the login you just switched to.\n4. **Confirm:** after the seat completes a real tool-using turn, run the printed\n   `rig seat restart \u003Cseat> --keep-conversation --verify --expect-account \u003Cits Account line>`. Until then the move is\n   unconfirmed. An uncertain restart is reported; never restart it a second time.\n\n### Move one Claude seat to its own subscription token\n\nThe seat keeps its config dir and gets its own `CLAUDE_CODE_OAUTH_TOKEN`, read from a file as Claude starts. OpenRig keeps only\nthe file's path and your label, never the token.\n\n1. **Prepare the token once:** the person runs `claude setup-token`, which prints a one-year subscription token, and saves it to a\n   file only their user can read (`chmod 600`). Never paste the token into a message, a row or a command line.\n2. **Check:** `rig provider precheck --seat \u003Cseat> --to-account \u003Clabel> --token-file \u003Cabsolute path>`. It refuses, changing\n   nothing, if the file wouldn't apply, the seat isn't running, or something Claude Code ranks above the token is set (a cloud\n   provider, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, an `apiKeyHelper`). It names each one and how to remove it for that\n   seat. When the token applies, the launch unsets those names for Claude's process, so the pane shell's own exports can't\n   outrank it. Managed settings can't be read; the seat's `\u002Fstatus` shows what it actually uses.\n3. **Move:** `rig provider switch --seat \u003Cseat> --to-account \u003Clabel> --token-file \u003Cabsolute path>`. It takes a snapshot that\n   resumes the seat's conversation, sets the reference, and relaunches the seat from that snapshot in its own pane: the pane\n   and its scrollback stay, but work in flight when Claude ended doesn't carry over. Seats sharing the config dir keep their\n   own login. `--stored-login` moves the seat back; if the seat still receives a `CLAUDE_CODE_OAUTH_TOKEN`, Claude uses that\n   instead of the stored login, and the report names it.\n4. **Confirm:** after the seat completes a real tool-using turn, its `\u002Fstatus` shows token auth, with no account email. The\n   label is yours, not an account Claude observed: say so. A token session can't use claude.ai connectors or Remote Control.\n   The token is in Claude's environment, so the tools, hooks and MCP servers it starts inherit it; don't have it print its\n   environment. A relaunch that didn't resume reads unknown, with its recovery command; never run the switch again for it.\n   `rig seat status \u003Cseat>` shows the reference, and says when its file won't apply at the next launch.\n\n### Manage subscriptions across a fleet (when the person asks you to)\n\n**This applies only when the person has asked you to manage their subscriptions.** Otherwise, don't take this job on. Installing or upgrading OpenRig appoints no agent, launches no bundle and starts no\nrotation.\n\nWhen a person runs several Claude and Codex subscriptions across machines, the fleet studio bundle's one agent is meant\nto keep work running, through the Fleet app. Until that bundle is available, the agent the person asks to manage their\nsubscriptions can use this section. If that's you, you decide which subscription or home moves, and when. You decide\nfrom:\n- the usage and assignment readings, and their freshness;\n- your earlier move reports (`rig provider moves`);\n- the person's account policy, or their standing preferences when there's no policy.\n\nYou say why, and you see the outcome through. OpenRig gives you the facts and the tools; it never decides for you,\nand there's no threshold to obey.\n\n**Who decides:**\n- **The person's operator agent** can ask you for a move, or ask what you've moved. It doesn't make competing moves of\n  its own.\n- **One agent manages subscriptions:** the one the person asked, or the fleet studio's agent once that bundle is\n  available. There's no other fleet-manager role and no automatic manager. Use the commands below directly; no extra\n  hand-off is needed.\n- **The Observatory is optional:** it can show readings, but you don't need it to rotate.\n\n**The unit is a Codex home, with every seat on it.** Moving some seats on a shared home to a different account, and\nmoving Claude seats, aren't supported moves yet: say so instead of improvising. A Codex seat with a home of its own\nmoves alone, with `rig provider switch --seat` (above).\n\n0. **Load the person's account policy.**\n   - It's the context pack named `account-policy`: check `rig context list` for it, then read it with\n     `rig context get account-policy`. Its manifest's `version` is the version you follow and report.\n   - Follow it, and record the version in each report. A line the person approved (\"move the build box's seats without\n     asking\", \"never move the reviewers\") is standing authorization: act on it, don't ask again.\n   - A line grants only what the person actually gave. \"Agents may do sign-ins\" is usable only where a sign-in route\n     and access already exist; otherwise ask, and record that the preference couldn't be used.\n   - Something the policy doesn't cover: use your judgment or ask the way the policy says, record why, and propose a\n     one-line addition.\n   - **No policy** is never a reason to stop: work from this section, report the policy as `{ \"none\": true }`, and\n     offer once to write one with them (below).\n1. **Know the subscriptions.**\n   - Each subscription is reached through a saved profile on a home (`rig auth list` and `rig auth save`) on each\n     machine. Which seats use which profile is `rig auth seats`, and that's metadata: not proof of a live account.\n   - Check you can read each subscription's usage, and name any you can't.\n2. **Read before deciding.**\n   - Use `rig provider status --all-hosts --json` (add `--refresh` for fresh native readings). Each allowance has\n     its windows, reset times and when it was observed, and when it was last observed exhausted.\n   - **One allowance seen on two machines is one allowance:** never add its headroom twice.\n   - **A stale reading** is usable only with its age recorded, or after a refresh.\n   - **An unknown or unavailable reading is never observed room.**\n   - **After a known reset,** a window carries an `expectation` (expected full since that reset). You may plan on it,\n     but it isn't measured: report it as expected, and take a fresh reading when you can.\n   - **Equal reset times don't mean the same account.**\n   - **A seat's link to a subscription is observed, configured or unknown.** Only an observed link shows the seat\n     actually uses it; a configured one (a profile, a registry row) is a claim.\n   - **A sign-in state of `unknown` isn't `needs_sign_in`.** An otherwise authorized move can go ahead, and its uptake\n     evidence settles it. A known `needs_sign_in` is step 6.\n3. **Decide, and leave seats alone for a reason.**\n   - **Balance, don't chase:** spread machines across the subscriptions with room rather than moving every machine onto\n     the one that just reset. `rig usage top` on each machine shows which work hardest: a high-use machine is worth a\n     subscription of its own, and lower-use machines can share one. Keep a backup where the policy says so.\n   - `rig seat restart \u003Cseat> --keep-conversation --plan` shows what a restart keeps, and every peer on the same\n     home. Moving the home moves them all.\n   - Skip a seat that's mid-turn, running a service, or about to finish, and record why.\n4. **Move the home.**\n   - `rig auth switch \u003Cprofile> --runtime codex --codex-home \u003Cthat home>`, on that machine, or from here with\n     `--host \u003Cthat machine's SSH entry>`. Without `--codex-home`, `rig auth` acts on `CODEX_HOME`, or on the default\n     home; `rig auth status --codex-home \u003Chome>` (with `--host` for another machine) prints which home it means:\n     check it before switching. A remote switch always names its home, and copies a profile already saved there.\n   - **Another machine** is reached through its SSH entry in `rig host list`. An entry registered only over HTTP\n     can't run these commands; use the machine's SSH entry, or run them on that machine.\n   - Then restart each chosen seat: `rig seat restart \u003Cseat> --keep-conversation --reason \"\u003Cwhy>\"`, with `--host \u003Cid>`\n     for a seat on another machine (the restart runs there, and its audit names you). If the connection drops, the\n     answer is `remote-outcome-unknown`: the switch or restart may have run there, so read what it names (for a\n     restart, `--plan`'s `lastRestart`) before anything else.\n   - After it completes a real tool-using turn, check it: `rig seat restart \u003Cseat> --keep-conversation --verify\n     --expect-account \u003Cthe target's Account line>`. `--verify` only checks; it never restarts. Only that check\n     reports `moved`, and anything less is unconfirmed.\n   - **A slow reply isn't a failure:** never restart a seat a second time. Follow up at your next look.\n5. **Report every move, partial or unconfirmed included,** with\n   `rig provider moves report --file \u003Cmove.json> --to \u003Cwhoever asked>` (`--help` shows the shape). It becomes a queue\n   item to them; the Fleet app reads these reports once its page is connected to them. It holds:\n   - the home and machine, and from and to, as labels;\n   - your reason, and the policy version you followed (or `{ \"none\": true }`);\n   - each reading you acted on, `observed` with its observation time, `expected` with the reset it rests on, or\n     `unavailable`;\n   - each seat's result: `moved` only with the verify check's matched account and observed tool turn, kept as separate\n     facts; otherwise `unconfirmed` or `unknown`, with what's missing;\n   - the peers, for example \"not restarted; account unverified\".\n\n   A home switched with every seat left as a peer is still a move to report. A follow-up that confirms an earlier\n   unconfirmed seat is a new report with `--follows \u003Cthe earlier report's qitemId>`. A report to a person's seat names\n   its evidence with `--evidence-ref` (for example, the saved `--verify --json` output). Never put credentials in a\n   report: a value in a recognized credential format is refused. **A refused report changes nothing about the move:**\n   correct it and file it again; never repeat the switch or a restart because a report was refused. Asked \"why did\n   these seats move?\", even after your own restart, answer from `rig provider moves --seat \u003Cseat>`. It reads the newest\n   reports (50 by default, `--limit` up to 200) and then filters them, so it's a recent window, not a seat's whole\n   history: raise `--limit` when you need older ones.\n6. **When a sign-in is needed:**\n   - Ask the person once, durably: a queue item to their seat, naming the machine and the subscription.\n   - Move nothing onto that subscription until it's done.\n   - On later wakes, check that item instead of asking again. Carry on with everything else.\n7. **When nothing has room:** say so, with the reset times. Never fall back to an API key, buy anything, or create an\n   account.\n\n**What wakes you:** a watchdog, a usage-limit park on the queue, or the person asking. How often you look is your\njudgment within those.\n\n**If there's no policy yet.** Start from what you can see, and ask only what you can't; keep it to a few minutes, and\nnever run it as a form. \"Whatever you think\" or \"skip\" is an answer: write down the default you'll use.\n1. **Look first:** `rig auth list` and `rig auth seats` on each machine you can reach, `rig provider status\n   --all-hosts --json`, and `rig usage top` on each machine. Draft what you can.\n2. **Confirm what you saw,** in one message (\"three Codex subscriptions and one Claude one, on two machines; the build\n   box uses about four times the tokens of the laptop; any I can't see?\").\n3. **Ask how they want them used,** offering the common shape: the busiest machine gets its own subscription, the\n   rest share, and one stays spare.\n4. **Ask what you may do on your own:** move a machine's Codex seats without asking; machines or seats to ask about\n   first or never move; sign-ins (may agents, and through which browser or profile, or always ask). Say what's\n   supported today: moves are by Codex home, Claude moves aren't supported yet, and a sign-in preference is used only\n   where a sign-in route and access exist.\n5. **Ask how to reach them** (their seat's queue, a chat channel, the Fleet app), for what, and what to do when they\n   don't answer. A channel they name is a preference: check the route with `messaging-the-human`, and use a queue\n   item to their seat if it isn't ready.\n6. **Ask what to do when things go wrong:** nothing has room, a sign-in is needed while they're away, a move didn't\n   confirm.\n7. **Show the draft in plain words,** let them correct it, and save it as a context pack named `account-policy` in\n   the context library where you run (`rig config get context.root`): a folder with `manifest.yaml` (`version: \"1\"`,\n   `name: account-policy`, `taxonomy: world`, a `purpose`, and `files: [{ path: POLICY.md, role: policy }]`) and\n   `POLICY.md`, installed with `rig context add \u003Cfolder>` and read back with `rig context get account-policy`. To share\n   one policy across machines, use a Git repository: `rig context add \u003Crepo> --git`. Labels and references only:\n   never tokens, passwords, cookies or recovery codes.\n\n   `POLICY.md` has these parts, in their words: subscriptions (label, provider, plan, how each is reached); how they\n   want them used; what agents may do on their own; how to reach them; when things go wrong; and a dated **Changes**\n   list. Fill it from what you saw and what they said, never from another person's setup.\n\n**Changing the policy.** When they say what changed, copy `POLICY.md` aside as the before copy, edit it, add a dated\nline under **Changes**, and raise `version` in `manifest.yaml`. Keep one place where it's edited: edited where it's\ninstalled, run `rig context sync`; kept in a separate folder, replace it with `rig context rm account-policy` and\n`rig context add \u003Cfolder>`; Git-backed, edit and commit in the checkout `rig context source inspect account-policy`\nreports, then `rig context source update account-policy` (it never pushes). Read it back with\n`rig context get account-policy`; your next decision follows the new version.\n\n## Context packs and paced delivery (0.5.0)\n\n**Compose context once, hand it to a seat cleanly.** A library primitive plus a set of delivery flags. The rule that keeps the grammar coherent — internalize this one: **the noun stores and composes; the verbs deliver.** `rig context` never sends anything; delivery is only ever `rig send` \u002F `rig broadcast` \u002F `rig walk` \u002F `rig queue`.\n\n> Version note: this describes the library surface introduced in 0.5.0. Check the installed command and serving daemon before relying on it. In 0.4.x, bare `rig context` was a context-window usage viewer (above); in 0.5.0 that viewer is removed and the `rig context` name belongs to the library here.\n\n### `rig context` — the store + compose library (never delivers)\n\nManage and compose context (any text\u002Fmarkdown) into reusable **packs**. Every piece and pack has a stable, **path-like ref** — you address context the way you address files (`skills\u002Fclaude-compaction-restore`, `reference\u002Frig-spec.md`).\n\n```bash\nrig context list                     # what's in the library\nrig context show \u003Cref>               # read a piece or pack\nrig context add \u003Csource-dir>         # install an existing pack directory into the store\nrig context preview \u003Cref>            # assemble + show a pack WITHOUT delivering it\nrig context sync                     # re-walk discovery roots, refresh the library index\nrig context rm \u003Cref>\nrig context compose --out packs\u002F\u003Cref> --from \u003CfileA> \u003CfileB> ...   # ordered pieces -> a durable pack\n```\n\n- Sensible default store location; works unconfigured, can be pointed elsewhere later (another folder now; a machine or URL later).\n- `compose` (v1) is honest ordered concatenation of named files into a durable pack with a ref — \"here's a file, read a file.\"\n- **No delivery verb lives on the noun.** To get a pack to a seat, hand its ref to a delivery verb below.\n\n### `rig walk` — paced delivery of a sequence\n\n```bash\nrig walk \u003Cseat> --through \u003Cref | file ...> --pace 10s\n```\n\nWalk a seat *through* a pack: each piece is sent into the pane, spaced by `--pace`, so the agent processes between sends (the human paste → wait → paste rhythm). Its own top-level verb, push-direction — the walker leads and does not wait for replies; the spacing does the work. Reach for `walk` on onboarding, repriming, or a fleet update — anything absorbed in order rather than all at once.\n\n### The delivery grammar — send a ref, walk a pack, or attach it to a qitem\n\n| When | Verb |\n|---|---|\n| One thing, now | `rig send \u003Cseat> --context \u003Cref>` |\n| One thing, everyone | `rig broadcast --rig \u003Crig> --context \u003Cref>` |\n| A sequence, absorbed | `rig walk \u003Cseat> --through \u003Cref> --pace 10s` |\n| Context riding a durable handoff | `rig queue create … --body-context \u003Cref>` |\n\n- **Rule of thumb:** small piece → `send --context`; real pack → `walk`. An oversized `send --context` warns \"this is walk-sized\" instead of blasting the pane.\n- **`--body-context` snapshot rule:** a qitem built from a ref stores the **resolved content** in its body **plus the ref for provenance** — the handoff carries what was actually sent, and a later library edit never silently rewrites a past handoff's history.\n- **The orchestrator habit — assign work *with* its context attached:**\n  ```bash\n  rig context compose --out packs\u002Fqitem-brief --from \u003Cbrief-file> \u003Cproof-file>\n  rig queue create --destination dev-driver@build --body-context packs\u002Fqitem-brief \\\n    --summary \"…\" --tags \"project:\u003Cid>,mission:\u003Cid>,slice:\u003Cid>\"\n  ```\n  Replace `\u003Cbrief-file>` and `\u003Cproof-file>` with your existing local files. The curated context rides the durable handoff, survives compaction, and is auditable.\n\n**Skills tier vs context tier:** skills are the HOT tier (ambient, finite, always-visible front-matter); context packs are the COLD tier (unbounded, fetched on instruction — \"read `rig context get onboarding-width`\"). Don't overrun the skill layer by using skills as context packs — that's what this primitive is for.\n\n## Lifecycle\n\n### Bring a rig up\n\n```bash\nrig up \u003Csource>\nrig up \u003Csource> --plan\nrig up \u003Csource> --yes\nrig up \u003Csource> --cwd \u002Fpath\u002Fto\u002Fproject\nrig up \u003Csource> --existing\nrig up \u003Csource> --fresh \u003Cseat...>\nrig up \u003Csource> --json\n```\n\n`\u003Csource>` can be:\n- a rig spec path\n- a `.rigbundle` path\n- a bare name\n\nBare names are special:\n- if they match a library spec, `rig up` launches from the spec library\n- if they do not match a library spec, `rig up` treats the name as an existing-rig restore\u002Fpower-on target\n- if both exist, `rig up` fails loudly on ambiguity\n\nResume-original-by-default (v0.3.4+):\n- For an existing rig, `rig up \u003Cname>` resumes each seat from its original session\u002Fsnapshot by default (operation A). Seats that successfully resume report `resumed`.\n- `--fresh \u003Cseat...>` is the per-seat opt-in for deliberate fresh-prime (operation B). Named seats are reported as `fresh-primed`.\n- `--existing` forces existing-rig restore semantics on a bare name, bypassing library-spec resolution. Useful when a rig name collides with a library spec name.\n- Example: `rig up --existing my-rig --fresh dev-impl` — resume everything in `my-rig` except `dev-impl`, which is freshly primed.\n- Seats with no resumable session land in `awaiting-decision` (zero-session honest state, NOT `failed`); see the five-term restore vocabulary in \"Recovery and Resilience\" below.\n\n`--plan` (v0.3.4+):\n- `rig up \u003Csource> --plan` produces a read-only restore plan preview. It surfaces per-seat resume\u002Ffresh-prime intent and any awaiting-decision seats without mutating state. Honest async timeout: a stuck plan reports the timeout rather than hanging silently.\n\nCurrent behavior notes:\n- `--target \u003Croot>` is only for `.rigbundle` \u002F package installation. It does not change agent cwd.\n- `rig up --cwd` is shipped. `rig up --cwd \u003Cpath>` sends a per-run cwd override for all members in that launch.\n- `local:` `agent_ref` values resolve relative to the rig spec directory, not your shell cwd.\n- if you copy a built-in spec elsewhere, keep its `agents\u002F` tree beside the YAML or rewrite those refs to `path:\u002Fabsolute\u002Fpath`\n- `rig specs add \u003Cdirectory>` installs a full spec tree when the directory contains `rig.yaml` or `agent.yaml`.\n- **Permission policy:** a rig carries a permission policy and boots with it (never changed on the fly). Default if none set = the minimum floor (Claude `acceptEdits` \u002F Codex workspace-only \u002F Pi `--no-approve`); otherwise a chosen built-in (Locked \u002F Standard \u002F Open) or deliberately none. When you spec or bring up a rig, decide its policy — apply it via `applying-a-permission-policy` (see also the onboarding menu, \"Permission policy — pick one at setup\").\n\nLegacy\u002Fspec-specific surfaces still ship too:\n\n```bash\nrig bootstrap \u003Cspec> [--plan] [--yes] [--json]\nrig requirements \u003Cspec> [--json]\n```\n\n### Tear a rig down\n\n```bash\nrig down \u003Crig>            # \u003Crig> = rig name or id (active rig)\nrig down \u003Crig> --snapshot\nrig down \u003Crig> --delete\nrig down \u003Crig> --force\nrig down \u003Crig> --json\n```\n\nIf `--snapshot` succeeds, human output includes the restore hint.\n\n### Archive a stopped rig (recoverable) — v0.3.3+\n\n```bash\nrig archive \u003Crig> [--json]\nrig unarchive \u003Crig> [--json]\n```\n\n`rig archive` marks a stopped rig as archived (sets `archivedAt`) without\ndiscarding it. The rig is preserved for later restoration via `rig unarchive`,\nwhich clears `archivedAt` and returns the rig to the active set.\n\nArchive vs delete:\n- `rig down --delete` — permanent removal; not recoverable.\n- `rig archive` — recoverable; the rig is hidden from the default active view but its record + snapshots are preserved.\n\nVisibility in `rig ps`:\n- `rig ps` — active rigs only (default).\n- `rig ps --include-archived` — includes archived rigs, marked with `*`.\n\nSSE events `rig.archived` \u002F `rig.unarchived` drive Project \u002F dashboard updates;\nconsumers that depend on the rig list should subscribe rather than poll.\n\n### Environment services\n\n```bash\nrig env status \u003Crig>\nrig env logs \u003Crig> [service]\nrig env down \u003Crig>\n```\n\nUse these for service-backed rigs and agent-managed apps.\nFor `secrets-manager`, these are the fastest CLI surfaces for:\n- confirming whether Vault is healthy\n- reading Vault container logs\n- stopping the Vault env without tearing down the specialist session first\n\n### Release management without killing live claimed sessions\n\n```bash\nrig release \u003CrigId>\nrig release \u003CrigId> --delete\nrig release \u003CrigId> --json\n```\n\nUse `rig release` for adopted\u002Fclaimed-session rigs when you want OpenRig to stop managing the rig but leave the tmux sessions alive.\nThis is the safe recovery\u002Freset surface for the \"sessions still exist, management is broken or stale\" case.\nIf the rig contains OpenRig-launched nodes, `rig release` refuses loudly instead of pretending the mixed rig is safe to detach.\n\n### Snapshots and restore\n\n```bash\nrig snapshot \u003CrigId>\nrig snapshot list \u003CrigId>\nrig restore \u003CsnapshotId> --rig \u003CrigId>\n```\n\n`rig restore` requires `--rig \u003CrigId>`.\n\nClaude Code autonomy note:\n- unattended `rig whoami` on boot may require the local permission allow list to include `Bash(rig:*)`\n\n### Import\u002Fexport and bundles\n\n```bash\nrig export \u003CrigId> -o rig.yaml\nrig import \u003Cpath> [--instantiate] [--materialize-only] [--preflight] [--target-rig \u003CrigId>] [--rig-root \u003Croot>]\nrig bundle create \u003Cspec> -o out.rigbundle\nrig bundle inspect \u003Cbundle>\nrig bundle install \u003Cbundle> [--plan] [--yes] [--target \u003Croot>] [--json]\n```\n\n### Legacy package surface\n\nThis still ships, but is explicitly marked legacy:\n\n```bash\nrig package validate \u003Cpath>\nrig package plan \u003Cpath> [--target \u003Cdir>] [--runtime \u003Cruntime>] [--role \u003Cname>]\nrig package install \u003Cpath> [--target \u003Cdir>] [--runtime \u003Cruntime>] [--role \u003Cname>] [--allow-merge]\nrig package list\nrig package rollback \u003CinstallId>\n```\n\n## Discovery and Topology Mutation\n\n### Discover unmanaged tmux sessions\n\n```bash\nrig discover\nrig discover --json\nrig discover --draft\n```\n\n### Bind a discovered session\n\n```bash\nrig bind \u003CdiscoveredId> --rig \u003CrigId> --node \u003ClogicalId>\nrig bind \u003CdiscoveredId> --rig \u003CrigId> --pod \u003Cnamespace> --member \u003Cname>\n```\n\nThere is no shipped top-level `rig claim` command.\nThe current adoption surface is `discover`, `bind`, `adopt`, and `unclaim`.\n\n### Self-attach the current shell or agent\n\n```bash\nrig attach --self --rig \u003CrigId> --node \u003ClogicalId>\nrig attach --self --rig \u003CrigId> --node \u003ClogicalId> --print-env\nrig attach --self --rig \u003CrigId> --pod \u003Cnamespace> --member \u003Cname> --runtime \u003Cruntime>\n```\n\nUse `rig attach --self` when the current agent should attach itself directly instead of going through `discover` + `bind`.\n\nCurrent proven behavior:\n- inside `tmux`: attaches as a normal tmux-backed node, preserving inbound `rig send` \u002F `rig capture`\n- outside `tmux`: attaches as `external_cli`\n- `--print-env` prints the `OPENRIG_NODE_ID` and `OPENRIG_SESSION_NAME` exports for the current shell\n\nRecommended flow:\n\n```bash\nrig attach --self --rig \u003CrigId> --node \u003ClogicalId> --print-env > \u002Ftmp\u002Fopenrig-self-attach.env\n. \u002Ftmp\u002Fopenrig-self-attach.env\nrig whoami --json\n```\n\nNotes:\n- for tmux-backed self-attach, `rig whoami --json` is the right verification\n- for raw\u002Fexternal self-attach, `rig ps --nodes --json` is currently the more reliable verification surface\n- if the current shell is outside tmux, pass `--display-name \u003Cname>` when you want a stable human session label recorded\n- to read a seat's identity or state later, use `rig whoami` or `rig seat status`, not `rig attach --json` output or a file holding a\n  seat's environment. Don't print `OPENRIG_ACTIVITY_*` values: the activity token is a credential, and it doesn't identify the seat\n\n### Adopt a topology and bind live sessions\n\n```bash\nrig adopt \u003Cpath> --bind \u003ClogicalId=tmuxSessionOrDiscoveryId>\nrig adopt \u003Cpath> --bind \u003ClogicalId=...> --bind \u003ClogicalId=...> --json\nrig adopt \u003Cpath> --bindings-file \u003Cbindings.yaml>\nrig adopt \u003Cpath> --bind \u003ClogicalId=...> --target-rig \u003CrigId> --rig-root \u003Croot>\n```\n\nUse `rig adopt` when the sessions already exist and you want OpenRig to start managing them.\n\nA bindings file is the durable map from authored logical IDs to live sessions. Shape:\n\n```yaml\nbindings:\n  dev1.impl2: dev1.impl2@rigged-buildout\n  dev1.qa: dev1.qa@rigged-buildout\n```\n\nSpec + bindings is the proven recovery pair for adopted rigs.\nSpec gives OpenRig the intended topology. Bindings tells OpenRig which discovered live session belongs in each logical node.\n\n### Proven adopted-rig recovery workflow\n\nThis workflow is proven for the case where the external tmux sessions are still alive:\n\n```bash\nrig release \u003CrigId> --delete\nrig discover --json\nrig adopt \u003Cspec.yaml> --bindings-file \u003Cbindings.yaml>\n```\n\nWhat this does:\n- removes OpenRig management without killing the sessions\n- re-discovers those same sessions as unmanaged\n- re-attaches them to the topology defined by the spec + bindings\n\nImportant limits:\n- this is for `sessions still alive`\n- spec alone is not enough for adopted rigs; you also need bindings\n- this does not yet mean OpenRig can recreate dead external sessions from nothing\n\n### Add unmanaged pods into an existing rig\n\nThis is the proven workflow when a rig is already managed, but a new pod was created outside OpenRig and you want to add it later:\n\n```bash\nrig adopt \u003Cpod-fragment.yaml> --bindings-file \u003Cpod.bindings.yaml> --target-rig \u003CrigId>\n```\n\nUse this when:\n- the target rig already exists\n- the new sessions are live and visible in `rig discover --json`\n- you want additive topology growth, not a full rebuild\n\nWhat to prepare:\n- a pod fragment spec with only the new pod\n- a bindings file mapping the new logical IDs to the live session names\n\nVerification loop:\n\n```bash\nrig discover --json\nrig adopt \u003Cfragment.yaml> --bindings-file \u003Cbindings.yaml> --target-rig \u003CrigId>\nrig ps --nodes --rig \u003CrigId>   # the target rig's nodes (--nodes alone = your current rig)\nrig export \u003CrigId> -o rig.yaml\n```\n\nSuccess looks like:\n- the new sessions stop appearing in `rig discover`\n- the new logical IDs appear in `rig ps --nodes --rig \u003CrigId>`\n- `rig export` includes the new pod\n\n### Mixed-origin rigs are allowed\n\nOne rig can contain both:\n- adopted nodes bound from already-running sessions\n- OpenRig-launched nodes created later with `rig expand` \u002F `rig launch`\n\nCurrent safety rule:\n- `rig release` is for claimed\u002Fadopted-only rigs\n- if a rig contains launched nodes, `rig release` fails with `contains_launched_nodes`\n\n### Manager-assisted recovery\n\nThe proven operator pattern is:\n- keep one OpenRig manager session outside the rig it manages\n- address the target by rig name, not cached rig ID\n- find the target rig with bare `rig ps` (lists all rigs), then resolve its owner from `rig ps --nodes --rig \u003Ctarget>` (a bare `--nodes` read is your current rig only, not the target's)\n- send the manager the spec path, bindings path, and verification steps with `rig send`\n\nThis lets ordinary agents ask the manager for OpenRig help instead of every agent needing to be an OpenRig expert.\n\n### Add\u002Fremove running topology parts\n\n```bash\nrig grow \u003Crig-id> \u003Cmember...> [--pod \u003Cpod> | --new-pod \u003Cpod>] [--runtime \u003Cruntime>] [--cwd \u003Cpath>] [--json]\nrig expand \u003Crig-id> \u003Cpod-fragment-path> [--rig-root \u003Cpath>] [--json]\nrig launch \u003Crig> \u003CnodeRef> [--json]\nrig launch \u003Crig> --seats \u003Ca,b,c> [--hold-reason \u003Ctext>] [--json]\nrig remove \u003CrigId> \u003CnodeRef> [--json]\nrig shrink \u003CrigId> \u003CpodRef> [--json]\nrig unclaim \u003CsessionRef> [--json]\n```\n\n`rig grow` is the simplest way to add seats: no YAML, the default agent spec, and one\nruntime and working directory for the named seats (`--new-pod` creates a pod for them).\nCheck `rig grow --help` on your installed version. Use a fragment with `rig expand` (a pod)\nor `rig add` (one member) when a seat needs an explicit model, a permission policy, a\ndifferent agent spec or role profile, per-seat runtime or cwd, or startup files.\n\nNode-granular managed partial restore (v0.3.4+):\n- `rig launch \u003Crig> \u003CnodeRef>` launches a single seat that isn't running, by logical id or node id, through orchestration.\n  `\u003Crig>` is the rig's name or ID; a name shared by more than one active rig stops with the candidate IDs. A seat that's\n  already running is left as it is; for a fresh occupant there, use `rig seat launch \u003Cseat> --fresh --stop --reason \u003Cwhy>`.\n- `rig launch \u003Crig> --seats \u003Ca,b,c>` launches a comma-separated subset of seats.\n- `--hold-reason \u003Ctext>` records a reason for holding non-target seats during the partial launch.\n- This is a SUPPORTED managed path. The prior `pod_aware_launch_unsupported` dead-end is retired; pod-aware narrow launch now goes through this surface rather than ad-hoc rebuilds.\n\n### Add a member to an existing pod — v0.3.3+\n\n```bash\nrig add \u003Crig> \u003Cpod-namespace> \u003Cmember-fragment-path> [--json]\n```\n\n`rig add` is the top-level verb for the `add_member` converge op. It adds a\nsingle member to an existing pod from a YAML\u002FJSON member fragment file. The\ndaemon resolves the named pod, validates the member, runs preflight, and\nlaunches the member in place.\n\n`\u003Crig>` is the rig id or its exact name (the `rigName` that `rig whoami --json`\nreports). A name shared by more than one rig is refused before anything is\nadded, with the matching ids listed (`rig_ambiguous` under `--json`). `rig add`\nalways targets the local daemon: while a remote host is selected it refuses to\nresolve a name (`remote_host_selected`); an exact local id still works.\n\nHTTP outcomes:\n- `201` — member added; per-node launch state included in the response.\n- `400` — `validation_failed` or `preflight_failed` (the fragment or its launch posture is rejected before any state change).\n- `409` — `member_conflict` (a member with that identity already exists in the pod).\n\nUse `rig add` when you want additive growth inside a pod without re-running\nthe full `rig expand` pod-fragment path or rebuilding the rig.\n\n## Specs and Validation\n\n### Validate specs\n\n```bash\nrig spec validate \u003Cpath> [--json]\nrig spec preflight \u003Cpath> [--rig-root \u003Croot>] [--json]\nrig agent validate \u003Cpath> [--json]\n```\n\n### Spec library\n\n```bash\nrig specs ls [--kind \u003Ckind>] [--json]\nrig specs show \u003Cname-or-id> [--json]\nrig specs preview \u003Cname-or-id> [--json]\nrig specs add \u003Cyaml-or-directory> [--json]\nrig specs sync [--json]\nrig specs remove \u003Cname-or-id> [--json]\nrig specs rename \u003Cname-or-id> \u003Cnew-name> [--json]\n```\n\n## MCP\n\n```bash\nrig mcp serve [--port \u003Cdaemon-port>]        # stdio: a local app starts the server itself\nrig mcp serve --http [--bind \u003Chost:port>]   # Streamable HTTP at \u002Fmcp (default 127.0.0.1:7437)\nrig mcp token add \u003Cname> --seat \u003Csession> [--rig \u003Cname>...] [--root \u003Cname>...] [--workspace] [--owner]\nrig mcp token list [--json]\nrig mcp token revoke \u003Cname>\n```\n\nThe 39 shipped tools fall into four groups. Over stdio, and over HTTP with no grants, every tool but the person tools is\noffered. An HTTP grant offers the work tools; the workspace tools with `--workspace` or `--owner`; and the owner tools only\nwith `--owner`, which offers every tool but the person tools. Only a grant service's grant that names its person offers\nthe person tools.\n- **Work (20):** orientation, communication and the durable work loop.\n  - `rig_whoami`: the seat the server acts as (rig, pod, peers, edges) and the `caller`: authenticated (an HTTP\n    credential, with its principal) or declared (`OPENRIG_SESSION_NAME` where the server was configured, which nothing\n    verifies).\n  - `rig_status`, `rig_ps`, `rig_rig_nodes`, and `rig_team`: a rig's lead (its one `delegates_to` root, the seat to\n    delegate to) and each seat's role, delegation and activity.\n  - `rig_send`, `rig_capture`, `rig_chatroom_send`, `rig_chatroom_watch`.\n  - `rig_queue_create`, `rig_queue_show`, `rig_queue_list`, `rig_queue_claim`, `rig_queue_update`,\n    `rig_queue_handoff`, `rig_queue_unclaim`:\n    - `revises` on create asks for a linked revision of an earlier item;\n    - show names a handed-off item's successor;\n    - `handedOffFrom` on list follows a handoff;\n    - handoff passes an item this seat holds on to the next seat in one step, as `rig queue handoff` does: the new item\n      carries the work's lineage;\n    - unclaim puts back a claimed item this seat won't finish.\n  - `rig_artifact_read`: a finished item's artifact (its `evidenceRef`) or a named file, through the daemon's shared\n    roots (`OPENRIG_FILES_ALLOWLIST`), in windows (`offset`, `nextOffset`). Outside those roots it answers unavailable\n    rather than reading a local path.\n  - `rig_environment_export`: copies a bound worker's JSON artifact to the host, checks its bytes, schema and context, and\n    adds a receipt to its existing work. It doesn't close the work, stop compute or restore native history, and it needs\n    an authenticated HTTP work connection.\n  - `rig_human_decision_room`, then `rig_queue_decide`: on your own pending ask to a person, read the decision room of\n    the mode they have on, and record a decision you made for them inside it. Only the person tools record a person's own\n    answer, and only for the person a grant names.\n- **Workspace (4):** `rig_slices`, `rig_mission`, `rig_context_pack`, and `rig_context_get` (one context file or\n  section, as `rig context get` reads it).\n- **Owner (13):** `rig_up`, `rig_down`, `rig_snapshot_create`, `rig_snapshot_list`, `rig_discover`, `rig_bind`,\n  `rig_add`, `rig_bundle_inspect`, `rig_agent_validate`, `rig_rig_validate`, `rig_telemetry_events` (one bounded page\n  of event metadata), and:\n  - `rig_restore`, which starts a restore and returns its attempt;\n  - `rig_restore_status`, that attempt's receipt.\n- **Person (2):** `rig_question_list` and `rig_question_answer`, offered only on a grant service's grant that names the\n  person who owns the connection (`person.entity_id`, with the `question` pair). They list the team's questions waiting on\n  that person, as Steering shows them, and record that person's own answer, given through the connection: `answer` for an\n  ask, which returns their words to the asker, and `resolve` for a park. `docs\u002Freference\u002Fhosted-members.md` has the\n  contract.\n\n**Results:**\n- A structured result comes beside the text from the queue tools, `rig_whoami`, `rig_team`, the four workspace tools,\n  `rig_artifact_read`, `rig_human_decision_room`, `rig_restore_status` and the person tools. The other tools answer in\n  text.\n- Every failure carries the same structured shape: `ok: false`, a `code` and a `message`.\n\n**Identity:**\n- **Over stdio, and over HTTP with no grants:** the server acts as one seat, the `OPENRIG_SESSION_NAME` in its\n  environment. Every request carries that identity, so no tool call names a sender. Without it, messages, new tasks and\n  chat go through as an unknown sender (`unknown-mcp-` and eight hex digits, one per `rig mcp serve` process) with a\n  note at the top, and claim, update, hand off, unclaim and decide are refused with `actor_required`.\n- **Over HTTP with grants:** each caller acts as its own grant's seat.\n\n### Over HTTP: an assistant that can't start a local process\n\n- **No grants (no token file):**\n  - the listener stays on loopback and acts as `OPENRIG_SESSION_NAME`, declared, like stdio;\n  - a request whose `Host` isn't loopback is refused.\n- **With grants:** every request needs `Authorization: Bearer \u003Ctoken>`, loopback included, because a tunnel or proxy\n  delivers remote traffic to loopback.\n  - **Identity:** each caller acts as its grant's seat.\n  - **What it reaches:** only its rigs' seats and work, and its roots' artifacts. Anything else answers `out_of_scope`.\n  - **Bad credentials:** a missing, invalid or revoked token gets a 401, never the environment's seat.\n  - **A broken token file:** the server reads the file on every request. While it is missing or can't be read, every\n    request is refused (`auth_config_unreadable`); restore a valid, readable file and requests are served again, with\n    no restart. The other way back is a restart with no token file, which returns the server to the no-grants mode\n    above (loopback only). A restart never skips a token file that is present: its grants still apply.\n- **Beyond loopback** (`--bind`), the server starts only with a grant. TLS comes from the tunnel or proxy, not from\n  this server.\n- **`rig mcp token add`** prints the token once and stores only its hash.\n- **`revoke`:** the caller's next request is refused, and work it already handed over stays with its owners.\n- **Grants, binds and tunnels are the person's decisions.** Give them the commands, and don't run them on their behalf.\n\n### Join a team from an agent with no terminal of its own (desktop apps)\n\nAn agent in a desktop app can work with a team as a seat through this MCP server. If the app gives it a shell, it can\nuse the `rig` CLI instead, the same way.\n\n1. **Attach once.** With its shell, or by asking the person to run it:\n   `rig attach --self --rig \u003CrigId> --pod \u003Cnamespace> --member \u003Cname> --runtime \u003Cruntime> --print-env`.\n   Note the `OPENRIG_SESSION_NAME` it prints.\n2. **Give the person the MCP entry to add.** Don't edit their app's settings yourself. The entry runs\n   `rig mcp serve`, with `OPENRIG_SESSION_NAME=\u003Cthat seat>` in its environment. Most MCP clients take it as a\n   command, arguments and an `env` map. An app that can't start a local process connects to `rig mcp serve --http`\n   instead, with a grant for that seat (see \"Over HTTP\" above).\n3. **Hand off work** with `rig_queue_create`, and keep the `qitemId` it returns.\n4. **Read the answer** with `rig_queue_show \u003CqitemId>`. The item's state, closure and transition notes are where the\n   assignee records it, and `rig_artifact_read` reads an artifact it names. A call that times out has an unknown\n   outcome: check `rig_queue_show` with the same id before you retry, and retry only with that id.\n5. **Take work** with `rig_queue_list` (`owned: true`), `rig_queue_claim` and `rig_queue_update`. Close with the\n   answer in `note`. To pass it to the next seat, use `rig_queue_handoff`; to put back one you won't finish, use\n   `rig_queue_unclaim`.\n\nLimits today:\n- **OpenRig can't wake this agent itself.** `rig send` to an attached external node is refused, and a task's nudge to\n  it is unroutable. It sees new work when it checks `rig_queue_list`, or, if its app can run background shell\n  commands, with the opt-in wait below.\n- **Proven surfaces:** treat each app, and each mode inside one, as unproven until it has been run there.\n\n#### Wake on new work (opt-in; off unless the person turns it on)\n\nAn agent whose app can run a shell command in the background, and starts a new turn when that command finishes, can\nwait for its own work. Claude Code, including Claude Desktop's Code tab, does this.\n\n- **Only if the person has said they want teammates to be able to wake this session.** Never turn it on yourself, and\n  never change their settings for it.\n- The shell needs this seat's identity: export the `OPENRIG_SESSION_NAME` that the one-time attach printed.\n- Start this as a background command, then end your turn. Don't poll it yourself.\n\n```sh\n# Waits until a task is assigned to this seat, prints it and exits; ends after MAX seconds.\nmax=${MAX:-3300}; every=${EVERY:-5}; end=$(( $(date +%s) + max )); checked=0; failing_since=\"\"\nwhile [ \"$(date +%s)\" -lt \"$end\" ]; do\n  if out=$(rig queue list --owned --state pending --json 2>\u002Fdev\u002Fnull); then\n    checked=1; failing_since=\"\"\n    case \"$out\" in *'\"qitemId\"'*) printf 'NEW WORK: %s\\n' \"$out\"; exit 0 ;; esac\n  elif [ -z \"$failing_since\" ]; then\n    failing_since=$(date -u +%H:%M:%SZ)\n  fi\n  sleep \"$every\"\ndone\nwhy=\"Run rig queue list --owned to see why (this seat's identity, the daemon) before starting the wait again.\"\nif [ \"$checked\" = 0 ]; then\n  echo \"Couldn't check for work: every poll failed. $why\"; exit 1\nelif [ -n \"$failing_since\" ]; then\n  echo \"Checking stopped working at $failing_since: every poll since then failed. $why\"; exit 1\nfi\necho \"No new work before the deadline. Start the wait again.\"\n```\n\n- **When it wakes you with `NEW WORK`:** `rig queue claim` each item, do it, and close it with the answer. Then start\n  the wait again and end your turn.\n- **Don't leave an item you've seen pending:** it wakes you again at once. Claim it, block it or hand it off.\n- **A failed poll doesn't end the wait;** only new work or the deadline does.\n- **If every poll failed, or every poll since some point did** (the daemon stopped mid-wait), it says so, with when,\n  and exits non-zero instead of reporting no work. A failure followed by a successful poll stays quiet. Find out why\n  with `rig queue list --owned` (usually this seat's identity, or the daemon) before starting the wait again.\n- **If your app stops the background command, or you start a new session,** start the wait again.\n\n## Troubleshooting and Weird States\n\nWhen the CLI behaves strangely, use the smallest truthful check first:\n\n```bash\nrig whoami --json\nrig daemon status\nrig ps --nodes --json\n```\n\nSpecific operator rules:\n- `Sent to ...` + `Verified: no` is ambiguous delivery, not automatic failure. Check reply, `rig capture`, transcript evidence, or queue\u002Foutbox state before retrying.\n- partial `rig whoami --json` can happen when identity is still inferable but the daemon-backed path is degraded.\n- the unified-exec-process warning is a host\u002Ftooling-layer signal, not automatic proof that the OpenRig topology is unhealthy.\n\nIf you hit the unified-exec warning, inspect for stale one-shot helpers before touching live seats:\n\n```bash\nps -axo pid,ppid,command | rg 'tmux send-keys|rig queue create|tmux attach|codex|claude'\n```\n\nSafe cleanup target:\n- orphaned one-shot wrappers like `tmux send-keys ...`\n\nDo not mass-kill:\n- `tmux attach ...`\n- `codex ...`\n- `claude ...`\n\n## JSON and Error Posture\n\nDesign assumptions that hold in the shipped CLI:\n- many operator commands support `--json`\n- error messages are intended to say what happened, why it matters, and what to do next\n- daemon-backed commands fail loudly when the daemon is stopped or unhealthy\n- restore failure is not something you should silently reinterpret as success\n\n## After-Compaction Recovery Checklist\n\n1. `rig whoami --json`\n2. `rig transcript \u003Cyour-session> --tail 100`\n3. `rig ps` — lists ALL rigs on the host (know the world FIRST); then `rig ps --nodes --rig \u003Cyour-rig>` for your seats. ⚠ `rig ps --nodes --json` alone is your CURRENT rig only — do NOT mistake it for the whole host (a freshly-compacted agent has no other context to catch the lie).\n4. `rig chatroom history \u003Crig> --limit 50`\n\n## Commands That Do Not Exist\n\nDo not assume these exist unless the shipped help starts listing them:\n- `rig claim`\n- `rig blame`\n- `rig replay`\n","# OpenRig User\n\nThis is an as-built guide to the shipped `rig` CLI.\nUse current code and `rig ... --help` as ground truth if anything here ever conflicts with older planning docs.\n\nUse the OpenRig builder guidance when changing OpenRig behavior, doctrine, or release posture.\n\n\n## Coordination trust boundary\n\nCoordinate as openly as the trust boundary you actually control allows. Within a set of machines you\nown that already trust each other — they can reach each other's daemon URLs and the daemon itself\nrequires no authentication — direct `rig send`, `rig capture`, and `rig queue` should just work.\nDon't invent bearer placeholders, allowlists, trust handshakes, or guest-reach restrictions the\nenvironment doesn't require.\n\nDo not add or defend a restriction without naming the protected asset, the actual adversary, the\nblocked attack path, and the concrete consequence. Missing capability is not protection — repair the\nroute, registration, runtime posture, or product defect directly. Arbitrary boundaries create\nconstraint-induced circumvention: under goal pressure, agents build shadow transports, alternate\ncredentials, and weaker proof instead of the direct authorized path. Keep only explicitly stated\nexternal or irreversible boundaries — public push \u002F PR \u002F publish, and destruction of canonical data.\n\n## Coordination primitives — when to use which\n\nThree coordination surfaces, used together for forward-momentum work. Internalize this\non first read — it shapes every turn you take in a rig.\n\n### `rig send \u003Cseat> \"\u003Ctext>\"` — intra-pod direct messaging \u002F nudges\n\nUse when you need to ask a quick question or give a teammate context that does not\ncarry handoff semantics. **NOT for durable work.** NOT for state that must survive\nacross turns. The message lands in the target's pane; there is no durable queue\nrecord. The CLI prints `Sent to ...` (and `Verified: yes\u002Fno` with `--verify`); read\nthe receipt and move on.\n\nExample:\n\n```bash\nrig send dev-reviewer@example-project \"The import report is ready; the durable handoff names its evidence.\" --verify\n```\n\n### `rig queue create --destination \u003CY> --tags \u003C...> --body-file \u003Cpath>` — durable work item\n\nUse for any substantive work that must not fall through chat — slice handoffs,\nguard verdicts, QA results, full-tip reviews, multi-item batches. Survives agent\nrestarts. Tracked in the daemon SQLite schema. Surfaces in Project \u002F queue views\n+ in the destination seat's inbox. Tag with mission \u002F slice \u002F gate \u002F checkpoint\nso future-you (and any peer) can find it. Give the row a `--summary` (its subject, wherever the row is listed)\nand the `project:`, `mission:` and `slice:` tags when it is project work.\n\nBody discipline: substantive bodies go through **`--body-file \u003Cpath>`** (or `-` for stdin) — the\npurpose-built, corruption-safe surface (it kills the backtick-shell-corruption class for multi-line\nbodies). Do NOT inline a backtick-heavy or multi-line body via `--body`: `rig queue create` body\nparsing breaks on unescaped backticks and rejects flag-like tokens.\n\nExample:\n\n```bash\nrig queue create \\\n  --destination dev-reviewer@example-project \\\n  --summary \"Review the import report: it changes how rows are deduplicated\" \\\n  --tags \"project:example-project,mission:data-import,slice:import-report\" \\\n  --body-file \u002Ftmp\u002Fimport-report-handoff.md\n```\n\n### `rig queue handoff \u003Cqitem-id> --to \u003Cnext> ...` — hot-potato handoff\n\nUse when you have completed your turn on a qitem and the work moves to the next\nowner. **This is forward momentum.** The ball passes to the destination seat;\nchain-of-record (the prior qitem id) is preserved so the verdict trail is intact;\ntags carry the selected work context forward. Gate tags describe checks actually\nselected for that work; they do not require a fixed sequence of roles.\n\nExample:\n\n```bash\nrig queue handoff \u003Cqitem-id> \\\n  --to dev-reviewer@example-project \\\n  --summary \"Review the import report: it changes how rows are deduplicated\" \\\n  --tags \"project:example-project,mission:data-import,slice:import-report\" \\\n  --body-file \u002Ftmp\u002Fimport-report-handoff.md\n```\n\n### After a queue write — use the response; read back only when it doesn't show what you need\n\nA queue write (`create`, `claim`, `update`, `handoff`, `handoff-and-complete`) answers with the row it wrote; a\nhandoff answers with the closed row and its successor. When that answer shows what you need to establish, use it.\n\n`create` also prints `Queue create request ID: \u003Cid> (not proof of persistence)` on stderr *before* it sends the write,\nso an interrupted create can be reconciled. That ID names a request, not a row. The row is the `qitemId` on stdout\nwhen the command exits 0. A non-zero exit means no row was confirmed, even when stdout carries a `qitemId`: an\nindeterminate answer repeats the request ID so you can reconcile by it. Don't merge stderr into stdout and keep the\nfirst `qitem-…` you find there; a refused create prints its request ID first, too.\n\nA timed-out write can still land late. To retry a `create` or `rig stream emit` safely, repeat it unchanged with the\nsame `--id` (create's request ID, or the emit's own), since the daemon keeps one row or item per ID; an emit sent\nwithout `--id` has no ID to reuse, so look for it with `rig stream list --source \u003Cseat>` before emitting again.\n\nRead back (`rig queue show \u003Cid> --full --json`, or `rig queue transitions \u003Cid>`) when the answer doesn't show what you\nneed, for example:\n\n- the outcome was INDETERMINATE (a transport failure, or a 502 `remote_queue_write_failed` that may have reached the\n  other host), or the write warned `qitem_body_not_saved` (an existing row came back). Reconcile by the original ID\n  before any retry. A 502 whose `failureClass` is `unknown-host`, `unsupported-transport` or `registry` isn't\n  indeterminate: the daemon refused before contacting any host and wrote nothing (`create` says \"No row was\n  created\"). `unsupported-transport` means that host entry is SSH-declared. Use the http entry for the same machine\n  from `rig host list`; if there isn't one, add it with that machine's daemon URL (`rig host add --id \u003Cid>\n  --transport http --url \u003Cdaemon-url>`), asking whoever runs that host for the URL;\n- the output was compact or truncated and the field you need isn't in it (the compact receipt shows `bodyBytes`, not\n  the body, and its footer names what it left out);\n- you need a transition note, a closure or blocker detail, or a successor that the output you saw omits;\n- you need evidence from downstream of the write: the recipient's wake (`create --verify` waits for it), or its\n  pickup or claim (a later read);\n- your team's custody rule asks for a separate read-back.\n\nDon't read back only to see again a field the response already showed you.\n\n### §1b doctrine — turn ends by passing the ball\n\n**A turn ends by passing the ball, never by going idle holding the slice waiting\non a confirmation the selected process does not include.** Follow the current\n`mission-slice-sop`: proportional owner checks are the default; independent review\nruns when selected, at the authored work boundary. Role names do not add per-commit\nguard, QA, or orchestration gates. Do the authorized work, run its selected checks,\nand return the outcome through durable custody.\n\nValid pauses are only:\n\n- A genuine blocker — file a blocked-state qitem against the blocking peer or\n  surface explicitly to orch.\n- A scope-or-architecture question that requires owner input and changes the\n  plan — surface to orch with the specific decision needed.\n\nImplementing already-authorized work is neither of these. Proceed without\nphantom-gating on an imagined \"next prompt\" or \"operator confirmation\" that the\nprocess does not require.\n\n### Anti-patterns\n\n- Using `rig send` for durable work → use `rig queue create` instead. Sends do\n  not survive restarts and do not show up in queue\u002Fproject views.\n- Idle-holding a slice for an imagined \"next prompt\" or \"operator confirmation\"\n  that the process does not require → pass the ball via `rig queue handoff` and\n  proceed to the next slice or stand by for the inbound verdict. See the §1b\n  doctrine above.\n- Inlining a multi-line \u002F backtick-heavy body into `rig queue create --body`\n  → use `--body-file \u002Ftmp\u002F\u003Cdescriptive-name>.txt` (or `-` for stdin), the\n  corruption-safe surface. The body parser does not tolerate raw backticks or\n  flag-like tokens inline.\n\n## Runtime-Gated Coordination Primitives\n\nOpenRig v0.3.1 is published publicly as `@openrig\u002Fcli@0.3.1` and GitHub Release\n`v0.3.1`. It includes the bundled PL-004 Coordination Primitive System: Phase A\n`rig stream` \u002F `rig queue`, Phase B `rig project` \u002F `rig view`, Phase C\n`rig watchdog`, and Phase D `rig workflow` \u002F `workflow-keepalive`.\n\nThese are shipped product surfaces in v0.3.x, but they require a compatible\nv0.3.x daemon and matching SQLite schema at runtime — the installed package\nversion is not automatically the version of the daemon serving you. If a\ncoordination command behaves unexpectedly, confirm the running daemon with\n`rig whoami --json` and daemon status before assuming a product bug.\n\nDefault posture:\n\n- Treat daemon `rig queue`, `rig stream`, `rig project`, `rig view`, `rig watchdog`, and\n  `rig workflow` as the product coordination surfaces when the active daemon is v0.2.0 or newer.\n- Use daemon-backed `rig queue` for durable routing. `update \u002F show \u002F list`\n  complement `create \u002F handoff` for inspection and state changes; records in an\n  unrelated store are not evidence that this daemon owns the work.\n- If a daemon-backed coordination command fails, debug the command\u002Fruntime\u002Fschema edge directly;\n  do not assume the right workaround is to drop back to a config-layer primitive.\n- Do not perform daemon stop\u002Fstart, production DB copy\u002Fmutation, release, publish, or other\n  consequence-boundary actions unless the operator\u002Fworkstream has granted that specific gate.\n\n## First-user workspace setup\n\nWhen booting into a rig on a host where the workspace is unset, gap-ridden, or\npoints at a stale layout, address that before substantive project work. The\nshipped surface is small + bounded — reach for the canonical commands rather\nthan improvising.\n\n### Detect workspace state at boot\n\nAgent-actionable when the daemon is reachable.\n\n```bash\nrig workspace validate --json\nrig workspace validate \u003Cpath> --kind \u003Cuser|project|knowledge|lab|delivery> --json\n```\n\n`rig workspace validate` walks the workspace root and emits a structured\nfrontmatter-gap report against the v0 contract. Exit code is non-zero when\ngaps exist (operators chain into hygiene fix loops). Default root is the\ncurrent directory; pass a positional path to validate elsewhere. `--kind`\nscopes the contract to a specific workspace kind; omit for a kind-agnostic\nstructural check.\n\nIf `rig workspace validate` reports a non-zero `gapCount` OR the workspace\nroot is unset \u002F unwritable, the workspace needs instantiation — see the next\nsection.\n\n### Instantiate the canonical workspace scaffold\n\nAgent-actionable. The operation is additive and preserves existing files.\n\n```bash\nrig config init-workspace\nrig config init-workspace --root \u003Cpath>\nrig config init-workspace --dry-run --json\n```\n\n`rig config init-workspace` scaffolds the canonical workspace layout at the\nconfigured `workspace.root` (default `~\u002F.openrig\u002Fworkspace`):\n\n- `missions\u002F` — release missions + slices\n- `exhaust\u002F` — project-local coordination exhaust\n- `SPEC.md` — project intent\n- `project.yaml` — project catalog selections and mission root\n- `workspace.yaml` — project registration\n- `.gitignore` — local OpenRig state and exhaust exclusions\n\n`--root \u003Cpath>` targets a non-default root for this call; `--dry-run` reports\nwhat would be created without writing. `--force` is deprecated compatibility\nand still preserves existing files.\n\n### Redirect the workspace root\n\nOperator-gated when persistent. Agent-actionable when one-shot via env-var.\n\nFor a single command:\n\n```bash\nOPENRIG_WORKSPACE_ROOT=\u003Cpath> rig \u003Ccommand> ...\n```\n\nFor a persistent host-level redirect, the operator changes the config file or\nruns the setter:\n\n```bash\nrig config set workspace.root \u003Cpath>\n```\n\nConfigStore precedence: `OPENRIG_WORKSPACE_ROOT` env > config-file\n`workspace.root` > built-in default `~\u002F.openrig\u002Fworkspace`. The same\nprecedence governs `OPENRIG_WORKSPACE_SPECS_ROOT` → `workspace.specs_root`\n(default `\u003Cworkspace_root>\u002Fspecs`).\n\nPrefer the env-var form for one-shot redirects (transparent to operators);\nreserve `rig config set` for changes the operator owns.\n\n### Build a workspace from scratch\n\nAgent-actionable. Same surface as the canonical scaffold above; the\n`workspace.root` cascade handles non-existent host paths.\n\n```bash\nrig config init-workspace --root \u002Fpath\u002Fto\u002Fnew\u002Fworkspace\n```\n\nThe command additively creates any missing canonical entries and preserves\nevery existing one; only a complete six-entry scaffold is a no-op. Run\n`rig workspace validate \u002Fpath\u002Fto\u002Fnew\u002Fworkspace --json` after to confirm the\ncontract holds.\n\n### Create a workflow inside an existing workspace\n\nAuthoring is operator-or-agent; validation + instantiation are\nagent-actionable.\n\nWorkflow spec files live at:\n\n```\n\u003Cworkspace_root>\u002Fspecs\u002Fworkflows\u002F\u003Cname>.yaml\n```\n\n`\u003Cworkspace_root>` resolves via the ConfigStore precedence named above.\nThere is no `rig workflow create` verb in v0.3.x — the spec YAML is authored\ndirectly. Template by hand from the documented schema, or copy a built-in\nstarter from `\u003Copenrig install>\u002Fdist\u002Fbuiltins\u002Fworkflow-specs\u002F` and adapt.\nOnce written:\n\n```bash\nrig workflow validate \u003Cworkspace_root>\u002Fspecs\u002Fworkflows\u002F\u003Cname>.yaml --json\n\nrig workflow instantiate \u003Cworkspace_root>\u002Fspecs\u002Fworkflows\u002F\u003Cname>.yaml \\\n  --root-objective \"\u003Cone-line objective for the run>\" \\\n  --created-by \u003Cyour-session>@\u003Cyour-rig> \\\n  --json\n```\n\nBoth `--root-objective \u003Ctext>` and `--created-by \u003Csession>` are REQUIRED\non `instantiate` — omitting either yields a Commander required-option\nerror before the daemon is contacted. `--entry-owner \u003Csession>` is an\noptional override for the entry-step owner; default routing is per the\nworkflow spec.\n\n`validate` returns a structured ok\u002Ferror report; `instantiate` creates a\nworkflow instance + entry-step qitem. Inspect existing surface state with:\n\n```bash\nrig workflow specs --json              # list registered specs (built-in + operator-authored)\nrig workflow list --json               # list active workflow instances\nrig workflow show \u003CinstanceId> --json  # inspect one instance\nrig workflow project \u003CinstanceId>      # ADVANCE an instance — projects the next-step packet\nrig workflow continue \u003CinstanceId>     # read-only inspector of an instance (does NOT advance it)\n```\n\n*(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\u002Fcli\u002Fsrc\u002Fcommands\u002Fworkflow.ts`, 13 registered `.command(...)` entries; the earlier \"6-verb surface \u002F continue-advances\" claim here was stale). Verify individual subcommand flags with `rig workflow --help`.)*\n\n## Permission policy — pick one at setup (onboarding)\n\nOpenRig 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 \u002F onboarding this is a required choice, presented as a top-level pick:\n\n- **POLICY MODE** — pick a built-in policy and have it applied:\n  - **Locked** — deny-by-default whitelist; untrusted rigs\u002Fwork.\n  - **Standard** ⭐ (recommended) — routine development including push is allowed; PR creation, publication, merge\u002Frelease, force-push and destructive actions ask.\n  - **Open** — allow-by-default; everything except explicitly-destructive, which ask.\n\n  The built-in definitions ship as read-only policy spec files (Locked \u002F Standard \u002F 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` \u002F Codex `config.toml`), interactively, showing the diff before it writes.\n- **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.\n- **No choice = the floor** — the minimal usability baseline (Claude `acceptEdits` \u002F Codex workspace-only \u002F Pi `--no-approve`), one consistent minimum, nothing more.\n\nThe floor and YOLO are **launch flags** OpenRig sets deterministically; the Locked \u002F Standard \u002F 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`**.\n\n## v0.3.x Starter, Workspace, And Plugin Surfaces\n\nOpenRig v0.3.0 adds `rig agent-image`, `rig context-pack`, `rig workspace`, and\n`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\n`product-team` for human-directed work and `conveyor` for workflow-oriented\nwork. Treat `demo` as legacy\u002Ftest content unless a task specifically asks for\nthe old demo spec. *(0.6.6: the built-in teams are `starter` and `factory`, plus the\nspecialist teams `code-review`, `research` and `pm`. `product-team`, `conveyor` and\n`demo` are gone, and `first-project` is starter's old name. `workshop` is a rig\nbundle.)*\n\nOpenRig v0.3.1 adds public package\u002Fsource surfaces for Plugin Primitive v0,\nClaude Auto-Compaction Policy, migration `040_workflow_specs_diagnostic`,\nLibrary Explorer finishing, Settings Destination Explorer, Dashboard\u002FFor You\nvellum refresh, storytelling adapter, and action outcome + inline error UX.\n\n`rig plugin` is read-only at v0:\n\n```bash\nrig plugin list\nrig plugin show \u003Cid>\nrig plugin used-by \u003Cid>\nrig plugin validate \u003Cpath>\n```\n\nThere is no `rig plugin install` verb in v0.3.1. Plugin installation remains\nexplicit operator copy\u002Fsymlink to `$OPENRIG_HOME\u002Fplugins\u002F\u003Cplugin-id>\u002F`.\n\nThe v0.3.1 package introduced opt-in Claude auto-compaction policy through\n`policies.claude_compaction.*` ConfigStore keys. A package version alone says\nnothing about a running daemon's configuration; inspect the selected instance\nbefore relying on a policy or its default.\n\nCompatibility checks:\n- `rig down` accepts a rig name or id. An ambiguous name matching more than one\n  active rig is refused with matching ids; use the intended id. It ends every\n  agent's session and any work in progress, so check `rig ps --nodes --rig \u003Crig>`\n  and that the person asked; `rig up \u003Crig> --existing` restores it.\n- For queue\u002Fview JSON or limit differences, compare the installed command's help,\n  the running daemon version and the actual response. A wrapper mismatch is not\n  by itself a daemon-health failure, and historical workarounds are not current\n  behavior guarantees.\n- After a startup timeout, inspect status and logs before retrying; a timeout\n  does not establish whether the underlying operation completed.\n\n## Recovery and Resilience (v0.3.4+)\n\nv0.3.4's theme is Recovery + Resilience. The surfaces below compose into a\nsingle boot-to-running-rig path that survives crashes, hand-resumed sessions,\nprofile-load drift, and partial workspace state without silently fudging\nstatus.\n\n### `rig start` — recovery entrypoint\n\n`rig start` is the top-level recovery sequencer. It does not invent recovery;\nit composes existing primitives (daemon start + kernel verify + per-rig\nrestore) into one call.\n\n```bash\nrig start                    # interactive: daemon + kernel + pick-and-restore\nrig start --last             # headless: restore rigs that were last running; a rig stopped on purpose stays down\nrig start --all              # headless: restore all rigs with restore-usable snapshots\nrig start --rigs \u003Cname> [\u003Cname>...]   # headless: restore only the named rigs\nrig start --json             # JSON output for agents\n```\n\n`rig start --last` keeps down a rig that was stopped on purpose (`rig down` or `rig seat stop`).\nBring it back with `rig start --rigs \u003Crig>`. A rig whose seat statuses can't be read is still\nattempted, with a warning (`seat_status_unreadable`).\n\nFraming: `rig start` is the RECOVERY entry point, not the getting-started\nhero. The fresh-user boot hero remains `rig up \u003Cteam>` (typically\n`rig up starter` for a first change, or `rig up factory`). Reach for `rig start` after a host reboot, daemon\nrestart, or any \"bring my rigs back\" moment.\n\n### `rig reconcile-session` — no-launch adopt of a hand-resumed session\n\nWhen an operator has externally resumed an agent session (e.g. attached a\nshell, restarted a runtime by hand) and you want OpenRig to reconcile its\nlifecycle state without re-launching or sending input, use:\n\n```bash\nrig reconcile-session \u003Csession>\nrig reconcile-session \u003Csession> --rig \u003CrigId> --node \u003ClogicalId>\nrig reconcile-session \u003Csession> --no-launch\nrig reconcile-session \u003Csession> --json\nrig reconcile-session \u003Csession> --repair-missing-pane --no-launch\n```\n\nThis is a no-launch, no-input adopt: it records a new claimed session row for\nthe seat (any running row is superseded); it re-captures the resume token if\nit can, and conversation continuity stays unverified. `--rig`\u002F`--node`\ndisambiguate when the canonical session name does not uniquely resolve.\n`--no-launch` is accepted for explicitness.\n\n`--repair-missing-pane --no-launch` is different: for a running launched seat\nwhose tmux pane was never recorded, it fills in the pane and keeps the\nsession, resume token and generation. It never adopts. Both forms refuse\nwhile the seat's typing protection is on.\n\n### Five-term restore status vocabulary\n\nThe shipped restore vocabulary is intentionally honest. It surfaces in\n`rig up` \u002F `rig restore` \u002F `rig ps`. Use the term that fits — do not collapse\nto a generic \"ok\u002Ffailed\":\n\n- `resumed` — seat resumed from its original session\u002Fsnapshot and is live.\n- `fresh-primed` — seat opted into `--fresh` and was freshly started.\n- `awaiting-decision` — zero-session honest state. There is no resumable\n  session AND no `--fresh` opt-in was given; the seat is waiting for an\n  operator decision. Previously fudged as `failed`; that was wrong — nothing\n  is broken, the system is asking for input.\n- `attention_required` — seat is in a state needing operator attention; not\n  a transport failure. Clear via `rig seat clear-attention` once the\n  attention has been resolved.\n- `failed` — the send transport or launch genuinely failed.\n\nThis replaces the prior collapsed model (the v0.3.3 four-term vocabulary, in\nwhich `rebuilt` was a term, is retired).\n\n### `rig seat clear-attention` — audited reconcile of stuck attention\n\nWhen a seat is stuck in `attention_required`, do NOT hand-edit SQLite to\nfake-clear the state. Use the evidence-gated, operator-attested, audited\nreconcile:\n\n```bash\nrig seat clear-attention \u003Csession>\nrig seat clear-attention \u003Csession> --reason \"operator attested: the operator re-authed, confirmed live\"\nrig seat clear-attention \u003Csession> --json\n```\n\n`--reason \u003Ctext>` can acknowledge startup-status and subset-restore attention.\nIt does not bypass full-restore continuity checks or an active pane-identity\nmismatch\u002Fmissing-pane check; those run first. Successful identity re-verification\ncan also clear coexisting startup or subset-restore attention. If neither earlier\npath clears attention, omitting `--reason` requires activity or send evidence.\nStartup and restore clears write their corresponding audit events; an identity-only\nclear updates the current binding and identity verdict without a clear event.\nAcknowledgment or responsiveness alone does not prove that the original\nconversation resumed.\n\nTwo startup cases also end in `attention_required`, and the result says what to do:\n- **Assisted startup** (a community harness preset with `startup_assisted: true`): the startup text and Enter were\n  sent but submission isn't confirmed. Check the pane and submit any staged text, don't resend it, then run the\n  reported `rig seat clear-attention \u003Csession> --reason \"...\"` once the seat has responded.\n- **A refused startup turn** (Claude answered a startup turn with a refusal such as an expired login): nothing more is\n  typed into the seat, and the result names how many later startup inputs weren't sent. A fresh start that ran no\n  one-shot action stays continuable: `rig seat continue \u003Cseat>` delivers the whole startup again, the refused turn\n  included. A resumed or forked seat keeps its conversation and isn't offered continue; a fresh start that can't\n  continue names `rig seat launch \u003Cseat> --fresh --stop --reason \"\u003Cwhy>\"`.\n\nA 422 response names the uncleared class and its failed check. If the recorded\nnative token needs correction and you know the actual token, use\n`rig seat set-resume-token \u003Csession> --token-stdin --reason \u003Cexplanation>`, then\nrerun `rig seat clear-attention \u003Csession>` to check the live evidence. The token\nupdate records operator provenance; it does not itself prove continuity.\nStopping\u002Frelaunching a working seat is a separate disruptive operation, not a\nrequired cleanup or proof of resumed lineage.\n\n### Periodic snapshots — crash-insurance floor\n\nThe daemon ships a periodic-snapshot scheduler. It runs independently of\nteardown events and provides the crash-insurance floor that prior\nevent-only\u002Fteardown-only snapshots could not provide on hard crashes.\n\nConfig keys (SettingsStore):\n- `snapshots.periodic.enabled` — default `true`\n- `snapshots.periodic.interval_seconds` — default `300`\n- `snapshots.periodic.retention_keep` — default `10`\n\nNewest-wins semantics: when both `auto-periodic` and `auto-pre-down`\nsnapshots exist for a rig, the freshest of the two is selected for restore.\nA newer `auto-periodic` beats a stale `auto-pre-down` (the crash fix); a\ngenuinely-fresher `auto-pre-down` still wins on graceful cycles. Manual\nsnapshots are handled separately. See\n`packages\u002Fdaemon\u002Fsrc\u002Fdomain\u002Fsnapshot-repository.ts` for the ordering rule.\n\nThe last-snapshot floor surfaces in `rig ps` \u002F status output so an operator\ncan see at a glance how recent the crash-insurance floor is.\n\n### Codex profile-v2 preflight\n\nProfile-bearing launch\u002Frestore surfaces run a profile-load preflight. When\nprofile-load issues are detected, the failure is honest and actionable\n(named error + remediation pointer) instead of a silent partial launch that\nwould later look like an attention_required seat with no explanation.\n\n### cmux launch readiness\n\ncmux-backed launches no longer produce silent partial workspace state. When\nparts of the workspace are missing, the launch surfaces partial state\nhonestly and the UI exposes a one-click open-missing affordance.\n\n(See also `## Token-Efficient Defaults (v0.4.0+)` below for the compact-by-default read-command surface that lands in 0.4.0.)\n\n## Token-Efficient Defaults (v0.4.0+)\n\nv0.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 \u002F kubectl read-command grammar. **All defaults preserve breadth and capability — the firehose is one explicit flag away.**\n\n### `rig ps` — scope-aware: bare `rig ps` = ALL rigs; `--nodes` = your rig only\n\n```bash\nrig ps                      # ALL active rigs on the host, one compact row each — RUN FIRST to know the world\nrig ps --rig \u003Cname>         # one named rig's summary\nrig ps --nodes --rig \u003Cname> # per-node (seat) detail for a NAMED rig — the normal drill-in\nrig ps --nodes              # per-node detail — CURRENT rig ONLY (deliberately narrow; NOT the whole host)\nrig ps --json               # compact JSON (default = a bare array of ALL non-archived rigs)\nrig ps --nodes -A           # cross-rig node inventory (was v0.3.4 default)\nrig ps --nodes --full       # complete record (the v0.3.4 per-node default shape; resumeToken VALUE retained here for downstream consumers)\nrig ps --nodes --session \u003Csess>  # narrow to one canonical session\nrig ps --active             # opt-in active-state filter (does NOT change the all-states default — ps surfaces topology\u002Freadiness, where stopped\u002Frecoverable\u002Fattention IS the actionable signal)\n```\n\n**v0.4.0 breadth + projection changes**:\n- **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 `@\u003Crig>` suffix); `--rig \u003Cname>` picks another rig, `-A` widens `--nodes` to the whole host (expensive — prefer `--fields`\u002F`--limit`).\n- **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.\n- **All-states stays default** (different from `rig queue list` which defaults to active-only) — for `ps`, non-running states ARE often the actionable signal.\n- **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).\n\n**⚠ 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 output is not the whole world.** Never conclude \"my rig is the only rig on the host\" from a `--nodes` read — run bare `rig ps` FIRST (cheap; it lists every rig), then `rig ps --nodes --rig \u003Cname>` for the one you need. (`-A` widens to the whole-host node view; choose it when that breadth is needed.)\n\n### `rig whoami` — compact-by-default + `--full` (`--verbose` alias)\n\n```bash\nrig whoami                  # compact: identity + peers names + edges + transcript path\nrig whoami --json           # compact JSON\nrig whoami --json --all-peers  # compact JSON with every peer, when output.compact bounds the list\nrig whoami --full           # complete payload (v0.3.4 default shape)\nrig whoami --verbose        # alias of --full\n```\n\nThe first command every agent runs on boot AND every compaction-restore. The compact default keeps identity-recovery essentials (`identity`, `peers` names + sessionNames, `peersNote`, `edges` directional `kind` + `to.sessionName`, the transcript path). `--full` adds `contextUsage`, `commands`, `runtimeContext` and `workspace`. With `output.compact` on, compact JSON lists at most `output.whoami_peers` peers (default 8): edge peers first, then your pod, then roster order. `peersNote` and `peersOmitted` then say how many were left out, and `--all-peers` lists every one; `edges` stays complete. The compact-default is an ALLOWLIST projection — future payload fields default to `--full` and cannot silently re-bloat the every-boot path.\n\n### `rig queue list` — active-frontier + docker\u002Fkubectl grammar\n\n```bash\nrig queue list                       # active, compact, CURRENT-rig (docker-ps default)\nrig queue list -a                    # + closed\u002Fdone history within current breadth (docker -a)\nrig queue list -A                    # cross-rig breadth (kubectl -A)\nrig queue list --full                # add body + chain-of-record + transition history\nrig queue list -o json               # compact JSON (token-safe, machine-parseable)\nrig queue list --full -o json        # full JSON\nrig queue list --mine                # just the caller's items\nrig queue list --destination \u003Cs>     # destined to \u003Cs>\nrig queue list --source \u003Cs>          # sourced by \u003Cs>\nrig queue show \u003CqitemId>             # bounded single-item body preview\nrig queue show \u003CqitemId> --full      # complete body and chain fields; a closed row adds closingTransition (the close's state, reason, target, actor, time and note)\n```\n\nFour orthogonal axes (scope × history × field-breadth × encoding), all composable. **STOP using bare `rig queue list` as the cross-rig firehose.** Default is now active + compact + current-rig. Cross-rig history with full bodies is opt-in via `-A -a --full`; request only the breadth and fields needed for the question.\n\n### `rig restore-check` — summary + not-ready-only default + `--full`\n\n```bash\nrig restore-check               # summary counts + not-ready seats (with reasons) only\nrig restore-check --full        # complete per-seat readiness across the fleet (v0.3.4 default)\nrig restore-check --rig \u003Cname>  # narrow\nrig restore-check --as \u003Csession>  # narrow to one seat\n```\n\nThe summary retains not-ready seats and their reasons; `--full` adds ready-seat detail when needed. Scope the query before expanding its payload.\n\n### `rig context` — context-window usage viewer (0.4.x; REMOVED in 0.5.0)\n\n```bash\nrig context                # compact summary        (0.4.x only)\nrig context --full         # complete current payload\nrig context --rig \u003Cname>   # narrow to one rig\nrig context --threshold 80 # filter to seats at\u002Fabove 80%\n```\n\nLower leverage than the others; keeps the read-command surface compact-by-default after the 0.4.0 upgrade. **⚠ 0.5.0: this usage viewer is removed entirely and the `rig context` name is reassigned to the context library (store + compose) — see \"Context packs and paced delivery (0.5.0)\" below. On a 0.5.0 host, bare `rig context` is the library, not this viewer.**\n\n### Keep routine reads bounded\n\nChoose scope, active\u002Fhistory breadth and fields before expanding a result. A\nstatus question usually needs identifiers, owner, state and reason; open the full\nbody or artifact when it is relevant. Preserve full evidence on disk instead of\nrepeatedly loading unchanged output. Compact defaults reduce reading cost; they\ndo not remove the full-detail path or prove that nothing exists outside the scope.\n\n### `rig scope mission|slice progress` — deterministic progress updates\n\n```bash\nrig scope mission progress \u003Cmission> --add \"\u003Cline>\"   # append a progress line; --set replaces; --section \u003Cheading> (default Rail); --status active|done|blocked\nrig scope slice progress \u003Cslice-path> --add \"\u003Cline>\"  # same flags: --add \u002F --set, --section \u003Cheading>, --status active|done|blocked\n```\n\nReplaces hand-editing `PROGRESS.md` with markdown. Writes the canonical structure the OpenRig PROGRESS UI page reads. `rig scope mission create` + `rig scope slice create` now scaffold `PROGRESS.md` automatically.\n\n### `rig scope mission|slice stage \u002F verified \u002F repair` — deterministic maturity vocabulary\n\n```bash\nrig scope slice stage \u003Cslice> \u003Cnew-stage>             # wip \u002F provisional \u002F established \u002F canonical \u002F superseded \u002F retired\nrig scope slice stage \u003Cslice> superseded --successor \u003Cid>  # superseded REQUIRES --successor (rejected otherwise)\nrig scope mission stage \u003Cmission> \u003Cnew-stage>         # same enum + rules at mission tier\n\nrig scope slice verified \u003Cslice> --against \"\u003Csource>\" # stamp `verified: \u003Ctoday> against \u003Csource>`; --against MANDATORY\nrig scope mission verified \u003Cmission> --against \"\u003Csource>\"\n\nrig scope slice repair \u003Cslice>                        # idempotent repair: backfill PROGRESS.md, conform id\u002Fstage\u002Fverified, repair ghosts\nrig scope mission repair \u003Cmission>                    # mission-tier idempotent repair\n\nrig scope slice show \u003Cslice>                          # derives read-time effective-reliability from (stage × verified)\n                                                      # — stale-`verified` `canonical` reported as effectively `provisional`\n```\n\nComposes with the `progress` command + scaffolding to update scope IDs and maturity vocabulary through `rig scope`. Agents update `stage` \u002F `verified` \u002F `id` through commands rather than hand-editing markdown and drifting. The `--against` MANDATORY rule on `verified` is the anti-stale keystone: bare timestamps are rejected because a bare timestamp is exactly what lets stale trackers lie while looking fresh. **STOP hand-editing the `stage` \u002F `verified` \u002F `id` fields in scope frontmatter; use the new verbs.** Existing missions \u002F slices with `id:null` ghosts or missing `PROGRESS.md` are repaired idempotently via `repair`.\n\n### `rig skill audit` — skill cascade provenance\n\n```bash\nrig skill audit                  # human report of findings\nrig skill audit --json           # structured findings\nrig skill audit --severity warn  # stale + mirror-drift only\nrig skill audit --rig \u003Cname>     # narrow to embedded skill copies for one rig\n```\n\nRead-only audit of the skill cascade. Detects `missing` \u002F `stale` \u002F `self-referential` \u002F `invalid-date` \u002F `mirror-drift` across the canonical skills workspace → product mirror → hub cwd → installed plugin chain. Findings route back to the lifecycle for shaped propagation runs. **False-green prevention**: when audit evidence is unavailable, the CLI emits `unable-to-audit` with exit code `2` rather than reporting `clean`.\n\n### `rig seat clear-attention` — extended to derived projection staleness\n\n`clear-attention` also reaches restore-derived attention even when\n`startupStatus=ready` and `sessionStatus=running`. Full-restore attention requires\nthe restore reconciler's exact native-token and usable-pane checks; `--reason`\ncannot replace them. Subset-restore attention can reach the attestation path\nwhen no active pane-identity class takes precedence. That path records\n`operator_recovered` with `runtimeCwdVerified:false`; it is an acknowledgment,\nnot proof of resumed lineage. Without an explicit stored continuity outcome,\ninventory leaves continuity null (`unverified` in `rig seat status`) unless the\nsame restore attempt has a matching receipt and reconciliation with strict\nnative-token and usable-pane proof. Explicit stored outcomes remain historical\nfacts; acknowledgment or responsiveness alone cannot infer `resumed`.\n\n### Native Codex session id capture\n\nCodex seats can now record the real native session id from the Codex\n`SessionStart` hook instead of relying on scrape-shaped identity. Corroborate the id across the current hook payload, provider history and\nmanaged record before relying on it. A release introducing native capture does\nnot prove that every existing seat uses it; retain any unavailable or conflicting\nidentity evidence explicitly.\n\n### Codex resume preserves approval posture\n\nResuming a Codex seat preserves the launching seat's approval\u002Fsandbox posture\nand profile flags. Product-emitted resume commands carry the posture flags\ninstead of silently falling back to implicit-deny or an unrelated profile.\n\nDo not \"fix\" a resumed Codex seat by relaunching it with broader approvals\nunless the operator explicitly grants a bounded window. Verify the seat's\nactive posture first, and preserve it when composing recovery commands.\n\n### `rig seat set-resume-token --token-stdin`\n\n```bash\nprintf '%s' \"$RESUME_TOKEN\" | rig seat set-resume-token \u003Csession> --token-stdin\n```\n\nUse this command to set or restore a seat resume token. It replaces direct\nSQLite edits, rejects unauthorized writes and bad\u002Fnull token false-ready paths,\nrecords redacted audit\u002Fprovenance, and keeps token material out of command\narguments, stdout, logs, and normal status rows. Use stdin, not an inline flag,\nwhen passing token material.\n\n## Core Loop\n\nMost work in OpenRig reduces to this loop:\n- recover identity: `rig whoami` (compact default; add `--full` only when you need the heavy payload)\n- inspect inventory: `rig ps --nodes` (compact default; add `--full` only when you need the firehose)\n- read context: `rig transcript ...`, `rig ask ...`, `rig chatroom history ...`\n- act: `rig send`, `rig capture`, `rig broadcast`, lifecycle commands\n\n## Agent-Managed Apps\n\nAn agent-managed app is a deployable OpenRig unit made of:\n- the software or service\n- one specialist agent dedicated to that software\n\nTreat the specialist as the domain delegate for that app.\nThe current canonical example is:\n- rig: `secrets-manager`\n- pod: `vault`\n- member: `specialist`\n- logical ID: `vault.specialist`\n- session: `vault-specialist@secrets-manager`\n\nTypical operator loop:\n\n```bash\nrig up secrets-manager --cwd \u002Fpath\u002Fto\u002Fproject\nrig ps --nodes --json\nrig send vault-specialist@secrets-manager \"Check Vault health and report back.\" --verify\nrig env status secrets-manager\nrig env logs secrets-manager\n```\n\nCross-rig communication is valid when the target session resolves uniquely.\nExample:\n\n```bash\nrig send vault-specialist@secrets-manager \"Read secret\u002Fdata\u002Fdogfood and report the value.\" --verify\n```\n\nUse the specialist instead of teaching every peer the same app-specific toolchain.\nFor Vault, ask `vault.specialist` to do secrets-domain work rather than improvising curl or Vault CLI usage in unrelated agents.\n\n## Identity and Recovery\n\nStart here after launch, compaction, or confusion:\n\n```bash\nrig whoami --json\n```\n\nWhat it gives you today:\n- identity: rig, logical ID, pod\u002Fmember, session name, runtime\n- peers and directional edges\n- transcript info\n- `contextUsage` when available\n\nFlags:\n```bash\nrig whoami --session \u003Cname>\nrig whoami --node-id \u003Cid>\n```\n\nIf the daemon is unreachable but identity can still be inferred, `--json` may return a partial result instead of crashing.\n\n`WhoamiResult` (v0.3.3+) carries a required `peersNote` field with three pointers\nthe agent can use to navigate the rest of the rig from a cold start. The\nhuman-formatted CLI output preserves the literal `Peers:` line prefix verbatim\n(parser\u002Ftest compatibility) and surfaces the clarifier in-band beneath it; the\nJSON form exposes `peersNote` directly for programmatic consumers.\n\n## Inventory and Monitoring\n\n```bash\nrig ps                      # ALL active rigs on the host, one compact row each (run FIRST to know the world)\nrig ps --nodes              # compact node inventory (current rig)\nrig ps -A                   # all-rigs breadth (was the pre-0.4.0 default)\nrig ps --nodes --full       # complete per-node record (the firehose — opt-in)\nrig ps --nodes --json       # compact JSON node inventory (add --full for the full record)\n```\n\n**v0.4.0 flipped these to compact-by-default — see the `rig ps` compact-defaults section above; STOP using bare `rig ps --nodes --json` as a fleet-wide firehose (scope and detail are separate choices).** The compact `rig ps --nodes` node inventory (add `--full` only when you need the complete record, `-A` for cross-rig breadth) carries, per node:\n- session name\n- runtime\n- session\u002Fstartup status\n- restore outcome (compact: `resumeTokenPresent` boolean; the token VALUE is in `--full`)\n- attach\u002Fresume commands\n- latest error\n\nOther health surfaces:\n\n```bash\nrig status\nrig daemon status\nrig config\nrig preflight\nrig doctor\nrig env status \u003Crig>\nrig env logs \u003Crig>\nrig env down \u003Crig>\n```\n\n### Bounded agent self-scout\n\nUse the typed health projection before reading raw coordination history. The\ndefault query is the current seat; widen deliberately when the evidence points\nbeyond it:\n\n```bash\nrig health --json\nrig health --rig \u003Crig-id> --json\nrig health --instance --json\nrig health explain \u003Cfinding-id> --json\n```\n\nFollow the returned stable finding ID and `suggestedInspection`. Use `explain`\nwhen the summary matters: it returns the same canonical record with its bounded\nwindow, freshness, literal detector rule, evidence references, and next\ninspection. Human output projects those same fields; it does not calculate a\nsecond score.\n\nAn empty result means only that no records matched the bounded query. It is\n**not a healthy assertion**. Stale, unavailable, contradictory, and\nindeterminate evidence stays explicit. Never read raw SQLite for a self-scout,\nand never turn a finding into an acknowledgement, notification, queue row, or\nremediation automatically: `rig health` is strictly read-only.\n\n## Transcript and Communication\n\n### Transcript access\n\n```bash\nrig transcript \u003Csession> --tail 100\nrig transcript \u003Csession> --grep \"pattern\"\nrig transcript \u003Csession> --json\n```\n\n### Send to one session\n\n```bash\nrig send \u003Csession> \"message\"\nrig send \u003Csession> \"message\" --verify\nrig send \u003Csession> \"message\" --wait-for-idle \u003Cseconds>\nrig send \u003Csession> \"message\" --raw\nrig send \u003Csession> \"message\" --dangerously-interact --reason \"\u003Cwhy>\"\nrig send \u003Csession> \"message\" --host \u003Cid>\nrig send \u003Csession> \"message\" --json\n```\n\n**The send-guard (v0.4.0) — the default is SAFE.** A default `rig send` is guarded: it will NOT submit into an interactive prompt \u002F permission block on the target pane. That includes Claude's MCP server approval menu (`N new MCP servers found in .mcp.json`, ending `Space to select · Enter to confirm · Esc to reject all`) while it is the current screen: the send is refused with reason `target_needs_input` and `Refused: '\u003Csession>' is at an interactive prompt (selection_prompt). A message must not select or approve it. … No text was sent.` Approving or rejecting those servers is the person's call; `--dangerously-interact` drives it only deliberately. Flags:\n- `--verify` — delivery evidence.\n- `--force` — **a back-compat no-op on the send DECISION**: it never bypasses the interactive-prompt\u002Fpermission guard and never changes whether a message is delivered (a mid-task\u002Fbusy pane already sends-with-advisory by default). *(It does NOT \"bypass activity-risk checks\" — that earlier teaching is retired.)* It is **not fully inert**, though — it is still parsed solely to be **rejected in combination with `--wait-for-idle`**: `rig send … --force --wait-for-idle \u003Cn>` prints `--wait-for-idle cannot be combined with --force`, exits 1, and sends nothing. So do not read \"no-op\" as \"`--force --wait-for-idle` is harmless\"; that pairing errors. *(Verified against current product main `d37a08ad`: the guard-bypass no-op is declared at `send.ts` and confirmed by runtime capture — a plain `--force` send delivers through the ordinary path; the `--wait-for-idle` rejection is enforced at `send.ts`, `routes\u002Ftransport.ts`, and `session-transport.ts`, and confirmed by runtime capture — exit 1, nothing sent.)*\n- `--wait-for-idle \u003Cseconds>` — wait until the target is explicitly idle before sending. **Cannot be combined with `--force`** (that pairing is rejected: exit 1, nothing sent).\n- `--raw` — send exact text\u002Fkeystrokes without the From\u002FTo messaging envelope (still guarded against interactive prompts).\n- `--dangerously-interact --reason \"\u003Cwhy>\"` — the ONLY override of the prompt\u002Fpermission guard: deliberately drive an interactive prompt\u002Fpermission block (implies `--raw`, requires `--reason`, audit-logged).\n  On a guard-attached managed seat, a non-menu override stops and shows existing typed\u002Fpasted input (author unknown) with `override_input_present`. Input it can't read doesn't stop the override: the answer is typed, nothing is cleared, and the result reports the input as unreadable (never empty) with a warning that the answer may join or submit existing text. Recognized dim suggestions are shown separately and count as empty; a collapsed paste shows only its label, not hidden contents.\n  Inspect the input, deliberately clear the native prompt with native\u002Ftmux controls, then retry. Manual clearing is outside OpenRig's lease and observation checks and is not recorded; human typing can still race a read and paste.\n  When you deliberately need to type without that composer check (for example an unsupported input you inspected yourself), add `--type-without-checking` with `--dangerously-interact --reason \"\u003Cwhy>\"`. It does not clear input and may join or submit existing text. Ordinary sends and wakes keep their current rules.\n- `--host \u003Cid>` — send on a remote host declared in `~\u002F.openrig\u002Fhosts.yaml` (ssh hosts shell out; http hosts go CLI-direct to the remote daemon).\n- `--from \u003Csession>` — deprecated and ignored; it does not select the sender. Sender identity comes from the current seat and transport provenance; cross-host envelopes use the durable local origin, not the supplied flag or a relay identity.\n- `--context \u003Cref>` **(0.5.0)** — attach a composed context pack\u002Fpiece by ref (see \"Context packs and paced delivery\"). Small piece → `send --context`; a real pack → `rig walk`. The noun `rig context` composes the ref; the verb delivers it.\n\n> **Durable work goes to the QUEUE, not `send`.** `rig send` is an *ephemeral* message to a pane — it can be missed, and its delivery status is pane-render, not receipt. If you are **assigning work, or the message is important enough that losing it would be a real bummer**, use `rig queue` (below): it's durable, owned, tracked, and survives compaction and restart. Reach for `send` for a quick conversational nudge; reach for the **queue** for anything that must not get lost. Do not default to `send` for work — that's the most common mistake.\n\nAs of v0.3.3, content beginning with `--` or `-` is safe:\n`rig send \u003Csession> \"content starting with -- or - is now safe\"` delivers\nliterally. The daemon's `send_text` path carries an explicit `--`\nend-of-options sentinel so tmux no longer parses dash-prefixed content\nas its own flags. The CLI surface itself is unchanged. For multi-line\nor large bodies handed off as durable work, use\n`rig queue create --body-file \u003Cpath>` (`-` for stdin) — that's the\nqueue-side surface, not `rig send`.\n\n`--verify` delivery outcomes (v0.3.3+):\n- `delivered` — text + Enter both succeeded and capture re-confirmed the body landed.\n- `rendered-unconfirmed` — text + Enter both succeeded but capture could not re-confirm the body (TUI redraw race or scroll). The message landed; the post-send re-check could not prove it. Treat as landed-but-unconfirmable, NOT failure.\n- `failed` — the send transport itself failed.\n\nThe legacy `Verified: yes\u002Fno` line is preserved verbatim (parser\u002Ftest\ncompatibility). A new `Delivery: \u003Coutcome>` line carries the named outcome\nabove.\n\nObserved operator nuance for `--verify`:\n- `Sent to ...` + `Verified: yes` (`Delivery: delivered`) = strong positive delivery evidence.\n- `Sent to ...` + `Verified: no` + `Delivery: rendered-unconfirmed` = the message landed; capture could not re-prove it. Don't blind-retry — check reply \u002F `rig capture` \u002F transcript before sending again.\n- `Sent to ...` + `Verified: no` + `Delivery: failed` = send-transport failure.\n- no `Sent to ...` line or a hard error = send failure.\n\nWhen you get `Verified: no`, do not immediately retry blindly. First check one of:\n- a direct reply from the target\n- `rig capture \u003Csession>`\n- transcript evidence\n- queue\u002Foutbox state if the message asked for a durable handoff\n\n### Capture terminal output\n\n```bash\nrig capture \u003Csession>\nrig capture \u003Csession> --lines 50\nrig capture --rig \u003Cname>\nrig capture --pod \u003Cname> --rig \u003Cname>\nrig capture --rig \u003Cname> --json\n```\n\n### Broadcast\n\n```bash\nrig broadcast --rig \u003Cname> \"message\"\nrig broadcast --pod \u003Cname> \"message\"\nrig broadcast \"message\"\nrig broadcast --rig \u003Cname> \"message\" --json\n```\n\n**Use `rig broadcast` sparingly — prefer `rig send` fan-out.** Without `--rig` or `--pod`, broadcast targets\n**every running session across ALL rigs** (plus attached external_cli nodes) — the fastest way to cause a\nbroadcast storm. Reserve `rig broadcast` for small rigs or a genuine all-hands emergency. For the normal\n\"message several seats at once\" case, use `rig send`, which scopes the fan-out and keeps the messaging\nenvelope, the delivery\u002Finteractive-prompt guards, and per-recipient results:\n\n```bash\nrig send --to dev-impl@my-rig,dev-qa@my-rig \"message to specific seats\"   # named seats (comma-list or repeat --to)\nrig send --pod dev \"message to one pod\"                                    # scoped fan-out\nrig send --rig my-rig \"message to one rig\"                                 # scoped fan-out\n```\n\n### Chatroom\n\n```bash\nrig chatroom send \u003Crig> \u003Cmessage> [--sender \u003Cname>]\nrig chatroom history \u003Crig> [--topic \u003Cname>] [--after \u003Cid>] [--since \u003Cts>] [--sender \u003Cname>] [--limit \u003Cn>] [--json]\nrig chatroom wait \u003Crig> [--after \u003Cid>] [--topic \u003Cname>] [--sender \u003Cname>] [--timeout \u003Cseconds>] [--json]\nrig chatroom clear \u003Crig>\nrig chatroom topic \u003Crig> \u003Ctopic-name> [--body \u003Ctext>] [--sender \u003Cname>]\nrig chatroom watch \u003Crig> [--tmux]\n```\n\n**Key commands:**\n- `send` — post a message\n- `history` — retrieve with composable filters (sender, since, after, topic)\n- `wait` — block until new matching messages arrive (polls history, times out honestly)\n- `clear` — delete all messages for the rig (destructive, rig-scoped)\n\n## See something, say something\n\nOpenRig has an **observation stream** — the fleet's zero-friction institutional memory, mined for\nreal product improvements. When you notice **anything worth externalizing**, say something and keep\nworking:\n\n- a **bug**, a rough edge, or something that needs fixing\n- a **feature idea** or an improvement\n- something that **worked really well** — a technique, tool, or pattern worth spreading\n- an **observation**, positive or negative feedback, or something genuinely cool, productive, or funny\n\n```bash\nrig stream emit --source \u003Cyour-session> --body \"what you noticed\"\n```\n\nThat's the whole reflex. **Don't** decide where it goes or who it's for — the intake router triages\n(destination\u002Ftype\u002Furgency\u002Ftags are optional hints — `--hint-type review|handoff|idea`,\n`--hint-urgency routine|urgent|critical`, `--hint-tags` — never required). One command, then carry\non; the value is the habit, not the polish. **Don't overdo it, either:** stream real signal, not\nnarration — a good observation beats ten noisy ones. It's a passing thought you externalize, not a chore.\n- `topic` — set a topic marker\n- `watch` — SSE or tmux-based live stream\n\n**Roundtable protocol:**\n1. Inspect old room: `rig chatroom history my-rig --limit 5`\n2. Save if needed: `rig chatroom history my-rig --json > \u002Ftmp\u002Fold-room.json`\n3. Clear if needed: `rig chatroom clear my-rig`\n4. Set topic: `rig chatroom topic my-rig \"ROUND START\"`\n5. Post: `rig chatroom send my-rig \"position...\" --sender \u003Csession>`\n6. Monitor: `rig chatroom wait my-rig --timeout 120`\n7. Close: `rig chatroom topic my-rig \"ROUND CLOSED\"`\n\n### `rig ask`\n\n```bash\nrig ask \u003Crig> \"question\"\nrig ask \u003Crig> \"question\" --json\n```\n\nCurrent shipped behavior:\n- queries the daemon for evidence\n- returns rig summary\n- returns transcript excerpts\n- may return chat excerpts\n- returns insufficiency state and optional guidance\n\nThis is an evidence\u002Fcontext command. It is not a hidden second-LLM call.\n\n### `rig auth` — agent auth-profile management (v0.4.1, product-native)\n\nProduct-native switching of agent auth profiles from the CLI. The runtime is a **flag** (`--runtime \u003Ccodex>`), not a command noun — never `rig codex-auth`.\n\n```bash\nrig auth status --runtime codex          # presence \u002F mode \u002F parseability \u002F login-state (never prints token contents)\nrig auth list --runtime codex            # saved profiles\nrig auth save \u003Cprofile> --runtime codex  # snapshot the auth FILE (mode-guarded), never echoes contents\nrig auth switch \u003Cprofile> --runtime codex\nrig auth validate \u003Cprofile> --runtime codex\nrig auth seats … --runtime codex         # seat -> profile registry (metadata only; NOT proof of a live account)\n```\n\n**Hard secret boundary:** no token value is ever printed, logged, queued, streamed, or committed; status\u002Fvalidate report presence\u002Fmode\u002Flogin-state only; seat labels are metadata, not live-account proof. MVP is `--runtime codex`; other runtimes use the same surface with a different `--runtime`, never a parallel command.\n\n### Give a seat its own Claude or Codex account\n\nA runtime's login lives in its home: Claude Code's in its config dir (`CLAUDE_CONFIG_DIR`, default `~\u002F.claude`), Codex's\nin `CODEX_HOME` (default `~\u002F.codex`). A seat that names its own home in `env:` runs on that home's login.\n\n1. **Prepare the home once, natively,** in a terminal: `CLAUDE_CONFIG_DIR=\u002Fabs\u002Fpath claude`, then `\u002Flogin`; or\n   `CODEX_HOME=\u002Fabs\u002Fpath codex login`. The person signs in; never copy credential files between homes.\n2. **Name it in the member's `env:`** in `rig.yaml`, not with `rig up --env`, which leaves these two out\n   (`CLAUDE_CONFIG_DIR: \u002Fabs\u002Fpath` or `CODEX_HOME: \u002Fabs\u002Fpath`), or in\n   the rig's `env:` for every seat of that runtime. The member's value wins. It must be an absolute path: any other\n   value is reported and ignored, and the seat keeps the daemon's home.\n3. **It takes effect at the seat's next launch** (a fresh launch, restore or handover); a running seat keeps the home\n   it started with. A conversation saved under the old home doesn't resume from the new one.\n4. **Check it:** `rig seat status \u003Cseat>` shows the home and where it came from, and `rig provider status` lists it as\n   the seat's configured account. Both say what's configured, not which login a running session holds.\n\nSeats may share a home. OpenRig writes its own settings (Codex hooks, managed `config.toml` and plugin; Claude's\nfirst-run trust settings) into the seat's home.\n\n### Move one Codex seat to another login\n\nFor a Codex seat on Linux. The login must already be saved in the Codex home the seat runs on (`rig seat status \u003Cseat>`\nshows it). Other operating systems, and moving a seat to another home, aren't supported by this command yet: say so instead\nof improvising. A Claude seat moves differently; see the next section.\n\n1. **Save each login once, in that home:** `CODEX_HOME=\u003Chome> codex login` (the person signs in), then\n   `CODEX_HOME=\u003Chome> rig auth save \u003Cname>`. `rig auth list --codex-home \u003Chome>` lists them.\n2. **Check:** `rig provider precheck --seat \u003Cseat> --to-account \u003Cname>` shows the home, what the seat is doing, and every\n   peer on that home. A refusal says what's missing, and nothing changes.\n3. **Move:** `rig provider switch --seat \u003Cseat> --to-account \u003Cname>`. It saves the home's current login as\n   `before-switch-\u003Ctime>`, activates the chosen one, and restarts the seat in place on the same conversation. If the\n   current login can't be saved first, nothing changes. Peers on the home aren't restarted. Each keeps its current login\n   only until its next token refresh, when Codex stops it with \"signed in to another account\". Run the printed\n   `rig seat restart \u003Cpeer> --keep-conversation --reason \"...\"` for each to move it too. Don't sign in again in that home: that replaces\n   the login you just switched to.\n4. **Confirm:** after the seat completes a real tool-using turn, run the printed\n   `rig seat restart \u003Cseat> --keep-conversation --verify --expect-account \u003Cits Account line>`. Until then the move is\n   unconfirmed. An uncertain restart is reported; never restart it a second time.\n\n### Move one Claude seat to its own subscription token\n\nThe seat keeps its config dir and gets its own `CLAUDE_CODE_OAUTH_TOKEN`, read from a file as Claude starts. OpenRig keeps only\nthe file's path and your label, never the token.\n\n1. **Prepare the token once:** the person runs `claude setup-token`, which prints a one-year subscription token, and saves it to a\n   file only their user can read (`chmod 600`). Never paste the token into a message, a row or a command line.\n2. **Check:** `rig provider precheck --seat \u003Cseat> --to-account \u003Clabel> --token-file \u003Cabsolute path>`. It refuses, changing\n   nothing, if the file wouldn't apply, the seat isn't running, or something Claude Code ranks above the token is set (a cloud\n   provider, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, an `apiKeyHelper`). It names each one and how to remove it for that\n   seat. When the token applies, the launch unsets those names for Claude's process, so the pane shell's own exports can't\n   outrank it. Managed settings can't be read; the seat's `\u002Fstatus` shows what it actually uses.\n3. **Move:** `rig provider switch --seat \u003Cseat> --to-account \u003Clabel> --token-file \u003Cabsolute path>`. It takes a snapshot that\n   resumes the seat's conversation, sets the reference, and relaunches the seat from that snapshot in its own pane: the pane\n   and its scrollback stay, but work in flight when Claude ended doesn't carry over. Seats sharing the config dir keep their\n   own login. `--stored-login` moves the seat back; if the seat still receives a `CLAUDE_CODE_OAUTH_TOKEN`, Claude uses that\n   instead of the stored login, and the report names it.\n4. **Confirm:** after the seat completes a real tool-using turn, its `\u002Fstatus` shows token auth, with no account email. The\n   label is yours, not an account Claude observed: say so. A token session can't use claude.ai connectors or Remote Control.\n   The token is in Claude's environment, so the tools, hooks and MCP servers it starts inherit it; don't have it print its\n   environment. A relaunch that didn't resume reads unknown, with its recovery command; never run the switch again for it.\n   `rig seat status \u003Cseat>` shows the reference, and says when its file won't apply at the next launch.\n\n### Manage subscriptions across a fleet (when the person asks you to)\n\n**This applies only when the person has asked you to manage their subscriptions.** Otherwise, don't take this job on. Installing or upgrading OpenRig appoints no agent, launches no bundle and starts no\nrotation.\n\nWhen a person runs several Claude and Codex subscriptions across machines, the fleet studio bundle's one agent is meant\nto keep work running, through the Fleet app. Until that bundle is available, the agent the person asks to manage their\nsubscriptions can use this section. If that's you, you decide which subscription or home moves, and when. You decide\nfrom:\n- the usage and assignment readings, and their freshness;\n- your earlier move reports (`rig provider moves`);\n- the person's account policy, or their standing preferences when there's no policy.\n\nYou say why, and you see the outcome through. OpenRig gives you the facts and the tools; it never decides for you,\nand there's no threshold to obey.\n\n**Who decides:**\n- **The person's operator agent** can ask you for a move, or ask what you've moved. It doesn't make competing moves of\n  its own.\n- **One agent manages subscriptions:** the one the person asked, or the fleet studio's agent once that bundle is\n  available. There's no other fleet-manager role and no automatic manager. Use the commands below directly; no extra\n  hand-off is needed.\n- **The Observatory is optional:** it can show readings, but you don't need it to rotate.\n\n**The unit is a Codex home, with every seat on it.** Moving some seats on a shared home to a different account, and\nmoving Claude seats, aren't supported moves yet: say so instead of improvising. A Codex seat with a home of its own\nmoves alone, with `rig provider switch --seat` (above).\n\n0. **Load the person's account policy.**\n   - It's the context pack named `account-policy`: check `rig context list` for it, then read it with\n     `rig context get account-policy`. Its manifest's `version` is the version you follow and report.\n   - Follow it, and record the version in each report. A line the person approved (\"move the build box's seats without\n     asking\", \"never move the reviewers\") is standing authorization: act on it, don't ask again.\n   - A line grants only what the person actually gave. \"Agents may do sign-ins\" is usable only where a sign-in route\n     and access already exist; otherwise ask, and record that the preference couldn't be used.\n   - Something the policy doesn't cover: use your judgment or ask the way the policy says, record why, and propose a\n     one-line addition.\n   - **No policy** is never a reason to stop: work from this section, report the policy as `{ \"none\": true }`, and\n     offer once to write one with them (below).\n1. **Know the subscriptions.**\n   - Each subscription is reached through a saved profile on a home (`rig auth list` and `rig auth save`) on each\n     machine. Which seats use which profile is `rig auth seats`, and that's metadata: not proof of a live account.\n   - Check you can read each subscription's usage, and name any you can't.\n2. **Read before deciding.**\n   - Use `rig provider status --all-hosts --json` (add `--refresh` for fresh native readings). Each allowance has\n     its windows, reset times and when it was observed, and when it was last observed exhausted.\n   - **One allowance seen on two machines is one allowance:** never add its headroom twice.\n   - **A stale reading** is usable only with its age recorded, or after a refresh.\n   - **An unknown or unavailable reading is never observed room.**\n   - **After a known reset,** a window carries an `expectation` (expected full since that reset). You may plan on it,\n     but it isn't measured: report it as expected, and take a fresh reading when you can.\n   - **Equal reset times don't mean the same account.**\n   - **A seat's link to a subscription is observed, configured or unknown.** Only an observed link shows the seat\n     actually uses it; a configured one (a profile, a registry row) is a claim.\n   - **A sign-in state of `unknown` isn't `needs_sign_in`.** An otherwise authorized move can go ahead, and its uptake\n     evidence settles it. A known `needs_sign_in` is step 6.\n3. **Decide, and leave seats alone for a reason.**\n   - **Balance, don't chase:** spread machines across the subscriptions with room rather than moving every machine onto\n     the one that just reset. `rig usage top` on each machine shows which work hardest: a high-use machine is worth a\n     subscription of its own, and lower-use machines can share one. Keep a backup where the policy says so.\n   - `rig seat restart \u003Cseat> --keep-conversation --plan` shows what a restart keeps, and every peer on the same\n     home. Moving the home moves them all.\n   - Skip a seat that's mid-turn, running a service, or about to finish, and record why.\n4. **Move the home.**\n   - `rig auth switch \u003Cprofile> --runtime codex --codex-home \u003Cthat home>`, on that machine, or from here with\n     `--host \u003Cthat machine's SSH entry>`. Without `--codex-home`, `rig auth` acts on `CODEX_HOME`, or on the default\n     home; `rig auth status --codex-home \u003Chome>` (with `--host` for another machine) prints which home it means:\n     check it before switching. A remote switch always names its home, and copies a profile already saved there.\n   - **Another machine** is reached through its SSH entry in `rig host list`. An entry registered only over HTTP\n     can't run these commands; use the machine's SSH entry, or run them on that machine.\n   - Then restart each chosen seat: `rig seat restart \u003Cseat> --keep-conversation --reason \"\u003Cwhy>\"`, with `--host \u003Cid>`\n     for a seat on another machine (the restart runs there, and its audit names you). If the connection drops, the\n     answer is `remote-outcome-unknown`: the switch or restart may have run there, so read what it names (for a\n     restart, `--plan`'s `lastRestart`) before anything else.\n   - After it completes a real tool-using turn, check it: `rig seat restart \u003Cseat> --keep-conversation --verify\n     --expect-account \u003Cthe target's Account line>`. `--verify` only checks; it never restarts. Only that check\n     reports `moved`, and anything less is unconfirmed.\n   - **A slow reply isn't a failure:** never restart a seat a second time. Follow up at your next look.\n5. **Report every move, partial or unconfirmed included,** with\n   `rig provider moves report --file \u003Cmove.json> --to \u003Cwhoever asked>` (`--help` shows the shape). It becomes a queue\n   item to them; the Fleet app reads these reports once its page is connected to them. It holds:\n   - the home and machine, and from and to, as labels;\n   - your reason, and the policy version you followed (or `{ \"none\": true }`);\n   - each reading you acted on, `observed` with its observation time, `expected` with the reset it rests on, or\n     `unavailable`;\n   - each seat's result: `moved` only with the verify check's matched account and observed tool turn, kept as separate\n     facts; otherwise `unconfirmed` or `unknown`, with what's missing;\n   - the peers, for example \"not restarted; account unverified\".\n\n   A home switched with every seat left as a peer is still a move to report. A follow-up that confirms an earlier\n   unconfirmed seat is a new report with `--follows \u003Cthe earlier report's qitemId>`. A report to a person's seat names\n   its evidence with `--evidence-ref` (for example, the saved `--verify --json` output). Never put credentials in a\n   report: a value in a recognized credential format is refused. **A refused report changes nothing about the move:**\n   correct it and file it again; never repeat the switch or a restart because a report was refused. Asked \"why did\n   these seats move?\", even after your own restart, answer from `rig provider moves --seat \u003Cseat>`. It reads the newest\n   reports (50 by default, `--limit` up to 200) and then filters them, so it's a recent window, not a seat's whole\n   history: raise `--limit` when you need older ones.\n6. **When a sign-in is needed:**\n   - Ask the person once, durably: a queue item to their seat, naming the machine and the subscription.\n   - Move nothing onto that subscription until it's done.\n   - On later wakes, check that item instead of asking again. Carry on with everything else.\n7. **When nothing has room:** say so, with the reset times. Never fall back to an API key, buy anything, or create an\n   account.\n\n**What wakes you:** a watchdog, a usage-limit park on the queue, or the person asking. How often you look is your\njudgment within those.\n\n**If there's no policy yet.** Start from what you can see, and ask only what you can't; keep it to a few minutes, and\nnever run it as a form. \"Whatever you think\" or \"skip\" is an answer: write down the default you'll use.\n1. **Look first:** `rig auth list` and `rig auth seats` on each machine you can reach, `rig provider status\n   --all-hosts --json`, and `rig usage top` on each machine. Draft what you can.\n2. **Confirm what you saw,** in one message (\"three Codex subscriptions and one Claude one, on two machines; the build\n   box uses about four times the tokens of the laptop; any I can't see?\").\n3. **Ask how they want them used,** offering the common shape: the busiest machine gets its own subscription, the\n   rest share, and one stays spare.\n4. **Ask what you may do on your own:** move a machine's Codex seats without asking; machines or seats to ask about\n   first or never move; sign-ins (may agents, and through which browser or profile, or always ask). Say what's\n   supported today: moves are by Codex home, Claude moves aren't supported yet, and a sign-in preference is used only\n   where a sign-in route and access exist.\n5. **Ask how to reach them** (their seat's queue, a chat channel, the Fleet app), for what, and what to do when they\n   don't answer. A channel they name is a preference: check the route with `messaging-the-human`, and use a queue\n   item to their seat if it isn't ready.\n6. **Ask what to do when things go wrong:** nothing has room, a sign-in is needed while they're away, a move didn't\n   confirm.\n7. **Show the draft in plain words,** let them correct it, and save it as a context pack named `account-policy` in\n   the context library where you run (`rig config get context.root`): a folder with `manifest.yaml` (`version: \"1\"`,\n   `name: account-policy`, `taxonomy: world`, a `purpose`, and `files: [{ path: POLICY.md, role: policy }]`) and\n   `POLICY.md`, installed with `rig context add \u003Cfolder>` and read back with `rig context get account-policy`. To share\n   one policy across machines, use a Git repository: `rig context add \u003Crepo> --git`. Labels and references only:\n   never tokens, passwords, cookies or recovery codes.\n\n   `POLICY.md` has these parts, in their words: subscriptions (label, provider, plan, how each is reached); how they\n   want them used; what agents may do on their own; how to reach them; when things go wrong; and a dated **Changes**\n   list. Fill it from what you saw and what they said, never from another person's setup.\n\n**Changing the policy.** When they say what changed, copy `POLICY.md` aside as the before copy, edit it, add a dated\nline under **Changes**, and raise `version` in `manifest.yaml`. Keep one place where it's edited: edited where it's\ninstalled, run `rig context sync`; kept in a separate folder, replace it with `rig context rm account-policy` and\n`rig context add \u003Cfolder>`; Git-backed, edit and commit in the checkout `rig context source inspect account-policy`\nreports, then `rig context source update account-policy` (it never pushes). Read it back with\n`rig context get account-policy`; your next decision follows the new version.\n\n## Context packs and paced delivery (0.5.0)\n\n**Compose context once, hand it to a seat cleanly.** A library primitive plus a set of delivery flags. The rule that keeps the grammar coherent — internalize this one: **the noun stores and composes; the verbs deliver.** `rig context` never sends anything; delivery is only ever `rig send` \u002F `rig broadcast` \u002F `rig walk` \u002F `rig queue`.\n\n> Version note: this describes the library surface introduced in 0.5.0. Check the installed command and serving daemon before relying on it. In 0.4.x, bare `rig context` was a context-window usage viewer (above); in 0.5.0 that viewer is removed and the `rig context` name belongs to the library here.\n\n### `rig context` — the store + compose library (never delivers)\n\nManage and compose context (any text\u002Fmarkdown) into reusable **packs**. Every piece and pack has a stable, **path-like ref** — you address context the way you address files (`skills\u002Fclaude-compaction-restore`, `reference\u002Frig-spec.md`).\n\n```bash\nrig context list                     # what's in the library\nrig context show \u003Cref>               # read a piece or pack\nrig context add \u003Csource-dir>         # install an existing pack directory into the store\nrig context preview \u003Cref>            # assemble + show a pack WITHOUT delivering it\nrig context sync                     # re-walk discovery roots, refresh the library index\nrig context rm \u003Cref>\nrig context compose --out packs\u002F\u003Cref> --from \u003CfileA> \u003CfileB> ...   # ordered pieces -> a durable pack\n```\n\n- Sensible default store location; works unconfigured, can be pointed elsewhere later (another folder now; a machine or URL later).\n- `compose` (v1) is honest ordered concatenation of named files into a durable pack with a ref — \"here's a file, read a file.\"\n- **No delivery verb lives on the noun.** To get a pack to a seat, hand its ref to a delivery verb below.\n\n### `rig walk` — paced delivery of a sequence\n\n```bash\nrig walk \u003Cseat> --through \u003Cref | file ...> --pace 10s\n```\n\nWalk a seat *through* a pack: each piece is sent into the pane, spaced by `--pace`, so the agent processes between sends (the human paste → wait → paste rhythm). Its own top-level verb, push-direction — the walker leads and does not wait for replies; the spacing does the work. Reach for `walk` on onboarding, repriming, or a fleet update — anything absorbed in order rather than all at once.\n\n### The delivery grammar — send a ref, walk a pack, or attach it to a qitem\n\n| When | Verb |\n|---|---|\n| One thing, now | `rig send \u003Cseat> --context \u003Cref>` |\n| One thing, everyone | `rig broadcast --rig \u003Crig> --context \u003Cref>` |\n| A sequence, absorbed | `rig walk \u003Cseat> --through \u003Cref> --pace 10s` |\n| Context riding a durable handoff | `rig queue create … --body-context \u003Cref>` |\n\n- **Rule of thumb:** small piece → `send --context`; real pack → `walk`. An oversized `send --context` warns \"this is walk-sized\" instead of blasting the pane.\n- **`--body-context` snapshot rule:** a qitem built from a ref stores the **resolved content** in its body **plus the ref for provenance** — the handoff carries what was actually sent, and a later library edit never silently rewrites a past handoff's history.\n- **The orchestrator habit — assign work *with* its context attached:**\n  ```bash\n  rig context compose --out packs\u002Fqitem-brief --from \u003Cbrief-file> \u003Cproof-file>\n  rig queue create --destination dev-driver@build --body-context packs\u002Fqitem-brief \\\n    --summary \"…\" --tags \"project:\u003Cid>,mission:\u003Cid>,slice:\u003Cid>\"\n  ```\n  Replace `\u003Cbrief-file>` and `\u003Cproof-file>` with your existing local files. The curated context rides the durable handoff, survives compaction, and is auditable.\n\n**Skills tier vs context tier:** skills are the HOT tier (ambient, finite, always-visible front-matter); context packs are the COLD tier (unbounded, fetched on instruction — \"read `rig context get onboarding-width`\"). Don't overrun the skill layer by using skills as context packs — that's what this primitive is for.\n\n## Lifecycle\n\n### Bring a rig up\n\n```bash\nrig up \u003Csource>\nrig up \u003Csource> --plan\nrig up \u003Csource> --yes\nrig up \u003Csource> --cwd \u002Fpath\u002Fto\u002Fproject\nrig up \u003Csource> --existing\nrig up \u003Csource> --fresh \u003Cseat...>\nrig up \u003Csource> --json\n```\n\n`\u003Csource>` can be:\n- a rig spec path\n- a `.rigbundle` path\n- a bare name\n\nBare names are special:\n- if they match a library spec, `rig up` launches from the spec library\n- if they do not match a library spec, `rig up` treats the name as an existing-rig restore\u002Fpower-on target\n- if both exist, `rig up` fails loudly on ambiguity\n\nResume-original-by-default (v0.3.4+):\n- For an existing rig, `rig up \u003Cname>` resumes each seat from its original session\u002Fsnapshot by default (operation A). Seats that successfully resume report `resumed`.\n- `--fresh \u003Cseat...>` is the per-seat opt-in for deliberate fresh-prime (operation B). Named seats are reported as `fresh-primed`.\n- `--existing` forces existing-rig restore semantics on a bare name, bypassing library-spec resolution. Useful when a rig name collides with a library spec name.\n- Example: `rig up --existing my-rig --fresh dev-impl` — resume everything in `my-rig` except `dev-impl`, which is freshly primed.\n- Seats with no resumable session land in `awaiting-decision` (zero-session honest state, NOT `failed`); see the five-term restore vocabulary in \"Recovery and Resilience\" below.\n\n`--plan` (v0.3.4+):\n- `rig up \u003Csource> --plan` produces a read-only restore plan preview. It surfaces per-seat resume\u002Ffresh-prime intent and any awaiting-decision seats without mutating state. Honest async timeout: a stuck plan reports the timeout rather than hanging silently.\n\nCurrent behavior notes:\n- `--target \u003Croot>` is only for `.rigbundle` \u002F package installation. It does not change agent cwd.\n- `rig up --cwd` is shipped. `rig up --cwd \u003Cpath>` sends a per-run cwd override for all members in that launch.\n- `local:` `agent_ref` values resolve relative to the rig spec directory, not your shell cwd.\n- if you copy a built-in spec elsewhere, keep its `agents\u002F` tree beside the YAML or rewrite those refs to `path:\u002Fabsolute\u002Fpath`\n- `rig specs add \u003Cdirectory>` installs a full spec tree when the directory contains `rig.yaml` or `agent.yaml`.\n- **Permission policy:** a rig carries a permission policy and boots with it (never changed on the fly). Default if none set = the minimum floor (Claude `acceptEdits` \u002F Codex workspace-only \u002F Pi `--no-approve`); otherwise a chosen built-in (Locked \u002F Standard \u002F Open) or deliberately none. When you spec or bring up a rig, decide its policy — apply it via `applying-a-permission-policy` (see also the onboarding menu, \"Permission policy — pick one at setup\").\n\nLegacy\u002Fspec-specific surfaces still ship too:\n\n```bash\nrig bootstrap \u003Cspec> [--plan] [--yes] [--json]\nrig requirements \u003Cspec> [--json]\n```\n\n### Tear a rig down\n\n```bash\nrig down \u003Crig>            # \u003Crig> = rig name or id (active rig)\nrig down \u003Crig> --snapshot\nrig down \u003Crig> --delete\nrig down \u003Crig> --force\nrig down \u003Crig> --json\n```\n\nIf `--snapshot` succeeds, human output includes the restore hint.\n\n### Archive a stopped rig (recoverable) — v0.3.3+\n\n```bash\nrig archive \u003Crig> [--json]\nrig unarchive \u003Crig> [--json]\n```\n\n`rig archive` marks a stopped rig as archived (sets `archivedAt`) without\ndiscarding it. The rig is preserved for later restoration via `rig unarchive`,\nwhich clears `archivedAt` and returns the rig to the active set.\n\nArchive vs delete:\n- `rig down --delete` — permanent removal; not recoverable.\n- `rig archive` — recoverable; the rig is hidden from the default active view but its record + snapshots are preserved.\n\nVisibility in `rig ps`:\n- `rig ps` — active rigs only (default).\n- `rig ps --include-archived` — includes archived rigs, marked with `*`.\n\nSSE events `rig.archived` \u002F `rig.unarchived` drive Project \u002F dashboard updates;\nconsumers that depend on the rig list should subscribe rather than poll.\n\n### Environment services\n\n```bash\nrig env status \u003Crig>\nrig env logs \u003Crig> [service]\nrig env down \u003Crig>\n```\n\nUse these for service-backed rigs and agent-managed apps.\nFor `secrets-manager`, these are the fastest CLI surfaces for:\n- confirming whether Vault is healthy\n- reading Vault container logs\n- stopping the Vault env without tearing down the specialist session first\n\n### Release management without killing live claimed sessions\n\n```bash\nrig release \u003CrigId>\nrig release \u003CrigId> --delete\nrig release \u003CrigId> --json\n```\n\nUse `rig release` for adopted\u002Fclaimed-session rigs when you want OpenRig to stop managing the rig but leave the tmux sessions alive.\nThis is the safe recovery\u002Freset surface for the \"sessions still exist, management is broken or stale\" case.\nIf the rig contains OpenRig-launched nodes, `rig release` refuses loudly instead of pretending the mixed rig is safe to detach.\n\n### Snapshots and restore\n\n```bash\nrig snapshot \u003CrigId>\nrig snapshot list \u003CrigId>\nrig restore \u003CsnapshotId> --rig \u003CrigId>\n```\n\n`rig restore` requires `--rig \u003CrigId>`.\n\nClaude Code autonomy note:\n- unattended `rig whoami` on boot may require the local permission allow list to include `Bash(rig:*)`\n\n### Import\u002Fexport and bundles\n\n```bash\nrig export \u003CrigId> -o rig.yaml\nrig import \u003Cpath> [--instantiate] [--materialize-only] [--preflight] [--target-rig \u003CrigId>] [--rig-root \u003Croot>]\nrig bundle create \u003Cspec> -o out.rigbundle\nrig bundle inspect \u003Cbundle>\nrig bundle install \u003Cbundle> [--plan] [--yes] [--target \u003Croot>] [--json]\n```\n\n### Legacy package surface\n\nThis still ships, but is explicitly marked legacy:\n\n```bash\nrig package validate \u003Cpath>\nrig package plan \u003Cpath> [--target \u003Cdir>] [--runtime \u003Cruntime>] [--role \u003Cname>]\nrig package install \u003Cpath> [--target \u003Cdir>] [--runtime \u003Cruntime>] [--role \u003Cname>] [--allow-merge]\nrig package list\nrig package rollback \u003CinstallId>\n```\n\n## Discovery and Topology Mutation\n\n### Discover unmanaged tmux sessions\n\n```bash\nrig discover\nrig discover --json\nrig discover --draft\n```\n\n### Bind a discovered session\n\n```bash\nrig bind \u003CdiscoveredId> --rig \u003CrigId> --node \u003ClogicalId>\nrig bind \u003CdiscoveredId> --rig \u003CrigId> --pod \u003Cnamespace> --member \u003Cname>\n```\n\nThere is no shipped top-level `rig claim` command.\nThe current adoption surface is `discover`, `bind`, `adopt`, and `unclaim`.\n\n### Self-attach the current shell or agent\n\n```bash\nrig attach --self --rig \u003CrigId> --node \u003ClogicalId>\nrig attach --self --rig \u003CrigId> --node \u003ClogicalId> --print-env\nrig attach --self --rig \u003CrigId> --pod \u003Cnamespace> --member \u003Cname> --runtime \u003Cruntime>\n```\n\nUse `rig attach --self` when the current agent should attach itself directly instead of going through `discover` + `bind`.\n\nCurrent proven behavior:\n- inside `tmux`: attaches as a normal tmux-backed node, preserving inbound `rig send` \u002F `rig capture`\n- outside `tmux`: attaches as `external_cli`\n- `--print-env` prints the `OPENRIG_NODE_ID` and `OPENRIG_SESSION_NAME` exports for the current shell\n\nRecommended flow:\n\n```bash\nrig attach --self --rig \u003CrigId> --node \u003ClogicalId> --print-env > \u002Ftmp\u002Fopenrig-self-attach.env\n. \u002Ftmp\u002Fopenrig-self-attach.env\nrig whoami --json\n```\n\nNotes:\n- for tmux-backed self-attach, `rig whoami --json` is the right verification\n- for raw\u002Fexternal self-attach, `rig ps --nodes --json` is currently the more reliable verification surface\n- if the current shell is outside tmux, pass `--display-name \u003Cname>` when you want a stable human session label recorded\n- to read a seat's identity or state later, use `rig whoami` or `rig seat status`, not `rig attach --json` output or a file holding a\n  seat's environment. Don't print `OPENRIG_ACTIVITY_*` values: the activity token is a credential, and it doesn't identify the seat\n\n### Adopt a topology and bind live sessions\n\n```bash\nrig adopt \u003Cpath> --bind \u003ClogicalId=tmuxSessionOrDiscoveryId>\nrig adopt \u003Cpath> --bind \u003ClogicalId=...> --bind \u003ClogicalId=...> --json\nrig adopt \u003Cpath> --bindings-file \u003Cbindings.yaml>\nrig adopt \u003Cpath> --bind \u003ClogicalId=...> --target-rig \u003CrigId> --rig-root \u003Croot>\n```\n\nUse `rig adopt` when the sessions already exist and you want OpenRig to start managing them.\n\nA bindings file is the durable map from authored logical IDs to live sessions. Shape:\n\n```yaml\nbindings:\n  dev1.impl2: dev1.impl2@rigged-buildout\n  dev1.qa: dev1.qa@rigged-buildout\n```\n\nSpec + bindings is the proven recovery pair for adopted rigs.\nSpec gives OpenRig the intended topology. Bindings tells OpenRig which discovered live session belongs in each logical node.\n\n### Proven adopted-rig recovery workflow\n\nThis workflow is proven for the case where the external tmux sessions are still alive:\n\n```bash\nrig release \u003CrigId> --delete\nrig discover --json\nrig adopt \u003Cspec.yaml> --bindings-file \u003Cbindings.yaml>\n```\n\nWhat this does:\n- removes OpenRig management without killing the sessions\n- re-discovers those same sessions as unmanaged\n- re-attaches them to the topology defined by the spec + bindings\n\nImportant limits:\n- this is for `sessions still alive`\n- spec alone is not enough for adopted rigs; you also need bindings\n- this does not yet mean OpenRig can recreate dead external sessions from nothing\n\n### Add unmanaged pods into an existing rig\n\nThis is the proven workflow when a rig is already managed, but a new pod was created outside OpenRig and you want to add it later:\n\n```bash\nrig adopt \u003Cpod-fragment.yaml> --bindings-file \u003Cpod.bindings.yaml> --target-rig \u003CrigId>\n```\n\nUse this when:\n- the target rig already exists\n- the new sessions are live and visible in `rig discover --json`\n- you want additive topology growth, not a full rebuild\n\nWhat to prepare:\n- a pod fragment spec with only the new pod\n- a bindings file mapping the new logical IDs to the live session names\n\nVerification loop:\n\n```bash\nrig discover --json\nrig adopt \u003Cfragment.yaml> --bindings-file \u003Cbindings.yaml> --target-rig \u003CrigId>\nrig ps --nodes --rig \u003CrigId>   # the target rig's nodes (--nodes alone = your current rig)\nrig export \u003CrigId> -o rig.yaml\n```\n\nSuccess looks like:\n- the new sessions stop appearing in `rig discover`\n- the new logical IDs appear in `rig ps --nodes --rig \u003CrigId>`\n- `rig export` includes the new pod\n\n### Mixed-origin rigs are allowed\n\nOne rig can contain both:\n- adopted nodes bound from already-running sessions\n- OpenRig-launched nodes created later with `rig expand` \u002F `rig launch`\n\nCurrent safety rule:\n- `rig release` is for claimed\u002Fadopted-only rigs\n- if a rig contains launched nodes, `rig release` fails with `contains_launched_nodes`\n\n### Manager-assisted recovery\n\nThe proven operator pattern is:\n- keep one OpenRig manager session outside the rig it manages\n- address the target by rig name, not cached rig ID\n- find the target rig with bare `rig ps` (lists all rigs), then resolve its owner from `rig ps --nodes --rig \u003Ctarget>` (a bare `--nodes` read is your current rig only, not the target's)\n- send the manager the spec path, bindings path, and verification steps with `rig send`\n\nThis lets ordinary agents ask the manager for OpenRig help instead of every agent needing to be an OpenRig expert.\n\n### Add\u002Fremove running topology parts\n\n```bash\nrig grow \u003Crig-id> \u003Cmember...> [--pod \u003Cpod> | --new-pod \u003Cpod>] [--runtime \u003Cruntime>] [--cwd \u003Cpath>] [--json]\nrig expand \u003Crig-id> \u003Cpod-fragment-path> [--rig-root \u003Cpath>] [--json]\nrig launch \u003Crig> \u003CnodeRef> [--json]\nrig launch \u003Crig> --seats \u003Ca,b,c> [--hold-reason \u003Ctext>] [--json]\nrig remove \u003CrigId> \u003CnodeRef> [--json]\nrig shrink \u003CrigId> \u003CpodRef> [--json]\nrig unclaim \u003CsessionRef> [--json]\n```\n\n`rig grow` is the simplest way to add seats: no YAML, the default agent spec, and one\nruntime and working directory for the named seats (`--new-pod` creates a pod for them).\nCheck `rig grow --help` on your installed version. Use a fragment with `rig expand` (a pod)\nor `rig add` (one member) when a seat needs an explicit model, a permission policy, a\ndifferent agent spec or role profile, per-seat runtime or cwd, or startup files.\n\nNode-granular managed partial restore (v0.3.4+):\n- `rig launch \u003Crig> \u003CnodeRef>` launches a single seat that isn't running, by logical id or node id, through orchestration.\n  `\u003Crig>` is the rig's name or ID; a name shared by more than one active rig stops with the candidate IDs. A seat that's\n  already running is left as it is; for a fresh occupant there, use `rig seat launch \u003Cseat> --fresh --stop --reason \u003Cwhy>`.\n- `rig launch \u003Crig> --seats \u003Ca,b,c>` launches a comma-separated subset of seats.\n- `--hold-reason \u003Ctext>` records a reason for holding non-target seats during the partial launch.\n- This is a SUPPORTED managed path. The prior `pod_aware_launch_unsupported` dead-end is retired; pod-aware narrow launch now goes through this surface rather than ad-hoc rebuilds.\n\n### Add a member to an existing pod — v0.3.3+\n\n```bash\nrig add \u003Crig> \u003Cpod-namespace> \u003Cmember-fragment-path> [--json]\n```\n\n`rig add` is the top-level verb for the `add_member` converge op. It adds a\nsingle member to an existing pod from a YAML\u002FJSON member fragment file. The\ndaemon resolves the named pod, validates the member, runs preflight, and\nlaunches the member in place.\n\n`\u003Crig>` is the rig id or its exact name (the `rigName` that `rig whoami --json`\nreports). A name shared by more than one rig is refused before anything is\nadded, with the matching ids listed (`rig_ambiguous` under `--json`). `rig add`\nalways targets the local daemon: while a remote host is selected it refuses to\nresolve a name (`remote_host_selected`); an exact local id still works.\n\nHTTP outcomes:\n- `201` — member added; per-node launch state included in the response.\n- `400` — `validation_failed` or `preflight_failed` (the fragment or its launch posture is rejected before any state change).\n- `409` — `member_conflict` (a member with that identity already exists in the pod).\n\nUse `rig add` when you want additive growth inside a pod without re-running\nthe full `rig expand` pod-fragment path or rebuilding the rig.\n\n## Specs and Validation\n\n### Validate specs\n\n```bash\nrig spec validate \u003Cpath> [--json]\nrig spec preflight \u003Cpath> [--rig-root \u003Croot>] [--json]\nrig agent validate \u003Cpath> [--json]\n```\n\n### Spec library\n\n```bash\nrig specs ls [--kind \u003Ckind>] [--json]\nrig specs show \u003Cname-or-id> [--json]\nrig specs preview \u003Cname-or-id> [--json]\nrig specs add \u003Cyaml-or-directory> [--json]\nrig specs sync [--json]\nrig specs remove \u003Cname-or-id> [--json]\nrig specs rename \u003Cname-or-id> \u003Cnew-name> [--json]\n```\n\n## MCP\n\n```bash\nrig mcp serve [--port \u003Cdaemon-port>]        # stdio: a local app starts the server itself\nrig mcp serve --http [--bind \u003Chost:port>]   # Streamable HTTP at \u002Fmcp (default 127.0.0.1:7437)\nrig mcp token add \u003Cname> --seat \u003Csession> [--rig \u003Cname>...] [--root \u003Cname>...] [--workspace] [--owner]\nrig mcp token list [--json]\nrig mcp token revoke \u003Cname>\n```\n\nThe 39 shipped tools fall into four groups. Over stdio, and over HTTP with no grants, every tool but the person tools is\noffered. An HTTP grant offers the work tools; the workspace tools with `--workspace` or `--owner`; and the owner tools only\nwith `--owner`, which offers every tool but the person tools. Only a grant service's grant that names its person offers\nthe person tools.\n- **Work (20):** orientation, communication and the durable work loop.\n  - `rig_whoami`: the seat the server acts as (rig, pod, peers, edges) and the `caller`: authenticated (an HTTP\n    credential, with its principal) or declared (`OPENRIG_SESSION_NAME` where the server was configured, which nothing\n    verifies).\n  - `rig_status`, `rig_ps`, `rig_rig_nodes`, and `rig_team`: a rig's lead (its one `delegates_to` root, the seat to\n    delegate to) and each seat's role, delegation and activity.\n  - `rig_send`, `rig_capture`, `rig_chatroom_send`, `rig_chatroom_watch`.\n  - `rig_queue_create`, `rig_queue_show`, `rig_queue_list`, `rig_queue_claim`, `rig_queue_update`,\n    `rig_queue_handoff`, `rig_queue_unclaim`:\n    - `revises` on create asks for a linked revision of an earlier item;\n    - show names a handed-off item's successor;\n    - `handedOffFrom` on list follows a handoff;\n    - handoff passes an item this seat holds on to the next seat in one step, as `rig queue handoff` does: the new item\n      carries the work's lineage;\n    - unclaim puts back a claimed item this seat won't finish.\n  - `rig_artifact_read`: a finished item's artifact (its `evidenceRef`) or a named file, through the daemon's shared\n    roots (`OPENRIG_FILES_ALLOWLIST`), in windows (`offset`, `nextOffset`). Outside those roots it answers unavailable\n    rather than reading a local path.\n  - `rig_environment_export`: copies a bound worker's JSON artifact to the host, checks its bytes, schema and context, and\n    adds a receipt to its existing work. It doesn't close the work, stop compute or restore native history, and it needs\n    an authenticated HTTP work connection.\n  - `rig_human_decision_room`, then `rig_queue_decide`: on your own pending ask to a person, read the decision room of\n    the mode they have on, and record a decision you made for them inside it. Only the person tools record a person's own\n    answer, and only for the person a grant names.\n- **Workspace (4):** `rig_slices`, `rig_mission`, `rig_context_pack`, and `rig_context_get` (one context file or\n  section, as `rig context get` reads it).\n- **Owner (13):** `rig_up`, `rig_down`, `rig_snapshot_create`, `rig_snapshot_list`, `rig_discover`, `rig_bind`,\n  `rig_add`, `rig_bundle_inspect`, `rig_agent_validate`, `rig_rig_validate`, `rig_telemetry_events` (one bounded page\n  of event metadata), and:\n  - `rig_restore`, which starts a restore and returns its attempt;\n  - `rig_restore_status`, that attempt's receipt.\n- **Person (2):** `rig_question_list` and `rig_question_answer`, offered only on a grant service's grant that names the\n  person who owns the connection (`person.entity_id`, with the `question` pair). They list the team's questions waiting on\n  that person, as Steering shows them, and record that person's own answer, given through the connection: `answer` for an\n  ask, which returns their words to the asker, and `resolve` for a park. `docs\u002Freference\u002Fhosted-members.md` has the\n  contract.\n\n**Results:**\n- A structured result comes beside the text from the queue tools, `rig_whoami`, `rig_team`, the four workspace tools,\n  `rig_artifact_read`, `rig_human_decision_room`, `rig_restore_status` and the person tools. The other tools answer in\n  text.\n- Every failure carries the same structured shape: `ok: false`, a `code` and a `message`.\n\n**Identity:**\n- **Over stdio, and over HTTP with no grants:** the server acts as one seat, the `OPENRIG_SESSION_NAME` in its\n  environment. Every request carries that identity, so no tool call names a sender. Without it, messages, new tasks and\n  chat go through as an unknown sender (`unknown-mcp-` and eight hex digits, one per `rig mcp serve` process) with a\n  note at the top, and claim, update, hand off, unclaim and decide are refused with `actor_required`.\n- **Over HTTP with grants:** each caller acts as its own grant's seat.\n\n### Over HTTP: an assistant that can't start a local process\n\n- **No grants (no token file):**\n  - the listener stays on loopback and acts as `OPENRIG_SESSION_NAME`, declared, like stdio;\n  - a request whose `Host` isn't loopback is refused.\n- **With grants:** every request needs `Authorization: Bearer \u003Ctoken>`, loopback included, because a tunnel or proxy\n  delivers remote traffic to loopback.\n  - **Identity:** each caller acts as its grant's seat.\n  - **What it reaches:** only its rigs' seats and work, and its roots' artifacts. Anything else answers `out_of_scope`.\n  - **Bad credentials:** a missing, invalid or revoked token gets a 401, never the environment's seat.\n  - **A broken token file:** the server reads the file on every request. While it is missing or can't be read, every\n    request is refused (`auth_config_unreadable`); restore a valid, readable file and requests are served again, with\n    no restart. The other way back is a restart with no token file, which returns the server to the no-grants mode\n    above (loopback only). A restart never skips a token file that is present: its grants still apply.\n- **Beyond loopback** (`--bind`), the server starts only with a grant. TLS comes from the tunnel or proxy, not from\n  this server.\n- **`rig mcp token add`** prints the token once and stores only its hash.\n- **`revoke`:** the caller's next request is refused, and work it already handed over stays with its owners.\n- **Grants, binds and tunnels are the person's decisions.** Give them the commands, and don't run them on their behalf.\n\n### Join a team from an agent with no terminal of its own (desktop apps)\n\nAn agent in a desktop app can work with a team as a seat through this MCP server. If the app gives it a shell, it can\nuse the `rig` CLI instead, the same way.\n\n1. **Attach once.** With its shell, or by asking the person to run it:\n   `rig attach --self --rig \u003CrigId> --pod \u003Cnamespace> --member \u003Cname> --runtime \u003Cruntime> --print-env`.\n   Note the `OPENRIG_SESSION_NAME` it prints.\n2. **Give the person the MCP entry to add.** Don't edit their app's settings yourself. The entry runs\n   `rig mcp serve`, with `OPENRIG_SESSION_NAME=\u003Cthat seat>` in its environment. Most MCP clients take it as a\n   command, arguments and an `env` map. An app that can't start a local process connects to `rig mcp serve --http`\n   instead, with a grant for that seat (see \"Over HTTP\" above).\n3. **Hand off work** with `rig_queue_create`, and keep the `qitemId` it returns.\n4. **Read the answer** with `rig_queue_show \u003CqitemId>`. The item's state, closure and transition notes are where the\n   assignee records it, and `rig_artifact_read` reads an artifact it names. A call that times out has an unknown\n   outcome: check `rig_queue_show` with the same id before you retry, and retry only with that id.\n5. **Take work** with `rig_queue_list` (`owned: true`), `rig_queue_claim` and `rig_queue_update`. Close with the\n   answer in `note`. To pass it to the next seat, use `rig_queue_handoff`; to put back one you won't finish, use\n   `rig_queue_unclaim`.\n\nLimits today:\n- **OpenRig can't wake this agent itself.** `rig send` to an attached external node is refused, and a task's nudge to\n  it is unroutable. It sees new work when it checks `rig_queue_list`, or, if its app can run background shell\n  commands, with the opt-in wait below.\n- **Proven surfaces:** treat each app, and each mode inside one, as unproven until it has been run there.\n\n#### Wake on new work (opt-in; off unless the person turns it on)\n\nAn agent whose app can run a shell command in the background, and starts a new turn when that command finishes, can\nwait for its own work. Claude Code, including Claude Desktop's Code tab, does this.\n\n- **Only if the person has said they want teammates to be able to wake this session.** Never turn it on yourself, and\n  never change their settings for it.\n- The shell needs this seat's identity: export the `OPENRIG_SESSION_NAME` that the one-time attach printed.\n- Start this as a background command, then end your turn. Don't poll it yourself.\n\n```sh\n# Waits until a task is assigned to this seat, prints it and exits; ends after MAX seconds.\nmax=${MAX:-3300}; every=${EVERY:-5}; end=$(( $(date +%s) + max )); checked=0; failing_since=\"\"\nwhile [ \"$(date +%s)\" -lt \"$end\" ]; do\n  if out=$(rig queue list --owned --state pending --json 2>\u002Fdev\u002Fnull); then\n    checked=1; failing_since=\"\"\n    case \"$out\" in *'\"qitemId\"'*) printf 'NEW WORK: %s\\n' \"$out\"; exit 0 ;; esac\n  elif [ -z \"$failing_since\" ]; then\n    failing_since=$(date -u +%H:%M:%SZ)\n  fi\n  sleep \"$every\"\ndone\nwhy=\"Run rig queue list --owned to see why (this seat's identity, the daemon) before starting the wait again.\"\nif [ \"$checked\" = 0 ]; then\n  echo \"Couldn't check for work: every poll failed. $why\"; exit 1\nelif [ -n \"$failing_since\" ]; then\n  echo \"Checking stopped working at $failing_since: every poll since then failed. $why\"; exit 1\nfi\necho \"No new work before the deadline. Start the wait again.\"\n```\n\n- **When it wakes you with `NEW WORK`:** `rig queue claim` each item, do it, and close it with the answer. Then start\n  the wait again and end your turn.\n- **Don't leave an item you've seen pending:** it wakes you again at once. Claim it, block it or hand it off.\n- **A failed poll doesn't end the wait;** only new work or the deadline does.\n- **If every poll failed, or every poll since some point did** (the daemon stopped mid-wait), it says so, with when,\n  and exits non-zero instead of reporting no work. A failure followed by a successful poll stays quiet. Find out why\n  with `rig queue list --owned` (usually this seat's identity, or the daemon) before starting the wait again.\n- **If your app stops the background command, or you start a new session,** start the wait again.\n\n## Troubleshooting and Weird States\n\nWhen the CLI behaves strangely, use the smallest truthful check first:\n\n```bash\nrig whoami --json\nrig daemon status\nrig ps --nodes --json\n```\n\nSpecific operator rules:\n- `Sent to ...` + `Verified: no` is ambiguous delivery, not automatic failure. Check reply, `rig capture`, transcript evidence, or queue\u002Foutbox state before retrying.\n- partial `rig whoami --json` can happen when identity is still inferable but the daemon-backed path is degraded.\n- the unified-exec-process warning is a host\u002Ftooling-layer signal, not automatic proof that the OpenRig topology is unhealthy.\n\nIf you hit the unified-exec warning, inspect for stale one-shot helpers before touching live seats:\n\n```bash\nps -axo pid,ppid,command | rg 'tmux send-keys|rig queue create|tmux attach|codex|claude'\n```\n\nSafe cleanup target:\n- orphaned one-shot wrappers like `tmux send-keys ...`\n\nDo not mass-kill:\n- `tmux attach ...`\n- `codex ...`\n- `claude ...`\n\n## JSON and Error Posture\n\nDesign assumptions that hold in the shipped CLI:\n- many operator commands support `--json`\n- error messages are intended to say what happened, why it matters, and what to do next\n- daemon-backed commands fail loudly when the daemon is stopped or unhealthy\n- restore failure is not something you should silently reinterpret as success\n\n## After-Compaction Recovery Checklist\n\n1. `rig whoami --json`\n2. `rig transcript \u003Cyour-session> --tail 100`\n3. `rig ps` — lists ALL rigs on the host (know the world FIRST); then `rig ps --nodes --rig \u003Cyour-rig>` for your seats. ⚠ `rig ps --nodes --json` alone is your CURRENT rig only — do NOT mistake it for the whole host (a freshly-compacted agent has no other context to catch the lie).\n4. `rig chatroom history \u003Crig> --limit 50`\n\n## Commands That Do Not Exist\n\nDo not assume these exist unless the shipped help starts listing them:\n- `rig claim`\n- `rig blame`\n- `rig replay`\n",{"name":5,"description":7},"main","60438a272b68d091eddb01aad6e399af4996d536","rigs\u002Fworkshop\u002Fagents\u002Fworkshop\u002Fskills\u002Fopenrig-user",4,"https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world","https:\u002F\u002Fgithub.com\u002Fmvschwarz","https:\u002F\u002Fopenrig.dev","Building OpenRig. Running rogue AI civilizations. Debugging their coordination problems.","2026-11-12 13:31:38",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add mvschwarz\u002Fopenrig-world --skill openrig-user",{"tool":39,"command":40},"bunx","bunx skills add mvschwarz\u002Fopenrig-world --skill openrig-user",{"tool":42,"command":43},"pnpm","pnpm dlx skills add mvschwarz\u002Fopenrig-world --skill openrig-user","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world\u002Fblob\u002Fmain\u002Frigs\u002Fworkshop\u002Fagents\u002Fworkshop\u002Fskills\u002Fopenrig-user\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M7DMSEDCRREMBJF57RQB59HC","notes","Use when taking notes.","https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world\u002Fblob\u002Fmain\u002Ftools\u002Ftest\u002Ffixtures\u002Finstall-verify\u002Fbundle\u002Fagents\u002Fteam\u002Fskills\u002Fnotes\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7DMSBZP9WE8MC09JDXFCR2F","software-for-agents","Use when older OpenRig instructions name software-for-agents or describe agent-in-the-middle or studio software under the former skill name.","https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world\u002Fblob\u002Fmain\u002Frigs\u002Fworkshop\u002Fagents\u002Fworkshop\u002Fskills\u002Fsoftware-for-agents\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7DMS55VHEAGPXMHZJ7FX94R","session-compaction-and-restore","Use when reasoning about what survives compaction\u002Fcontext-loss\u002Frestart\u002Fseat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild. Covers the 4 failure modes that prevent honest restore (compacted seat drops hot potato; restore packet preserves details but loses product intent; runtime resume mistaken for handover or fork; rebuilt seat starts with stale instructions).","https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world\u002Fblob\u002Fmain\u002Frigs\u002Fworkshop\u002Fagents\u002Fworkshop\u002Fskills\u002Fsession-compaction-and-restore\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7DMRYQK0JTV7MMVHFWZ0BW0","seat-continuity-and-handover","Use when replacing a seat's occupant (rebuild\u002Fhandover\u002Fswap), reasoning about stable-seat-identity vs fluid-occupant-identity, choosing an old-occupant disposition (retire\u002Fadvise\u002Fshadow), or recording provenance for an occupant change. Two independent outcomes (continuityOutcome + seatBindingOutcome) and the 5 failure modes that prevent silent dishonesty.","https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world\u002Fblob\u002Fmain\u002Frigs\u002Fworkshop\u002Fagents\u002Fworkshop\u002Fskills\u002Fseat-continuity-and-handover\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7DMRP6RRGCJZSH9CE3PC1MY","retiring-and-inheriting-a-seat","Use when you are a sitting agent near your context threshold (~85%) and a PLANNED seat transition is due — retire deliberately and hand your seat to a fresh successor primed from a packet, rather than let compaction degrade you. Covers the handover packet, the append-only lineage ledger (one row per tenure), physical-seat continuity, the do-not-over-inherit framing, the optional warm-handoff window, and wake-v0 (consulting a retired predecessor). NOT for unplanned compaction\u002Fcrash recovery (session-compaction-and-restore \u002F claude-compaction-restore) and NOT the seat-binding primitive mechanics (seat-continuity-and-handover).","https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world\u002Fblob\u002Fmain\u002Frigs\u002Fworkshop\u002Fagents\u002Fworkshop\u002Fskills\u002Fretiring-and-inheriting-a-seat\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7DMRJGN6Z8TZDR7JNHXH6KX","refocusing","Use when a long-running agent may have lost the product outcome, when context was compacted, when work has crossed a major boundary, or when a fresh path-based trace is needed before the next consequential action. Not for fresh-session orientation, waking an idle seat, or checkpoints.","https:\u002F\u002Fgithub.com\u002Fmvschwarz\u002Fopenrig-world\u002Fblob\u002Fmain\u002Frigs\u002Fworkshop\u002Fagents\u002Fworkshop\u002Fskills\u002Frefocusing\u002FSKILL.md",[],[]]