readio 0.2.2__tar.gz → 0.2.3__tar.gz

{readio-0.2.2 → readio-0.2.3}/.github/workflows/codecov.yml

@@ -16,8 +16,7 @@ jobs:
           cache: pip
       - name: Install Readio runtime dependencies
         run: |
-          python -m pip install "ssmd @ git+https://github.com/buchwandler/ssmd.git@631aa5a03ba2b2fcb364272843f88a8738d36484"
-          python -m pip install "pykokoro[playback] @ git+https://github.com/buchwandler/pykokoro.git@07fdd07f4cccff7ab58bbe1f5c801bebe8b41a85"
+          python -m pip install "pykokoro[playback]==0.9.4"
       - name: Install project and coverage tools
         run: |
           python -m pip install --upgrade pip

readio-0.2.3/.github/workflows/python-publish.yml

@@ -0,0 +1,49 @@
+# Build and publish Readio when a GitHub Release is published.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out release
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+      - name: Build package
+        run: python -m build
+      - name: Validate artifact metadata
+        run: python -m twine check dist/*
+      - name: Validate release version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          from packaging.utils import parse_wheel_filename
+
+          expected = os.environ["RELEASE_TAG"].removeprefix("v")
+          wheels = list(Path("dist").glob("*.whl"))
+          assert len(wheels) == 1, f"expected one wheel, found {len(wheels)}"
+          _, version, _, _ = parse_wheel_filename(wheels[0].name)
+          assert str(version) == expected, (
+              f"wheel version {version} does not match release tag {expected}"
+          )
+          PY
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          attestations: false

{readio-0.2.2 → readio-0.2.3}/.github/workflows/tests.yml

@@ -25,8 +25,7 @@ jobs:
           cache: pip
       - name: Install Readio runtime dependencies
         run: |
-          python -m pip install "ssmd @ git+https://github.com/buchwandler/ssmd.git@631aa5a03ba2b2fcb364272843f88a8738d36484"
-          python -m pip install "pykokoro[playback] @ git+https://github.com/buchwandler/pykokoro.git@07fdd07f4cccff7ab58bbe1f5c801bebe8b41a85"
+          python -m pip install "pykokoro[playback]==0.9.4"
       - name: Install project and test tools
         run: |
           python -m pip install --upgrade pip
@@ -34,6 +33,27 @@ jobs:
       - name: Run test suite
         run: python -m pytest -q
 
+
+  minimum-compatibility:
+    name: Minimum PyKokoro compatibility (Ubuntu, Python 3.10)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install PortAudio
+        run: sudo apt-get update && sudo apt-get install --yes portaudio19-dev
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: pip
+      - name: Install minimum PyKokoro runtime
+        run: python -m pip install "pykokoro[playback]==0.9.4"
+      - name: Install project and test tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Run minimum-version test suite
+        run: python -m pytest -q
   quality:
     name: Static quality checks
     runs-on: ubuntu-latest
@@ -48,8 +68,7 @@ jobs:
           cache: pip
       - name: Install Readio runtime dependencies
         run: |
-          python -m pip install "ssmd @ git+https://github.com/buchwandler/ssmd.git@631aa5a03ba2b2fcb364272843f88a8738d36484"
-          python -m pip install "pykokoro[playback] @ git+https://github.com/buchwandler/pykokoro.git@07fdd07f4cccff7ab58bbe1f5c801bebe8b41a85"
+          python -m pip install "pykokoro[playback]==0.9.4"
       - name: Install development tools
         run: python -m pip install -e ".[dev]"
       - name: Ruff lint
@@ -81,9 +100,9 @@ jobs:
         shell: bash
         run: |
           python -m venv "${RUNNER_TEMP}/readio-wheel-smoke"
-          "${RUNNER_TEMP}/readio-wheel-smoke/bin/python" -m pip install "ssmd @ git+https://github.com/buchwandler/ssmd.git@631aa5a03ba2b2fcb364272843f88a8738d36484"
-          "${RUNNER_TEMP}/readio-wheel-smoke/bin/python" -m pip install "pykokoro[playback] @ git+https://github.com/buchwandler/pykokoro.git@07fdd07f4cccff7ab58bbe1f5c801bebe8b41a85"
+          "${RUNNER_TEMP}/readio-wheel-smoke/bin/python" -m pip install "pykokoro[playback]==0.9.4"
           "${RUNNER_TEMP}/readio-wheel-smoke/bin/python" -m pip install dist/*.whl
+          "${RUNNER_TEMP}/readio-wheel-smoke/bin/python" -m pip check
           cd "${RUNNER_TEMP}"
           "${RUNNER_TEMP}/readio-wheel-smoke/bin/python" - <<'PY'
           import importlib.metadata

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

@@ -55,3 +55,8 @@
 {"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}
+{"data":{"status":"planned"},"event":"release.created","event_id":"event-0058","record_revisions":{"release:v0.2.3":1},"release_version":"v0.2.3","schema_version":2}
+{"data":{"kind":"changed","status":"accepted"},"entry_id":"entry-0001","event":"entry.added","event_id":"event-0059","record_revisions":{"entry:v0.2.3/entry-0001":1,"release:v0.2.3":2},"release_version":"v0.2.3","schema_version":2}
+{"data":{"kind":"quality","status":"accepted"},"entry_id":"entry-0002","event":"entry.added","event_id":"event-0060","record_revisions":{"entry:v0.2.3/entry-0002":1,"release:v0.2.3":3},"release_version":"v0.2.3","schema_version":2}
+{"data":{"kind":"changed","status":"accepted"},"entry_id":"entry-0003","event":"entry.added","event_id":"event-0061","record_revisions":{"entry:v0.2.3/entry-0003":1,"release:v0.2.3":4},"release_version":"v0.2.3","schema_version":2}
+{"data":{"kind":"docs","status":"accepted"},"entry_id":"entry-0004","event":"entry.added","event_id":"event-0062","record_revisions":{"entry:v0.2.3/entry-0004":1,"release:v0.2.3":5},"release_version":"v0.2.3","schema_version":2}

readio-0.2.3/.ledger/releaseledger/data/ledgers/main/releases/v0.2.3/entries/entry-0001.md

@@ -0,0 +1,29 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0001
+release_version: v0.2.3
+kind: changed
+summary:
+  Aligned Readio dependency metadata and CI with released PyKokoro 0.9.4 and
+  SSMD 0.8.7+
+status: accepted
+audience: null
+scopes: []
+source_refs:
+  - tl:task-0019
+paths:
+  - pyproject.toml
+  - .github/workflows/tests.yml
+  - .github/workflows/codecov.yml
+issues: []
+prs: []
+sources: []
+contributors: []
+breaking: false
+internal: false
+order: 1
+---

readio-0.2.3/.ledger/releaseledger/data/ledgers/main/releases/v0.2.3/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.3
+kind: quality
+summary: Added bounded PyKokoro compatibility and package metadata regression coverage
+status: accepted
+audience: null
+scopes: []
+source_refs: []
+paths:
+  - tests/test_pykokoro_09_contract.py
+  - tests/test_pykokoro_09_support.py
+  - tests/test_packaging_metadata.py
+issues: []
+prs: []
+sources:
+  - tl:task-0019
+contributors: []
+breaking: false
+internal: false
+order: 2
+---

readio-0.2.3/.ledger/releaseledger/data/ledgers/main/releases/v0.2.3/entries/entry-0003.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0003
+release_version: v0.2.3
+kind: changed
+summary:
+  Hardened package publishing with artifact checks and release-tag version
+  validation
+status: accepted
+audience: null
+scopes: []
+source_refs: []
+paths:
+  - .github/workflows/python-publish.yml
+issues: []
+prs: []
+sources:
+  - tl:task-0019
+contributors: []
+breaking: false
+internal: false
+order: 3
+---

readio-0.2.3/.ledger/releaseledger/data/ledgers/main/releases/v0.2.3/entries/entry-0004.md

@@ -0,0 +1,30 @@
+---
+schema_version: 2
+object_type: release_entry
+versioning:
+  schema_version: 1
+  revision: 1
+entry_id: entry-0004
+release_version: v0.2.3
+kind: docs
+summary:
+  Documented the PyKokoro support floor, 0.9.4 tested target, and supported
+  SSMD API
+status: accepted
+audience: null
+scopes: []
+source_refs: []
+paths:
+  - README.md
+  - docs/index.md
+  - skill/readio/SKILL.md
+  - llm-guides
+issues: []
+prs: []
+sources:
+  - tl:task-0019
+contributors: []
+breaking: false
+internal: false
+order: 4
+---

readio-0.2.3/.ledger/releaseledger/data/ledgers/main/releases/v0.2.3/release.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+object_type: release
+versioning:
+  schema_version: 1
+  revision: 5
+version: v0.2.3
+status: planned
+history_state: curated
+title: Readio v0.2.3
+released_at: null
+previous_version: v0.2.2
+cancel_reason: null
+superseded_by: null
+changelog_file: null
+boundary_ref: null
+source_refs: []
+source_count: null
+entry_count: 4
+artifact_count: 0
+git_base_ref: null
+git_base_sha: null
+git_head_ref: null
+git_head_sha: null
+git_range: null
+git_commit_count: null
+---

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

@@ -1,19 +1,19 @@
 Metadata-Version: 2.4
 Name: readio
-Version: 0.2.2
+Version: 0.2.3
 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.1
+Requires-Dist: pykokoro[playback]<0.10,>=0.9.2
 Requires-Dist: platformdirs>=4.0
 Requires-Dist: soundfile>=0.12
 Requires-Dist: tomli>=2.0; python_version < "3.11"
 Requires-Dist: typing_extensions>=4.0
 Requires-Dist: tomli-w>=1.0
 Requires-Dist: PyYAML>=6.0
-Requires-Dist: ssmd<0.9,>=0.8.6
+Requires-Dist: ssmd<0.9,>=0.8.7
 Requires-Dist: markdown-it-py<5.0,>=3.0
 Requires-Dist: mdit-py-plugins<1.0,>=0.4
 Provides-Extra: cpu
@@ -95,7 +95,8 @@ The configuration contains reader settings, SSMD defaults, provider-specific voi
 
 ### Model discovery and language defaults
 
-PyKokoro 0.9.x is the runtime contract and owns the model, language, voice, quality, frontend, and named-lexicon catalog. Discovery is metadata-only and does not download model weights:
+PyKokoro >=0.9.2,<0.10 is the runtime contract and owns the model, language, voice, quality, frontend, and named-lexicon catalog. Discovery is metadata-only and does not download model weights:
+Readio v0.2.3 is tested against PyKokoro 0.9.4.
 
 ```bash
 readio models list --language de --offline
@@ -116,11 +117,30 @@ readio defaults show de-at --json
 readio render --lang de --file notes.md
 ```
 
-When a model is selected, Readio fills its normalized source, default voice, and preferred quality, then validates language compatibility, voice roster, quality, named lexicons, and experimental frontend permission before saving. `--no-lexicons` clears an inherited explicit selection. Repeat `--lexicon` to preserve ordered layered lookup.
+When a model is selected, Readio fills its normalized source, default voice, and preferred quality, then validates language compatibility, voice roster, quality, named lexicons, and experimental frontend permission before saving. `--no-lexicons` selects explicit provider-only pronunciation (`lexicons=[]`); `--auto-lexicons` returns to PyKokoro language defaults (`lexicons=null`). Repeat `--lexicon` to preserve ordered layered lookup.
 
-Direct `speak`, `render`, and `spotify publish` options (`--model`, `--model-source`, `--quality`, repeatable `--lexicon`, `--no-lexicons`, and `--allow-experimental`) override persisted defaults. Use `--json` for automation; JSON preserves unknown lexicon capability as `null` rather than an empty list.
+Direct `speak`, `render`, and `spotify publish` options (`--model`, `--model-source`, `--quality`, repeatable `--lexicon`, `--no-lexicons`, `--auto-lexicons`, `--g2p-fallback`, `--lexicon-data-policy`, `--language-detection`, and repeatable `--detect-language`) override persisted defaults. Use `--json` for automation; JSON preserves `null` versus `[]` for lexicon selection.
 `--model-source github|huggingface` selects the same distribution for discovery, validation, and runtime construction. Voices are model-scoped: the legacy global `reader.voice` is retained only for unchanged default-reader use; `--lang de` without a voice leaves PyKokoro free to choose the German model default.
 
+Named lexicons use PyKokoro selectors, not backend asset IDs:
+
+```text
+crane          = named selection token
+de-de:crane    = language-qualified Lexphon asset resolved downstream
+de-crane       = separate acoustic model ID
+```
+
+For reproducible German synthesis:
+
+```bash
+readio models show de-thorsten
+readio defaults set de --model de-thorsten --lexicon crane --g2p-fallback espeak --lexicon-data-policy auto
+readio plan --file article.md --lang de --json
+readio render --file article.md --lang de --model de-thorsten --no-lexicons --g2p-fallback espeak --format mp3
+```
+
+The plan also records optional PyKokoro language detection. SSMD documents may use `language_detection: {mode: auto, languages: [de, en]}`; this routes pronunciation fragments while retaining the selected acoustic language.
+
 ## Templates
 
 Built-in templates are copied into the user template directory during initialization. They are user-owned and are not overwritten by normal initialization or package upgrades.
@@ -265,13 +285,25 @@ readio --json spotify status spotify:episode:abc --wait
 ```
 
 Progress includes the current phase, completed units, elapsed time, approximate ETA for bounded renders, generated audio duration, and finalization. Live renders show cumulative units without a percentage or ETA. `--json` keeps stdout to one result object; automatic progress is disabled in JSON mode, while explicit `--progress` remains stderr-only.
+
+## Verbose diagnostics
+
+Use the global repeatable verbosity option for live operational diagnostics:
+
+```bash
+readio -v speak "Hello"
+readio -vv render episode.ssmd -o episode.mp3
+readio speak "literal --verbose" --
+```
+
+`-v` shows timestamped lifecycle records at INFO level. `-vv` enables DEBUG-level Readio and PyKokoro details; additional repetitions are clamped to DEBUG. Verbose records always go to stderr, so ordinary output and `--json` results remain on stdout and stay machine-parseable. `--progress` is a separate user-facing progress control. When verbose mode and progress are combined, progress uses line-oriented stderr records instead of in-place terminal rewriting. Logs can contain paths and model or voice identifiers, so review them before sharing and never treat verbose mode as permission to expose document text, audio, or credentials.
 When `-o` is supplied, its `.wav`, `.mp3`, `.m4a`, or `.ogg` suffix selects the encoder. Use `--format` when the output path is omitted or to select the automatic filename suffix. An explicit format and suffix must agree. Extensionless output paths receive the selected suffix, and unsupported suffixes fail before synthesis. Automatic names use the configured output directory and never overwrite an existing file. Explicit output remains atomic and requires `--force` for replacement.
 
 M4A output requires an `ffmpeg` executable on `PATH`. WAV uses PCM16, while MP3 and OGG use the installed SoundFile/libsndfile codecs.
 
 ## SSMD consumption and authoring checks
 
-For `.ssmd` inputs, Readio parses the document through SSMD 0.8.6 and passes a PyKokoro 0.9 `SSMDRenderConfig` containing only missing Readio role defaults. Document `voice_bindings` remain authoritative, invocation `--voice-bind` values override configured provider roles, and concrete targets must belong to the active model roster. Normal `speak`, `render`, and `spotify` commands do not invoke `ssmd create`, rewrite the source, or require generic round-trip validation.
+For `.ssmd` inputs, Readio parses the document through the supported SSMD 0.8.x API and passes a PyKokoro 0.9 `SSMDRenderConfig` containing only missing Readio role defaults. Document `voice_bindings` remain authoritative, invocation `--voice-bind` values override configured provider roles, and concrete targets must belong to the active model roster. Normal `speak`, `render`, and `spotify` commands do not invoke `ssmd create`, rewrite the source, or require generic round-trip validation.
 
 Inspect a document before rendering:
 

{readio-0.2.2 → readio-0.2.3}/README.md

@@ -68,7 +68,8 @@ The configuration contains reader settings, SSMD defaults, provider-specific voi
 
 ### Model discovery and language defaults
 
-PyKokoro 0.9.x is the runtime contract and owns the model, language, voice, quality, frontend, and named-lexicon catalog. Discovery is metadata-only and does not download model weights:
+PyKokoro >=0.9.2,<0.10 is the runtime contract and owns the model, language, voice, quality, frontend, and named-lexicon catalog. Discovery is metadata-only and does not download model weights:
+Readio v0.2.3 is tested against PyKokoro 0.9.4.
 
 ```bash
 readio models list --language de --offline
@@ -89,11 +90,30 @@ readio defaults show de-at --json
 readio render --lang de --file notes.md
 ```
 
-When a model is selected, Readio fills its normalized source, default voice, and preferred quality, then validates language compatibility, voice roster, quality, named lexicons, and experimental frontend permission before saving. `--no-lexicons` clears an inherited explicit selection. Repeat `--lexicon` to preserve ordered layered lookup.
+When a model is selected, Readio fills its normalized source, default voice, and preferred quality, then validates language compatibility, voice roster, quality, named lexicons, and experimental frontend permission before saving. `--no-lexicons` selects explicit provider-only pronunciation (`lexicons=[]`); `--auto-lexicons` returns to PyKokoro language defaults (`lexicons=null`). Repeat `--lexicon` to preserve ordered layered lookup.
 
-Direct `speak`, `render`, and `spotify publish` options (`--model`, `--model-source`, `--quality`, repeatable `--lexicon`, `--no-lexicons`, and `--allow-experimental`) override persisted defaults. Use `--json` for automation; JSON preserves unknown lexicon capability as `null` rather than an empty list.
+Direct `speak`, `render`, and `spotify publish` options (`--model`, `--model-source`, `--quality`, repeatable `--lexicon`, `--no-lexicons`, `--auto-lexicons`, `--g2p-fallback`, `--lexicon-data-policy`, `--language-detection`, and repeatable `--detect-language`) override persisted defaults. Use `--json` for automation; JSON preserves `null` versus `[]` for lexicon selection.
 `--model-source github|huggingface` selects the same distribution for discovery, validation, and runtime construction. Voices are model-scoped: the legacy global `reader.voice` is retained only for unchanged default-reader use; `--lang de` without a voice leaves PyKokoro free to choose the German model default.
 
+Named lexicons use PyKokoro selectors, not backend asset IDs:
+
+```text
+crane          = named selection token
+de-de:crane    = language-qualified Lexphon asset resolved downstream
+de-crane       = separate acoustic model ID
+```
+
+For reproducible German synthesis:
+
+```bash
+readio models show de-thorsten
+readio defaults set de --model de-thorsten --lexicon crane --g2p-fallback espeak --lexicon-data-policy auto
+readio plan --file article.md --lang de --json
+readio render --file article.md --lang de --model de-thorsten --no-lexicons --g2p-fallback espeak --format mp3
+```
+
+The plan also records optional PyKokoro language detection. SSMD documents may use `language_detection: {mode: auto, languages: [de, en]}`; this routes pronunciation fragments while retaining the selected acoustic language.
+
 ## Templates
 
 Built-in templates are copied into the user template directory during initialization. They are user-owned and are not overwritten by normal initialization or package upgrades.
@@ -238,13 +258,25 @@ readio --json spotify status spotify:episode:abc --wait
 ```
 
 Progress includes the current phase, completed units, elapsed time, approximate ETA for bounded renders, generated audio duration, and finalization. Live renders show cumulative units without a percentage or ETA. `--json` keeps stdout to one result object; automatic progress is disabled in JSON mode, while explicit `--progress` remains stderr-only.
+
+## Verbose diagnostics
+
+Use the global repeatable verbosity option for live operational diagnostics:
+
+```bash
+readio -v speak "Hello"
+readio -vv render episode.ssmd -o episode.mp3
+readio speak "literal --verbose" --
+```
+
+`-v` shows timestamped lifecycle records at INFO level. `-vv` enables DEBUG-level Readio and PyKokoro details; additional repetitions are clamped to DEBUG. Verbose records always go to stderr, so ordinary output and `--json` results remain on stdout and stay machine-parseable. `--progress` is a separate user-facing progress control. When verbose mode and progress are combined, progress uses line-oriented stderr records instead of in-place terminal rewriting. Logs can contain paths and model or voice identifiers, so review them before sharing and never treat verbose mode as permission to expose document text, audio, or credentials.
 When `-o` is supplied, its `.wav`, `.mp3`, `.m4a`, or `.ogg` suffix selects the encoder. Use `--format` when the output path is omitted or to select the automatic filename suffix. An explicit format and suffix must agree. Extensionless output paths receive the selected suffix, and unsupported suffixes fail before synthesis. Automatic names use the configured output directory and never overwrite an existing file. Explicit output remains atomic and requires `--force` for replacement.
 
 M4A output requires an `ffmpeg` executable on `PATH`. WAV uses PCM16, while MP3 and OGG use the installed SoundFile/libsndfile codecs.
 
 ## SSMD consumption and authoring checks
 
-For `.ssmd` inputs, Readio parses the document through SSMD 0.8.6 and passes a PyKokoro 0.9 `SSMDRenderConfig` containing only missing Readio role defaults. Document `voice_bindings` remain authoritative, invocation `--voice-bind` values override configured provider roles, and concrete targets must belong to the active model roster. Normal `speak`, `render`, and `spotify` commands do not invoke `ssmd create`, rewrite the source, or require generic round-trip validation.
+For `.ssmd` inputs, Readio parses the document through the supported SSMD 0.8.x API and passes a PyKokoro 0.9 `SSMDRenderConfig` containing only missing Readio role defaults. Document `voice_bindings` remain authoritative, invocation `--voice-bind` values override configured provider roles, and concrete targets must belong to the active model roster. Normal `speak`, `render`, and `spotify` commands do not invoke `ssmd create`, rewrite the source, or require generic round-trip validation.
 
 Inspect a document before rendering:
 

{readio-0.2.2 → readio-0.2.3}/docs/changelog.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## Unreleased
+> **Generated by releaseledger.** Manual edits may be overwritten. Update releaseledger entries and rebuild this file instead.
+
+## [v0.2.3] - 2026-09-11
+
+### Changed
+
+- Aligned Readio dependency metadata and CI with released PyKokoro 0.9.4 and SSMD 0.8.7+
+- Hardened package publishing with artifact checks and release-tag version validation
+
+### Documentation
+
+- Documented the PyKokoro support floor, 0.9.4 tested target, and supported SSMD API
+
+### Quality
+
+- Added bounded PyKokoro compatibility and package metadata regression coverage
+
+<!-- generated by releaseledger -->
 
 ## [v0.2.2] - 2026-09-05
 
@@ -85,3 +102,5 @@
 - Added cross-platform CI, pre-commit, coverage, package publishing checks, and a podcast example
 
 <!-- generated by releaseledger -->
+
+<!-- releaseledger:generated-file -->

{readio-0.2.2 → readio-0.2.3}/docs/index.md

@@ -80,12 +80,19 @@ Synthesis options are available on all three commands:
 ```text
 --voice VOICE       PyKokoro voice ID
 --lang LANGUAGE     language code, such as en-us
+--lexicon NAME     named PyKokoro lexicon; repeat for ordered layers
+--no-lexicons      explicit provider-only pronunciation
+--auto-lexicons    restore automatic language-default lexicons
+--g2p-fallback MODE none, espeak, or goruut
+--lexicon-data-policy POLICY auto or installed-only
+--language-detection MODE off or auto
+--detect-language LANG repeatable pronunciation-routing language
 --speed NUMBER      speech speed multiplier
 --pause-mode MODE   tts, manual, or auto
 --unit UNIT         sentence or paragraph
 ```
 
-Runtime discovery and per-language defaults are separate from legacy provider role configuration. Readio 0.2.0 requires the PyKokoro 0.9.x public discovery contract:
+Runtime discovery and per-language defaults are separate from legacy provider role configuration. Readio v0.2.x uses the PyKokoro >=0.9.2,<0.10 public discovery and tokenizer contract. Readio v0.2.3 is tested with PyKokoro 0.9.4:
 
 ```bash
 readio models list --language de --offline
@@ -98,7 +105,7 @@ readio defaults show de-at --json
 readio render --lang de --file notes.md
 ```
 
-`models` reads PyKokoro's lightweight registry and supports `--offline`, `--refresh`, `--status`, and `--json`; it never loads model weights. `--refresh` updates metadata only and cannot be combined with `--offline`. Offline synthesis still needs cached model and voice assets. `defaults` stores validated user policy in schema 2. Exact locale profiles override base-language profiles, and `--no-lexicons` explicitly clears inherited lexicons. Repeated named lexicons retain their order for layered lookup.
+`models` reads PyKokoro's lightweight registry and supports `--offline`, `--refresh`, `--status`, and `--json`; it never loads model weights. `--refresh` updates metadata only and cannot be combined with `--offline`. Offline synthesis still needs cached model and voice assets. `--lexicon crane` selects a named lexicon; `de-de:crane` is the downstream Lexphon asset ID, while `de-crane` is an acoustic model ID.
 `--model-source github|huggingface` drives both discovery and runtime selection. Voices are model-scoped. The legacy global `reader.voice` applies only to unchanged default-reader use; a language override such as `--lang de` leaves voice selection to the active PyKokoro model unless explicitly set. SSMD preflight uses that same resolved model roster.
 
 ## Synthesis planning
@@ -117,6 +124,8 @@ Keep the layers separate:
 - **Planning** (`readio plan`, `render --dry-run`) resolves one concrete request — model, source, quality, voice, lexicons, SSMD cast with per-reference bindings, output format/backend/path — and records a decision (winning source) for every effective value. Generated output paths are allocated once by the plan and reused by the render.
 - **Render result** executes the plan; a plan that fails validation (for example `model_language_incompatible`, `model_runtime_unavailable`, `ssmd_unresolved_voice`, `encoder_unavailable`) is printed with its diagnostics and no TTS model is loaded.
 
+Plans preserve the tokenizer tri-state: `lexicons: null` means PyKokoro language defaults, `lexicons: []` means no static lexicon layers, and a non-empty list means ordered named layers. Fallback and lexicon data policy are also carried unchanged into `TokenizerConfig`; SSMD `language_detection` hints are resolved into the plan before execution.
+
 Planning is deterministic: `--resolve-voices` is rejected during `plan`/`--dry-run` in favor of `--voice-bind ROLE=VOICE_ID` or persisted roles, and `plan` supports `--force` to mirror render output requests.
 
 ## Durable render manifests
@@ -143,6 +152,16 @@ readio render --file notes.md -o notes.mp3 --json --progress
 
 Bounded renders show phases, completed/total units, percentage, elapsed time, approximate ETA, generated audio duration, and finalization. Live rendering shows elapsed time, cumulative units, and audio duration but no invented percentage or ETA.
 
+## Verbose diagnostics
+
+Use `-v` for timestamped INFO lifecycle records and `-vv` for DEBUG details from Readio and PyKokoro:
+
+```bash
+readio -v speak "Hello"
+readio -vv render episode.ssmd -o episode.mp3
+```
+
+The option is global and may appear before or after a command. Logs are written only to stderr. Human results and JSON remain on stdout, so `readio -v doctor --json` still emits valid JSON. `--progress` and `--no-progress` remain independent; verbose mode makes progress line-oriented on a TTY. Review paths, model names, and voice identifiers before sharing diagnostics. Complete document text, raw audio, Spotify credentials, and authorization responses are not logged.
 Playback-only options are `--queue-size` and `--device`. Audio rendering is streamed to an atomic output file through a bounded audio path rather than accumulated as one in-memory waveform.
 
 ## Configuration
@@ -162,8 +181,8 @@ readio config validate
 - `[ssmd]`: the selected `voice_provider` and SSMD validation behavior.
 - `[paths]`: user template, ingest, and audio output directories.
 - `[voices.<provider>]`: concrete voice IDs and logical role mappings.
-
-- `[languages.<locale>]`: validated model, source, quality, voice, ordered lexicons, and experimental opt-in defaults.
+- `[languages.<locale>]`: validated model, source, quality, voice, ordered lexicons, `g2p_fallback`, and `lexicon_data_policy` defaults.
+- `[reader]`: optional `language_detection` mode and ordered `detect_languages` routing hints.
   Set values with dotted keys. Aliases `voice`, `lang`, and `speed` target the corresponding reader settings:
 
 ```bash

{readio-0.2.2 → readio-0.2.3}/llm-guides/README.md

@@ -56,8 +56,8 @@ When file creation is unavailable, the guide instructs the LLM to return the com
 The guides target the conservative authoring subset used by:
 
 - Readio 0.2.x
-- SSMD >=0.8.6,<0.9
-- PyKokoro 0.9.x
+- SSMD >=0.8.7,<0.9
+- PyKokoro >=0.9.2,<0.10 (Readio v0.2.3 tested with 0.9.4)
 
 This is a compatibility target, not a claim that the authoring environment ran validation. A generated file should be checked on the destination system before rendering.
 

{readio-0.2.2 → readio-0.2.3}/llm-guides/ssmd/audio-drama.md

@@ -42,8 +42,8 @@ If downloadable file or artifact creation is unavailable:
 Generate conservative SSMD for this compatibility target:
 
 - Readio 0.2.x
-- SSMD >=0.8.6,<0.9
-- PyKokoro 0.9.x
+- SSMD >=0.8.7,<0.9
+- PyKokoro >=0.9.2,<0.10 (Readio v0.2.3 tested with 0.9.4)
 
 These are authoring instructions, not a requirement to install or execute the runtime. They must work without Python, a Readio installation, the Readio Agent Skill, local SSMD tooling, or local model discovery. The generated file can be checked and rendered later on a Readio-capable system.
 

{readio-0.2.2 → readio-0.2.3}/llm-guides/ssmd/debate-pro-con.md

@@ -42,8 +42,8 @@ If downloadable file or artifact creation is unavailable:
 Generate conservative SSMD for this compatibility target:
 
 - Readio 0.2.x
-- SSMD >=0.8.6,<0.9
-- PyKokoro 0.9.x
+- SSMD >=0.8.7,<0.9
+- PyKokoro >=0.9.2,<0.10 (Readio v0.2.3 tested with 0.9.4)
 
 These are authoring instructions, not a requirement to install or execute the runtime. They must work without Python, a Readio installation, the Readio Agent Skill, local SSMD tooling, or local model discovery. The generated file can be checked and rendered later on a Readio-capable system.
 

{readio-0.2.2 → readio-0.2.3}/llm-guides/ssmd/document-summary.md

@@ -42,8 +42,8 @@ If downloadable file or artifact creation is unavailable:
 Generate conservative SSMD for this compatibility target:
 
 - Readio 0.2.x
-- SSMD >=0.8.6,<0.9
-- PyKokoro 0.9.x
+- SSMD >=0.8.7,<0.9
+- PyKokoro >=0.9.2,<0.10 (Readio v0.2.3 tested with 0.9.4)
 
 These are authoring instructions, not a requirement to install or execute the runtime. They must work without Python, a Readio installation, the Readio Agent Skill, local SSMD tooling, or local model discovery. The generated file can be checked and rendered later on a Readio-capable system.
 

{readio-0.2.2 → readio-0.2.3}/llm-guides/ssmd/dramatic-story.md

@@ -42,8 +42,8 @@ If downloadable file or artifact creation is unavailable:
 Generate conservative SSMD for this compatibility target:
 
 - Readio 0.2.x
-- SSMD >=0.8.6,<0.9
-- PyKokoro 0.9.x
+- SSMD >=0.8.7,<0.9
+- PyKokoro >=0.9.2,<0.10 (Readio v0.2.3 tested with 0.9.4)
 
 These are authoring instructions, not a requirement to install or execute the runtime. They must work without Python, a Readio installation, the Readio Agent Skill, local SSMD tooling, or local model discovery. The generated file can be checked and rendered later on a Readio-capable system.
 

{readio-0.2.2 → readio-0.2.3}/llm-guides/ssmd/educational-explainer.md

@@ -42,8 +42,8 @@ If downloadable file or artifact creation is unavailable:
 Generate conservative SSMD for this compatibility target:
 
 - Readio 0.2.x
-- SSMD >=0.8.6,<0.9
-- PyKokoro 0.9.x
+- SSMD >=0.8.7,<0.9
+- PyKokoro >=0.9.2,<0.10 (Readio v0.2.3 tested with 0.9.4)
 
 These are authoring instructions, not a requirement to install or execute the runtime. They must work without Python, a Readio installation, the Readio Agent Skill, local SSMD tooling, or local model discovery. The generated file can be checked and rendered later on a Readio-capable system.
 

{readio-0.2.2 → readio-0.2.3}/llm-guides/ssmd/funny-story.md

@@ -42,8 +42,8 @@ If downloadable file or artifact creation is unavailable:
 Generate conservative SSMD for this compatibility target:
 
 - Readio 0.2.x
-- SSMD >=0.8.6,<0.9
-- PyKokoro 0.9.x
+- SSMD >=0.8.7,<0.9
+- PyKokoro >=0.9.2,<0.10 (Readio v0.2.3 tested with 0.9.4)
 
 These are authoring instructions, not a requirement to install or execute the runtime. They must work without Python, a Readio installation, the Readio Agent Skill, local SSMD tooling, or local model discovery. The generated file can be checked and rendered later on a Readio-capable system.
 

{readio-0.2.2 → readio-0.2.3}/llm-guides/ssmd/general-narration.md

@@ -42,8 +42,8 @@ If downloadable file or artifact creation is unavailable:
 Generate conservative SSMD for this compatibility target:
 
 - Readio 0.2.x
-- SSMD >=0.8.6,<0.9
-- PyKokoro 0.9.x
+- SSMD >=0.8.7,<0.9
+- PyKokoro >=0.9.2,<0.10 (Readio v0.2.3 tested with 0.9.4)
 
 These are authoring instructions, not a requirement to install or execute the runtime. They must work without Python, a Readio installation, the Readio Agent Skill, local SSMD tooling, or local model discovery. The generated file can be checked and rendered later on a Readio-capable system.