@sublang/playbook 7.0.0 → 8.0.0

package/README.md

@@ -19,7 +19,11 @@ SubLang Playbook addresses both:
 
 ![Venn diagram: Skill is flexible, Workflow is deterministic, and Playbook sits in the intersection as both.](docs/assets/playbook-venn.svg)
 
-Vocabulary: the **Boss** is you; the **Captain** is the coordinating agent you talk to; **players** are the agents a playbook delegates work to.
+Vocabulary: the **Boss** is you; the **Captain** is the coordinating agent you
+talk to; a **role** is a playbook-local job such as `coder`; and a **player** is
+a stable Captain-session agent and provider conversation to which one or more
+roles bind. Roles describe the workflow, while player IDs decide which work
+shares conversation continuity.
 
 Run `playbook` for an interactive tmux UI powered by [cligent](https://github.com/sublang-ai/cligent), or `playbook run` for the same Captain session without tmux in scripts and CI.
 
@@ -28,7 +32,10 @@ Run `playbook` for an interactive tmux UI powered by [cligent](https://github.co
 Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, and **DECIDE** for independently proposed and reviewed specification decisions.
 CODE and DECIDE call REVIEW as a nested playbook.
 
-The shared starter config uses Claude as both Captain and Coder, and Codex as Reviewer.
+The shared starter config uses Claude as both Captain and the `dev.coder`
+player, and Codex as `dev.reviewer`. CODE, REVIEW, and DECIDE bind their local
+roles explicitly to those two stable players, so nested and later engagements
+share a conversation only where their bindings name the same player ID.
 
 ```sh
 npm install -g @sublang/playbook
@@ -44,7 +51,7 @@ Prerequisites:
 - Authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY`
 - Authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY`
 
-Interactive `playbook` additionally needs `tmux` and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`; headless `playbook run` does not.
+Interactive `playbook` additionally needs tmux 3.3 or newer and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`; headless `playbook run` does not.
 
 CODE works in the current directory and can edit and commit autonomously, so use a clean branch or worktree.
 
@@ -58,12 +65,18 @@ Type a task, enter `/code <task>` for implementation, or enter
 
 On first launch, Playbook writes its config to `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`.
 
-The same config, compiled Captain, enabled playbooks, players, and nested calls power headless turns.
+The same config, compiled Captain, enabled playbooks, stable players, and
+nested calls power headless turns. Both front ends create the same durable
+logical session: copy the reported session ID to reopen an interactive session
+headlessly or a headless session interactively.
 Run REVIEW explicitly, or pipe a longer request to Captain:
 
 ```sh
 playbook run "/review review the latest commit"
 printf '%s\n' 'Implement the approved specification, then review it.' | playbook run
+# Later, either presentation can reopen the returned/reported session id:
+playbook --session 4f2c0000-0000-4000-8000-000000009ab1
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 "continue"
 ```
 
 `playbook run` prints the one Boss-visible Captain reply to stdout and operational status to stderr; CODE and DECIDE can complete their nested REVIEW calls there too.

package/docs/cli.md

@@ -8,6 +8,9 @@ interactive tmux-play UI and a headless `playbook run` turn for scripts and
 CI. Both use the same compiled Captain, enabled catalog, players, nested
 stack, and [config](configuration.md); only presentation differs.
 
+The interactive form requires tmux 3.3 or newer and `glow` on `PATH`;
+the headless form requires neither presentation tool.
+
 ## Installing agent SDKs
 
 Each adapter is backed by a vendor runtime that installing
@@ -56,9 +59,11 @@ following it cannot install a version the gate refuses again
 ## Interactive
 
 ```sh
-playbook            # launch the configured playbooks in tmux-play
-playbook --list     # ids, slash commands, and intents; no launch
-playbook --help     # config path, auth pointers, agent-swap recipe
+playbook                         # fresh durable session in this directory
+playbook --cwd /path/to/repo     # fresh session in an explicit directory
+playbook --session <id>          # reopen either front end's settled session
+playbook --list                  # ids, slash commands, and intents; no launch
+playbook --help                  # config path, auth pointers, binding recipe
 ```
 
 Without a global install, `npx` runs the same bin — but name each
@@ -78,10 +83,21 @@ already present, since each distinct package set is a distinct tree —
 and replaying your original arguments, so the printed command works in
 one hop.
 
-The command resolves its config (seeding it on first run), composes a
-`tmux-play` config, checks adapter readiness, and launches. It exits
-with tmux-play's status, re-raises a terminating signal on itself, and
-exits `127` when it cannot launch at all
+For a managed launch, the outer command resolves current config (seeding it on
+first use), prepares the complete stored catalog and presenter, waits for the
+pane child to acquire the session lease and publish its settled turn-zero
+record, prints the verified session ID, and then attaches. A normal outer
+detach exits `0`; the pane child keeps owning the durable session and accepting
+turns until it shuts down. Preparation, attachment, or required cleanup
+failure prints its diagnostics and exits nonzero.
+
+Before native-client hand-off, SIGHUP, SIGINT, or SIGTERM aborts activation,
+joins the child, retires the lease, and only then re-raises the signal. At the
+synchronous native-client hand-off, ownership transfers before tmux starts, so
+later signals use native client detach or termination semantics and do not
+retire the pane child's session. Only `--config` and composed
+`--theme-diagnostics` use the stock subprocess boundary: those forms mirror
+its exit status or signal and exit `127` when it cannot be spawned
 ([[playbook-cli-1](../specs/packages/playbook-cli.md#playbook-cli-1)],
 [[playbook-cli-2](../specs/packages/playbook-cli.md#playbook-cli-2)]).
 
@@ -106,10 +122,12 @@ untouched
 [[playbook-captain-2](../specs/packages/playbook-captain.md#playbook-captain-2)]).
 
 The current CODE, REVIEW, and DECIDE workflows take their deterministic
-initial event from the selecting Boss turn. CODE and DECIDE then call
-REVIEW as a nested playbook: an exact same-name child role continues the
-ancestor's player pane and backend conversation, while any additional
-role uses REVIEW's configured fallback. When a player surfaces a
+initial event from the selecting Boss turn. CODE and DECIDE then call REVIEW
+as a nested playbook. Local role names do not imply continuity: each frame
+uses the exact stable player IDs configured under its `roles` map. Equal IDs
+share one pane and provider conversation across nested and later root
+engagements; distinct IDs remain isolated even when their agent settings are
+identical. When a player surfaces a
 clarifying question the FSM parks, the pane shows the question, and a
 judge classifies your next turn as its reply or a fresh directive that
 abandons it
@@ -147,7 +165,7 @@ stderr, and `--verbose` adds only telemetry topic names to stderr.
 
 | Flag | Meaning |
 | --- | --- |
-| `--with <path>` | overlay the shared config for a new session; repeatable |
+| `--with <path>` | overlay current config for a fresh session or compatible ordinary reopen; repeatable |
 | `--no-provision` | do not create missing engine links for configured filesystem registries |
 | `--json` | print exactly one `sessionId` / `reply` object |
 | `--verbose` | add Captain telemetry topic names to stderr |
@@ -168,9 +186,14 @@ uncertain boundary, withhold stdout, and are re-raised after lease retirement
 
 The former positional `<from>`, `resume`, `--player`, `--captain`,
 `--option`, `--cwd`, `--last`, run-only `--config`, and top-level `run:`
-config are removed. Enable a registry under `playbooks`, tune its inline
-agents and options there or in a fresh `--with` overlay, invoke its effective
-`/command`, and run from the working directory you want agents to use.
+config are removed from `playbook run`. Enable a registry under `playbooks`,
+declare provider agents once under top-level `players`, bind every local role
+under `playbooks.<id>.roles`, tune compatible model and effort in a `--with`
+overlay, invoke the effective `/command`, and run from the working directory
+you want agents to use. Legacy `playbooks.<id>.players` blocks are rejected and
+are not auto-migrated because choosing equal or distinct new player IDs chooses
+conversation sharing or isolation; see [Migrating per-playbook
+players](configuration.md#migrating-per-playbook-players).
 
 ### Piping a Spex update prompt
 
@@ -208,23 +231,38 @@ module's directory is a git repository, add `node_modules/` to its
 
 ### Continuing a Captain session
 
-Every successfully presented headless turn is stored under
-`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/` before stdout.
-Continue the newest logical session, or select the id returned by `--json`:
+Interactive and headless commands write the same logical-session records under
+`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/`. A fresh interactive
+child persists turn zero before printing `playbook: session <id>` and opening
+Boss input; a fresh headless turn returns the same kind of ID in `--json`.
+After the current writer exits or explicitly hands off, either presentation
+can reopen either origin:
 
 ```sh
+# Reopen the latest settled session headlessly:
 playbook run --continue "keep the scope small; skip the docs"
+
+# Reopen one exact session in either presentation:
+playbook --session 4f2c0000-0000-4000-8000-000000009ab1
 playbook run --session 4f2c0000-0000-4000-8000-000000009ab1
 ```
 
-A missing reply is read verbatim from stdin. Continuation restores the exact
+A missing headless reply is read verbatim from stdin. Reopening restores the
 compiled Captain conversation, engagement stack, nested child boundary,
-mapped-player conversations, normalized execution config, and absolute
-working directory. It does not reread current config, does not repeat a
-settled or pending child start, and rejects `--with` because an existing
-session's lineup is frozen
+stable-player ledger, and absolute working directory without replaying a
+settled or pending child start. One exclusive writer owns the session, so a
+detached interactive pane child remains the owner until it shuts down; a
+competing front end fails closed instead of forking the history.
+
+An ordinary reopen reads current config and any opening `--with` fragments,
+projects them to the stored catalog and player roster, and requires the stored
+role bindings plus every structural setting to remain exact. Compatible
+current `model` and `effort` selections apply to the next call, including an
+explicit boolean `false` provider-default reset. The retained provider token
+is never silently replaced by a fresh conversation if that selection is not
+supported
 ([[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
-[DR-031](../specs/decisions/031-shared-captain-session-front-ends.md)).
+[DR-032](../specs/decisions/032-explicit-roles-session-players.md)).
 
 ### Recovering an uncertain turn
 
@@ -238,8 +276,15 @@ playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 --retry-uncertain
 playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 --discard-uncertain
 ```
 
-Retry reads no input and reuses the byte-exact recorded turn; it may duplicate
-external effects. Discard reads no input and runs no model: it restores the
-exact prior settled boundary, or deletes a never-settled fresh session, while
-abandoning the attempted work. Session files written by the removed direct
-v6 runner are not shared-Captain sessions and cannot be continued.
+Retry reads no input and reuses the byte-exact recorded turn and its exact
+attempted Captain, player, and per-role model/effort selections; current config
+cannot retune that attempt, and retry may duplicate external effects. Discard
+reads no input and runs no model: it restores the exact prior settled boundary,
+or deletes a never-settled fresh session, while abandoning the attempted work.
+An interrupted interactive turn uses the same uncertain record and is
+recovered with these headless commands. Session files written by the removed
+direct v6 runner and legacy record schemas are not shared schema-3 Captain
+sessions and cannot be continued. Explicit selection rejects them. Implicit
+`--continue` reports and skips released schema-2 Captain records, naming each
+session and path; move them outside the sessions directory or remove them to
+silence the warning. Malformed records and unknown schemas still fail closed.

package/docs/configuration.md

@@ -3,7 +3,7 @@
 
 # Configuring agents
 
-`playbook` and every fresh `playbook run` read one config at
+Fresh launches and ordinary reopens read one config at
 `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`. The
 first launch seeds it from the bundled starter and prints the path;
 later launches reuse it untouched.
@@ -14,28 +14,35 @@ $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
 
 ## Anatomy
 
-The config is top-level (no `config:` wrapper): a `captain` agent (it
-runs the session Captain's hidden control calls, the hidden judge calls,
-and the replies you see in the Captain pane or on headless stdout), optional
-`layout` / `notifications` / `theme`, and a `playbooks` map of enabled
-playbooks. Those three presentation fields apply only to interactive tmux;
-headless runs ignore them.
-
-Each `captain` or `players.<role>` value is either an adapter shorthand
-(`claude`, `codex`) or a block carrying that agent's own `adapter`,
-`model`, `effort`, and `permissions`. Settings are inline per agent, so
-tuning one player never changes another
-([DR-021](../specs/decisions/021-inline-agent-settings.md)). Other
-adapter ids pass through to `tmux-play` with a warning, because
-`playbook` cannot preflight their auth.
-
-Within a `playbooks.<id>` block, `from` (the registry module), `command`
-(an optional slash-command override), and `players` are launcher-owned;
-every other key is that playbook's option slice. The launcher injects
-the rest — you do not write host wiring by hand.
-
-The seeded config runs each Coder on Claude Opus 4.8 1m and each
-Reviewer on GPT-5.5:
+The config is top-level (no `config:` wrapper): a `captain` agent, one flat
+`players` map of stable Captain-session agents, a `playbooks` map of enabled
+workflows and their explicit role bindings, and optional `layout` /
+`notifications` / `theme`. The Captain runs hidden control and judge calls and
+writes the replies you see in the Captain pane or on headless stdout. The three
+presentation fields apply only to interactive tmux; headless runs ignore them.
+
+A **role** is local to a playbook artifact: CODE's `coder` and REVIEW's `coder`
+have the same semantic name but remain separate declarations. A **player** is
+a stable session-wide provider conversation with an exact ID such as
+`dev.coder`. A role uses only the player named by its binding; matching role
+names, nesting, and ancestry never infer a binding.
+
+Each `captain` or `players.<player-id>` value is either an adapter shorthand
+(`claude`, `codex`) or a block carrying that agent's own `adapter`, `model`,
+`effort`, `instruction`, and `permissions`. Settings are inline per stable
+agent ([DR-021](../specs/decisions/021-inline-agent-settings.md)). Dots in a
+player ID are literal characters, not YAML hierarchy. Other adapter IDs pass
+through to `tmux-play` with a warning because `playbook` cannot preflight their
+auth.
+
+Within a `playbooks.<id>` block, `from` (the registry module), `command` (an
+optional slash-command override), and `roles` are launcher-owned; every other
+key is that playbook's option slice. Every manifest role must be present
+exactly once. The launcher injects the rest — you do not write host wiring by
+hand.
+
+The seeded config runs the stable Coder player on Claude Opus 4.8 1m and the
+stable Reviewer player on GPT-5.5:
 
 ```yaml
 captain:
@@ -45,86 +52,116 @@ captain:
   permissions:
     mode: auto # protected auto mode for the Claude Captain
 
+players:
+  dev.coder:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    effort: xhigh
+    permissions:
+      mode: auto # protected auto mode for the Claude Coder
+
+  dev.reviewer:
+    adapter: codex
+    model: gpt-5.5
+    effort: xhigh
+    permissions:
+      mode: auto
+      writablePaths:
+        - .git # allow git metadata writes under Codex auto mode
+
 playbooks:
   code:
     from: '@sublang/playbook/code/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto # protected auto mode for the Claude Coder
+    roles:
+      coder: dev.coder
 
   review:
     from: '@sublang/playbook/review/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
-      reviewer:
-        adapter: codex
-        model: gpt-5.5
-        effort: xhigh
-        permissions:
-          mode: auto
-          writablePaths:
-            - .git # allow git metadata writes under Codex auto mode
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
 
   decide:
     from: '@sublang/playbook/decide/registry'
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
-      reviewer:
-        adapter: codex
-        model: gpt-5.5
-        effort: xhigh
-        permissions:
-          mode: auto
-          writablePaths:
-            - .git
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
 ```
 
 The current bundled workflows accept no workflow-specific options.
-Each role's per-run prompt names its pinned `model`, else its `adapter`
+Each role's per-call prompt names its current `model`, else its player's
+`adapter`
 ([[playbook-runtime-4](../specs/packages/playbook-runtime.md#playbook-runtime-4)]),
 so commit trailers credit the concrete model rather than the adapter
 family.
 
-## Nested roles and sessions
+## Role binding forms
+
+The shortest binding is a scalar stable player ID:
+
+```yaml
+roles:
+  coder: dev.coder
+```
+
+Use a block to override only that role invocation's model or effort:
+
+```yaml
+roles:
+  coder:
+    player: dev.coder
+    model: claude-opus-4-8[1m]
+    effort: false # explicitly reset to this provider's default
+```
+
+Omitting `model` or `effort` inherits that player's top-level default. The
+boolean `false` is different: it selects the provider default explicitly, so a
+resumed conversation cannot accidentally retain an earlier selection. A role
+binding cannot override adapter, instruction, permissions, workspace, or tool
+posture; those define the stable player envelope.
+
+## Sharing, isolation, and concurrency
 
-The launcher creates a namespaced fallback player for every configured
-playbook role, but a nested call maps an exact same-name role to the
-nearest ancestor's effective player and backend conversation. CODE's
-nested REVIEW therefore continues CODE's `coder` and uses REVIEW's
-configured `reviewer`; DECIDE's nested REVIEW continues both of
-DECIDE's roles. A standalone REVIEW starts with REVIEW's own configured
-players, and every new root engagement starts fresh
-([DR-030](../specs/decisions/030-shared-mapped-player-continuity.md)).
+Two bindings that name the same player ID deliberately share one sequential
+provider conversation throughout the logical Captain session — across nested
+calls, returns, and later root engagements. CODE's and REVIEW's `coder` roles
+therefore share `dev.coder` in the starter, and DECIDE and its nested REVIEW
+share both starter players. Disposal of one playbook frame does not clear that
+session ledger.
 
-The separate fallback entries are still required because tmux creates
-its roster at launch time. The host changes which existing panes are
-visible as the active nested leaf changes; it does not create a new
-host player or backend agent session for a mapped role.
+Two distinct player IDs stay isolated even when their agent blocks are
+byte-for-byte equal. To give standalone REVIEW an independent Coder, define a
+second top-level player and change only its binding:
+
+```yaml
+players:
+  review.coder:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    effort: xhigh
+
+playbooks:
+  review:
+    from: '@sublang/playbook/review/registry'
+    roles:
+      coder: review.coder
+      reviewer: dev.reviewer
+```
+
+Roles a manifest may run concurrently must bind to distinct IDs. DECIDE's
+`coder` and `reviewer` are concurrent, so aliasing both to one player rejects
+before registry import, host creation, or agent work.
 
 ## Choosing the Captain agent
 
 Every session-Captain call and adjudication call is hidden and runs
 tool-free, which is what keeps the Captain deciding and reporting
-instead of doing the work itself. Claude enforces
-that at the provider level. The Codex adapter cannot — it rejects any
-tool list — so a `captain:` on `codex` falls back to a prompt-level
-restriction
+instead of doing the work itself. Claude and Gemini enforce that at the
+provider level. The Codex, Kimi, and OpenCode adapters cannot — they
+reject any tool list — so a `captain:` using one of them falls back to a
+prompt-level restriction
 ([DR-013](../specs/decisions/013-routing-only-captain-control.md) A1).
-Codex remains a good choice for *players*, where full tools are wanted.
+Those adapters remain good choices for *players*, where full tools are wanted.
 
 Adapter readiness is intentionally light: `claude` is ready with local
 Claude Code auth or `ANTHROPIC_API_KEY`; `codex` with local Codex CLI
@@ -143,40 +180,52 @@ playbook run --with fast-lineup.yaml "/code implement the approved change"
 ```
 
 ```yaml
-# fast-lineup.yaml — swap the Coder for one run; nothing is written back.
+# fast-lineup.yaml — retune the shared Coder; nothing is written back.
+players:
+  dev.coder:
+    model: claude-opus-4-8
+    effort: medium
+```
+
+Fragments merge into the agent block rather than replacing it, so
+settings the base defines and the fragment omits — here the adapter,
+instruction, and permissions — survive. Retuning a top-level player affects
+every bound role that does not override that field. To retune only one role,
+overlay its binding instead:
+
+```yaml
 playbooks:
   code:
-    players:
+    roles:
       coder:
-        adapter: codex
-        model: gpt-5.5
-        effort: medium
-        permissions:
-          mode: auto
-          # CODE's Coder commits, so Codex needs the `.git` grant to write
-          # repository metadata.
-          writablePaths:
-            - .git
+        player: dev.coder
+        effort: low
 ```
 
-Fragments merge into the agent block rather than replacing it, so
-settings the base defines and the fragment omits — here `mode: auto` —
-survive. Anything the adapter itself requires must still be stated: a
-role switched to `codex` needs its own `writablePaths` grant, because
-the base Claude block had no reason to carry one.
-
 The global file is never modified, and `--with` is not forwarded to
 `tmux-play` ([[playbook-cli-25](../specs/packages/playbook-cli.md#playbook-cli-25)]).
-Overlays apply only when creating a fresh session. A continued headless
-session restores its frozen config and working directory and rejects `--with`.
-
-## Shared headless configuration
-
-Fresh interactive and headless sessions use the same top-level `captain`
-and `playbooks` blocks. A headless session retains the normalized lineup,
-catalog, options, and absolute working directory with every durable turn;
-continuation does not reread the current file. Presentation-only fields are
-inert headlessly.
+Overlays apply when creating a fresh session and as current-config input for a
+compatible ordinary reopen. A selected session keeps its stored catalog,
+player roster, role bindings, adapter, instruction, permissions, and working
+directory; only model and effort may change. The next call reapplies both
+complete selections. An uncertain retry accepts no tuning overlay and uses the
+exact attempted selections already stored with that turn.
+
+## Durable shared configuration
+
+Fresh interactive and headless sessions use the same top-level Captain,
+players, role bindings, and playbooks. Both persist the same logical-session
+record, shell snapshot, player ledger, normalized catalog, structural agent
+envelopes, last-applied tuning, and absolute working directory. A session
+created by either front end can reopen through either front end with the same
+public UUID. Presentation-only fields are inert headlessly.
+
+An ordinary reopen reads current config and opening overlays, but first
+projects them to the stored playbooks and referenced players. An unrelated new
+entry cannot enter or invalidate the session. Structural drift fails closed;
+compatible model or effort changes apply on the next provider call. Legacy
+record, shell, runtime-snapshot, and trace schemas are rejected rather than
+having role or player identity guessed.
 
 ## External playbooks
 
@@ -187,11 +236,14 @@ and `createRuntime`. Enable it under `playbooks`, bind every role listed in
 its `requiredRoleIds`, and invoke its effective slash command through Captain:
 
 ```yaml
+players:
+  my.worker: claude
+
 playbooks:
   my-workflow:
     from: /absolute/path/to/my-workflow.ts
-    players:
-      worker: claude
+    roles:
+      worker: my.worker
 ```
 
 ```sh
@@ -205,15 +257,60 @@ Before either front end imports a filesystem registry, the shared launcher
 checks and, unless `--no-provision` is set, provisions its runtime engine
 links as described in [Using the CLI](cli.md#external-playbooks-and-engine-provisioning).
 
+## Migrating per-playbook players
+
+The former `playbooks.<id>.players` shape made agent configuration and local
+workflow roles the same thing. It is removed. For example, this legacy config
+gave CODE and REVIEW two separately configured `coder` entries:
+
+```yaml
+playbooks:
+  code:
+    from: '@sublang/playbook/code/registry'
+    players:
+      coder: { adapter: claude, model: claude-opus-4-8[1m] }
+  review:
+    from: '@sublang/playbook/review/registry'
+    players:
+      coder: { adapter: claude, model: claude-opus-4-8[1m] }
+      reviewer: { adapter: codex, model: gpt-5.5 }
+```
+
+Move each provider agent into the flat top-level map, choose stable IDs, and
+bind the local roles explicitly:
+
+```yaml
+players:
+  dev.coder: { adapter: claude, model: claude-opus-4-8[1m] }
+  dev.reviewer: { adapter: codex, model: gpt-5.5 }
+
+playbooks:
+  code:
+    from: '@sublang/playbook/code/registry'
+    roles: { coder: dev.coder }
+  review:
+    from: '@sublang/playbook/review/registry'
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
+```
+
+The launcher intentionally does **not** perform this migration for you. It
+cannot know whether the two old `coder` blocks were meant to share one
+conversation or remain isolated. Reusing `dev.coder` above chooses sharing;
+using `code.coder` and `review.coder` would choose isolation. A surviving
+per-playbook `players` block therefore rejects before profile migration,
+registry preparation, or agent work.
+
 ## Migrating direct runs from 6.x
 
 The top-level `run:` block is deliberately rejected rather than silently
 ignored or rewritten, because doing otherwise could change the agents after
 an upgrade. Re-express `run.captain`, `run.players`, and former `--player`
-bindings as the inline agent blocks above; the old `run.player` catch-all has
-no shared equivalent, so configure every required role explicitly at
-`playbooks.<id>.players.<role>`. Use a fresh `--with` fragment for temporary
-lineup changes. Move former `--option` values into their `playbooks.<id>`
+bindings as top-level stable player blocks and explicit role bindings above;
+the old `run.player` catch-all has no shared equivalent, so configure every
+required role at `playbooks.<id>.roles.<role>`. Use a `--with` fragment for
+temporary compatible tuning changes. Move former `--option` values into their `playbooks.<id>`
 block, run from the desired directory instead of passing `--cwd`, enable a
 former positional `<from>` as a configured registry, and quote or pipe one
 `/command task` Boss message. Replace `resume` and `--last` with `--continue`