textflowkit 0.1.10__tar.gz → 0.1.12__tar.gz

{textflowkit-0.1.10 → textflowkit-0.1.12}/CHANGELOG.md

@@ -1,5 +1,99 @@
 # Changelog
 
+## v0.1.12 — 2026-10-17
+
+Core: 0.1.12; unchanged optional fonts: 0.1.6. The native Windows installer has been built and tested locally. The installer recipe ships in v0.1.12; the EXE remains local-only until unresolved corresponding-source compliance review is cleared. No public installer download link is available.
+
+### Optional local UI proofreading (v0.1.12)
+
+- Add explicit post-transcription local Ollama proofreading with an installed-tag
+  picker; prefer `qwen3.5:9b` only when installed (size/performance fit unverified),
+  otherwise require selection.
+  No model downloads, cloud tags, paid provider, telemetry or new package dependency.
+- Preserve original jobs and exports; persist a separate original-hash-bound AI
+  variant with provider/model/time provenance, source segment IDs/timestamps, no
+  inherited word alignment, comparison/original-only views and corrected TXT/copy.
+- Bound background work and validate complete JSON/segment coverage atomically.
+  One cleanup at a time; fail without partial output. Normal shutdown drains work;
+  interrupted leases expire. AI corrections require human review.
+
+- Validation history: the first cold full-UI attempt ended in a generic error; a
+  later hot 39-segment run returned zero edits despite clear spelling errors.
+  Final cold run (model explicitly unloaded first) completed all 39 segments in
+  three chunks with four changed segments at 2026-10-16 17:39:52 UTC. The original
+  SQLite JSON/source and IDs/timestamps matched; visible side-by-side review and
+  corrected TXT save were verified, with the saved file hash matching the variant.
+  This proves workflow completion for one run, not accuracy; “fundamental” and
+  “victims” were plausible guesses not verified against audio. Review against audio.
+
+### Native Windows installer
+
+- Package the existing local browser UI in a native per-user installer for core
+  v0.1.12. Built and tested locally; public EXE publication remains gated on
+  corresponding-source compliance review. No public installer link is available.
+- Bundle: private embeddable CPython, the UI and HTTP, export, and
+  streaming dependencies, the pinned Whistle model and runtime, and ffmpeg,
+  ffprobe, and Node. The installer is designed to need no separate Python, WSL,
+  or Docker installation.
+- Prebundled Whistle assets and media binaries mean local file jobs need no
+  first-use asset download. URL media still needs network access. The default
+  Whistle engine supports only these seven advertised languages: `en`, `de`,
+  `fr`, `es`, `it`, `nl`, and `pl`.
+- Per-user setup with a Start Menu entry and optional desktop shortcut; launch
+  starts the loopback server and opens the existing UI in the browser. It normally
+  needs no administrator rights, changes no global `PATH`, and has no automatic
+  updates.
+- Keep UI data outside the app install directory and preserve it on upgrade and
+  uninstall. Stop server and wait before upgrade or uninstall; the candidate will
+  block while it is running rather than force-kill active jobs. Stop server drains
+  jobs, so cancel one first if it should not finish.
+- Do not bundle optional `openai-whisper` or diarization dependencies; their
+  documented optional paths remain available through the Python package. Bundled
+  streaming dependencies do not change the opt-in default; physical browser
+  microphone capture remains unverified.
+- The installer bundle includes third-party license and notice files,
+  including FFmpeg LGPL notices and corresponding-source information. Verify
+  exact notices and source-distribution details against final binaries before
+  publication.
+- The candidate is unsigned, so Windows may show a SmartScreen warning.
+
+## v0.1.11 — 2026-10-06
+
+Optional native live streaming supports **Windows x86_64 only**. Core version:
+0.1.11; unchanged optional fonts: 0.1.6. Existing standalone Whistle defaults,
+file/URL jobs, CLI, and MCP behavior are unchanged. The public site remains static
+documentation and serves no streams. Local source validation does not establish
+published-package verification or cross-platform live support.
+
+
+### Added
+
+- **Public `StreamingSession` API.** Bounded PCM feed, typed incremental events,
+  flush/finish, cancellation, canonical final `Transcript`, and context-manager
+  cleanup. One owned native child per session binds directly to the separately
+  pinned `libneedle3.dll`; no upstream Python SDK or telemetry module is loaded.
+  Live sessions are ephemeral, with no replay or durable resume.
+- **Live microphone streaming (opt-in, loopback-only).** When
+  `TEXTFLOWKIT_STREAMING=1` is set, the developer HTTP app serves a `/stream`
+  WebSocket and the local UI serves `/api/stream`, both transcribing audio as it
+  arrives. A runnable, self-hosted browser example is at `/streaming-example`
+  (and `/api/streaming-example` under the UI); its `AudioWorklet` resamples any
+  device rate to 16 kHz mono with continuous phase. Off by default: with the
+  switch unset the endpoint does not exist. The standalone `textflowkit` CLI is
+  unaffected — it does not open a microphone or a streaming socket. Requires the
+  new `streaming` extra (`pip install "textflowkit[streaming]"`), which adds the
+  `websockets` dependency. Auth is fail-closed: the UI accepts only its own origin
+  and capability, the standalone API requires the API token (even in developer
+  mode), and a separate origin may stream only if the operator lists it in
+  `TEXTFLOWKIT_STREAMING_ORIGINS` (a browser needs its own origin listed, including
+  the standalone example's). See [docs/streaming.md](docs/streaming.md).
+  **Bounded live runs verified on this machine's native engine** — 65 s and 300 s
+  through the product core on Windows x86_64. A separate assembled UI WebSocket
+  run fed prerecorded PCM at real time for 12 s. Browser lifecycle and resampling
+  checks used fake audio; **physical microphone capture was not verified**. Only
+  English was measured natively; the other six accepted languages and live
+  Linux/macOS were not exercised. No public remote streaming is provided.
+
 ## v0.1.10 — 2026-10-06
 
 **The local browser interface ships.** The loopback-only browser workspace
@@ -51,7 +145,7 @@ security boundaries. A **native Windows** machine, in a real browser, proved the
 workspace end to end (drop a file, submit, download, stop). That is one platform's
 browser proof, **not** a live Linux or macOS UI run — those platforms are covered
 by automated tests only, and cross-platform CI (Windows/Linux/macOS) is a separate
-step run by the coordinator. **No live optional-backend (translation or
+release gate. **No live optional-backend (translation or
 diarization) run through the UI is claimed.** The engine and packaging changes of
 v0.1.9 are unchanged by this release.
 

{textflowkit-0.1.10 → textflowkit-0.1.12}/CONTRIBUTING.md

@@ -14,9 +14,15 @@ python -m venv .venv
 # Windows: .venv\Scripts\activate
 # POSIX:   source .venv/bin/activate
 pip install ./packages/textflowkit-fonts  # local optional PDF font companion
-pip install -e ".[dev,mcp,http,export]"
+pip install -e ".[dev,mcp,http,streaming,export,whisper]"
 ```
 
+The full suite needs both `streaming` (WebSocket transport) and `whisper`
+(optional standalone engine) dependencies. Use a development environment; for
+an existing AMD ROCm torch stack, follow [the install guide](docs/install.md)
+to preserve that stack. Native live streaming supports Windows x86_64 only;
+ordinary standalone platform support and defaults remain unchanged.
+
 ## Test and lint — the commands CI runs
 
 ```bash

{textflowkit-0.1.10 → textflowkit-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.10
+Version: 0.1.12
 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
@@ -32,6 +32,7 @@ Requires-Dist: python-docx>=1.1; extra == 'all'
 Requires-Dist: reportlab>=4.0; extra == 'all'
 Requires-Dist: textflowkit-fonts<0.2,>=0.1.5; extra == 'all'
 Requires-Dist: uvicorn>=0.30; extra == 'all'
+Requires-Dist: websockets<16,>=15; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: hatchling>=1.25; extra == 'dev'
@@ -53,6 +54,11 @@ 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: streaming
+Requires-Dist: fastapi>=0.115; extra == 'streaming'
+Requires-Dist: pydantic>=2.7; extra == 'streaming'
+Requires-Dist: uvicorn>=0.30; extra == 'streaming'
+Requires-Dist: websockets<16,>=15; extra == 'streaming'
 Provides-Extra: whisper
 Requires-Dist: openai-whisper>=20240930; extra == 'whisper'
 Description-Content-Type: text/markdown
@@ -67,7 +73,7 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [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.10](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.10).**
+**Current release: [v0.1.12](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.12).**
 
 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
@@ -128,7 +134,7 @@ DOCX and PDF are available through the optional `export` extra.
 
 ## Architecture
 
-![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above 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.10/docs/assets/architecture-overview.svg)
+![TextFlowKit shared-core architecture: five thin entry points feed one core. The CLI, Python API, MCP, HTTP API, and the local browser UI (a fifth door that mounts the existing HTTP app under /api and shares the same job store, adding transport only, not a new pipeline) sit above 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.12/docs/assets/architecture-overview.svg)
 
 The design principle is **one shared core, thin doors**. Everything of substance
 lives in the core; the interfaces are thin — the local browser UI is a fifth door
@@ -150,6 +156,32 @@ means writing one source adapter, not another tool.
 For the job lifecycle, process ownership, checkpoints, and output publication,
 see [docs/architecture.md](https://github.com/scottconverse/textflowkit/blob/main/docs/architecture.md).
 
+## Live microphone streaming (opt-in)
+
+In v0.1.12, live streaming supports **Windows x86_64 only**. When
+`TEXTFLOWKIT_STREAMING=1` is set, the developer HTTP app serves a `/stream`
+WebSocket and the local UI serves `/api/stream`, both transcribing a live microphone
+as you speak. A **runnable, self-hosted browser example** ships at
+`/streaming-example` (and `/api/streaming-example` under the UI): it captures with an
+`AudioWorklet`, resamples any device rate to 16 kHz mono, and shows the transcript.
+No CDN, no analytics, no external fetch. Requires the `streaming` extra:
+
+```bash
+python -m pip install "textflowkit[streaming]==0.1.12"
+```
+
+It is **off by default** — with the switch unset the endpoint does not exist — and
+**loopback-only**: auth is fail-closed, so the UI accepts only its own origin and
+capability, the standalone API requires `TEXTFLOWKIT_API_TOKEN` (even in developer
+mode), and a separate origin — including the standalone browser example's own origin —
+may stream only if listed in `TEXTFLOWKIT_STREAMING_ORIGINS`. The standalone
+`textflowkit` CLI is unaffected: it does not open a microphone or a streaming socket.
+**Bounded live runs are verified on the native engine here** — 65 s and 300 s
+end-to-end on Windows x86_64; the transport and the browser resampler are covered by
+tests, and a physical browser microphone has not yet been captured (the browser proof
+drives the page against a fake audio device). See
+[docs/streaming.md](https://github.com/scottconverse/textflowkit/blob/main/docs/streaming.md).
+
 ## Recognized sources
 
 YouTube · TikTok · Facebook · Instagram · Vimeo · Twitch · Bilibili · Rumble ·
@@ -201,6 +233,38 @@ installs `textflowkit-fonts` for offline multilingual PDF rendering:
 python -m pip install 'textflowkit[export]'
 ```
 
+## Windows desktop installer (v0.1.12; public EXE pending)
+
+An installer for the existing local browser workspace accompanies core v0.1.12. The native Windows installer has been built and tested locally. The installer recipe ships in v0.1.12; the EXE remains local-only until unresolved corresponding-source compliance review is cleared. No public installer download link is available. The Python package remains supported for developers and integrations.
+
+The candidate is designed to run without a separately installed Python, WSL, or
+Docker. Its bundle includes a private embeddable CPython runtime, the
+browser UI and HTTP, export, and streaming dependencies, the pinned Whistle model
+and runtime, and ffmpeg, ffprobe, and Node. The setup installs per user,
+creates a Start Menu shortcut, and offers an optional desktop shortcut. Opening
+the shortcut will start the local server and open the existing browser UI at
+localhost. It is designed to need no administrator rights in normal use, change
+no global `PATH`, and avoid automatic updates.
+
+The pinned Whistle assets and media binaries are prebundled, so local file jobs
+need no first-use asset download. URL sources still need their normal network
+access. The default Whistle engine supports only these seven advertised languages:
+`en`, `de`, `fr`, `es`, `it`, `nl`, and `pl`. Optional `openai-whisper` and diarization dependencies are not
+bundled; those features remain documented for the Python package when separately
+installed and configured. Streaming dependencies are bundled, but live streaming
+remains opt-in and physical browser microphone capture has not been verified.
+
+The candidate is designed to keep UI data outside the application install
+directory and preserve it on upgrades and uninstall. Stop the UI server with
+**Stop server** and wait for it to exit before upgrading or uninstalling; the
+installer will block while it is running rather than force-killing active jobs.
+Cancel a job first if it should not drain to completion. The bundle also
+includes third-party license and notice files, including FFmpeg's LGPL notices
+and corresponding-source information. Check exact notices and source-distribution
+details against the final bundled binaries before publication. The candidate is
+unsigned, so Windows may show a SmartScreen warning. See the [installer candidate
+notes](docs/install.md#windows-desktop-installer-v0112-public-exe-pending).
+
 ## Python API
 
 The same pipeline used by the CLI and adapters is available to Python callers:
@@ -296,7 +360,7 @@ textflowkit export ./transcript.json --format vtt
 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.10/docs/assets/whistle-resume.svg)
+![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.12/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
@@ -313,7 +377,7 @@ torch; `openai-whisper` is an explicitly selectable opt-in engine.
   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
+- **Standalone 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
@@ -407,7 +471,7 @@ its own beyond the `http` extra. It ships with the core package as of v0.1.10:
 a regular install of the current release carries it.
 
 ```bash
-python -m pip install 'textflowkit[http,export]==0.1.10'
+python -m pip install 'textflowkit[http,export]==0.1.12'
 textflowkit-ui
 ```
 
@@ -478,29 +542,37 @@ browser interface share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.10 release.** Core, CLI, MCP, HTTP, and the local browser interface have
-automated coverage. This release **ships the local browser interface**
-(`textflowkit-ui`) in the core package: a loopback-only workspace that reuses the
-same pipeline, submission contract, and job store, with a durable store, cancel
-and resume, and a Windows desktop shortcut (`textflowkit-ui --create-shortcut`).
-It adds **no new dependency** beyond the existing `http` extra, so a regular
-`pip install 'textflowkit[http,export]==0.1.10'` carries it. The engine, CLI,
-Python, MCP, and HTTP surfaces are unchanged and there is **no endpoint-breaking
-change**. It builds on v0.1.9, which made **Whistle the default engine** — a
-native CPU-only transcriber that needs no PyTorch — and moved `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.
+**v0.1.12 release.** Adds optional UI-only local Ollama proofreading and native
+Windows installer packaging; public EXE distribution remains gated on unresolved
+corresponding-source compliance review, with no public installer download link.
+Existing optional live streaming provides a transport-neutral
+`StreamingSession` Python API, incremental transcript events, and authenticated
+loopback WebSockets (`/stream` on the developer HTTP API and `/api/stream` on the
+local UI), with a packaged browser microphone example. The native live capability
+supports **Windows x86_64 only** and uses one owned child with a separately pinned
+`libneedle3.dll`. The `streaming` extra supplies the WebSocket dependency;
+`TEXTFLOWKIT_STREAMING=1` enables the server routes. Streaming is off by default.
+
+Existing file and URL transcription, CLI, MCP, durable jobs, and local browser
+workspace defaults remain unchanged. Whistle stays the CPU-only standalone default;
+`openai-whisper` remains an explicit opt-in engine. The local browser workspace
+introduced in v0.1.10 still needs only the `http` extra for its ordinary job flow.
+Fonts remain 0.1.6. Live sessions are ephemeral and have no durable resume.
+
+**Streaming evidence.** Local English PCM runs exercised the native core for 65 s
+and 300 s; a separate assembled UI WebSocket run fed prerecorded PCM at real time
+for 12 s and returned incremental events and a final transcript. Browser lifecycle
+and resampling checks used fake audio. Physical browser microphone capture, live
+Linux/macOS, and the six other accepted languages were not verified. The public
+website remains static documentation and serves no streaming endpoint. Local source
+validation does not establish published-package or exact-commit CI results.
 
 **Verification limit.** The local browser interface is covered by an automated
 suite, and the UI's behavior was proved on a **native Windows** machine in a real
 browser. No live optional-backend (translation/diarization) run through the UI is
 claimed, and **no live Linux or macOS UI run was performed here** — those
 platforms are covered by automated tests only, and CI across Windows, Linux, and
-macOS is the coordinator's separate step. Release publication uses the tag
+macOS is a separate release gate. 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
@@ -517,7 +589,7 @@ 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 releases' record, not evidence
-for v0.1.10.
+for v0.1.12.
 
 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
@@ -536,7 +608,7 @@ 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 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.10, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.12, 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
@@ -573,3 +645,90 @@ limitation of liability.
 
 Issues and PRs welcome. Please read [LEGAL.md](https://github.com/scottconverse/textflowkit/blob/main/LEGAL.md) before adding a source
 adapter.
+
+
+## Optional local AI transcript cleanup (v0.1.12)
+
+v0.1.12 adds **opt-in proofreading in the local browser UI only**. After a transcription finishes, choose an
+installed local Ollama model and click **Proofread with local AI**. Cleanup never
+runs automatically. Ollama and cleanup models are not bundled in the installer.
+The optional default preference is `qwen3.5:9b` only if already installed; its
+size/performance fit has not been verified. Otherwise choose an installed local
+model explicitly, such as `qwen3.8:27b-q4_K_M`. Larger models are never silently
+selected. Install a model yourself through Ollama when needed; TextFlowKit does
+not pull models, enable cloud tags, or use a paid provider.
+
+The original transcript, job JSON, original copy button, search, and all existing
+exports remain unchanged. Choose **Original only** or compare **source original
+(left) / AI corrected (right)** in timestamp-anchored rows. Use **Copy corrected
+text** or **Save corrected TXT** for the separate AI variant. The comparison
+proofreads original source speech, not an optional translation. AI can make
+plausible but wrong corrections, including names and facts: review against the
+original and audio before using it. Prompt instructions reduce errors but do not
+guarantee accuracy or resistance to instructions embedded in speech.
+
+Corrected segments retain source start/end timestamps and stable zero-based
+original segment indices. They have no inherited word alignment or translation;
+**corrected word timing is not verified**. A separate persisted variant records
+local provider, requested/returned model, UTC completion time, endpoint, successful
+`done_reason=stop`, policy version and original SHA-256. If original job JSON
+changes, its correction is invalidated. No partial replacement is published: bad,
+truncated, missing, duplicated, reordered or extra segments fail the entire attempt.
+A failed retry retains an earlier fully validated variant only if its original
+hash still matches.
+
+Cleanup uses a separate SQLite file named `<job database filename>.cleanup.sqlite3`
+beside `TEXTFLOWKIT_DB` (or the UI default database). Include it when backing up UI
+data; it contains transcript text and provenance. The canonical job store is never
+updated by cleanup. Reloading/reopening a completed job retrieves its saved variant,
+even if Ollama is offline. Model selection is per attempt; it is not a global
+transcription/translation model setting.
+
+Configuration is process-local environment, consistent with the existing UI:
+
+- `TEXTFLOWKIT_CLEANUP_OLLAMA_URL`: default `http://127.0.0.1:11434`; only HTTP on
+  a literal loopback IP and explicit port is accepted (IPv6 `[::1]` also works).
+  DNS names, credentials, other paths, remote hosts and redirects are refused;
+  proxy environment variables are ignored by the cleanup client.
+- `TEXTFLOWKIT_CLEANUP_MODEL`: optional preferred installed local tag; defaults
+  to `qwen3.5:9b`. If absent from installed tags, explicit selection is required.
+  Cloud tags and Ollama remote-model metadata are refused.
+
+One cleanup runs at a time; the browser polls a background worker and remains
+usable. Limits: 2,000 segments, 120,000 source characters, 60 chunks, at most
+1,000 UTF-8 encoded bytes per chunk and 40 segments per chunk. A small read-only
+neighboring context helps with sentences spanning segments without merging them.
+Generation requests use temperature 0, thinking disabled, context 8,192 and at
+most 4,096 generated tokens per chunk. Requests have a 180-second socket timeout,
+bounded response reads (1 MiB), and strict 64 KiB model JSON limits. The overall
+work budget remains 600 seconds, checked between requests and reads; a blocking
+socket operation can take up to its remaining request timeout before failure is
+observed. Oversize or timeout failures leave the original available.
+
+Normal UI shutdown drains an active cleanup (it can take several minutes); there
+is no cleanup cancellation button. Abrupt process exit leaves no partial variant;
+an interrupted running lease becomes retryable after at most 785 seconds from its
+start. Cleanup does not restart Ollama or stop/unload other models. Model text is
+rendered with DOM text nodes, never HTML. Cleanup adds no Python dependency,
+telemetry, cloud provider or network destination beyond the configured local
+Ollama service. Existing media acquisition/translation network behavior is separate.
+
+### Candidate validation status
+
+The first cold full-UI attempt ended with a generic error and produced no variant;
+the original remained intact. A subsequent hot 39-segment run returned zero text
+edits despite clear source spelling errors, so it was not useful cleanup-quality
+evidence. The final cold run began with the model explicitly unloaded and
+completed all 39 segments in three chunks at
+2026-10-16 17:39:52 UTC. It used matching requested/returned
+`qwen3.8:27b-q4_K_M` and changed four segments. The original SQLite JSON matched
+the source file, with segment IDs and timestamps preserved. The in-app-browser
+side-by-side comparison was visible, and **Save corrected TXT** produced a
+2,516-byte file whose SHA-256 matched the validated variant.
+
+Observed edits included “guardrails,” “precludes,” and punctuation. “Fundamental”
+and “victims” were plausible guesses, not verified against the audio. This is
+measured evidence that the local full workflow completed and saved its separate
+variant for this run; it does not establish transcription accuracy or general
+cleanup quality. Review every correction against the audio. This is local workflow evidence,
+not an audio-accuracy certification.