@openrig/cli 0.6.6 → 0.6.7

package/daemon/assets/plugins/openrig-core/hooks/scripts/refocus.cjs

@@ -11,10 +11,14 @@ const fs = require("node:fs");
 const path = require("node:path");
 const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
+const { recordRefocusResult } = require("./refocus-health.cjs");
 
 const DEFAULT_THRESHOLD = 2_600_000;
 const FALSE_VALUES = new Set(["0", "false", "off", "no"]);
 const CONTENT_LOOKUP_TIMEOUT_MS = 2_000;
+// Normal managed restore advances on ~30 s polls with a 10 s idle wait.
+// A lost daemon stage must not suppress this occupant's refocus indefinitely.
+const MANAGED_RESTORE_HOLD_MS = 10 * 60_000;
 
 function runtime() {
   const index = process.argv.indexOf("--runtime");
@@ -188,6 +192,7 @@ function renderTrace() {
     script,
     "--trees", trees,
     "--depth", process.env.OPENRIG_REFOCUS_DEPTH || "light",
+    "--check",
   ];
   if (process.env.OPENRIG_REFOCUS_TOPOLOGY_NODE) {
     args.push("--topology-start", process.env.OPENRIG_REFOCUS_TOPOLOGY_NODE);
@@ -213,9 +218,15 @@ function renderTrace() {
     maxBuffer: 16 * 1024 * 1024,
   });
   const reason = result.error?.message || result.stderr?.trim() || `trace exited ${result.status ?? "without a status"}`;
-  const trace = !result.error && result.status === 0 && result.stdout.trim()
-    ? result.stdout.trim() : `TRACE GAP — ${String(reason).replace(/\s+/g, " ").trim()}`;
-  return [trace, role].filter(Boolean).join("\n\n");
+  const failed = Boolean(result.error) || result.status !== 0 || !result.stdout?.trim();
+  const trace = [
+    ...(failed ? [`TRACE GAP — ${String(reason).replace(/\s+/g, " ").trim()}`] : []),
+    result.stdout?.trim(),
+  ].filter(Boolean).join("\n");
+  return {
+    text: [trace, role].filter(Boolean).join("\n\n"),
+    failed,
+  };
 }
 
 (async () => {
@@ -226,6 +237,16 @@ function renderTrace() {
   const event = input.hook_event_name || "UserPromptSubmit";
   const harness = runtime();
 
+  // The acknowledgement is never an actionable restore turn. The managed
+  // marker below also holds earlier/later peer messages, not just this prompt.
+  const rawPrompt = typeof input.prompt === "string" ? input.prompt.trim() : "";
+  // Claude can wrap a complete submitted message as pasted content. Unwrap only
+  // that envelope; a peer quoting a restore request is still an ordinary prompt.
+  const prompt = harness === "claude"
+    ? (rawPrompt.match(/^<pasted_content id="([^"]+)">\s*([\s\S]*)\s*<\/pasted_content id="\1">$/)?.[2]?.trim() ?? rawPrompt)
+    : rawPrompt;
+  if (event === "UserPromptSubmit" && prompt.startsWith("OpenRig post-compaction turn boundary.")) process.exit(0);
+
   // Fresh-session orientation is the default onboarding pack's job. Even a manually invoked hook must
   // no-op here, so a stale registration cannot corrupt the world install.
   if (event === "SessionStart") process.exit(0);
@@ -311,16 +332,16 @@ function renderTrace() {
     state = { lastBytes: size, baselineAt: new Date().toISOString() };
     persist();
   } else if (size > 0 && size < Number(state.lastBytes || 0)) {
-    // Shrink clears pending and resets the baseline BEFORE due computation. The
-    // reset itself emits no refocus, and a stale pending can never ride through a
-    // reset into a delivery. Advisory once per reset episode: the reset moment is
-    // the dedupe (afterwards lastBytes === size), and the marker records in state.
-    delete state.pendingOn;
-    delete state.pendingAt;
+    // Shrink invalidates growth-based due state, not an exact PostCompact event
+    // awaiting its actionable restore turn.
+    if (state.pendingOn !== "PostCompact") {
+      delete state.pendingOn;
+      delete state.pendingAt;
+    }
     state.lastReset = { at: new Date().toISOString(), fromBytes: Number(state.lastBytes || 0), toBytes: size };
     state.lastBytes = size;
     persist();
-    process.stderr.write(`refocus: transcript shrank for ${seat} — baseline reset, pending cleared\n`);
+    process.stderr.write(`refocus: transcript shrank for ${seat} — baseline reset; PostCompact pending retained if present\n`);
   }
 
   const lastBytes = Number(state.lastBytes || 0);
@@ -334,17 +355,46 @@ function renderTrace() {
   if (!due) process.exit(0);
 
   if (event !== "UserPromptSubmit") {
+    if (event === "PostCompact" && harness === "claude") {
+      // PreCompact records whether THIS compact was initiated by the enforcer.
+      // A manual /compact overwrites the marker with false; other occupants
+      // cannot hold this session. Read the early sentinel first if it survives.
+      state.managedRestorePending = false;
+      for (const suffix of [".expected.json", ".json"]) {
+        try {
+          const marker = JSON.parse(fs.readFileSync(path.join(home, "compaction", "restore-pending", seatKey + suffix), "utf8"));
+          if (marker.sessionName !== seat || (marker.sessionId ? marker.sessionId !== identity : !transcriptPath || marker.transcriptPath !== transcriptPath)) continue;
+          state.managedRestorePending = marker.managedRefocusPending === true;
+          break;
+        } catch {}
+      }
+      if (state.managedRestorePending) state.managedRestorePendingAt = new Date().toISOString();
+      else delete state.managedRestorePendingAt;
+    }
     if (event === "PostCompact" || !state.pendingOn) state.pendingOn = event;
     state.pendingAt ||= new Date().toISOString();
     persist();
     process.exit(0);
   }
 
+  if (harness === "claude" && state.managedRestorePending) {
+    const heldFor = Date.now() - Date.parse(state.managedRestorePendingAt);
+    // Missing/invalid timestamps from older state, or a clock moving backwards,
+    // cannot establish a live hold. No timer or extra turn is created here.
+    if (heldFor >= 0 && heldFor < MANAGED_RESTORE_HOLD_MS
+      && !prompt.startsWith("Please respond to this normal user message now by restoring this Claude session after compaction.")) process.exit(0);
+    delete state.managedRestorePending;
+    delete state.managedRestorePendingAt;
+    persist();
+  }
+
   // Run the public trace before resolving a context ref. Besides keeping the
   // content ladder untouched, this makes `rig context get` the last resolver
   // call and preserves the existing observable ref contract.
-  const trace = renderTrace();
+  const rendered = renderTrace();
+  const trace = rendered.text;
   const configured = readConfiguredContent(home);
+  const failed = rendered.failed || Boolean(configured.failure);
   const why = onDemand
     ? "on demand"
     : state.pendingOn === "PostCompact"
@@ -391,7 +441,14 @@ function renderTrace() {
       additionalContext: payload,
     },
   });
-  process.stdout.write(output, () => {
+  process.stdout.write(output, (error) => {
+    recordRefocusResult({ home, seat, identity, failed: failed || Boolean(error) });
+    if (failed || error) {
+      state.pendingOn ||= event;
+      state.pendingAt ||= new Date().toISOString();
+      persist();
+      return;
+    }
     if (size > 0) state.lastBytes = size;
     state.firedAt = new Date().toISOString();
     state.firedOn = event;

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/SKILL.md

@@ -92,8 +92,10 @@ You are about to lose every connection you have built. Spend this turn making th
    What were the threads? What did you work out about how the pieces fit? What is unfinished? What did you
    decide, and why? What were you about to be wrong about?
 2. **Write the restore map at the exact path named in OpenRig's preparation request.** Follow that
-   request's completion marker and atomic publication instructions: the daemon waits for that specific
-   file. Do not substitute the seat folder or another map. Managed preparation normally uses
+   request's completion instructions: use your ordinary file-edit tool to write the named `.tmp` file,
+   with the exact completion marker as its last line, then finish and close it. The daemon publishes
+   the completed map atomically; do not run a shell rename or write the final file incrementally.
+   Do not substitute the seat folder or another map. Managed preparation normally publishes
    `<launch cwd>/.openrig/compaction/preparation/<session>/<attempt>/RESTORE-MAP.md`; its parent
    compaction folder ignores itself in Git because maps hold private working context. Unknown or
    unwritable launch directories retain the instance-home fallback named in the request; it may need
@@ -149,6 +151,15 @@ already leaves you. The edges are the point.
 
 You have facts without connections. Rebuild the connections before you act on anything.
 
+Use the native read tool for file reads throughout restoration. Load `refocusing`
+and consume the current topology and work trace that actually arrived with the
+restore request; do not rerun Python merely to duplicate it. If no current trace
+arrived, name that delivery gap. A packet pointer, compact summary or truncated
+extract is not a full source read. Read required notes and full sources separately
+and complete the restore steps and read-depth audit below; partial reading does
+not establish completed restoration. The earlier acknowledgement-only boundary
+is not a restore request.
+
 1. **Check for a hold first.** Read the restore request, the per-seat instruction file
    (`<OPENRIG_HOME>/compaction/post-compact-extra/<session>.md`, named by your full session such as
    `dev-impl@my-rig.md`) when it exists, the newest row or message from whoever routes your work, and any hold

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/precompact-hook.mjs

@@ -125,6 +125,8 @@ function writeExpectedSentinel(input) {
   fs.mkdirSync(path.dirname(p), { recursive: true });
   fs.writeFileSync(p, `${JSON.stringify({
     version: 1,
+    managedRefocusPending: typeof input.custom_instructions === "string"
+      && input.custom_instructions.trimStart().startsWith("OpenRig managed compaction; wait for the restore request."),
     sessionName: process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || null,
     sessionId: input.session_id || input.sessionId || null,
     transcriptPath: input.transcript_path || null,
@@ -137,6 +139,8 @@ function writePendingRestoreMarker(input, parsed, restoreInstruction, customMess
   fs.mkdirSync(path.dirname(markerPath), { recursive: true });
   const payload = {
     version: 1,
+    managedRefocusPending: typeof input.custom_instructions === "string"
+      && input.custom_instructions.trimStart().startsWith("OpenRig managed compaction; wait for the restore request."),
     createdAt: nowIso(),
     sessionName: process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || null,
     sessionId: input.session_id || input.sessionId || null,

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

@@ -57,7 +57,7 @@ These are auto-delivered to every rig; their name+description are already in you
 - **loading-addressable-markdown** — a task names Markdown as `path#h2-slug` or `path#h2-slug/h3-slug` outside the context-pack library.
 - **session-compaction-and-restore** — preparing for, or recovering from, compaction (any runtime). The write- and read-side protocol.
 - **queue-handoff** — you're passing durable work to another seat or ending your turn. The queue is the work ledger, not chat.
-- **refocusing** — a long-running seat may have lost the product outcome, crossed a major boundary, or compacted and needs a fresh path-based trace.
+- **refocusing** — invoke as `refocusing` when a long-running seat may have lost the product outcome, crossed a major boundary, or compacted and needs a fresh path-based trace.
 - **seat-continuity-and-handover** — handing your seat's work across a restart or to another owner.
 - **orienting-to-an-inherited-seat** — you just inherited an existing seat through a planned handover and need to verify its identity, state, and testimony.
 - **retiring-and-inheriting-a-seat** — you're planning a seat transition and need to retire the current occupant into a fresh successor without losing continuity.

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

@@ -11,20 +11,47 @@ metadata:
 
 # Refocusing
 
+Invoke the skill as `refocusing`, its frontmatter name. OpenRig seeds it in the
+Claude and Codex global skill roots and includes selected plugin skills in managed
+loadouts. Existing externally managed copies remain authoritative. If the harness
+has not discovered it yet, read this installed skill file and run its script directly;
+hook registration alone does not prove native skill discovery.
+
 Refocus preserves a long session's earned expertise while re-grounding it in current intent and
 lived context. It is not a restart, wake, or phase checkpoint.
 
-Run the bundled trace from this skill directory instead of reconstructing the hierarchy from memory:
+During an actionable managed restore, consume the current topology and work trace
+that actually arrived with the request. Do not rerun Python merely to duplicate it.
+If no current trace arrived, name that delivery gap. A packet pointer, compact
+summary or truncated extract is not a full source read. Use the native file-read
+tool for required notes and full sources, and complete the existing restore audit;
+partial file reads do not establish completed refocus or restoration.
+
+For a new trace outside that delivered context, follow the command guidance below.
+Resolve the bundled script's absolute path from the directory of this loaded skill.
+Stay in your current working directory; do not `cd` into the skill directory, which
+can change the inferred work node. Run the trace as **one plain command**, replacing
+the example path with the actual absolute path written out in the tool call:
 
 ```bash
-python3 scripts/trace-to-root.py --trees both --depth light
+python3 "/absolute/path/to/refocusing/scripts/trace-to-root.py" --trees both --depth light
 ```
 
+Do not combine this command with shell variables, environment assignments, command
+substitution, exit-status printing or file-reading loops. Read the named source
+files separately with the native read tool. Combined shell loops or variables can
+require native approval even when the intended operations are read-only; a plain
+command is not a guarantee that approval will never be needed.
+
+For managed compaction, refocus during the restore request or its read-depth
+audit. The earlier acknowledgement-only boundary is not permission to restore.
+
 Use `--trees topology|work|both` to select context domains and `--depth light|full` to control how
 much each node contributes. Light work traces compose `intent:` and name notes; full traces include
 the complete node and notes bodies. The script resolves `topology.root` and `workspace.root` with
-`rig config get`. When a current node cannot be derived, set `OPENRIG_REFOCUS_TOPOLOGY_NODE` or
-`OPENRIG_REFOCUS_WORK_NODE`, or pass the matching `--*-start` option.
+`rig config get`. When a known current node must be supplied, pass `--work-start` or
+`--topology-start` with its literal absolute path in the same plain command. Do not
+substitute the project root for a mission or slice node and claim that mission was traced.
 
 The trace walks the topology and work trees. For the project's own declared context (intent, context files,
 skills), `rig context work-install` lists it; read what the next action needs.

package/daemon/assets/plugins/openrig-core/skills/refocusing/scripts/trace-to-root.py

@@ -148,10 +148,11 @@ def light_learned(text):
     return body[:boundary if boundary > 0 else 800].rstrip() + "\n[… use --depth full for the rest]"
 
 
-def render_topology(start, root, depth):
+def render_topology(start, root, depth, failures):
     output = ["## TOPOLOGY TRACE", f"root: {root}", f"start: {start}"]
     nodes, error = ascent(start, root)
     if error:
+        failures.append(error)
         return "\n".join(output + [f"TRACE GAP — {error}"])
     for node in nodes:
         chain_file = node / "LEARNED.md"
@@ -165,12 +166,13 @@ def render_topology(start, root, depth):
     return "\n".join(output)
 
 
-def render_work(start, root, depth, fallback=None):
+def render_work(start, root, depth, failures, fallback=None):
     output = ["## WORK TRACE", f"root: {root}", f"start: {start}"]
     if fallback:
         output.append(f"FALLBACK — {fallback}")
     nodes, error = ascent(start, root)
     if error:
+        failures.append(error)
         return "\n".join(output + [f"TRACE GAP — {error}"])
     for node in nodes:
         label = node.relative_to(root) or Path(".")
@@ -188,12 +190,14 @@ def render_work(start, root, depth, fallback=None):
 
         notes, resolution_error = resolve_notes(node)
         if resolution_error:
+            failures.append(resolution_error)
             output.append(f"NOTES RESOLUTION GAP — {resolution_error} at {node}")
         elif notes:
             notes_path, notes_name = notes
             if depth == "full":
                 notes_text = read(notes_path)
                 if notes_text is None:
+                    failures.append(f"unreadable notes: {notes_path}")
                     output.append(f"NOTES RESOLUTION GAP — resolved {notes_name} became unreadable at {notes_path}")
                 else:
                     output.append(f"\nNOTES · {notes_name}\n{notes_text.strip()}")
@@ -201,6 +205,7 @@ def render_work(start, root, depth, fallback=None):
                 try:
                     size = notes_path.stat().st_size
                 except OSError:
+                    failures.append(f"unreadable notes: {notes_path}")
                     output.append(f"NOTES RESOLUTION GAP — resolved {notes_name} became unreadable at {notes_path}")
                 else:
                     output.append(f"NOTES · {notes_name} · {size} bytes · {notes_path}")
@@ -273,43 +278,49 @@ def main():
     parser.add_argument("--work-start")
     parser.add_argument("--work-basis", help="the daemon's reason no current work node was named")
     parser.add_argument("--work-unknown", help="why the current work node could not be read")
+    parser.add_argument("--check", action="store_true", help="exit nonzero on trace or notes resolution failure; rendered text is unchanged")
     args = parser.parse_args()
 
     sections = []
+    failures = []
+
+    def gap(text):
+        failures.append(text)
+        return text
     if args.trees in {"topology", "both"}:
         root = configured_root("topology.root", "OPENRIG_TOPOLOGY_ROOT")
         if root is None:
-            sections.append("## TOPOLOGY TRACE\nTRACE GAP — topology.root is unresolved")
+            sections.append(gap("## TOPOLOGY TRACE\nTRACE GAP — topology.root is unresolved"))
         else:
             start = Path(args.topology_start) if args.topology_start else derive_topology_start(root)
-            sections.append(render_topology(start, root, args.depth) if start else
-                            "## TOPOLOGY TRACE\nTRACE GAP — current topology node is unresolved; set OPENRIG_REFOCUS_TOPOLOGY_NODE")
+            sections.append(render_topology(start, root, args.depth, failures) if start else
+                            gap("## TOPOLOGY TRACE\nTRACE GAP — current topology node is unresolved; pass --topology-start with a literal absolute path (or configure OPENRIG_REFOCUS_TOPOLOGY_NODE separately)"))
 
     if args.trees in {"work", "both"}:
         root = configured_root("workspace.root", "OPENRIG_WORKSPACE_ROOT")
         if root is None:
-            sections.append("## WORK TRACE\nTRACE GAP — workspace.root is unresolved")
+            sections.append(gap("## WORK TRACE\nTRACE GAP — workspace.root is unresolved"))
         else:
             # Precedence: an explicit start wins; then the hook's daemon answer (basis or unknown);
             # only a standalone run with neither falls back to inferring from the working directory.
             explicit = args.work_start or os.environ.get("OPENRIG_REFOCUS_WORK_NODE")
             if explicit:
-                sections.append(render_work(Path(explicit), root, args.depth))
+                sections.append(render_work(Path(explicit), root, args.depth, failures))
             elif args.work_basis == NO_CURRENT_BATON_BASIS:
-                sections.append(render_work(root, root, args.depth, fallback=(
+                sections.append(render_work(root, root, args.depth, failures, fallback=(
                     f"no current typed baton ({args.work_basis}). Showing the project-level chain from the work root: "
                     "a broad orientation, not evidence of a current mission")))
             elif args.work_basis:
-                sections.append(f"## WORK TRACE\nTRACE GAP — no single current work node: {args.work_basis}")
+                sections.append(gap(f"## WORK TRACE\nTRACE GAP — no single current work node: {args.work_basis}"))
             elif args.work_unknown:
-                sections.append(f"## WORK TRACE\nTRACE GAP — current work node UNKNOWN: {args.work_unknown}")
+                sections.append(gap(f"## WORK TRACE\nTRACE GAP — current work node UNKNOWN: {args.work_unknown}"))
             else:
                 start = derive_work_start(root)
-                sections.append(render_work(start, root, args.depth) if start else
-                                "## WORK TRACE\nTRACE GAP — current work node is unresolved; set OPENRIG_REFOCUS_WORK_NODE")
+                sections.append(render_work(start, root, args.depth, failures) if start else
+                                gap("## WORK TRACE\nTRACE GAP — current work node is unresolved; pass --work-start with a literal absolute path (or configure OPENRIG_REFOCUS_WORK_NODE separately)"))
 
     print("\n\n".join(sections))
-    return 0
+    return 1 if args.check and failures else 0
 
 
 if __name__ == "__main__":

package/daemon/assets/plugins/openrig-core/skills/retiring-and-inheriting-a-seat/SKILL.md

@@ -61,6 +61,9 @@ threshold you can see coming; fall back to compaction only when a transition was
    cadence, on which surface, and who will hold it after cutover. Carry each duty both in this
    packet and in durable seat state, because recurring duties are the content most often lost at
    a generation boundary while urgent one-off work carries cleanly.
+   **Write the seat's recap too:** run `rig context recap-write --rig <rig> --seat <seat> --file <draft>`
+   alongside updating `LEARNED.md`. A `rebuild` reads `RECAP.md` before anything else. The format
+   the store checks is in `seat-continuity-and-handover`, "Write the seat's recap before a handover".
 3. **Prime the fresh successor** — `rig walk` the packet into the seat (paced delivery lets the
    successor absorb it in order), or launch-with-packet. The successor reads it as
    *inheritance*, not *identity*. **The packet's first-read line MUST point the successor at

package/daemon/assets/plugins/openrig-core/skills/seat-continuity-and-handover/SKILL.md

@@ -124,6 +124,48 @@ and provenance results independently. A help listing or dry-run is not proof of
 successful transition. The linked cutover SOP supplies the operator mechanics
 and required effect checks after the named owner authorizes the action.
 
+## Write the seat's recap before a handover
+
+A `rebuild` primes the successor from the seat's durable artifacts, highest trust
+first:
+1. the authored `RECAP.md`;
+2. `LEARNED.md`;
+3. the latest restore packet, when one is marked;
+4. the superseded recaps.
+
+A missing `RECAP.md` is recorded as a gap. The successor is directed to the remaining
+available artifacts in that order. So before a handover, a compaction or a long pause,
+the sitting occupant writes its recap alongside `LEARNED.md`:
+
+```sh
+rig context recap-write --rig <rig> --seat <seat> --file <draft.md>
+```
+
+- `<seat>` is the seat's folder under `rigs/<rig>/seats/`, the part of its session
+  name before `@`.
+- The command reads `topology.root` and doesn't need the daemon.
+- Each write moves the previous recap into the seat's `recap-superseded/` chain,
+  which later rebuilds also read. Write through this command, not a file tool, so
+  the chain is kept.
+
+**The store refuses the write, and writes nothing,** when a section can't be
+addressed. Only H2 and H3 headings are sections. Addresses lowercase the title,
+remove Markdown formatting markers, replace remaining runs outside `a-z`/`0-9` with
+a hyphen, and trim edge hyphens. Duplicate section paths, a nonblank H2/H3 title
+that normalizes to an empty slug, and an unclosed code fence are refused. A
+duplicate path is two H2s with the same address, or two H3s with the same address
+under one H2. Blank headings are retained as scope boundaries.
+
+**It writes, with an advisory on stderr,** when:
+- no H2 or H3 title contains "decision";
+- a line mentions "unverified" without the exact marker `UNVERIFIED:`.
+
+**A recap that passes the first time** has:
+- a short summary;
+- a `## Decisions, with reasons` section, each decision with its reason;
+- what's in flight and who owns the next step;
+- an `UNVERIFIED:` line for each fact you haven't checked yourself.
+
 ## Why load-bearing for RSI
 
 Any recursive seat-refresh loop must be able to replace an occupant

package/daemon/assets/plugins/openrig-core/skills/session-compaction-and-restore/SKILL.md

@@ -152,6 +152,12 @@ selected startup path, use `skills/core/agent-startup-and-context-ingestion/SKIL
 A packet or marker proves retained/delivered evidence, not successful provider
 restoration; measure the resumed seat against the proof standard above.
 
+Before a planned compaction, restart or long pause, write the seat's authored recap
+with `rig context recap-write --rig <rig> --seat <seat> --file <draft>`. Its format is
+in `seat-continuity-and-handover`, "Write the seat's recap before a handover". A
+rebuild reads it before `LEARNED.md`, and a profile source of `seat:RECAP.md` serves
+it after a restore.
+
 ## See also
 
 - `claude-compaction-restore` skill — the Claude Code restore SOP (PreCompact hook + JSONL restore script for post-compaction recovery)

package/daemon/assets/skills/rigs/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: rigs
+description: Use when the user mentions OpenRig, rigs or the rig command, or wants a team of coding agents (Claude Code, Codex) on their project. That includes installing, setting up, starting or updating OpenRig, seeing or getting back to their OpenRig agents, TUI or operator, starting or sharing a team, and joining this session to one.
+---
+
+# rigs: your route into OpenRig
+
+OpenRig runs a team of coding agents (Claude Code, Codex and others) side by side in tmux. A local daemon keeps their
+tasks, messages and state, so the team keeps working across restarts. This skill gets OpenRig installed, gets a team
+working on what the person wants, and shows how to work with that team from here.
+
+**The goal is a team doing the person's work, not just an install.** Go through the steps in order and stop early only
+if the person asks you to. When they say what they want built, give it to OpenRig's operator (step 2) instead of
+building it yourself.
+
+Tell the person what you're about to run and why before you run it. Don't install system packages or change their
+machine without a yes. Starting OpenRig and a team writes files: Codex hooks and settings in
+`~/.codex/config.toml`, a discovery skill in `~/.claude/skills` and `~/.agents/skills`, and, in the repository, managed
+guidance in `AGENTS.md` or `CLAUDE.md` plus the team's skills and plugins. Say so before you start OpenRig
+([the full list](https://github.com/mvschwarz/openrig#what-openrig-changes-on-your-machine)).
+
+## 1. Install OpenRig, if it isn't installed
+
+- **Check first:** `rig --version`. If it prints a version, go to step 2.
+- **What it needs:** macOS or Linux, Node.js 22 or 24, tmux, and Claude Code or Codex signed in. Check only what's
+  missing: `node --version`, `tmux -V`, `claude auth status` or `codex login status`.
+- **Install:** `npm install -g @openrig/cli`, then `rig preflight` (Node, tmux, the daemon port and state folders)
+  and `rig doctor`.
+- **Then go on to step 2:** say it's installed and ask what they want worked on, and in which repository. A plain
+  "install OpenRig" includes this. Stop here only if they say not to start a team.
+- **If something fails:** `rig context get help` is the help guide for the installed version. If `rig` itself won't
+  run, use https://www.openrig.dev/help/agents. Getting started: https://openrig.dev/docs/getting-started
+
+## 2. Open OpenRig and give its operator the goal
+
+- **Start OpenRig:** `rig daemon status`, and `rig daemon start` if it isn't running. `rig preflight` and `rig doctor`
+  don't start it. Starting it also starts OpenRig's own team, the kernel, whose operator sets up the person's team.
+  Keep it.
+- **Show them OpenRig, the handoff:** once OpenRig is running, open the OpenRig TUI and operator for the person. Say
+  you're opening it, then run `rig terminal open saved:kernel --window` on the daemon's desktop. This is the next step
+  after installing or starting OpenRig, and the way back whenever they want their agents or OpenRig again. Don't wait
+  to be asked or for particular words. If they've said not now, give them that command for later. It opens a view
+  itself, using herdr when installed or plain tmux otherwise:
+  - **Inside Herdr** (you run in a Herdr pane): it switches the person's Herdr to an `openrig kernel` space, reusing a live
+    one. No new window and no macOS prompt; their own spaces stay in the sidebar.
+  - **In Terminal or Ghostty:** a new tab or window the size of theirs.
+  - **From Claude Desktop, iTerm or VS Code on a Mac:** a new Ghostty window when supported, otherwise Terminal. Only
+    here, tell the person before running it that **Allow is fine** if macOS asks to control that app.
+    `echo $TERM_PROGRAM $__CFBundleIdentifier` tells you where you run. `herdr`, `Apple_Terminal` or `ghostty`, or
+    `tmux` with `com.apple.Terminal` or `com.mitchellh.ghostty`, mean no macOS prompt, so don't mention one. `tmux`
+    with anything else (iTerm, VS Code) can prompt, so say Allow is fine first.
+  - **Layout:** under 120 columns the operator fills the first page; from 120, the dashboard and operator share it. The
+    advisor has its own tab or tmux window.
+
+  Then tell the person in a sentence or two where it opened and that the operator is ready for what they want to
+  build. Don't list agents or statuses (the TUI shows them), and don't suggest a command for them to type.
+  Preserve the current terminal. If OpenRig's notes say it couldn't confirm the view, say so plainly. If it's already
+  open, point them to it rather than opening another. Only if the window cannot open, `rig tui --shared` is the
+  dashboard-only fallback; explain the failure and help with the chosen fallback. Herdr is visible only in a terminal
+  the person can see; switching the shared TUI to `:terminals` does not open one. No and headless/SSH use are valid
+  background outcomes. Provider-only `--provider herdr` or `--provider cmux` is for an existing provider workspace,
+  not the first desktop window.
+- **If the window can't open, or over headless SSH:** say plainly that no visible terminal was opened, and ask the
+  person to open a new terminal window or tab on the daemon's host. Over SSH, that's a new SSH session to it with the
+  known account. If you only know an HTTP daemon address, ask for the SSH details rather than inventing them. Then
+  give them one complete command:
+  - **The command OpenRig printed:** when `rig terminal open saved:kernel --window` can't open a window, it says why
+    and ends with `run:` and a command (the `error` field with `--json`). That command already names the installed
+    herdr binary and the daemon's socket, or the conversation to attach. Relay it exactly rather than composing one.
+    If a note asks you to place the view once Herdr starts, run that `rig terminal open` yourself after they start it.
+  - **If it printed no command:** find `operator.agent` in `rig ps --nodes --rig kernel --json`, take its
+    `canonicalSessionName` (never a guessed name) and give
+    `env -u TMUX tmux attach-session -t '=<canonicalSessionName>'` for the operator's conversation.
+
+  For any other failure, the table under "What can interrupt installation and the OpenRig view" in
+  `rig context get reference/getting-started.md#open-the-kernel-conversations` says why and what to do next.
+- **Give the operator the goal:** ask what they want worked on, in which repository and on which branch, unless they've
+  said. Find the `operator.agent` row in `rig ps --nodes --rig kernel --json`, take its `canonicalSessionName`
+  (never the logical ID or a guessed name) and send:
+  `rig send <canonicalSessionName> 'This is the agent that installed OpenRig. The person will answer in your pane. Goal: <goal>. Project folder: <absolute path>. Branch: <branch>.'`
+  Or the person types the goal and folder in the operator's pane. If they give you a goal later, forward it the same
+  way. The operator helps them pick a team that fits their logins, starts it on their yes and gives the goal to the
+  team's lead. Show them where the operator answers, and don't build the project yourself.
+- **Relay the operator's questions:** the operator asks in its own pane, and the person may not be looking there.
+  After each step you hand it, read its screen with `rig capture <canonicalSessionName>`. When it asks the person
+  something (start this team? which folder? which option?), ask them here in the operator's words and send their
+  answer back with `rig send`, or tell them to answer in the operator's pane. Unlike a prompt or a menu, a question
+  doesn't show up as a stopped seat, so don't leave it to a background wait.
+- **Installation is finished** when the operator is ready and the person is talking to it; a healthy daemon alone isn't
+  that. If they'd rather talk later, keep that choice, leave them the exact connection step and say the handoff to the
+  operator is still pending.
+- **See what's running:** `rig ps`, then `rig ps --nodes --rig <rig>` for a team's agents. If a team is already
+  running in that repository, tell the operator.
+- **Check it's ready before you say so:** `rig ps --nodes --rig <rig>`. If an agent is stopped at a prompt or a menu,
+  read it with `rig capture <seat>@<rig>` and answer with the key that screen shows (`rig send --help` says how to
+  send a digit, a letter or Escape), or ask the person. Capture it again before sending anything more.
+- **Join this session to the team, if that helps:**
+  `rig attach --self --rig <rigId> --pod <pod> --member <name> --runtime <claude-code|codex> --print-env` adds this
+  session as a new member of a pod. `--node <logicalId>` binds it to an existing seat instead. Attach once, and keep
+  the variables it prints (`OPENRIG_NODE_ID` and `OPENRIG_SESSION_NAME`). Each command may run in a fresh shell, so put
+  them in front of every later `rig` command. Check with `rig whoami --json`.
+- **Replies:** other agents can't type into this session. Read work sent to you with
+  `rig queue list --destination <your address>` and `rig queue show <id> --full`, and read an agent's screen with
+  `rig capture <seat>@<rig>`.
+
+## 3. Follow the work to its result
+
+- **Find the team's task:** the operator gives the goal to the team's lead as a queue task: `dev-build@starter`, or
+  `orch-lead` in `workshop` and `factory` (for starter and factory, `rig specs preview <name> --kind rig` says what
+  each seat does; for a running team, `rig ps --nodes --rig <rig>`). Find it with
+  `rig queue list --destination <seat>@<rig> -a`.
+- **Follow it to the result:** a task that changed hands isn't finished. `rig queue show <id> --full` names the seat it
+  went to, and that seat's next task is the one whose `handedOffFrom` is that ID
+  (`rig queue list --destination <seat>@<rig> -a -o json`). Follow each handoff until an agent reports the result, and
+  use `rig capture <seat>@<rig>` to see what it's doing. Then read what it produced and tell the person what the team
+  actually did (the branch, commit, review or PR text), not just that you sent it.
+- **Give the team more work:** write the goal to a file: what to change, in which repository and branch, what done
+  looks like, and that the result comes back to you (the branch or commit, the review, any PR text). Then
+  `rig queue create --source <your name> --destination <seat>@<rig> --body-file <file>`, and tell that agent with
+  `rig send <seat>@<rig> "task <id> is yours"`. A message informs, and a queue task is the work someone owns.
+  `--source` names you when this session hasn't joined the team.
+- **Then ask what's next.** If no team can take the work, fix that or ask the person. Don't quietly do it yourself.
+- **Other ways to work with the team:** `rig send <seat>@<rig> "..."` types into an agent's terminal,
+  `rig capture <seat>@<rig>` reads its screen, and `rig ps --nodes --rig <rig>` shows who's on it.
+
+## 4. Find out more
+
+- **How OpenRig works:** `rig context profile world-public --situation fresh`.
+- **What you can do:** `rig context get onboarding-width` (the capability map).
+- **Everything in the library:** `rig context list`.
+- **Exact syntax:** `rig <command> --help` is always current for the installed version.
+
+Written for OpenRig 0.6.7. When something here and `--help` disagree, `--help` wins.