textflowkit 0.1.11__tar.gz → 0.1.13__tar.gz

{textflowkit-0.1.11 → textflowkit-0.1.13}/.github/workflows/ci.yml

@@ -45,9 +45,20 @@ jobs:
         if: runner.os == 'Linux'
         run: sudo apt-get update && sudo apt-get install -y ffmpeg
 
-      - name: Install ffmpeg (Windows)
+      - name: Install pinned ffmpeg (Windows)
         if: runner.os == 'Windows'
-        run: choco install ffmpeg --no-progress -y
+        shell: python
+        run: |
+          import os, runpy
+          from pathlib import Path
+          ns = runpy.run_path('scripts/prepare_windows_payload.py')
+          spec = ns['load_asset_lock'](Path('packaging/windows/assets.lock.json'))['assets']['ffmpeg']
+          cache = Path(os.environ['RUNNER_TEMP']) / 'textflowkit-ci-ffmpeg'
+          archive = ns['_download_locked_asset'](cache, spec)
+          destination = cache / 'payload'
+          ns['prepare_ffmpeg_archive'](archive, destination)
+          with open(os.environ['GITHUB_PATH'], 'a', encoding='utf-8') as f:
+              f.write(str(destination / 'bin') + '\n')
 
       - name: Install ffmpeg (macOS)
         if: runner.os == 'macOS'

textflowkit-0.1.13/AGENTS.md

@@ -0,0 +1,19 @@
+# TextFlowKit agent instructions
+
+Scott's current bounded completion contract governs this work. Follow the active task and repository-required CI; preserve unrelated work and credentials. Keep one concise execution record, reuse unaffected evidence, and distinguish prepared, executed, verified and delivered work. A documented blocker remains incomplete. Do not invent adjacent features or weaken checks.
+
+## Roles and delegation
+
+The main assistant coordinates, plans and oversees. A worker invoked for an implementation unit performs that assigned unit directly; it is not another coordinator. Do not launch nested workers or automatic review/fan-out unless the owner or assignment explicitly authorizes it. Default to serial execution and one release candidate.
+
+## Model selection
+
+Follow Scott's active task selection; do not impose a project-wide Ollama default. His normal substantial-work/coordination preference is gpt-6.1-sol at medium, with gpt-6-luna at xhigh for small bounded work when available. Do not spawn a worker merely to switch models or add providers without authorization.
+
+For the explicitly authorized current Whistle release and issue #31 source-recovery work, Scott requested Ollama `deepseek-v4.1-flash:1017-cloud`, reasoning OFF. `scripts/run_deepseek_worker.py` is an explicit opt-in runner for those assigned DeepSeek units: it sends `think: false`, allows no model fallback, and records the actual response model. Ollama currently returns canonical ID `deepseek-v4.1-flash:1017` without the `-cloud` transport suffix. Do not confuse a worker's self-description with the transport receipts. Preserve existing DeepSeek integrations with reasoning off, but do not turn this task-specific instruction into the default for unrelated future work.
+
+This does not change the application's transcription or AI-cleanup defaults. Whistle remains the default transcription engine.
+
+## Scope and delivery safeguards
+
+Preserve unfinished work. Workers must not push, merge, tag, publish, release, stop unrelated processes, or change global configuration unless that unit is explicitly authorized to do so. The coordinating release task has Scott's push/merge/tag/publication authorization and separately his authorization to complete issue #31. Keep scratch, caches and build outputs outside the checkout. Verify process identity before acting on a PID; record ownership and terminal result for background jobs. Follow enforced controls rather than disguising a rejected action.

{textflowkit-0.1.11 → textflowkit-0.1.13}/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## v0.1.13 — 2026-10-19
+
+Core: 0.1.13; unchanged optional fonts: 0.1.6. Whistle missing-speech fixes and a
+native Windows installer distributed with matching FFmpeg sources and notices.
+
+- Bound native Whistle decode inputs to 15 seconds with 11-second owned cores
+  and up to two seconds of context per side. The former 30-second inputs
+  reproducibly omitted passages recovered by shorter inputs. Window policy is
+  part of resume identity; partial progress from the old plan requires a fresh
+  run. The engine and pinned model remain Whistle.
+- Check short gaps with a bounded, differently framed native decode. Add words
+  only between two matching timed anchors; retain original words/repetitions,
+  skip long pauses, and cap extra calls per core. Record recovery counts.
+- Correct Whistle shared-context assembly when independently estimated word
+  timestamps cause both neighboring cores to keep or discard the same occurrence.
+  Match occurrences one-to-one; preserve real repeated speech and leave ambiguous
+  collapsed repetitions untouched rather than using global text deduplication.
+- Persist raw boundary context in Whistle progress schema 2 so resumed assembly
+  matches uninterrupted output. Old schema-1 partial runs require a fresh start;
+  completed jobs remain unchanged. Default engine remains Whistle.
+- The native 30-second omission cases remain reproducible upstream; shorter
+  input windows and anchored gap checks mitigate them in TextFlowKit without
+  changing the engine or model weights.
+- Verification on one four-hour public meeting (1310 native cores, 18 min 34 s
+  native decode, 34,723 final words): the two long missing passages were
+  restored (2 to 50 and 0 to 47 words), 62 short-gap checks accepted 7 for 53
+  added words, resume after cores 350 and 700 reproduced exact word text and
+  timings, and no invalid bounds or backwards starts remained. Focused suite:
+  113 passed. Full suite: 2,097 passed, 18 skipped; skips are not passes. This is
+  coverage evidence for one recording, not human WER or perfect accuracy; normal
+  spelling errors remain. See
+  [the verification note](docs/verification/whistle-coverage-20261019.md).
+
+- Package matching FFmpeg sources, pinned build recipes, dependency archives and full notices alongside the Windows installer; record source hashes and preserve compatible DLL replacement. See [source verification](docs/verification/windows-sources-20261019.md).
+
+## 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:

{textflowkit-0.1.11 → textflowkit-0.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.11
+Version: 0.1.13
 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
@@ -73,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.11](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.11).**
+**Current release: [v0.1.13](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.13).**
 
 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
@@ -134,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.11/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.13/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
@@ -158,7 +158,7 @@ see [docs/architecture.md](https://github.com/scottconverse/textflowkit/blob/mai
 
 ## Live microphone streaming (opt-in)
 
-In v0.1.11, live streaming supports **Windows x86_64 only**. When
+In v0.1.13, 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
@@ -167,7 +167,7 @@ as you speak. A **runnable, self-hosted browser example** ships at
 No CDN, no analytics, no external fetch. Requires the `streaming` extra:
 
 ```bash
-python -m pip install "textflowkit[streaming]==0.1.11"
+python -m pip install "textflowkit[streaming]==0.1.13"
 ```
 
 It is **off by default** — with the switch unset the endpoint does not exist — and
@@ -233,6 +233,40 @@ installs `textflowkit-fonts` for offline multilingual PDF rendering:
 python -m pip install 'textflowkit[export]'
 ```
 
+## Windows desktop installer (v0.1.13)
+
+[Download Windows x64 setup](https://github.com/scottconverse/textflowkit/releases/download/v0.1.13/TextFlowKit-0.1.13-windows-x64-setup.exe) · [Matching sources and notices](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.13)
+
+An installer for the existing local browser workspace accompanies core v0.1.13. The Windows installer and its matching FFmpeg source and notice bundles are distributed together through the [v0.1.13 release](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.13). The Python package remains supported for developers and integrations.
+
+The installer 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 installer 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 in the matching source bundles distributed with this release. The installer is
+unsigned, so Windows may show a SmartScreen warning. See the [installer candidate
+notes](https://github.com/scottconverse/textflowkit/blob/main/docs/install.md#windows-desktop-installer-v0113).
+
 ## Python API
 
 The same pipeline used by the CLI and adapters is available to Python callers:
@@ -328,7 +362,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.11/docs/assets/whistle-resume.svg)
+![Whistle bounded block run and durable resume: a decoded PCM WAV is split into 11-second cores with up to 2 seconds of context (each clip ≤ 15 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.13/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
@@ -341,16 +375,26 @@ torch; `openai-whisper` is an explicitly selectable opt-in engine.
   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.
+- **How it works:** long audio is split into 11-second cores with up to 2 seconds
+  of context on each side, so every standalone clip is ≤ 15 seconds. This conservative
+  ceiling avoids reproduced omissions on 30-second inputs. Midpoints provide initial ownership; shared-context matching
+  reconciles duplicate or dropped occurrences when neighboring timestamps
+  disagree. This is not global text deduplication: real repetitions and ambiguous
+  recognition are preserved. The 15-second ceiling and this assembly behavior ship
+  in v0.1.13; neither recovers speech the native recognizer never emits.
+- **Speech-gap check (v0.1.13).** Short gaps between recognized words receive a
+  bounded second listen with different clip boundaries. Extra words are accepted
+  only between matching words on both sides at nearby times. Existing words and
+  repetitions stay intact; long pauses do not trigger this check. The model is
+  still Whistle, with the same pinned weights and telemetry settings.
 - **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
   config, then re-runs only the blocks that were not finished. The durable store
-  still assumes one owning process.
+  still assumes one owning process. The v0.1.13 assembly policy saves raw
+  boundary context with schema 2; old schema-1 partial runs must be restarted,
+  not resumed under the new assembly policy. Existing completed jobs are unchanged.
 - **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
@@ -439,7 +483,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.11'
+python -m pip install 'textflowkit[http,export]==0.1.13'
 textflowkit-ui
 ```
 
@@ -510,7 +554,17 @@ browser interface share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.11 release.** Optional live streaming adds a transport-neutral
+**v0.1.13 release.** Fixes reproduced Whistle speech omissions. Native decode
+inputs are now bounded to 15 seconds (11-second owned cores with up to 2 seconds
+of context per side), short interior speech gaps get a bounded second listen that
+accepts words only between matching timed anchors, and shared-context words are
+reconciled one-to-one before durable resume. Whistle remains the default engine
+with the same pinned model and runtime; fonts remain 0.1.6. Progress schema 2
+stores raw boundary context, so an unfinished partial job from the previous
+26-second-core plan (schema 1) must be restarted instead of resumed; completed
+records are unchanged. The native Windows installer is rebuilt at v0.1.13 and
+distributed with matching FFmpeg sources, notices, hashes and build instructions.
+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
@@ -532,6 +586,22 @@ 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.
 
+**v0.1.12 cleanup (historical).** The opt-in local Ollama proofreading path remains
+as introduced in v0.1.12, covering the local browser UI only; it was not changed by
+v0.1.13. It keeps the published 39-segment cleanup proof from v0.1.12 with no
+audio-accuracy claim: that proof records segment/format handling, not recognition
+accuracy.
+
+**v0.1.13 Whistle coverage, omission, and resume.** The 15-second bound (11-second
+cores plus up to 2 s context per side) fixes reproduced speech omissions on
+30-second inputs; the interior speech-gap second listen accepts extra words only
+between matching timed anchors; shared-context words are reconciled one-to-one
+before durable resume so a partial run rejoins without double ownership. Recognized
+language coverage remains the same accepted set, and nothing here recovers speech
+the native recognizer never emits. See
+[docs/verification/whistle-coverage-20261019.md](https://github.com/scottconverse/textflowkit/blob/main/docs/verification/whistle-coverage-20261019.md)
+for the run-by-run coverage, omission, and resume evidence.
+
 **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
@@ -554,7 +624,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.11.
+for v0.1.13.
 
 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
@@ -573,7 +643,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.11, whose separate release evidence is not supplied by these historical paragraphs.
+historical record as published: it is not re-verified for v0.1.13, 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
@@ -610,3 +680,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 (introduced in v0.1.12)
+
+v0.1.12 adds **opt-in proofreading in the local browser UI only** (introduced in v0.1.12; unchanged in v0.1.13). 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.