v2 rebuild: GDI+ single-surface UI, self-calibrating progress, compact push-to-talk, GGML+Whisper integration

dev-task-list.md

@@ -0,0 +1,321 @@
+# Win Dictation — Developer Task List
+
+A prioritised, junior-friendly backlog to finish polishing the app. Each task says **what**, **which files**, **steps**, **the code** (inline, or a pointer to the verbatim block in a companion doc), and **how to know it's done**.
+
+**Companion docs (full code lives here — don't retype, copy from them):**
+- `ARCHITECTURE-AND-DEVGUIDE.md` — Part B1 (chrome removal), Part B2 (progress + ETA). Verbatim code.
+- `MODERN-UI-AND-FIXES.md` — the modern UI design + GDI+ helpers.
+- `FINDINGS-FIXES-TESTS.md` — the test harness (`tests/test_core.cpp`).
+
+**Baseline (already done — do NOT redo):** batch record-then-transcribe; crash fixes (null-context guard, `g_modelOk`, `g_initializing`, `m_cfg_mtx`); append behaviour (`text_util.h`); no-hide + safe auto-paste; Clear button; `run_inference`/`transcribe_sync` refactor; modern dark UI (GDI+, rounded panel, owner-draw buttons, custom VU, dark caption); resizable window; `test-core` CMake target.
+
+**Conventions:** Effort = XS (<30 min) · S (≤2 h) · M (half-day) · L (1–2 days). Do phases in order; tasks within a phase are mostly independent unless "Depends on" says otherwise. After every task: `cmake --build build --config Release` must succeed with **zero new warnings**, and the app must still launch.
+
+**Color tokens (already in `main.cpp`, reuse — never hard-code hex elsewhere):** `C_BG #0F1115`, `C_SURFACE #181B22`, `C_SURFACEHI #20242D`, `C_BORDER #262B36`, `C_TEXT #E7E9EE`, `C_TEXTDIM #9AA0AB`, `C_ACCENT #6E8BFF`, `C_DANGER #FF5C5C`, `C_GOOD #46D39A`.
+
+---
+
+## Phase 0 — Repo hygiene (do first; clears traps)
+
+### Task 0.1 — Delete the stale `src/CMakeLists.txt`
+- **Goal:** Remove a build file that references **removed** APIs (`init()`, `is_using_gpu()`) and a `test-audio` target the real build ignores. The authoritative build is the **root** `CMakeLists.txt`.
+- **Files:** `src/CMakeLists.txt` (delete).
+- **Steps:** Confirm `build.ps1` configures from repo root (`-S $RepoRoot`). It does. Delete `src/CMakeLists.txt`.
+- **Done when:** Clean build from root still works; no other file `add_subdirectory(src)`.
+- **Effort:** XS
+
+### Task 0.2 — Remove the broken `src/test-audio.cpp` (replaced in Phase 4)
+- **Goal:** `src/test-audio.cpp` calls `m_transcriber.init(...)` / `is_using_gpu()` which no longer exist — it cannot compile. It's superseded by `tests/test_core.cpp` (Task 4.1).
+- **Files:** `src/test-audio.cpp` (delete), `src/record-test-audio.ps1` (keep — still useful for capturing WAVs), `src/TESTING.md` (mark superseded in Task 4.4).
+- **Done when:** No target references `test-audio.cpp`.
+- **Effort:** XS
+
+### Task 0.3 — Create the `tests/` folder + placeholder
+- **Goal:** The root `CMakeLists.txt` already declares `add_executable(test-core tests/test_core.cpp ...)`, but the file doesn't exist yet → configure fails if anyone builds `test-core`.
+- **Steps:** Create `tests/` and add `tests/test_core.cpp` (full content in Task 4.1). Until then, the `test-core` target can stay; just don't build it.
+- **Done when:** `tests/test_core.cpp` exists and `cmake --build build --target test-core` compiles (after Task 4.1).
+- **Effort:** XS · **Depends on:** 4.1 for real content
+
+---
+
+## Phase 1 — Visual polish & assets
+
+### Task 1.1 — App icon asset (custom)
+- **Goal:** Replace the placeholder icon with a clean, modern app icon used for the window, taskbar, and tray.
+- **Files:** `assets/icon-source.png` (new, 1024×1024), `src/icon.ico` (generated), `src/convert_icon.py` (fix paths), `src/win-dictation.rc` (already references `101 ICON "icon.ico"`).
+- **Design spec:** Flat, minimal. A single rounded **microphone** glyph, centered, on a dark charcoal rounded-square (`#15171C`). Mic filled with the indigo accent (`#6E8BFF`), subtle top-down gradient to `#5B7BFF`. No text. Must read clearly at **16×16**. Keep ~12% padding around the glyph.
+  - Ready-to-use generation prompt (AI image tool): *"Minimalist modern app icon, a single simple microphone glyph centered on a dark charcoal rounded square, microphone filled indigo #6E8BFF with a soft vertical gradient, flat design, crisp clean edges, no text, high contrast, legible at small sizes, 1024×1024."*
+  - Or design in Figma/Inkscape and export 1024×1024 PNG.
+- **Steps:**
+  1. Put the source PNG at `assets/icon-source.png`.
+  2. Fix `convert_icon.py` to use real paths and multi-size output:
+     ```python
+     from PIL import Image
+     img = Image.open("assets/icon-source.png").convert("RGBA")
+     img.save("src/icon.ico", format="ICO",
+              sizes=[(256,256),(64,64),(48,48),(32,32),(16,16)])
+     print("wrote src/icon.ico")
+     ```
+  3. Run it (`python src/convert_icon.py` from repo root). Confirm `src/icon.ico` exists.
+  4. Rebuild; the resource compiler picks up `src/icon.ico` via the `.rc`.
+- **Done when:** The new icon shows on the title bar, taskbar, Alt-Tab, and tray — sharp at all sizes.
+- **Effort:** S
+
+### Task 1.2 — Tray icon reflects recording state (optional but nice)
+- **Goal:** When recording (window may be hidden), the **tray** icon turns red so state is visible at a glance.
+- **Files:** `assets/icon-rec-source.png` (new), `src/icon-rec.ico`, `src/win-dictation.rc` (add `102 ICON "icon-rec.ico"`), `src/main.cpp`.
+- **Steps:**
+  1. Create a red variant of the icon (mic in `#FF5C5C`). Convert to `src/icon-rec.ico` (same sizes), add `102 ICON "icon-rec.ico"` to the `.rc`.
+  2. In `main.cpp`, load both icons once: `HICON g_icoIdle, g_icoRec;` via `LoadIcon(hInst, MAKEINTRESOURCE(101/102))`.
+  3. Add a helper `void SetTrayIcon(bool rec){ nid.uFlags = NIF_ICON; nid.hIcon = rec?g_icoRec:g_icoIdle; Shell_NotifyIcon(NIM_MODIFY,&nid); }`.
+  4. Call `SetTrayIcon(true)` when recording starts, `SetTrayIcon(false)` on stop/cancel/result.
+- **Done when:** Start recording, hide the window — the tray icon is red; after transcription it returns to normal.
+- **Effort:** S · **Depends on:** 1.1
+
+### Task 1.3 — Kill the button hairlines + focus rectangles (B1.1)
+- **Goal:** Remove the thin light line around *Pinned* and the left/top lines on Copy/Paste/Clear.
+- **Files:** `src/main.cpp`; link `uxtheme.lib`.
+- **Steps (full code in `ARCHITECTURE-AND-DEVGUIDE.md` §B1.1):**
+  1. Add `#include <uxtheme.h>` and `#pragma comment(lib, "uxtheme.lib")`.
+  2. After creating each owner-draw button (Record, Pin, Copy, Paste, Clear), call `SetWindowTheme(hBtn, L"", L"");` (before/after `SetWindowSubclass` is fine).
+  3. Add `WS_CLIPCHILDREN` to the main window style in `CreateWindowExW`.
+  4. After all controls are created (end of the create block), call once:
+     `SendMessageW(hMainWnd, WM_CHANGEUISTATE, MAKEWPARAM(UIS_SET, UISF_HIDEFOCUS), 0);`
+- **Done when:** No hairline around any button; tabbing between controls draws no dotted focus rect.
+- **Effort:** S
+
+### Task 1.4 — Replace comboboxes with custom dropdowns (B1.2)
+- **Goal:** Remove the native Windows dropdown button (the "second arrow") on the mic + model selectors.
+- **Files:** `src/main.cpp`.
+- **Steps (full code — `DrawSelect`, `PopupProc`, `ShowSelectPopup`, `WM_APP_SELECT` — in `ARCHITECTURE-AND-DEVGUIDE.md` §B1.2):**
+  1. Add label/selection state: `std::vector<std::wstring> g_audioItems; int g_audioSel=0;` and `g_modelItems`/`g_modelSel`. Populate them in `RefreshAudioDevices`/`RefreshModelList` (keep populating `g_modelComboPaths` in parallel).
+  2. Replace the two `COMBOBOX` creations with `BS_OWNERDRAW` buttons `ID_SEL_AUDIO`/`ID_SEL_MODEL`; subclass with `BtnProc`; `SetWindowTheme(.., L"", L"")`.
+  3. Add `#define WM_APP_SELECT (WM_USER + 5)` and `#define ID_SEL_AUDIO/ID_SEL_MODEL`.
+  4. Paste `DrawSelect`, route both IDs in `WM_DRAWITEM`. Paste `PopupProc` + `ShowSelectPopup`. On `WM_COMMAND` for the two IDs call `ShowSelectPopup(...)`. Handle `WM_APP_SELECT` to apply the choice (set `capture_id` / reload model).
+  5. Delete the now-unused `DrawCombo`, `WM_MEASUREITEM` combo branch, and `WM_CTLCOLORLISTBOX`.
+  6. Update `LayoutControls` to position `ID_SEL_AUDIO`/`ID_SEL_MODEL` where the combos were.
+- **Done when:** Each selector shows exactly one (our) chevron, opens a dark rounded popup, hover highlights rows, selecting reloads the model / switches mic, and clicking elsewhere dismisses it.
+- **Effort:** M · **Depends on:** 1.3 (shared `SetWindowTheme`)
+
+---
+
+## Phase 2 — Progress feedback & control
+
+### Task 2.1 — Transcription progress + ETA (B2)
+- **Goal:** Replace the static "Transcribing…" with a moving progress bar + live status like **"Transcribing 1:40 · 45% · ~9s left"**.
+- **Files:** `src/transcriber.h`, `src/transcriber.cpp`, `src/main.cpp`.
+- **Steps (full code in `ARCHITECTURE-AND-DEVGUIDE.md` §B2.1–§B2.3):**
+  1. `transcriber.h`: add `set_progress_callback`, `audio_seconds()`, private `m_on_progress`, `m_audio_seconds`, and the static `s_progress` trampoline.
+  2. `transcriber.cpp`: implement `s_progress`; in `run_inference` set `m_audio_seconds`, `wp.progress_callback = &Transcriber::s_progress; wp.progress_callback_user_data = this;`.
+  3. `main.cpp`: add `#define WM_APP_PROGRESS (WM_USER + 6)`, `std::atomic<int> g_progress{0};`, `DWORD g_busyStart;`. Register `set_progress_callback([](int p){ PostMessage(hMainWnd, WM_APP_PROGRESS, p, 0); })`.
+  4. Set `g_busyStart = GetTickCount(); g_progress = 0;` right before `stop_and_transcribe()`.
+  5. Handle `WM_APP_PROGRESS` (store + invalidate `g_vuRect`). Replace the `is_busy()` branch of `UpdateStatus` with the ETA formatter. Add `DrawProgress` and, in `WM_PAINT`, draw the progress bar in `g_vuRect` while busy (VU otherwise). In `WM_TIMER`, also invalidate `g_vuRect` while busy so the bar/ETA tick.
+- **Edge cases:** `progress < 3%` → show "Transcribing m:ss of audio…" (ETA not stable yet). Clamp `remain >= 0`.
+- **Done when:** A 1–2 min clip shows a filling bar + percentage + shrinking ETA and completes; short clips still feel instant.
+- **Effort:** M
+
+### Task 2.2 — Cancel a running transcription (B2.4)
+- **Goal:** Let the user abort a long/incorrect transcription instead of waiting it out.
+- **Files:** `src/transcriber.h/.cpp`, `src/main.cpp`.
+- **Steps:**
+  1. `transcriber.h`: add `void request_cancel(){ m_abort = true; }`, private `std::atomic<bool> m_abort{false};`, static `s_abort`.
+  2. `transcriber.cpp`: in `run_inference`, `m_abort = false;` at the top, and set `wp.abort_callback = &Transcriber::s_abort; wp.abort_callback_user_data = this;` (skip if your `whisper.h` lacks `abort_callback`).
+  3. `main.cpp`: at the very top of the `HK_TOGGLE` handler add `if (g_tx.is_busy()) { g_tx.request_cancel(); SetStatus(hWnd, L"Cancelling…"); break; }` — so the Record button becomes "cancel" while busy.
+  4. In `WM_APP_RESULT`, when the result is empty *and* a cancel was requested, show "Cancelled" instead of "No speech detected" (track a `g_cancelRequested` flag, reset each Stop).
+- **Done when:** Pressing the button (or hotkey) mid-transcription stops it within ~1 s and the status reads "Cancelled".
+- **Effort:** S · **Depends on:** 2.1
+
+---
+
+## Phase 3 — Robustness & persistence
+
+### Task 3.1 — Persist settings between launches
+- **Goal:** Remember mic, model, pin state, auto-paste, auto-hide, and window position. Today everything resets each launch.
+- **Files:** `src/settings.h` (new, header-only), `src/main.cpp`.
+- **Code (`src/settings.h`):**
+  ```cpp
+  #pragma once
+  #include <windows.h>
+  #include <string>
+  struct AppSettings {
+      int  captureId = 0;
+      std::wstring modelFile;                 // e.g. L"models\\ggml-tiny.en.bin" ("" = auto)
+      bool pinned = true, autoPaste = true, autoHide = false;
+      int  winX = CW_USEDEFAULT, winY = CW_USEDEFAULT, winW = 400, winH = 340;
+  };
+  inline std::wstring SettingsPath() {
+      wchar_t buf[MAX_PATH]; GetModuleFileNameW(nullptr, buf, MAX_PATH);
+      std::wstring p(buf); p = p.substr(0, p.find_last_of(L"\\/"));
+      return p + L"\\win-dictation.ini";
+  }
+  inline int  GetIni(const wchar_t* k, int d){ return GetPrivateProfileIntW(L"app", k, d, SettingsPath().c_str()); }
+  inline void PutIni(const wchar_t* k, int v){ wchar_t b[32]; wsprintfW(b, L"%d", v); WritePrivateProfileStringW(L"app", k, b, SettingsPath().c_str()); }
+  inline void LoadSettings(AppSettings& s){
+      s.captureId = GetIni(L"captureId", s.captureId);
+      s.pinned    = GetIni(L"pinned",    s.pinned)    != 0;
+      s.autoPaste = GetIni(L"autoPaste", s.autoPaste) != 0;
+      s.autoHide  = GetIni(L"autoHide",  s.autoHide)  != 0;
+      s.winX = GetIni(L"winX", s.winX); s.winY = GetIni(L"winY", s.winY);
+      s.winW = GetIni(L"winW", s.winW); s.winH = GetIni(L"winH", s.winH);
+      wchar_t m[MAX_PATH]; GetPrivateProfileStringW(L"app", L"modelFile", L"", m, MAX_PATH, SettingsPath().c_str());
+      s.modelFile = m;
+  }
+  inline void SaveSettings(const AppSettings& s){
+      PutIni(L"captureId", s.captureId); PutIni(L"pinned", s.pinned);
+      PutIni(L"autoPaste", s.autoPaste); PutIni(L"autoHide", s.autoHide);
+      PutIni(L"winX", s.winX); PutIni(L"winY", s.winY); PutIni(L"winW", s.winW); PutIni(L"winH", s.winH);
+      WritePrivateProfileStringW(L"app", L"modelFile", s.modelFile.c_str(), SettingsPath().c_str());
+  }
+  ```
+- **Wiring (`main.cpp`):**
+  1. Add a global `AppSettings g_set;` Call `LoadSettings(g_set);` **before** creating the window.
+  2. Apply: use `g_set.winX/Y/W/H` in `CreateWindowExW` (validate on-screen; fall back to `CW_USEDEFAULT` if off all monitors). Set `g_pinned = g_set.pinned`, `g_autoPaste = g_set.autoPaste`, `g_autoHide = g_set.autoHide`, `g_config.capture_id = g_set.captureId`. If `g_set.modelFile` is non-empty and the file exists, use it instead of `SelectOptimalModel`.
+  3. Save on change: after toggling pin/auto-paste/auto-hide, after a model/mic change, and on `WM_EXITSIZEMOVE` (window moved/resized → store rect) and `WM_DESTROY` (final save). A `void PersistNow()` that copies the live globals into `g_set` then `SaveSettings(g_set)` keeps it DRY.
+- **Done when:** Change mic/model, move/resize the window, toggle pin, quit, relaunch → everything is restored. Deleting the `.ini` restores defaults.
+- **Effort:** M
+
+### Task 3.2 — Quick toggles in the tray menu
+- **Goal:** Expose Auto-paste, Always-on-top, and Auto-hide without building a settings panel.
+- **Files:** `src/main.cpp` (`ShowContextMenu`, `WM_COMMAND`).
+- **Steps:** Add checkable items to the tray popup (`MF_STRING | (flag?MF_CHECKED:0)`) with new IDs (`ID_TRAY_AUTOPASTE`, `ID_TRAY_TOPMOST`, `ID_TRAY_AUTOHIDE`). In `WM_COMMAND`, flip the matching global, apply (for top-most call `SetWindowPos(... HWND_TOPMOST/NOTOPMOST ...)`), then `PersistNow()`.
+- **Done when:** Right-click tray → toggles show check state, take effect immediately, and survive a relaunch.
+- **Effort:** S · **Depends on:** 3.1
+
+### Task 3.3 — Bound the recording length
+- **Goal:** A forgotten recording shouldn't grow memory without limit (~1.9 MB/30 s today, uncapped).
+- **Files:** `src/transcriber.h/.cpp`, `src/main.cpp`.
+- **Steps:**
+  1. `transcriber.h`: add `float recorded_seconds() const;` returning `m_capture` size / `WHISPER_SAMPLE_RATE` under `m_capture_mtx` (or maintain an atomic sample counter incremented in `on_audio`).
+  2. `main.cpp` `WM_TIMER` (recording branch): if `g_tx.recorded_seconds() >= kMaxRecordSeconds` (e.g. 600), auto-stop by posting the same path as a manual Stop, and set status "Max length reached — transcribing".
+- **Done when:** Recording auto-stops at the cap and transcribes what was captured; normal short clips unaffected.
+- **Effort:** S
+
+### Task 3.4 — Surface hotkey-registration failures + make hotkeys configurable
+- **Goal:** Today `RegisterHotKey` return values are ignored — if another app owns `Ctrl+Shift+Space`, the hotkey silently dies. Also allow remapping.
+- **Files:** `src/main.cpp`, `src/settings.h`.
+- **Steps:**
+  1. Capture the return of both `RegisterHotKey` calls. If either fails, show a non-blocking status ("Hotkey in use — set another in win-dictation.ini") and still allow the on-screen Record button to work.
+  2. Read modifiers + key from the INI (`hkMods`, `hkVk`, defaulting to `MOD_CONTROL|MOD_SHIFT` + `VK_SPACE` / `'H'`); register those. (Full remap UI is a Phase 5 stretch — INI is enough now.)
+- **Done when:** With a conflicting global hotkey registered by another app, the app launches, warns, and the button still records; editing the INI changes the hotkey.
+- **Effort:** S · **Depends on:** 3.1
+
+### Task 3.5 — Lightweight logging
+- **Goal:** One small log file so field issues are diagnosable without a debugger.
+- **Files:** `src/logging.h` (new), `src/main.cpp`, `src/transcriber.cpp`.
+- **Code (`src/logging.h`):**
+  ```cpp
+  #pragma once
+  #include <windows.h>
+  #include <cstdio>
+  #include <string>
+  inline void LogLine(const char* msg) {
+      wchar_t buf[MAX_PATH]; GetModuleFileNameW(nullptr, buf, MAX_PATH);
+      std::wstring p(buf); p = p.substr(0, p.find_last_of(L"\\/")) + L"\\win-dictation.log";
+      FILE* f = _wfopen(p.c_str(), L"a"); if (!f) return;
+      SYSTEMTIME t; GetLocalTime(&t);
+      fprintf(f, "%04d-%02d-%02d %02d:%02d:%02d  %s\n", t.wYear,t.wMonth,t.wDay,t.wHour,t.wMinute,t.wSecond, msg);
+      fclose(f);
+  }
+  ```
+- **Log at minimum:** startup (model path, threads, GPU on/off), model load success/failure, mic-open failure, and each transcription (audio seconds, elapsed ms, output char count). Keep messages one line, ASCII.
+- **Optional:** if the file exceeds ~1 MB at startup, rename to `.log.1` (simple 1-file rotation).
+- **Done when:** `win-dictation.log` appears next to the exe and records a startup line + one line per transcription.
+- **Effort:** S
+
+---
+
+## Phase 4 — Tests, docs & packaging
+
+### Task 4.1 — Create `tests/test_core.cpp`
+- **Goal:** Headless regression tests that catch the bugs we already fixed and lock in progress reporting.
+- **Files:** `tests/test_core.cpp` (new — **full content in `FINDINGS-FIXES-TESTS.md` §4.2**).
+- **Steps:**
+  1. Copy the test program from `FINDINGS-FIXES-TESTS.md` §4.2 into `tests/test_core.cpp`.
+  2. Add the progress assertion from `ARCHITECTURE-AND-DEVGUIDE.md` §B3 (max progress ≥95, monotonic).
+  3. Build + run:
+     ```powershell
+     cmake --build build --config Release --target test-core
+     cd build\bin\Release
+     copy ..\..\..\deps\SDL2-2.28.5\lib\x64\SDL2.dll .   # if missing
+     .\test-core.exe models\ggml-tiny.en.bin ..\..\..\samples\jfk.wav
+     ```
+- **Tests covered:** append rule; bad model path → no crash + empty; real clip → contains "country"; short audio → no crash; progress reaches ~100% and is non-decreasing.
+- **Done when:** `test-core.exe` prints "ALL TESTS PASSED" and exits 0.
+- **Effort:** S · **Depends on:** 2.1 (for the progress test)
+
+### Task 4.2 — (Optional) CI workflow
+- **Goal:** Run the build + `test-core` on every push.
+- **Files:** `.github/workflows/build.yml` (new).
+- **Steps:** Windows runner → configure CMake (CPU-only) → build `win-dictation` + `test-core` → download `ggml-tiny.en.bin` → run `test-core` with `jfk.wav`. Fail the job on non-zero exit.
+- **Done when:** A pushed branch shows a green check that actually ran the tests.
+- **Effort:** M · **Depends on:** 4.1
+
+### Task 4.3 — Desktop / Start-Menu shortcut on install
+- **Goal:** One-click launch (the user already pins to taskbar; a shortcut makes first run easy).
+- **Files:** `src/package.ps1` (extend) or a new `install-shortcut.ps1`.
+- **Steps:** After packaging, create a `.lnk` via `WScript.Shell` with `TargetPath` = the exe and `WorkingDirectory` = its folder (so `models\` resolves even though we also use `exe_dir()`), `IconLocation` = the exe. (Snippet in `MODERN-UI-AND-FIXES.md` §9 / spec doc §9.)
+- **Done when:** Running the script creates a working Desktop shortcut that launches the app with the icon.
+- **Effort:** S
+
+### Task 4.4 — Fix the documentation (it describes the OLD app)
+- **Goal:** `README.md`, `src/README.md`, `src/CHANGES.md`, `src/CUDA-SETUP.md`, `src/QUICK-REBUILD-GPU.md`, `src/TESTING.md`, `src/DESIGN.md`, `src/FIXES-APPLIED.md` still describe the **streaming / ring-buffer / 24-thread / Ctrl+Shift+R** design and RTX-3090 benchmarks — all now wrong/misleading.
+- **Steps:**
+  1. Rewrite the top-level `README.md` to describe the **current** app: push-to-talk batch transcription, `Ctrl+Shift+Space` to record/stop, `Ctrl+Shift+H` to hide, tray, always-on-top, copy + auto-paste, model/mic selectors, CPU-tuned (physical-core threads, tiny.en default). Remove ring-buffer/VAD/24-thread/streaming claims and the RTX benchmarks (or move GPU notes to an "optional" aside).
+  2. Update `build.ps1` end-of-run messages ("Hotkey: Ctrl+Shift+R", "Model: base.en") to match reality.
+  3. Mark `CHANGES.md`, `FIXES-APPLIED.md`, `TESTING.md`, `QUICK-REBUILD-GPU.md`, `CUDA-SETUP.md` as **historical/superseded** (a one-line banner at top), or fold the still-true bits into the README and delete the rest. Keep `DESIGN.md` only if updated to the batch architecture.
+- **Done when:** A new reader following `README.md` gets accurate hotkeys, model behaviour, and build steps; no doc claims a ring buffer or 24 threads.
+- **Effort:** M
+
+---
+
+## Phase 5 — Stretch features (nice-to-have)
+
+### Task 5.1 — Hold-to-talk mode
+- **Goal:** Option to record only while a key is held (vs. toggle).
+- **Files:** `src/main.cpp`, `src/settings.h`.
+- **Steps:** Add a low-level keyboard hook (`SetWindowsHookEx(WH_KEYBOARD_LL, ...)`); on key-down of the chosen key start recording, on key-up `stop_and_transcribe`; debounce auto-repeat with a flag. Gate behind a `holdToTalk` INI setting; keep toggle as default. (Outline in the original spec doc §7.)
+- **Done when:** With the setting on, holding the key records and releasing transcribes; toggle mode still available.
+- **Effort:** M
+
+### Task 5.2 — Settings panel (graduate from tray toggles + INI)
+- **Goal:** A small in-app settings popup (reuse the custom popup window from Task 1.4) for mic, model, auto-paste, auto-hide, hold-to-talk, and hotkey capture.
+- **Done when:** All settings are editable in-app and persist (Task 3.1).
+- **Effort:** L · **Depends on:** 1.4, 3.1
+
+### Task 5.3 — Export / save transcript
+- **Goal:** Save the transcript box to a `.txt` (and timestamped filename) from the tray menu or a button.
+- **Effort:** S
+
+### Task 5.4 — Multi-language support
+- **Goal:** Allow non-English models + a language selector (currently hard-wired `en`). Swap to a multilingual model (`ggml-base.bin`) and set `WhisperConfig.language` from a selector.
+- **Effort:** M · **Depends on:** 1.4 (selector), 3.1
+
+---
+
+## Definition of Done (per task)
+- [ ] Builds clean (`cmake --build build --config Release`), **zero new warnings**.
+- [ ] App launches, records, transcribes, appends, copies/pastes — no regressions.
+- [ ] `test-core.exe` exits 0 (after Phase 4).
+- [ ] Any new setting persists across relaunch (after Phase 3).
+- [ ] Change is reflected in `README.md` if user-facing.
+
+## Suggested order (fastest path to "feels finished")
+1. **0.1–0.3** (hygiene) → **1.3** (hairlines, 5-min win) → **2.1** (progress — biggest UX gain).
+2. **1.1** (icon) → **1.4** (custom dropdowns) → **1.2** (tray state) → **2.2** (cancel).
+3. **3.1** (persistence) → **3.2** (tray toggles) → **3.4** (hotkey safety) → **3.3** (length cap) → **3.5** (logging).
+4. **4.1** (tests) → **4.4** (docs) → **4.3** (shortcut) → **4.2** (CI).
+5. Stretch (**5.x**) as desired.
+
+## Verification matrix (final smoke test)
+| Area | Check |
+|---|---|
+| Crash-free | Record/stop 10× incl. a 2-min clip; window never vanishes; process stable |
+| Progress | 2-min clip shows filling bar + % + shrinking ETA; cancel works |
+| Chrome | No hairlines/focus rects; selectors have one chevron + dark popup |
+| Paste | Hotkey-from-another-app pastes the latest utterance; button = copy only |
+| Persistence | mic/model/pin/auto-paste/window pos restored after relaunch |
+| Assets | New icon crisp in title bar, taskbar, Alt-Tab, tray; red tray icon while recording |
+| Robustness | Missing model → clear message (no crash); hotkey conflict → warned; long record auto-stops |
+| Tests/docs | `test-core` green; README matches actual hotkeys/behaviour |
+
+