textflowkit 0.1.7__tar.gz → 0.1.9__tar.gz

{textflowkit-0.1.7 → textflowkit-0.1.9}/.github/workflows/ci.yml

@@ -58,7 +58,11 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install ./packages/textflowkit-fonts
-          python -m pip install -e ".[dev,mcp,http,export]"
+          # `whisper` is installed here because the existing engine tests
+          # (openai-whisper's verbose/quiet contract, model-name validation)
+          # genuinely need the openai-whisper package present. It is an optional
+          # extra now that Whistle is the default engine, so it must be named.
+          python -m pip install -e ".[dev,mcp,http,export,whisper]"
 
       - name: Show ffmpeg version
         shell: bash

{textflowkit-0.1.7 → textflowkit-0.1.9}/.github/workflows/publish-pypi.yml

@@ -149,12 +149,24 @@ jobs:
           packages-dir: dist/main/
 
   publish-github-release:
-    # Deliberately no `if:` here. The implicit `success()` plus the default skip
-    # propagation is the gate that matters: a core upload that failed or was
-    # skipped for any reason skips this job too, so a failed release cannot end
-    # in a public GitHub release. Adding a status check function here would
-    # weaken that, not strengthen it.
+    # The release exists only to advertise a core version that is on PyPI, so it
+    # runs exactly on a successful core upload and nothing else. The condition is
+    # written out rather than left implicit for the same reason as the core
+    # upload above: a status check function must defeat skip propagation. An
+    # implicit `success()` here is still subject to it, and on a reused fonts
+    # release the workflow-wide propagation from the *skipped* fonts job reaches
+    # this job through `publish-main` and its skipped fonts dependency - v0.1.7
+    # initially skipped the release even though core reached PyPI, and the
+    # recovery published it.
+    #
+    # `always()` would also defeat the propagation, but it runs the job in a
+    # cancelled run too, so it is not used. Only a `success` core upload reaches
+    # the release: a failed, skipped or cancelled core upload, a cancelled run,
+    # and a build that did not succeed all leave no public release, so the
+    # release can never advertise a core version that is not on PyPI.
     needs: publish-main
+    if: >-
+      ${{ !cancelled() && needs.publish-main.result == 'success' }}
     runs-on: ubuntu-latest
     permissions:
       contents: write

textflowkit-0.1.9/CHANGELOG.md

@@ -0,0 +1,217 @@
+# Changelog
+
+## v0.1.9 — 2026-10-05
+
+**Whistle is now the default engine.** This release ships the Whistle integration
+prepared on the `feat/whistle-primary` branch.
+
+### Changed
+
+- **Whistle is the default engine; openai-whisper becomes an explicit opt-in.**
+  Whistle is a CPU-only native CLI that needs no PyTorch, so a fresh
+  `pip install textflowkit` no longer pulls the torch stack. `openai-whisper`
+  moves to a new optional `whisper` extra and is selected with `--engine whisper`
+  (or `engine="whisper"` on the Python/MCP/HTTP surfaces); the `all` extra still
+  includes it. A saved request or checkpoint from before this change keeps running
+  on the engine it names, so legacy Whisper work is never silently migrated, and
+  legacy engine aliases are preserved so older decoders keep working.
+- **Engine selection is never silent.** An unknown engine name, an unsupported
+  language, or a non-CPU device for Whistle is refused at request construction —
+  before any media is fetched — and the message names `--engine whisper` as the
+  GPU alternative. The engine is not switched to satisfy a request.
+
+### Added
+
+- **Whistle engine.** Seven advertised languages (`en`, `de`, `fr`, `es`, `it`,
+  `nl`, `pl`); native Windows x86-64/arm64, Linux x86-64/arm64, and Apple Silicon
+  (an Intel Mac is refused and pointed at the explicit Whisper engine); no WSL.
+  One pinned native binary and one pinned model are downloaded and hash-verified
+  on first use, outside the package. Long audio is split into 26-second cores with
+  up to 2 seconds of context (each clip ≤ 30 s); a word is owned by the clip whose
+  core contains its midpoint, so repeated phrases are preserved. Native
+  `--audio-stream` is never used.
+- **Durable per-block resume for Whistle.** A long run persists a partial
+  checkpoint after each core; a resume validates the source and decoded-WAV
+  hashes and the configuration, then re-runs only the unfinished blocks and adopts
+  the rest. A partial body is Whistle-only. Reuses the existing single SQLite
+  store and its one-owning-process model.
+- **Prompt, bounded cancellation.** A running Whistle run polls for cancellation
+  between clips and terminates its exact owned child process, bounded by a
+  per-clip timeout and a bounded stdout cap. A single long `openai-whisper` model
+  call is still cancellable only at its next stage boundary.
+- **Telemetry off, unconditionally.** Every Whistle child process forces
+  `NEEDLE_TELEMETRY=0`, `DO_NOT_TRACK=1`, and `CI=1`, overriding a parent that
+  opted in, and there is no opt-in setting. The product adds no analytics, usage
+  SDK, anonymous ids, or events. `TEXTFLOWKIT_OFFLINE` refuses downloads and
+  `TEXTFLOWKIT_MODELS_DIR` chooses the asset directory; the pinned first-use
+  asset/model download is not telemetry.
+
+### Documentation
+
+- README, user manual, install/adapter/architecture/roadmap/release docs and the
+  website source now describe Whistle as the shipped default. ROCm (and the
+  torch-pinning caveat) is scoped to the explicit `whisper` engine and
+  diarization, never to Whistle.
+- Self-contained checked-in SVG architecture drawings were added under
+  `docs/assets` and embedded in the README, both manuals (`user-manual.md` and the
+  renamed **Developer and integration manual**, `adapters.md`), the architecture
+  guide, and the landing page.
+- The live YouTube release smoke pins `--engine whisper --model tiny` so its
+  measured default-clip word stays reproducible across the default-engine change.
+
+### Verification boundary
+
+Local evidence only: a 4-hour (14,407-second) CPU run produced 555
+clips / 34,596 words / 2,875 segments in 731 seconds, offline with telemetry
+forced off, and a separate two-process run proved durable block resume. These are
+first local test numbers on one machine — not a universal performance claim, and
+not a claim that Whistle's accuracy equals Whisper's. No human-scored
+word-error rate is claimed.
+
+## v0.1.8 — 2026-10-02
+
+The 2026-10-02 audit-lite repair release. Core version: 0.1.8; unchanged optional fonts: 0.1.6. It carries the four fixes for the post-release audit-lite of 2026-10-01 (findings AL-001 – AL-004). Release artifacts and publication status are recorded on [GitHub Releases](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.8). Local source-candidate verification does not establish installed-package or individual harness compatibility.
+
+### Engineering fixes
+
+- **AL-001 — CLI owning-process startup recovery.** A CLI invocation that was
+  interrupted left its PENDING/RUNNING row active; because the CLI submits with
+  `background=False` it never started the recovering executor, so a later
+  `--resume` read the orphan as "already active" and refused a job whose expensive
+  work was saved. Recovery now runs once per owning process at the CLI's
+  process/store boundary (`cli.main`), before single or batch resume selection,
+  through the shared per-store owner. It is deliberately **not** an unconditional
+  reap in every `submit_request(background=False)`: an embedding process can hold
+  genuinely live work. A recovery write failure is reported as a clear error with
+  a nonzero exit, not a false success or a raw traceback. The documented
+  one-owning-process-per-database model is unchanged.
+- **AL-002 — preserve the completed transcript across resume setup failures.** The
+  source checkpoint serialized the local transcript (still `None`) before
+  hydrating the previous transcript, so a directory/`mkdtemp` failure replaced a
+  durable completed transcript with `null` while still listing `transcribe` as
+  finished. Reuse is now hydrated and validated **before** any directory setup,
+  and a replacement snapshot can no longer drop a still-finished transcript. A
+  changed local source is still refused, stages are never falsely marked complete,
+  and a healthy retry reuses the recognized work.
+
+### Documentation corrections
+
+- **AL-003 — MCP batch cookie capability.** The adapter guide said
+  `submit_batch_media` has no `cookies_from_browser` parameter. It does: the tool
+  accepts one shared value and forwards it to every request, and the production
+  refusal is enforced by the same shared guard as the other surfaces. The matrix
+  and paragraph (and the historical DOC-003 changelog text) were corrected, with a
+  schema-consistency regression test that reads the real SDK-generated tool schema.
+- **AL-004 — roadmap evidence.** The POSIX file-mode and fonts-reuse follow-ups
+  are marked done against their exact receipts: current-main CI run 36961982098
+  (12 OS/Python test jobs + three installed-wheel jobs + Ruff) verifies POSIX modes
+  on Linux/macOS, and release-workflow run 36961162844 built the reused 0.1.6
+  fonts, skipped the fonts upload, and published core to PyPI. The GitHub-release
+  job skip, its manual recovery, and the PR #23 condition repair are recorded
+  without claiming the original workflow was all green or the repaired automatic
+  path has been live-tested. The v0.1.7 history and version are preserved.
+
+## v0.1.7 — 2026-10-01
+
+The 2026-10-01 audit repair release. Core version: 0.1.7; unchanged optional fonts: 0.1.6. Release artifacts and publication status are recorded on [GitHub Releases](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.7). Local source-candidate verification does not establish installed-package or individual harness compatibility.
+
+### Engineering fixes
+
+- **Confined decoder boundary.** With `TEXTFLOWKIT_INPUT_ROOT` set, a confined
+  local input is staged and its decode is restricted to FFmpeg's self-contained
+  demuxers (`-format_whitelist`), and the `ffprobe` duration probe carries the
+  same whitelist. A playlist/manifest that would make the decoder open referenced
+  files is refused. The restriction covers a resume that re-decodes; a stage with
+  durable output is reused, not re-decoded. Owner runs without an input root stay
+  unrestricted.
+- **Atomic attempt ownership.** A worker pins the attempt generation it claimed;
+  every progress write, checkpoint write, and terminal finalize is guarded on it,
+  so a stale run cannot overwrite a newer attempt's label or verdict. The reopen
+  of a terminal row for resume is an atomic claim pinned to the observed attempt —
+  two callers racing one job id cannot both reopen it.
+- **Atomic worker startup and cancellation.** Worker-thread startup is atomic, and
+  the completion/cancellation race is decided in one place against the owned
+  attempt: the row becomes CANCELLED only if that generation carries an accepted
+  cancellation, DONE otherwise, so a finished DONE row can never still carry an
+  accepted cancel.
+- **DOCX identity.** Completed-output reuse for DOCX compares the archive bytes
+  with only the local and central ZIP time/date pairs blanked; every other byte
+  (member names and order, compression, flags, extra fields, comments, compressed
+  content) must be equal, and the comparison never inflates a member.
+- **Completed-stage reuse.** A run leaves a durable per-stage marker for each
+  expensive stage it finishes; resume reuses only stages finished for the
+  **requested configuration**, and a legacy coarse `postprocess` marker is honoured
+  only for the optional stages that record actually requested. The rule keys on
+  the marker, never on transcript metadata.
+- **Aggregate export preflight.** The whole requested format set is validated
+  (unsupported/duplicate names, then every dependency) and the aggregate rendered
+  bytes are bounded **before any destination file is written**, for every surface
+  that publishes output.
+- **Translation completeness.** The translator's result length is checked against
+  its input and every result is validated **before mutating any segment**: a
+  blank result for a non-blank segment raises and leaves the transcript exactly as
+  it was, rather than half-writing a set.
+- **Per-item batch validation.** Each batch entry is constructed and admitted
+  independently (HTTP and MCP): a non-object entry, a non-string/empty source, an
+  unsupported format, or an unusable engine is **that** entry's error, carrying its
+  original zero-based `index` and best-effort `source`, while the other entries
+  still queue, in submitted order. There is no whole-batch engine preflight.
+- **Terminal feedback.** A non-quiet CLI run streams live stage progress to
+  **stderr, flushed** (stdout stays clean for `--stdout`); quiet suppresses it.
+  Batch prints each item's result as it finishes. Job status exposes the recorded
+  stage.
+
+### Documentation corrections (DOC-001 – DOC-006)
+
+- **DOC-001** — the user manual now states that canonical saved/exported JSON
+  retains hidden segments and is an archive, not a redaction mechanism, and adds
+  a worked safe-publication-copy example that filters the copy without mutating
+  the stored transcript.
+- **DOC-002** — the adapter guide and manual now distinguish response shapes:
+  HTTP JSON returns a `transcript` object with page counts but no `next`, MCP
+  returns a JSON string under `content` and adds a `next` instruction, and HTTP
+  text reads carry no paging metadata. Time selection is described as
+  overlapping rather than clipped.
+- **DOC-003** — "same options" is replaced with a per-surface parameter matrix
+  (HTTP `formats` array vs MCP comma-separated string; HTTP batch options are
+  **per item**, MCP batch options are shared), and the batch contract now states
+  that 202 means admission, not completion, with per-item indexed errors. MCP
+  `sources` is documented as a list of **strings**: a non-string entry (including
+  a nested object or a number) is that entry's own error, not a whole-call
+  refusal, while a string remains valid.
+  *Correction (2026-10-01, audit-lite AL-003):* the v0.1.7 text of this entry
+  claimed the MCP batch tool exposes **no** `cookies_from_browser` parameter.
+  That was wrong. `submit_batch_media` accepts `cookies_from_browser` and
+  forwards the one shared value to every request it builds; the production
+  refusal is enforced by the same shared guard as the other surfaces. The
+  adapter guide was corrected to match the generated tool schema.
+- **DOC-004** — a full production settings reference (names, defaults, units,
+  required fields) is added to the adapter guide, and the production refusal of
+  browser-cookie submissions is stated across the adapter guide, the sources
+  guide, and `SECURITY.md`, including resume.
+- **DOC-005** — the install guide chooses the diarization install path (preserve
+  a working ROCm stack vs fresh CPU) **before** the first pip command, and the
+  manual's ROCm deep link now resolves to the actual heading.
+- **DOC-006** — new [architecture and lifecycle guide](docs/architecture.md)
+  maps the core/CLI/MCP/HTTP doors, single-owning-process SQLite, startup
+  recovery via the HTTP/MCP lifespans and the lazy executor, checkpoint reuse,
+  and output publication; the adapter guide's "reaped at startup" wording is
+  qualified to match. Linked from the README and `CONTRIBUTING.md`.
+
+The production settings reference lives in
+[docs/adapters.md](docs/adapters.md#production-settings-reference).
+
+### Deferred audit follow-ups — later fixes
+
+On 2026-10-01, the owner explicitly deferred the following findings from the
+full five-role audit. They remain open; they are not completed fixes, new release
+claims, or additions to the current core-bug repair goal. No release date is set.
+
+See [Later fixes in the roadmap](docs/roadmap.md#later-fixes--2026-10-01-audit)
+for the complete list and completion criteria. The current repair goal still
+covers decoder confinement, job lifecycle, publication/resume, translation and
+batch correctness, major terminal guidance/documentation, and its final gate.
+
+This changelog starts with the v0.1.8 release notes, followed by the v0.1.7
+release notes; published historical
+release notes remain on [GitHub Releases](https://github.com/scottconverse/textflowkit/releases).

{textflowkit-0.1.7 → textflowkit-0.1.9}/Dockerfile

@@ -77,11 +77,13 @@ RUN set -eux; \
 WORKDIR /app
 COPY pyproject.toml README.md LICENSE ./
 COPY src ./src
-# The base dependencies are yt-dlp and openai-whisper, so this image is large:
-# openai-whisper pulls a torch build. That is the product's own requirement, not
-# something this file adds.
+# The base dependencies are yt-dlp alone: the default engine (Whistle) is a
+# native CPU binary fetched on first use, so this image does not pull a torch
+# build. Selecting the openai-whisper engine needs the `whisper` extra named
+# here; the image installs it because the container is meant to serve the
+# Whisper stack too, and openai-whisper is what pulls the torch build.
 RUN python -m pip install --no-cache-dir --upgrade pip \
- && python -m pip install --no-cache-dir ".[http]"
+ && python -m pip install --no-cache-dir ".[http,whisper]"
 
 # Non-secret defaults only. The roots are the directories created above; Compose
 # repeats them so the volumes it mounts land on the paths the service reads.

{textflowkit-0.1.7 → textflowkit-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.7
+Version: 0.1.9
 Summary: Cross-platform media transcription toolkit: URL or file in, timestamped transcripts and subtitle files out.
 Project-URL: Homepage, https://www.textflowkit.org/
 Project-URL: Issues, https://github.com/scottconverse/textflowkit/issues
@@ -21,11 +21,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Classifier: Topic :: Text Processing
 Requires-Python: >=3.10
-Requires-Dist: openai-whisper>=20240930
 Requires-Dist: yt-dlp>=2025.1.1
 Provides-Extra: all
 Requires-Dist: fastapi>=0.115; extra == 'all'
 Requires-Dist: mcp>=2.0; extra == 'all'
+Requires-Dist: openai-whisper>=20240930; extra == 'all'
 Requires-Dist: pyannote-audio>=4.0; extra == 'all'
 Requires-Dist: pydantic>=2.7; extra == 'all'
 Requires-Dist: python-docx>=1.1; extra == 'all'
@@ -53,6 +53,8 @@ Requires-Dist: pydantic>=2.7; extra == 'http'
 Requires-Dist: uvicorn>=0.30; extra == 'http'
 Provides-Extra: mcp
 Requires-Dist: mcp>=2.0; extra == 'mcp'
+Provides-Extra: whisper
+Requires-Dist: openai-whisper>=20240930; extra == 'whisper'
 Description-Content-Type: text/markdown
 
 # textflowkit
@@ -62,9 +64,10 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [Project landing page](https://www.textflowkit.org/) ·
 [PyPI package](https://pypi.org/project/textflowkit/) ·
 [GitHub releases](https://github.com/scottconverse/textflowkit/releases) ·
-[User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
+[User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md) ·
+[Developer and integration manual](https://github.com/scottconverse/textflowkit/blob/main/docs/adapters.md)
 
-**Current release: [v0.1.7](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.7).**
+**Current release: [v0.1.9](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.9).**
 
 The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
 Pages. GitHub remains the source and CI host; the website does not run the
@@ -111,7 +114,7 @@ URL or file  ─►  detect platform  ─►  acquire media  ─►  ffmpeg
                                                           │
                               ┌───────────────────────────┘
                               ▼
-                    speech-to-text (Whisper)
+              speech-to-text (Whistle default; Whisper on request)
                               │
                               ▼
                  canonical transcript (JSON)
@@ -125,6 +128,8 @@ DOCX and PDF are available through the optional `export` extra.
 
 ## Architecture
 
+![TextFlowKit shared-core architecture: four thin entry points (CLI, Python, MCP, HTTP) feed one core that acquires and decodes media, transcribes with the default Whistle engine or an explicitly selected openai-whisper, keeps job state and resume checkpoints in an optional SQLite store, adds optional speaker or translation postprocessing, and publishes TXT, SRT, VTT, JSON, Markdown, and optional DOCX/PDF exports.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/architecture-overview.svg)
+
 The design principle is **one engine, three doors**. Everything of substance lives in
 the core; the interfaces are thin.
 
@@ -164,6 +169,22 @@ python -m pip install textflowkit
 textflowkit doctor
 ```
 
+The default engine is **Whistle**: a native CPU-only transcription CLI that
+needs no PyTorch. It downloads one pinned model (about 17 MB) and a small pinned
+binary on first use; a fresh default install therefore stays small and pulls no
+torch. To use the `openai-whisper` engine instead — the ROCm/CUDA/CPU torch
+stack — install the `whisper` extra and name it explicitly:
+
+```bash
+python -m pip install 'textflowkit[whisper]'
+textflowkit transcribe meeting.mp4 --engine whisper --model small
+```
+
+See [Whistle (default engine)](#whistle-default-engine) for platform and
+language coverage, and the [install guide](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md)
+for the AMD ROCm path, which applies to the explicit `whisper` engine and
+diarization.
+
 For MCP or the JSON HTTP adapter, install the matching extra:
 
 ```bash
@@ -187,7 +208,6 @@ from textflowkit import transcribe
 
 result = transcribe(
     "meeting.mp4",            # also accepts supported URLs
-    model="small",
     formats=["json", "srt", "txt"],
     output_dir="transcripts", # omit to return the transcript without writing files
 )
@@ -200,6 +220,10 @@ for segment in result.transcript.segments:
         print("  ", word.start, word.end, word.text)
 ```
 
+`engine` defaults to the product default (Whistle) and `model=None` resolves to
+that engine's own model. To use the Whisper-family engines, name one and its
+model explicitly: `transcribe("meeting.mp4", engine="whisper", model="small")`.
+
 `transcribe()` returns `TranscribeResult` with a canonical `Transcript` and
 written output paths. `Transcript.to_dict()` / `.to_json()` preserve segment and
 word timing; older transcript JSON without `words` remains readable. Pass
@@ -264,6 +288,60 @@ does **not** assert that the remote bytes are still identical.
 textflowkit export ./transcript.json --format vtt
 ```
 
+## Whistle (default engine)
+
+**Whistle is the default engine** as of v0.1.9. It is a native CPU-only CLI that
+needs no PyTorch, so a fresh `pip install textflowkit` stays small and pulls no
+torch; `openai-whisper` is an explicitly selectable opt-in engine.
+
+![Whistle bounded block run and durable resume: a decoded PCM WAV is split into 26-second cores with up to 2 seconds of context (each clip ≤ 30 s), each core runs as one owned child with forced telemetry-off flags, a partial checkpoint is written after each core, and a resume validates the source and decoded-WAV hashes then re-runs only the unfinished cores.](https://raw.githubusercontent.com/scottconverse/textflowkit/v0.1.9/docs/assets/whistle-resume.svg)
+
+- **CPU only, no torch.** It runs a pinned native binary and downloads one pinned
+  model on first use. Naming a GPU device is refused rather than silently
+  ignored: a GPU request names the explicit `whisper` engine as the alternative,
+  and the engine is never switched for you.
+- **Seven advertised languages:** `en`, `de`, `fr`, `es`, `it`, `nl`, `pl`. A
+  request for another language is refused at request construction, before any
+  media is fetched.
+- **Native platforms:** Windows x86-64 and arm64, Linux x86-64 and arm64, and
+  Apple Silicon. **Intel Macs are not supported**; a request there is refused
+  with a message that names the explicit `whisper` engine instead. No WSL layer
+  is involved.
+- **How it works:** long audio is split into 26-second cores with up to 2 seconds
+  of context on each side, so every standalone clip is ≤ 30 seconds (the native
+  CLI's limit). Overlap words are selected by core midpoint rather than text
+  deduplication, so repeated spoken phrases are preserved.
+- **Streaming is not used.** The native `--audio-stream` mode failed its
+  coverage and is never passed; only the committed standalone output is parsed.
+- **Durable block resume.** With `TEXTFLOWKIT_DB` set, a long run writes partial
+  per-block checkpoints; a resume checks the source and decoded-WAV hashes and the
+  config, then re-runs only the blocks that were not finished. The durable store
+  still assumes one owning process.
+- **Cancellation.** A running Whistle run terminates its exact owned child
+  process bounded by a per-clip timeout. A single long `openai-whisper` model call
+  is still only cancellable at its next stage boundary, as documented for the
+  Whisper engine.
+- **Telemetry is off, unconditionally.** Every Whistle child process forces
+  `NEEDLE_TELEMETRY=0`, `DO_NOT_TRACK=1`, and `CI=1`, overriding a parent that
+  opted in. The product ships no analytics, usage SDK, anonymous ids, or events,
+  and there is no opt-in setting. This applies the upstream documented gate; it
+  is **not** a claim that the upstream binary's tracking code is physically
+  removed.
+- **Offline and downloads.** Set `TEXTFLOWKIT_OFFLINE` to refuse any download, and
+  `TEXTFLOWKIT_MODELS_DIR` to choose the asset directory. The Whistle asset helper
+  downloads only pinned runtime/model assets; media acquisition and optional
+  translation may independently use the network. These downloads are not
+  telemetry.
+
+**Verification boundary.** A local run transcribed a 4-hour (14,407 s)
+recording on CPU into 555 clips / 34,596 words / 2,875 segments in 731 s, with
+telemetry forced off and offline mode on; a separate run proved durable block
+resume across two processes. These are **first local test numbers**, not a
+promise of universal performance or of accuracy equal to Whisper — no
+human-scored word-error rate is claimed. See the
+[user manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
+and [install guide](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md).
+
 ## Use as an MCP server
 
 ```bash
@@ -323,7 +401,7 @@ scope here, so no image is claimed to build or start. See
 
 ```bash
 TEXTFLOWKIT_DB=./jobs.db            # job state survives restart (SQLite)
-TEXTFLOWKIT_MAX_CONCURRENCY=1        # default; Whisper saturates a GPU alone
+TEXTFLOWKIT_MAX_CONCURRENCY=1        # default; bounded job worker pool
 ```
 
 `cancel_job` stops a queued job immediately, or a running job at its next stage
@@ -338,14 +416,31 @@ web frontend share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.7 release.** Core, CLI, MCP, and HTTP have automated
-coverage. This release is the 2026-10-01 audit repair set — the post-v0.1.6
-review follow-ups the owner accepted on 2026-10-01: a confined decoder boundary
-for rooted local inputs, atomic job-attempt ownership with atomic worker startup
-and cancellation finalization, DOCX completed-output identity, per-request
-completed-stage reuse, an aggregate export preflight, translation completeness
-and per-item batch validation, live terminal feedback, and major documentation
-corrections. Implementation was verified on a native-Windows source candidate with real CLI, HTTP and MCP speech, seven-format exports and completed resume. Release publication uses the tag workflow, which requires successful exact-commit main CI before PyPI uploads and creates the public GitHub release only afterward. Check the linked release for artifacts and workflow status; local source verification is not a fresh PyPI-install or individual-harness receipt.
+**v0.1.9 release.** Core, CLI, MCP, and HTTP have automated
+coverage. This release makes **Whistle the default engine** — a native CPU-only
+transcriber that needs no PyTorch — and moves `openai-whisper` to the optional
+`whisper` extra, selected explicitly with `--engine whisper` or
+`engine="whisper"`. Legacy engine aliases are preserved, so older saved jobs and
+`transcribe()` calls still decode. Whistle refuses an unsupported platform,
+language, or GPU request instead of silently falling back. Its engine's
+verification boundary is in [Whistle (default engine)](#whistle-default-engine)
+above. Release publication uses the tag workflow, which requires successful
+exact-commit main CI before PyPI uploads and creates the public GitHub release
+only afterward. Check the linked release for artifacts and workflow status; local
+source verification is not a fresh PyPI-install or individual-harness receipt.
+
+The v0.1.8 release carried four fixes for the 2026-10-01 post-release audit-lite
+(findings AL-001 – AL-004): CLI owning-process startup recovery so an interrupted
+run's saved work can be resumed instead of being refused as "already active",
+preservation of the completed transcript across resume setup failures, a
+correction to the MCP batch cookie capability, and corrected roadmap evidence
+receipts. It built on the v0.1.7 audit repair set and the v0.1.6 review repairs
+that precede it. The v0.1.7 source candidate was verified with real CLI, HTTP and
+MCP speech, seven-format exports and completed resume; the v0.1.8 runtime fixes
+were independently checked through fresh-process CLI restart probes, real SQLite
+setup-failure tests, and the full Windows test suite. Those checks are not new
+individual-harness receipts. That is the previous release's record, not evidence
+for v0.1.9.
 
 The v0.1.6 release was the post-v0.1.5 review repair set: security hardening
 for media acquisition and the HTTP and MCP adapters, safer subtitle wrapping and
@@ -362,9 +457,9 @@ The v0.1.6 release is public: the
 [v0.1.6 GitHub release](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.6)
 and both [core](https://pypi.org/project/textflowkit/0.1.6/) and
 [fonts](https://pypi.org/project/textflowkit-fonts/0.1.6/) PyPI projects are
-live — that is the previous release's evidence, not a receipt for v0.1.7.
+live — that is the v0.1.6 release's evidence, not a receipt for a later release.
 Everything from here to the end of this section is the v0.1.6 release's
-historical record as published: it is not re-verified for v0.1.7, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.9, whose separate release evidence is not supplied by these historical paragraphs.
 Merged-main CI passed 16/16 on the tagged commit; the published wheel and
 sdist digests match the GitHub release assets and their SHA-256 list; and a fresh
 Windows Python 3.12 install of `textflowkit[export,mcp,http]==0.1.6` from PyPI