@openrig/cli 0.6.5 → 0.6.7

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.

package/daemon/context-packs/help/help.md

@@ -1,13 +1,14 @@
 # Help your user get unstuck
 
 This page is for an agent whose user says OpenRig isn't working. It is the one place OpenRig keeps this guidance. The
-copy installed with OpenRig matches that installed version. Read it with `rig context get help`. If `rig` won't run,
-open `daemon/docs/reference/help.md` inside the installed `@openrig/cli` package (under `npm root -g`); in the source
+copy installed with OpenRig matches that installed version. Read it with `rig context get help`, which needs a running
+daemon. If `rig` won't run or the daemon is down, open `daemon/docs/reference/help.md` inside the installed
+`@openrig/cli` package (under `npm root -g`); in the source
 repository the same file is `docs/reference/help.md`. The same text is online at
 [openrig.dev/help/agents](https://www.openrig.dev/help/agents), next to the ways people can contact OpenRig support.
 
 Each guide this page links to is installed too. Load one only when you need it, with the `rig context get` address
-shown beside its link; the same files sit beside this one in `daemon/docs/reference/`.
+shown beside its link where there is one; every linked file also sits beside this one in `daemon/docs/reference/`.
 
 Start with what your user was trying to do. Try the next useful step, check the result, and if you can't finish,
 prepare a message to OpenRig support at **hello@openrig.dev**. Your user doesn't need a GitHub account.
@@ -23,7 +24,10 @@ rig doctor --json
 ```
 
 Use the installed command's `--help` if an option is unavailable. Read the diagnostic findings; don't treat them as
-instructions to reset the machine.
+instructions to reset the machine. `rig doctor` checks Claude and Codex authentication using the same local checks
+as setup, including a configured Codex provider credential variable. A set variable does not prove that the provider accepts it or that managed
+seats receive it. Doctor does not run an agent task: also inspect `rig ps --nodes --rig <rig>`. If the daemon is involved, `rig daemon status` and `rig daemon logs` show its state
+and recent output.
 
 **If OpenRig won't install or `rig` won't run, start here anyway.** Record the attempted package version, install
 command and error. Leave unknown values unknown. A working daemon or a passing diagnostic is not required to ask for
@@ -32,17 +36,58 @@ help.
 ## Match the guidance to the installed version
 
 The reference documents beside this file describe the version they were installed with. GitHub's default branch can
-contain changes that haven't reached your user's version. For release notes and known limitations, open
-`https://github.com/mvschwarz/openrig/blob/v<version>/docs/releases/v<version>.md`, using the version from
-`rig --version`. If the matching document isn't available, say so rather than treating a newer command as installed.
+contain changes that haven't reached your user's version. After an upgrade, start with the short note on what changed
+in the installed version: `rig context get reference/whats-new.md`. For full release notes and known limitations, open
+`https://github.com/mvschwarz/openrig/blob/v<version>/docs/releases/v<version>.md`, using the version number from
+`rig --version` (without the commit it may show in parentheses). When that file doesn't exist, use the version's
+section of `https://github.com/mvschwarz/openrig/blob/v<version>/CHANGELOG.md`. If neither is available, say so
+rather than treating a newer command as installed.
 
 ## Find your next step
 
 ### Installation or platform problems
 
-Supported platforms are macOS and Linux. Native Windows is not supported yet, and WSL2 has not been tested. OpenRig needs
-Node.js 22 or 24 and tmux. A WSL error needs its actual versions, commands and error text; don't assume a
-Windows-related pull request fixes it.
+Supported platforms are macOS and Linux, and WSL2 on Windows; native Windows isn't supported. OpenRig's automated tests
+don't run on WSL2 yet; one user's [reported working setup](getting-started.md#wsl2-a-reported-working-setup) lists what
+mattered. OpenRig needs
+Node.js 22 or 24 and tmux. A Linux distribution's own Node.js can be older; check `node --version`. With npm 11 or
+later, an `npm warn install-scripts` line for `@openrig/cli` means only the postinstall Node.js and SQLite check was
+skipped; `node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"` runs it. A WSL error needs its actual versions,
+commands and error text; don't assume a Windows-related pull request fixes it.
+
+The one-command install ([getting-started](getting-started.md#install-and-sign-in)) prints its plan with
+`--dry-run` and changes nothing. When a step fails it prints `FAILED [n/4] <command or check> (exit <code>)` and
+stops. Read its diagnostic: if it names a runnable command, run that command by hand for the full error and record it
+in a report; otherwise follow the accompanying diagnostic. If the only remaining failures are provider sign-ins under
+"Some steps need attention", the install steps finished: sign in to each selected provider and continue.
+
+### Installation finished, but there is nobody to talk to
+
+Load the `rigs` skill and follow its step 2: it opens the OpenRig view (`rig terminal open saved:kernel --window`),
+gives the attach commands when the window can't open or over SSH, and hands the person's goal to the operator.
+[Install and sign in](getting-started.md#install-and-sign-in) says how to load it. The reference for the view, manual
+attachment and the table of what can interrupt it is
+[Open the kernel conversations](getting-started.md#open-the-kernel-conversations)
+(`rig context get reference/getting-started.md#open-the-kernel-conversations`). Started is not ready: the view can
+open while the kernel's agents finish starting, and opening it creates no other kernel or account.
+
+### A step interrupted setup or the OpenRig view
+
+Name the exact command and result, the reason it stopped and the next useful step. A harness's permission rules,
+sandbox or automatic permission decision can refuse an installing agent's tool call before OpenRig runs.
+Claude Code's [auto mode can deny calls](https://code.claude.com/docs/en/auto-mode-config); explain the reported
+refusal and let the person review that step in their harness controls or run it themselves, within their chosen
+permissions. Do not silently claim installation failed or completed from a refused call.
+
+For missing tools, downloads or selected logins, use the specific setup hint. A Herdr install warning leaves plain
+tmux available. A requested Ghostty install can fail setup; resolve it or decline with `--no-ghostty` and keep the
+earlier choices. Terminal.app remains available; required tools and logins still matter. macOS may ask for
+Automation permission; a missing display or remote daemon needs the documented headless/manual route.
+Herdr may show an intro (Return to continue) and an agent-integration panel (Esc to close); the view does not
+require installing those integrations. Enlarge a cramped 80×24 window. Use authorized desktop tools to inspect the
+window contents, or state that visibility is unconfirmed and ask the person to check. A successful command or
+window listing alone is not visual proof. The [OpenRig view guide and friction table](getting-started.md#open-the-kernel-conversations)
+connects each observation to its next step. Preserve existing conversations while resolving it.
 
 ### The team did not start, or a terminal is missing
 
@@ -67,6 +112,14 @@ and `rig ps --nodes --rig <rig-name>`, then compare the reported state with what
 A waiting prompt, a failed launch and an agent working behind a stale status need different next steps. Repeatedly
 clearing attention doesn't fix an underlying readiness problem.
 
+A fresh seat stopped at a native prompt (Claude's bypass-permissions warning, a login or a folder-trust question)
+keeps its startup context. `rig up`, `rig bundle install` and `rig ps --nodes` print "Startup attention" or "Startup
+details" for it, ending with the command to run. Once your user has answered the prompt in that seat's terminal,
+`rig seat continue <seat>` delivers the context in the same conversation, without relaunching. If it reports an
+unknown outcome, check `rig seat status <seat>` before trying again. For a rig whose seats bypass permissions,
+`--non-interruptive` on `rig up` or `rig bundle install` avoids Claude's warning and Codex's notices in the first
+place; see `non-interruptive-mode.md` beside this file.
+
 ### You can't tell which instance or configuration is involved
 
 Read [instance layout](instance-layout.md) (`rig context get reference/instance-layout.md`) and
@@ -87,8 +140,9 @@ issue's current status; a similar symptom alone is not a diagnosis.
 - A Codex seat on the default `workspace-write` sandbox starts without network access, so it can't reach the local
   daemon, when its Codex configuration sets network access off, a managed requirement could restrict it, or Codex
   doesn't answer OpenRig's configuration read in time: [#275](https://github.com/mvschwarz/openrig/issues/275).
-- Stopping the daemon can report a timeout while closing connections:
-  [#166](https://github.com/mvschwarz/openrig/issues/166).
+- Kernel seats fail within a second of the first start on a distribution tmux whose server exits on `capture-pane`
+  (`tmux -V` prints `next-3.4`): [#980](https://github.com/mvschwarz/openrig/issues/980). The check and recovery
+  are in [Incomplete setup and restart](getting-started.md#incomplete-setup-and-restart).
 
 For everything else, search [open issues](https://github.com/mvschwarz/openrig/issues).
 

package/daemon/context-packs/help/manifest.yaml

@@ -1,6 +1,6 @@
 # Agent help: the single troubleshooting and escalation guide (docs/reference/help.md).
 name: help
-version: "0.6.5"
+version: "0.6.7"
 taxonomy: world
 purpose: "What an agent does when its user says OpenRig isn't working: diagnose, fix within permissions, verify, and escalate to OpenRig support."
 files:

package/daemon/context-packs/onboarding-width/manifest.yaml

@@ -1,6 +1,6 @@
 # Public capability and source-map width for the default onboarding walk.
 name: onboarding-width
-version: "0.6.5"
+version: "0.6.7"
 taxonomy: world
 purpose: "The public capability map and source map referenced by the default onboarding walk."
 files: