docs(first-run): refresh getting started, the startup guide, help and launch docs against main (#779)

Refreshes `docs/reference/getting-started.md`, `agent-startup-guide.md`, `help.md`, `developing.md`, `worktree-builds.md` and `non-interruptive-mode.md` against main. Corrects a `rig seat set-permissions` example that didn't resolve, the startup layer order (culture before rig), the documented `resources.hooks`, which validation now refuses, and a known problem fixed in 0.6.5. Adds the recovery path after a startup gate (`rig seat continue`, the startup attention line), Claude's bypass warning and `--non-interruptive`, `builtin:auto`, the readiness window and startup proof, and `npm ci` plus build for development. Commands checked against a help capture of `a350c59b`. Part of the 0.6.6 developer documentation refresh. Text only.
2026-11-07 22:58:42 -10:00 · 2026-10-05 02:42:45 -07:00
1 parent 596b389506
commit fcaf1f8ee8
@@ -1,8 +1,7 @@
 # Agent Startup Guide

-Version: 0.2.0
-Last validated: 2026-04-11
-Applies to: OpenRig 0.1.x
+Last validated: 2026-10-05, against main `9b88b118`
+Applies to: OpenRig 0.6.6

 This guide teaches you how to think about what goes into an agent's startup experience — what files to write, where to put them, and how the layering model delivers them. It is an authoring guide, not a schema reference. For field-level details, see `rig-spec.md` and `agent-spec.md`.

@@ -11,20 +10,33 @@ This guide teaches you how to think about what goes into an agent's startup expe
 ## Continue after a native consent prompt

 If a fresh Claude seat is waiting at its bypass-permissions warning, review and
-answer that warning in the seat's native pane. OpenRig does not accept it for you
-or send configured startup context into the active dialog. The seat reports
-`attention_required` and retains that context for the same occupant.
+answer that warning in the seat's native pane. Unless the rig was launched with
+`--non-interruptive` (see [non-interruptive mode](non-interruptive-mode.md)),
+OpenRig does not accept it for you, and it never sends configured startup context
+into the active dialog. The seat reports `attention_required` and retains that
+context for the same occupant.

-After accepting, run `rig seat continue <seat>` (or use **continue** in the
-TUI's startup actions). This delivers the pending context without relaunching
-Claude. It does not replay a delivery that already started. A timeout reports
-an unknown outcome; inspect `rig seat status <seat>` before taking another action.
+After accepting, run `rig seat continue <seat>` (or press `c` on the seat in the
+TUI, shown while its context is pending). This delivers the pending context
+without relaunching Claude, and its first prompt reminds the seat that this is a
+fresh conversation and how to find its work. It does not replay a delivery that
+already started. A timeout, or a refusal because nothing is pending, reports an
+unknown outcome; inspect `rig seat status <seat>` before taking another action.
+It is also refused while the prompt is still showing (`attention_required`), or
+when the seat's binding or runtime has changed since launch.
 Runtime readiness, startup delivery, and orientation proof remain separate;
 a missing proof does not block this continuation.

 Other fresh-launch prerequisites, such as login or workspace trust, use the same
 continuation: resolve the prerequisite in the native pane, then run the displayed
-`rig seat continue <seat>` command to deliver its pending startup context.
+command. `rig ps --nodes` shows it under "Startup details (<seat>)", and
+`rig up` and `rig bundle install` print it as "Startup attention (<seat>)":
+"After resolving it in <session>, run: rig seat continue <session>".
+
+The attention codes that stop startup this way are `trust_gate`,
+`hook_trust_gate`, `update_gate`, `login_required`, `mcp_gate`,
+`bypass_consent_gate`, `codex_auth_refusal` and `codex_client_incompatible`.
+They are recognized from each harness's English prompt text.

 ## Two Categories of Startup

@@ -44,14 +56,14 @@ Context loading shapes what the agent knows, believes, and is capable of:
 ### Category 2: Deterministic Configuration

 The rig spec declaratively installs things into the agent's runtime environment:
- Hooks (git hooks, pre-commit scripts)
+- Hooks (shipped inside plugins)
 - Permissions (`.claude/settings.json` allowlists, approval modes)
 - MCPs (Model Context Protocol servers)
 - System dependencies (tools, packages)

 See the **Current Support Matrix** section at the end of this guide for what is reliable today vs experimental.

-**The v0.2.0 recommendation:** Put as much of your setup logic as possible into Category 1 (context loading via markdown files). Describe the desired end state in startup files and let the agent handle the configuration. The deterministic path exists in the spec and will become more reliable over time, but for now the context-loading path is the one that works consistently across runtimes.
+**The recommendation:** Put as much of your setup logic as possible into Category 1 (context loading via markdown files). Describe the desired end state in startup files and let the agent handle the configuration. The deterministic path exists in the spec and will become more reliable over time, but for now the context-loading path is the one that works consistently across runtimes.

 ---

@@ -136,30 +148,35 @@ Startup content is merged additively through layers. Each layer adds to what the
 ```
 1. Agent layer     — from the AgentSpec's top-level startup block
 2. Profile layer   — from the active profile's startup block
-3. Rig layer       — from the RigSpec's top-level startup block
-4. Culture layer   — from the RigSpec's culture_file
+3. Culture layer   — OpenRig's default culture, then the RigSpec's culture_file
+4. Rig layer       — from the RigSpec's top-level startup block
 5. Pod layer       — from the pod's startup block
 6. Member layer    — from the member's startup block in the RigSpec
-7. Operator layer  — injected at runtime (openrig-start overlay, context collector, etc.)
+7. Operator layer  — added by OpenRig: openrig-start.md and, on a fresh start, the onboarding pack
 ```

+A member with a `starter_ref` gets that agent starter's files in front of the agent layer. Terminal seats
+(`builtin:terminal`) skip the agent and profile layers.
+
 ### What Each Layer Is For

 | Layer | Authored by | Purpose | Example content |
 |-------|-------------|---------|-----------------|
 | Agent | Agent spec author | Core identity and capabilities that travel with this agent type | Role guidance, default skills |
 | Profile | Agent spec author | Profile-specific variations | Different skill sets for "default" vs "minimal" profiles |
-| Rig | Rig spec author | Rig-wide context for all agents | Team norms, project documentation |
-| Culture | Rig spec author | Rig constitution | `CULTURE.md` — communication, quality, operating philosophy |
+| Culture | OpenRig, then the rig spec author | Team norms | OpenRig's `CULTURE-default.md` for every seat, then the rig's own `CULTURE.md` |
+| Rig | Rig spec author | Rig-wide context for all agents | Project documentation |
 | Pod | Rig spec author | Pod-specific coordination context | Pod SOP, intra-pod workflow |
 | Member | Rig spec author | Individual member overrides | Member-specific instructions, cwd-specific context |
-| Operator | OpenRig system | System-injected runtime content | `openrig-start.md`, context collector |
+| Operator | OpenRig system | System-injected runtime content | `openrig-start.md` (optional delivery); on a fresh start, `openrig-onboarding-01.md` and `-02.md` unless `onboarding.default_pack.enabled` is false |
+
+After the files, OpenRig sends a session-identity message (rig, pod, member, logical ID) once the seat is ready.

 ### Practical Guidance

-**Most rigs only need three layers:** agent (role.md), rig (culture), and operator (openrig-start). Start simple. Add pod and member layers only when agents in the same pod need different startup content.
+**Most rigs only need three layers:** agent (role.md), culture, and the built-in operator layer. Start simple. Add pod and member layers only when agents in the same pod need different startup content.

-**The culture layer is high-value and often skipped.** A rig without a `CULTURE.md` relies on agents to guess how the team communicates and coordinates. Write one. Even a short culture file dramatically improves team coherence.
+**The rig's own culture file is high-value and often skipped.** Every seat gets OpenRig's default culture, but that says nothing about how this team communicates and coordinates. Write a `CULTURE.md`. Even a short one dramatically improves team coherence.

 **Member-level startup is for exceptions, not the rule.** If every member has its own startup block, the layering model is being used as a configuration dump. Refactor shared content up to the pod or rig level.

@@ -171,8 +188,8 @@ Startup content is merged additively through layers. Each layer adds to what the

 | Delivery Hint | When | How | Use For |
 |---------------|------|-----|---------|
-| `auto` | Before harness boot | System chooses | Default — let OpenRig decide |
-| `guidance_merge` | Before harness boot | Merged into `CLAUDE.md` / `AGENTS.md` as a managed block | Role guidance, culture, project context |
+| `auto` | Depends on the file | Resolved per file: a `SKILL.md` (or content starting `# SKILL`) is `skill_install`, any other `.md` is `guidance_merge`, and any other file is `send_text` | Default — let OpenRig decide |
+| `guidance_merge` | Before harness boot | Merged as a managed block into `AGENTS.md` (Codex, Pi) or `CLAUDE.md` (Claude; `CLAUDE.local.md` with the rig's `managed_blocks: { claude-code: CLAUDE.local.md }`) | Role guidance, culture, project context |
 | `skill_install` | Before harness boot | Copied to runtime's skill directory | Skills |
 | `send_text` | After harness is ready | Sent as text to agent's terminal via tmux | Boot-time grounding, identity hints, instructions to read skills |

@@ -185,11 +202,42 @@ Files delivered via `send_text` happen AFTER the harness is ready. The agent rec
 - Instructions to load skills (the files are already projected, the message tells the agent to read them)
 - Context that should feel like an operator briefing, not pre-loaded content

+On a fresh launch the first message is one turn: the session identity, the first `send_text` file and, when a startup
+proof is selected, its challenge (below).
+
+A file's `required` field defaults to `true`: a required file that can't be delivered fails startup, and an optional
+one is dropped without a message.
+
+### Readiness, startup proof and failure
+
+**Readiness.** After launch OpenRig polls the pane until the harness is interactive (backing off 1, 2, 4, 8 and 16
+seconds), for up to 30 seconds by default. Change the window with
+`rig config set runtime.readiness_timeout_seconds <1-600>` (or `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`); it
+applies to the next launch. A recognized prompt (the attention codes above) ends the wait at once as
+`attention_required`. A timeout ends startup as `failed` ("Readiness timeout after Ns — harness did not become
+interactive"), and the post-launch files aren't sent.
+
+**Claude submission check.** For every startup message to a Claude seat, OpenRig confirms the prompt was submitted. If
+the text is still sitting in the input, it presses Enter once more; if it's still there, it warns "Startup prompt still
+staged in <session>; press Enter in that pane." The seat still ends `ready`. After each send, readiness is checked
+again, so a prompt that appears at that point gives `attention_required`.
+
+**Startup proof.** A `startup_proof` action selects `authenticated` or `none` (the default is none; the last applicable
+one wins, and it needs `idempotent: true`). With `authenticated`, a fresh launch of an agent seat includes a challenge,
+and the seat answers it with `rig startup-proof submit --challenge-id <id> --answer <answer>`. `rig ps --nodes` shows
+the result in the ORIENTED column: `verified`, `missing`, `rejected` or `n-a`. A missing proof doesn't block startup.
+
+**After a failure.** Delivery, launch and action failures, and readiness timeouts, give `failed`. Every 30 seconds the
+context monitor marks a `failed` or `attention_required` seat `ready` once its pane reads ready, unless fresh context
+is still pending for `rig seat continue`. A seat that timed out can therefore read `ready` without having received its
+post-launch files; relaunch it with `rig seat launch <seat> --fresh` if it needs them.
+
 ### The `applies_on` Field

 Each startup file and action specifies when it applies:
- `fresh_start` — delivered on first launch only
- `restore` — delivered on restore from snapshot
+- `fresh_start` — delivered when a new conversation starts: the first launch, `rig seat launch --fresh`,
+  `rig seat continue`, and seats restored with `--fresh`
+- `restore` — delivered when a seat is restored, including a restore whose resume falls back to a fresh conversation
 - Default: `[fresh_start, restore]` (both)

 Use this to avoid re-sending context that the agent already has from its resumed conversation. For example, a one-time project briefing might only apply on `fresh_start`, while identity grounding should apply on both.
@@ -202,15 +250,8 @@ The AgentSpec and RigSpec allow declaring deterministic environment configuratio

 ### What the Spec Supports

-**Hooks** (in `resources.hooks`):
-```yaml
-resources:
-  hooks:
-    - id: pre-commit
-      path: hooks/pre-commit.sh
-      runtimes: [claude-code]
-```
-Hooks are scripts copied to the agent's workspace. They can be git hooks, automation scripts, or environment setup.
+**Hooks** ship inside plugins: declare the plugin under `resources.plugins[]`. AgentSpec validation refuses
+`resources.hooks`.

 **Runtime resources** (in `resources.runtime_resources`):
 ```yaml
@@ -232,23 +273,26 @@ startup:
      phase: after_ready
      idempotent: true
 ```
-Commands sent to the agent's terminal after it's ready. Can install MCPs, run setup commands, etc.
+Each value is typed into the harness's input and submitted, so it is a prompt or a slash command, not a shell command.
+Types are `send_text`, `slash_command` and `startup_proof` (see "Startup proof" above); `shell` is refused.
+`idempotent` is required, and an action that isn't idempotent must not list `restore` in `applies_on`. Both phases
+run after the harness is ready: `after_files` (the default) after the post-launch files, then `after_ready`.

-### Current Support Matrix (OpenRig 0.1.x)
+### Current Support Matrix

 | Capability | Status | Notes |
 |------------|--------|-------|
 | Guidance file projection (`guidance_merge`) | **Supported** | Reliable. Primary delivery mechanism. |
 | Skill projection (`skill_install`) | **Supported** | Reliable. Skills are copied to workspace. |
 | `send_text` delivery after ready | **Supported** | Reliable. Requires harness to be ready. |
-| Hook projection | **Experimental** | Files are copied but execution/integration varies by runtime. |
+| Hooks | **Through plugins** | Declare a plugin under `resources.plugins[]`; `resources.hooks` is refused. |
 | Runtime resource projection | **Supported for recognized fragments** | `claude_settings_fragment`, `claude_mcp_fragment`, and `codex_config_fragment` are applied to provider config. Unknown types are copied to runtime extension directories. |
 | Permission configuration | **Native settings plus managed launch flags** | OpenRig launches Claude with `acceptEdits` and Codex with `workspace-write` unless an explicit supported selection changes them. It does not add a global Claude `Bash(rig:*)` allowance. Use [the first-user permission guide](getting-started.md#opt-in-permissive-operation) for opt-in and custom choices. |
-| MCP installation | **Experimental** | Claude Code: `/mcp` interactive command or `claude mcp add` from CLI. Can also be described in startup files for agent self-configuration. Reliability depends on runtime TUI state. |
+| MCP installation | **Supported for Claude fragments** | A selected `claude_mcp_fragment` is merged into the project's `.mcp.json`. Claude asks to approve new servers found there; that prompt stops startup as `mcp_gate` until someone answers it and runs `rig seat continue`. Otherwise use `/mcp` or `claude mcp add`, or describe the servers in startup files for the agent to configure. |
 | System dependency installation | **Not deterministic** | Describe in startup files; agent handles via shell commands. |
 | Recurring tasks / wake timers | **Runtime-dependent** | Claude Code supports recurring tasks via the `/loop` command. Codex does not have a confirmed equivalent. Orchestrators should include `/loop` instructions in startup for Claude Code agents. |

-### The v0.2.0 Approach: Describe, Then Let the Agent Handle It
+### The Approach: Describe, Then Let the Agent Handle It

 For anything beyond `guidance_merge`, `skill_install`, and `send_text`, the recommended approach is:

@@ -347,6 +391,13 @@ remain shared.
  `CODEX_HOME`, read its login and fetch managed policy, as a Codex start does.
 - Can self-install dependencies from instructions but timer/recurring behavior is not reliably available

+**Pi and OMP:**
+- Read `AGENTS.md` in the working directory; guidance is merged there, added to Pi's own system prompt
+- Selected skills are projected into the seat's own agent directory under OpenRig's state, not into a shared
+  workspace folder
+
+**Terminal seats** (`builtin:terminal`) get no agent or profile layers and no startup proof.
+
 When authoring startup content, note which instructions are runtime-specific. For example, an orchestrator that needs a monitoring loop should include instructions like: "If running Claude Code, use `/loop 3m` to periodically check rig health. If running Codex, check rig health at the start of each task cycle instead."

 ---
@@ -417,7 +468,7 @@ This prompts the agent to actually invoke the skills, not just have them as pass

 After identity recovery, verify:
 1. `rig ps --nodes` shows your rig running (scoped to your session's rig by default; outside a managed session name it explicitly: `rig ps --nodes --rig <name>`)
-2. `rig env status` shows services healthy (if applicable)
+2. `rig env status <rig>` shows services healthy (if applicable)
 3. Your working directory is correct
 4. Required tools are available (node, npm, git, etc.)

@@ -9,6 +9,10 @@ external network, and an installed-package scenario (`scripts/run-pr-scenarios.s
 with one difference: `npm test` does not include the UI suite, which CI runs as
 `package-tests (ui)`. Run `npm run test:ui` for it.

+**In a fresh clone or worktree, run `npm ci`, then `npm run build`,** as CI does in every job and
+before each package suite (see `CONTRIBUTING.md` and [worktree builds](worktree-builds.md)).
+Locally, `npm test` builds only the daemon, and `test:workspaces` and `test:ui` build nothing.
+
 ## Blocking gates (must pass before a candidate moves)

 | Gate | Command | Covers |
@@ -18,6 +22,8 @@ with one difference: `npm test` does not include the UI suite, which CI runs as
 | Repo scripts | `npm run test:repo` | daemon build, script self-tests, docs guard, skill mirror check, context-pack generation check |
 | Unit tests | `npm run test:workspaces` | `packages/daemon` + `packages/cli` + `packages/tui` |
 | UI unit tests | `npm run test:ui` | `packages/ui` vitest. NOT part of `npm test`, but every pull request runs it as `package-tests (ui)` (the `package-tests` matrix in `.github/workflows/tests.yml`) |
+| Installed-package scenario | CI only: `scripts/run-pr-scenarios.sh` | the installed package, a daemon restart and a seeded durability failure. The script refuses to run outside GitHub Actions unless given `--remote` with `DOCKER_HOST=ssh://…` |
+| Package file lists | CI only | records each package's published file list (`npm pack --dry-run`) |

 `npm test` runs `test:repo` and `test:workspaces`; `npm run test:ui` is the separate UI
 suite. Both sets are readable in the root `package.json` scripts.
@@ -8,8 +8,9 @@ you already have. Terminal-provider support does not change the harness or login
 You need Node.js 22 or 24 and tmux, on macOS or Linux. On a Mac with Apple
 silicon, use Node.js 22 (see the [compatibility
 history](../releases/v0.5.15.md#known-compatibility-limitation)). Native
-Windows is not supported yet, and WSL2 has not been tested. Node 20 is no longer
-supported; Node 26 and other versions are untested.
+Windows is not supported yet, and WSL2 has not been tested. Node 20 and
+odd-numbered releases (23, 25 and so on) are not supported; Node 26 and later
+even-numbered releases are untested.

 **Choose permissions before starting the team.** Ordinary OpenRig launches use
 Codex's `-s workspace-write`, with approval policy from your native configuration,
@@ -63,7 +64,8 @@ but does not resume that history. Authentication or runtime failures require
 repair of that prerequisite. **o** opens the existing native terminal here; detach
 to return (tmux defaults to Ctrl-b, then d). Decide native trust/auth prompts
 there. If a fresh start paused before context delivery, **c** finishes that
-delivery to the same occupant. **r** reads actual state again; **d** expands details.
+delivery to the same occupant (from a shell, `rig seat continue <seat>` does the
+same). **r** reads actual state again; **d** expands details.

 ### Choose your providers

@@ -84,7 +86,7 @@ command before proceeding. Confirm account access to any pin; if unavailable,
 ask for a supported model choice rather than silently substituting a model or
 provider. After launch, confirm the actual native model before assigning work.

-Install OpenRig and check `tmux -V`. Check **only the selected providers**:
+Install OpenRig (`npm install -g @openrig/cli`) and check `tmux -V`. Check **only the selected providers**:

 - Claude Code: `claude --version` and `claude auth status`. If sign-in is missing,
  ask once: “Please run `claude auth login` in your launch environment.”
@@ -95,8 +97,11 @@ Install a missing selected CLI using its provider's installation instructions.
 The other provider's CLI/login and Herdr/cmux are optional. Do not copy credentials
 or start repeated sign-in attempts. Recheck the selected login after the user
 completes it. `rig setup --dry-run` previews the broader setup; applying
-`rig setup` installs/checks **both** harnesses and cmux, so it is optional for
-this selected-provider path, not a requirement to fix an unused provider.
+`rig setup` installs/checks **both** harnesses and, on macOS, Homebrew and cmux
+(off macOS those steps are skipped, and tmux isn't installed for you). It also
+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.

 ### Kernel startup stays automatic

@@ -127,7 +132,12 @@ Preview the selected seats, models and resources. Plan checks resolution and
 preflight for the working directory. Launch starts the daemon if needed, with
 the kernel behavior above. Read readiness for the project seats, not only daemon
 health. Resolve a named authentication, trust or permission prompt before giving
-that seat work. No new team is needed when returning to an existing project.
+that seat work. When a seat stops at such a prompt, `rig up` reports
+`Status: partial`, prints `Startup attention (<seat>): <reason>` and exits 1;
+`rig ps --nodes` repeats it as "Startup details". The reason ends with the command
+to run once the prompt is answered: `rig seat continue <seat>`, which delivers the
+seat's startup context in the same conversation. No new team is needed when
+returning to an existing project.

 When a seat pauses, open its existing terminal with **o** in the startup view.
 Read the proposed command, working directory and target instance. For an intended
@@ -141,13 +151,17 @@ After answering, watch for the command's result and the agent continuing. Read
 the corresponding queue row and transition from your ordinary terminal. If an
 operation timed out, read its result before asking for another attempt: it may
 already have taken effect. A delivered message or disappearing prompt alone is
-not progress. If startup is still waiting for context delivery, use **c** for the
-same occupant, then **r** to refresh. Do not start another seat to clear a prompt.
+not progress. If startup is still waiting for context delivery, use **c** (or
+`rig seat continue <seat>`) for the same occupant, then **r** to refresh. If the
+command times out, check `rig seat status <seat>` before trying again. Do not
+start another seat to clear a prompt.

 These starters are deliberately small starting points, not universal teams.
 For a different installed runtime or team shape, inspect `rig specs ls --kind
 rig` and `rig specs preview <name>` before selecting it. A seven-seat showcase
-is optional and consumes more concurrent capacity.
+is optional and consumes more concurrent capacity. A team published on GitHub
+installs from its folder link with `rig up <link>` (see
+[publishing a rig bundle](publishing-a-rig-bundle.md)).

 ## Give the owner an outcome

@@ -208,6 +222,10 @@ Return to the same owner with the next outcome, citing the earlier result.
 The seat address and durable queue survive closing your viewing terminal.
 Keep intent, acceptance and evidence in the repository's existing project,
 mission and slice artifacts; the starter reads those before inventing a path.
+`rig context work-install` lists what the project declares (intent, context files,
+skills). Without `--project` it picks the project by the seat's rig, then by the
+working directory, and stops with `project_required` and the exact `--project`
+commands only if several still match.

 If the project has no work tree, start with `rig workspace doctor` and
 `rig scope mission create --help`, then `rig scope slice create --help`. Set
@@ -234,6 +252,8 @@ This guide remains the short first-use path.
 | Observation | Next action |
 | --- | --- |
 | Tool missing or login fails | Use the specific setup/auth hint; recheck that executable in the launch shell. Do not send work to an unready seat. |
+| "Startup attention" or "Startup details" names a prompt | Answer the login, trust or bypass prompt in that seat's terminal, then run the `rig seat continue <seat>` it shows. |
+| "Readiness timeout after 30s — harness did not become interactive" | The harness took longer than the readiness window. Raise it for the next launch with `rig config set runtime.readiness_timeout_seconds <1-600>`, then relaunch that seat. |
 | Daemon is healthy, kernel is still starting | Read `rig status` and `rig ps --nodes --rig kernel`; kernel readiness is separate. |
 | Shared terminal is absent | Inspect the existing kernel binding and recovery state; use standalone `rig tui` while resolving it. |
 | Viewing terminal was closed | Reattach with `rig tui --shared`; do not relaunch the team. |
@@ -248,7 +268,8 @@ missing or ambiguous source instead of selecting an arbitrary historical row.
 Repair the named source, retry, or leave the seat stopped. Check the retained
 queue, project notes and observed result before continuing work.

-`rig setup` prints the short form of this path; `rig status` points back here.
+`rig setup` prints the short form of this path once setup is ready; `rig status`
+points back here while no rigs are registered.

 ## Kernel framing (what `rig setup` does and does not do)

@@ -281,7 +302,7 @@ Two related primitives, often confused by new operators:

 Scope files retain what the work is; workflow instances and their queue packets
 retain who acts next. Creating or editing a mission does not start work. You can
-instantiate a named workflow with `rig workflow instantiate <name>`, or explicitly
+instantiate a named workflow with `rig workflow instantiate <name> --root-objective <text> --created-by <session>` (both options are needed), or explicitly
 inspect an authored lifecycle with `rig workflow compile` and create its runtime
 with `rig workflow instantiate-lifecycle`. Compilation alone does not start work.
 [OpenRig Software Factory](../../packages/daemon/specs/agents/shared/skills/core/openrig-software-factory/SKILL.md)
@@ -383,6 +404,9 @@ the named-profile argument. The profile recipe above remains useful when you
 want to maintain those choices in native configuration. The legacy
 environment-only `OPENRIG_YOLO=1` path remains sandbox-only when no resolved
 policy is present. A standalone `codex --yolo` command is not an OpenRig setting.
+At full access, Codex can show its full-access and GPT-5.1 migration notices at
+first launch; `rig up <spec> --non-interruptive` hides them with per-launch `-c`
+overrides (see [non-interruptive mode](non-interruptive-mode.md)).

 To return to a restricted next launch, change the selected profile to:

@@ -400,8 +424,8 @@ Permission mode is the native execution choice; work posture is project guidance
 For an existing managed seat, select future-launch permissions explicitly:

 ```sh
-rig seat set-permissions owner@first-project --mode full_bypass --reason "Operator selected broader access"
-rig seat status owner@first-project --json
+rig seat set-permissions dev-owner@first-project --mode full_bypass --reason "Operator selected broader access"
+rig seat status dev-owner@first-project --json
 ```

 This records the actor, reason and old/new choice on that seat. It does not
@@ -458,7 +482,21 @@ rig policy current --spec ./my-claude-rig/rig.yaml
 ```

 This records `permission_policy: builtin:yolo`; the next managed launch passes
-`--dangerously-skip-permissions`. Member-level policies take precedence. To return
+`--dangerously-skip-permissions`. Member-level policies take precedence.
+
+On a machine where nobody has accepted it yet, Claude Code then shows its
+bypass-permissions warning in each new seat, and OpenRig reports the seat as
+needing attention without sending its startup context. Either accept the warning
+once beforehand (run `claude --dangerously-skip-permissions` in your repository,
+accept, then `/exit`; Claude Code remembers it), or accept it in the seat and run
+`rig seat continue <seat>`. Or launch with `rig up <spec> --non-interruptive`,
+which accepts it with a launch flag and writes nothing to your settings; see
+[non-interruptive mode](non-interruptive-mode.md).
+
+`rig policy apply auto --spec ./my-claude-rig/rig.yaml` (also `rig setup --policy
+auto`) records `builtin:auto` instead: Claude seats launch with
+`--permission-mode auto`, and Codex and Pi seats, which have no auto mode, launch
+at the floor. To return
 future launches to OpenRig's `acceptEdits` mode, use `rig policy apply none --spec
 ./my-claude-rig/rig.yaml` and remove any member-level bypass override. Native rules
 and managed restrictions still matter; this flag is not a promise about sandbox
@@ -1,13 +1,14 @@
 # Help your user get unstuck

 This page is for an agent whose user says OpenRig isn't working. It is the one place OpenRig keeps this guidance. The
-copy installed with OpenRig matches that installed version. Read it with `rig context get help`. If `rig` won't run,
-open `daemon/docs/reference/help.md` inside the installed `@openrig/cli` package (under `npm root -g`); in the source
+copy installed with OpenRig matches that installed version. Read it with `rig context get help`, which needs a running
+daemon. If `rig` won't run or the daemon is down, open `daemon/docs/reference/help.md` inside the installed
+`@openrig/cli` package (under `npm root -g`); in the source
 repository the same file is `docs/reference/help.md`. The same text is online at
 [openrig.dev/help/agents](https://www.openrig.dev/help/agents), next to the ways people can contact OpenRig support.

 Each guide this page links to is installed too. Load one only when you need it, with the `rig context get` address
-shown beside its link; the same files sit beside this one in `daemon/docs/reference/`.
+shown beside its link where there is one; every linked file also sits beside this one in `daemon/docs/reference/`.

 Start with what your user was trying to do. Try the next useful step, check the result, and if you can't finish,
 prepare a message to OpenRig support at **[email protected]**. Your user doesn't need a GitHub account.
@@ -23,7 +24,8 @@ rig doctor --json
 ```

 Use the installed command's `--help` if an option is unavailable. Read the diagnostic findings; don't treat them as
-instructions to reset the machine.
+instructions to reset the machine. If the daemon is involved, `rig daemon status` and `rig daemon logs` show its state
+and recent output.

 **If OpenRig won't install or `rig` won't run, start here anyway.** Record the attempted package version, install
 command and error. Leave unknown values unknown. A working daemon or a passing diagnostic is not required to ask for
@@ -33,8 +35,9 @@ help.

 The reference documents beside this file describe the version they were installed with. GitHub's default branch can
 contain changes that haven't reached your user's version. For release notes and known limitations, open
-`https://github.com/mvschwarz/openrig/blob/v<version>/docs/releases/v<version>.md`, using the version from
-`rig --version`. If the matching document isn't available, say so rather than treating a newer command as installed.
+`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
+rather than treating a newer command as installed.

 ## Find your next step

@@ -67,6 +70,14 @@ and `rig ps --nodes --rig <rig-name>`, then compare the reported state with what
 A waiting prompt, a failed launch and an agent working behind a stale status need different next steps. Repeatedly
 clearing attention doesn't fix an underlying readiness problem.

+A fresh seat stopped at a native prompt (Claude's bypass-permissions warning, a login or a folder-trust question)
+keeps its startup context. `rig up`, `rig bundle install` and `rig ps --nodes` print "Startup attention" or "Startup
+details" for it, ending with the command to run. Once your user has answered the prompt in that seat's terminal,
+`rig seat continue <seat>` delivers the context in the same conversation, without relaunching. If it reports an
+unknown outcome, check `rig seat status <seat>` before trying again. For a rig whose seats bypass permissions,
+`--non-interruptive` on `rig up` or `rig bundle install` avoids Claude's warning and Codex's notices in the first
+place; see `non-interruptive-mode.md` beside this file.
+
 ### You can't tell which instance or configuration is involved

 Read [instance layout](instance-layout.md) (`rig context get reference/instance-layout.md`) and
@@ -87,8 +98,6 @@ issue's current status; a similar symptom alone is not a diagnosis.
 - A Codex seat on the default `workspace-write` sandbox starts without network access, so it can't reach the local
  daemon, when its Codex configuration sets network access off, a managed requirement could restrict it, or Codex
  doesn't answer OpenRig's configuration read in time: [#275](https://github.com/mvschwarz/openrig/issues/275).
- Stopping the daemon can report a timeout while closing connections:
-  [#166](https://github.com/mvschwarz/openrig/issues/166).

 For everything else, search [open issues](https://github.com/mvschwarz/openrig/issues).

@@ -9,6 +9,7 @@ This must be declared through `builtin:yolo`, a `full_bypass` flag policy, or an
 ambient `OPENRIG_YOLO` alone without an attached policy is not covered.

 - 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.
 - Codex receives per-launch `-c notice.…=true` overrides for the full-access and GPT-5.1 migration notices.
  The separate GPT-5.1-Codex-Max migration notice is not suppressed.
 - Pi's existing launch flags are unchanged.
@@ -18,12 +19,24 @@ when the option is omitted. To turn it off, first stop the rig with `rig down <r
 `rig up <rig-name> --existing --no-non-interruptive`. The choice is cleared for this and subsequent
 launches. If the rig is still running, the command is refused before the choice changes. `--plan`
 changes nothing. Disabling the mode does not erase acceptance that a person previously saved in the harness.
+Turning it on for an existing rig works the same way: `rig down <rig-name>`, then
+`rig up <rig-name> --existing --non-interruptive`. Rigs created before this option existed start with it off.

-For an operator default on **new rigs**, use `rig config set launch.non_interruptive true`.
+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
 keep their saved choice when the operator default changes. On a remote install the receiving daemon's
 default applies.

+`rig up` and `rig bundle install` print what happened as warnings: "Non-interruptive mode is saved for this rig…"
+when it is on (also on each restore), "Non-interruptive mode is off for this rig's launches…" when you turn it off,
+and, for each affected seat, "Non-interruptive: OpenRig accepted Claude's bypass-permissions warning" or "…hid
+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).
+
 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
 versions, sign-in, and harness preconditions can still require attention. Ordinary launches without
@@ -23,17 +23,22 @@ A worktree can therefore report green against code it does not contain.

 1. **Run `npm ci` in each worktree** so workspace packages resolve to the
   worktree's own source. It installs the locked versions without rewriting
-   `package-lock.json`.
+   `package-lock.json`. Then run `npm run build`, as CI does before the package suites.
 2. **Never symlink `node_modules` from the primary checkout.** It appears to work — builds pass,
   typechecks pass — which is exactly the danger.
 3. **`npx tsc` with no `node_modules` installs an unrelated `tsc` package** and prints
   "This is not the tsc command you are looking for". That message means *no install*, not a
   TypeScript error.
-4. **Build `@openrig/daemon` before typechecking `@openrig/cli`** in a fresh worktree: cli imports
-   `@openrig/daemon/crash-cart` etc., which resolve to daemon's `dist`. Absent dist reads as
+4. **Build `@openrig/daemon` before typechecking `@openrig/cli` or `@openrig/tui`** in a fresh worktree:
+   cli imports `@openrig/daemon/crash-cart` etc. and tui imports `@openrig/daemon/attention`, which resolve
+   to daemon's `dist`. `npm run lint` does this build first. Absent dist reads as
   TS2307 "Cannot find module" plus a cascade of implicit-any — a provisioning artifact, not a
   code defect.

+Some cli imports don't depend on `node_modules` at all: `packages/cli/tsconfig.json` maps a few daemon
+subpaths (`crash-cart` among them) straight to the worktree's own `../daemon/dist`. The others resolve through
+`node_modules`, so the rules above still hold.
+
 ## Self-check before trusting any worktree build

    [ "$(readlink -f packages/daemon)" = "$(readlink -f node_modules/@openrig/daemon)" ] \