@sublang/playbook 5.0.0 → 7.0.0

package/README.md

@@ -21,13 +21,14 @@ SubLang Playbook addresses both:
 
 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.
+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.
 
 ## Quick start
 
-Out of the box, Playbook includes **CODE**, a coding-and-review loop, and **DISCUSS**, in which two agents develop, reconcile, and review a specification.
+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.
+The shared starter config uses Claude as both Captain and Coder, and Codex as Reviewer.
 
 ```sh
 npm install -g @sublang/playbook
@@ -40,10 +41,11 @@ If an SDK is missing or older than cligent supports, Playbook prints the pinned
 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`
 
+Interactive `playbook` additionally needs `tmux` 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.
 
 ```sh
@@ -51,18 +53,22 @@ cd /path/to/your/project
 playbook
 ```
 
-Type a task, or enter `/code <task>` to select CODE directly.
+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; retain the Codex Reviewer with:
+The same config, compiled Captain, enabled playbooks, players, and nested calls power headless turns.
+Run REVIEW explicitly, or pipe a longer request to Captain:
 
 ```sh
-playbook run @sublang/playbook/code/registry "add a test for parseArgs" --player reviewer=codex --json
+playbook run "/review review the latest commit"
+printf '%s\n' 'Implement the approved specification, then review it.' | playbook run
 ```
 
-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.
+`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.
+
+See [Using the CLI](docs/cli.md) for flags and durable continuation, [Configuring agents](docs/configuration.md) for the shared lineup, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](CHANGELOG.md) for releases.
 
 ## Create your own playbook
 
@@ -71,10 +77,12 @@ The separate [SLC compiler](https://github.com/sublang-ai/slc) requires Node.js
 ```sh
 npm install -g @sublang/slc
 slc playbook my-workflow.md
-playbook run ./my-workflow.ts "<your task>"
+# After enabling /absolute/path/to/my-workflow.ts in the shared config:
+playbook run "/my-workflow <your task>"
 ```
 
-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.
+SLC writes `my-workflow.ts`, a registry entry ready for Playbook, beside the source, and the inspectable intermediates and tests under `my-workflow.playbook/`.
+Enable that entry and bind each role it declares under `playbooks.my-workflow` in the shared config, then invoke `/my-workflow`; see [External playbooks](docs/configuration.md#external-playbooks) and the [SLC documentation](https://github.com/sublang-ai/slc#quick-start).
 
 ## How it compiles
 
@@ -85,7 +93,7 @@ SLC's `playbook` pipeline has three phases:
 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), and [DISCUSS](reference/sdlc/discuss.md) examples.
+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
 
@@ -108,8 +116,8 @@ pnpm playbook   # drive a Boss turn against the source tree
 ```
 
 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/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.
+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/cli.md

@@ -3,9 +3,10 @@
 
 # Using the CLI
 
-`playbook` has two surfaces: an interactive tmux-play session, and a
-one-shot non-interactive `run`. Agent settings for both come from the
-[config](configuration.md).
+`playbook` has two presentations of one configured Captain session: an
+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.
 
 ## Installing agent SDKs
 
@@ -50,7 +51,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,117 +82,164 @@ 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, where the session
-Captain runs for the whole session and sees every turn. Use
-`/code <task>` to select the CODE playbook 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 `/code` 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
-([CAPTAIN-1](../specs/user/playbook-captain.md#captain-1),
-[CAPTAIN-2](../specs/user/playbook-captain.md#captain-2)).
-
-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)).
+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
+([[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
-([CAPTAIN-19](../specs/user/playbook-captain.md#captain-19)).
+([[playbook-captain-19](../specs/packages/playbook-captain.md#playbook-captain-19)]).
 
-## Non-interactive
+## Headless
 
-`playbook run <from> [task]` runs one playbook once, without tmux-play
-and without a config entry — point it straight at a registry module:
+`playbook run [input]` submits one exact Boss turn to the same Captain that
+the interactive pane hosts, without constructing tmux. The shared config
+selects the Captain, enabled playbooks, players, options, provisioning, and
+readiness; a slash command selects a playbook through Captain, and ordinary
+text remains a conversational Captain turn.
 
 ```sh
-playbook run @sublang/playbook/code/registry "add a test for parseArgs" \
-  --player coder=claude --player reviewer=codex --cwd ./my-repo
+cd ./my-repo
+playbook run "/review review the latest commit"
+playbook run "/code implement the approved specification"
+printf '%s\n' 'Summarize the current work and propose the next step.' | playbook run
 ```
 
-`[task]` is read from stdin when omitted — pipe long or multi-line
-intents the same way you would to `claude -p` or `codex exec`.
+When `[input]` is absent, stdin is read to EOF as verbatim UTF-8 text.
+Use `--` before one flag-shaped input. Plain stdout is exactly the one
+Boss-visible Captain reply plus a line feed; status and diagnostics use
+stderr, and `--verbose` adds only telemetry topic names to stderr.
+`--json` instead prints exactly `{"sessionId":"…","reply":"…"}`.
 
 | Flag | Meaning |
 | --- | --- |
-| `--player <role>=<agent>` | bind a required role |
-| `--captain <agent>` | set the captain/judge agent |
-| `--option <key>=<value>` | a playbook option (CODE's `committer`) |
-| `--cwd <dir>` | the agents' working directory |
-| `--json` | one envelope: `outcome`, `sessionId`, output or questions |
-| `--no-provision` | never create engine links beside a filesystem `<from>` |
-
-`<agent>` is `<adapter>[:<model>][@<effort>]` — `codex:gpt-5.5@xhigh`,
-or `claude@high` for the default model at high reasoning effort. The
-model keeps every interior colon (`opencode:ollama/llama3:8b@max`), and
-an unsupported effort is rejected up front naming the adapter's
-supported values. Roles and the captain default to `claude` unless the
-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)).
-
-### Engine provisioning
-
-A compiled playbook module imports `xstate` and
-`@sublang/playbook/xstate-runtime` from its own directory. When a
-filesystem `<from>` cannot resolve them — typically under a global
-install with no project-local packages —
-`playbook run` provisions them automatically before loading: it creates
-`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),
+| `--with <path>` | overlay the shared config for a new session; 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 |
+| `--continue` | continue the latest durable Captain session |
+| `--session <id>` | continue one durable Captain session explicitly |
+| `--retry-uncertain` | with `--session`, retry its exact recorded uncertain input |
+| `--discard-uncertain` | with `--session`, abandon its uncertain attempt |
+| `--` | end options before one literal input or reply |
+| `-h`, `--help` | print the complete grammar without reading stdin or config |
+
+Exit `0` means the Captain turn and its durable hand-off were presented,
+even when the selected action reported rejection or failure through the
+Captain reply. Argument, config, catalog, readiness, or pre-turn setup errors
+exit `1`; a started-turn, persistence, lease-release, or presentation failure
+exits `2` with stdout empty. SIGINT, SIGTERM, and SIGHUP preserve the
+uncertain boundary, withhold stdout, and are re-raised after lease retirement
+([[playbook-cli-18](../specs/packages/playbook-cli.md#playbook-cli-18)]).
+
+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.
+
+### Piping a Spex update prompt
+
+`spex scaffold --update` refreshes its scaffold before printing guidance and
+a fenced reconciliation prompt. Force Spex's non-interactive agent-file
+selection, capture its successful output, extract the first fenced prompt,
+and pass only that prompt to Captain:
+
+```sh
+update_output="$(spex scaffold --update </dev/null)" &&
+printf '%s\n' "$update_output" |
+  awk '/^```$/{if (++n==2) exit; next} n==1' |
+  playbook run
+```
+
+The capture prevents a failed Spex command from launching Playbook. Without
+`--lang`, the first fenced block is the sole structure reconciliation or
+legacy-migration prompt; a language switch adds a second translation prompt.
+
+### External playbooks and engine provisioning
+
+Enable an external registry in the shared config and invoke its effective
+slash command; a path-shaped `playbooks.<id>.from` is resolved relative to
+the primary config file. Before either front end imports a configured
+filesystem registry, the shared launcher checks whether that module can
+resolve `xstate` and `@sublang/playbook/xstate-runtime`. When needed, it
+creates engine symlinks beside the module and prints one provisioning line
+([[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
-mechanism entirely.
 
-If the module's directory is a git repository, add `node_modules/` to
-its `.gitignore` so the provisioned links never land in commits made by
-player agents working there.
+A directory where both imports already resolve is untouched, and
+`--no-provision` disables new links for either fresh front end. If the
+module's directory is a git repository, add `node_modules/` to its
+`.gitignore` so provisioned links never enter player commits.
+
+### 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`:
+
+```sh
+playbook run --continue "keep the scope small; skip the docs"
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1
+```
+
+A missing reply is read verbatim from stdin. Continuation restores the exact
+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
+([[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
+[DR-031](../specs/decisions/031-shared-captain-session-front-ends.md)).
 
-### Resuming a parked run
+### Recovering an uncertain turn
 
-When the playbook stops to ask something, the run is parked, not lost:
-the question prints to stdout, the session is saved under
-`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/`, and stderr
-names the command that continues it.
+Before model work, the runner takes one exclusive session lease and writes an
+uncertain marker. If the process is interrupted after effects may
+have begun but before settlement is durable, ordinary continuation refuses
+to guess. Choose explicitly:
 
 ```sh
-playbook run resume 4f2c…9ab1 "keep the scope small; skip the docs"
-playbook run resume --last   # most recently parked session; reply on stdin
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 --retry-uncertain
+playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 --discard-uncertain
 ```
 
-A resumed run picks up exactly where it parked — same session id, same
-workflow state, and each agent continues its own conversation — then
-prints the final output and exits `0`, or parks again and exits `3`. The
-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),
-[DR-014](../specs/decisions/014-durable-one-shot-run-sessions.md)).
+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.

package/docs/configuration.md

@@ -3,7 +3,7 @@
 
 # Configuring agents
 
-`playbook` reads one config at
+`playbook` and every fresh `playbook run` 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.
@@ -16,9 +16,10 @@ $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
 
 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), optional
+and the replies you see in the Captain pane or on headless stdout), optional
 `layout` / `notifications` / `theme`, and a `playbooks` map of enabled
-playbooks.
+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`,
@@ -33,8 +34,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:
@@ -54,6 +55,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
@@ -62,15 +73,47 @@ 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
 
@@ -80,7 +123,7 @@ 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
@@ -96,6 +139,7 @@ recursively, other values replace):
 
 ```sh
 playbook --with fast-lineup.yaml
+playbook run --with fast-lineup.yaml "/code implement the approved change"
 ```
 
 ```yaml
@@ -109,8 +153,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
 ```
@@ -122,25 +166,65 @@ 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)]).
+Overlays apply only when creating a fresh session. A continued headless
+session restores its frozen config and working directory and rejects `--with`.
 
-## Defaults for `playbook run`
+## Shared headless configuration
 
-An optional top-level `run` block supplies the non-interactive host's
-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),
-[DR-017](../specs/decisions/017-run-defaults-config.md)).
+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.
+
+## External playbooks
+
+`slc playbook my-workflow.md` emits `my-workflow.ts` beside its artifact
+directory. That file already default-exports the registry manifest Playbook
+requires: `id`, `command`, `intent`, `requiredRoleIds`, `validateOptions`,
+and `createRuntime`. Enable it under `playbooks`, bind every role listed in
+its `requiredRoleIds`, and invoke its effective slash command through Captain:
 
 ```yaml
-run:
-  captain: claude:claude-opus-4-8@high
-  players:
-    coder: claude:claude-opus-4-8[1m]@xhigh
+playbooks:
+  my-workflow:
+    from: /absolute/path/to/my-workflow.ts
+    players:
+      worker: claude
 ```
 
+```sh
+playbook run "/my-workflow perform the task"
+```
+
+A relative path-shaped `from` is resolved relative to the primary config
+file, not the invocation directory; an absolute path is clearest for an SLC
+entry emitted in a project working tree.
+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 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>`
+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`
+or `--session`.
+
+The JSON response is now exactly `{ "sessionId": "…", "reply": "…" }`.
+Released direct-run session records are not complete Captain sessions and
+cannot be continued by the new host ([[playbook-cli-19](../specs/packages/playbook-cli.md#playbook-cli-19)],
+[[playbook-cli-22](../specs/packages/playbook-cli.md#playbook-cli-22)],
+[[playbook-cli-28](../specs/packages/playbook-cli.md#playbook-cli-28)]).
+
 ## Migrating from `profiles`
 
 Configs written before 3.0.0 carried a top-level `profiles` map. The
@@ -153,7 +237,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