textflowkit 0.1.11__tar.gz → 0.1.12__tar.gz

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

@@ -1,5 +1,62 @@
 # 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:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.11
+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
@@ -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.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
@@ -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.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
@@ -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.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
@@ -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.12"
 ```
 
 It is **off by default** — with the switch unset the endpoint does not exist — and
@@ -233,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:
@@ -328,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.11/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
@@ -439,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.11'
+python -m pip install 'textflowkit[http,export]==0.1.12'
 textflowkit-ui
 ```
 
@@ -510,7 +542,10 @@ browser interface share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.11 release.** Optional live streaming adds a transport-neutral
+**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
@@ -554,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.11.
+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
@@ -573,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.11, 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
@@ -610,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.

{textflowkit-0.1.11 → textflowkit-0.1.12}/README.md

@@ -8,7 +8,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.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
@@ -69,7 +69,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.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
@@ -93,7 +93,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.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
@@ -102,7 +102,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.12"
 ```
 
 It is **off by default** — with the switch unset the endpoint does not exist — and
@@ -168,6 +168,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:
@@ -263,7 +295,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 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
@@ -374,7 +406,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.12'
 textflowkit-ui
 ```
 
@@ -445,7 +477,10 @@ browser interface share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.11 release.** Optional live streaming adds a transport-neutral
+**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
@@ -489,7 +524,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.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
@@ -508,7 +543,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.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
@@ -545,3 +580,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.

{textflowkit-0.1.11 → textflowkit-0.1.12}/docs/adapters.md

@@ -1,6 +1,6 @@
 # Developer and integration manual
 
-Current release: [v0.1.11](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.11).
+Current release: [v0.1.12](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.12).
 Start with the [user manual](user-manual.md) for everyday use. Harness versions
 in the compatibility table below identify **historical test sessions**, not
 the version of TextFlowKit currently published.
@@ -22,6 +22,48 @@ API and WebSockets are ephemeral and bypass durable job submission.
    HTTP ───────────►└──────────────────────┘
 ```
 
+## Windows desktop installer (v0.1.12; public EXE pending)
+
+The Windows x86_64 installer packages the existing browser interface for 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. Its bundle includes private embeddable CPython, the UI and HTTP, export, and streaming dependencies, the pinned Whistle model and runtime, and ffmpeg, ffprobe, and Node. It requires no separately installed Python, WSL, or Docker. The Python package remains supported for developers and integrations; Docker remains a separate operator deployment example.
+
+The setup installs per user, adds a Start Menu entry, and offers an
+optional desktop shortcut. Launching it will start the local server and open the
+existing UI at localhost. Administrator rights are not normally required; the
+installer is designed not to change global `PATH` or auto-update. The 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`.
+
+UI data is designed to stay outside the install directory and be preserved on
+upgrade and uninstall. Before either operation, stop the UI server with **Stop
+server** and wait for it to exit. The candidate will block while that server is
+running rather than force-kill it; the stop action drains active jobs, so cancel a
+job first if it should not finish. The installer does not bundle optional
+`openai-whisper` or diarization dependencies; those documented optional features
+remain available to Python package users who install and configure the required
+dependencies separately. Streaming dependencies are bundled, but streaming
+remains opt-in, and physical browser microphone capture has not been verified.
+The installer bundle includes third-party license and notice files,
+including FFmpeg's LGPL notices and corresponding-source information. The exact
+notices and source-distribution details must be checked against the final binaries
+before publication. The candidate is unsigned, so Windows may show a SmartScreen
+warning.
+
+```mermaid
+flowchart LR
+    Setup[Per-user Windows x86_64 installer candidate] --> Runtime[Private embeddable CPython and bundled components]
+    Shortcut[Start Menu or optional desktop shortcut] --> Server[Local server at 127.0.0.1]
+    Runtime --> Server
+    Server <--> Browser[Existing browser UI at localhost]
+    Server --> Core[Existing HTTP adapter and shared TextFlowKit core]
+    Core --> Data[Per-user jobs, uploads, transcripts, and outputs outside install folder]
+```
+
+This is a locally built and tested packaging path for the local UI; it does not turn the public
+static website into a hosted transcription service or change the developer API
+contracts.
+
 ## Resuming and batching
 
 `textflowkit transcribe --resume` reuses completed work, and
@@ -509,7 +551,7 @@ observation rather than forwarding the caller's header, and keep
 
 ## Live microphone streaming (`/stream`, opt-in)
 
-In v0.1.11, native live streaming supports **Windows x86_64 only**. Other live
+In v0.1.12, native live streaming supports **Windows x86_64 only**. Other live
 platforms are unsupported; existing standalone defaults and platform support are
 unchanged. Physical browser microphone capture was not verified. The public site
 is static documentation and serves no streams. Both local server surfaces can
@@ -520,7 +562,7 @@ exist and a connection is refused before any session is allocated - and it needs
 `streaming` extra (`websockets`).
 
 ```powershell
-python -m pip install "textflowkit[streaming]==0.1.11"
+python -m pip install "textflowkit[streaming]==0.1.12"
 # Native Windows PowerShell:
 $env:TEXTFLOWKIT_API_TOKEN="choose-a-long-random-token"
 $env:TEXTFLOWKIT_STREAMING="1"
@@ -560,7 +602,7 @@ supplies FastAPI and uvicorn, and adds no new dependency). It has no public site
 of its own: it is a local app, not a hosted service.
 
 ```bash
-python -m pip install 'textflowkit[http,export]==0.1.11'
+python -m pip install 'textflowkit[http,export]==0.1.12'
 textflowkit-ui                 # serve on 127.0.0.1 and open a browser
 textflowkit-ui --no-browser --port 8901
 ```
@@ -943,3 +985,27 @@ job id immediately means:
 By default the job store is in-memory and bounded (`max_jobs=200`, terminal
 jobs evicted first). Set `TEXTFLOWKIT_DB` to use the durable SQLite store for
 restart-safe jobs and checkpoints. The SQLite store assumes one owning process.
+
+## UI-only proofreading routes (v0.1.12)
+
+These routes belong to the local UI session gate, not the developer HTTP or MCP
+API. POST requires the existing `x-textflowkit-ui-capability` header. Host, peer
+and Origin remain subject to the existing UI restrictions.
+
+| Route | Behavior |
+|---|---|
+| `GET /ui/cleanup/models` | Installed local tags only; selected preference only if installed; never pulls models |
+| `POST /ui/jobs/{id}/cleanup` | Body `{"model":"installed-local-tag"}` (max 4 KiB); completed jobs only; 202 admitted, 409 busy/not complete, 422 model/config/input error |
+| `GET /ui/jobs/{id}/cleanup` | `none`, `running`, `done`, `error` or `stale`; fully validated separate variant and provenance when available |
+| `GET /ui/jobs/{id}/cleanup/download` | Valid current variant as plain TXT attachment; 409 if none/stale |
+
+Cleanup does not modify existing `/api` routes, original job JSON or original
+downloads. Polling is background and job-scoped. There is no cancel endpoint.
+See the user manual for time/token/output limits, crash lease expiry, local-only
+endpoint rules and human review requirements.
+
+A cold local full-UI verification (model unloaded before start) completed 39
+segments in three chunks; four segments changed. The original JSON and segment
+IDs/timestamps were preserved, and visible comparison plus corrected TXT save
+were verified. This validates one workflow run, not accuracy. Review against
+audio; AI guesses are not audio-verified.