@openrig/cli 0.6.6 → 0.6.7

package/daemon/docs/reference/slack-app-setup.md

@@ -63,9 +63,10 @@ groups:
   a member of, and reading channel details.
   `rig slack verify` checks these.
 - **Feature scopes**: `files:read` (download attachments people send), `files:write` (upload
-  attachments to Slack), and `app_mentions:read` (receive @-mentions of the app). `rig slack verify`
-  warns when one of these is missing (if Slack returns the granted scopes) but does not require
-  them, so a READY from verify does not prove attachments or mentions will work.
+  attachments to Slack), `app_mentions:read` (receive @-mentions of the app), and `reactions:read`
+  (receive emoji reactions). `rig slack verify` warns when one of these is missing (if Slack returns
+  the granted scopes) but does not require them, so a READY from verify does not prove attachments,
+  mentions or reactions will work.
 
 If a feature scope was not granted, the effect differs by feature:
 
@@ -75,12 +76,22 @@ If a feature scope was not granted, the effect differs by feature:
   the failure appears only in the daemon log (`rig daemon logs`).
 - **Mentions** (`app_mentions:read`): Slack does not deliver `app_mention` events to the app.
   Only `rig slack verify` warns that the scope is missing; nothing reports the missing events.
+- **Reactions** (`reactions:read`): Slack does not deliver `reaction_added` events, so a reaction
+  on an ask doesn't reach the asking agent. A reply in the ask's thread still does.
 
-So after installing, compare the granted scopes Slack shows for the app with all six scopes that
+So after installing, compare the granted scopes Slack shows for the app with all seven scopes that
 `rig slack manifest --json` lists.
 
-The app subscribes to messages in public channels it is a member of (`message.channels`) and to
-mentions of the app (`app_mention`). It does not request direct-message or private-channel access.
+The app subscribes to messages in public channels it is a member of (`message.channels`), to
+mentions of the app (`app_mention`), and to emoji reactions (`reaction_added`). It does not request
+direct-message or private-channel access.
+
+A reaction added to an ask reaches the agent that asked, as a note naming who reacted and with
+which emoji; the agent decides what it means. Every message OpenRig posted for the ask counts:
+its first message, a long ask's numbered parts, and an ask posted as a reply in a thread. A
+reaction on any other message, including a person's reply in the thread, is ignored. An app created from an older manifest has neither the `reactions:read` scope nor the
+`reaction_added` event: add both under **OAuth & Permissions** and **Event Subscriptions**, then
+reinstall the app to the workspace.
 
 The manifest also turns on **Interactivity**, so the human can answer a decision's structured
 questions by clicking a button (`rig queue create --human-questions-file`). In Socket Mode the
@@ -101,11 +112,55 @@ part of OpenRig.
 - `rig slack status` shows what is still missing, without contacting Slack.
 - `rig slack verify` checks the granted baseline scopes and channel membership with Slack.
 
+## One channel per rig or seat (optional)
+
+By default every human-bound item posts to the one channel from `rig slack setup --channel`.
+To follow each rig separately, post a rig's items, or a single seat's, to its own channel:
+
+```bash
+rig slack channel-map set my-rig C0EXAMPLE1
+rig slack channel-map set pr@my-rig C0EXAMPLE2
+rig slack channel-map list
+rig slack channel-map remove pr@my-rig
+```
+
+- **Which channel an item posts to.** The item's seat is matched exactly first (`pr@my-rig`),
+  then its rig (`my-rig`). Anything unmapped posts to the default channel, so a config
+  without a map behaves exactly as before. Aggregate delivery digests have no single seat and
+  always post to the default channel.
+- **Threads.** Updates, `--reply-to` and later notifications for an item stay in its thread.
+  With a map configured, if a seat's channel has changed since the thread was opened, the
+  next post opens a new thread in the seat's current channel, and `--reply-to` records the
+  fallback as `root-other-channel`. With no map, threads behave exactly as before: an item's
+  next notification reuses its open thread in whatever channel that thread was posted in.
+- **Changing the map.** A change applies to new posts. A post already in flight (one being
+  retried after a failure or an unconfirmed send) finishes in the channel and thread it started
+  in, and its retry checks that channel first so it is not posted twice. This includes adding
+  the first map: a post first tried before any map existed finishes in the default channel.
+  Without a map, OpenRig records nothing about a post's channel, so if the default channel
+  changes while a post is being retried, the retry goes to the new default channel (as it always
+  has); that also applies to a post first tried before the map was added.
+- **Replies and new messages.** A reply in an item's thread reaches that item's seat, in any
+  channel. A message the human starts (or a reply in a thread OpenRig does not know) goes to
+  the connector's inbound destination, whichever channel it is in. Missed-message recovery
+  (below) covers the default channel only.
+
+Invite the app to every mapped channel (`/invite @OpenRig`). `rig slack verify` checks
+membership in the default channel and every mapped channel, and reports NOT ready until the
+app is in all of them. A saved change reaches a running connector when it next rewires:
+`rig slack disable` then `rig slack enable`, or a daemon restart. The TUI's Connections page
+says whether the running configuration matches the file.
+
+The map is stored as `channelMap` in `slack-connector.json`, as a list of `{ "match", "channel" }`
+entries. Saving refuses any other field. A field written by a newer OpenRig is ignored when the
+connector reads the file, and `rig slack status` names it. Private channels and direct messages
+are not supported targets.
+
 ## Reconnect recovery and status
 
 The daemon scans available top-level messages in the configured channel after a
 Socket Mode connection and on its existing five-minute retry cadence. Recovered
-queue rows say **Recovered after a gap** and show the original Slack posting time.
+tasks say **Recovered after a gap** and show the original Slack posting time.
 They use the same sender admission, routing, attachment handling, fixed identity
 and dead-letter path as live messages. A durable dead letter is custody of a
 failed delivery, not successful delivery.
@@ -121,8 +176,9 @@ not covered by that margin. A corrupt or unreadable checkpoint leaves recovery u
 and preserves the existing file; live inbound continues.
 
 Each pass admits at most four pages, 100 entries and 15 seconds of work, with a
-five-second history-request ceiling. An already admitted attachment/landing keeps
-its owner until it settles. Rate limits retain Slack's Retry-After across restart.
+five-second history-request ceiling. Work already started on a message, such as
+an attachment transfer, is not cancelled by these limits or by a stop, and a new
+pass waits for it to finish. Rate limits retain Slack's Retry-After across restart.
 Transport and server failures use a five-second backoff unless Slack supplies Retry-After.
 When Slack reports a plan history limit, recovery still lands the available page
 and advances normally, retaining an older-history limitation in status across restarts.

package/daemon/docs/reference/whats-new.md

@@ -0,0 +1,134 @@
+# What changed in OpenRig 0.6.7
+
+This note is for an agent on an install that was just upgraded to 0.6.7. It lists only what behaves differently from
+0.6.6 and what to do about it. For everything OpenRig can do, read the capability map:
+`rig context get onboarding-width/public-what-you-can-do.md`. Each release replaces this file, so
+`rig context get reference/whats-new.md` describes the installed version once the upgraded daemon is running. Without
+a running daemon, read `$OPENRIG_HOME/reference/whats-new.md`. The daemon refreshes that copy when it starts, so right
+after an upgrade it can still hold the previous version's note.
+
+## The OpenRig view is now the handoff
+
+- **Open the view as the step after install or start; don't wait to be asked.** Say you're opening it, run
+  `rig terminal open saved:kernel --window`, then tell the person where it opened. Don't ask "Open the OpenRig view
+  now?", don't wait for a phrase like "show me my agents", and don't finish by printing a command for them to copy. The
+  same command brings their agents back later.
+- **The layout follows the person's terminal width.** On a narrow terminal the operator gets the first tab. On a wide
+  one the dashboard and operator sit side by side and the advisor has its own tab. Inside herdr it opens a focused
+  `openrig kernel` space. A `kernel` view the person saved themselves still wins.
+- **It opens where the caller is.** Terminal gets a window and Ghostty a tab. From Claude Desktop, iTerm or VS Code on a
+  Mac it opens a new Ghostty or Terminal window, and macOS may ask to allow it: mention that clicking Allow is fine only
+  in that case. Over SSH, in CI or with no display, it returns a definite no-window result with the reason. Relay the
+  `run:` command it prints exactly, or give `env -u TMUX tmux attach-session -t '=<canonicalSessionName>'` for the
+  operator.
+- **`rig terminal open <view>` opens a window by default.** Pass `--provider herdr` or `--provider cmux` only to add
+  tiles to a workspace that's already visible. With `--json`, `reusedWorkspace` and `opened: []` mean an existing view
+  was reused, which is success.
+- **The TUI's action is now "Open terminals ▸"** (it was `term ▸`). It opens a desktop window through the same
+  launcher, so the TUI must run on the daemon's desktop.
+- **The `rigs` skill is installed for the person's own agent.** The daemon writes it to `~/.claude/skills/rigs` and
+  `~/.agents/skills/rigs` and refreshes it on every upgrade. It now triggers on any mention of OpenRig, rigs or a team
+  of coding agents. A copy added earlier with skills.sh is left alone and never refreshed.
+
+## Installing and setting up
+
+- **Show the install preview first.** The published install command has a `--dry-run` preview
+  (`rig context get reference/getting-started.md` has both forms). Run the install when the person agrees. If the only
+  failures left are provider sign-ins, have them sign in and continue at "Start the kernel".
+- **If your own harness refuses a tool call while installing,** say so and show the refusal: Claude Code's auto mode can
+  deny calls as well as approve them. Let the person review it in their harness or run that step themselves. A refused
+  call doesn't prove the OpenRig command failed.
+- **`rig setup` installs herdr by default** on macOS and Linux; `--no-herdr` declines it. On a Mac, ask once about
+  Ghostty and on yes rerun `rig setup --ghostty`, keeping `--no-herdr` if it was chosen. Setup no longer installs cmux,
+  and an existing cmux still works. In `--json` output the `cmux_install` step is gone and `herdr_install` and
+  `ghostty_install` appear.
+- **`rig doctor` checks Claude and Codex installs, and a login or configured provider credential,** the way setup does.
+  It exits 1 when either harness is missing or has neither, including one the person doesn't use, so ignore a failure
+  on an unused harness. A pass means a login or configured provider credential is available locally, not that a
+  provider accepts the credential or that an agent can work; no provider request or agent work is tested.
+- **When setting up permissions,** recommend keeping the team default and offer remembered allowances only if the
+  person wants fewer prompts. People slowed by prompts can be pointed to the workshop listing.
+- **Windows users go through WSL2.** For Pi seats there, offer either credential route; a global Pi login still isn't
+  shared with managed seats.
+
+## Fewer prompts
+
+- **In Claude team seats, help on lifecycle commands runs without a prompt.** `rig down --help` and `-h` forms run;
+  the lifecycle actions themselves still ask. Pipelines, command substitutions, redirects and heredocs aren't allowed
+  automatically.
+- **The kernel operator's Claude session runs routine inspection without prompts:** Python, command lookup, `cd`, text
+  helpers and WebFetch. Compound commands and redirects still go to Claude's own permission check.
+- **Managed Codex seats no longer stop at the update menu on start.** Updating Codex is the operator's job: if a Codex
+  seat says its model needs a newer Codex, offer to update Codex and restart that seat, without stopping the team. If a
+  Codex seat shows a model-switch menu near a rate limit, ask the person; don't change the team's model.
+
+## Messages, wakes and Slack
+
+- **A send or wake no longer answers a question that's waiting for a person.** It's refused with
+  `target_needs_input`, and the reason ends `; latest hook, pane unrecognized` when the screen can't be read, even if
+  the hook is minutes old. Read the seat with `rig capture` and get the question answered by whoever should answer it.
+  Don't retry the send.
+- **Slack can post to a channel per rig or seat:** `rig slack channel-map list`, `set <match> <channel>` and
+  `remove <match>`. After a change, invite the app to each channel, run `rig slack verify`, then `rig slack disable`
+  and `rig slack enable` (or restart the daemon). Thread replies still reach the seat in any channel.
+- **A reaction on any part of a Slack ask reaches the seat that asked,** as a task tagged `human-reaction`. Treat it as
+  a signal to interpret, not an answer; the ask stays open. An existing app needs the `reactions:read` scope, the
+  `reaction_added` event and a reinstall, and `rig slack verify` warns when the scope is missing.
+- **A long Slack ask is posted in parts.** If it still can't be posted, you get a task `<ask id>-undeliverable`, tagged
+  `slack-undeliverable`: shorten the ask or link a file for the long part, and send it as a new ask.
+- **Replies sent with "Also send to #channel" now arrive** at the seat that asked, like any other thread reply.
+
+## Running teams
+
+- **`rig down` prints what each agent seemed to be doing before it stops them,** on one stderr line, or "unknown". It's
+  a best-effort snapshot, not a record of what was interrupted. `rig down --host` now exits 2 when the remote teardown
+  reports errors.
+- **Before a handover or compaction, write the seat's recap** with
+  `rig context recap-write --rig <rig> --seat <seat> --file <draft.md>`, not a file tool, so earlier recaps are kept.
+  `rig seat handover <seat>` now works on the same seat again and again; a seat left half-handed-over recovers by
+  running it again.
+- **After a managed compaction, read the `refocusing` skill and consume the current topology and work traces
+  delivered with the restore.** Don't rerun them just to duplicate the delivery; name a missing trace. For a new trace
+  outside that context, use the skill's one-command form. The daemon now installs the skill globally.
+- **The built-in starter and factory leads publish their team's roster** at first start, so `rig roster list` and
+  `rig roster find <topic>` know those teams.
+- **Claiming a parked queue item clears its `blocked_on`.** To park it again on the same gate, run
+  `rig queue update <id> --state blocked` without `--blocked-on`: it reuses the previous gate. Add the usual wake when
+  one is required.
+- **A periodic reminder first fires one interval after you register it,** not immediately.
+- **Workflows:** `rig workflow run` and `rig workflow watch` exit 3 for an aborted instance. When a step that was sent
+  back completes again, the steps that depend on it run again too, including ones that had passed.
+- **Sharing teams:** `rig bundle create` and `rig up <link>` name the bundle after `rig.yaml`'s `name`, and
+  `rig bundle check` names the file in each finding. Submissions go to `mvschwarz/openrig-registry`. The bundle safety
+  check always runs, even with `--skip-version-check --force`.
+- **`rig context add <url> --git` retrieves shallowly by default:** the initial retrieval fetches only the current
+  commit, and a server that refuses shallow retrieval falls back to a full clone with a warning. Use
+  `rig context source update` for later revisions.
+- **Values that used to fail quietly are refused:** a bad `rig chatroom history --since` (fix the value; the room isn't
+  empty) and a `--wake-after` such as `7d` (use hours, for example `168h`).
+- **Pi seats print a `[pi-runner] seat …:` line at start** saying whether a credential was found and, if not, how to
+  fix it. A MiniMax model gets `MINIMAX_API_KEY` when that name is in `recovery.provider_auth_env_allowlist`.
+- **`agents.advisor_session` defaults to the kernel's advisor seat.**
+
+## What to stop doing
+
+- **Stop asking whether to open the OpenRig view, or waiting for a phrase.** Open it after install or start.
+- **Stop using `--provider herdr` for the first view,** and stop pre-warning about macOS prompts from Terminal or
+  Ghostty.
+- **Stop suggesting `--skip-version-check --force` to get past a bundle pre-check failure.** The check always runs.
+- **Stop retrying a send refused with `target_needs_input`.** Get the question answered instead.
+- **Stop telling people to untick "Also send to #channel" when they answer in Slack.** Those replies now arrive.
+
+## Known gaps in 0.6.7
+
+- **Not yet checked on a real machine:** opening the view from Claude Desktop, and the plain-tmux layout without herdr.
+  The full first install from nothing and a Linux run come after this release.
+- **Only one selected lifecycle-help command has been checked in a live Claude session;** source and parser coverage
+  is broader. If a help command still asks, report it.
+- **Codex team seats aren't asked before lifecycle commands yet.**
+- **The send gate trusts the most recently recorded hook.** If hooks are recorded out of order, it can hold a send for
+  a question that's already answered, or miss one that's waiting. `rig capture` shows the real screen.
+- **A Codex seat whose permission request was approved automatically can still read "needs input".**
+- **A launched team still writes its skills into its working folder.**
+- **After a restart, `rig status` shows `Kernel: skipped` whatever the kernel seats' state.** Read them with
+  `rig ps --nodes --rig kernel --full`.

package/daemon/specs/agents/shared/skills/core/openrig-skills/SKILL.md

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

package/daemon/specs/agents/shared/skills/core/openrig-software-factory/SKILL.md

@@ -51,7 +51,7 @@ or `codex login` once when that selected login is missing. No credential copying
 unused provider prerequisite or silent model/provider fallback.
 
 Read the compatible getting-started guide's **Choose your providers** and
-**Kernel startup stays automatic** sections before launch. The choice selects
+**Start the kernel and check its state** sections before launch. The choice selects
 the two project agents. Kernel auto-boot independently uses available
 authenticated accounts, so it may use both even when the project uses one.
 Do not add an unused-provider login gate or manual kernel setup to this path.
@@ -63,7 +63,8 @@ Show the chosen team, resolved runtimes/models and exact
 retain `gpt-6-astra`; Claude seats use the configured native default without an
 OpenRig model override. Confirm that model with the user and its availability;
 verify the native session's actual model before consequential work. Use the
-chosen rig name in owner/checker addresses throughout the same task and return.
+chosen rig name in owner/checker addresses (in the starter, `dev-build@<rig>` and
+`dev-review@<rig>`) throughout the same task and return.
 
 ## Establish the working agreement
 
@@ -79,16 +80,21 @@ model turns, but delivered wakes and resumed work **can spend tokens**. Prefer
 an event-driven wait to frequent empty reminders. Wakes cannot answer a user
 question, clear a permission prompt or guarantee progress.
 
-**Ask once before launching or assigning work:** “Allow your agents to run
-OpenRig commands without repeated permission prompts?” **Yes — recommended** /
-**No — keep prompts**. Reuse an existing explicit choice for this scope. Explain
-that this covers all `rig` verbs, including starting/stopping agents and changing
-configuration, at personal project scope unless the user explicitly chooses
-user-wide sessions. It is not global YOLO or permission to invent work.
+**Ask once before launching or assigning work.** For a team with no permission
+policy, seat choice or named Codex profile, recommend keeping the team default:
+Claude team seats run ordinary `rig` commands, project reads and common tests
+without prompts, and lifecycle commands such as `rig up` and `rig down` still
+ask. Only if they want more, offer: “Remember these selected OpenRig commands in
+your native settings for this project?” **Yes** / **No — keep the team default**.
+Reuse an existing explicit choice for this scope.
+Explain that a remembered allowance can cover all `rig` verbs, but Claude team
+seats still ask before lifecycle commands, at personal project scope unless the
+user explicitly chooses user-wide sessions. It is not global YOLO or permission
+to invent work.
 On an actual Yes, follow [Applying a permission policy](#find-the-compatible-permission-guide)
 to add existing native rules, preserve stricter/unrelated settings, and verify
-the target conversation. No or no answer leaves settings alone and continues
-with existing prompts. Remember the explicit choice and exact additions in the
+the target conversation. No or no answer leaves settings alone and keeps the
+team default. Remember the explicit choice and exact additions in the
 existing onboarding context; “Undo the OpenRig command allowances added by this
 setup” removes only those additions. Broader access remains a separate opt-in.
 
@@ -102,8 +108,9 @@ or explicitly reports none. Preserve work and custody before a supported stop.
 
 Choose the team size separately from the coordination method above:
 
-1. **Use the two-agent starter.** Keep the existing owner and independent checker
-   while that pair meets the workload. The owner can implement and coordinate.
+1. **Use the two-agent starter.** Keep its builder (the owner) and independent
+   reviewer (the checker) while that pair meets the workload. The builder can
+   implement and coordinate.
 2. **Add one or two seats to the running rig.** This is the usual next step.
    Follow [Grow the running team](references/worked-example.md#grow-the-running-team)
    for `rig grow` commands, readiness/context/work

package/daemon/specs/agents/shared/skills/core/openrig-software-factory/references/worked-example.md

@@ -86,8 +86,8 @@ permissions, supplies a missing product decision or authorizes more work.
 
 ## Permissions at the point of work
 
-Before the first task, ask the agent to configure your choice: keep prompts,
-remember selected commands, or deliberately select broader access. Use
+Before the first task, ask the agent to configure your choice: keep the team
+default, remember selected commands, or deliberately select broader access. Use
 `rig context get skills/applying-a-permission-policy/SKILL.md`, or the
 [compatible source/package paths](../SKILL.md#find-the-compatible-permission-guide).
 The agent handles setup and verifies the actual conversation; the user need not

package/daemon/specs/agents/shared/skills/core/openrig-upgrade/SKILL.md

@@ -239,6 +239,8 @@ host in front of you.
     mechanism; this skill does not rewrite launchers.
 11. Record the observed result, remaining local preservation decisions, and the
     exact rollback runtime and backup.
+12. Read what changed in the new version, `rig context get reference/whats-new.md`,
+    and tell your user anything in it that changes how they work.
 
 ## Stop and hand back when
 

package/daemon/specs/rigs/launch/factory/guidance/lead-first-move.md

@@ -21,3 +21,63 @@ When the goal is done, close the operator's row with the result.
 
 `rig down` and `rig seat stop` end agents' sessions and any work in progress, and `rig up <spec>` on a stopped team's
 name replaces it with a new team. Don't run them unless the person asked; check `rig ps --nodes` first.
+
+## Publish the team's roster
+
+A roster tells anyone who uses `rig roster find` who to ask on this team and why. Write one the first time you start,
+alongside the goal, and never replace one that exists:
+
+1. Take the rig's name from `rig whoami --json` (`identity.rigName`). It is `factory` unless this team was launched
+   under another name; `<rig>` below means that name. If it is null, the rig name is unavailable: skip the roster
+   for now and try again when identity is available.
+2. Run `rig roster list`. If it shows a roster with id `<rig>`, stop here.
+3. The file is `<workspace.root>/rosters/<rig>.json`; `rig config get workspace.root` gives the root. If the file
+   exists, stop here too. Create the `rosters/` folder if it is missing.
+4. Run `rig ps --nodes --rig <rig> --json --fields canonicalSessionName,hostSelfId`. It gives each seat's exact address
+   and the host that serves it.
+5. Match `orch-lead` (you) to lead, `orch-advisor` to advisor, `dev-build` to builder, `dev-qa` to QA,
+   `dev-design` to designer, and `review-r1` and `review-r2` to the two reviewers, using the actual addresses from step 4.
+   Write the file with those addresses and hosts, today's date, and yourself as curator (format: OpenRig's
+   `$OPENRIG_HOME/reference/rosters.md`):
+
+   ```json
+   {
+     "version": 1,
+     "id": "<rig>",
+     "name": "Factory",
+     "purpose": "Plan, build, design and check software in this repository as a full team",
+     "curator": { "seat": "<your address>", "host": "<your host>" },
+     "updated_at": "<YYYY-MM-DD>",
+     "members": [
+       { "seat": "<lead>", "host": "<host>", "capabilities": ["planning", "routing work"],
+         "engagement": ["consult", "delegate"], "use_when": "Deciding what to build next, or who should take a piece",
+         "why": "Leads this team, talks to the person and routes the work" },
+       { "seat": "<advisor>", "host": "<host>", "capabilities": ["product intent", "ideas"],
+         "engagement": ["consult"], "use_when": "Shaping an idea, or checking that work still serves the goal",
+         "why": "The lead's idea and intent partner" },
+       { "seat": "<builder>", "host": "<host>", "capabilities": ["implementation"],
+         "engagement": ["delegate"], "use_when": "A planned piece needs building",
+         "why": "Builds the changes the lead routes to it" },
+       { "seat": "<QA seat>", "host": "<host>", "capabilities": ["testing", "verification"],
+         "engagement": ["review"], "use_when": "A change needs its checks run and reported",
+         "why": "Runs the checks a change calls for and says what each one proved" },
+       { "seat": "<designer>", "host": "<host>", "capabilities": ["product design", "user experience"],
+         "engagement": ["consult", "review"], "use_when": "A change affects what people see or how they use it",
+         "why": "Designs and reviews the user-facing side" },
+       { "seat": "<reviewer 1>", "host": "<host>", "capabilities": ["code review"],
+         "engagement": ["review"], "use_when": "A change needs an independent review",
+         "why": "One of two independent reviewers" },
+       { "seat": "<reviewer 2>", "host": "<host>", "capabilities": ["code review"],
+         "engagement": ["review"], "use_when": "A change needs an independent review",
+         "why": "The second independent reviewer; ask both for important changes" }
+     ]
+   }
+   ```
+
+6. Run `rig roster list` to see it listed, then tell the person in one line.
+
+Running this again, after `rig seat continue` or a restore, changes nothing. When a seat takes on a capability worth
+asking it about, add it to that seat's `capabilities` and set `updated_at` to today; starting again never replaces the
+file.
+
+Need expertise your team lacks? `rig roster find <topic>` lists who to ask and why.

package/daemon/specs/rigs/launch/kernel/agents/operator/agent/guidance/role.md

@@ -5,12 +5,30 @@ and the affected work before acting. You already own these operational
 diagnoses; the queue worker retains intake classification. Never report an
 unknown activity signal as idle or a persisted running record as process proof.
 
-The shared dashboard is the kernel's `operator.human` terminal. The human can enter with
-`rig tui --shared`, or through `rig terminal open saved:kernel --provider herdr`
-(cmux is also supported). It is an ordinary TUI in a terminal, not an agent
-or human-message inbox. Capture it before driving it, preserve the user's view
-unless the task calls for navigation, and use the registered human channel for
-decisions. If the TUI has exited, its shell remains; run `rig tui` there once.
+For the kernel's first-boot health check, run `rig daemon status` and
+`rig ps --nodes --rig kernel` as separate shell tool calls and read their output
+directly. Claude Code can ask for approval for a compound command containing
+pipes, redirects or subshells even when its individual commands are allowed;
+these plain commands let the health check finish without that extra prompt.
+
+When the person wants to see their agents or OpenRig in a terminal, in any words, run
+`rig terminal open saved:kernel --window` on the daemon's desktop. It opens the
+OpenRig TUI and operator in a new terminal tab/window, or a space in the current Herdr session:
+below 120 measured columns, operator alone first;
+from 120, dashboard and operator equally side by side. The advisor has a separate tab or tmux window. Inspect its result and visible content, or state what you cannot confirm. On a desktop, do
+not end by showing a table or suggesting a command for the person to type. Herdr is visible
+only inside a terminal the person can see; changing the shared TUI to `:terminals`
+does not open one. Over headless SSH, explain that limitation, ask the person to
+open a new terminal window or tab, and give one exact connection and attachment
+command using the current Herdr endpoint or operator binding from the
+getting-started guide. Do not report a window as visible without confirming it.
+Only if that window cannot open, `rig tui --shared` is the named dashboard-only
+fallback. Explain the window failure and help with the chosen fallback.
+The shared dashboard is the kernel's `operator.human` terminal, an ordinary TUI,
+not an agent or human-message inbox. Capture it before driving it, preserve the
+user's view unless the task calls for navigation, and use the registered human
+channel for decisions. If the TUI has exited, its shell remains; run `rig tui`
+there once.
 
 You run OpenRig on behalf of the user. The operator pod's `operator.human`
 member holds their shared terminal view. Human decisions use the registered
@@ -21,6 +39,15 @@ human channel; a terminal attachment is not a person's address.
 - Bring rigs up and down (`rig up <spec>`, `rig down <rigId>`). `rig down` and `rig seat stop`
   end agents' sessions and any work in progress: check `rig ps --nodes --rig <name>` first, and
   stop a team or seat only when the person asked for it.
+  For "stop everything", list the rigs with `rig ps --json`, then run `rig down`
+  for each rig they want stopped while the daemon is available. Stop kernel last
+  if it is included, since that ends your own session too. `rig daemon stop`
+  stops the service but leaves agent sessions running; it comes after the rigs
+  when the person also wants the service stopped.
+  If the service should also stop and kernel is included, before running
+  `rig down kernel` tell the person to run `rig daemon stop` in their own shell
+  once kernel is down and check its result. That hands off the final service
+  stop before your own session ends.
 - Restart selected work after a reboot. Bare `rig` starts only the daemon;
   the TUI recommends kernel first and lets the user select individual seats.
   When the user says "bring my rigs back online":
@@ -43,6 +70,13 @@ After install, the person usually talks to you first. When they are talking to
 you in this pane, their answers here are their decisions; don't send a launch
 question through the human channel instead.
 
+For a team's `/rigs` listing page, use `WebFetch` when available. It returns
+page text and is already allowed by the kernel's Claude defaults, avoiding
+approval for an HTML-cleanup shell pipeline. If it is unavailable or fails,
+use a plain `curl -fsSL <listing-url>` call and read the response directly.
+Fetch the raw registry YAML separately for the installation commit and
+configurations, as below; do not take the pin from a cached page summary.
+
 1. **Goal first.** Use a goal and folder already supplied, including a handoff
    from the installing agent; do not ask for them again. If the goal is missing,
    ask once: "What would you like to build or change?" If they already named a
@@ -52,30 +86,70 @@ question through the human channel instead.
    own working directory is OpenRig's workspace, not their project, so never launch with
    `--cwd .` from here.
 3. **Three teams, one recommendation.** Present starter, workshop and factory,
-   recommend one with a short reason tied to their goal, and draw each:
+   recommend one with a short reason tied to their goal, and show each graph
+   in the shared TUI as you explain it (step 4):
    - `starter`: a builder and a reviewer (`dev-build`, `dev-review`) for one
      bounded change. Built in; `first-project` is its old name.
    - `workshop`: a lead, a builder, a QA seat and a reviewer for ongoing work
      in one repository. Not built in: it installs from its listing on
      openrig.dev/rigs, a GitHub folder link pinned to a reviewed commit. Read
      the commit and its configurations from
-     https://raw.githubusercontent.com/mvschwarz/openrig-world/main/registry/workshop.yaml,
+     https://raw.githubusercontent.com/mvschwarz/openrig-registry/main/registry/workshop.yaml,
      fetched fresh, for example with `curl -fsSL <that link>`. A web tool's cached
      copy can be older than the current pin and would launch an older workshop;
      the raw link itself can trail a new pin by a few minutes (it is cached for
-     300 seconds).
+     300 seconds). If permission prompts are slowing the person down, point
+     them to https://openrig.dev/rigs/workshop: the bundle ships with broad
+     access and non-interruptive mode, bypassing permission prompts and
+     supported harness warning dialogs. Its listing and before-install view
+     explain that access so they can choose it knowingly.
    - `factory`: seven agents (a lead, an advisor, build, QA, design and two
      independent reviewers) for sustained product work. Built in; it uses the
      most concurrent capacity.
    Offer the shelf only when the goal asks for it: `code-review` (two
    independent reviews), `research` (an analyst and a synthesizer) and `pm` (a
    product lead, a researcher and a builder for prototypes).
-4. **Draw from the real spec, before anything starts.** For a built-in team,
-   run `rig specs preview <team> --kind rig --json` and draw members and
-   runtimes from `graph.nodes` and edges from `graph.edges`, for example
-   `[dev.build, Claude] --delegates_to--> [dev.review, Codex]`, with one line
-   on what each role does. For workshop, draw from its `rig.yaml` at the pinned
-   commit.
+4. **Show the real spec, before anything starts.** Find the shared TUI's
+   `canonicalSessionName` on the kernel's `operator.human` member with
+   `rig ps --nodes --rig kernel --json`, then capture that pane with
+   `tmux capture-pane -p -t '=<session>:'`, substituting that canonical name
+   for `<session>` and keeping the trailing colon. When it shows
+   the TUI's normal view and an empty command line, type the TUI command
+   `spec starter` and Enter with `tmux send-keys -t '=<session>:'`. A rig spec
+   opens on its graph tab; capture again and confirm the named spec and its graph
+   are visible while you explain its roles. Do the same with `spec workshop`
+   and `spec factory` as you present those choices. These are TUI commands,
+   not shell commands. Previewing does not launch a team; leave the Launch
+   action for after the person's choice and approval.
+   - **Workshop's preview:** first inspect `rig specs ls --kind rig --json`.
+     If exactly one workshop entry is listed, show it and add nothing; say if
+     its source differs from the pinned install you are offering. If several
+     entries share that name, explain the ambiguity and use the text fallback
+     rather than letting `spec workshop` pick the first one. Otherwise, create
+     a temporary directory with `mktemp -d` and put a clean checkout of the
+     exact commit in the fresh registry listing from step 3 inside it.
+     Verify `git -C <checkout> rev-parse HEAD` equals that commit and
+     `git -C <checkout> status --porcelain -- rigs/workshop` is empty; use its
+     complete `rigs/workshop` folder. Tell the person: "Showing workshop
+     adds this version to your team library; it doesn't start any agents."
+     Run `rig specs add <pinned-workshop-folder> --json`; once it succeeds,
+     the temporary checkout can be removed because the library has its own
+     copy. Refresh the TUI and open `spec workshop`. Keep that same commit in
+     the later install link: the preview is a library copy, while installation
+     still uses the pinned link and `--target ~/rigs/workshop`, not the bare
+     library name.
+     Do not overwrite an existing workshop entry. If you cannot bind the
+     copy to that commit or the preview copy prevents the pinned install,
+     explain why workshop needs the text fallback below.
+   - **If the graph cannot be shown:** at the shared pane's shell prompt,
+     start `rig tui` there once, then capture before navigating. If it has a
+     startup screen, a dialog, unfinished input or another program, preserve
+     it. Name the unavailable preview and draw that team in the conversation
+     instead; use this fallback only when the TUI or that exact graph cannot
+     be driven. For a built-in team, read
+     `rig specs preview <team> --kind rig --json`: draw members and runtimes
+     from `graph.nodes` and edges from `graph.edges`, with one line on each
+     role. For workshop, draw from its `rig.yaml` at the pinned commit.
 5. **Fit it to their providers.** Infer which tools they have from the
    kernel's own runtimes (`rig ps --nodes --rig kernel --json`), or ask. Check
    only the providers the team needs (`claude auth status` or
@@ -120,12 +194,24 @@ question through the human channel instead.
    person or a fix. If `rig up` reports `Status: partial` with
    `Startup attention (<seat>): <reason>`, tell them what that seat is waiting
    for and the command its reason ends with.
+   Relay any untracked-file warnings from `rig up` to the person, including the
+   paths and suggested local exclude lines. Those files were created by the
+   launch, so describe them as OpenRig additions rather than pre-existing work.
+   - **A Codex seat says its model requires a newer version of Codex:** their
+     Codex is older than the model the team pins (the starter's reviewer uses
+     `gpt-6-astra`, which Codex 0.145 can't run). Tell them, and offer to update
+     Codex the way it was installed, for example
+     `npm install -g @openai/codex`. On their yes, update it, then start
+     that seat again. It's context for them, not a reason to stop or change the
+     team.
 8. **Show them the team.** Capture the shared TUI: its session is the
    `operator.human` member's `canonicalSessionName` in
-   `rig ps --nodes --rig kernel --json`. Only when the capture shows the TUI's
-   own view, type the TUI command `rig <team>` and Enter into that pane (tmux
-   send-keys to its session), and capture again to confirm it shows the team's
-   table.
+   `rig ps --nodes --rig kernel --json`. Use
+   `tmux capture-pane -p -t '=<session>:'`, substituting that canonical name
+   for `<session>` and keeping the trailing colon. Only when the capture shows
+   the TUI's own view, type the TUI command `rig <team>` and Enter into that pane
+   with `tmux send-keys -t '=<session>:'`, and capture again to confirm it shows
+   the team's table.
    At a shell prompt, run `rig tui` there first or tell them the command; if a
    startup view or another mode holds the keys, leave it and tell them the
    command instead. Then open the team's terminals as a new space with

package/daemon/specs/rigs/launch/kernel/culture/CULTURE.md

@@ -16,8 +16,11 @@ machine and have things happen.
   acts on behalf of the operator.human; ops decisions needing human
   approval escalate.
 - **operator.human** is the shared mission-control terminal. A fresh kernel
-  starts `rig tui` there. `rig tui --shared` attaches another client to that
-  same terminal; detaching preserves navigation. It is a screen, not proof a
+  starts `rig tui` there. When the person wants to see their agents or OpenRig in a terminal, run
+  `rig terminal open saved:kernel --window`: below 120 measured columns, operator first; from 120,
+  dashboard and operator equally side by side. The advisor keeps a separate tab or tmux window. Only if
+  the window cannot open, `rig tui --shared` is the dashboard-only fallback;
+  detaching preserves navigation. It is a screen, not proof a
   person is watching or a destination that can answer a queue item. Use the
   registered human delivery channel when a decision is required.
 - **queue.worker** classifies stream-to-queue substrate. New stream