utterplan 0.6.3__tar.gz → 0.6.5__tar.gz

utterplan-0.6.5/MANIFEST.in

@@ -0,0 +1,2 @@
+prune .ledger
+include docs/ssmdoc.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.3
+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
 
@@ -285,6 +285,24 @@ utterplan compile-many examples/*.ssmd --output-dir build/plans
 
 This writes one `.utterplan.toml` per source plus an atomically refreshed `compile-report.toml`. Terminal diagnostics default to warnings; `--diagnostics all` also prints informational records, while `--diagnostics none` suppresses non-failure details. Failures are always reported, and the operational report retains every diagnostic. Use `--fail-fast` to skip later inputs after a failure, `--force` to replace existing plans, or `--report PATH` to choose another report location.
 
+## Compile an SSMDDoc workspace
+
+Compile one editable `.ssmdoc` directory as one SSMD document and one FlowPlan:
+
+```bash
+utterplan compile-document story.ssmdoc
+```
+
+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:
 
 ```bash
@@ -306,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.3 → 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
 
@@ -41,6 +41,24 @@ utterplan compile-many examples/*.ssmd --output-dir build/plans
 
 This writes one `.utterplan.toml` per source plus an atomically refreshed `compile-report.toml`. Terminal diagnostics default to warnings; `--diagnostics all` also prints informational records, while `--diagnostics none` suppresses non-failure details. Failures are always reported, and the operational report retains every diagnostic. Use `--fail-fast` to skip later inputs after a failure, `--force` to replace existing plans, or `--report PATH` to choose another report location.
 
+## Compile an SSMDDoc workspace
+
+Compile one editable `.ssmdoc` directory as one SSMD document and one FlowPlan:
+
+```bash
+utterplan compile-document story.ssmdoc
+```
+
+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:
 
 ```bash
@@ -62,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.3 → utterplan-0.6.5}/docs/architecture.md

@@ -1,6 +1,6 @@
 ---
 title: "Architecture Documentation"
-version: 1
+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)
@@ -60,6 +60,10 @@ The compiler still handles one document at a time; the CLI's explicit SSMDBook
 commands (`compile-book`, `render-book`) discover chapters and orchestrate per-file
 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 `<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
 
 <!-- archledger: no accepted records for this section yet -->
@@ -121,7 +125,7 @@ TTSReady
     ^
 UtterPlan
     ^
-Readio / VoiceRender / other FlowPlan consumers
+Downstream FlowPlan consumers
 ```
 
 UtterPlan depends directly on SSMD, PhraseSplit, and TTSReady:
@@ -136,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
 
@@ -164,6 +168,12 @@ UtterPlan depends directly on SSMD, PhraseSplit, and TTSReady:
 - Renderer chunking, token-budget, and pause-realization choices.
 - Consumer-specific compatibility testing.
 
+## SSMDDoc source workspace
+
+- An editable `.ssmdoc` directory is discovered by its `ssmdconvert.document` v1 manifest, not by its directory suffix. Its canonical `document.ssmd.md` is the current compiler input.
+- The workspace remains one document to one FlowPlan. Manifest digests are provenance only for editable directories: UtterPlan compiles current content and never refreshes the manifest or edits the source.
+- `compile-document` is single-document convenience, not book orchestration. ZIP bundles, fake chapters, and an `ssmdconvert` runtime dependency are outside the contract.
+
 ## Business Context
 
 <!-- archledger: no accepted records for this section yet -->
@@ -253,6 +263,10 @@ provenance, diagnostics, and renderability evidence in a separate versioned TOML
 sidecar. Trace state is not renderer input and does not affect plan identity or
 TOML.
 
+## Document workspace orchestration
+
+`ssmdoc.py` performs read-only manifest discovery and canonical path safety checks; `source_input.py` centralizes standalone-file and `.ssmdoc` source loading; and `document_workspace.py` delegates one stable `document-0001` CompileRequest to the existing batch persistence/report path. The CLI and public package API expose `compile-document` and `compile_ssmdoc()` without shadowing the in-memory `compile_document()` compiler.
+
 <!-- archledger: no accepted records for this section yet -->
 
 # Runtime View
@@ -327,6 +341,28 @@ accepts TOML only and rejects JSON.
 RenderPlan and its matching preflight report are required together; UtterPlan does
 not calculate renderer-specific metrics.
 
+## Scenario: compile an editable SSMDDoc workspace
+
+```text
+ssmdconvert.document v1 manifest + current document.ssmd.md
+    -> utterplan compile-document
+    -> 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
@@ -338,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
@@ -347,14 +383,16 @@ 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 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 -->
 
 # Cross-cutting Concepts
@@ -484,6 +522,8 @@ drafts and never become canonical plans.
   compiled plan; replanning is a separate operation. _Rationale:_ schema evolution
   must not force package-version coupling or silent replans.
 
+- **AD: SSMDDoc is one document, not a book.** An `ssmdconvert.document` v1 workspace resolves to its current canonical SSMD source and the existing one-document compiler, producing one FlowPlan. Editable directory digests do not override current source content; UtterPlan neither refreshes nor mutates the workspace. _Rationale:_ preserve one-document/one-plan semantics and keep source-workspace ownership in `ssmdconvert`.
+
 <!-- archledger: no accepted records for this section yet -->
 
 # Quality Requirements
@@ -584,4 +624,6 @@ drafts and never become canonical plans.
 | Planning attempt | Inspect-only `utterplan.planning-attempt.v1` artifact for reviewing blocked renderability outcomes; never a canonical plan.                                                                         |
 | plan_id          | Deterministic renderer-independent plan identity; v7 `utterplan-flow-v3` includes boundaries and never hashes TOML formatting.                                                                      |
 
+| SSMDDoc | Editable single-document workspace using the `ssmdconvert.document` v1 manifest; `compile-document` compiles the current canonical SSMD file to one FlowPlan without mutating source. |
+
 <!-- archledger: no accepted records for this section yet -->

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

@@ -4,7 +4,32 @@
 
 ## [Unreleased]
 
-## [v0.6.3] - 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
+
+- Added compile-document for editable SSMDDoc workspaces with safe source loading and plan reports
+
+<!-- generated by releaseledger -->
+
+## [v0.6.3] - 2026-10-15
 
 ### Added
 

{utterplan-0.6.3 → 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:
@@ -124,6 +136,35 @@ Compile reports use format version 2. Each successful item records its resolved
 
 Shared planning options include `--language`, `--input-format auto|plain|ssmd`, `--text-preparation`, `--spacy`, and `--renderability`. `--diagnostics warnings|all|none` controls terminal detail (default `warnings`): warnings mode suppresses informational diagnostics, all includes them, and none suppresses non-failure diagnostics. Failures are always reported, and the operational report always retains complete diagnostics. Progress, selected diagnostic details, actionable errors, and final counts are written to stderr. Exit status is 0 if every input succeeds, 1 if any input fails, and 2 for usage errors such as output collisions. `--fail-fast` skips later requests after the first failure but preserves all completed outputs and updates the report.
 
+## Compile one SSMDDoc workspace
+
+`compile-document` reads a single editable `ssmdconvert.document` v1 workspace and compiles its canonical SSMD 0.9 document into one plan. It accepts the workspace root or its canonical `document.ssmd.md` path:
+
+```text
+utterplan compile-document INPUT [--output-dir PATH] [--language LANGUAGE]
+  [--text-preparation {auto,ssmd,spokenform,identity}]
+  [--renderability {strict,repair}] [--spacy {auto,off,sm,md,lg,trf}]
+  [--force] [--report PATH] [--diagnostics {warnings,all,none}]
+```
+
+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:
@@ -170,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.3 → utterplan-0.6.5}/docs/index.md

@@ -9,6 +9,7 @@ speech plans. It stops before G2P and synthesis.
 
 getting-started
 cli
+SSMDDoc workspace support <ssmdoc>
 SSMDBook and RenderPlan workflow <ssmdbook>
 consumer-guide
 format
@@ -27,4 +28,5 @@ changelog
 ```
 
 The [SSMDBook guide](ssmdbook.md) covers workspace compilation and the profile-specific `render-book` workflow, including how RenderPlan and VoiceRender fit after semantic planning.
+The [SSMDDoc guide](ssmdoc.md) covers one-document workspace compilation, source immutability, and how it differs from an SSMDBook.
 The package version and the UtterPlan schema version are independent. Schema v7 is the only version accepted by normal loading and execution. Schema-v5/v6 TOML and schemas v1–v4 remain immutable historical migration inputs; the sequential path reaches v6, while v6-to-v7 requires recompiling the original source.

{utterplan-0.6.3 → 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.3 → 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.5/docs/ssmdoc.md

@@ -0,0 +1,80 @@
+# SSMDDoc workspace support
+
+UtterPlan can compile an editable `.ssmdoc` workspace as one SSMD 0.9 document. This is a workspace input convenience around the existing one-document compiler; it is not a book format and does not create chapter plans.
+
+## Workspace contract
+
+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. 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.
+
+ZIP bundles are not supported by this workflow; use an editable directory workspace.
+
+## Compile a workspace
+
+Run `compile-document` with the workspace directory (the suffix need not be `.ssmdoc` if the manifest identifies it):
+
+```bash
+utterplan compile-document story.ssmdoc
+```
+
+It writes one plan and one operational report by default:
+
+```text
+story.ssmdoc/utterplan/
+├── document.utterplan.toml
+└── compile-report.toml
+```
+
+The report describes the single compilation and is not a FlowPlan. You can override the destination and report path:
+
+```bash
+utterplan compile-document story.ssmdoc \
+  --output-dir build/story-plan \
+  --report build/story-report.toml \
+  --language en-US \
+  --spacy off
+```
+
+Options are `--output-dir`, `--report`, `--language`/`--lang`, `--text-preparation`, `--renderability`, `--spacy`, `--diagnostics`, and `--force`. SSMD header language remains authoritative; pass `--language` as a fallback when the document has no language. Existing plan outputs are protected unless `--force` is supplied. The report may not collide with the plan, manifest, or source document. `compile-document` is a single-workspace command, so it has no chapter selector or `--fail-fast` option.
+
+The existing `compile` and `validate` commands also accept the workspace root or its canonical `document.ssmd.md` file as input. `compile` keeps its normal stdout/`-o` behavior; use `compile-document` when you want the workspace-oriented default output directory and report. `validate` compiles the source for validation without writing a plan.
+
+## Python API
+
+Use `compile_ssmdoc()` for file-backed workspace compilation. The existing `compile_document()` remains the in-memory text API:
+
+```python
+from utterplan import compile_ssmdoc
+
+result = compile_ssmdoc("story.ssmdoc", language="en-US")
+if result.failed:
+    raise RuntimeError(f"workspace compilation failed; see {result.report_path}")
+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: `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.5/tests/fixtures/ssmdoc-v1/story.ssmdoc/document.ssmd.md

@@ -0,0 +1,6 @@
+---
+ssmd_version: "0.9"
+language: en-US
+---
+
+I have [UtterPlan]{ph="utter plan"} here.

utterplan-0.6.5/tests/fixtures/ssmdoc-v1/story.ssmdoc/manifest.json

@@ -0,0 +1,21 @@
+{
+  "format": "ssmdconvert.document",
+  "schema_version": 1,
+  "ssmd_version": "0.9",
+  "metadata": {
+    "title": "UtterPlan document fixture",
+    "language": "en-US"
+  },
+  "source": {
+    "format": "markdown",
+    "media_type": "text/markdown",
+    "name": "story.md",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "document": {
+    "id": "document-0001",
+    "path": "document.ssmd.md",
+    "char_count": 87,
+    "sha256": "ed67851d91bb3d82c08020d1cdfef99102632a62dbeea46ee1793cf8fa9a49c3"
+  }
+}

{utterplan-0.6.3 → 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()