readio 0.2.1__tar.gz → 0.2.2__tar.gz

{readio-0.2.1 → readio-0.2.2}/.codecrate.toml

@@ -9,6 +9,7 @@ include = [
   "**/*.toml",
   "**/*.rst",
   "**/*.md",
+  "**/*.ssmd",
   "**/*.json",
   "**/*.jsonl",
   "**/*.ipynb",

{readio-0.2.1 → readio-0.2.2}/.ledger/releaseledger/data/ledgers/main/events/events.jsonl

@@ -41,3 +41,17 @@
 {"data":{"updated_rows":1},"event":"audit.updated","event_id":"event-0041","record_revisions":{"commit_audit_sheet":2},"release_version":"v0.2.1","schema_version":2}
 {"data":{"entry_ids":["entry-0001"],"synced_audit_rows":1},"event":"entry.batch_added","event_id":"event-0042","record_revisions":{"commit_audit_sheet":3,"entry:v0.2.1/entry-0001":1,"release:v0.2.1":3},"release_version":"v0.2.1","schema_version":2}
 {"data":{"released_at":"2026-09-05"},"event":"release.finalized","event_id":"event-0043","record_revisions":{"release:v0.2.1":4},"release_version":"v0.2.1","schema_version":2}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0044","record_revisions":{"release:v0.2.2":1},"release_version":"v0.2.2","schema_version":2}
+{"data":{"fields":["git_base_ref","git_base_sha","git_commit_count","git_head_ref","git_head_sha","git_range"]},"event":"release.updated","event_id":"event-0045","record_revisions":{"release:v0.2.2":2},"release_version":"v0.2.2","schema_version":2}
+{"data":{"row_count":4},"event":"audit.created","event_id":"event-0046","record_revisions":{"commit_audit_sheet":1},"release_version":"v0.2.2","schema_version":2}
+{"data":{"kind":"added","status":"accepted"},"entry_id":"entry-0001","event":"entry.added","event_id":"event-0047","record_revisions":{"entry:v0.2.2/entry-0001":1,"release:v0.2.2":3},"release_version":"v0.2.2","schema_version":2}
+{"data":{"kind":"docs","status":"accepted"},"entry_id":"entry-0002","event":"entry.added","event_id":"event-0048","record_revisions":{"entry:v0.2.2/entry-0002":1,"release:v0.2.2":4},"release_version":"v0.2.2","schema_version":2}
+{"data":{"kind":"added","status":"accepted"},"entry_id":"entry-0003","event":"entry.added","event_id":"event-0049","record_revisions":{"entry:v0.2.2/entry-0003":1,"release:v0.2.2":5},"release_version":"v0.2.2","schema_version":2}
+{"data":{"kind":"changed","status":"accepted"},"entry_id":"entry-0004","event":"entry.added","event_id":"event-0050","record_revisions":{"entry:v0.2.2/entry-0004":1,"release:v0.2.2":6},"release_version":"v0.2.2","schema_version":2}
+{"data":{"released_at":"2026-09-05"},"event":"release.finalized","event_id":"event-0051","record_revisions":{"release:v0.2.2":7},"release_version":"v0.2.2","schema_version":2}
+{"data":{"updated_rows":4},"event":"audit.updated","event_id":"event-0052","record_revisions":{"commit_audit_sheet":2},"release_version":"v0.2.2","schema_version":2}
+{"data":{"fields":["git_commit_count","git_head_sha","git_range"]},"event":"release.updated","event_id":"event-0053","record_revisions":{"release:v0.2.2":8},"release_version":"v0.2.2","schema_version":2}
+{"data":{"new_rows":3,"preserved_reviewed_rows":4,"removed_rows":0},"event":"audit.updated","event_id":"event-0054","record_revisions":{"commit_audit_sheet":3},"release_version":"v0.2.2","schema_version":2}
+{"data":{"kind":"quality","status":"accepted"},"entry_id":"entry-0005","event":"entry.added","event_id":"event-0055","record_revisions":{"entry:v0.2.2/entry-0005":1,"release:v0.2.2":9},"release_version":"v0.2.2","schema_version":2}
+{"data":{"kind":"quality","status":"accepted"},"entry_id":"entry-0006","event":"entry.added","event_id":"event-0056","record_revisions":{"entry:v0.2.2/entry-0006":1,"release:v0.2.2":10},"release_version":"v0.2.2","schema_version":2}
+{"data":{"kind":"internal","status":"accepted"},"entry_id":"entry-0007","event":"entry.added","event_id":"event-0057","record_revisions":{"entry:v0.2.2/entry-0007":1,"release:v0.2.2":11},"release_version":"v0.2.2","schema_version":2}

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/audit/commit-audit.yaml

@@ -0,0 +1,213 @@
+schema_version: 1
+object_type: commit_audit_sheet
+versioning:
+  schema_version: 1
+  revision: 3
+release_version: v0.2.2
+git_base_ref: v0.2.1
+git_base_sha: 52c6084a8dfc3fbf46ac5fca8ff670cb1e97bf35
+git_head_ref: HEAD
+git_head_sha: 0302f797298f78a7f56bf85fdccd2fa977110870
+git_range: 52c6084a8dfc3fbf46ac5fca8ff670cb1e97bf35..0302f797298f78a7f56bf85fdccd2fa977110870
+commit_count: 7
+rows:
+  - sha: 5827dda1b6efda39c08b3cc38da8c6ebd867e24d
+    source_ref: git:5827dda1b6efda39c08b3cc38da8c6ebd867e24d
+    short_sha: 5827dda
+    changed_paths:
+      - .codecrate.toml
+      - README.md
+      - llm-guides/README.md
+      - llm-guides/ssmd/audio-drama.md
+      - llm-guides/ssmd/debate-pro-con.md
+      - llm-guides/ssmd/document-summary.md
+      - llm-guides/ssmd/dramatic-story.md
+      - llm-guides/ssmd/educational-explainer.md
+      - llm-guides/ssmd/funny-story.md
+      - llm-guides/ssmd/general-narration.md
+      - llm-guides/ssmd/guided-meditation.md
+      - llm-guides/ssmd/kids-story.md
+      - llm-guides/ssmd/language-learning.md
+      - llm-guides/ssmd/news-briefing.md
+      - llm-guides/ssmd/podcast-interview.md
+      - llm-guides/ssmd/podcast-roundtable.md
+      - llm-guides/ssmd/podcast-solo.md
+      - llm-guides/ssmd/quiz-trivia.md
+      - tests/test_llm_guides.py
+    stats:
+      files_changed: 0
+      insertions: 4998
+      deletions: 0
+    inspected: true
+    inspected_paths:
+      - llm-guides/README.md
+      - llm-guides/ssmd/
+    observed_behavior:
+      Added comprehensive LLM guides for SSMD audio content creation
+      covering podcasts, stories, educational content, meditation, news, and more
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: llm guides added"
+    target_entry_key: entry-0002
+    target_entry_id: entry-0002
+    notes: ""
+  - sha: 1ef0e91959f5986fed3bc6fdffcc32982649f5f5
+    source_ref: git:1ef0e91959f5986fed3bc6fdffcc32982649f5f5
+    short_sha: 1ef0e91
+    changed_paths:
+      - pyproject.toml
+      - readio/cli.py
+      - readio/models.py
+      - readio/plan.py
+      - readio/reader.py
+      - readio/ssmd.py
+      - skill/readio/SKILL.md
+      - tests/test_plan.py
+      - tests/test_plan_cli.py
+      - tests/test_plan_no_tts_load.py
+      - tests/test_pykokoro_09_contract.py
+    stats:
+      files_changed: 0
+      insertions: 2804
+      deletions: 3
+    inspected: true
+    inspected_paths:
+      - readio/plan.py
+      - tests/test_plan.py
+    observed_behavior:
+      New synthesis plan resolution system with explicit plan domain,
+      resolution pipeline, validation, and comprehensive test coverage
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: new plan feature"
+    target_entry_key: entry-0001
+    target_entry_id: entry-0001
+    notes: ""
+  - sha: 6449c24426d1f4e4d318b553b4ce2fa46b0f3c1e
+    source_ref: git:6449c24426d1f4e4d318b553b4ce2fa46b0f3c1e
+    short_sha: 6449c24
+    changed_paths:
+      - README.md
+      - docs/index.md
+      - readio/cli.py
+      - readio/plan.py
+      - readio/reader.py
+      - readio/ssmd.py
+      - skill/readio/references/cli.md
+      - skill/readio/references/ssmd.md
+      - skill/readio/references/troubleshooting.md
+      - tests/test_cli.py
+      - tests/test_plan.py
+      - tests/test_plan_cli.py
+      - tests/test_plan_no_tts_load.py
+      - tests/test_plan_validation.py
+      - tests/test_render_from_plan.py
+      - tests/test_ssmd_single_source.py
+    stats:
+      files_changed: 0
+      insertions: 1428
+      deletions: 335
+    inspected: true
+    inspected_paths:
+      - readio/cli.py
+      - readio/plan.py
+    observed_behavior: Improved plan feature with enhanced CLI commands and validation
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: improve plan feature"
+    target_entry_key: entry-0004
+    target_entry_id: entry-0004
+    notes: ""
+  - sha: 33b44019d3d4899a551a6e621e8a78189bf52b60
+    source_ref: git:33b44019d3d4899a551a6e621e8a78189bf52b60
+    short_sha: 33b4401
+    changed_paths:
+      - README.md
+      - docs/index.md
+      - readio/cli.py
+      - readio/errors.py
+      - readio/jsonutil.py
+      - readio/manifest.py
+      - readio/plan.py
+      - skill/readio/SKILL.md
+      - skill/readio/references/cli.md
+      - skill/readio/references/troubleshooting.md
+      - tests/test_manifest.py
+      - tests/test_render_manifest_cli.py
+    stats:
+      files_changed: 0
+      insertions: 719
+      deletions: 22
+    inspected: true
+    inspected_paths:
+      - readio/manifest.py
+      - tests/test_manifest.py
+    observed_behavior:
+      Added manifest module for project metadata and package information
+      management
+    public_impact: public
+    decision: accepted
+    stale: false
+    evidence_subject: "feat: add manifest"
+    target_entry_key: entry-0003
+    target_entry_id: entry-0003
+    notes: ""
+  - sha: 9ec43c0c70d5badaf282547142af78fe9e986ca4
+    source_ref: git:9ec43c0c70d5badaf282547142af78fe9e986ca4
+    short_sha: 9ec43c0
+    changed_paths:
+      - .ledger/releaseledger/data/ledgers/main/events/events.jsonl
+      - .ledger/releaseledger/data/ledgers/main/releases/v0.2.2/audit/commit-audit.yaml
+      - .ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0001.md
+      - .ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0002.md
+      - .ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0003.md
+      - .ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0004.md
+      - .ledger/releaseledger/data/ledgers/main/releases/v0.2.2/release.md
+      - CHANGELOG.md
+    stats:
+      files_changed: 0
+      insertions: 315
+      deletions: 0
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "doc: changelog"
+  - sha: 6656cdd980d30a65d403961909d5e911e3e81dbc
+    source_ref: git:6656cdd980d30a65d403961909d5e911e3e81dbc
+    short_sha: 6656cdd
+    changed_paths:
+      - tests/test_plan_no_tts_load.py
+    stats:
+      files_changed: 0
+      insertions: 2
+      deletions: 0
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "fix: pytest"
+  - sha: 0302f797298f78a7f56bf85fdccd2fa977110870
+    source_ref: git:0302f797298f78a7f56bf85fdccd2fa977110870
+    short_sha: 0302f79
+    changed_paths:
+      - readio/jsonutil.py
+      - tests/test_plan_no_tts_load.py
+    stats:
+      files_changed: 0
+      insertions: 3
+      deletions: 2
+    inspected: false
+    inspected_paths: []
+    observed_behavior: ""
+    public_impact: unknown
+    decision: needs_review
+    stale: false
+    evidence_subject: "chore: pytest and pre-commit fix"

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0001.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: v0.2.2
+kind: added
+summary:
+  Added synthesis plan resolution system with explicit plan domain, resolution
+  pipeline, and validation
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:1ef0e91959f5986fed3bc6fdffcc32982649f5f5
+paths:
+  - readio/plan.py
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 1
+---

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0002.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0002
+release_version: v0.2.2
+kind: docs
+summary:
+  Added comprehensive LLM guides for SSMD audio content creation including
+  podcasts, stories, educational content, and more
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:5827dda1b6efda39c08b3cc38da8c6ebd867e24d
+paths:
+  - llm-guides/README.md
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 2
+---

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0003.md

@@ -0,0 +1,25 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0003
+release_version: v0.2.2
+kind: added
+summary: Added manifest module for project metadata and package information management
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:33b44019d3d4899a551a6e621e8a78189bf52b60
+paths:
+  - readio/manifest.py
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 3
+---

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0004.md

@@ -0,0 +1,25 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0004
+release_version: v0.2.2
+kind: changed
+summary: Improved plan feature with enhanced CLI commands and validation
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:6449c24426d1f4e4d318b553b4ce2fa46b0f3c1e
+paths:
+  - readio/cli.py
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 4
+---

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0005.md

@@ -0,0 +1,26 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0005
+release_version: v0.2.2
+kind: quality
+summary: Fixed pytest and pre-commit configuration for plan feature tests
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:0302f797298f78a7f56bf85fdccd2fa977110870
+paths:
+  - readio/jsonutil.py
+  - tests/test_plan_no_tts_load.py
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: true
+order: 5
+---

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0006.md

@@ -0,0 +1,25 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0006
+release_version: v0.2.2
+kind: quality
+summary: Fixed pytest test setup for plan feature without TTS dependency
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:6656cdd980d30a65d403961909d5e911e3e81dbc
+paths:
+  - tests/test_plan_no_tts_load.py
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: true
+order: 6
+---

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/entries/entry-0007.md

@@ -0,0 +1,24 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0007
+release_version: v0.2.2
+kind: internal
+summary: Initialized releaseledger state and changelog for v0.2.2
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - git:9ec43c0c70d5badaf282547142af78fe9e986ca4
+paths: []
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: true
+order: 7
+---

readio-0.2.2/.ledger/releaseledger/data/ledgers/main/releases/v0.2.2/release.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release
+versioning:
+  schema_version: 1
+  revision: 11
+version: v0.2.2
+status: released
+history_state: curated
+title: Readio v0.2.2
+released_at: "2026-09-05"
+previous_version: v0.2.1
+cancel_reason: null
+superseded_by: null
+changelog_file: null
+boundary_ref: null
+source_refs: []
+source_count: null
+entry_count: 7
+artifact_count: 0
+git_base_ref: v0.2.1
+git_base_sha: 52c6084a8dfc3fbf46ac5fca8ff670cb1e97bf35
+git_head_ref: HEAD
+git_head_sha: 0302f797298f78a7f56bf85fdccd2fa977110870
+git_range: 52c6084a8dfc3fbf46ac5fca8ff670cb1e97bf35..0302f797298f78a7f56bf85fdccd2fa977110870
+git_commit_count: 7
+---

readio-0.2.2/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [v0.2.2] - 2026-09-05
+
+### Added
+
+- Added synthesis plan resolution system with explicit plan domain, resolution pipeline, and validation
+- Added manifest module for project metadata and package information management
+
+### Changed
+
+- Improved plan feature with enhanced CLI commands and validation
+
+### Documentation
+
+- Added comprehensive LLM guides for SSMD audio content creation including podcasts, stories, educational content, and more
+
+<!-- generated by releaseledger -->

{readio-0.2.1/readio.egg-info → readio-0.2.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: readio
-Version: 0.2.1
+Version: 0.2.2
 Summary: Read text aloud in the terminal with streaming TTS and an Agent Skill for LLM invocation
 License: Apache-2.0
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pykokoro[playback]<0.10,>=0.9.0
+Requires-Dist: pykokoro[playback]<0.10,>=0.9.1
 Requires-Dist: platformdirs>=4.0
 Requires-Dist: soundfile>=0.12
 Requires-Dist: tomli>=2.0; python_version < "3.11"
@@ -143,6 +143,14 @@ draft="$(readio template use podcast)"
 
 The returned path is under the configured ingest directory. A caller can request a filename with `readio template use podcast --name weekly-review.ssmd`.
 
+## Standalone LLM authoring guides
+
+`llm-guides/ssmd/` contains standalone Markdown instructions for generic LLMs. These guides are distinct from the runtime `.ssmd` templates managed by `readio template`.
+
+No Readio or Python installation is needed on the authoring system: choose one guide and attach it with the task and source material. When the harness supports artifacts, ask it to create and return one downloadable `.ssmd` file; otherwise save the raw SSMD response as a file. Rendering and final validation happen later on a system where Readio is installed.
+
+See [`llm-guides/README.md`](llm-guides/README.md) for the catalog and the authoring-to-rendering workflow.
+
 ## Ingest directory
 
 The ingest directory stores text, Markdown, and SSMD files created for later processing.
@@ -157,6 +165,81 @@ readio ingest list
 
 Automatic names contain a UTC artifact ID such as `20260824T111423Z-5f8ab31c`. Explicit names are relative to the ingest directory and path traversal is rejected.
 
+## Planning before rendering
+
+Every non-live render resolves one explicit synthesis plan before any TTS work. `readio plan` and `readio render --dry-run` display that plan without loading a model, and a normal `render` executes exactly the plan it resolved — the plan is the execution contract, not a prediction:
+
+```bash
+readio plan --file episode.ssmd --format mp3 --json
+readio render --file episode.ssmd --dry-run          # same plan, human output
+readio render --file episode.ssmd                    # resolves the same plan, then executes it
+```
+
+Planning, discovery, defaults, and render results are distinct layers:
+
+- **`readio models` / `readio voices` (discovery)** list what the installed PyKokoro runtime _could_ provide — model IDs, languages, voices, qualities, lexicons, status.
+- **`readio defaults` (defaults)** persist validated per-language policy that resolution _prefers_.
+- **`readio plan` (planning)** resolves one concrete request against config, defaults, CLI options, and PyKokoro's automatic selection: a concrete model, source, quality, voice, SSMD cast, and output allocation, with provenance for every effective value. No TTS model is loaded.
+- **`readio render` (render result)** executes the plan; the plan JSON's synthesis, SSMD bindings, and output path are the values actually used. A render that fails planning exits 1 with the plan and its diagnostics instead of loading TTS.
+
+`readio.plan.v1` JSON exposes `schema`, `ok`, `input`, `synthesis` (with `model` capability metadata), `ssmd` bindings, `output` (format, encoder backend, path, path origin, `force`), `environment` (including `ffmpeg_available`), `decisions` (winning source per field), and `diagnostics`:
+
+```json
+{
+  "schema": "readio.plan.v1",
+  "ok": true,
+  "operation": "render",
+  "synthesis": {
+    "engine": "pykokoro",
+    "language": "de",
+    "model": {
+      "id": "de-thorsten",
+      "source": "github",
+      "quality": "fp32",
+      "voice": "thorsten",
+      "status": "ready",
+      "runtime_available": true,
+      "languages": ["de"],
+      "experimental": false
+    }
+  },
+  "ssmd": { "enabled": false, "bindings": [], "unresolved": [] },
+  "output": {
+    "mode": "file",
+    "format": "mp3",
+    "encoder_backend": "soundfile",
+    "path": ".../episode.mp3",
+    "path_origin": "explicit",
+    "force": false
+  },
+  "decisions": [
+    {
+      "field": "synthesis.model",
+      "value": "de-thorsten",
+      "origin": "cli",
+      "locator": "request.model"
+    }
+  ],
+  "diagnostics": []
+}
+```
+
+Plans are deterministic and non-interactive: `--resolve-voices` is rejected by `plan` and `--dry-run`; use repeatable `--voice-bind ROLE=VOICE_ID` options or persisted role configuration instead. `plan` accepts `--force` so it can represent every render output request, and an invalid plan (incompatible model/language, unavailable runtime, unresolved SSMD cast, unavailable encoder, non-concrete synthesis) fails before model loading.
+
+## Durable render manifests
+
+For bounded renders that will be reused, published, compared, or handed to another agent, request an opt-in post-render manifest:
+
+```bash
+readio plan --file episode.ssmd --format mp3 --json
+readio render --file episode.ssmd --format mp3 --manifest
+readio render --file episode.ssmd --format mp3 --manifest --json
+```
+
+A successful render writes the audio and a colocated `<audio>.readio.json` sidecar. The sidecar uses schema `readio.render-manifest.v1` and records the exact executed `readio.plan.v1`, its canonical SHA-256, the final encoded audio hash and byte count, render summary facts, document metadata, and final marker offsets. The plan is pre-execution intent; the manifest is post-execution evidence.
+
+Human stdout remains only the audio path. JSON render output remains one object and adds `manifest` with the sidecar schema and path, or `null` when the flag is absent. `--manifest` is available only for bounded rendering, not `--live`, `speak`, planning, dry runs, or publishing. If sidecar writing fails, Readio preserves the committed audio and returns `render.manifest_error`.
+
 ## Multi-format audio output
 
 The output path is optional and WAV remains the default: