@openrig/cli 0.4.3 → 0.4.6

package/daemon/assets/guidance/openrig-start.md

@@ -17,6 +17,12 @@ That skill covers the broader surface, including chatroom, discovery, adopt/bind
 Your per-session startup guidance may also name additional packaged skills for your role and pod.
 Load those too. This shared overlay is only the common bootstrap floor, not the full operating manual for your seat.
 
+## Working missions and slices (the SDLC)
+
+If your seat works missions or slices, load the packaged `mission-slice-sop` skill BEFORE authoring or building — it teaches the flow the Living Notes UI projects: intent → mini-requirements + proof contract (→ mockups for UI slices) → plan-lock (`rig scope slice approve --scope spec`) → build the locked set → QA visual compare → `rig proof add … --media` drops (the C1 drop verb — never hand-place proof files) → proof-lock (`--scope delivery`).
+
+The conventions themselves (section names, proof-contract format, the two locks, C1 proof headers) live in ONE shipped document: `docs/reference/sdlc-conventions.md` (in the CLI package). `rig scope slice create` scaffolds the convention sections for every template kind; `rig scope audit` is the advisory backstop — it records and advises, it never blocks your work.
+
 ## Identity
 
 Run this first after launch or compaction to recover your identity:

package/daemon/assets/plugins/openrig-core/skills/mission-slice-sop/SKILL.md

@@ -1,19 +1,18 @@
 ---
 name: mission-slice-sop
-description: Use when working a mission or slice — how to track, prove, hand off, and carry state across agents and compaction via the canonical files (PROGRESS.md / PROOF.md / MISSION_NOTES.md / MISSION_BRIEF.md / README.md). Covers the per-file WHO/WHEN/HOW rules, the four-legs lifecycle (SCAFFOLD/POPULATE/PROJECT/VERIFY), hot-potato queue handoffs, the moment-of-truth checklist, the deterministic `rig scope audit` backstop, and the known ghost-text gotcha when reading terminal captures.
+description: Use when working a mission or slice — the full SDLC flow (intent → mini-requirements + proof contract → mockups → plan-lock → build → QA visual compare → `rig proof` drops → proof-lock) plus how to track, prove, hand off, and carry state across agents and compaction via the canonical files (PROGRESS.md / PROOF.md / MISSION_NOTES.md / MISSION_BRIEF.md / README.md / IMPLEMENTATION-PRD.md). Covers the convention sections the Living Notes UI projects, the two locks, the three role contracts, per-file WHO/WHEN/HOW rules, the four-legs lifecycle, hot-potato queue handoffs, the moment-of-truth checklist, the deterministic `rig scope audit` backstop, and the ghost-text capture gotcha.
 metadata:
   openrig:
     stage: shipped
-    last_verified: "2026-07-03"
+    last_verified: "2026-07-06"
     distribution_scope: product-bound
     source_evidence: |
-      Authored + embedded in release-0.4.3 slice 32 (mission-slice-sop). The
-      canonical SOP is the operating surface for mission/slice work: the
-      PROGRESS / PROOF / MISSION_NOTES / MISSION_BRIEF files drive the workspace
-      UI and carry state across agents + compaction. Operationalizes the
-      markdown-control-plane convention (loose freeform write + deterministic
-      verify) and the shipped `rig scope audit` classifier — the deterministic
-      backstop is the audit, not standalone check scripts.
+      The canonical product SDLC skill: it teaches the full SDLC flow the
+      Living Notes UI projects — the convention sections, the proof-contract
+      pairing, the two staged-approval locks, C1 proof drops, and the three
+      role contracts. Conventions SSOT: docs/reference/sdlc-conventions.md
+      (shipped with the CLI package). The deterministic backstop is the
+      `rig scope audit` classifier.
     sibling_skills:
       - queue-handoff
       - seat-continuity-and-handover
@@ -22,17 +21,43 @@ metadata:
 
 # Mission/Slice SOP — how you work a mission & slice
 
-Use this skill to actually **do** mission/slice work the way OpenRig expects: track on the canonical files, prove on them, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.** The deterministic backstop is `rig scope audit` — there are no separate bundled check scripts; the audit classifier is the source of truth for adherence.
+Use this skill to actually **do** mission/slice work the way OpenRig expects: author the convention sections, track on the canonical files, prove on them, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.** The deterministic backstop is `rig scope audit` — the audit classifier is the source of truth for adherence. The conventions themselves live in ONE place: **`docs/reference/sdlc-conventions.md`** (shipped with the CLI package) — this skill teaches the flow; the SSOT defines the formats.
 
-> The canonical files below are the **operating surface of the work** — you track on them, prove on them, hand off through them, and survive compaction on them. They are NOT side-artifacts to "maintain"; keeping them current *is* the work.
+## The SDLC flow (intent → proof)
+
+```
+intent → mini-requirements + proof contract → (UI slices: mockups)
+      → plan-lock (rig scope slice approve --scope spec)
+      → build the LOCKED set
+      → QA: mockup ↔ delivered VISUAL compare
+      → proof drops (rig proof add <slice> …)
+      → proof-lock (rig scope slice approve --scope delivery)
+```
+
+1. **Record intent** verbatim in the slice's `## Intent` section (`rig scope slice create` scaffolds it — every template kind).
+2. **Author the mini-requirements + proof contract**: `## Mini-requirements` is the concise one-glance tier (approval starts there); `## Proof contract` is a checkbox list of promised deliverables, each written as an observable outcome. UI deliverables name their planned mockup. The IMPLEMENTATION-PRD opens with the mini-requirements; everything between intent and proof is **elastic** — for a small slice the mini-requirements may BE the whole PRD.
+3. **Plan-lock**: `rig scope slice approve <slice> --scope spec` — "the PRD matches the intent; THIS artifact set is what gets built." One daemon-side write: frontmatter stamp + append-only audit row.
+4. **Build the locked set** — look at the mockups, not just the spec text.
+5. **QA visual compare**: for each deliverable, load the planned mockup, produce the real artifact in a test/demo environment, visually compare, and record the verdict.
+6. **Drop proof**: `rig proof add <slice> --artifact-type qa --verdict PASS --candidate-sha <tip> --money-evidence "…" --evidences "1,3" --media "walk.webm,panel.png" --self-check "…"` — the C1 header's closed sets validate at drop time; `--evidences` joins the drop to its proof-contract items and `--media` names the curated proof/-relative media the drop stands behind (that pairing + media set is what the UI's DELIVERED section renders).
+7. **Proof-lock**: `rig scope slice approve <slice> --scope delivery` — the terminal sign-off. Approval is freeze/sign-off, **never** proven-green: proven-green requires the recorded C1 verdicts.
+
+## The three role contracts
+
+- **Planning agent:** authors intent + mini-requirements + the proof contract; produces mockups for UI deliverables and attaches them to the locked set (a UI slice with no mockup is an incomplete plan; non-UI slices have none — not a gate); locks the plan.
+- **Build agent:** builds against the LOCKED set only; looks at the mockups.
+- **QA agent (owns the compare):** visually compares planned vs delivered per deliverable, records verdict + note via proof drops, and **curates** the canonical proof set (bounded, mapped to deliverables; the fix-loop pile stays in `proof/`, one drill-in down). On mismatch: fix-and-re-review or kick back with the reason — never escalate a raw mismatch to the human.
 
 ## The canonical files (the operating surface)
 
-- **README.md** (mission + slice) — the overview: what the mission/slice is + why. The **mission README carries this SOP at its bottom.**
+> The canonical files below are the **operating surface of the work** — you track on them, prove on them, hand off through them, and survive compaction on them. They are NOT side-artifacts to "maintain"; keeping them current *is* the work.
+
+- **README.md** (mission + slice) — the overview, OPENING with the convention sections (`## Intent` / `## Mini-requirements` / `## Proof contract`). The **mission README carries this SOP at its bottom.**
+- **IMPLEMENTATION-PRD.md** — the full PRD; opens with the mini-requirements; the `## Proof contract` here is what the UI's DELIVERED pairing joins proof against.
 - **PROGRESS.md** — the live delivery state. One line per outcome; links down for detail.
 - **MISSION_NOTES.md** — the accruing handoff + tribal-knowledge doc. Blank-slate onboarding + **compaction-restore** read it. `§1` top-of-mind + per-seat `§A–§X`.
 - **MISSION_BRIEF.md** — the steering doc (the UI "Steering" tab). The 7-section schema.
-- **PROOF.md** (+ `proof/`) — acceptance evidence. **A slice is not done until every plan success-criterion has proof.**
+- **PROOF.md** (+ `proof/`) — acceptance evidence. **A slice is not done until every proof-contract item has evidence.**
 
 ## Per-file rules — WHO / WHEN / HOW
 
@@ -41,10 +66,10 @@ Use this skill to actually **do** mission/slice work the way OpenRig expects: tr
 - **WHEN:** after every slice-done **AND every commit**; on any material state change.
 - **HOW:** one line per outcome (checkbox), link down for detail (workstream-continuity format); keep frontmatter `stage`/`verified` honest.
 
-### PROOF.md
+### PROOF.md + proof/
 - **WHO:** the impl/QA pair that worked the slice.
-- **WHEN:** a slice is **NOT "done"** until PROOF.md exists and every plan success-criterion has evidence.
-- **HOW:** proof maps **1:1 to the plan's acceptance/success criteria** — each criterion gets an evidence artifact (screenshot/capture/log) in `proof/` + a line in PROOF.md stating what it proves. No proof → not done.
+- **WHEN:** a slice is **NOT "done"** until every proof-contract item has evidence.
+- **HOW:** proof maps **1:1 to the proof contract's deliverables** — put media under `proof/`, then ATTACH it with `rig proof add <slice> … --evidences <item> --media <files>` (the drop writes the C1 header the DELIVERED pairing joins on) + a line in PROOF.md stating what it proves. **Hand-placing files in `proof/` without a drop is the anti-pattern** — the deliverable stays unpaired and `unverified`. No proof → not done.
 
 ### MISSION_NOTES.md
 - **WHO:** any agent updates `§1` (top-of-mind); each seat owns + appends to its own `§A–§X` section.
@@ -59,11 +84,11 @@ Use this skill to actually **do** mission/slice work the way OpenRig expects: tr
 ### README.md
 - **WHO:** the author at creation; refreshed on rescope.
 - **WHEN:** at mission/slice creation + when scope/theme changes.
-- **HOW:** overview + honest frontmatter (`id`/`stage`/`verified`); the mission README carries this SOP at its bottom.
+- **HOW:** overview + honest frontmatter (`id`/`stage`/`verified`) + the convention sections up top; the mission README carries this SOP at its bottom.
 
 ## The lifecycle (4 legs)
 
-**SCAFFOLD** (`rig scope` creates the files from templates) → **POPULATE** (agents fill them as work happens, per the rules above) → **PROJECT** (the workspace UI reads them into tabs) → **VERIFY** (`rig scope audit` + the validation scripts check adherence). "Loose freeform write + deterministic verify."
+**SCAFFOLD** (`rig scope` creates the files from templates — every slice kind emits the convention sections + `proof/` + the IMPLEMENTATION-PRD skeleton) → **POPULATE** (agents fill them as work happens, per the rules above) → **PROJECT** (the Living Notes UI reads them into INTENT → PLAN → DELIVERED) → **VERIFY** (`rig scope audit` checks adherence). "Loose freeform write + deterministic verify."
 
 ## Hot-potato (handoffs)
 
@@ -71,7 +96,7 @@ End every turn by passing the ball — a `rig queue` handoff to the next agent (
 
 ## Verify (deterministic backstop)
 
-Run `rig scope audit` at slice-close. The validation scripts flag: committed-without-touching-PROGRESS; slice-marked-done-without-PROOF; active-mission-without-MISSION_NOTES; MISSION_BRIEF off-schema. **Fix the flag, don't suppress it.**
+Run `rig scope audit` at slice-close. It flags: committed-without-touching-PROGRESS; slice-marked-done-without-PROOF; active-mission-without-MISSION_NOTES; MISSION_BRIEF off-schema; proof artifacts violating the C1 header; missing IMPLEMENTATION-PRD on a building slice; missing convention sections (`## Intent`, a well-formed `## Proof contract`, the UI-slice mockup ref). Every convention check is **advisory / fail-open** — it records and advises, never blocks a write. **Fix the flag, don't suppress it.**
 
 ## Reading terminal captures — KNOWN GOTCHA: ghost-text autocomplete is NOT real
 
@@ -81,7 +106,8 @@ When you `rig capture` a pane, **greyed / ghost autocomplete suggestions are NOT
 
 ## Moment-of-truth checklist
 
-- **Finishing a slice?** → PROOF complete (every criterion has evidence)? PROGRESS updated? MISSION_NOTES `§1` refreshed? Handed off via queue?
+- **Starting a slice?** → intent recorded verbatim? mini-requirements + proof contract authored? mockups attached (UI slices)? plan locked (`--scope spec`)?
+- **Finishing a slice?** → every proof-contract item has curated evidence via `rig proof add … --evidences --media` (C1 drops — never only hand-placed files)? PROGRESS updated? MISSION_NOTES `§1` refreshed? proof locked (`--scope delivery`)? Handed off via queue?
 - **Committing?** → PROGRESS updated?
 - **Compacting?** → filed your state in MISSION_NOTES?
-- **Starting on a mission?** → read the mission README (incl. this SOP) + MISSION_NOTES?
+- **Starting on a mission?** → read the mission README (incl. this SOP) + MISSION_NOTES + `docs/reference/sdlc-conventions.md`?

package/daemon/assets/plugins/openrig-core/skills/openrig-cmux/SKILL.md

@@ -0,0 +1,86 @@
+---
+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
+    distribution_scope: product-bound
+    source_evidence: |
+      cmux is OpenRig's shipped terminal provider generalized onto `rig terminal <provider>` —
+      best-effort, not proof-gated. Authored clean-room.
+    transfer_test: pending
+    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/assets/plugins/openrig-core/skills/openrig-herdr/SKILL.md

@@ -0,0 +1,158 @@
+---
+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
+    distribution_scope: product-bound
+    source_evidence: |
+      Empirical herdr 0.7.1 hands-on findings + the ratified implementation PRD. Authored
+      clean-room (patterns only, no herdr source text; AGPL arm's-length).
+    transfer_test: pending
+    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:02-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.