@openrig/cli 0.6.13 → 0.7.0

package/daemon/docs/reference/getting-started.md

@@ -1,20 +1,66 @@
-# Getting started: meet the kernel, then make one useful change
-
-Install OpenRig, use a working provider login, and meet the kernel operator with
-the advisor and TUI beside it. No starter team is needed to reach that view.
-Tell the operator what you want to do, then choose a project team for a bounded
-change you can exercise. Reuse the accounts and terminal tools you already have.
-
-After installation and sign-in, your agent opens the **OpenRig TUI and operator** for you. The path is `rig daemon start` (if stopped),
-then `rig terminal open saved:kernel --window`. The second command opens the
-desktop window itself. An agent can run it from its shell on the daemon's
-desktop; it does not need to type into your current terminal. See
-[Open the kernel conversations](#open-the-kernel-conversations).
-`rig tui` is the team dashboard; installation ends when you are talking to the
-operator in the OpenRig view.
+# OpenRig setup reference
+
+This is the full reference for installing and running OpenRig, written for the agent doing the setup and for anyone
+who wants the detail. The short version for people is [Getting started](quickstart.md).
+
+## For the agent doing the setup
+
+The `rigs` skill is the procedure: follow it in order. This page is what it looks things up in.
+
+- **Done** means the person is talking to the operator in a visible OpenRig view. A healthy daemon, a started kernel
+  or an opened window isn't done on its own. If they'd rather talk later, the handoff is still pending: say so, and
+  leave them the exact command.
+- **Read readiness; don't assume it:**
+  - **The kernel:** the `Kernel:` line in `rig status`, and `rig ps --nodes --rig kernel`.
+  - **A team:** `rig ps --nodes --rig <team>`.
+  - A missing or unknown signal isn't ready.
+  - `rig up` exiting 1 with `Status: partial` and `Startup attention` means a seat is waiting at a prompt. Answer it,
+    or ask the person to, then run the `rig seat continue <seat>` it names.
+- **Prerequisites:** check the person's existing toolchain first (mise, nvm, Homebrew or the nodejs.org installer)
+  and the PATH. Use what's there. Don't change a shared Homebrew's ownership, and don't make a local workaround the
+  standard route. If Node.js is installed after your session started, check that new shells and the session's hooks
+  can find it. In one published-0.6.11 Mac run, OpenRig's Claude hooks reported `node: command not found` until the
+  PATH was fixed.
+- **Ask once, then reuse the answer:** the provider (Claude Code, Codex or both), Herdr, Ghostty on macOS,
+  remembered command allowances, and the team.
+- **Before changing their machine:** say what applies to their route, then wait for a yes. See
+  [what OpenRig changes on your machine](../../README.md#what-openrig-changes-on-your-machine).
+- **When something stops:**
+  - [Incomplete setup and restart](#incomplete-setup-and-restart) maps what you see to the next action.
+  - [What can interrupt installation and the OpenRig view](#what-can-interrupt-installation-and-the-openrig-view)
+    covers the view.
+  - [Headless or SSH handoff](#headless-or-ssh-handoff) covers no-display cases.
+  - A timed-out command may still have taken effect. Read `rig ps` or `rig seat status <seat>` before you run it
+    again.
+- **Don't:**
+  - relaunch a team to reopen its view;
+  - start another seat to clear a prompt;
+  - build the person's project yourself. Give the goal to the operator.
 
 ## Before you start
 
+> **What OpenRig changes on your machine**
+> - **Install:** `@openrig/cli` goes in globally with npm.
+> - **Setup:** `rig setup` adds an OpenRig block to `~/.tmux.conf`. It can install tmux (with Homebrew on macOS), and
+>   Herdr unless you pass `--no-herdr`. Plain `rig setup`, which is what the one-command install runs, checks both
+>   Claude Code and Codex and may install a missing one; `rig setup --providers claude` (or `codex`) limits it to
+>   yours.
+> - **Starting OpenRig, for the coding agent you use** (paths are the usual defaults):
+>   - Codex: hooks and trust in `~/.codex/config.toml`.
+>   - Claude Code: workspace trust in `~/.claude.json`, and activity hooks in the project's
+>     `.claude/settings.local.json`, plus a status line unless you already have your own.
+>   - Discovery skills go in `~/.claude/skills` and `~/.agents/skills`.
+> - **Starting a team in your project:** adds managed guidance to `AGENTS.md` or `CLAUDE.md`, plus the team's skills
+>   and plugins.
+> - **Permissions:** by default, OpenRig's own kernel gets broader permissions than a project team gets by default.
+>   On Codex that's full access with no approval prompts (`-s danger-full-access -a never`). On Claude Code, its file
+>   tools, web fetches and operational commands, including reads under your home folder, run without asking. A
+>   permission policy, per-agent choice or Codex profile changes that. What your team can do depends on the team you
+>   choose and your settings; `workshop`, for example, ships with broad access.
+> - **Backups:** OpenRig doesn't guarantee it can preserve or roll back these files, so back them up first.
+>
+> [Everything OpenRig writes, and why →](https://github.com/mvschwarz/openrig#what-openrig-changes-on-your-machine)
+
 You need Node.js 22 or 24 and tmux, on macOS or Linux, and one working Claude
 Code or Codex account: one is enough, since the kernel operator adapts the
 shipped `starter` team to whichever you have. On Linux, the distribution's own
@@ -26,12 +72,16 @@ you aren't an administrator, or where Homebrew belongs to another account (its
 `brew install` is refused), install Node.js in your own home folder with
 [nvm](https://github.com/nvm-sh/nvm): run `touch ~/.zshrc` (a new Mac account
 has none, and nvm's installer only adds itself to a profile file that already
-exists), then the install command on nvm's page, open a new terminal, and run
-`nvm install 22`. That needs no administrator password, and `npm install -g`
-then installs into your nvm folder. Native
-Windows isn't supported. On Windows, use WSL2: it's the Windows route OpenRig
-supports, though OpenRig's automated tests don't run on it yet. One user's
-[working setup](#wsl2-a-reported-working-setup) is below. Node 20 and
+exists), then nvm's install command, for nvm v0.40.8
+`curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash`
+([nvm's page](https://github.com/nvm-sh/nvm#install--update-script) has the
+newest), open a new terminal, and run `nvm install 22`. nvm itself needs no
+administrator password, and `npm install -g` then installs into your nvm folder.
+If nvm's installer says you need Apple's command line tools, run
+`xcode-select --install`, then its install command again. Native Windows isn't
+supported. On Windows, use WSL2: it's the Windows route
+OpenRig supports, though OpenRig's automated tests don't run on it yet. One
+user's [working setup](#wsl2-a-reported-working-setup) is below. Node 20 and
 odd-numbered releases (23, 25 and so on) are not supported; Node 26 and later
 even-numbered releases are untested.
 
@@ -131,20 +181,19 @@ You can also read [`skills/rigs/SKILL.md`](../../skills/rigs/SKILL.md) directly.
 script will do and changes nothing:
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.13/scripts/install.sh | sh -s -- --dry-run
+curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.0/scripts/install.sh | sh -s -- --dry-run
 ```
 
 The same command without `--dry-run`,
-`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.13/scripts/install.sh | sh`, installs the
+`curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.0/scripts/install.sh | sh`, installs the
 latest published `@openrig/cli` with `npm install -g`,
 runs the Node.js and SQLite check, then `rig setup --dry-run` and `rig setup`. `rig setup` checks both Claude Code and
-Codex and may install a missing one, as described below. A failed step among the first three prints
-`FAILED [n/4] <command or check> (exit <code>)`. When `rig setup` (step 4) doesn't finish ready, for example because a
-provider isn't signed in yet, the script ends with `INSTALLED, SETUP NOT COMPLETE (exit <code>)`: the CLI is
-installed, and `rig setup` lists what's left under "Some steps need attention". If the only items left are provider
-sign-ins, sign in to each selected provider as below, then continue at
-[Start the kernel](#start-the-kernel-and-check-its-state); run `rig setup` again rather than reinstalling the CLI. To
-install only what the selected providers need, go step by step instead:
+Codex and may install a missing one, as described below. A failed step prints
+`FAILED [n/4] <command or check> (exit <code>)`. Where a provider isn't signed in yet, step 4 ends that way and
+`rig setup` lists each sign-in under "Some steps need attention". If the only remaining failures are provider
+sign-ins, the install steps finished: sign in to each selected provider as below, then continue at
+[Start the kernel](#start-the-kernel-and-check-its-state). To install only what the selected providers need, go step
+by step instead:
 
 ### Choose your providers
 
@@ -174,6 +223,26 @@ writes an OpenRig-managed block (mouse on, a longer history) into `~/.tmux.conf`
 It is optional for this selected-provider path, not a requirement to fix an unused
 provider.
 
+The block keeps `terminal.history_limit` rows of scrollback per pane (default
+10000). To keep more, run `rig config set terminal.history_limit 50000`, then
+`rig setup` again. A running tmux server keeps its old limit until it restarts
+or you run `tmux source-file ~/.tmux.conf`; before tmux 3.7 that changes new
+panes only.
+
+New managed agents and handover successors on macOS/Linux start from the daemon's
+selected launch environment and declared seat values, rather than stored tmux globals.
+Values named by tmux's `update-environment` option, including its default SSH-agent
+and display variables, come from the daemon's environment.
+Normal shell startup and configured tmux shell commands still run. If your custom setup
+intentionally supplies values through tmux's global environment, opt in with
+`rig config set terminal.inherit_tmux_environment true`. Setup points out this option
+when it detects custom tmux configuration; it never enables it automatically. The setting
+applies to future launches and successors, not running agents or your personal tmux server.
+If the scoped environment cannot be prepared, launch keeps its previous environment and
+reports a warning in fresh launch results and the daemon log. For handovers, check
+that log for this warning. This is not a promise that shell startup cannot add or override values.
+
+
 ## Start the kernel and check its state
 
 With a working selected login, start the daemon if it is stopped, then read its
@@ -205,9 +274,51 @@ A missing or unknown readiness signal is not proof of readiness. Follow
 startup or missing-seat problems.
 
 `rig setup` itself does not start the daemon. Preserve a daemon and kernel that
-already exist: ordinary daemon startup skips a managed kernel, and
-`OPENRIG_NO_KERNEL=1` skips automatic kernel startup. If neither runtime is
-authenticated, kernel boot reports `auth_blocked`. Do not restart or recreate an
+already exist: daemon startup does not boot a second kernel when one is managed,
+and `OPENRIG_NO_KERNEL=1` (`--no-kernel`) skips automatic kernel startup,
+including the restore below. If neither runtime is authenticated, kernel boot
+reports `auth_blocked`.
+
+Daemon startup restores one existing kernel by itself: a managed kernel whose
+seats are all `detached` and still bound to their newest session, which is what
+startup reconcile leaves when every kernel terminal is gone, for example after a
+reboot. It does not detect a reboot as such. It uses the same restore as
+`rig up kernel --existing`, and `rig status` reports it as `Kernel: booting`
+until the seats are ready. A kernel stopped with `rig down kernel`, including
+one whose seats were already detached, stays down on later starts. So do a kernel
+with only some seats stopped and seats you unclaimed. Start one again with
+`rig up kernel --existing`.
+When the tmux server is gone, an explicit `rig down` of any rig can start an
+empty server and probe again. It records the stop and clears eligible bindings
+only after confirming the sessions are absent. This can leave an empty tmux
+server running; it never launches an agent or provider session. Unreadable or
+permission results and changed occupants leave the stop bookkeeping unchanged.
+
+While that automatic restore runs, `rig start` continues to your other rigs and
+says the kernel is still restoring (`kernelRestore.state: "restoring"` with
+`--json`). Its exit status 0 then does not mean the kernel is ready; check
+`rig status`. When the restore has returned without a ready kernel, `rig start`
+still goes on to your other rigs but exits 1 (`kernelRestore.state: "failed"`),
+so `rig start && next` does not run `next`. A `rig down kernel` made during the
+restore waits for it to return and then stops the kernel, which stays down on
+later starts. A `rig up kernel --existing` with no fresh seats and no change to
+the saved non-interruptive choice, made during the restore, or after it restored
+every seat while those seats still run the sessions it started, reports that
+restore's outcome instead of starting another. Explicitly repeating the saved
+`--non-interruptive` or `--no-non-interruptive` choice also joins that restore.
+
+An explicit `rig up kernel --existing --fresh <seat...>` waits for startup's
+restore to finish, then replaces only the named seats that still hold the exact
+sessions startup launched. Other seats keep running. An operator's conversation
+correction also takes effect for that seat on the next explicit `up` or
+`restore`, using the corrected target; editing the token alone restarts nothing.
+Each replacement takes new seat leases, rechecks the managed occupant and terminal,
+and reports its own per-seat outcome. If the occupant changed, it is left alone.
+A different `--non-interruptive` or `--no-non-interruptive` choice after startup
+launched the seats is refused: the running launch choice stays unchanged. Stop
+the rig, then rerun with the desired choice.
+
+Do not restart or recreate an
 existing kernel merely to open its view. The startup TUI (`rig`) offers its own
 kernel setup and individual-seat recovery; it does not automatically boot agents
 when it starts the daemon.
@@ -644,7 +755,7 @@ the lifecycle API without booting a new kernel, then stop the remaining rigs.
 | Shared terminal is absent | Inspect the existing kernel binding and recovery state; use standalone `rig tui` while resolving it. |
 | Viewing terminal was closed | Open the conversations again with `rig terminal open saved:kernel --window`; `rig tui --shared` is only the dashboard fallback if that window cannot open. Do not relaunch the team. |
 | Daemon restarted but tmux survived | Re-read `rig status` and the existing queue; a daemon restart is not a fresh project. |
-| Host reboot lost tmux sessions | Open `rig`, start the daemon if needed (press **S** if it opens on the work views), and select the existing rig and seats. Resume is the default; a fresh conversation needs a separate decision. |
+| Host reboot lost tmux sessions | Starting the daemon restores the kernel by itself when all of its seats were lost; check `rig status`, and if it reports the restore failed, run `rig up kernel --existing`. For other rigs, open `rig`, start the daemon if needed (press **S** if it opens on the work views), and select the existing rig and seats. Resume is the default; a fresh conversation needs a separate decision. |
 | Launch reports no usable snapshot | Inspect the existing rig and retained project files, then follow the same-seat recovery below. |
 | Work is waiting on a prompt or decision | Read the row, transition and named prompt; preserve the obligation until the missing decision arrives. |
 
@@ -675,8 +786,9 @@ This recovery is for the case the reporter hit: the kernel's seats failed and no
 IDs, for example `advisor.lead operator.agent operator.human queue.worker` when all four failed. `--fresh` starts a
 new conversation for each seat you name. Seats you don't name follow their normal recovery policy and may remain
 awaiting a decision if their old conversation can't be resumed. A later `rig daemon start` doesn't retry the failed
-seats by itself: once a kernel exists, startup skips the built-in kernel boot, and `rig status` then reads
-`Kernel: skipped` whatever its seats' state, so check `rig ps --nodes --rig kernel --full`.
+seats by itself: once a kernel exists, startup skips the built-in kernel boot and restores only a kernel whose seats
+were all lost, not seats that failed. `rig status` then reads `Kernel: skipped` unless some of its seats are running
+and ready, so check `rig ps --nodes --rig kernel --full`.
 
 If a snapshot is unavailable, the startup view checks the selected seat's
 retained startup source and authoritative occupant relation. It reports a
@@ -995,6 +1107,37 @@ same-seat stop/resume path after checking its retained policy; do not erase the
 rig or start a duplicate to reset permissions. A resume can reapply the stored
 launch mode, so verify the native mode again before continuing work.
 
+## Optional Mac local-user check
+
+On a Mac shared by multiple OS accounts, `transport.local_user_guard` can reduce
+accidental CLI routing to another account's local daemon. It is **off by default**.
+Enable it with `rig config set transport.local_user_guard true`, or set
+`OPENRIG_TRANSPORT_LOCAL_USER_GUARD=true` in the CLI's environment. Set it to
+`false` to turn it off; no daemon restart is needed for the CLI check.
+
+When enabled, automatic local CLI data requests compare the daemon's reported
+`/healthz` PID and effective UID (`euid`) with two `ps` UID/start observations and
+a second health response, with at most one second of observation per check.
+Only stable agreement on a foreign effective UID stops the request. This does
+not require visibility into another user's socket descriptors. It does not
+stop the daemon, choose another port or retry. Diagnostic health/status checks
+remain available. Older daemons without `euid` remain unknown and are permitted.
+`sudo rig …` uses the caller's **effective** UID, so an enabled check against a
+user-owned daemon refuses when its reported/observed UID differs from root.
+
+Explicit `OPENRIG_URL`/`RIGGED_URL` targets and registered remote hosts retain
+their selected routing, including tunnels. An internally resolved local URL is
+still checked. Default UI and TUI openings are checked before launch; this does
+not police later browser or TUI connections.
+
+Missing, disagreeing, restricted or timed-out evidence **continues today's
+behavior**. This is a partial accidental-routing check, not authenticated user
+isolation: it trusts the daemon's PID/UID report and corroborates that process;
+it does not establish the socket's owner. Identity can change between observation
+and connection, and equal UIDs do not distinguish separate instances belonging
+to one account. The check
+does not add authentication to the daemon or protect direct HTTP clients.
+
 ## Custom settings and precedence
 
 - **OpenRig:** member `permission_policy` overrides rig `permission_policy`.

package/daemon/docs/reference/quickstart.md

@@ -0,0 +1,200 @@
+# Getting started
+
+OpenRig runs a team of coding agents (Claude Code, Codex and others) on your project, each in its own terminal. You
+talk to one agent, and it hands work to the others. The team keeps its tasks and messages between sessions.
+
+Most people let their coding agent set it up. This page explains what happens either way, so nothing is a black
+box, and shows how to do each step by hand if you'd rather.
+
+## The quick way: let your coding agent do it
+
+In your project folder, add OpenRig's `rigs` skill to the agent you use:
+
+```sh
+# Claude Code
+npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs --skill rigs --agent claude-code
+# Codex
+npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs --skill rigs --agent codex
+```
+
+For a new install, use the latest release's tag, for example `v0.7.0`. If OpenRig is already installed, use the tag
+that matches `rig --version`, or upgrade first. If the command fails with `npx: command not found`, Node.js isn't
+installed or isn't on your PATH yet (see [What you need](#what-you-need)). Then type `/rigs` in Claude Code, or `$rigs` in Codex, and say what
+you want built.
+
+The skill has your agent work through the steps below in order. It says what it will run and change before it runs
+it, and it asks before installing anything on your system. It finishes when you're talking to the operator.
+
+## How the pieces fit
+
+- **`rig`** is the command you and your agents use. It comes from the npm package `@openrig/cli`.
+- **The daemon** is a small background service on your machine. It keeps tasks, messages and state in a local
+  database. `rig daemon start` starts it.
+- **tmux** runs each agent in its own terminal session. Agents keep running when you close a window, and one agent
+  can type into another's terminal.
+- **The kernel** is OpenRig's own small team, which starts with the daemon. You talk to its **operator**, which
+  starts and runs teams for you. Its **advisor** helps you think through what you want.
+- **Your team** (a *rig*) is the set of agents that work on your project, such as `starter`.
+- **The OpenRig view** is a terminal window with the operator and, beside it or on another page, a dashboard of your
+  agents.
+
+## What you need
+
+- macOS or Linux. On Windows, use WSL2 ([one person's working setup](getting-started.md#wsl2-a-reported-working-setup)).
+- Node.js 22 or 24 (on Apple silicon, Node.js 22) and tmux.
+- Claude Code or Codex, signed in. One is enough to start.
+
+If `node --version` does not show a supported version, first check your existing Node installation and PATH.
+Ask your coding agent to help use the toolchain already on your machine. On a Mac, a shared Homebrew installation
+may belong to another user; do not change its ownership to complete this setup. After correcting PATH or installing
+Node, open a new terminal and check `node --version` and `npx --version` before continuing.
+
+On a Mac where you aren't an administrator, or where another account owns Homebrew, install Node.js in your own home
+folder with [nvm](https://github.com/nvm-sh/nvm); nvm itself needs no administrator password. A new Mac account has no
+`~/.zshrc`, and nvm's installer only adds itself to a profile file that already exists, so create one first:
+
+```sh
+touch ~/.zshrc
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
+```
+
+Then open a new terminal and run `nvm install 22`. If nvm's installer says you need Apple's command line tools, run
+`xcode-select --install`, then its install command again. That's nvm v0.40.8's install command; [nvm's
+page](https://github.com/nvm-sh/nvm#install--update-script) has the newest.
+
+## What happens, step by step
+
+Each step shows the command, so you can run it yourself.
+
+### 1. Install the `rig` command
+
+```sh
+npm install -g @openrig/cli
+rig --version
+```
+
+This installs the CLI globally under your npm prefix. `rig --version` prints the version and a commit, such as
+`0.6.12 (9e5382dd)`. With npm 11 or later, an `npm warn install-scripts` line is expected: it means only the
+Node.js and SQLite check was skipped.
+
+### 2. Set up the tools around it
+
+```sh
+rig setup --providers claude
+```
+
+Use `codex` or `both` in place of `claude` to match the coding agents you use. Add `--dry-run` first to see the plan without changing anything. Setup does four things:
+- it checks Node.js, tmux and your sign-in;
+- it installs a missing tmux (with Homebrew on macOS, if you have it) or the coding agent you chose;
+- it installs Herdr, a terminal workspace app the OpenRig view can use, unless you add `--no-herdr`;
+- it adds an OpenRig block to `~/.tmux.conf` (mouse support and longer scrollback).
+
+It doesn't start anything. It ends with a summary of what's done and what still needs you. A missing sign-in shows
+there: run `claude auth login` or `codex login`, then carry on.
+
+### 3. Start OpenRig
+
+```sh
+rig daemon start
+rig status
+rig ps --nodes --rig kernel
+```
+
+The daemon starts and boots the kernel with the coding agents you're signed in to, or both if you're signed in to both.
+
+**What starting OpenRig changes, for the coding agents you use** (paths are the usual defaults):
+- **For Codex:** hooks and trust in `~/.codex/config.toml`, when OpenRig or a Codex agent starts.
+- **For Claude Code:** workspace trust in `~/.claude.json`, and activity hooks in the project's
+  `.claude/settings.local.json`, plus a status line unless you already have your own.
+- **For both:** small discovery skills in `~/.claude/skills` and `~/.agents/skills`.
+- **Kernel access:** by default the kernel gets broader permissions than a project team gets by default. On Codex
+  that's full access with no approval prompts. On Claude Code, its file tools, web fetches and operational commands,
+  including reads under your home folder, run without asking. A permission policy, per-agent choice or Codex profile
+  changes that.
+
+OpenRig doesn't guarantee it can preserve or roll back these files, so back them up first. [Everything OpenRig writes, and why](../../README.md#what-openrig-changes-on-your-machine).
+
+Started isn't the same as ready. `rig status` shows a `Kernel:` line, and `rig ps --nodes --rig kernel` shows each
+kernel agent's state. They can take a moment after the daemon is up.
+
+### 4. Open the OpenRig view
+
+```sh
+rig terminal open saved:kernel --window
+```
+
+**What you'll see:**
+- **Where it opens:** a new terminal window or tab. If your agent is already running inside Herdr, it opens a new
+  Herdr space instead. It uses Herdr when installed, plain tmux otherwise.
+- **Layout:** in a narrow window, or when the width can't be measured, the operator fills the first page. From 120
+  columns, the dashboard and the operator share it. The advisor has its own tab.
+- **On a Mac:** you may be asked to let your terminal app be controlled. Allowing it is fine.
+- **Over SSH or with no display:** the window can't open. The command says why and, where it can, prints a command
+  to run in a new terminal. Otherwise your agent works out the exact command to join the operator.
+
+You're installed when you're talking to the operator.
+
+### 5. Start your first team
+
+Tell the operator what you want built, and in which folder. It recommends one of three teams:
+- `starter`: a builder and a reviewer, for one bounded change;
+- `workshop`: a lead, a builder, QA and a reviewer, for ongoing work in one repository;
+- `factory`: seven agents, for sustained product work.
+
+Before it starts one, it tells you what starting a team in your folder changes: managed guidance in `AGENTS.md` or
+`CLAUDE.md`, plus the team's skills. Then it waits for your yes. As shipped, `starter` uses both Claude Code and
+Codex. With only one of them, ask the operator to adapt it.
+
+By hand, from your repository (the first command shows what it would start, and starts nothing):
+
+```sh
+rig up starter --cwd . --plan
+rig up starter --cwd .
+rig ps --nodes --rig starter
+```
+
+If an agent stops at a sign-in, trust or permission prompt, `rig up` reports `Status: partial` and names the prompt.
+Answer it in that agent's terminal, then run the `rig seat continue <seat>` command it prints. The team is ready
+for work once its agents show as ready in `rig ps --nodes --rig starter`.
+
+### 6. Give the team work, and stop it
+
+```sh
+rig send dev-build@starter 'Fix <one useful thing>. Ask dev-review to check it, and record the result and how I can try it.'
+rig queue list --destination dev-build@starter
+```
+
+The builder records the work as a task, so you can follow it with `rig queue`. When you're done, `rig down starter`
+stops that team. `rig daemon stop` stops the background service and leaves agent sessions running.
+
+## The one-command install
+
+Instead of steps 1 and 2 (the first line shows the plan and changes nothing):
+
+```sh
+curl -fsSL https://openrig.dev/install.sh | sh -s -- --dry-run
+curl -fsSL https://openrig.dev/install.sh | sh
+```
+
+It checks Node.js and npm, installs the latest `@openrig/cli`, then runs `rig setup`. It doesn't know which coding agent
+you use, so it checks and may install both. For just one, use steps 1 and 2. If a sign-in is missing, setup reports
+it as the step to finish: sign in, then continue at step 3.
+
+## What these words mean
+
+- **Rig:** a team of agents, started with one command. Your first one is usually `starter`.
+- **Seat:** one agent's role and address in a team, such as `dev-build@starter`.
+- **Harness:** the software around the model that an agent runs in: Claude Code, Codex or Pi.
+- **Kernel:** OpenRig's own small team, which starts with OpenRig. It isn't your project's team.
+- **Operator:** the kernel's agent you talk to first. It recommends a team for your goal and starts it when you say
+  yes.
+- **Advisor:** the kernel's agent for thinking through what you want before a team starts. It has its own tab.
+- **OpenRig view:** the terminal view that opens on the operator. In a wide window the dashboard sits beside it;
+  otherwise, or when the width can't be measured, the dashboard is on its own page. `saved:kernel` in
+  `rig terminal open saved:kernel` is the name of this saved view.
+
+## More
+
+- **Every detail of setup:** troubleshooting, permissions, headless and SSH use, and what can stop the view from
+  opening. See the [setup reference](getting-started.md).
+- **Stuck?** Run `rig context get help`, or read [Help](help.md).

package/daemon/docs/reference/refocus-channel.md

@@ -36,9 +36,15 @@ own project folder is the same project and still acts as the seat, as before thi
 launched before this change, a manual run) the hooks do what they always did. The plugin's activity relay stays quiet next to
 the seat's own `settings.local.json` copy only when that entry is exactly OpenRig's and the script it names is the same
 script; an entry from an older install doesn't match, so both report until the seat's next launch refreshes it.
-Codex has no way to load a plugin from a directory; its hooks come from the daemon's
-managed block in `config.toml`, which today carries the activity relay only, so the Codex column above describes
-`hooks/codex.json`'s registration and not a hook a Codex seat currently runs.
+OpenRig automatically installs its Codex plugin for seats that select it. On its first installation, the six exact shipped
+hook definitions are trusted before launch, after checking the installed hook files against this daemon's shipped copy.
+Existing plugin disables and hook choices are retained. An existing untrusted installation stays under native review:
+Codex's "continue without trusting" leaves no record, so OpenRig does not assume an absent trust record is permission.
+The file check happens only when trust is granted: a later edit to the cached hook scripts keeps that trust, as with any hook trusted in Codex.
+The Codex
+column above then applies only to a Codex seat whose plugin selection includes openrig-core: every Codex hook command
+exits 0 before running anything unless OpenRig gave that seat `OPENRIG_SEAT_PROJECT_DIR` and an explicit
+`OPENRIG_NODE`.
 
 Claude's additional firing signal is **transcript growth** — not turns (one turn
 can burn 200k tokens across fifty tool calls) and not wall-clock (the failure is

package/daemon/docs/reference/rig-spec.md

@@ -354,7 +354,7 @@ pods:
 
 - A seat gets the rig's `env` with its own `env` laid over it, name by name.
 - The same environment is applied on first launch, on `rig up <rig-name>` restore, and to the successor of a seat handover.
-- `rig up <spec> --env KEY=VALUE` (repeatable) adds or overrides a value for one launch. A one-off value belongs to the terminal that launch creates: it stays in that terminal's environment for as long as the terminal lives, and OpenRig removes it from the tmux session's environment as soon as the terminal has started, so a terminal started later in that session does not get it. A restore, a handover successor or any later launch starts from the spec's `env:` alone, so the value is not saved and does not carry forward. To keep a value, put it in `env:`. One exception to "does not carry forward", for a managed Claude seat (see below): a one-off name that the seat's spec does not declare stays on the session's list of names, `OPENRIG_SEAT_ENV_KEYS` (names only, no values), because the first launch and an in-place restart of the same terminal read that list. So if a later pane in that session gets a value for that name from the tmux server's own environment, its managed Claude launch can forward that value, where a launch without `--env` would leave it out. The first launch's one-off value itself is not passed on to that pane. This comes from reading the code and has not been measured. `--env` does not apply to `rig up <rig-name>` (a restore) or to a topology (several rigs from their own specs); the CLI refuses both. For a topology, put `env:` in each rig's spec.
+- `rig up <spec> --env KEY=VALUE` (repeatable) adds or overrides a value for one launch. A one-off value belongs to the terminal that launch creates: it stays in that terminal's environment for as long as the terminal lives, and OpenRig removes it from the tmux session's environment as soon as the terminal has started, so a terminal started later in that session does not get it. If OpenRig can't take it out, the seat keeps running and the launch warns, naming the variable and the tmux command to put it back or remove it. Until then, a terminal started later in that session would get it. A restore, a handover successor or any later launch starts from the spec's `env:` alone, so the value is not saved and does not carry forward. To keep a value, put it in `env:`. One exception to "does not carry forward", for a managed Claude seat (see below): a one-off name that the seat's spec does not declare stays on the session's list of names, `OPENRIG_SEAT_ENV_KEYS` (names only, no values), because the first launch and an in-place restart of the same terminal read that list. So if a later pane in that session gets a value for that name from the tmux server's own environment, its managed Claude launch can forward that value, where a launch without `--env` would leave it out. The first launch's one-off value itself is not passed on to that pane. This comes from reading the code and has not been measured. `--env` does not apply to `rig up <rig-name>` (a restore) or to a topology (several rigs from their own specs); the CLI refuses both. For a topology, put `env:` in each rig's spec.
 - Names starting `OPENRIG_` are reserved for OpenRig and refused. Empty values are refused, because the launch omits empty variables.
 - `rig export` writes the rig and member `env:` back out.
 

package/daemon/docs/reference/seat-delivery.md

@@ -8,7 +8,7 @@ daemon-owned retry scheduler. Sibling seats keep their own mode.
 | Mode | Terminal input | When input is unavailable |
 |---|---|---|
 | `off` (default) | Existing delivery and prompt checks | Existing send result |
-| `draft-aware` | Paste into a recognized empty composer; check ownership again before Enter | Immediately retain the original message with the exact refusal reason and ID |
+| `draft-aware` | Paste into a recognized empty composer; check ownership again before Enter | Hold input and retain this attempt for inspection when bookkeeping is available |
 | `hold` | No automatic terminal input, even at an empty prompt | Retain for inspection outside the pane |
 
 Runtime permissions are separate. Recipient and interactive-prompt checks still
@@ -36,13 +36,22 @@ to finish. The API may return HTTP 202 with `pending: true`; wait for
 `pending: false` before relying on the requested mode. Status reports desired
 and effective modes and retains the text `Typing guard: on (hold)` for hold.
 
-A held send immediately returns `outcome: "retained"`, `sent: false`,
-`outboxIds` and its exact reason, such as `draft_input_busy` or
-`draft_input_unknown`. No automatic retry is scheduled, including when the
-caller requested wait-for-idle. The caller can inspect or route the retained work
-and decide when to make a new request. Reusing the same delivery ID reads its
-original result; it does not replay that message. Changing modes, clearing a
-draft, or restarting the daemon also does not flush held records.
+A held send immediately returns `outcome: "retained"`, `sent: false`, its exact
+reason (such as `draft_input_busy`) and the saved attempt's `outboxIds`. No automatic
+retry is scheduled. Each explicit draft-aware request is a new attempt, including
+one with a reused `deliveryId`; the result warns older callers that this field no
+longer deduplicates input. The CLI does not generate a deduplication key.
+
+Clearing a draft, changing modes or restarting does not flush saved messages or
+callbacks. To try again, send a current request: it rechecks the recipient and input.
+A caller abort before paste cancels input; after a write may have started, the
+result preserves that uncertainty rather than claiming nothing was sent.
+
+Bookkeeping is observational. If its write fails, an otherwise valid input attempt
+still proceeds and the response includes a warning instead of a saved receipt.
+Actual transport success stays success; an unknown write stays unknown. If input
+was held and no record could be saved, the response reports failure with `sent:
+false` and the protection reason, rather than claiming durable custody.
 
 Reading never sends. Retirement frees that record's active retention quota while
 preserving evidence; it does not deliver a message or close queue work.
@@ -72,22 +81,34 @@ A large paste can appear as several labels plus a literal tail. The existing
 boundary. That complete rendering must be observed after this operation's paste
 and remain unchanged before Enter. Labels alone do not prove arbitrary content.
 
-| Delivery state | Meaning |
+| Historical delivery state | Meaning |
 |---|---|
-| `sending` | The original IDs have an unresolved write attempt |
-| `held` | No input was written; the original message remains retained or has been retired |
+| `sending` | This saved attempt has an unresolved write outcome |
+| `held` | No input was written; this attempt remains retained or has been retired |
 | `complete` | Transport execution succeeded, including render verification if requested; native consumption is not asserted |
-| `indeterminate` | Input may have occurred or requested render verification failed; no automatic replay |
+| `indeterminate` | Input may have occurred or requested render verification failed |
+| `failed` | A definite failure before input, such as caller cancellation |
 
 Migration `100_typing_guard_modes` extends the existing guard/audit rows and
 adds receipt metadata to the original outbox rows; it creates no tables, retry
 indexes or executable requests. Combined wakes retain each original ID and body.
-A held queue wake stays on the existing queue recovery path. Interrupted writes
-become indeterminate at startup regardless of which recovery component runs first.
+A held queue wake stays on the existing queue recovery path. Interrupted historical
+writes become indeterminate at startup. That history never suppresses a current
+explicit request and is not consulted to determine its result.
+
+At startup, the queue recovery pass retries still-current failed or unconfirmed
+wake notifications. It preserves their original envelopes and warns that delivery
+may repeat. Each notification is attempted once per pass, including coalesced
+wakes; a failed attempt cannot spin in that pass. A no-write failure on a later
+retry does not resolve an earlier unknown delivery. Prior-process claims are
+reconciled before new startup sends can begin. Known deliveries and held or
+retired messages stay untouched. Closed, claimed or reassigned work is not woken,
+and the retry never repeats the queue mutation or a lifecycle action.
 
 The existing retention limits apply: 100 records and 8 MiB per seat, with a 1 MiB
-message limit. New admissions refuse at capacity; already-committed queue intent
-remains durable even if concurrent activation exceeds the limit.
+message limit. Hold mode cannot retain another message at capacity. Draft-aware
+input attempts continue with a bookkeeping warning if a record cannot be saved;
+already-committed queue intent remains durable.
 
 ## Rollback and lifecycle
 
@@ -121,7 +142,25 @@ unchanged; no RigSpec field is required.
 ## Verification scope
 
 Regression tests exercise rollback/re-upgrade, same-value legacy writes, exact
-retained outcomes, restart without replay, unchanged IDs/bodies, trailing spaces,
-numbered bodies, real-menu refusals and multi-placeholder ownership. Native tests
+retained outcomes, current requests after restart, coalesced queue bodies, trailing
+spaces, numbered bodies, real-menu refusals and multi-placeholder ownership. Native tests
 use private real tmux panes with scripted editable composers. These verify the
 transport mechanics; they are not live Claude/Codex provider sessions.
+
+## Watchdog reminders
+
+A currently due watchdog reminder makes a new delivery attempt, including after an interrupted attempt or job
+accounting. Historical outbox receipts do not suppress a lone reminder or prevent it from joining a digest. The
+message tells its recipient that delivery may repeat after an unconfirmed attempt. Its job history records the
+current transport result; an unknown write is not proof that nothing arrived.
+
+The transport still protects approval/question prompts, human drafts and recipient identity. Scheduler timing,
+current parked-row eligibility and stop checks still apply. This changes message retries, not the idempotence of
+structured continuity actions such as creating a cutover baton.
+
+The parked-owner supervisor also retries current obligations despite an earlier failed, unknown or unrecorded attempt.
+A recorded success to the same known occupant waits for a change in its obligations. Rotation includes retained attempts,
+so a held input cannot starve another owner. Interactive prompts stay with the existing prompt-refusal recovery.
+Its own reminders wait while managed compaction owes the turn boundary, restore or audit, including a fresh check
+at the paste and Enter boundary. A stage that begins after paste leaves an honest partial-input result; OpenRig
+does not erase or replay that text. Peer messages and unrelated reminder policies keep their existing behavior.