docs: open a new kernel conversation space after installation (#821)

After installation, the installing agent tells the person it will open a terminal so they can see their OpenRig agents, then opens a new space with existing tools: herdr, else cmux, else a plain terminal window. The first space shows the kernel advisor, the operator agent and the OpenRig TUI for a dual kernel, or the advisor and the TUI for a single-runtime kernel; it never takes over the installing agent's terminal or an existing space. Getting started gives the same steps as exact commands for a person, with session names taken from the kernel inventory, and on a headless or SSH target it says so and gives the exact attach command. The README, help, onboarding guide and setup's final text point to it.

README.md

@@ -56,9 +56,10 @@ starter=first-project  # or first-project-claude or first-project-mixed
 rig specs preview "$starter" --kind rig
 rig up "$starter" --cwd . --plan
 rig up "$starter" --cwd .
-rig tui --shared
 ```
 
+After installation, your agent should [open a **new kernel conversation space**](docs/reference/getting-started.md#open-the-kernel-conversations): herdr first, then cmux, then a plain terminal. It tells you before opening it and keeps its own terminal and your existing spaces intact. The guide also gives the manual and SSH commands.
+
 The kernel provides separate operational support and the shared dashboard. To detach without stopping the dashboard, press Ctrl-b then d; `rig tui --shared` returns to that view. Plain `rig tui` opens an independent view. Closing a viewing terminal does not mean you should relaunch the team.
 
 Check project-seat readiness with `rig ps --nodes --rig "$starter"` and resolve any authentication, trust or permission prompt before assigning work. If a seat stopped at such a prompt before its startup context arrived, `rig ps` shows the `rig seat continue <seat>` command that delivers it once the prompt is answered. Then give the owner one bounded outcome from your repository:

docs/reference/getting-started.md

@@ -163,6 +163,175 @@ 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)).
 
+## Open the kernel conversations
+
+Once OpenRig and the existing kernel are available, the installing agent tells
+you: **“I'll open a new terminal space so you can see and talk to the kernel
+agents, with the OpenRig TUI beside them.”** It then opens that space using
+existing tools, even when installation is being performed from an agent's own
+terminal. It must not attach in that terminal, switch an existing tmux client,
+or replace another window's contents.
+
+Use **herdr first**, **cmux second**, and otherwise a **new plain terminal
+window**. The first view contains the advisor, operator agent and TUI for a
+dual-runtime kernel, or the advisor and TUI for a single-runtime kernel.
+The queue worker stays out of this view; it remains reachable through the TUI.
+This selects what you see, not which kernel seats run. Keep the current kernel,
+accounts and conversations; opening a view is not a reason to start or restore
+seats. If the kernel is absent or not ready, report that and follow
+[Incomplete setup and restart](#incomplete-setup-and-restart).
+
+### Confirm the existing seats
+
+Run these on the daemon's machine, in the installation environment:
+
+```sh
+rig status
+rig ps --nodes --rig kernel --json --fields logicalId,runtime,canonicalSessionName,tmuxAttachCommand
+rig terminal status --json
+```
+
+Use the returned bindings, not the library preview. Find the rows whose
+`logicalId` is `advisor.lead`, `operator.agent` and `operator.human` (the TUI).
+For each, take its `canonicalSessionName`; a logical ID is not a tmux session
+name. The installing agent fills in those exact values before opening the
+view or handing commands to you. Missing bindings stay named missing. Compare
+the advisor and operator runtimes to choose the dual- or single-runtime view.
+
+### Herdr or cmux: one new workspace
+
+Both providers can open the same saved view. On the daemon's machine, add the
+following entry to `terminal-views.yaml` in its OpenRig home (normally
+`~/.openrig`; `OPENRIG_HOME`, or the legacy `RIGGED_HOME`, selects another home).
+If the file already has views, keep them and add only this entry; choose a fresh
+id if `kernel-conversation` already means something else. In this template,
+replace each `SESSION_FOR_...` value with the `canonicalSessionName` from the
+matching logical-ID row above; these are placeholders, not literal targets:
+
+```yaml
+version: 1
+views:
+  - id: kernel-conversation
+    name: Kernel conversation
+    members:
+      - seat: SESSION_FOR_ADVISOR_LEAD
+        label: Advisor
+      - seat: SESSION_FOR_OPERATOR_AGENT
+        label: Operator
+      - seat: SESSION_FOR_OPERATOR_HUMAN
+        label: OpenRig TUI
+```
+
+For a **single-runtime kernel**, omit the Operator member and keep Advisor and
+OpenRig TUI. The saved view is read when opened; no daemon restart is needed.
+If you chose a different view id, substitute it in the commands below. Preserve
+unrelated saved views.
+
+Check `rig terminal status --json` for provider availability and liveness. If
+herdr is installed but closed, open the app normally and check again. When it
+is available:
+
+```sh
+rig terminal views --json
+rig terminal open saved:kernel-conversation --provider herdr --json
+```
+
+If herdr is unavailable, use a running cmux:
+
+```sh
+rig terminal open saved:kernel-conversation --provider cmux --json
+```
+
+These view opens create a fresh provider workspace. Inspect `opened`, `absent`,
+`degraded` and any notes, then confirm the new workspace actually shows the
+intended conversations and TUI. A partial result is not a complete handoff.
+Do not use `rig terminal open kernel` for this first view: it also includes the
+queue worker. A failed or uncertain open is not evidence that nothing opened;
+inspect the provider before retrying or falling back. If the shared TUI tile
+shows a shell, run `rig tui` **in that new tile**, not in the installing agent's
+terminal.
+
+### Plain terminal: a new viewing session
+
+If neither provider is available, compose existing tmux attachments. These
+commands create only a new viewing session; they do not move or recreate the
+kernel's panes. Run them once on the kernel host after checking the bindings
+above. For a manual install, these prompts collect the two exact session names
+from that inventory. An installing agent sets the same variables from the
+observed values itself:
+
+```sh
+printf 'canonicalSessionName for advisor.lead: '; read -r advisor_session
+printf 'canonicalSessionName for operator.human (TUI): '; read -r tui_session
+kernel_view="openrig-kernel-$(date +%s)-$$"
+kernel_pane=$(tmux new-session -d -P -F '#{pane_id}' -s "$kernel_view" -n kernel "env -u TMUX tmux attach-session -t '=$advisor_session'")
+tmux split-window -h -t "$kernel_pane" "env -u TMUX tmux attach-session -t '=$tui_session'"
+```
+
+For a dual-runtime kernel, add the operator beside the advisor:
+
+```sh
+printf 'canonicalSessionName for operator.agent: '; read -r operator_session
+tmux split-window -h -t "$kernel_pane" "env -u TMUX tmux attach-session -t '=$operator_session'"
+```
+
+Then arrange the view and print its exact attach command:
+
+```sh
+tmux select-layout -t "$kernel_view:" even-horizontal
+printf "env -u TMUX tmux attach-session -t '=%s'\n" "$kernel_view"
+```
+
+**On macOS**, the installer can open a new Terminal window with that view:
+
+```sh
+osascript - "$kernel_view" <<'APPLESCRIPT'
+on run argv
+  tell application "Terminal"
+    do script "env -u TMUX tmux attach-session -t " & quoted form of ("=" & item 1 of argv)
+    activate
+  end tell
+end run
+APPLESCRIPT
+```
+
+**On a Linux desktop with GNOME Terminal**, use its explicit new-window action:
+
+```sh
+gnome-terminal --window -- env -u TMUX tmux attach-session -t "=$kernel_view"
+```
+
+For another terminal app, use its **New Window** action and run the attach
+command printed above in that window. The installing agent should perform the
+available new-window action, not stop at printing advice when it can open it.
+If desktop automation is unavailable or denied, say so and give the printed
+command to the person for a new terminal. Never silently reuse an existing
+window. Close the viewing window or use **Ctrl-b, then d** to detach; don't
+quit the native agents. A standalone `rig tui` in another new terminal is also
+available if the shared TUI binding is missing, with that limitation stated.
+
+### Headless or SSH handoff
+
+A provider running on the server does not establish a window on your desktop.
+When there is no display, say **“No visible terminal was opened here.”** Keep
+the exact attach command printed above. From a new terminal on your own
+machine, connect to the same host/account used for installation, then run that
+command. For example, this asks for the actual SSH destination and the viewing
+session name printed above; neither value is guessed:
+
+```sh
+printf 'Existing SSH destination (user@host): '; read -r kernel_host
+printf 'Viewing session name (openrig-kernel-... printed above): '; read -r kernel_view
+ssh -t "$kernel_host" "env -u TMUX tmux attach-session -t '=$kernel_view'"
+```
+
+The installing agent gives you the **fully resolved** connection and attach
+command from the known installation host and created viewing session. If only
+an HTTP daemon address is known, ask for the SSH connection details instead of
+inventing them. No new account or credential provisioning is part of this
+handoff. Report which provider or fallback ran, which conversations and TUI
+were visible, and any headless or unverified branch.
+
 ## Give the owner an outcome
 
 For example, in a project that imports CSV files:
@@ -210,7 +379,8 @@ guidance rather than creating a second kernel.
 
 Herdr users follow the same launch and task path. To place the managed team in
 Herdr, use `rig terminal open "$starter" --provider herdr`; for the shared
-dashboard, use `rig terminal open kernel --provider herdr`. The equivalent
+dashboard together with the kernel conversations, use the
+[saved first view](#open-the-kernel-conversations). The equivalent
 cmux provider is also available. Read the opened/absent/degraded result: a
 partial terminal view is not a healthy team. Repeated terminal-open calls can
 create another provider workspace; return to the one already open when you

docs/reference/help.md

@@ -47,6 +47,16 @@ Supported platforms are macOS and Linux. Native Windows is not supported yet, an
 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.
 
+### 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`). Once the existing kernel is available,
+tell the person you will open a new terminal space, then do it: herdr, otherwise cmux, otherwise a new plain terminal
+window. Show advisor, operator agent and TUI for a dual-runtime kernel, or advisor and TUI for a single-runtime
+kernel. Leave the queue worker accessible through the TUI. Being an installing agent is not a reason to skip this;
+keep your own terminal and existing user spaces intact. If no display can be opened, report that and supply the exact
+connection/attach command. The guide uses existing views and tmux; it does not call for another kernel or new accounts.
+
 ### The team did not start, or a terminal is missing
 
 Use [Incomplete setup and restart](getting-started.md#incomplete-setup-and-restart)

packages/cli/src/commands/setup.ts

@@ -784,7 +784,11 @@ export function goldenPathNextSteps(): string[] {
     "     Preview rig up <starter> --cwd . --plan, then rig up <starter> --cwd .; daemon and kernel start automatically",
     "  3. rig status                       Check daemon/kernel readiness; rig ps --nodes --rig <starter> checks the team",
     "  4. rig send dev-owner@<starter> '<one useful change, boundaries, and how to check it>'",
-    "  5. rig tui --shared                  Join the kernel dashboard; plain rig tui opens your own view",
+    "  5. Open a NEW kernel conversation space: herdr, otherwise cmux, otherwise a new terminal window",
+    "     rig context get reference/getting-started.md#open-the-kernel-conversations",
+    "     Installing agent: tell the person, then open it; keep your own terminal and existing spaces intact",
+    "     Manual: the guide gives exact provider/tmux commands; headless/SSH: report no window and give the connection/attach step",
+    "     rig tui --shared joins the existing kernel TUI from a new terminal; plain rig tui opens an independent view",
     "  Next: rig queue list --destination dev-owner@<starter>; rig workspace doctor; rig scope ...; rig workflow specs",
   ];
 }

packages/daemon/assets/onboarding/02-self-and-competent-action.md

@@ -42,6 +42,19 @@ looked like. State scoped absences honestly: “not represented on the surface c
 than a global absence you did not establish. If another seat must act, transfer durable work rather
 than printing a summary and disappearing.
 
+## When you are installing OpenRig for someone
+
+Once OpenRig and its kernel are available, tell the person you will open a new terminal space so they can talk to
+the agents. Then use the existing tools to open it: herdr first, otherwise cmux, otherwise a new plain terminal window.
+Do this even from an agent's installation session; never attach into your own terminal or take over an existing space.
+Show advisor, operator agent and TUI for a dual-runtime kernel, or advisor and TUI for a single-runtime kernel.
+Keep the queue worker off the first view and accessible through the TUI. Reuse the existing conversations and accounts.
+
+Read `rig context get reference/getting-started.md#open-the-kernel-conversations` for the commands and manual
+path. Without a working daemon, the same guide is `daemon/docs/reference/getting-started.md` in the installed
+`@openrig/cli` package. Confirm what actually opened; on a headless host or unavailable display, say so and give the
+person the exact connection/attach step. Opening a terminal is not permission to start or reset seats or provision accounts.
+
 ## When you need more
 
 When you need to know what OpenRig can do, run `rig context get onboarding-width`: its

scripts/generate-context-packs.test.mjs

@@ -605,6 +605,7 @@ test("HELP ADDRESSES: every guide address taught in help.md resolves through the
     assert.deepEqual(addresses.sort(), [
       "reference/getting-started.md#have-your-agent-configure-permissions",
       "reference/getting-started.md#incomplete-setup-and-restart",
+      "reference/getting-started.md#open-the-kernel-conversations",
       "reference/instance-layout.md",
       "reference/rig-spec.md",
     ]);