@openrig/cli 0.4.4 → 0.4.7

package/daemon/specs/agents/shared/skills/core/cross-host-rig-commands/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: cross-host-rig-commands
+description: Use when issuing `rig` commands against a remote host via `--host <id>` flag (single-hop SSH to a host declared in `~/.openrig/hosts.yaml`). Covers the 4 structured failure modes (ssh-unreachable / permission-gate / remote-daemon-unreachable / remote-command-failed), the `--verify` honest pass-through (SSH success is NOT verify success), and the host-registry shape. v0 supports `rig send / capture / ps / whoami --host <id>`.
+metadata:
+  cli_surfaces_referenced:
+    - capture
+    - daemon start
+    - host list
+    - host show
+    - ps
+    - send
+    - whoami
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - rig-lifecycle
+      - topology-mutation-and-seat-management
+      - seat-scaling-and-specialization
+      - sidecar-operator
+      - rig-bundles-and-shareable-artifacts
+      - specification-system
+      - extension-and-user-workspace
+---
+
+# Cross-Host Rig Commands
+
+A first-class OpenRig surface for issuing `rig` commands against a
+remote host via single-hop SSH. v0 productizes the existing SSH-envelope
+operator pattern (`ssh <host> rig <cmd>`) with declared host identity,
+explicit cross-host invocation path, preserved `--verify` semantics, and
+4 named failure modes.
+
+**Current-host note (2026-07-14):** this skill still preserves the original
+SSH-v0 doctrine below, but the live host registry may also contain HTTP
+read-through/tunnel entries such as `your-vm` and `your-other-vm`. Use the
+host registry entry as ground truth for transport shape, and use
+`conventions/multi-host-naming/README.md` for host-id naming. HTTP entries
+require `url` plus exactly one of `bearer_file` or `bearer_env`.
+
+**v0 is CLI-side shell-out only — `packages/daemon/` is NOT touched.**
+The remote host has its own managed `rig` available on `$PATH`.
+
+## Use this when
+
+- Driving a Tart VM from the host (the immediate cross-host consumer)
+- Operating Mac host A against Mac host B
+- Reading remote state via `rig ps --host` / `rig whoami --host`
+- Sending or capturing on a remote rig session (`rig send/capture --host <id>`)
+- Authoring a `~/.openrig/hosts.yaml` registry entry
+
+## Don't use this when
+
+- The target is local. Don't pass `--host` for local commands.
+- You need multi-hop SSH (host A → host B → host C). v0 is single-hop only.
+- You want reverse direction (remote initiates back to local). v0 is originator-pull only.
+- Cross-host **seat handover** (moving a durable owned seat across hosts) — deferred to higher-level primitives. (Cross-host **queue writes**, by contrast, now ship — see "Cross-host queue writes" below.)
+- The transport isn't SSH. v0 supports `transport: ssh` only.
+
+## Cross-host queue writes (updated 2026-07-21 vs main d37a08ad)
+
+Cross-host **queue writes** are no longer deferred — they ship — but the rule
+differs from the interactive verbs (`send`/`capture`/`ps`/`whoami`):
+
+- **Queue writes are EXPLICIT-only.** Address the target host explicitly with
+  `--host <id>` or the `member@rig@<host>` form. A queue write **never** follows a
+  persisted host selection.
+- **`host select` stickiness does NOT apply to queue.** `host select` affects the
+  `resolveEffectiveHost` verbs (`send`/`capture`/`ps`/`whoami`) — those follow the
+  selected host — but a queue write ignores it and requires explicit addressing.
+- **Host address parsing differs** between the interactive verbs and the queue
+  verbs; do not assume the interactive form carries over. When unsure, address the
+  host explicitly.
+
+## Host registry shape (`~/.openrig/hosts.yaml`)
+
+Host ids should follow the OpenRig-work multi-host naming convention:
+`conventions/multi-host-naming/README.md`. In this environment that means
+physical hosts such as `your-vm`, local OpenRig development VMs such as
+`your-vm`, persistent product VMs such as `your-other-vm`, and VPS hosts such
+as `your-vps`. Keep old aliases during migration until no live routing
+depends on them.
+
+```yaml
+hosts:
+  - id: a-test-vm
+    transport: ssh                       # v0 supports "ssh" only
+    target: a-test-vm.local         # DNS name, SSH config alias, or IP
+    user: wrandom                        # optional
+    notes: "Tart VM"                     # optional
+  - id: laptop-b
+    transport: ssh
+    target: laptop-b.tail-scale-net
+    user: wrandom
+```
+
+Validation rules:
+
+- `hosts` required, non-null array
+- Each entry: `id` required (non-empty, unique), `transport` required (`ssh` only), `target` required
+- `user` and `notes` optional
+- Operator-managed file; v0 does NOT include any sub-command to add/remove/list hosts (operators edit YAML directly)
+- Missing or invalid file returns a clear error pointing at the canonical path
+
+## CLI surface (v0 shipped)
+
+```bash
+rig send <session> "msg" --host <id> --verify
+rig capture <session> --host <id>
+rig ps --host <id> [--nodes] [...]
+rig whoami --host <id>
+```
+
+Forwards every shaping flag (`--nodes`, `--full`, `--limit`, `--fields`,
+`--summary`, `--filter`, `--json`) to the remote `rig` invocation. The
+remote rig's output is verbatim passthrough on success.
+
+## The 4 structured failure modes (load-bearing API contract)
+
+The CLI distinguishes 4 failure modes; operators get an actionable error
+per mode; JSON output preserves the `failedStep` enum:
+
+| Mode | Cause | Action |
+|---|---|---|
+| `ssh-unreachable` | SSH itself failed (connection refused, host key mismatch, DNS failure, timeout) | Verify SSH access and the registry entry |
+| `permission-gate` | SSH hit auth/permission gate (Permission denied, Keychain) | Error includes hint to keychain-over-SSH field note (L4-3 D6) |
+| `remote-daemon-unreachable` | SSH succeeded but remote `rig` reported the remote daemon was not reachable | `ssh <target> rig daemon start` |
+| `remote-command-failed` | SSH succeeded but remote `rig` exited non-zero for some other reason; remote stderr is surfaced | Read remote stderr; debug remote command |
+
+Each is distinct and routable. Don't conflate them.
+
+## `--verify` honest pass-through (load-bearing)
+
+`--verify` against a remote target must:
+
+- **Propagate** the verification request to the remote daemon (or remote `rig` invocation that talks to it)
+- **Bring back a structured verification result** (true/false + reason if false), NOT just SSH exit code 0
+- **Distinguish "SSH succeeded but verify returned false" from "SSH itself failed"** — these are different operator actions
+
+**SSH success is NOT verify success.** The remote rig is authoritative
+on `--verify`; its `Verified: yes/no` line is surfaced verbatim. Verified
+at 3 layers (executor unit, command integration, source impl).
+
+## Hard boundaries (do-not list)
+
+- **Do NOT collapse `--verify` honest result into SSH exit code.** Operators and agents rely on the distinction.
+- **Do NOT silently retry SSH failures inside the primitive.** Surface them; let the caller decide.
+- **Do NOT introduce non-SSH transports in v0.** Goal is productizing the existing shipped pattern, not replacing it.
+- **Do NOT touch host-side daemon code as part of v0.** Cross-host shape is on the originator side.
+
+## Cross-host annotation
+
+Every cross-host invocation is observable as cross-host:
+
+- **Operator output**: `[via host=<id> (<target>)]` annotation
+- **JSON output**: `cross_host: { host, target }` field
+
+Annotation is PRESENT when `--host` is set and ABSENT otherwise
+(compat regression).
+
+## Currently shipped (v0) vs deferred
+
+Shipped at openrig `cdce3a6` (2026-04-30):
+- `--host <id>` flag on `rig send / capture / ps / whoami` (initial 2 commands; promoted to 4 at `6b7043a` same day)
+- Read-only host registry validation
+- Single-hop SSH executor with 4-mode `failedStep` enum
+- `--verify` honest pass-through
+- Cross-host annotation (operator + JSON)
+- Daemon untouched
+
+Deferred:
+- Tier 2 real-runtime cross-host proof (disposable Tart VM cycle)
+- `rig host list / show` read-only sub-namespace (only if host count grows past comfortable manual editing)
+- Non-SSH transports
+- Multi-hop SSH
+- Reverse direction (remote initiates)
+- Connection pooling/caching
+
+## See also
+
+- `seat-continuity-and-handover` skill — host-aware seat-binding semantics for cross-host handover (deferred to v1 on top of this v0 baseline)
+- `openrig-user` skill — the local CLI surface that cross-host commands wrap
+
+## Sender identity is ASYMMETRIC (verified vs current main, 2026-07-25)
+
+The `@host` sugar is **target-addressing only**, not sender-identity. A cross-host
+message's **From:** is `member@rig` — the sender carries **NO `@host` suffix**. The target
+supports `member@rig@<host>` for addressing; the sender does not reflect its own host in
+`From:`. **Do NOT teach or expect a host-qualified `from`** (in openrig-user / operator send
+docs or anywhere) until that core gap is fixed. (pm@your-rig verified this against
+current main, 2026-07-25 — a known asymmetry, not a doc error to paper over.)

package/daemon/specs/agents/shared/skills/core/human-in-the-loop/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: human-in-the-loop
+description: Use when classifying a slice closeout (auto-continue / human gate / park), routing a real decision to a human, or designing a human queue/dashboard surface. Treats humans as durable network participants with attention surfaces, queues, and decision records — escalation lands as a durable attention item, not a chat message. Approval is NOT required for every clean closeout; the default RSI conveyor continues unless an explicit human gate is reached.
+metadata:
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - queue-handoff
+      - workflow-runtime
+      - watchdog
+      - alignment-trace
+      - looping-workflows
+      - intake-routing
+      - attention-queue
+      - dispatching-parallel-agents
+      - subagent-driven-development
+      - control-plane-capabilities
+      - status-not-chat-orchestrator
+      - control-plane-queue
+      - control-plane-watchdog
+      - control-plane-workflows
+      - control-plane-delivery-loop
+      - control-plane-rollout-manager
+---
+
+# Human In The Loop
+
+The primitive that treats humans as **durable network participants** —
+attention surfaces, queues, decision records, routing semantics — not
+as ad-hoc chat receivers.
+
+**Autonomy is not the absence of humans; it is knowing when human
+judgment is needed and making that handoff crisp.**
+
+## Use this when
+
+- A slice closeout needs classifying: auto-continue, human gate, or park
+- A real decision needs to land in front of a human (usage limits, provider auth, roadmap tradeoff, product-intent ambiguity)
+- Designing a human queue/dashboard surface
+- Returning a hot potato to orchestration after human approval
+
+## Don't use this when
+
+- The slice closeout is clean and `PROGRESS.md` already names the next safe slice. **Default RSI conveyor continues; do NOT manufacture a human gate.**
+- The escalation is just a status update. Humans are participants for *decisions*, not narration.
+- The next owner is another agent. Use queue-handoff, not human-in-the-loop.
+
+## The 3-class closeout classification
+
+In a productized daemon-backed version, closeout classifies the next
+step BEFORE touching the human queue:
+
+| Class | When | Action |
+|---|---|---|
+| **auto-continue** | Slice closes cleanly, next named slice in workstream plan | Mark closed; create next-owner qitem from plan |
+| **human gate** | Genuine decision needed (usage limits, provider auth, product-intent ambiguity, roadmap tradeoff) | Create human queue item with proof + decision text + recommended default + action outcomes |
+| **park** | Intentionally stop the conveyor (e.g., waiting on external) | Stop with reason + resumption path |
+
+## Failure modes (5)
+
+1. **Human decision needed, but the rig only mentions it in chat.** Decisions belong as durable attention items, not chat messages.
+2. **Human queue item lacks enough plain-English context for a decision.** Include proof + decision text + recommended default + action outcomes.
+3. **Human response updates a file but does not wake the next owner.** Approval should return the hot potato; feedback should create the next durable qitem.
+4. **The dashboard shows too much raw rig state and hides the actual decision queue.** Decision queue is the primary surface; rig state is secondary.
+5. **A clean closeout is parked on the human even though `PROGRESS.md` already names the next safe slice.** Don't manufacture human gates.
+
+## Proof standard (both paths)
+
+A trustworthy human-in-the-loop system proves both directions:
+
+- **Blocking gate path**: real item routed to human → human decision recorded through UI → resulting hot-potato handoff wakes correct next owner
+- **Non-blocking closeout path**: proof inspectable by human, but orchestrator continues to next named slice without manufacturing a human gate
+
+A primitive that only wakes humans is not trustworthy. It must also know when NOT to.
+
+## Product shape (SHIPPED — Mission Control, PL-005)
+
+This surface has shipped as **Mission Control** (product UI, `/mission-control`
+route; actions via `POST /api/mission-control/action`). The seven verbs the
+human acts with:
+- **approve** (returns the hot potato to orchestration or the chosen owner)
+- **deny** (reject the item)
+- **route** (send to a different owner)
+- **annotate** (add context without action)
+- **hold** (intentional pause with reason)
+- **drop** (mark not-actionable)
+- **handoff** (hand to a specific next owner — creates the next durable qitem)
+
+**Approval returns the hot potato to orchestration or the chosen owner;
+feedback creates the next durable qitem rather than only mutating the source
+queue file** — enforced by the shipped verbs (handoff/route create qitems).
+See `docs/as-built/architecture/mission-control.md`.
+
+## Long-term shape
+
+Likely needs **multiple humans with different scopes**, not a singleton
+human attention feed. Different humans own different decision
+domains; queue items route by scope.
+
+## See also
+
+- `queue-handoff` skill — durable handoff via queue items; human-in-the-loop is the human-side complement
+- `watchdog` skill — when to wake (humans included) vs no-op
+- `looping-workflows` (convention) — the looping-workflows convention covers loop closeouts; human-in-the-loop is the escape hatch

package/daemon/specs/agents/shared/skills/core/openrig-architect/SKILL.md

@@ -1,18 +1,28 @@
 ---
 name: openrig-architect
-description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (work in the openrig product repo); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
+description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
 metadata:
+  cli_surfaces_referenced:
+    - agent validate
+    - capture
+    - daemon start
+    - ps
+    - send
+    - spec validate
+    - specs ls
+    - up
+    - whoami
   openrig:
     stage: factory-approved
-    last_verified: "2026-05-04"
-    distribution_scope: product-bound
-    source_evidence: |
-      Bootstrap skill — NPM install lands this in personal homes (~/.claude/skills/, ~/.agents/skills/) for users authoring their own rigs.
     sibling_skills:
       - openrig-user
       - openrig-operator
+      - openrig-builder
+      - openrig-upgrade
       - forming-an-openrig-mental-model
-    transfer_test: pending
+      - ai-dev-workflows
+    notes: |
+      Description was already correct (starts with "Use when..."; lists specific authoring triggers including the diagnose-bad-rig case). Final sentence ("Covers the full authoring lifecycle from user intent to validated, launchable rig.") is workflow-summary-adjacent; on next iteration, consider trimming. For factory-adoption cycle, kept as-is to match product source-of-truth.
 ---
 
 # OpenRig Architect
@@ -47,8 +57,13 @@ Load these before starting any design work. The quality of your output depends o
 
 **Read if present on this host:**
 
-4. **Host-level doctrine file** (if your team maintains one — e.g., a HOST-TOPOLOGY doc that defines canonical rig classes, context-sharing patterns, and authoring SOPs for high-stakes rigs). If present, it supersedes the baseline process below for complex or high-stakes rigs (≥4 members, HA, managed-app, or shared/copied). Solo operators and small/focused rigs use the baseline below directly.
-5. **Agent-facing software design principles** if your rig ships a new CLI, service, or managed app that agents will operate. Treat the operating surface as a context-engineering problem: every error message and help text gives the agent information to act on.
+4. **Host-level doctrine** in your host's topology doc, if it keeps one. If this file exists, it supersedes the baseline process below for complex or high-stakes rigs. Specifically:
+   - §3 defines the canonical rig classes (kernel, project, ephemeral, infra-build, managed-app). Classify before designing.
+   - §4 defines context-sharing patterns (pods as context domains, pair pattern, HA via mental-model-ha skill + substrate session logs, terminal nodes as common-room, chatroom/substrate/transcripts/Corpus).
+   - **§7 is the canonical 12-step rig-spec authoring SOP for high-stakes rigs — use it instead of the baseline "Design Process" below when the rig is ≥4 members, uses HA, is a managed-app, or will be shared/copied.** The baseline below still applies to small/focused rigs.
+   - §10 contains the host's bootstrap sequence so you know where your new rig fits.
+   - §12 has the naming canon and vocabulary mapping to shipped terms.
+5. **`building-agent-software` skill** if available in your skill catalog. Design principles for agent-facing tools and surfaces. Relevant when your rig ships a new CLI, service, or managed app.
 
 **Load as needed:**
 - Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
@@ -231,6 +246,8 @@ rig spec validate rig.yaml
 rig agent validate agents/my-agent/agent.yaml
 ```
 
+Then run `rig spec audit rig.yaml` for advisory checks such as stale seat references and other cross-file drift that schema validation cannot detect.
+
 If validation fails, fix the errors. Do not try to launch an invalid spec — it will fail with a less helpful error.
 
 ## Diagnosis: When Things Go Wrong

package/daemon/specs/agents/shared/skills/core/openrig-cmux/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: openrig-cmux
+description: >
+  Use when opening OpenRig fleet terminals into cmux — turning a rig, pod, mission, slice, or saved
+  view into live agent tiles via `rig terminal --provider cmux`, or driving cmux on an agent's
+  request. Same OpenRig view semantics as openrig-herdr (the verbs, honest-partial/degrade, read-only
+  cross-rig, scroll/copy, same-size-only duplicates); cmux is the **best-effort** provider (herdr is
+  the default and the proof-gated one). Prefer openrig-herdr unless cmux is specifically wanted.
+metadata:
+  openrig:
+    stage: candidate
+    sibling_skills:
+      - openrig-herdr
+      - openrig-user
+---
+
+# openrig-cmux
+
+cmux is a **provider** for OpenRig views — the same `rig terminal` surface as herdr, rendering the
+tiles into cmux instead. It is the provider OpenRig already shipped (the existing "Launch in cmux"
+affordance generalizes onto `rig terminal <provider>`), kept working. The OpenRig-semantic half is
+identical to openrig-herdr: OpenRig decides **which** agents form a view; the provider renders the
+pixels. **Read openrig-herdr first for the full model** — this skill only calls out what differs for
+cmux.
+
+## Provider status — cmux is best-effort
+
+- **herdr is the default and the proof-gated provider**; **cmux is best-effort** — it ships on the
+  same `rig terminal <provider>` + web-launcher neighborhood, but a cmux miss is not a slice failure.
+  Reach for cmux when it is specifically wanted; otherwise default to herdr (`rig terminal open <view>`
+  with no `--provider`).
+- Views are **provider-agnostic**: the same view + the same agents + the same semantics carry across
+  herdr and cmux. A saved view opens in either.
+
+## The surface (same three verbs, `--provider cmux`)
+
+```bash
+rig terminal open <view> --provider cmux [--json]   # open a view into cmux (herdr is the no-flag default)
+rig terminal views [--json]                          # the same view library, provider-agnostic
+rig terminal status --provider cmux [--json]         # cmux liveness / health
+```
+
+`<view>` resolves exactly as with herdr: a **rig name** · **`pod:<rig>/<podNamespace>`** ·
+**`mission:<id>`** · **`slice:<id>`** (derived live) · a **saved-view name**.
+
+## What carries over unchanged from openrig-herdr
+
+All of these behave identically — see openrig-herdr for the detail:
+
+- **Honest-partial / honest-degrade** — opened / absent / degraded, each named; partial opens exit 0,
+  zero-pane exits non-zero; an http-registered host's agents degrade with the reason ("host `<id>` is
+  http-registered; tiles need ssh"), never silently dropped.
+- **Read-only policy** — a rig or `pod:` view is interactive; `mission:` / `slice:` views are
+  read-only by construction; a saved view is per-member (`readOnly`). A read-only pane is
+  `tmux attach -r` (client `readonly=1`, keystrokes physically cannot reach the agent). See openrig-herdr.
+- **Safety rails (the fleet-safety rail)** — a tile is a *view* (nested `tmux attach`) of a
+  daemon-owned session; never move/join/kill/re-parent a daemon-owned pane; closing a tile detaches
+  one client and leaves the session untouched; never live-flip tmux options on a running seat in
+  production (prove it in an isolated environment first).
+- **Scroll + copy out of the box** — the daemon's terminal defaults (per-session scroll at launch +
+  the server's clipboard defaults); running seats pick up wheel-scroll at their next relaunch.
+- **Limits** — tile chrome v1 = a plain label; same-size panes for duplicate/multi-view membership
+  (the different-size resize mismatch is an inherent tmux multi-client limit, documented not fixed).
+
+## cmux-specific notes
+
+- **Open-or-focus per agent** — cmux's shipped integration opens a node or focuses it if already open;
+  expect focus (not a duplicate) when a seat is already tiled in cmux.
+- **The shipped "Launch in cmux" affordance is preserved** (byte-compatible) and generalizes into the
+  provider + view picker; opening cmux from the web launcher still works.
+- **No AGPL arm's-length concern** — unlike herdr, cmux is OpenRig's shipped provider integration; the
+  clean-room/never-embed rail that applies to herdr is not a cmux constraint. (This skill itself is
+  still authored clean-room.)
+
+## Saved views — provider-agnostic
+
+Saved views are **hand-authored** in `terminal-views.yaml` (v1 has no save/write verb) and are
+**provider-agnostic** — see **openrig-herdr** for the exact schema, the store facts (atomic tmp+rename,
+byte-stable, at the OpenRig home root), and the derived-views-never-persisted rule. Reopen any saved
+view in cmux with `rig terminal open <id> --provider cmux`. Derived views (a rig, `pod:<rig>/<pod>`,
+`mission:<id>`, `slice:<id>`) are computed live and never written to the file.

package/daemon/specs/agents/shared/skills/core/openrig-herdr/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: openrig-herdr
+description: >
+  Use when opening OpenRig fleet terminals as a herdr wall — turning a rig, pod, mission, slice, or
+  saved view into live interactive agent tiles via `rig terminal`, watching another rig read-only,
+  or driving herdr on an agent's request ("open all my rigs + a mission as views"). Covers the
+  `rig terminal open|views|status` verbs, the honest-partial/degrade reading of the result, the
+  read-only-by-construction rail for cross-rig views, scroll/copy out of the box, and the
+  same-size-only duplicate-pane limit. herdr is the default, proof-gated provider.
+metadata:
+  openrig:
+    stage: candidate
+    sibling_skills:
+      - openrig-cmux
+      - openrig-user
+---
+
+# openrig-herdr
+
+OpenRig decides **which** agents make up a view (a rig, a pod, a mission, a slice, or a saved
+group); **herdr** renders the pixels. A view opens as live, interactive terminal tiles — each tile
+is a nested `tmux attach` to a daemon-owned agent session, so you get the real session, not a
+snapshot. OpenRig owns the semantics; herdr owns the surface. You drive it entirely through the
+`rig terminal` CLI, which rides the installed herdr binary at arm's length — never link, embed, or
+plugin it.
+
+## The whole surface — three verbs
+
+```bash
+rig terminal open <view> [--provider herdr|cmux] [--json]   # herdr is the default provider
+rig terminal views [--json]                                 # list openable views (saved + derived)
+rig terminal status [--provider] [--json]                   # provider liveness / health
+```
+
+`<view>` resolves, in order, to one of:
+- a **rig name** — every live agent in that rig, auto-laid-out;
+- **`pod:<rig>/<podNamespace>`** — every live agent in one pod of a rig (the rig's inventory filtered by pod);
+- **`mission:<id>`** — the agents working that mission (derived live from topology);
+- **`slice:<id>`** — the agents working that slice (derived live);
+- a **saved-view name** — a user-defined group (see Saved views).
+
+## Compose a view from a sentence
+
+An agent asked "open all my rigs plus a mission as views" runs one `open` per target:
+
+```bash
+rig terminal open acme-web                     # a whole rig, live agents as tiles
+rig terminal open mission:site-relaunch        # exactly the agents working the mission
+rig terminal open slice:search-filters      # the agents working one slice
+```
+
+No hand-listing of seats: the mission/slice membership is derived from live topology at open time.
+
+## Read the result honestly — partial and degrade
+
+The result is a partition — every seat lands in exactly one bucket, each **named**:
+
+- **opened** — the live agents now showing as tiles.
+- **absent** — seats in the view that aren't currently live: **named and skipped, never silently
+  dropped.** A view that opens *some* of its seats is a success (the partial is disclosed) and exits
+  **0**. Only a view where **no** pane opens exits **non-zero**.
+- **degraded** — an agent that structurally cannot tile, named **with the reason**. The v1 case:
+  an agent on a host registered over HTTP has no ssh path, so its tile can't be composed — it reads
+  as **"host `<id>` is http-registered; tiles need ssh"** and is skipped, never dropped. (ssh-reachable
+  hosts tile via an ssh-wrapped attach; full http-host tiling is deferred to the cross-host transport
+  seam.)
+
+Read `--json` to branch on the partition programmatically; the exit code alone tells you opened-something
+(0) vs opened-nothing (non-zero).
+
+## Read-only — who's interactive, who's watch-only
+
+Read-only is composed into the pane at open time — a read-only tile is a `tmux attach -r`, the client
+reports `readonly=1`, and it **physically cannot send input**. The current policy, by view kind:
+
+- **A rig view or a `pod:` view is interactive** — you asked for that rig (or pod) directly, so you
+  can drive its agents.
+- **`mission:` and `slice:` views are read-only by construction** — these derived views cut across
+  rigs; you watch and scroll, you don't keystroke into them.
+- **A saved view is per-member** — each member carries its own `readOnly` (omit = interactive;
+  `true` = `attach -r`).
+
+So you don't have to remember to be careful: the view kind (and, for a saved view, the per-member
+flag) sets it at open time.
+
+## Safety rails (hard — the fleet-safety rail)
+
+- A tile is a **view** (a nested `tmux attach`) of a daemon-owned session. **Never** move, join, kill,
+  or re-parent a daemon-owned pane. Closing a tile detaches one tmux client — the daemon's session is
+  untouched and its addressing (send/capture/nudge) is unaffected.
+- Host-local read-only viewing mutates nothing. Anything that would change a **live** daemon session's
+  shared state (e.g. flipping a tmux option on a running seat) is a config/design change — prove it in
+  an isolated environment, never live-flip in production.
+
+## Scroll + copy work out of the box
+
+On a freshly-launched agent tile the mouse wheel scrolls the pane's history and a drag-select copies
+to your **system** clipboard — with no tmux commands typed. This rides the daemon's terminal defaults
+(a per-session scroll option set at launch, plus the daemon tmux server's clipboard defaults). Honest
+timing: agents that were already running before this shipped pick up wheel-scroll at their **next
+natural relaunch** (the scroll default is per-session and running seats are never retro-flipped);
+system-clipboard copy works immediately (it's server-wide).
+
+## Limits — state them, don't paper over them
+
+- **Tile chrome v1 = a plain label** (agent + slice). Rich per-tile status is roadmap.
+- **Duplicate / multi-view membership** (the same agent live in two views at once) works — put the
+  duplicates in **same-size panes**. Different-sized duplicate panes have an inherent tmux
+  multi-client resize mismatch (tmux clamps to the smallest client); it is **documented, not fixed** —
+  don't expect a setting to remove it.
+- **Inner tmux status bar** is hidden by default (herdr provides the chrome); one config key
+  (`terminal.status_bar`) flips it back on for raw-tmux / no-provider surfaces, and the flip applies
+  to **future launches only**.
+
+## Saved views — the library (`terminal-views.yaml`)
+
+In v1 you **create** a saved view by **hand-authoring** `terminal-views.yaml` — there is no save/write
+verb (`open` / `views` / `status` are the whole surface; a `rig terminal save <id>` verb is a named
+stretch/follow-up). You **reopen** it like any other view: `rig terminal open <id>`.
+
+The file lives at the OpenRig home root (resolved via `getDefaultOpenRigPath()`), is written
+atomically (tmp + rename), and is byte-stable. **Only hand-authored saved views live here — derived
+views (a rig, `pod:<rig>/<pod>`, `mission:<id>`, `slice:<id>`) are computed live and never written to
+this file.**
+
+Schema — use these field names **exactly**, in this order; **omit** optional fields when absent
+(never write `null`):
+
+```yaml
+version: 1
+views:
+  - id: my-view-id             # required — the id `rig terminal open <id>` takes
+    name: Human Name           # required
+    members:
+      - seat: pod-member@rig    # required — the canonical session name
+        label: agent . slice    # optional — pane label
+        host: some-host-id      # optional — STRUCTURED host id (NEVER a `member@rig@host` string);
+                                #            omit for local. ssh-registered hosts tile;
+                                #            http-registered hosts honest-degrade (named + skipped, with reason)
+        tmuxSession: sessname   # optional — defaults to `seat`
+        readOnly: true          # optional — omit = interactive; true = `tmux attach -r`
+```
+
+An agent composing a saved view on request **writes this YAML** and then opens the id:
+`rig terminal open my-view-id` (add `--provider cmux` for cmux). The library is provider-agnostic —
+the same saved view opens in herdr or cmux.
+
+## AGPL / clean-room
+
+Driving herdr through the `rig terminal` CLI (which talks to the installed herdr binary over its
+CLI/socket) is arm's-length and fine. Do **not** link herdr's source, embed it in-process, or ship a
+herdr plugin — a plugin needs legal review. This skill and its docs are clean-room: patterns only,
+never herdr source text.