python-voiceio 0.3.12__py3-none-any.whl → 0.4.0__py3-none-any.whl

{python_voiceio-0.3.12.dist-info → python_voiceio-0.4.0.dist-info}/METADATA

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 0.3.12
-Summary: Speak → text, locally, instantly.
+Version: 0.4.0
+Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Hugo0/voiceio
 Project-URL: Repository, https://github.com/Hugo0/voiceio
 Project-URL: Issues, https://github.com/Hugo0/voiceio/issues
 Project-URL: Changelog, https://github.com/Hugo0/voiceio/releases
-Keywords: voice,speech-to-text,whisper,linux,windows,dictation,wayland,ibus
+Keywords: voice,speech-to-text,whisper,linux,dictation,wayland,ibus
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: X11 Applications
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: Operating System :: POSIX :: Linux
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Requires-Python: >=3.11
@@ -61,10 +59,18 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://img.shields.io/pepy/dt/python-voiceio)](https://pepy.tech/projects/python-voiceio)
 
-Speak → text, locally, instantly.
+Voice dictation for Linux. Local, yours, and it learns how you speak.
 
 https://github.com/user-attachments/assets/9cf5d1ac-b4bb-4cf8-b775-7a66dc16b376
 
+Open-source, sovereign voice input/output. Your speech is transcribed on your own machine, everything it learns about you stays in local files you own, and it gets better the more you use it.
+
+- **Local & sovereign** — speech is transcribed on-device with [faster-whisper](https://github.com/SYSTRAN/faster-whisper); audio never leaves the machine. Your history, retained audio, corrections, and vocabulary all live in plain local files (JSONL / TOML / txt) you can read, edit, and delete. Zero telemetry. The one honest nuance: two *optional, off-by-default* features send text (never audio) to a cloud LLM you configure yourself — final-transcript polish (`[postcorrect]`) and the weekly correction-mining review.
+- **Improves with use — automatically** — every utterance teaches it your words and names. See [How it learns](#how-it-learns).
+- **Linux-first & hackable** — Wayland/X11, GNOME/KDE/sway/i3, chosen automatically by chain-and-probe backends. It's plain Python you can read in an afternoon and [contribute to](CLAUDE.md).
+
+> **Linux-first.** voiceio is developed and tested daily on Linux (GNOME/Wayland). Windows and macOS ship as **experimental, untested** targets — the code paths exist but are unmaintained and likely broken. See [Experimental platforms](#experimental-platforms).
+
 ## Quick start
 
 ```bash
@@ -102,28 +108,9 @@ voiceio setup
 </details>
 
 <details>
-<summary><strong>Windows</strong></summary>
-
-```powershell
-# Option A: Install with pip (requires Python 3.11+)
-pip install python-voiceio
-voiceio setup
-
-# Option B: Download the installer from GitHub Releases (no Python needed)
-# https://github.com/Hugo0/voiceio/releases
-# Also available as a portable .zip if you prefer no installation.
-```
+<summary><strong>Windows / macOS (experimental)</strong></summary>
 
-Windows uses pynput for hotkeys and text injection. No extra system dependencies required.
-</details>
-
-<details>
-<summary><strong>macOS</strong></summary>
-
-```bash
-pipx install python-voiceio
-voiceio setup
-```
+See [Experimental platforms](#experimental-platforms) below — these builds are untested and unmaintained.
 </details>
 
 <details>
@@ -152,7 +139,35 @@ hotkey → mic capture → whisper (local) → text at cursor
           pre-buffered   streaming        IBus / clipboard
 ```
 
-Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via [faster-whisper](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals.
+Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via [faster-whisper](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals. It runs in real time on a modern CPU and ships with model tiers from `tiny` to `large-v3`.
+
+## How it learns
+
+Most dictation tools transcribe the same way on day 100 as on day 1. voiceio adapts to *you* — your jargon, names, and accent — entirely from data that never leaves your machine.
+
+```mermaid
+flowchart LR
+    subgraph live ["every utterance"]
+        A["🎙️ dictate"] --> B["store audio + raw text\n+ confidence (local)"]
+        A --> C["hotwords + recent context\nbias the Whisper decoder"]
+        A --> D["optional LLM pass fixes\nmisheard proper nouns"]
+    end
+    subgraph weekly ["weekly, in the background"]
+        E["mine history for recurring errors\n→ learn corrections + vocabulary\n(safety-gated, multi-vote)"] --> F["teacher model replays your audio\n→ audits what was learned"]
+        F -->|"bad rule"| G["auto-retired"]
+        F -->|"quality regressed"| H["whole week rolled back"]
+    end
+    B --> E
+    F -->|"confirmed"| C
+```
+
+1. **Capture** — every utterance stores its audio, raw text, and confidence in local files.
+2. **Bias** — your vocabulary and recent context steer the Whisper decoder (hotwords / prompt) on every recording.
+3. **Contextual fix** — an optional LLM pass repairs misheard proper nouns using surrounding context.
+4. **Mine** — a weekly background job scans your history for recurring errors and auto-learns corrections and vocabulary. Multi-vote adjudication and a protected-languages guard (for bilingual users) keep it safe; it never asks you to triage.
+5. **Audit** — a teacher model (a larger Whisper) replays your retained audio to verify what was learned. Bad rules are retired automatically, and a system-level drift metric rolls back an entire week of learning if quality regressed.
+
+Rules are always **probationary, never tenured** — anything that stops helping is dropped. Your only touchpoint is an occasional desktop notification telling you what was learned.
 
 ## Features
 
@@ -202,7 +217,7 @@ voiceio uninstall        Remove all system integrations
 `voiceio setup` handles everything interactively. To tweak later, edit the config file or override at runtime:
 
 - Linux/macOS: `~/.config/voiceio/config.toml`
-- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml`
+- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml` (see [Experimental platforms](#experimental-platforms))
 
 ```bash
 voiceio --model large-v3 --language auto -v
@@ -224,12 +239,12 @@ voiceio logs             # check debug output
 | Hotkey doesn't work on Wayland | `sudo usermod -aG input $USER` then log out and back in |
 | Transcription too slow | Use a smaller model: `voiceio --model tiny` |
 | Want to start fresh | `voiceio uninstall` then `voiceio setup` |
-| Windows: antivirus blocks hotkeys | pynput uses global keyboard hooks — add an exception for voiceio |
-| Windows: no sound feedback | Check `voiceio logs` for audio device info |
-| macOS issues | Experimental — consider [aquavoice.com](https://aquavoice.com/) or contribute a PR |
+| Windows / macOS issues | These platforms are experimental and untested — see [Experimental platforms](#experimental-platforms) |
 
 ## Platform support
 
+voiceio targets **Linux**. That's what it's developed and tested against.
+
 | Platform | Status | Text injection | Hotkeys | Streaming preview |
 |----------|--------|---------------|---------|-------------------|
 | Ubuntu / Debian (GNOME, Wayland) | **Tested daily** | IBus | evdev / GNOME shortcut | Yes |
@@ -237,11 +252,22 @@ voiceio logs             # check debug output
 | Fedora (GNOME) | Supported | IBus | evdev / GNOME shortcut | Yes |
 | Arch Linux | Supported | IBus | evdev | Yes |
 | KDE / Sway / Hyprland | Should work | IBus / ydotool / wtype | evdev | Yes |
-| Windows 10/11 | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
-| macOS | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
 
 voiceio auto-detects your platform and picks the best available backends. Run `voiceio doctor` to see what's working on your system.
 
+## Experimental platforms
+
+Windows and macOS code paths exist, but they are **experimental, untested, and unmaintained** — the maintainer only develops on Linux, so they may be broken at any given time. No parity with Linux is promised. Contributions are welcome, but please don't file bugs expecting a fix.
+
+| Platform | Status | Text injection | Hotkeys | Streaming preview |
+|----------|--------|---------------|---------|-------------------|
+| Windows 10/11 | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+| macOS | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+
+- **Windows:** `pip install python-voiceio` then `voiceio setup` (pynput handles hotkeys + text injection; no system deps). Prebuilt installers may appear on [GitHub Releases](https://github.com/Hugo0/voiceio/releases).
+- **macOS:** `pipx install python-voiceio` then `voiceio setup`. If it doesn't work for you, consider [aquavoice.com](https://aquavoice.com/) or contribute a PR.
+- Config lives at `%LOCALAPPDATA%\voiceio\config\config.toml` (Windows) or `~/.config/voiceio/config.toml` (macOS).
+
 ## Uninstall
 
 ```bash
@@ -275,7 +301,7 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and [open issues](
 - [x] Voice commands — "new line", "new paragraph", "scratch that", punctuation by name
 - [x] Custom vocabulary / personal dictionary (bias Whisper via `initial_prompt`)
 - [x] Smart punctuation & capitalization post-processing
-- [x] Windows support
+- [x] Windows support (experimental, untested)
 - [x] System tray icon with animated states
 - [x] Auto-stop on silence
 

{python_voiceio-0.3.12.dist-info → python_voiceio-0.4.0.dist-info}/RECORD

@@ -1,35 +1,40 @@
-python_voiceio-0.3.12.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
-voiceio/__init__.py,sha256=uzDtUmN3o6XGGV0Pkoi7vJCijlJJCOYCmLl8900CcXg,23
+python_voiceio-0.4.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
+voiceio/__init__.py,sha256=42STGor_9nKYXumfeV5tiyD_M8VdcddX7CEexmibPBk,22
 voiceio/__main__.py,sha256=xT5QCGGreYMisHO7Lh_Y-xAQ2TOzG2D7npKknGNcWSY,53
-voiceio/app.py,sha256=AfpGBpk-uT4QFTFys9mm-O3cOl_V1TESJLoJJYfC1sY,46427
-voiceio/autocorrect.py,sha256=qEug82DDrxKamnU0HSbp-Llo08RvecZreLSwA2HRJmE,9982
+voiceio/app.py,sha256=V6XGwWvvB6C6detltWW4OGMKWYUZPcAFcWUL4gXdqBY,53130
+voiceio/audit.py,sha256=vX3x-YAhmt6EZYRZd0_6wvTquZu5sxGMvH45BhSBnCk,14915
+voiceio/autocorrect.py,sha256=jGsglEYwAHWk2uWedeEZzyAMW2LWO_8nQGZgrWYy4Dc,26552
+voiceio/autocorrect_state.py,sha256=BNzdHP5slcOV_-OU4MlaKE7xgVJzrPncsYFK30JWTs8,6858
 voiceio/backends.py,sha256=-rs1YhPblub4NjFb6qCD7Ih9FqBRXtPuvjVv9bQoQ1w,368
-voiceio/cli.py,sha256=lTNhKiEsq0TKm6sdRx4GN_7mdAiNOacXwNuOSYWQyEg,46993
+voiceio/cli.py,sha256=a27O_1IIn6jaV3Q3f5w9BXtsg3zAAdNi0nDlGx2drU4,65822
 voiceio/clipboard_read.py,sha256=266u_QoJb_n3iLuy5fbccPZJfpYpPkjsNtZxjDNmqAE,2062
 voiceio/commands.py,sha256=Vhtn8s5G5OcCbRN44YZ-_14Fa85ISXl_3Ix-KqSHs2A,4694
-voiceio/config.py,sha256=VNOBOQmTYXyzP0l_FVvrKJAAF9el_yABN5i4VHasGSg,5975
-voiceio/corrections.py,sha256=pSTmk4QVoc419GuOIcy05Z99U2K8HWR1-nVzyTvI8Ak,6164
+voiceio/config.py,sha256=TORjFrY6VDb36CbX9W-U4uDwRaEdcUQY369-uV_EF8U,8137
+voiceio/corrections.py,sha256=7moKhkVvo5CZU1mZobV2-MajkcHiwliKBY1dSBFh0w0,7445
 voiceio/demo.py,sha256=lhVMdBC-9uh25-7AXl30CVrmpL53KeGrZhY4HAtuxDI,8626
-voiceio/feedback.py,sha256=gku30BFjOKk-5I2Ba6ZUWxWqlz2ImGwbhSl1FVLtHls,5016
+voiceio/feedback.py,sha256=TyUy_wy5HNTO0u3opx58aaPXz7mAqeN98UbNdLfnoiw,5136
 voiceio/health.py,sha256=aJcULea1F06iUjjmREGcD-uO_JF_7zar3b5CFIR_uUM,15204
 voiceio/hints.py,sha256=dmoiMAJ0YGTWwFc9kIPvEs_BQJN7UEUiwYuLUD_GoQQ,1415
-voiceio/history.py,sha256=2r1sP5DrjVK-PH_s9GpLzGWitoy6MimMZSZBbC23BsY,1891
+voiceio/history.py,sha256=bku01AmAkbpl376ud9Ldjp-F-gYKyH1RXoHV5_cxK5s,2699
 voiceio/llm.py,sha256=_m13jodMVB1iEtze3VGkBCafkg85OssTPBEVyaRabgA,9250
-voiceio/llm_api.py,sha256=2YqPoHllCKQ6DcQElrI_p61XY-vNbmI8wbNpfiRmoIk,5426
+voiceio/llm_api.py,sha256=Vjs7x_qphd95TmdPELbMlUdenKdtblusZVFm2G8FQJE,6159
 voiceio/numbers.py,sha256=MP8jag4_F2OqUU5H14KzOmR9L8gWg48yQhLoUbGg_YI,8376
 voiceio/pidlock.py,sha256=RInlF_8H7wR0nqkdlhUfxYs7OGzHIvb5p-XDjjQSTNg,619
 voiceio/platform.py,sha256=5Z_bUVDrU3-tuGQW6zaW_Q5EAER4_y07-wDS3d132fU,7870
-voiceio/postprocess.py,sha256=3xN5lDLxHGcauYQs6yj5G6lPjghpRew1Ssa54MtZSxQ,2524
-voiceio/prompt.py,sha256=mVq2U7srTf2d_vmIpA_VkzxHMzvqjn78G8-meLFj7Tw,2499
-voiceio/recorder.py,sha256=jIXcEdW_OWuzAfaAnT4hB-1AGdOtovazloelKQhBf4w,10878
-voiceio/service.py,sha256=JFJ1_GuZA49pojs9xs2NNhz7jR8-u8YBI7ZDnfyQoQ4,9923
-voiceio/streaming.py,sha256=TLBqLDZjJbCDWslvJWDA0YDqAFC9HVQVa2y-EZiwQaA,11039
-voiceio/transcriber.py,sha256=tZT7FWA3s1LD0Yy3mmbdzq9Cn-WvnuLJCs61ica7hJ0,6186
-voiceio/vad.py,sha256=k821wp9dO8SxAAiiuEcreZL-6d4vLLk0DyjXhiAp8EU,4310
-voiceio/vocabulary.py,sha256=1sGjMSZx4up9MTxgEH0qcet9DnKQaVMVwPm2bD1QDPc,1731
-voiceio/wizard.py,sha256=4ql9fH6Tq16msEo8SV0TM-RtV5KsZI0_nA_bX3Fuc6s,61823
+voiceio/postcorrect.py,sha256=S4aIbMjeYny8-oo7kUQM-6YZB8IDAy7vi80-F1qjwRc,7860
+voiceio/postprocess.py,sha256=9grkq3I6XgiQV6ZQbIw2_fOUe57tzC7GBPvLXqhhdTs,2979
+voiceio/prompt.py,sha256=9iza8KoQxvO_U9NPMJ8Ep7j-zkIs9nW8N5sacCRpsEk,2904
+voiceio/recorder.py,sha256=sTxkKpaGoixmnWnNmygb7dwifu5aZZAXGqRgH1pketE,12026
+voiceio/retention.py,sha256=MhXW3BOw8m50-q6ty6zjXic95VfLjmr6nUQytRuVPK0,2838
+voiceio/service.py,sha256=jqX1opZyQh_dOJMK4bVf8Aoei0zOuuk1Ogta9BXTWGY,12106
+voiceio/snapshots.py,sha256=bm-lzIeYucDUDlPBZiFiWd-jyB2I6Ft1jRANZCO6go4,2351
+voiceio/streaming.py,sha256=epPaQbJLDP8U18RR7LJaQ_KuYmlx2E1gv2lJsJNkloo,11702
+voiceio/transcriber.py,sha256=dslLArdozpqYe2ddTh7KZCXT35TnDpv1dCnRsVZkDjQ,8109
+voiceio/vad.py,sha256=72_ICk4jSuSPYvTHdHYtHzY8W5uaGEOz5FTdqkolJi8,5327
+voiceio/vocabulary.py,sha256=eGV7QZs3tN6Cw5YpyoZsVEk2M5fJvie1n2XFi9CD4hw,6321
+voiceio/wizard.py,sha256=GEG0ykw52kF81CIA9JlatA0rSTxIxapmCMbTuOzA4EM,63350
 voiceio/wordfreq.py,sha256=2UMjW1xIFqo5EchXzsXPizUhRb9N18CVgjnXso1wsgw,2382
-voiceio/worker.py,sha256=Xo1GK85MrGhuZj4fXQEBtI0UFiZvWAgjYqKzxIIAzR4,1656
+voiceio/worker.py,sha256=M6e4s6P0-4UGQzw0j8Mq68nypvwZleOSwuRhjuOqlVE,2563
 voiceio/hotkeys/__init__.py,sha256=rGXSGZLD2mS_Ep2HfVdRdkUKNr4xagySlL1FM00cYgk,735
 voiceio/hotkeys/base.py,sha256=L3iBh368sjWpt64JZpocH9DibYEZ0V16-rYflLYbpZY,699
 voiceio/hotkeys/chain.py,sha256=8pvPhipmxWwmGG9DRXy8dlEKTPFILxNzYO-adcvw5Ps,2800
@@ -64,8 +69,8 @@ voiceio/typers/pynput_type.py,sha256=DTtkT59M-EKOAlTNkvcZrRvf_Fq52OpI8S5t_8S-QAY
 voiceio/typers/wtype.py,sha256=d1wG-HZdYDQxXIysV_Xvk9HixDpaJgl3VEoKbP5vhIs,1786
 voiceio/typers/xdotool.py,sha256=dh1zhPqUT8ihJahJ7ZKm6PtfYY087UAzADx664DvQOM,1356
 voiceio/typers/ydotool.py,sha256=OQPNmaA2DxTAaJKBYpWzh_R6JnPSfum9OpmF7KvKYD4,3728
-python_voiceio-0.3.12.dist-info/METADATA,sha256=XoDDYdAaq41kV6lQmxVgOZ50CNCVL7_qx4nD303-rjc,11562
-python_voiceio-0.3.12.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_voiceio-0.3.12.dist-info/entry_points.txt,sha256=U64fA65zxzyLoC8bgbn2ztQVWHLsc0o0H0qCk1J9DMc,218
-python_voiceio-0.3.12.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
-python_voiceio-0.3.12.dist-info/RECORD,,
+python_voiceio-0.4.0.dist-info/METADATA,sha256=u1G5NlIoTB4K8BDw_phICZPzzQR9ov4WaSadS3kbMn8,15381
+python_voiceio-0.4.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_voiceio-0.4.0.dist-info/entry_points.txt,sha256=U64fA65zxzyLoC8bgbn2ztQVWHLsc0o0H0qCk1J9DMc,218
+python_voiceio-0.4.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
+python_voiceio-0.4.0.dist-info/RECORD,,

{python_voiceio-0.3.12.dist-info → python_voiceio-0.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (83.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

voiceio/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.12"
+__version__ = "0.4.0"

voiceio/app.py

@@ -22,7 +22,7 @@ from voiceio.streaming import StreamingSession
 from voiceio.transcriber import Transcriber
 from voiceio.typers import chain as typer_chain
 from voiceio.vad import load_vad
-from voiceio.vocabulary import load_vocabulary
+from voiceio.vocabulary import VocabularyLoader
 
 if TYPE_CHECKING:
     from voiceio.typers.base import TyperBackend
@@ -92,6 +92,12 @@ def _import_graphical_env() -> None:
 
 _HEALTH_CHECK_INTERVAL = 10  # seconds between health checks
 
+# Whisper's decoder has a hard 448-token sequence budget shared by hotwords,
+# initial_prompt AND the transcription output. Hotwords + prompt must stay
+# well under half of it or output gets truncated mid-utterance.
+# ~600 chars ≈ 150 tokens.
+_HOTWORDS_MAX_CHARS = 600
+
 
 class _State(enum.Enum):
     IDLE = "idle"
@@ -154,19 +160,21 @@ class VoiceIO:
         vad = load_vad(cfg.audio)
         self.recorder = AudioRecorder(cfg.audio, vad=vad)
 
-        vocab = load_vocabulary(cfg.model)
         self._corrections = CorrectionDict()
-        # Merge correction targets into vocabulary for Whisper conditioning
-        vocab_terms = self._corrections.vocabulary_terms()
-        if vocab_terms:
-            extra = ", ".join(vocab_terms)
-            vocab = f"{vocab}, {extra}" if vocab else extra
-        if vocab:
-            self.transcriber.set_initial_prompt(vocab)
+        # mtime-cached loader so `voiceio correct` vocabulary edits are picked
+        # up per-recording without a daemon restart.
+        self._vocab_loader = VocabularyLoader(cfg.model)
+        # Vocabulary biases the decoder via hotwords; initial_prompt carries
+        # recent-transcript context (rebuilt per recording via PromptBuilder).
+        self._hotwords = ""
+        self._refresh_hotwords()
+        from voiceio.prompt import PromptBuilder
+        self._prompt_builder = PromptBuilder()
 
         self._command_processor = CommandProcessor(enabled=cfg.commands.enabled, editing=cfg.commands.editing)
         self._cleanup = cfg.output.punctuation_cleanup
         self._number_conversion = cfg.output.number_conversion
+        self._voice_input_prefix = cfg.output.voice_input_prefix
         self._streaming = cfg.output.streaming
 
         # LLM post-processing (optional, requires Ollama)
@@ -180,11 +188,28 @@ class VoiceIO:
             else:
                 log.warning("LLM enabled but Ollama not available (will retry)")
 
+        # Constrained LLM post-correction (optional, cloud API, final pass only)
+        self._postcorrect = None
+        if cfg.postcorrect.enabled:
+            from voiceio.postcorrect import PostCorrector
+            self._postcorrect = PostCorrector(cfg)
+            if self._postcorrect.is_available():
+                log.info("PostCorrect: %s", cfg.postcorrect.model or cfg.autocorrect.model)
+            else:
+                log.warning("PostCorrect enabled but no API key resolved (disabled)")
+
         # Explicit state machine
         self._state = _State.IDLE
         self._generation = 0          # incremented on every stop; leaked threads check this
         self._session: StreamingSession | None = None
         self._record_start: float = 0
+        self._last_clip_warn: float = 0
+        self._context_title: str | None = None
+        # Prune retained recordings over the size cap (startup housekeeping)
+        from voiceio import retention
+        threading.Thread(
+            target=retention.prune, args=(cfg.data,), daemon=True,
+        ).start()
 
         # Hotkey deduplication
         self._hotkey_lock = threading.Lock()
@@ -265,6 +290,32 @@ class VoiceIO:
             # The generation counter ensures the old finalizer exits cleanly.
             self._do_start()
 
+    def _refresh_hotwords(self) -> None:
+        """Rebuild Whisper hotwords from vocabulary + correction targets.
+
+        The vocabulary read is mtime-cached (only a `stat` when unchanged), and
+        `set_hotwords` is called only when the merged string actually changed,
+        so this stays cheap enough to run on every recording start.
+        """
+        vocab = self._vocab_loader.get()
+        # Only merge RARE correction targets (proper nouns, technical terms):
+        # common-word targets ("review", "company") add nothing to decoder bias
+        # and hundreds of them blow Whisper's 448-token prompt+output budget,
+        # which truncates transcriptions mid-utterance.
+        from voiceio.wordfreq import is_common
+        vocab_terms = [
+            t for t in self._corrections.vocabulary_terms()
+            if not is_common(t, self.cfg.model.language)
+        ]
+        if vocab_terms:
+            extra = ", ".join(vocab_terms)
+            vocab = f"{vocab}, {extra}" if vocab else extra
+        vocab = vocab[:_HOTWORDS_MAX_CHARS]
+        if vocab != self._hotwords:
+            self._hotwords = vocab
+            if vocab:
+                self.transcriber.set_hotwords(vocab)
+
     def _do_start(self) -> None:
         """Transition to RECORDING."""
         # Pre-flight: ensure audio stream is healthy before recording
@@ -283,6 +334,12 @@ class VoiceIO:
         self._state = _State.RECORDING
         self._activate_ibus()
         self._corrections.load()  # hot-reload corrections on each recording
+        self._refresh_hotwords()  # hot-reload vocabulary (mtime-cached)
+        self.transcriber.set_initial_prompt(self._prompt_builder.build())
+        if self.cfg.data.capture_context:
+            # Snapshot the dictation target now — focus may change by finalize
+            self._context_title = None
+            threading.Thread(target=self._capture_context, daemon=True).start()
         self._record_start = time.monotonic()
         self.recorder.start()
         self.recorder.set_on_auto_stop(self._on_auto_stop)
@@ -297,7 +354,9 @@ class VoiceIO:
                 language=self.cfg.model.language,
                 commands=self._command_processor,
                 corrections=self._corrections,
+                postcorrect=self._postcorrect,
                 llm=self._llm,
+                voice_input_prefix=self._voice_input_prefix,
                 on_typer_broken=self._on_typer_broken,
             )
             self._session.start()
@@ -314,6 +373,16 @@ class VoiceIO:
         self.recorder.set_on_auto_stop(None)
         audio = self.recorder.stop()
         tray.set_recording(False)
+        self._warn_if_clipping()
+
+        if self._postcorrect is not None:
+            # Freshest context for the finalize pass: this recording's window
+            # title (captured at start) and the latest transcripts/vocabulary.
+            self._postcorrect.set_context(
+                vocabulary=self._hotwords,
+                recent=self._prompt_builder.recent(3),
+                title=self._context_title,
+            )
 
         if self._streaming and self._session is not None:
             self._state = _State.FINALIZING
@@ -343,6 +412,61 @@ class VoiceIO:
 
         self._deactivate_ibus()
 
+    def _capture_context(self) -> None:
+        from voiceio import retention
+        self._context_title = retention.active_window_title()
+
+    def _retention_extra(self, audio: np.ndarray | None) -> dict:
+        """Save the utterance audio (before transcription, so it survives
+        worker timeouts) and collect context for the history entry."""
+        from voiceio import retention
+        audio_name = None
+        if audio is not None:
+            audio_name = retention.save_audio(audio, time.time(), self.cfg.data)
+        return {
+            "audio": audio_name,
+            "context": self._context_title if self.cfg.data.capture_context else None,
+            "model": self.cfg.model.name,
+        }
+
+    def _strip_voice_prefix(self, text: str) -> str:
+        """Remove the configured voice-input prefix before persisting.
+
+        The prefix is presentation for the target app, not dictated content;
+        storing it would pollute vocabulary mining and correction analysis.
+        """
+        if self._voice_input_prefix and text.startswith(self._voice_input_prefix):
+            return text[len(self._voice_input_prefix):].lstrip()
+        return text
+
+    _CLIP_RATIO_WARN = 0.005   # >0.5% of samples in flat-top runs
+    _CLIP_WARN_INTERVAL = 300  # seconds between warnings
+
+    def _warn_if_clipping(self) -> None:
+        """Warn (rate-limited) when the mic input is saturating the ADC.
+
+        Clipping cannot be repaired in software — the gain must come down
+        before the ADC — so tell the user how to lower it.
+        """
+        meter = self.recorder.get_meter()
+        if meter["clip_ratio"] < self._CLIP_RATIO_WARN:
+            return
+        now = time.monotonic()
+        if now - self._last_clip_warn < self._CLIP_WARN_INTERVAL:
+            return
+        self._last_clip_warn = now
+        log.warning(
+            "Microphone is clipping (%.1f%% of samples saturated, peak %.2f) — "
+            "transcription quality suffers. Lower the input gain, e.g.: "
+            "wpctl set-volume @DEFAULT_AUDIO_SOURCE@ 10%%-",
+            meter["clip_ratio"] * 100, meter["peak"],
+        )
+        from voiceio import feedback
+        feedback.notify(
+            "VoiceIO: microphone too loud",
+            "Input is clipping — lower your mic gain in system sound settings.",
+        )
+
     # ── Background work ─────────────────────────────────────────────────
 
     def _finalize_streaming(
@@ -350,14 +474,23 @@ class VoiceIO:
         elapsed: float, gen: int,
     ) -> None:
         """Run final transcription and commit in background thread."""
+        extra = self._retention_extra(audio)
         final_text = session.stop(audio)
         if self._generation != gen:
             log.debug("Finalize cancelled (gen %d, current %d)", gen, self._generation)
             return
         if final_text:
             self._play_feedback(final_text)
+            stored = self._strip_voice_prefix(final_text)
+            self._prompt_builder.add_transcript(stored)
             from voiceio import history
-            history.append(final_text)
+            history.append(
+                stored,
+                raw=session.raw_final_text,
+                segments=session.final_segments,
+                duration=elapsed,
+                extra=extra,
+            )
         log.info("Streaming done (%.1fs): '%s'", elapsed, final_text)
         # Transition to IDLE under lock to avoid racing with _toggle
         with self._hotkey_lock:
@@ -370,7 +503,10 @@ class VoiceIO:
         try:
             if self._generation != gen:
                 return
-            text = self.transcriber.transcribe(audio)
+            extra = self._retention_extra(audio)
+            raw = self.transcriber.transcribe(audio, final=True)
+            segments = self.transcriber.last_segments
+            text = raw
             if self._generation != gen:
                 return
             if text:
@@ -382,7 +518,9 @@ class VoiceIO:
                     language=self.cfg.model.language,
                     commands=self._command_processor,
                     corrections=self._corrections,
+                    postcorrect=self._postcorrect,
                     llm=self._llm,
+                    voice_input_prefix=self._voice_input_prefix,
                     final=True,
                 )
                 if abort:
@@ -390,8 +528,16 @@ class VoiceIO:
                 if text:
                     self._type_with_fallback(text)
                     self._play_feedback(text)
+                    stored = self._strip_voice_prefix(text)
+                    self._prompt_builder.add_transcript(stored)
                     from voiceio import history
-                    history.append(text)
+                    history.append(
+                        stored,
+                        raw=raw,
+                        segments=segments,
+                        duration=len(audio) / self.recorder.sample_rate,
+                        extra=extra,
+                    )
                     log.info("Typed: '%s'", text)
         except Exception:
             log.exception("Processing failed")