@sublang/playbook 4.0.0 → 6.0.0

package/README.md

@@ -1,143 +1,101 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 <!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
 
-# playbook
+# Playbook: Reliability Is All You Need
 
 [![npm version](https://img.shields.io/npm/v/@sublang/playbook)](https://www.npmjs.com/package/@sublang/playbook)
 [![Node.js](https://img.shields.io/node/v/@sublang/playbook)](https://nodejs.org/)
 [![CI](https://github.com/sublang-ai/playbook/actions/workflows/ci.yml/badge.svg)](https://github.com/sublang-ai/playbook/actions/workflows/ci.yml)
 
-_Skills made reliable through state machines and visualization._
+_Skills made reliable through state machines and diverse LLMs._
 
-playbook turns a natural-language procedure into a runnable,
-inspectable state-machine agent — a _playbook_ — that orchestrates other
-AI agents per a spec written in plain prose. Instead of a free-form LLM
-deciding what to do next, an explicit finite state machine drives the
-workflow, every agent-invoking state pinned 1:1 to a human-readable spec
-item and contract-tested.
+Natural-language skills are flexible and easy to use, but less predictable than scripted workflows, especially on long-horizon jobs.
+And even the best LLMs make mistakes, partly because plain-language descriptions rarely eliminate vagueness or guarantee completeness.
 
-Vocabulary: the **Boss** is you; the **Captain** is the agent pane you
-talk to; **players** are the coding agents a playbook delegates to; a
-hidden **judge** classifies your free text into state-machine events.
-Playbooks run inside a *host* built on
-[cligent](https://github.com/sublang-ai/cligent), the sibling SDK that
-drives coding-agent CLIs; its `tmux-play` terminal app is the reference
-host.
+SubLang Playbook addresses both:
+
+- The companion [SLC compiler](https://github.com/sublang-ai/slc) turns plain-language procedures, such as a `SKILL.md`, into playbooks with deterministic state-machine control flow.
+- A playbook can assign different agents or LLMs to its steps and have them review and challenge one another, helping catch mistakes before delivery.
+
+![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.
+
+Run `playbook` for an interactive tmux UI powered by [cligent](https://github.com/sublang-ai/cligent), or `playbook run` for one-shot scripts and CI.
 
 ## Quick start
 
-Requires Node.js >= 20.6.0, `tmux` and
-[`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`,
-and auth for the seeded agents — signed-in
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
-or `ANTHROPIC_API_KEY`, and signed-in
-[Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY`.
+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 interactive starter config uses Claude as both Captain and Coder, and Codex as Reviewer.
 
 ```sh
-npm install -g @sublang/playbook @anthropic-ai/claude-agent-sdk @openai/codex-sdk
+npm install -g @sublang/playbook
+npm install -g @anthropic-ai/claude-agent-sdk @openai/codex-sdk
+```
+
+Custom configurations need the SDKs required by their providers; see [Configuring agents](docs/configuration.md).
+If an SDK is missing or older than cligent supports, Playbook prints the pinned install command before launching anything; see [Installing agent SDKs](docs/cli.md#installing-agent-sdks) for upgrades, `npx`, and other adapters.
+
+Prerequisites:
+
+- Node.js >= 20.6.0
+- `tmux` and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`
+- 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`
+
+CODE works in the current directory and can edit and commit autonomously, so use a clean branch or worktree.
+
+```sh
+cd /path/to/your/project
 playbook
 ```
 
-The agent SDKs are optional, so you install only the vendors your
-config names — install one and the package stays around 14 MB rather
-than pulling every stack. Name each SDK as its own top-level install
-root, exactly as above: an SDK nested inside another package's subtree
-is not reachable from the adapter that loads it. Which versions work
-is cligent's knowledge and ships with it: if a runtime is missing — or
-installed below the version cligent supports — `playbook` says so
-before it launches anything, naming the installed and required
-versions and printing cligent's pinned install command
-([DR-026](specs/decisions/026-optional-adapter-sdks.md),
-[DR-027](specs/decisions/027-runtime-compatibility-from-cligent.md)).
-
-Upgrading from 3.1.0 or earlier? Use the same full line — npm removes
-the SDK copies those releases bundled when it upgrades the package, so
-upgrading `@sublang/playbook` alone leaves no agent SDK installed.
-Running via `npx` instead? Name each SDK as a sibling package of the
-same invocation (`npx -y -p @sublang/playbook -p <sdk> playbook`) — no
-install command reaches npx's ephemeral tree; see
-[docs/cli.md](docs/cli.md).
-
-The first launch seeds a commented config at
-`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`,
-composes a `tmux-play` config, checks the declared adapters, and opens
-the session. Then type a task, or `/code <task>` to select the CODE
-playbook directly.
-
-Every agent carries its own settings, so retuning one player never
-changes another:
-
-```yaml
-playbooks:
-  code:
-    from: '@sublang/playbook/code/registry'
-    players:
-      coder: { adapter: claude, model: 'claude-opus-4-8[1m]', effort: xhigh }
-      reviewer: { adapter: codex, model: gpt-5.5, effort: xhigh }
+Type a task, enter `/code <task>` for implementation, or enter
+`/decide <question>` for an independently proposed and reviewed decision.
+
+On first launch, Playbook writes its config to `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`.
+
+One-shot runs use separate defaults instead of the interactive lineup.
+Without configured `run` defaults, the Captain and every player use Claude; run standalone REVIEW with a Codex Reviewer using:
+
+```sh
+playbook run @sublang/playbook/review/registry "review the latest commit" --player reviewer=codex --json
 ```
 
-To run once without tmux — for scripts and CI — point `run` straight at
-a registry module:
+CODE and DECIDE require interactive `playbook` because the one-shot host does not drive nested calls.
+
+See [Using the CLI](docs/cli.md) for flags and session resume, [Configuring agents](docs/configuration.md) for lineups, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](CHANGELOG.md) for releases.
+
+## Create your own playbook
+
+The separate [SLC compiler](https://github.com/sublang-ai/slc) requires Node.js >= 23.6 and compiles a plain-language `.md` or `.txt` procedure:
 
 ```sh
-playbook run @sublang/playbook/code/registry "add a test for parseArgs" --json
+npm install -g @sublang/slc
+slc playbook my-workflow.md
+playbook run ./my-workflow.ts "<your task>"
 ```
 
-- **[docs/cli.md](docs/cli.md)** — both surfaces: Boss turns, flags,
-  exit codes, and resuming a parked `run`.
-- **[docs/configuration.md](docs/configuration.md)** — the config file,
-  per-launch `--with` overlays, and choosing the Captain agent.
-- **[docs/embedding.md](docs/embedding.md)** — the six-port runtime
-  contract for hosts other than `tmux-play`.
-
-> **Current release:** 4.0.0. The composed system — the compiled default
-> Captain, CODE and DISCUSS, nested playbook calls, script actors and the
-> GEARS optimize pass, the semver-stable six-port runtime contract, and
-> non-interactive `playbook run` with parked-session resume — landed in
-> 1.0.0. Since then, `playbook run` gained defaults in the user config,
-> 3.0.0 replaced the top-level `profiles` map with inline agent settings
-> (existing configs migrate themselves on the next launch), 3.1.0
-> added the linked-artifact/engine compatibility check, and 4.0.0 made
-> the agent SDKs optional — an install carries only the vendors you name
-> — with which versions work now owned and published by cligent. See the
-> [CHANGELOG](CHANGELOG.md).
+SLC writes `my-workflow.ts` beside the source, and the inspectable intermediates and tests under `my-workflow.playbook/`; see the [SLC documentation](https://github.com/sublang-ai/slc#quick-start) for setup and phase commands.
 
 ## How it compiles
 
-Three phases take prose to runtime, plus an optional optimizer:
-
-1. **text → GEARS** ([slc/text2gears.md](slc/text2gears.md)) — normative
-   spec items, one per state behavior, partitioned by trigger and prompt
-   content.
-2. **GEARS → FSM** ([slc/gears2fsm.md](slc/gears2fsm.md)) — an XState v5
-   machine; each gear maps to one direct-Captain, delegated-player, or
-   nested-playbook state with a typed actor contract. The compiled FSM
-   can be visualized and simulated with the bundled
-   [XState sketch visualizer](views/sketch).
-3. **FSM → runtime** ([slc/link.md](slc/link.md)) — a host-agnostic
-   module that drives Boss turns through ports the host wires up.
-
-Between the first two, [slc/optimize.md](slc/optimize.md) may rewrite a
-deterministic mechanical gear — canonically git repository setup — into a
-*script item* the runtime executes directly, with no agent call.
-Unoptimized compiles are byte-identical, so the pass is opt-in.
-
-The repository carries end-to-end worked examples: the generic default
-Captain from [`reference/sdlc/captain.md`](reference/sdlc/captain.md),
-CODE — a coder / reviewer / committer loop — from
-[`reference/sdlc/code.md`](reference/sdlc/code.md), and DISCUSS — two
-agents converging on spec items — from
-[`reference/sdlc/discuss.md`](reference/sdlc/discuss.md). Together they
-show direct Captain work, sequential nested playbook calls, and parallel
-players. Compiled artifacts live beside each source in
-`<basename>.playbook/`, the [slc](https://github.com/sublang-ai/slc)
-pipeline's output directory.
+SLC's `playbook` pipeline has three phases:
+
+1. **text → GEARS** ([slc/text2gears.md](slc/text2gears.md)) — makes each behavior explicit with its trigger, actor, prompt, and outcomes.
+2. **GEARS → FSM** ([slc/gears2fsm.md](slc/gears2fsm.md)) — maps each item to an XState state that invokes the Captain, a player, another playbook, or a local script.
+3. **FSM → runtime** ([slc/link.md](slc/link.md)) — links the machine to a host-independent interface for user input, agent calls, status, and telemetry.
+
+The default [optimization pass](slc/optimize.md) replaces eligible mechanical steps with local shell scripts; `--no-optimize` skips it.
+Inspect the complete [Captain](reference/sdlc/captain.md), [CODE](reference/sdlc/code.md), [REVIEW](reference/sdlc/review.md), and [DECIDE](reference/sdlc/decide.md) examples.
 
 ## Contributing
 
 We welcome contributions of all kinds.
 
-- 🌟 Star our repo if you find playbook useful.
+- 🌟 Star our repo if you find Playbook useful.
 - [Open an issue](https://github.com/sublang-ai/playbook/issues) for bugs or feature requests.
 - [Open a PR](https://github.com/sublang-ai/playbook/pulls) for fixes or improvements.
 - Discuss on [Discord](https://discord.gg/XxTPjNqy9g) for support or new ideas.
@@ -153,20 +111,9 @@ pnpm test
 pnpm playbook   # drive a Boss turn against the source tree
 ```
 
-To co-develop against an unreleased cligent checkout, clone it beside
-this repository, build it, and copy `pnpm-workspace.yaml.example` to the
-gitignored `pnpm-workspace.yaml`. Do not commit the lockfile rewrite it
-produces ([RELEASE-11](specs/dev/release.md#release-11)).
-
-playbook is itself spec-driven: the compiler phases are specs in
-[`slc/`](slc), and the reference playbooks are regenerated from their
-prose sources. Edit a source, recompile gears then FSM and runtime into
-its artifact directory, sync tests and downstream specs until
-`pnpm test` is green, and commit with co-author trailers per
-[`specs/dev/git.md`](specs/dev/git.md). The gears↔FSM contract
-([the PLAYBOOK dev items](specs/dev/playbook.md)) and the runtime
-contract ([the PBRT dev items](specs/dev/playbook-runtime.md)) are
-pinned in [`specs/dev/`](specs/dev) and verified by the test suite.
+Playbook is itself spec-driven: the compiler phases are specs in [`slc/`](slc), and the reference playbooks are regenerated from their prose sources.
+Edit a source, regenerate its GEARS, FSM, and runtime artifacts, sync the tests and downstream specs until `pnpm test` passes, and commit with co-author trailers per [`specs/packages/git.md`](specs/packages/git.md).
+The gears↔FSM contract ([the playbook package](specs/packages/playbook.md)) and runtime contract ([the playbook-runtime package](specs/packages/playbook-runtime.md)) are pinned in [`specs/packages/`](specs/packages) and verified by the test suite.
 
 ## License
 

package/docs/assets/playbook-venn.svg

@@ -0,0 +1,13 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 415 124" width="415" height="124" role="img" aria-labelledby="venn-title" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif">
+  <title id="venn-title">Skills are flexible, workflows are deterministic; Playbook sits in the intersection and is both.</title>
+  <ellipse cx="136" cy="62" rx="126" ry="56" fill="#e5484d" fill-opacity="0.06" stroke="#e5484d" stroke-width="2.2"/>
+  <ellipse cx="279" cy="62" rx="126" ry="56" fill="#4285d6" fill-opacity="0.06" stroke="#4285d6" stroke-width="2.2"/>
+  <path d="M 207.5 15.9 A 126 56 0 0 1 207.5 108.1 A 126 56 0 0 1 207.5 15.9 Z" fill="#b06bff" fill-opacity="0.08"/>
+  <text x="91" y="42.7" text-anchor="middle" font-size="12" font-weight="600" letter-spacing="1" fill="#e5484d">FLEXIBLE</text>
+  <text x="91" y="71.7" text-anchor="middle" font-size="16" font-weight="600" fill="#e5484d">Skill</text>
+  <text x="324" y="42.7" text-anchor="middle" font-size="12" font-weight="600" letter-spacing="1" fill="#4285d6">DETERMINISTIC</text>
+  <text x="324" y="71.7" text-anchor="middle" font-size="16" font-weight="600" fill="#4285d6">Workflow</text>
+  <text x="207.5" y="71.7" text-anchor="middle" font-size="16" font-weight="700" fill="#b06bff">Playbook</text>
+</svg>

package/docs/cli.md

@@ -50,7 +50,7 @@ runtime is reported as not installed; a stale one with its installed
 and required versions, never as absent. Either way the remedy printed
 is cligent's pinned install, `npm install -g <package>@<version>`, so
 following it cannot install a version the gate refuses again
-([PBCLI-40](../specs/user/playbook-cli.md#pbcli-40)).
+([[playbook-cli-40](../specs/packages/playbook-cli.md#playbook-cli-40)]).
 
 ## Interactive
 
@@ -81,39 +81,56 @@ 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
-([PBCLI-1](../specs/user/playbook-cli.md#pbcli-1),
-[PBCLI-2](../specs/user/playbook-cli.md#pbcli-2)).
+([[playbook-cli-1](../specs/packages/playbook-cli.md#playbook-cli-1)],
+[[playbook-cli-2](../specs/packages/playbook-cli.md#playbook-cli-2)]).
 
 ### Running a Boss turn
 
-The Boss pane starts at the Playbook Captain shell. Use `/code <task>`
-to select the CODE playbook explicitly, or type ordinary text and let
-the compiled default Captain ask a material routing question or plan one
-or more enabled playbook calls. It cannot answer the initial intent
-directly; calls run sequentially so Captain can reassess after every
-child result and then return a concrete result or actionable conclusion.
-
-Once a turn reaches CODE, the CODE judge classifies it into an FSM event
-— start a coding turn, continue or summarize an iteration, interrupt to
-a named state, or nothing
-([PBRT-1](../specs/user/playbook-runtime.md#pbrt-1)). When a player
-surfaces a clarifying question the FSM parks, the pane shows the
-question, and your next turn is normally classified as the reply — a
-fresh directive abandons it
-([PBRT-2](../specs/user/playbook-runtime.md#pbrt-2)).
+The Boss pane starts at the Playbook Captain shell, where the session
+Captain runs for the whole session and sees every turn. Use `/code`,
+`/review`, or `/decide` followed by a task to select one of the bundled
+playbooks explicitly. A registered command resolves deterministically,
+with no model call parsing it: at idle it starts that playbook, at its
+own leaf it delivers the rest of the line, an enabled command absent
+from the active path switches to it, and a bare command answers with
+status or a clarification instead of restarting anything. Type ordinary
+text and the session Captain decides the turn instead: it chats back,
+starts or switches a playbook, hands the text to the working playbook,
+dismisses it, or applies one recovery action the running playbook
+currently offers. It never does the specialized work itself, and a
+conversational turn — including a progress or status question — leaves
+the engagement, its parked state, and any pending player question
+untouched
+([[playbook-captain-1](../specs/packages/playbook-captain.md#playbook-captain-1)],
+[[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
+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
+([[playbook-runtime-2](../specs/packages/playbook-runtime.md#playbook-runtime-2)]).
 
 The Captain pane shows start/stop/finished status with `◇` lines and
 streams progress with captain-speech classification and questions
-([PBRT-3](../specs/user/playbook-runtime.md#pbrt-3)), while player
-prompts ride their own panes.
+([[playbook-runtime-3](../specs/packages/playbook-runtime.md#playbook-runtime-3)]), while player
+prompts ride their own panes. A turn that actually did something ends
+with one Captain reply summarizing what changed, composed only from that
+turn's reported outcome; a turn that changed nothing ends with an
+ordinary reply and no saved-counts line
+([[playbook-captain-19](../specs/packages/playbook-captain.md#playbook-captain-19)]).
 
 ## Non-interactive
 
 `playbook run <from> [task]` runs one playbook once, without tmux-play
-and without a config entry — point it straight at a registry module:
+and without an interactive config entry. For example, run REVIEW
+directly against the latest commit:
 
 ```sh
-playbook run @sublang/playbook/code/registry "add a test for parseArgs" \
+playbook run @sublang/playbook/review/registry "review the latest commit" \
   --player coder=claude --player reviewer=codex --cwd ./my-repo
 ```
 
@@ -124,7 +141,7 @@ intents the same way you would to `claude -p` or `codex exec`.
 | --- | --- |
 | `--player <role>=<agent>` | bind a required role |
 | `--captain <agent>` | set the captain/judge agent |
-| `--option <key>=<value>` | a playbook option (CODE's `committer`) |
+| `--option <key>=<value>` | a registry-defined playbook option (none in the current bundled workflows) |
 | `--cwd <dir>` | the agents' working directory |
 | `--json` | one envelope: `outcome`, `sessionId`, output or questions |
 | `--no-provision` | never create engine links beside a filesystem `<from>` |
@@ -138,7 +155,7 @@ config supplies [run defaults](configuration.md#defaults-for-playbook-run).
 
 Exit codes: `0` terminal, `1` bad argument or module, `2` failure, `3`
 the playbook needs a Boss reply
-([PBCLI-18](../specs/user/playbook-cli.md#pbcli-18)).
+([[playbook-cli-18](../specs/packages/playbook-cli.md#playbook-cli-18)]).
 
 ### Engine provisioning
 
@@ -150,7 +167,7 @@ install with no project-local packages —
 `node_modules/xstate` and `node_modules/@sublang/playbook` beside the
 module as symlinks to the running host's own packages and prints one
 line naming what it linked
-([PBCLI-36](../specs/user/playbook-cli.md#pbcli-36),
+([[playbook-cli-36](../specs/packages/playbook-cli.md#playbook-cli-36)],
 [DR-024](../specs/decisions/024-runtime-engine-provisioning.md)).
 A directory where the imports already resolve is never touched — a
 project-local install always wins — and `--no-provision` disables the
@@ -179,5 +196,5 @@ lineup, options, and working directory are stored with the session, so
 `resume` takes no binding flags. In scripts, capture the session id from
 the `--json` envelope, like Claude Code's `session_id` or
 `codex exec resume`
-([PBCLI-22](../specs/user/playbook-cli.md#pbcli-22),
+([[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
 [DR-014](../specs/decisions/014-durable-one-shot-run-sessions.md)).

package/docs/configuration.md

@@ -15,7 +15,8 @@ $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
 ## Anatomy
 
 The config is top-level (no `config:` wrapper): a `captain` agent (it
-runs both visible Captain work and hidden judge calls), optional
+runs the session Captain's hidden control calls, the hidden judge calls,
+and the replies you see in the Captain pane), optional
 `layout` / `notifications` / `theme`, and a `playbooks` map of enabled
 playbooks.
 
@@ -32,8 +33,8 @@ Within a `playbooks.<id>` block, `from` (the registry module), `command`
 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 the Coder on Claude Opus 4.8 1m and the Reviewer
-on GPT-5.5:
+The seeded config runs each Coder on Claude Opus 4.8 1m and each
+Reviewer on GPT-5.5:
 
 ```yaml
 captain:
@@ -53,6 +54,16 @@ playbooks:
         effort: xhigh
         permissions:
           mode: auto # protected auto mode for the Claude 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
@@ -61,24 +72,57 @@ playbooks:
           mode: auto
           writablePaths:
             - .git # allow git metadata writes under Codex auto mode
-    committer: coder # which role commits — `coder` or `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
 ```
 
-`committer` is CODE's one option: an alias naming which role runs the
-commit turn (fallback semantics:
-[PBRT-8](../specs/dev/playbook-runtime.md#pbrt-8)). Each role's per-run
-prompt names its pinned `model`, else its `adapter`
-([PBRT-4](../specs/user/playbook-runtime.md#pbrt-4)), so commit trailers
-credit the concrete model rather than the adapter family.
+The current bundled workflows accept no workflow-specific options.
+Each role's per-run prompt names its pinned `model`, else its `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
+
+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)).
+
+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.
 
 ## Choosing the Captain agent
 
-Hidden routing and adjudication calls run tool-free, which is what keeps
-the Captain routing instead of doing the work itself. Claude enforces
+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
-([DR-013 A1](../specs/decisions/013-routing-only-captain-control.md#addendum-a1-prompt-level-isolation-for-adapters-without-tool-enforcement)).
+([DR-013](../specs/decisions/013-routing-only-captain-control.md) A1).
 Codex remains a good choice for *players*, where full tools are wanted.
 
 Adapter readiness is intentionally light: `claude` is ready with local
@@ -107,8 +151,8 @@ playbooks:
         effort: medium
         permissions:
           mode: auto
-          # The seeded `committer` is `coder`, so this role runs the commit
-          # turn; a Codex agent needs the `.git` grant to write git metadata.
+          # CODE's Coder commits, so Codex needs the `.git` grant to write
+          # repository metadata.
           writablePaths:
             - .git
 ```
@@ -120,7 +164,7 @@ 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` ([PBCLI-25](../specs/user/playbook-cli.md#pbcli-25)).
+`tmux-play` ([[playbook-cli-25](../specs/packages/playbook-cli.md#playbook-cli-25)]).
 
 ## Defaults for `playbook run`
 
@@ -129,7 +173,7 @@ lineup so you stop retyping flags — `run.captain`, `run.players.<role>`,
 and a `run.player` catch-all for any other required role, each an
 `<adapter>[:<model>][@<effort>]` string. Flags win per role, and
 `resume` always keeps the lineup stored with the parked session
-([PBCLI-28](../specs/user/playbook-cli.md#pbcli-28),
+([[playbook-cli-28](../specs/packages/playbook-cli.md#playbook-cli-28)],
 [DR-017](../specs/decisions/017-run-defaults-config.md)).
 
 ```yaml
@@ -137,6 +181,7 @@ run:
   captain: claude:claude-opus-4-8@high
   players:
     coder: claude:claude-opus-4-8[1m]@xhigh
+    reviewer: codex:gpt-5.5@xhigh
 ```
 
 ## Migrating from `profiles`
@@ -151,7 +196,7 @@ do by hand.
 
 For a one-off, pass a raw `tmux-play` config explicitly. This bypasses
 the seed, composition, and readiness gate, forwarding arguments to
-`tmux-play` verbatim ([PBCLI-1](../specs/user/playbook-cli.md#pbcli-1)):
+`tmux-play` verbatim ([[playbook-cli-1](../specs/packages/playbook-cli.md#playbook-cli-1)]):
 
 ```sh
 playbook --config ./tmux-play.config.yaml

package/docs/embedding.md

@@ -8,7 +8,7 @@ one host, and [spex](https://github.com/sublang-ai/spex) (the desktop
 app) is another. This guide shows how to wire a playbook runtime into
 your own host.
 
-> **Release note:** this guide targets the semver-stable 1.0 six-port
+> **Release note:** this guide targets the current semver-stable six-port
 > contract; see the [CHANGELOG](../CHANGELOG.md) for migration details.
 
 ## The runtime contract
@@ -17,11 +17,11 @@ The port and runtime contracts live in the type-only module
 [`@sublang/playbook/runtime`](../src/runtime.ts) — a public,
 semver-stable surface (`PlayerResult`, `PlaybookPorts`,
 `PlaybookRuntime`, `PlaybookSession`, `PlayerCallOptions`,
-`CaptainCallOptions`, `CaptainResult`, `PlaybookTraceEvent`, and
-`PlaybookRuntimeFactory`) that imports no CODE or FSM types, so a host
-satisfies it once and inherits every playbook. The CODE runtime
-re-exports `PlayerResult`, `PlaybookPorts`, `PlaybookSession`, and
-`PlaybookRuntime` from `@sublang/playbook/code/playbook`;
+`PlayerSessionStore`, `CaptainCallOptions`, `CaptainResult`,
+`PlaybookTraceEvent`, and `PlaybookRuntimeFactory`) that imports no CODE
+or FSM types, so a host satisfies it once and inherits every playbook.
+The generated CODE, REVIEW, and DECIDE modules re-export their shared
+runtime contract types from their public `playbook` subpaths;
 `PlaybookRuntimeFactory` is available from `@sublang/playbook/runtime`.
 
 Generated linked runtimes reuse the XState integration engine exposed
@@ -32,7 +32,7 @@ nested-playbook bridge.
 ## Constructing a runtime against your own ports
 
 ```ts
-import createPlaybookRuntime from '@sublang/playbook/code/playbook';
+import createPlaybookRuntime from '@sublang/playbook/review/playbook';
 import type {
   CaptainCallOptions,
   CaptainResult,
@@ -104,20 +104,20 @@ const ports: PlaybookPorts = {
 };
 
 const runtime = createPlaybookRuntime({
-  coderPlayer: 'claude',
-  reviewerPlayer: 'codex',
+  coderLlm: 'claude-opus-4-8[1m]',
+  reviewerLlm: 'gpt-5.5',
 });
 
 const playbookSessionId = randomUUID();
 await runtime.init({
   sessionId: playbookSessionId,
-  playbookId: 'code',
+  playbookId: 'review',
   rootSessionId: playbookSessionId,
   depth: 0,
   ports,
 });
 await runtime.handleBossInput({
-  text: 'Start fixing the bug',
+  text: 'Review the latest commit against the requested intent',
   signal: new AbortController().signal,
 });
 await runtime.dispose();
@@ -129,11 +129,19 @@ Every init-to-dispose lifecycle is one playbook session. Its
 `playbook.trace` telemetry carries that immutable ID plus a contiguous
 sequence across exact Boss input, judge/player calls, FSM transitions,
 visible Captain work, nested playbook calls, status, settlement, and
-disposal. Each resolved player starts fresh in a new playbook session
-and then resumes only from the latest opaque `resumeToken` its adapter
-returned; trace data and tokens never enter Boss-visible status text.
-Because trace observers do receive opaque resume tokens, persisted
-traces should be protected as sensitive data.
+disposal. Without `PlaybookSession.playerSessions`, a standalone runtime
+starts each player fresh and privately retains the latest opaque
+`resumeToken` its adapter returned.
+
+A composing host can instead supply a frame-local `PlayerSessionStore`
+view over one root-owned continuation map. The host maps each local role
+to its effective binding, so a nested exact same-name role selects and
+updates the ancestor conversation while an unmatched child role gets
+its own binding. Child return or disposal does not clear the root's
+token, and a new root engagement starts fresh. Trace data and tokens
+never enter Boss-visible status text. Because trace observers do receive
+opaque resume tokens, persisted traces should be protected as sensitive
+data.
 
 See
 [`code.playbook.test.ts`](../reference/sdlc/code.playbook/code.playbook.test.ts)