@openrig/cli 0.6.6 → 0.6.8

package/daemon/docs/reference/help.md

@@ -24,7 +24,9 @@ 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. If the daemon is involved, `rig daemon status` and `rig daemon logs` show its state
+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
@@ -34,34 +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
+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). If the matching document isn't available, say so
+`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
 
-Follow [Open the kernel conversations](getting-started.md#open-the-kernel-conversations)
-(`rig context get reference/getting-started.md#open-the-kernel-conversations`). The default
-`rig terminal open saved:kernel --provider herdr` needs no saved-view YAML or starter team. After the selected login
-works, start the daemon if stopped, then read `rig status` and `rig ps --nodes --rig kernel`. Started is not ready;
-the view can open while the agents finish starting, with that state reported honestly.
-Ask **“Open the OpenRig view now?”** Yes opens a new space using installed herdr, else cmux, else the guide's exact
-new-terminal command. No gives the command to open it later. Over SSH or without a display, give the exact
-connection/attach command. Keep your own terminal and existing user spaces intact; no new view provider is needed.
-No, SSH and headless use are valid background outcomes. For herdr, open or attach the actual session and check the
-visible view; a created workspace or a CLI running in a new OS window is not visual proof.
-Show TUI | advisor | operator for Claude-only, Codex-only and mixed kernels; the queue worker stays accessible through
-the TUI. Talk to the operator about your goal before choosing and launching a first project team.
-Use the existing recovery routes for unavailable seats; opening a view does not create another kernel or new accounts.
+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
 
@@ -114,6 +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).
+- 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/docs/reference/instance-layout.md

@@ -79,6 +79,11 @@ Missing or malformed selections fail; absence is never inferred as disablement.
 `rig context work-install --json` reports the effective state, source, manifest,
 context selectors, and skills. With `--runtime`, its managed skill loadout then
 combines System World, topology, and Project World selectors with provenance.
+The catalog is a Git checkout. A skill folder with uncommitted or untracked content is
+skipped by itself and named. With `--runtime`, work-install reports selected skips with
+exit 1. It inspects by default; `--apply-skills` projects the remaining clean skills while
+keeping any previously projected copy of the skipped skill. An uncommitted change directly
+in the catalog root, such as `catalog.yaml`, still makes the whole catalog unavailable.
 
 For a pre-0.5.9 home, use the `openrig-upgrade` skill's
 `migrate-telemetry-state-0.5.9.mjs` helper as an Agent-Operated Migration. Its

package/daemon/docs/reference/non-interruptive-mode.md

@@ -6,7 +6,8 @@ This does not sign in to a provider or change any seat's permission policy.
 
 The option applies only to seats whose resolved launch posture is `full_bypass`.
 This must be declared through `builtin:yolo`, a `full_bypass` flag policy, or an explicit `full_bypass` selection;
-ambient `OPENRIG_YOLO` alone without an attached policy is not covered.
+ambient `OPENRIG_YOLO` alone without an attached policy is not covered. One exception: kernel Codex seats on the
+kernel's operational default always get the Codex notice overrides below, without this option.
 
 - Claude Code receives `--settings '{"skipDangerousModePermissionPrompt":true}'`, accepting its bypass-permissions warning.
   A seat with an explicitly selected native permission mode other than `bypassPermissions` doesn't get it.
@@ -24,7 +25,8 @@ Turning it on for an existing rig works the same way: `rig down <rig-name>`, the
 
 For an operator default on **new rigs**, use `rig config set launch.non_interruptive true`, or set
 `OPENRIG_LAUNCH_NON_INTERRUPTIVE` in the daemon's environment (it overrides the config file).
-The default is false; an explicit positive or negative command-line flag overrides it. Existing rigs
+The default is false; a rig spec's `non_interruptive` overrides it (see below), and an explicit positive or
+negative command-line flag overrides both. Existing rigs
 keep their saved choice when the operator default changes. On a remote install the receiving daemon's
 default applies.
 
@@ -34,8 +36,9 @@ and, for each affected seat, "Non-interruptive: OpenRig accepted Claude's bypass
 Codex's full-access and GPT-5.1 migration notices… no warning-acceptance settings were written."
 
 A bundle's before-install view (`rig bundle inspect`) says when this option is available for its full-bypass
-Claude and Codex seats, and that Claude Code asks once to accept its warning otherwise. See
-[bundle formats](bundle-formats.md).
+Claude and Codex seats, and that Claude Code asks once to accept its warning otherwise. When the bundle's `rig.yaml`
+declares `non_interruptive: true`, it says instead that the bundle's launches are non-interruptive by default, and
+leaves out the asks-once note. See [bundle formats](bundle-formats.md).
 
 This feature writes no warning-acceptance settings to Claude or Codex files. It uses the launch-flag
 surfaces checked in Claude Code 2.1.282 and Codex 0.153.4. Other notices introduced by later harness

package/daemon/docs/reference/project-workspace.md

@@ -115,7 +115,7 @@ an explicit install whose `install.skills` is empty clears it. This keeps
 catalog, the workspace root itself is the project (`selectedBy: workspace`, or
 `explicit` with a matching `--project`), and `--project` must match its
 `project.yaml` id. Operating posture uses steps 3-5
-the same way when a queue row names no project (see
+the same way when a task names no project (see
 [scoped operating posture](scoped-operating-posture.md)).
 
 1. `--project <id>`;
@@ -160,7 +160,7 @@ existing file-reader allowlist. Catalog membership does not grant file-read or
 execution permission. These views only read; they do not select a lifecycle
 operation or activate a mission. Execution and slice queue membership require
 an exact `project:<id>` tag; lifecycle instances use their authored project
-identity. Unscoped historical queue rows and global review artifacts without
+identity. Unscoped historical tasks and global review artifacts without
 project binding are excluded from project-specific claims.
 
 The read API adds `GET /api/scopes/projects` and optional `project` and

package/daemon/docs/reference/publishing-a-rig-bundle.md

@@ -11,7 +11,9 @@ For every flag, see the [rig bundle reference](rig-bundle.md); for the file form
 ## 1. Lay out the folder
 
 A shareable bundle is one folder, kept on GitHub: in its own repository, or as a subfolder of one you already have.
-The folder holds the rig spec (`rig.yaml`), the agents it uses, and a README. The rules are the bundle standard
+The folder holds the rig spec (`rig.yaml`), the agents it uses, and a README. Choose
+[names that describe the team, domains and roles](topology-naming.md) before wiring its references.
+The rules are the bundle standard
 (`openrig.bundle-standard/v1`), summarized under "Advisory author check" in the
 [rig bundle reference](rig-bundle.md#advisory-author-check).
 
@@ -35,9 +37,9 @@ Two optional files sit beside `rig.yaml`:
 rig bundle check ./my-team                     # checks the folder against the standard; launches nothing
 ```
 
-Fix what it reports, or say in your README why a finding doesn't apply. Any finding exits 1, and `--json` names the file
-each finding is about. It checks the folder on disk, including files you haven't committed, so check again at the
-commit you share. README completeness and embedded secrets always read `not_checked`: those are yours to review.
+Fix what it reports, or say in your README why a finding doesn't apply. Any finding exits 1, and the output names the
+file a finding is about when there is one. It checks the folder on disk, including files you haven't committed, so
+check again at the commit you share. README completeness and embedded secrets always read `not_checked`: those are yours to review.
 
 You can also build and look inside the archive:
 
@@ -77,18 +79,21 @@ ask.
 
 Links need `git`, a running local OpenRig daemon, and a public GitHub link without credentials; they don't work with
 `--host`. If the team uses `permission_policy: builtin:yolo` (no permission prompts), `--non-interruptive` lets OpenRig accept the harnesses'
-first-launch warnings for you (see [non-interruptive mode](non-interruptive-mode.md)).
+first-launch warnings for you (see [non-interruptive mode](non-interruptive-mode.md)). As the author, you can make that
+the install default by declaring `non_interruptive: true` in `rig.yaml`; `--no-non-interruptive` overrides it.
 
 Installing writes the bundle's files into the install target (`--target`, the current directory if you leave it
 out) and launches the team from there, with the seats working in `--cwd`. If the target already
-has a different file at the same path, install refuses and writes nothing, so use an empty or dedicated directory. The
-reference's "Install a bundle" section has the details.
+has a different file at the same path, install refuses and writes nothing, so use an empty or dedicated directory.
+Installing again over a stopped team of the same name replaces it, and in its own install folder the changed files are
+backed up first under `~/.openrig/bundle-backups/`. A running team of the same name is refused, so stop it with
+`rig down` first. The reference's "Install a bundle" section has the details.
 
 ## 5. Choose your harnesses (when a bundle offers configurations)
 
 ```sh
 rig up <link> --preset all-claude
-rig up <link> --seat build.lead=pi --seat check.qa=codex
+rig up <link> --seat orch.lead=pi --seat dev.qa=codex
 ```
 
 On openrig.dev/rigs, pick a configuration and the page gives you one command to paste, which fetches exactly that
@@ -99,14 +104,14 @@ or **"Not tested by OpenRig"**, which means exactly that. You're welcome to run
 
 ## 6. Submit it to openrig.dev/rigs
 
-Open a pull request to [mvschwarz/openrig-world](https://github.com/mvschwarz/openrig-world) that adds one file,
+Open a pull request to [mvschwarz/openrig-registry](https://github.com/mvschwarz/openrig-registry) that adds one file,
 `registry/submissions/<your-team>.yaml`, with three fields: `repository` (your GitHub repository URL), `folder` (the
 folder holding `rig.yaml`, or `.` for the repository root) and `ref` (a branch, tag or commit). No pull requests? Open
 an issue there with the same three things. A maintainer then writes the full entry, in the `registry-entry.v1` format
 defined in the [bundle formats reference](bundle-formats.md), with the parts only a review can produce, such as the
 pinned commit and each configuration's package digest.
 
-Rig names are unique on the site. If `registry/<your-team>.yaml` already exists, the check says the name is taken;
+Rig names are unique on the site. If `registry/<your-team>.yaml` already exists, openrig-registry's registry check says the name is taken;
 choose a distinct one, for example `<taken-name>-<your-name>`.
 
 What happens next:

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

@@ -14,7 +14,7 @@ it is the mechanism that makes shipped chain files (see
 |---|---|---|---|
 | UserPromptSubmit | ✓ | ✓ | deliver due or on-demand context at a model-visible boundary |
 | Stop | ✓ | — | catch a long Claude turn crossing the growth threshold |
-| PostCompact | ✓ | ✓ | retain exact compaction due-state; deliver on the next prompt |
+| PostCompact | ✓ | ✓ | retain exact compaction due-state; deliver on the next actionable prompt |
 
 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
@@ -25,7 +25,12 @@ redundant double-fire around Codex's own compaction cadence. Set
 `OPENRIG_REFOCUS_NOW=1` for an on-demand refocus and
 `OPENRIG_REFOCUS_ENABLED=0` to disable the feature. Fresh `SessionStart` is
 always a no-op: the default onboarding pack owns fresh orientation. Both
-runtimes retain `PostCompact` due-state for the next prompt. Otherwise the hook
+runtimes retain `PostCompact` due-state for the next prompt. After a managed Claude
+compaction, the acknowledgement-only boundary and other prompts (for up to 10 minutes)
+are skipped without consuming that state, so the hook delivers on the restore request
+(after 10 minutes, on the next prompt);
+that request asks the seat to read the refocusing skill and consume the delivered
+traces rather than rerun them, and the read-depth audit accounts for them. Otherwise the hook
 is a no-op (it writes a stderr advisory when the transcript shrinks or the
 session has no identity), and it degrades to silence on unrelated hook errors.
 Both runtimes stop the hook after 5 seconds, and the content REF lookup gets 2;
@@ -34,6 +39,13 @@ configured REF resolution failure instead degrades
 loudly in the delivered payload while still completing the hook — a refocus
 must never break a seat's turn.
 
+Failed trace or configured-content resolution keeps refocus due. After three
+consecutive failed attempts for the same seat and occupant, the hook emits one
+idempotent issue-stream item tagged `issue,refocus`, visible through `rig stream
+list --tag refocus`. A successful delivery resets that failure episode. An
+unconfirmed stream write keeps the same item ID for the next failed attempt; it
+does not send a wake, change seat status, or prove the agent read the content.
+
 Because the hook runs at the seat's own turn boundaries, delivery to a
 RUNNING seat needs no relaunch, no operator action, and no message traffic:
 the next prompt the seat processes carries the content. The latency bound is

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

@@ -1,8 +1,8 @@
 # RigBundle Reference
 
 Version: 2 (pod-aware)
-Last validated against code: 2026-10-05, whole document, at main `a350c59b`
-Source of truth: `packages/daemon/src/domain/bundle-types.ts`, `packages/daemon/src/domain/bundle-archive.ts`, `packages/daemon/src/domain/pod-bundle-assembler.ts`, `packages/daemon/src/routes/bundles.ts`, `packages/cli/src/commands/bundle.ts`
+Last validated against code: 2026-10-07, at the 0.6.6 cut `2620dea8` (whole document at `a350c59b`; changes to its sources since then checked)
+Source of truth: `packages/daemon/src/domain/bundle-types.ts`, `packages/daemon/src/domain/bundle-archive.ts`, `packages/daemon/src/domain/pod-bundle-assembler.ts`, `packages/daemon/src/routes/bundles.ts`, `packages/cli/src/commands/bundle.ts`, `packages/daemon/src/domain/bundle-install-context.ts`, `packages/daemon/src/domain/bundle-source-resolver.ts`, `packages/daemon/src/domain/bootstrap-orchestrator.ts`
 
 A `.rigbundle` is a self-contained distributable archive that packages a rig spec, all referenced agent specs, their resources (skills, guidance, startup files), culture file, documentation, and an integrity manifest into a single file. The recipient can install and launch the rig without needing the original source tree.
 
@@ -20,8 +20,8 @@ Replace `COMMIT` with a full commit ID. Branches and tags are also accepted, inc
 resolve once to a full commit before fetching. Each result names the resolved source, configuration ID, package digest
 and assembler. Save the printed commit-pinned URL to repeat the same source selection. Only a full 40-character commit
 ID counts as a commit; a shorter one is looked up as a branch or tag name. `--preset` and repeatable
-`--seat pod.member=runtime` select only configurations the folder declares. A link build is named `github-bundle`
-unless `--name` says otherwise.
+`--seat pod.member=runtime` select only configurations the folder declares. A link build takes the rig's `name` from
+its `rig.yaml` unless `--name` says otherwise, and is named `github-bundle` when `rig.yaml` has no readable name.
 
 Link import needs a running, verified local daemon and a credential-free, publicly readable GitHub URL. It does not
 upload files to remote daemons. For a remote target, run the link command on that host, or create an archive, transfer
@@ -59,7 +59,8 @@ checks pod-aware rig validity, README inclusion in `docs`, readable declared fil
 minimum-version shape, declared preset consistency and known sensitive filenames. It does not contact a daemon,
 build an archive, run preflight or launch anything. Findings give exit status 1; they are never an install gate. It
 reads the folder on disk, not a link or a commit, so files that aren't committed are checked too. Human output gives
-each rule's status, ID and reason; `--json` also names the files a finding is about.
+each rule's status, ID and reason, then the file it's about in parentheses when there is one; `--json` carries the
+same as a `path` field.
 
 README completeness and arbitrary embedded secrets need human review and are reported as `not_checked`. A bounded
 or unreadable scan is also `not_checked`, never a clean scan. The check is advice for authors, not a security audit or
@@ -283,7 +284,7 @@ rig bundle create <spec-path-or-github-link> -o <output.rigbundle> [--rig-root <
 | `--seat <pod.member=runtime>` | no | — | Use this runtime for one seat, within what `configurations.yaml` allows. Repeatable; applied after `--preset`. An undeclared choice is refused with the allowed set, and nothing is built. |
 | `--context-pack <dir>` | no | — | Carry the context pack in `<dir>`. Repeatable. The directory may be outside the rig folder, for example a world pack whose `manifest.yaml` is at its repository root. Only `manifest.yaml` and the files it declares are carried, the same set `rig context add --git` installs, and the pack lands in the bundle at `context-packs/<manifest name>/`. Needs a pod-aware spec. |
 | `--project-dir <dir>` | no | — | Carry the project the rig works in: the folder holding its `project.yaml` (which must declare an `id`) and files beside it, such as `SPEC.md`. On install the project is registered in the workspace catalog and the rig is associated with it, before any seat launches (see [project-workspace.md](project-workspace.md)). Needs a pod-aware spec. |
-| `--name` | no | `my-bundle` (`github-bundle` for a link) | Bundle name in the manifest. |
+| `--name` | no | the rig's `name` in `rig.yaml`; `my-bundle` (`github-bundle` for a link) when it has no readable name | Bundle name in the manifest. |
 | `--bundle-version` | no | `0.1.0` | Bundle version in the manifest. |
 | `--min-cli-version`, `--min-daemon-version` | no | — | The oldest OpenRig CLI or daemon that may install the bundle, checked on install. For a link they override the author's `bundle.yaml` minimums. |
 | `--notes <text>` | no | — | Notes stored in the manifest's provenance. |
@@ -334,7 +335,9 @@ Under "Needs (not checked)" the view lists the author's setup preconditions, wit
 shell, in order". For a declared full-bypass Claude seat it notes that Claude Code asks once to accept its bypass
 warning, and when any Claude or Codex seat is full bypass it says that `--non-interruptive` is available (see
 [non-interruptive mode](non-interruptive-mode.md)). It doesn't select the mode or check whether you've already
-accepted the warning.
+accepted the warning. When the bundle's `rig.yaml` declares `non_interruptive: true`, the view instead says that the
+bundle declares non-interruptive launches for those seats, with broad file, command and network access, and that
+`--no-non-interruptive` overrides it; the asks-once note is left out.
 
 `rig bundle install` and bundle-form `rig up` print this same view to stderr before the existing action, including
 `--plan`. With `--json`, stdout remains one result; its optional `behaviour` field carries the structured view.
@@ -367,9 +370,9 @@ rig bundle install <bundle-path-or-github-link> [--plan] [--yes] [--target <root
 | `--target <root>` | yes in apply mode, for an archive path | the current directory for a link | Directory the bundle is installed into and launched from. Required for an archive path unless `--plan` is used. |
 | `--cwd <dir>` | no | — | Working directory for every launched member, for this install only (for example, the repository the rig works on). Does not change the install target. |
 | `--preset <name>`, `--seat <pod.member=runtime>` | no | — | For a GitHub link, the declared configuration to build and install. |
-| `--non-interruptive` | no | off, or the operator setting `launch.non_interruptive` | Accept the harnesses' first-launch warnings for this rig's full-bypass Claude and Codex seats with launch flags, writing nothing to your settings. The choice is saved on the rig. `--no-non-interruptive` turns a saved choice off; stop a running rig with `rig down` first. See [non-interruptive mode](non-interruptive-mode.md). |
+| `--non-interruptive` | no | the bundle `rig.yaml`'s `non_interruptive`, else the operator setting `launch.non_interruptive`, else off | Accept the harnesses' first-launch warnings for this rig's full-bypass Claude and Codex seats with launch flags, writing nothing to your settings. The choice is saved on the rig. `--no-non-interruptive` turns a saved choice off; stop a running rig with `rig down` first. See [non-interruptive mode](non-interruptive-mode.md). |
 | `--skip-version-check` | no | off | Skip the compatibility check below. Not for routine use. |
-| `--force` | no | off | Skip the rig-name conflict check below. Not for routine use: a conflict can leave a partial install. |
+| `--force` | no | off | Skip the running-team check below. Not for routine use. A pod-aware bundle is still refused before target files are written when a team with the same name is running; a legacy (schema 1) bundle can be left partly installed. |
 | `--json` | no | `false` | Emit machine-readable JSON. |
 
 Install **launches the rig**; it does not just unpack it. It extracts the bundle to a temporary directory, validates integrity, and bootstraps the rig. In apply mode, the daemon requires `targetRoot`, so `rig bundle install` must be given `--target <root>` for an archive path unless you are running with `--plan`.
@@ -377,16 +380,28 @@ Install **launches the rig**; it does not just unpack it. It extracts the bundle
 Before it plans or applies, install runs two checks on the archive, both also under `--plan`:
 - **compatibility:** the manifest's `min_daemon_version` and `min_cli_version` against this daemon and CLI. A failure
   reports "Bundle compatibility check failed" with the versions involved.
-- **rig-name conflict:** the bundle's rig name against every rig this daemon knows, running or not. A match reports
-  "Bundle install conflict check failed".
+- **running team:** a running team with the bundle's rig name refuses the install with "Bundle install conflict check
+  failed". The error names the installed and the offered team and lists three choices: use the existing team, stop it
+  with `rig down` and retry to replace it, or cancel. This check does not refuse a stopped team with that name.
 
-Each error lists its fixes, including the override flag.
+Each error lists its fixes; the compatibility error also names `--skip-version-check`. `--skip-version-check` and
+`--force` skip only these two checks: the manifest safety check of its `rig_spec` and `project` entries always runs.
+
+For a pod-aware (schema version 2) bundle, installing a team whose rig name matches a stopped team replaces it: the
+earlier team is archived when the new one is created, and the result gives the `rig unarchive <id>` command that
+restores it. If OpenRig cannot confirm the earlier team is stopped, install refuses with `generation_unconfirmed` and
+creates no replacement team. For an install into that team's own install folder, OpenRig makes this check before
+writing any files; for any other target, bundle files already copied there stay.
+
+A legacy (schema version 1) bundle does not replace a stopped team. Its approved external and package install steps run
+first, and then its rig-name check fails preflight with "Rig name '<name>' already exists".
 
 For a pod-aware (schema version 2) bundle, apply copies every extracted file (`bundle.yaml`, `rig.yaml`, `agents/`, culture and docs files, and any carried `project/`, `context-packs/` and author-declared contents) into the target and launches from there, then removes the temporary extraction. So:
 
 - the target becomes the rig root: `agent_ref` paths resolve inside it, and a member with `cwd: "."` starts in the target (every pod-aware member must declare a `cwd`);
 - an absolute member `cwd` stays as authored, and `--cwd <dir>` (on `rig bundle install` or `rig up`) still overrides every member's cwd;
-- if the target already has a file with **different** content at any bundle path (for example its own `rig.yaml`), install refuses with `target_conflict` and writes nothing. Identical target files don't cause a target-content conflict; the other installation checks above, including the rig-name conflict check, still apply. Use an empty or dedicated directory as the target.
+- if the target already has a file with **different** content at any bundle path (for example its own `rig.yaml`), install refuses with `target_conflict` and writes nothing. Identical target files don't cause a target-content conflict; the other installation checks above, including the running-team check, still apply. Use an empty or dedicated directory as the target.
+- exception: reinstalling over a stopped team into that team's own install folder (the target's `bundle.yaml` is schema version 2 with the same bundle name, or with `my-bundle` or `github-bundle`, the default names before 0.6.7) replaces its files there. Each differing path is first copied under `<OpenRig home>/bundle-backups/reinstall-*/files/`, with a `RESTORE.json` beside it; other files in the folder are kept. The files stay installed even if a later launch fails.
 
 The bundle's declared skills, plugins, workflow specs, context packs and agent images are routed into your libraries **before any member launches**, and the context-pack library is rescanned, so a member's first turn can already read a pack the bundle carried. A routing failure does not stop the install: it is printed as a warning, returned in `routingFailures`, and recorded in the install audit. The human output lists what each declared kind routed and any entry that was not routed.
 
@@ -437,17 +452,20 @@ rig up <bundle-path-or-github-link> [--target <root>] [--cwd <dir>] [--plan] [--
 take different routes:
 - **A GitHub link** builds the archive and installs it through the `rig bundle install` path, with its compatibility
   and rig-name checks and the install audit.
-- **A local `.rigbundle` path** goes through the bundle bootstrap path directly. It skips the compatibility and
-  rig-name checks, isn't recorded in the install audit (so `rig bundle history` doesn't list it), and doesn't print the
-  routing summary. A legacy (schema 1) archive gets no post-install routing this way. To get the checks and the audit
-  for a local archive, use `rig bundle install` or `rig bootstrap`.
+- **A local `.rigbundle` path** goes through the bundle bootstrap path directly. It skips the compatibility check,
+  isn't recorded in the install audit (so `rig bundle history` doesn't list it), and doesn't print the routing summary.
+  For a pod-aware archive, a running team with the same name is still refused before target files are written, and a
+  stopped one is replaced as described under "Install a bundle". A legacy (schema 1) archive runs its approved install
+  steps before its rig-name check, which then refuses a running team and fails preflight for a stopped one; it also
+  gets no post-install routing this way. To get the checks and the audit for a local archive, use `rig bundle install`
+  or `rig bootstrap`.
 
 `rig bootstrap <bundle-path>` also accepts archives and uses the ordinary bundle
 install path, including compatibility checks and the install audit. Use `--plan`
 to preview, or `--target <root>` to choose the persistent install directory. Its
 default target is the caller's current directory; `--cwd` only changes the agents'
 working directory. YAML files and library spec names keep the spec bootstrap path.
-It prints no behaviour view and has no `--non-interruptive` option.
+It prints no behaviour view and has no `--non-interruptive` option; a bundle's declared `non_interruptive` still applies.
 
 - `--target <root>` is the install target described above (for a schema-version-2 bundle, the directory the bundle is copied into and launched from)
 - if `--target` is omitted for a `.rigbundle` or a link, the CLI defaults the install target to the current working directory, so the bundle's files are written there
@@ -609,4 +627,6 @@ Equivalent explicit form:
 rig up /path/to/my-team.rigbundle --target ~/projects/my-project
 ```
 
-The bundle is extracted to a temporary directory and its integrity is verified. A schema-version-2 bundle is then copied into the target root (refused if the target holds different files at the same paths) and the rig is launched from there, with all agents and resources from the bundle. If you also want agents to launch with a different working directory for that run, pass `--cwd <dir>` separately.
+The bundle is extracted to a temporary directory and its integrity is verified. A schema-version-2 bundle is then copied into the target root and the rig is launched from there, with all agents and resources from the bundle. If you also want agents to launch with a different working directory for that run, pass `--cwd <dir>` separately.
+
+A running team must be stopped before reinstalling. Reinstalling into a stopped team's recorded install folder preserves conflicting files in the instance's `bundle-backups` directory; the result names the backup. The folder must still contain that bundle's installed manifest. A copied same-name manifest in another folder does not authorize replacing its conflicting files. Other targets retain first-install behavior: different files at the same paths are refused before writing. New installations record the canonical target folder for each generation, independently of `--cwd`. Older generations and new generations created directly from `rig.yaml` have no recorded folder and retain the manifest-only check until their next successful bundle installation, so a copied same-name manifest can still qualify for those generations.

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

@@ -1,13 +1,16 @@
 # RigSpec Reference
 
 Version: 0.2 (pod-aware)
-Last validated against code: 2026-10-05, at main `fcaf1f8e`
-Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/types.ts`, `packages/daemon/src/domain/startup-validation.ts`, `packages/daemon/src/domain/permission-policy/policy-ref.ts`, `packages/daemon/src/domain/profile-resolver.ts`, `packages/daemon/src/domain/rigspec-preflight.ts`
+Last validated against code: 2026-10-07, at the 0.6.6 cut `2620dea8` (whole document at `fcaf1f8e`; changes to its sources since then checked)
+Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/types.ts`, `packages/daemon/src/domain/startup-validation.ts`, `packages/daemon/src/domain/permission-policy/policy-ref.ts`, `packages/daemon/src/domain/profile-resolver.ts`, `packages/daemon/src/domain/rigspec-preflight.ts`, `packages/daemon/src/adapters/kernel-authority.ts`, `packages/daemon/src/domain/native-permission-store.ts`, `packages/daemon/src/domain/codex-team-workspace.ts`
 
 This is the canonical reference for the pod-aware RigSpec YAML format. Every field, validation rule, and default documented here was traced from the actual parser and validator code, not from prior documentation.
 
 ---
 
+For choosing IDs, see [naming rigs, pods and seats](topology-naming.md). Keep the same
+logical names in edges, startup instructions, workflow targets and runtime presets.
+
 ## Minimal Valid Example
 
 ```yaml
@@ -18,7 +21,7 @@ pods:
   - id: dev
     label: Development
     members:
-      - id: impl
+      - id: build
         agent_ref: "local:agents/impl"
         profile: default
         runtime: claude-code
@@ -105,7 +108,7 @@ pods:
           required: true
       actions: []
     members:
-      - id: impl
+      - id: build
         agent_ref: "local:agents/impl"
         profile: default
         runtime: claude-code
@@ -131,7 +134,7 @@ pods:
         cwd: "."
     edges:
       - kind: delegates_to
-        from: impl
+        from: build
         to: qa
 
   - id: rev
@@ -152,13 +155,13 @@ pods:
 edges:
   - kind: delegates_to
     from: orch.lead
-    to: dev.impl
+    to: dev.build
   - kind: delegates_to
     from: orch.peer
     to: dev.qa
   - kind: can_observe
     from: rev.r1
-    to: dev.impl
+    to: dev.build
   - kind: can_observe
     from: rev.r2
     to: dev.qa
@@ -226,12 +229,35 @@ Claude keeps `acceptEdits` and receives inline session settings allowing ordinar
 `rig` commands, project reads and common project test commands (for example,
 `npm test`, `pnpm test`, `pytest`, `go test` and `cargo test`). Lifecycle commands
 such as `rig up`, `rig down`, `rig restore`, `rig bundle install` and seat stop or
-handover are listed as **ask** rules. Native deny and ask rules take precedence
-over allow rules. These are native command-matching rules, not filesystem
-containment: a project's test command can execute code. Flags before the verb
-(for example, `rig --host vps up`) or wrapper commands may not match the lifecycle
-prefixes. OpenRig does not write these settings into a personal or project
-permission file.
+handover ask through a session `PreToolUse` hook. Their literal help forms, such
+as `rig down --help`, `rig bundle install -h` and `rig help down`, run without
+that lifecycle prompt. Native personal, project and managed deny/ask rules still
+apply; OpenRig does not remove or override them.
+
+For allowances, the hook recognizes literal command words (including quoted or absolute paths),
+leading environment assignments that do not change executable lookup or startup,
+and `env`, `command` and `exec` wrappers without options other than `--`.
+Relative executable paths and assignments such as `PATH` or `NODE_OPTIONS` stay
+with native checks. The same existing team allowances apply after spelling
+normalization; project `node_modules/.bin/vitest` and `jest` paths match their
+existing `npx` allowances. It does not automatically allow pipelines, command
+substitutions, redirects, heredocs, shell functions or other unrecognized syntax.
+Lifecycle prefixes are checked at every word position, including after wrappers,
+control-flow words and CLI argument separators. A `--` separator before or after
+the subcommand ends option parsing, so a later `--help` is an operand and still
+asks. Ask detection also scans with comment text retained, so a `#` inside a
+substitution does not hide a later lifecycle command. Unquoted prose or comments
+containing a lifecycle command may also ask; ordinary trailing comments do not
+change allowance matching. Quoted messages and quoted heredoc bodies remain data.
+Arithmetic shifts are not treated as heredoc operators. These are command
+allowances, not containment: a project's test command can execute code. The
+hook and allowances are passed with `--settings` at launch, including resume
+and fork; nothing is written to personal or project permission files.
+
+If the helper asset is missing at launch, OpenRig falls back to the native lifecycle
+ask rules; help can prompt in that fallback. A helper that disappears or times out
+after launch cannot supply a decision, leaving Claude's remaining native rules
+in effect. The hook is a convenience policy, not a containment boundary.
 
 Codex keeps `workspace-write` with its existing approval policy and receives the
 configured OpenRig workspace root plus its pod's shared state directory as
@@ -267,7 +293,8 @@ The destructive class is `delete_everything`, `drop_persistent_store` and
 **At launch.** `builtin:yolo` selects Claude `--dangerously-skip-permissions`, Codex
 `-s danger-full-access -a never`, and Pi `--approve`. `builtin:auto` selects Claude
 `--permission-mode auto`, while Codex and Pi do not have an auto mode and launch at the floor.
-Every other seat launches at the floor:
+Every other seat launches at the floor (a non-kernel seat with no policy also gets the
+[team launch default](#team-launch-defaults) above):
 - Claude `--permission-mode acceptEdits`;
 - Codex `-s workspace-write`, or `-p <profile>` when the member sets
   `codex_config_profile`, in which case the profile governs its own sandbox;
@@ -276,7 +303,8 @@ Every other seat launches at the floor:
 Seats of the rig named `kernel` are the exception. With no member or rig policy, no
 per-seat choice and (for Codex) no named profile, Claude launches in `acceptEdits` with a
 per-launch `--settings` allow list for its file tools and operational commands, and Codex
-launches with `-s danger-full-access -a never`.
+launches with `-s danger-full-access -a never`, plus per-launch `-c` overrides that hide its
+full-access and GPT-5.1 migration notices, whatever the rig's non-interruptive choice.
 
 **Config-surface policies are recorded, not applied at launch.** The seat still starts at
 the floor. The `allow`, `ask` and `deny` rules take effect once they are translated into the
@@ -388,7 +416,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 
 - **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
 - **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
-- **Credentials:** The Pi process receives only `PATH`, `HOME`, `USER`, `LOGNAME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY` or `KIMI_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>` or `kimi-coding/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
+- **Credentials:** The Pi process receives only `PATH`, `HOME`, `USER`, `LOGNAME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY`, `KIMI_API_KEY` or `MINIMAX_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>`, `kimi-coding/<id>` or `minimax/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
 
 ### Oh My Pi (`runtime: omp`)
 
@@ -428,7 +456,7 @@ The canonical session name is derived from the pod ID, member ID, and rig name:
 {podId}-{memberId}@{rigName}
 ```
 
-Example: pod `dev`, member `impl`, rig `my-team` → session `dev-impl@my-team`
+Example: pod `dev`, member `build`, rig `my-team` → session `dev-build@my-team`
 
 Pod and member IDs cannot contain `@` because the first `@` separates their portion
 of the session address from the rig name. Rig names may still contain `@`.
@@ -457,13 +485,13 @@ Edges within a pod use **unqualified member IDs** (just the member `id`, not `po
 pods:
   - id: dev
     members:
-      - id: impl
+      - id: build
         # ...
       - id: qa
         # ...
     edges:
       - kind: delegates_to
-        from: impl      # NOT dev.impl
+        from: build     # NOT dev.build
         to: qa          # NOT dev.qa
 ```
 
@@ -477,7 +505,7 @@ Edges between pods use **fully-qualified `pod.member` IDs**:
 edges:
   - kind: delegates_to
     from: orch.lead     # pod.member format
-    to: dev.impl        # pod.member format
+    to: dev.build       # pod.member format
 ```
 
 Cross-pod edges must reference different pods. An edge where both `from` and `to` are in the same pod is a validation error — use pod-local edges instead.

package/daemon/docs/reference/rosters.md

@@ -4,7 +4,8 @@ A roster records who to involve for a purpose and why. The same seat can appear
 rosters with different capabilities and engagement. Membership is a recommendation, not an
 assignment or a grant of authority. Contact someone with the existing `rig send` or `rig queue` commands.
 
-Put JSON files in `<workspace.root>/rosters/`. Read `workspace.root` with
+Put JSON files in `<workspace.root>/rosters/`; the included starter and factory leads write
+their team's `<rig>.json` there at first start and never replace an existing one. Read `workspace.root` with
 `rig config get workspace.root`, or use `--folder` to read another folder in place.
 
 ```sh

package/daemon/docs/reference/schemas/registry-entry.v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openrig.dev/schemas/registry-entry.v1.json",
-  "title": "Registry entry (openrig-world/registry/<slug>.yaml)",
+  "title": "Registry entry (openrig-registry/registry/<slug>.yaml)",
   "type": "object",
   "required": [
     "schema",