utterplan 0.6.4__tar.gz → 0.6.5__tar.gz

{utterplan-0.6.4 → utterplan-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.4
+Version: 0.6.5
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -253,7 +253,7 @@ UtterPlan is the canonical, engine-independent semantic compiler from one SSMD
 document (or explicitly selected plain-text document) to an executable speech
 plan. It produces deterministic prepared text, paragraph-local flow units, safe boundary opportunities, authored pause intents, and segment-local
 semantics, portable document metadata, and typed directives for
-independent downstream consumers such as Readio, VoiceRender, and other FlowPlan users. Its book commands read the SSMDBook manifest only for chapter discovery, never modify the manifest or source chapters, and write derived plans to separate directories. It uses TTSReady for written-to-spoken preparation and stops before G2P, synthesis, and audio.
+independent downstream FlowPlan consumers. Its book commands read the SSMDBook manifest only for chapter discovery, never modify the manifest or source chapters, and write derived plans to separate directories. It uses TTSReady for written-to-spoken preparation and stops before G2P, synthesis, and audio.
 
 ## CLI
 
@@ -293,7 +293,15 @@ Compile one editable `.ssmdoc` directory as one SSMD document and one FlowPlan:
 utterplan compile-document story.ssmdoc
 ```
 
-By default this writes `story.ssmdoc/.readio/utterplan/document-0001.utterplan.toml` and a `compile-report.toml`. The current `document.ssmd.md` is authoritative even if its manifest digest is stale; UtterPlan leaves the source and manifest untouched. This is separate from the multi-chapter SSMDBook workflow below. See the [SSMDDoc workspace guide](docs/ssmdoc.md) for manifest safety, output options, and the Python API.
+By default this writes `story.ssmdoc/utterplan/document.utterplan.toml` and `story.ssmdoc/utterplan/compile-report.toml`. The current `document.ssmd.md` is authoritative even if its manifest digest is stale; UtterPlan leaves the source and manifest untouched. This is separate from the multi-chapter SSMDBook workflow below. See the [SSMDDoc workspace guide](docs/ssmdoc.md) for manifest safety, output options, and the Python API.
+
+Project the saved plan with an explicit RenderProfile:
+
+```bash
+utterplan render-document story.ssmdoc --profile narration.renderprofile.toml
+```
+
+The profile-specific RenderPlan is written to a matching variant directly under `story.ssmdoc/renderplan/`.
 
 Compile a selected chapter range directly from an editable SSMDBook workspace:
 
@@ -316,6 +324,58 @@ utterplan/
 
 Omit `--chapters` to compile all manifest chapters. Use comma-separated source-number selections for non-contiguous ranges, for example `utterplan compile-book chapters --chapters 1,3-5`. `--diagnostics warnings|all|none` defaults to warnings; failures are always shown and reports retain complete diagnostics. The book root itself is also accepted as input; see the [SSMDBook guide](docs/ssmdbook.md).
 
+## Logical roles and complete RenderProfiles
+
+An SSMD `voice` reference is a **logical role**: a renderer-independent name such as `narrator`, `host`, or `guest`. A **role binding** is the concrete renderer configuration for that name in a RenderProfile. One RenderProfile is the complete cast for one render variant, together with shared planning and pause policy; it may bind different roles to different engines. UtterPlan accepts one `--profile` per projection, not one profile per role, and does not discover engines or voices.
+
+A profile can define a default for speech without an explicit role reference and explicit bindings for other roles:
+
+In SSMD, the source remains renderer-independent; for example:
+
+```markdown
+:::{voice="host"}
+Host line.
+:::
+```
+
+```toml
+default_role = "narrator"
+
+[roles.narrator]
+language = "en-US"
+
+[roles.narrator.binding]
+renderer = "kokoro"
+target_id = "v1.0"
+voice = "af_heart"
+
+[roles.host]
+language = "en-US"
+
+[roles.host.binding]
+renderer = "kitten"
+target_id = "mini-0.8"
+voice = "Jasper"
+
+[roles.guest]
+language = "en-US"
+
+[roles.guest.binding]
+renderer = "piper"
+target_id = "en_US-amy-medium"
+voice = "en_US-amy-medium"
+```
+
+Inspect symbolic role usage without a profile, then project a document or selected book chapters with the same complete cast:
+
+```bash
+utterplan inspect story.utterplan.toml --roles
+utterplan render-document story.ssmdoc --profile printer-cast.renderprofile.toml
+utterplan render-book novel.ssmdbook --profile novel-cast.renderprofile.toml
+```
+
+Projection reports required and available roles and rejects incomplete coverage before writing the RenderPlan variant. The profile and its concrete role bindings remain separate from the source SSMD.
+
 ## From an SSMDBook to RenderPlans
 
 UtterPlan keeps one canonical semantic plan per chapter. A RenderProfile is a

{utterplan-0.6.4 → utterplan-0.6.5}/README.md

@@ -9,7 +9,7 @@ UtterPlan is the canonical, engine-independent semantic compiler from one SSMD
 document (or explicitly selected plain-text document) to an executable speech
 plan. It produces deterministic prepared text, paragraph-local flow units, safe boundary opportunities, authored pause intents, and segment-local
 semantics, portable document metadata, and typed directives for
-independent downstream consumers such as Readio, VoiceRender, and other FlowPlan users. Its book commands read the SSMDBook manifest only for chapter discovery, never modify the manifest or source chapters, and write derived plans to separate directories. It uses TTSReady for written-to-spoken preparation and stops before G2P, synthesis, and audio.
+independent downstream FlowPlan consumers. Its book commands read the SSMDBook manifest only for chapter discovery, never modify the manifest or source chapters, and write derived plans to separate directories. It uses TTSReady for written-to-spoken preparation and stops before G2P, synthesis, and audio.
 
 ## CLI
 
@@ -49,7 +49,15 @@ Compile one editable `.ssmdoc` directory as one SSMD document and one FlowPlan:
 utterplan compile-document story.ssmdoc
 ```
 
-By default this writes `story.ssmdoc/.readio/utterplan/document-0001.utterplan.toml` and a `compile-report.toml`. The current `document.ssmd.md` is authoritative even if its manifest digest is stale; UtterPlan leaves the source and manifest untouched. This is separate from the multi-chapter SSMDBook workflow below. See the [SSMDDoc workspace guide](docs/ssmdoc.md) for manifest safety, output options, and the Python API.
+By default this writes `story.ssmdoc/utterplan/document.utterplan.toml` and `story.ssmdoc/utterplan/compile-report.toml`. The current `document.ssmd.md` is authoritative even if its manifest digest is stale; UtterPlan leaves the source and manifest untouched. This is separate from the multi-chapter SSMDBook workflow below. See the [SSMDDoc workspace guide](docs/ssmdoc.md) for manifest safety, output options, and the Python API.
+
+Project the saved plan with an explicit RenderProfile:
+
+```bash
+utterplan render-document story.ssmdoc --profile narration.renderprofile.toml
+```
+
+The profile-specific RenderPlan is written to a matching variant directly under `story.ssmdoc/renderplan/`.
 
 Compile a selected chapter range directly from an editable SSMDBook workspace:
 
@@ -72,6 +80,58 @@ utterplan/
 
 Omit `--chapters` to compile all manifest chapters. Use comma-separated source-number selections for non-contiguous ranges, for example `utterplan compile-book chapters --chapters 1,3-5`. `--diagnostics warnings|all|none` defaults to warnings; failures are always shown and reports retain complete diagnostics. The book root itself is also accepted as input; see the [SSMDBook guide](docs/ssmdbook.md).
 
+## Logical roles and complete RenderProfiles
+
+An SSMD `voice` reference is a **logical role**: a renderer-independent name such as `narrator`, `host`, or `guest`. A **role binding** is the concrete renderer configuration for that name in a RenderProfile. One RenderProfile is the complete cast for one render variant, together with shared planning and pause policy; it may bind different roles to different engines. UtterPlan accepts one `--profile` per projection, not one profile per role, and does not discover engines or voices.
+
+A profile can define a default for speech without an explicit role reference and explicit bindings for other roles:
+
+In SSMD, the source remains renderer-independent; for example:
+
+```markdown
+:::{voice="host"}
+Host line.
+:::
+```
+
+```toml
+default_role = "narrator"
+
+[roles.narrator]
+language = "en-US"
+
+[roles.narrator.binding]
+renderer = "kokoro"
+target_id = "v1.0"
+voice = "af_heart"
+
+[roles.host]
+language = "en-US"
+
+[roles.host.binding]
+renderer = "kitten"
+target_id = "mini-0.8"
+voice = "Jasper"
+
+[roles.guest]
+language = "en-US"
+
+[roles.guest.binding]
+renderer = "piper"
+target_id = "en_US-amy-medium"
+voice = "en_US-amy-medium"
+```
+
+Inspect symbolic role usage without a profile, then project a document or selected book chapters with the same complete cast:
+
+```bash
+utterplan inspect story.utterplan.toml --roles
+utterplan render-document story.ssmdoc --profile printer-cast.renderprofile.toml
+utterplan render-book novel.ssmdbook --profile novel-cast.renderprofile.toml
+```
+
+Projection reports required and available roles and rejects incomplete coverage before writing the RenderPlan variant. The profile and its concrete role bindings remain separate from the source SSMD.
+
 ## From an SSMDBook to RenderPlans
 
 UtterPlan keeps one canonical semantic plan per chapter. A RenderProfile is a

{utterplan-0.6.4 → utterplan-0.6.5}/docs/architecture.md

@@ -1,6 +1,6 @@
 ---
 title: "Architecture Documentation"
-version: 2
+version: 3
 generator: "archledger 0.4.0"
 arc42_template_version: "9.0-EN"
 ---
@@ -50,7 +50,7 @@ FlowPlan v7 (paragraph-local units, segments, boundaries, authored pauses)
 Downstream chunking / token-budget / pause choices
        |
        v
-Readio / VoiceRender / other FlowPlan consumers
+Downstream FlowPlan consumers
        |
        v
 G2P / synthesis / audio (downstream)
@@ -62,7 +62,7 @@ workspaces without changing book content.
 
 ## Document workspaces
 
-An editable `ssmdconvert.document` v1 workspace (`.ssmdoc`) is another source path for the one-document compiler. `compile-document` discovers its canonical current SSMD document and writes one FlowPlan plus an operational report under `.readio/utterplan/`; it does not create a book or alter workspace source material.
+An editable `ssmdconvert.document` v1 workspace (`.ssmdoc`) is another source path for the one-document compiler. `compile-document` discovers its canonical current SSMD document and writes one FlowPlan plus an operational report under `<workspace>/utterplan/`; `render-document` projects that saved plan with an explicit profile into `<workspace>/renderplan/<label>--<profile-id-prefix>/`. Neither command creates book-set semantics or alters workspace source material.
 
 ## Requirements Overview
 
@@ -125,7 +125,7 @@ TTSReady
     ^
 UtterPlan
     ^
-Readio / VoiceRender / other FlowPlan consumers
+Downstream FlowPlan consumers
 ```
 
 UtterPlan depends directly on SSMD, PhraseSplit, and TTSReady:
@@ -140,9 +140,9 @@ UtterPlan depends directly on SSMD, PhraseSplit, and TTSReady:
 - **spaCy** optionally enriches tokens (best effort, `sm`/`md`/`lg`/`trf` preference;
   UtterPlan never downloads models and falls back to deterministic tokens).
 - **RenderPlan** defines the shared profile/plan contract used by the optional
-  projection; **VoiceRender** creates engine-backed profiles and owns runtime
-  validation, preflight, and speech execution; **Readio** and other consumers
-  consume FlowPlan downstream.
+  projection; downstream renderers consume portable RenderProfiles and RenderPlans,
+  while other downstream consumers consume FlowPlans. Engine selection, preflight,
+  and speech execution are outside UtterPlan.
 
 ## In scope
 
@@ -346,12 +346,23 @@ not calculate renderer-specific metrics.
 ```text
 ssmdconvert.document v1 manifest + current document.ssmd.md
     -> utterplan compile-document
-    -> one FlowPlan at .readio/utterplan/document-0001.utterplan.toml
+    -> one FlowPlan at utterplan/document.utterplan.toml
        + one compile-report.toml
 ```
 
 The manifest validates the workspace contract and safe canonical path; SSMD 0.9 content is compiled by the existing single-document path. A stale stored digest does not block editable-directory compilation, and UtterPlan does not modify source material or model the document as a chapter.
 
+## Scenario: project a RenderPlan from an editable SSMDDoc workspace
+
+```text
+saved FlowPlan + explicit RenderProfile
+    -> utterplan render-document
+    -> one profile-specific RenderPlan at renderplan/<label>--<profile-id-prefix>/document.renderplan.toml
+       + canonical renderprofile.toml snapshot + render-report.toml
+```
+
+The command projects the existing plan without compiling source or invoking a renderer. Profile identity is embedded in the variant path, and a mismatched or ambiguous profile snapshot is rejected; source files and the SSMDDoc manifest remain unchanged.
+
 <!-- archledger: no accepted records for this section yet -->
 
 # Deployment View
@@ -363,8 +374,8 @@ or audio dependencies:
   dynamically derived from Git tags by setuptools-scm and is independent of the
   plan schema version.
 - **Installation shapes.** Installed as a library (`pip install utterplan`) for
-  consumer pipelines such as Readio, or with the `utterplan` CLI for direct SSMDBook
-  workflows. Development installs use `pip install -e '.[dev,docs]'`.
+  downstream FlowPlan consumers, or with the `utterplan` CLI for direct SSMDBook and
+  SSMDDoc workflows. Development installs use `pip install -e '.[dev,docs]'`.
 - **Optional linguistic enrichment.** spaCy models are preferred in `sm`, `md`,
   `lg`, `trf` order when already installed; UtterPlan never downloads models and
   continues with deterministic fallback tokens when spaCy or every compatible local
@@ -372,15 +383,15 @@ or audio dependencies:
 - **No runtime services.** Everything runs in-process; there is no server, daemon,
   network fetch, or audio device access. Media references and extension names in
   plans are data only.
-- **Downstream placement.** Consumers (Readio, VoiceRender, PyKokoro-based
-  renderers) import UtterPlan, never the reverse. Renderers add engines, model
-  runtimes, G2P, synthesis, and audio on their side of the boundary.
+- **Downstream placement.** Consumers of UtterPlan's portable FlowPlan and optional
+  RenderPlan contracts add engines, model runtimes, G2P, synthesis, and audio on their
+  side of the boundary; UtterPlan does not import those packages.
 - **Documentation.** Sphinx docs build from `docs/` with
   `sphinx-build -W --keep-going -b html docs docs/_build/html`.
 - **Quality gate.** `python -m pytest -q`, `ruff check .`, and `mypy utterplan` run
   against the self-contained repository test suite.
 
-- **Editable document workspaces.** `.ssmdoc` v1 is consumed as a stable file-format contract with the standard library; `ssmdconvert` is not a runtime dependency. `compile-document` writes derived plans under the reserved `.readio/utterplan/` directory without changing source files.
+- **Editable document workspaces.** `.ssmdoc` v1 is consumed as a stable file-format contract with the standard library; `ssmdconvert` is not a runtime dependency. `compile-document` writes semantic plans and its report directly under `<workspace>/utterplan/`; `render-document` writes profile-specific artifacts directly under `<workspace>/renderplan/` without changing source files.
 
 <!-- archledger: no accepted records for this section yet -->
 

{utterplan-0.6.4 → utterplan-0.6.5}/docs/changelog.md

@@ -4,6 +4,23 @@
 
 ## [Unreleased]
 
+## [v0.6.5] - 2026-10-19
+
+### Added
+
+- Added render-document for projecting compiled SSMDDoc FlowPlans into profile-specific RenderPlans
+- Added logical role coverage inspection and complete-profile validation for document and book rendering
+
+### Changed
+
+- Changed editable SSMDDoc workspaces to use stable utterplan and renderplan output directories
+
+### Fixed
+
+- Fixed documentation links for logical role and profile coverage guidance
+
+<!-- generated by releaseledger -->
+
 ## [v0.6.4] - 2026-10-19
 
 ### Added

{utterplan-0.6.4 → utterplan-0.6.5}/docs/cli.md

@@ -50,6 +50,18 @@ require `--force`. `--explain` formats the generated plan and replan decisions;
 does not invoke planning a second time. `--json` emits a versioned JSON wrapper to
 stdout while the RenderPlan artifact remains TOML at `--output`.
 
+## Logical roles and complete-profile coverage
+
+Role coverage is validated before grouping or replanning. The selected profile must contain every explicit speech role and, when any speech omits a role reference, its `default_role`. Missing roles are reported together as `renderplan.role.missing`; extra profile roles are allowed. The check is renderer-independent and does not add role data to the RenderPlan schema.
+
+Use source-only role inspection without loading a RenderProfile:
+
+```bash
+utterplan inspect chapter.utterplan.toml --roles
+```
+
+The human `render-plan` summary reports required roles and `coverage: complete`. With `--json`, the versioned CLI wrapper includes a `role_coverage` object (`default_role`, `required`, `available`, `missing`, and `uses_default_role`) alongside, but outside, the RenderPlan payload.
+
 ## Input resolution
 
 The rules are deterministic:
@@ -135,10 +147,24 @@ utterplan compile-document INPUT [--output-dir PATH] [--language LANGUAGE]
   [--force] [--report PATH] [--diagnostics {warnings,all,none}]
 ```
 
-The default output directory is `<workspace>/.readio/utterplan/`, containing `document-0001.utterplan.toml` and `compile-report.toml`. `--output-dir` and `--report` override those locations. Existing plan files require `--force`; output collisions with the source or manifest are rejected. A document header's language is authoritative; `--language`/`--lang` is a fallback when it is absent.
+The default output directory is `<workspace>/utterplan/`, containing `document.utterplan.toml` and `compile-report.toml`. `--output-dir` and `--report` override those locations. Existing plan files require `--force`; output collisions with the source or manifest are rejected. A document header's language is authoritative; `--language`/`--lang` is a fallback when it is absent.
 
 Editable content wins over the stored manifest digest: compilation reads the current `document.ssmd.md` but never modifies the manifest or source. The command has no `--input-format`, chapter selection, or `--fail-fast`; it handles one document. The existing `compile` and `validate` commands also accept the workspace root or canonical document path, while `compile` retains its normal stdout/`-o` behavior. This is not `compile-book`: an SSMDDoc creates one plan, while an SSMDBook orchestrates independent chapter plans. ZIP bundles are not supported and `ssmdconvert` is not a runtime dependency. See the [SSMDDoc guide](ssmdoc.md) for format validation and the `compile_ssmdoc()` Python API.
 
+## Project an SSMDDoc RenderPlan
+
+`render-document` projects the already-saved single-document UtterPlan through an explicit RenderProfile. It never compiles implicitly:
+
+```text
+utterplan render-document INPUT --profile PROFILE
+  [--utterplan-dir PATH] [--output-root PATH] [--variant LABEL]
+  [--force] [--report PATH]
+```
+
+By default it reads `<workspace>/utterplan/document.utterplan.toml` and writes a profile-fingerprinted variant under `<workspace>/renderplan/<label>--<profile-id-prefix>/`, containing `renderprofile.toml`, `document.renderplan.toml`, and `render-report.toml`. `--variant` changes only the readable label; the profile fingerprint remains part of the directory identity. A profile mismatch or ambiguous existing snapshot is rejected even with `--force`. This is a one-document projection, not a book-set workflow. See the [SSMDDoc guide](ssmdoc.md).
+
+The start summary also lists the document's required roles and coverage. Coverage is checked before a new variant directory, profile snapshot, or RenderPlan is written; a missing role leaves no partial variant.
+
 ## Compile chapters from an SSMDBook workspace
 
 `compile-book` discovers selected SSMD chapters from an editable `.ssmdbook` manifest and compiles each chapter independently through the batch compiler. Pass either the book directory or its canonical `chapters/` directory:
@@ -185,8 +211,9 @@ utterplan render-book INPUT --profile PROFILE [--chapters SELECTOR]
 `chapters/` directory. `--chapters` uses the same manifest `source_number`
 selector as `compile-book`: `all` (default), one number, an inclusive range, or
 comma-separated selections such as `1,3-5,9`. Chapters remain in manifest order.
-`--profile` is required and is loaded once through the shared RenderPlan codec;
-UtterPlan does not call VoiceRender or probe engines.
+`--profile` is required and is loaded once through the shared RenderPlan codec; UtterPlan does not call VoiceRender or probe engines.
+
+Before initializing a new variant, `render-book` checks role coverage across all readable selected chapter plans. A single incomplete chapter fails the projection with the missing role names and affected chapter IDs; no new profile snapshot or `renderplan-set.toml` is written. The start summary lists the aggregate required roles and complete coverage. Other missing/invalid source-plan behavior is unchanged.
 
 Defaults and behavior:
 

{utterplan-0.6.4 → utterplan-0.6.5}/docs/python-api.md

@@ -79,6 +79,29 @@ prior partitions and replaces only exact failed speech occurrences. Backend metr
 remain diagnostics supplied by preflight; UtterPlan does not estimate them. Use
 `utterplan render-plan --explain` to format the already-built decisions.
 
+### Inspect logical role coverage
+
+The public role-coverage helpers expose source inventory independently of projection or renderer bindings. `logical_role_inventory()` counts explicit role references and speech using the profile default; `profile_role_coverage()` compares those requirements with one complete RenderProfile, preserving first-occurrence order for required roles and deterministic sorting for available roles. The returned `LogicalRoleInventory` and `ProfileRoleCoverage` types separate source inventory from profile coverage. Both functions are available from the package root:
+
+```python
+from renderplan.codec import load_profile
+from utterplan import (
+    FlowPlan,
+    logical_role_inventory,
+    profile_role_coverage,
+    assert_profile_role_coverage,
+)
+
+source = FlowPlan.load("chapter.utterplan.toml")
+inventory = logical_role_inventory(source)
+profile = load_profile("cast.renderprofile.toml")
+coverage = assert_profile_role_coverage(source, profile)
+print(inventory.explicit_roles, inventory.explicit_occurrences)
+print(coverage.required_roles, coverage.available_roles, coverage.missing_roles)
+```
+
+Empty and audio-only segments do not require a role. `assert_profile_role_coverage()` raises the normal `renderplan.role.missing` projection error with all missing role names; `build_render_plan()` performs this check before grouping or replanning.
+
 ## Persistable planning attempts
 
 `compile_attempt` and `UtterancePlanner.compile_attempt` expose a finalized planning

{utterplan-0.6.4 → utterplan-0.6.5}/docs/ssmdbook.md

@@ -102,6 +102,8 @@ utterplan render-book . --profile amy.renderprofile.toml --chapters 5-17
 utterplan render-book . --profile joe.renderprofile.toml --chapters 5-17
 ```
 
+One RenderProfile is the complete cast shared by every selected chapter, not a profile per character or role. Logical role names live in SSMD; the profile's role bindings can target different renderers. Before creating a new variant, `render-book` checks all readable selected UtterPlans together and reports every uncovered role with the affected chapter IDs. See the [README role example](https://github.com/buchwandler/utterplan/blob/main/README.md#logical-roles-and-complete-renderprofiles).
+
 The result has one shared semantic collection and distinct renderer-specific
 variants, for example:
 

{utterplan-0.6.4 → utterplan-0.6.5}/docs/ssmdoc.md

@@ -6,7 +6,7 @@ UtterPlan can compile an editable `.ssmdoc` workspace as one SSMD 0.9 document.
 
 A workspace is identified by a `manifest.json` whose `format` is `ssmdconvert.document` and whose `schema_version` is `1`. UtterPlan supports the v1 contract and expects the canonical document entry to identify `document-0001` at the normalized relative path `document.ssmd.md`. The source is SSMD 0.9.
 
-The current `document.ssmd.md` is authoritative. Its manifest digest and character count are metadata, not a lock: if you edit the document and its recorded digest becomes stale, UtterPlan compiles the current file. It never rewrites the manifest, refreshes hashes, or edits source content. The `.readio/utterplan/` directory is reserved for derived UtterPlan artifacts.
+The current `document.ssmd.md` is authoritative. Its manifest digest and character count are metadata, not a lock: if you edit the document and its recorded digest becomes stale, UtterPlan compiles the current file. It never rewrites the manifest, refreshes hashes, or edits source content. Semantic plans and reports are written directly under the workspace's visible `utterplan/` directory; profile-specific RenderPlans are written directly under `renderplan/`. These are derived artifacts, not manifest members.
 
 Discovery and path handling are deliberately strict. The manifest must be valid UTF-8 JSON within the 2 MiB limit, and the document is limited to 64 MiB. UtterPlan checks the canonical path and workspace containment, rejects unsupported manifest versions and unsafe paths, and does not follow a document path outside the workspace. It reads no source-media files. `ssmdconvert` is not a runtime dependency: UtterPlan consumes the published file-format contract directly.
 
@@ -23,8 +23,8 @@ utterplan compile-document story.ssmdoc
 It writes one plan and one operational report by default:
 
 ```text
-story.ssmdoc/.readio/utterplan/
-├── document-0001.utterplan.toml
+story.ssmdoc/utterplan/
+├── document.utterplan.toml
 └── compile-report.toml
 ```
 
@@ -55,10 +55,26 @@ if result.failed:
 print(result.plan_path)
 ```
 
-The result provides the workspace and source paths, output and report paths, and the one-item batch outcome. Options include `output_dir`, `report`, `language`, `planner_config`, `force`, `diagnostics`, and progress/start callbacks. The default artifacts match the CLI: `.readio/utterplan/document-0001.utterplan.toml` and `compile-report.toml`.
+The result provides the workspace and source paths, output and report paths, and the one-item batch outcome. Options include `output_dir`, `report`, `language`, `planner_config`, `force`, `diagnostics`, and progress/start callbacks. The default artifacts match the CLI: `utterplan/document.utterplan.toml` and `utterplan/compile-report.toml`.
 
 ## SSMDDoc is not SSMDBook
 
 An SSMDDoc contains one editable document and produces one canonical FlowPlan. An SSMDBook manifest discovers multiple independent chapter documents; `compile-book` writes one plan per selected chapter and never builds a book-level combined plan. Use [SSMDBook workflows](ssmdbook.md) for book compilation and RenderPlan projection.
 
 Neither workspace workflow changes its source manifest or source documents. UtterPlan stops at semantic FlowPlans; engine selection, G2P, synthesis, and audio remain downstream.
+
+## Projecting a document RenderPlan
+
+After `utterplan compile-document .`, project the existing canonical FlowPlan without recompiling it:
+
+```bash
+utterplan render-document . --profile narration.renderprofile.toml
+```
+
+This writes `renderplan/<label>--<profile-fingerprint>/renderprofile.toml`, `document.renderplan.toml`, and `render-report.toml` directly under the workspace. The printed exact variant can be passed to `voicerender render-document`. A document is never wrapped in a one-chapter book or a RenderPlanSet. Re-run `compile-document` and this projection after source edits; VoiceRender intentionally renders only the selected explicit RenderPlan.
+
+### Logical roles and profile coverage
+
+A source-level `voice` name such as `narrator`, `host`, or `guest` is a **logical role**; it does not name an engine voice. The selected RenderProfile's **role binding** supplies the concrete renderer configuration. Treat one RenderProfile as the complete cast for a rendering variant, including its default role and shared planning/pause policy. UtterPlan accepts exactly one profile for this projection; it does not accept one profile per role or discover engines.
+
+Use `utterplan inspect <plan> --roles` to see explicit speech-role counts and whether unqualified speech needs the selected profile's default. `render-document` reports required roles and complete coverage, and rejects any missing roles before creating a new variant directory. The same multi-role RenderProfile format and example are documented in the [README](https://github.com/buchwandler/utterplan/blob/main/README.md#logical-roles-and-complete-renderprofiles).

{utterplan-0.6.4 → utterplan-0.6.5}/tests/test_book_api.py

@@ -27,7 +27,7 @@ from utterplan import (
     replan_book,
 )
 from utterplan.config import LinguisticsConfig, PlannerConfig
-from utterplan.model import FlowPlan
+from utterplan.model import FlowPlan, FlowSegment, FlowUnit, SegmentDirectives, VoiceDirective
 
 
 def _ssmd(text: str) -> str:
@@ -481,3 +481,28 @@ def test_public_book_services_refuse_outputs_inside_source_chapters(tmp_path: Pa
     with pytest.raises(BookServiceError, match="inside source chapters"):
         render_book(root, profile=profile_path, output_root=root / "chapters" / "renderplans")
     assert not (root / "chapters/renderplans").exists()
+
+
+def test_render_book_aggregates_missing_roles_before_variant_initialization(tmp_path: Path) -> None:
+    root = _book(tmp_path / "role-coverage.ssmdbook", (5, 6, 7))
+    utterplan_dir = root / "utterplan"
+    utterplan_dir.mkdir()
+    for number, role in ((5, None), (6, "host"), (7, "guest")):
+        text = f"Chapter {number}."
+        directives = (
+            SegmentDirectives(voice=VoiceDirective(reference=role)) if role else SegmentDirectives()
+        )
+        FlowPlan(
+            language="en-US",
+            flow=(FlowUnit((FlowSegment(text, "en-US", directives=directives),)),),
+        ).save(utterplan_dir / f"chapter-{number:04d}.utterplan.toml")
+    profile_path = root / "narration.renderprofile.toml"
+    _profile(profile_path)
+
+    with pytest.raises(BookServiceError) as raised:
+        render_book(root, profile=profile_path)
+
+    message = str(raised.value)
+    assert "host: chapter-0006" in message
+    assert "guest: chapter-0007" in message
+    assert not (root / "renderplan").exists()

{utterplan-0.6.4 → utterplan-0.6.5}/tests/test_cli_render_book.py

@@ -16,7 +16,14 @@ from renderplan import (
 )
 from renderplan import codec as renderplan_codec
 
-from utterplan import FlowPlan, FlowSegment, FlowUnit, TokenView
+from utterplan import (
+    FlowPlan,
+    FlowSegment,
+    FlowUnit,
+    SegmentDirectives,
+    TokenView,
+    VoiceDirective,
+)
 from utterplan.cli import build_parser, main
 
 
@@ -95,6 +102,32 @@ def _profile(path: Path, voice: str = "amy") -> RenderProfile:
     return renderplan_codec.load_profile(path)
 
 
+def _write_role_plan(root: Path, chapter: int, role: str | None) -> None:
+    text = f"Chapter {chapter} {role or 'narration'}."
+    directives = (
+        SegmentDirectives(voice=VoiceDirective(reference=role)) if role else SegmentDirectives()
+    )
+    FlowPlan(
+        language="en-US",
+        flow=(FlowUnit((FlowSegment(text, "en-US", directives=directives),)),),
+    ).save(root / "utterplan" / f"chapter-{chapter:04d}.utterplan.toml")
+
+
+def _multi_role_profile(path: Path) -> RenderProfile:
+    profile = RenderProfile(
+        roles={
+            "narrator": RoleProfile(language="en-US", binding={"engine": "kokoro"}),
+            "host": RoleProfile(language="en-US", binding={"engine": "kitten"}),
+            "guest": RoleProfile(language="en-US", binding={"engine": "piper"}),
+        },
+        default_role="narrator",
+        planning=PlanningPolicy(split="sentence"),
+        pauses=PausePolicy(mode="manual"),
+    )
+    renderplan_codec.save_profile(profile, path)
+    return renderplan_codec.load_profile(path)
+
+
 def _render(
     root: Path,
     profile_path: Path,
@@ -208,6 +241,32 @@ def test_render_book_success_matches_single_file_projection(tmp_path: Path, caps
     assert batch_plan.plan_id == single_plan.plan_id
 
 
+def test_render_book_reports_multi_role_coverage(tmp_path: Path, capsys) -> None:
+    root = _write_book(tmp_path / "multi-role.ssmdbook", (5, 6, 7))
+    _write_role_plan(root, 5, "host")
+    _write_role_plan(root, 6, "guest")
+    _write_role_plan(root, 7, None)
+    profile_path = root / "cast.renderprofile.toml"
+    profile = _multi_role_profile(profile_path)
+
+    assert _render(root, profile_path) == 0
+
+    output = capsys.readouterr().err
+    assert "roles:      host, guest, narrator" in output
+    assert "coverage:   complete" in output
+    variant = _variant(root, profile, label="cast")
+    collection = load_renderplan_set(variant / "renderplan-set.toml")
+    assert len(collection.chapters) == 3
+    plans = [
+        renderplan_codec.load_plan(variant / chapter.renderplan) for chapter in collection.chapters
+    ]
+    assert {speech.role for plan in plans for speech in plan.speech} == {
+        "host",
+        "guest",
+        "narrator",
+    }
+
+
 def test_render_book_accumulates_successful_chapters_and_replaces_latest_report(
     tmp_path: Path, capsys
 ) -> None: