utterplan 0.6.3__tar.gz → 0.6.4__tar.gz

utterplan-0.6.4/MANIFEST.in

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utterplan
-Version: 0.6.3
+Version: 0.6.4
 Summary: Engine-independent text-to-speech planning compiler and interchange format
 Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
 License:                                  Apache License
@@ -285,6 +285,16 @@ 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/.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.
+
 Compile a selected chapter range directly from an editable SSMDBook workspace:
 
 ```bash

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

@@ -41,6 +41,16 @@ 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/.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.
+
 Compile a selected chapter range directly from an editable SSMDBook workspace:
 
 ```bash

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

@@ -1,6 +1,6 @@
 ---
 title: "Architecture Documentation"
-version: 1
+version: 2
 generator: "archledger 0.4.0"
 arc42_template_version: "9.0-EN"
 ---
@@ -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 `.readio/utterplan/`; it does not create a book or alter workspace source material.
+
 ## Requirements Overview
 
 <!-- archledger: no accepted records for this section yet -->
@@ -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,17 @@ 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 .readio/utterplan/document-0001.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.
+
 <!-- archledger: no accepted records for this section yet -->
 
 # Deployment View
@@ -355,6 +380,8 @@ or audio dependencies:
 - **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.
+
 <!-- archledger: no accepted records for this section yet -->
 
 # Cross-cutting Concepts
@@ -484,6 +511,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 +613,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.4}/docs/changelog.md

@@ -4,7 +4,15 @@
 
 ## [Unreleased]
 
-## [v0.6.3] - Unreleased
+## [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.4}/docs/cli.md

@@ -124,6 +124,21 @@ 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>/.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.
+
+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.
+
 ## 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:

{utterplan-0.6.3 → utterplan-0.6.4}/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.4/docs/ssmdoc.md

@@ -0,0 +1,64 @@
+# 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. The `.readio/utterplan/` directory is reserved for derived UtterPlan artifacts.
+
+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/.readio/utterplan/
+├── document-0001.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: `.readio/utterplan/document-0001.utterplan.toml` and `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.

utterplan-0.6.4/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.4/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.4}/tests/test_cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import io
 import json
+import shutil
 from pathlib import Path
 
 import pytest
@@ -147,6 +148,57 @@ def test_compile_auto_detects_ssmd_suffix(
     assert _payload(capsys)["document"]["format"] == "ssmd"
 
 
+def test_compile_ssmdoc_directory_matches_canonical_file(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    fixture = Path(__file__).parent / "fixtures/ssmdoc-v1/story.ssmdoc"
+    workspace = tmp_path / "story.ssmdoc"
+    shutil.copytree(fixture, workspace)
+    source = workspace / "document.ssmd.md"
+
+    assert main(["compile", str(source), "--spacy", "off"]) == 0
+    direct = FlowPlan.from_toml(capsys.readouterr().out)
+    assert main(["compile", str(workspace), "--spacy", "off"]) == 0
+    from_workspace = FlowPlan.from_toml(capsys.readouterr().out)
+
+    assert from_workspace.plan_id == direct.plan_id
+    assert from_workspace.to_dict() == direct.to_dict()
+
+
+def test_validate_accepts_dirty_ssmdoc_workspace(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    fixture = Path(__file__).parent / "fixtures/ssmdoc-v1/story.ssmdoc"
+    workspace = tmp_path / "dirty.ssmdoc"
+    shutil.copytree(fixture, workspace)
+    manifest = workspace / "manifest.json"
+    manifest_before = manifest.read_bytes()
+    source = workspace / "document.ssmd.md"
+    source.write_text(
+        '---\nssmd_version: "0.9"\nlanguage: en-US\n---\n\nEdited current document.\n',
+        encoding="utf-8",
+    )
+
+    assert main(["validate", str(workspace)]) == 0
+    captured = capsys.readouterr()
+    assert "valid" in captured.out
+    assert "input format: ssmd" in captured.out
+    assert manifest.read_bytes() == manifest_before
+    assert "Edited current document." in source.read_text(encoding="utf-8")
+
+
+def test_compile_and_validate_reject_arbitrary_directories(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    directory = tmp_path / "not-a-source"
+    directory.mkdir()
+
+    assert main(["compile", str(directory)]) == 1
+    assert "unsupported source directory" in capsys.readouterr().err
+    assert main(["validate", str(directory)]) == 1
+    assert "unsupported source directory" in capsys.readouterr().err
+
+
 def test_compile_explicit_ssmd_from_stdin(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:

utterplan-0.6.4/tests/test_cli_ssmdoc.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+import pytest
+import tomlkit
+
+from utterplan.cli import build_parser, main
+from utterplan.model import FlowPlan
+
+FIXTURE = Path(__file__).parent / "fixtures/ssmdoc-v1/story.ssmdoc"
+
+
+def _workspace(
+    tmp_path: Path, name: str = "story.ssmdoc", *, text: str = "Original content."
+) -> Path:
+    root = tmp_path / name
+    shutil.copytree(FIXTURE, root)
+    (root / "document.ssmd.md").write_text(
+        f'---\nssmd_version: "0.9"\nlanguage: en-US\n---\n\n{text}\n',
+        encoding="utf-8",
+    )
+    return root
+
+
+def _report(path: Path) -> dict[str, object]:
+    return dict(tomlkit.parse(path.read_text(encoding="utf-8")))
+
+
+def _plan_text(path: Path) -> str:
+    plan = FlowPlan.load(path)
+    return " ".join(segment.text for unit in plan.flow for segment in unit.segments)
+
+
+def test_compile_document_writes_default_layout_and_keeps_source_unchanged(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+    manifest = root / "manifest.json"
+    source = root / "document.ssmd.md"
+    manifest_before = manifest.read_bytes()
+    source_before = source.read_bytes()
+
+    result = main(
+        ["compile-document", str(root), "--text-preparation", "identity", "--spacy", "off"]
+    )
+
+    captured = capsys.readouterr()
+    output_dir = root / ".readio" / "utterplan"
+    plan_path = output_dir / "document-0001.utterplan.toml"
+    report_path = output_dir / "compile-report.toml"
+    assert result == 0
+    assert captured.out == ""
+    assert "UtterPlan document compile" in captured.err
+    assert f"source:    {source}" in captured.err
+    assert "[1/1] document-0001" in captured.err
+    assert "written:   1" in captured.err
+    assert "Original content." in _plan_text(plan_path)
+    report = _report(report_path)
+    assert report["requested"] == 1
+    assert report["written"] == 1
+    assert report["item"][0]["id"] == "document-0001"
+    assert manifest.read_bytes() == manifest_before
+    assert source.read_bytes() == source_before
+
+
+def test_compile_document_uses_manifest_not_directory_suffix(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path, "workspace")
+
+    result = main(
+        ["compile-document", str(root), "--text-preparation", "identity", "--spacy", "off"]
+    )
+
+    assert result == 0
+    capsys.readouterr()
+    assert (root / ".readio/utterplan/document-0001.utterplan.toml").is_file()
+
+
+def test_compile_document_uses_dirty_current_content_without_refreshing_manifest(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+    manifest = root / "manifest.json"
+    manifest_before = manifest.read_bytes()
+    source = root / "document.ssmd.md"
+    source.write_text(
+        '---\nssmd_version: "0.9"\nlanguage: en-US\n---\n\nEdited current content.\n',
+        encoding="utf-8",
+    )
+
+    result = main(
+        ["compile-document", str(root), "--text-preparation", "identity", "--spacy", "off"]
+    )
+
+    assert result == 0
+    capsys.readouterr()
+    assert "Edited current content." in _plan_text(
+        root / ".readio/utterplan/document-0001.utterplan.toml"
+    )
+    assert manifest.read_bytes() == manifest_before
+    assert "Edited current content." in source.read_text(encoding="utf-8")
+
+
+def test_compile_document_missing_source_is_a_reported_read_failure(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+    (root / "document.ssmd.md").unlink()
+
+    result = main(["compile-document", str(root)])
+
+    captured = capsys.readouterr()
+    report = _report(root / ".readio/utterplan/compile-report.toml")
+    assert result == 1
+    assert "FAILED" in captured.err
+    assert report["item"][0]["status"] == "failed"
+    assert report["item"][0]["stage"] == "read"
+
+
+def test_compile_document_invalid_workspace_fails_before_output_creation(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+    manifest = root / "manifest.json"
+    data = json.loads(manifest.read_text(encoding="utf-8"))
+    data["format"] = "ssmdconvert.book"
+    manifest.write_text(json.dumps(data), encoding="utf-8")
+    output_dir = tmp_path / "outside-plans"
+
+    result = main(["compile-document", str(root), "--output-dir", str(output_dir)])
+
+    captured = capsys.readouterr()
+    assert result == 2
+    assert "ssmdconvert.document" in captured.err
+    assert not output_dir.exists()
+
+
+def test_compile_document_output_and_report_overrides(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+    output_dir = tmp_path / "build" / "plans"
+    report = tmp_path / "reports" / "compile.toml"
+
+    result = main(
+        [
+            "compile-document",
+            str(root),
+            "--output-dir",
+            str(output_dir),
+            "--report",
+            str(report),
+            "--text-preparation",
+            "identity",
+            "--spacy",
+            "off",
+        ]
+    )
+
+    assert result == 0
+    captured = capsys.readouterr()
+    assert str(output_dir) in captured.err
+    assert (output_dir / "document-0001.utterplan.toml").is_file()
+    assert report.is_file()
+    assert not (root / ".readio/utterplan").exists()
+
+
+def test_compile_document_force_only_replaces_existing_plan(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+    output = root / ".readio/utterplan/document-0001.utterplan.toml"
+    output.parent.mkdir(parents=True)
+    output.write_text("sentinel", encoding="utf-8")
+    args = ["compile-document", str(root), "--text-preparation", "identity", "--spacy", "off"]
+
+    assert main(args) == 1
+    capsys.readouterr()
+    assert output.read_text(encoding="utf-8") == "sentinel"
+
+    assert main([*args, "--force"]) == 0
+    captured = capsys.readouterr()
+    assert "Original content." in _plan_text(output)
+    assert "written:   1" in captured.err
+
+
+def test_compile_document_accepts_canonical_document_file(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+
+    result = main(
+        [
+            "compile-document",
+            str(root / "document.ssmd.md"),
+            "--text-preparation",
+            "identity",
+            "--spacy",
+            "off",
+        ]
+    )
+
+    assert result == 0
+    capsys.readouterr()
+    assert (root / ".readio/utterplan/document-0001.utterplan.toml").is_file()
+
+
+def test_compile_document_uses_only_ssmd_language_or_explicit_fallback(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _workspace(tmp_path)
+    source = root / "document.ssmd.md"
+    source.write_text('---\nssmd_version: "0.9"\n---\n\nNo language.\n', encoding="utf-8")
+    args = ["compile-document", str(root), "--text-preparation", "identity", "--spacy", "off"]
+
+    assert main(args) == 1
+    capsys.readouterr()
+    item = _report(root / ".readio/utterplan/compile-report.toml")["item"][0]
+    assert item["code"] == "input.language_required"
+
+    assert main([*args, "--language", "en-US"]) == 0
+    capsys.readouterr()
+
+
+def test_compile_document_parser_exposes_only_single_document_options() -> None:
+    parser = build_parser()
+    args = parser.parse_args(
+        [
+            "compile-document",
+            "story.ssmdoc",
+            "--language",
+            "en-US",
+            "--text-preparation",
+            "identity",
+            "--renderability",
+            "strict",
+            "--spacy",
+            "off",
+            "--force",
+            "--diagnostics",
+            "none",
+        ]
+    )
+    assert args.language == "en-US"
+    assert args.text_preparation == "identity"
+    assert args.renderability == "strict"
+    assert args.spacy == "off"
+    assert args.force is True
+    assert args.diagnostics == "none"
+    assert args.output_dir is None
+    with pytest.raises(SystemExit):
+        parser.parse_args(["compile-document", "story.ssmdoc", "--chapters", "1"])
+    with pytest.raises(SystemExit):
+        parser.parse_args(["compile-document", "story.ssmdoc", "--fail-fast"])
+    with pytest.raises(SystemExit):
+        parser.parse_args(["compile-document", "story.ssmdoc", "--input-format", "ssmd"])
+
+
+def test_public_workspace_api_does_not_shadow_core_compile_document() -> None:
+    from utterplan import (
+        DocumentCompileRequest,
+        DocumentCompileResult,
+        DocumentCompileStart,
+        DocumentWorkspaceServiceError,
+        compile_document,
+        compile_ssmdoc,
+    )
+    from utterplan.compiler import compile_document as compile_document_core
+
+    assert DocumentCompileRequest is not None
+    assert DocumentCompileResult is not None
+    assert DocumentCompileStart is not None
+    assert DocumentWorkspaceServiceError is not None
+    assert callable(compile_ssmdoc)
+    assert compile_document is compile_document_core