vocalize-cli 0.13.0__tar.gz → 0.13.1__tar.gz

{vocalize_cli-0.13.0 → vocalize_cli-0.13.1}/CHANGELOG.md

@@ -5,7 +5,36 @@ All notable changes to this project are documented here. Format follows
 
 ## Unreleased
 
-Nothing yet.
+### Added
+
+- **`vocalize pause`** pauses live playback and saves your place for up to an
+  hour under `~/.cache/vocalize/interrupted.*` (0600 mode), continuing where you
+  left off with `vocalize resume` (with a 1.0-second rewind overlap).
+- **`[app] stop_hotkey = "stop" | "pause"`** (default `"stop"`). Set to
+  `"pause"`, the stop chord (Control-Option-Command-X) becomes a play/pause
+  toggle with zero Accessibility re-grant: pauses live audio, and resumes a
+  saved read when nothing is playing (refusing silently during dictation).
+- `vocalize settings` prints `app.stop_hotkey=…`.
+
+- **The dictation cue no longer reaches the transcript.** The "Start."
+  word and/or Tink now play after the microphone is actually open, timed
+  off the real first growth of the recording rather than a guess, and
+  those seconds are trimmed back off the head of the take before it's
+  transcribed ([#2](https://github.com/matthager12-collab/vocalize/issues/2)).
+  A machine where the recording never grows incrementally falls back to
+  today's order (word before the microphone opens) with no trim.
+- **Hold-to-talk.** `[app] dictate_mode = "hold"` turns the dictate chord
+  from a toggle into a press-and-hold: hold it, speak, let go, no cancel
+  window. `vocalize dictate --start` / `--stop` drive the same thing from
+  a terminal or a script. `--start` is idempotent; `--stop` never treats a
+  short hold as a cancel.
+- **`[stt] paste`** (default off). When on, a dictation that copies to the
+  clipboard also pastes into the app you started it in — a marker file
+  carrying the dictation's nonce is how the menu-bar app knows it's safe
+  to paste (same session, same frontmost app, under 2 seconds old); a
+  window switch leaves the transcript on the clipboard and says "Copied,
+  not pasted (window changed)." instead.
+- `vocalize settings` prints `stt.paste=…`.
 
 ## 0.13.0 - 2026-09-08
 

{vocalize_cli-0.13.0 → vocalize_cli-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.13.0
+Version: 0.13.1
 Summary: A local-first CLI that turns text, markdown, or piped stdin into speech: the on-device Kokoro voice by default, cloud voices optional, with markdown-table-aware preprocessing and Claude Code hooks.
 Project-URL: Homepage, https://github.com/matthager12-collab/vocalize
 Project-URL: Repository, https://github.com/matthager12-collab/vocalize
@@ -600,7 +600,7 @@ cues = "sounds"        # "sounds" | "words" | "both" — speak "Start."/"Stopped
 | `cleanup` | `off`, `local` (0.13), `claude-cli`, `anthropic`; an old `true`/`false` reads as `claude-cli`/`off` | `off` |
 | `verbatim` | `true` / `false` — keep every word even when cleanup is on | `false` |
 | `beam_size` | integer, 1–8 | `5` |
-| `paste` | reserved — not implemented in 0.10.0 | `false` |
+| `paste` | `true` / `false` — paste into the app you dictated in, after copying (see docs/dictation.md § Auto-paste) | `false` |
 | `max_seconds` | integer, 1–600 | `120` |
 | `sounds` | `true` / `false` | `true` |
 | `cues` | `sounds`, `words`, `both` | `sounds` |
@@ -628,7 +628,7 @@ The chords the menu-bar app owns, system-wide. A change needs
 ```toml
 [app]
 dictate = "ctrl+alt+cmd+d"   # start/stop dictation
-dictate_mode = "toggle"      # toggle | hold ("hold" arrives in 0.13.1)
+dictate_mode = "toggle"      # toggle | hold
 speak = "ctrl+alt+cmd+s"     # speak the selection
 stop = "ctrl+alt+cmd+x"      # stop whatever is playing
 ```
@@ -693,6 +693,7 @@ where it stopped, and once your transcript has landed, vocalize asks:
 up after 15 seconds (counted as no). From a terminal, the same thing is:
 
 ```bash
+vocalize pause             # pause live playback and save your place
 vocalize resume            # continue where the last read left off
 vocalize resume --forget   # discard it instead
 ```

{vocalize_cli-0.13.0 → vocalize_cli-0.13.1}/README.md

@@ -564,7 +564,7 @@ cues = "sounds"        # "sounds" | "words" | "both" — speak "Start."/"Stopped
 | `cleanup` | `off`, `local` (0.13), `claude-cli`, `anthropic`; an old `true`/`false` reads as `claude-cli`/`off` | `off` |
 | `verbatim` | `true` / `false` — keep every word even when cleanup is on | `false` |
 | `beam_size` | integer, 1–8 | `5` |
-| `paste` | reserved — not implemented in 0.10.0 | `false` |
+| `paste` | `true` / `false` — paste into the app you dictated in, after copying (see docs/dictation.md § Auto-paste) | `false` |
 | `max_seconds` | integer, 1–600 | `120` |
 | `sounds` | `true` / `false` | `true` |
 | `cues` | `sounds`, `words`, `both` | `sounds` |
@@ -592,7 +592,7 @@ The chords the menu-bar app owns, system-wide. A change needs
 ```toml
 [app]
 dictate = "ctrl+alt+cmd+d"   # start/stop dictation
-dictate_mode = "toggle"      # toggle | hold ("hold" arrives in 0.13.1)
+dictate_mode = "toggle"      # toggle | hold
 speak = "ctrl+alt+cmd+s"     # speak the selection
 stop = "ctrl+alt+cmd+x"      # stop whatever is playing
 ```
@@ -657,6 +657,7 @@ where it stopped, and once your transcript has landed, vocalize asks:
 up after 15 seconds (counted as no). From a terminal, the same thing is:
 
 ```bash
+vocalize pause             # pause live playback and save your place
 vocalize resume            # continue where the last read left off
 vocalize resume --forget   # discard it instead
 ```

{vocalize_cli-0.13.0 → vocalize_cli-0.13.1}/docs/app.md

@@ -74,7 +74,7 @@ Three chords, set under `[app]` in `~/.config/vocalize/config.toml`:
 | Key | What it does | Default |
 |---|---|---|
 | `dictate` | start/stop dictation | `ctrl+alt+cmd+d` |
-| `dictate_mode` | `toggle` or `hold` (`hold` arrives in 0.13.1) | `toggle` |
+| `dictate_mode` | `toggle` or `hold` | `toggle` |
 | `speak` | speak the selection | `ctrl+alt+cmd+s` |
 | `stop` | stop whatever is playing | `ctrl+alt+cmd+x` |
 

{vocalize_cli-0.13.0 → vocalize_cli-0.13.1}/docs/dictation.md

@@ -140,9 +140,8 @@ touching System Settings at all, whichever way you trigger it.
   classic symptom of an unworn Bluetooth microphone — the dictation ends
   quietly: "Nothing heard — nothing was transcribed," no clipboard write.
 - If words were heard, a Glass plays and the transcript is copied to the
-  clipboard. Nothing is typed or pasted for you; that's a deliberate
-  narrowing (`[stt] paste` is reserved for a future release and does
-  nothing in 0.10.0).
+  clipboard. Nothing is typed or pasted for you unless you've turned on
+  `[stt] paste` — see [Auto-paste](#auto-paste) below.
 
 **A second press within two seconds of the first is a cancel**, not a
 stop — treated as "I changed my mind" rather than the end of a very short
@@ -164,12 +163,61 @@ silently drops one either. Wait for the clipboard notification, or use
 New to the sounds and can't tell Tink from Pop from Glass? Set
 `[stt] cues = "words"` and vocalize says "Start.", "Stopped." and "Ready."
 instead, or `"both"` to hear the word and then its sound — see the `[stt]`
-table below. Timing matters: "Start." is spoken *before* the microphone
-opens (so it is never in your recording), and the microphone is open
-about a second later — the Tink marks that moment. So in `"both"` mode
-talk after the Tink; in `"words"` mode give it a beat after "Start.".
-Closing that gap is
-[#2](https://github.com/matthager12-collab/vocalize/issues/2).
+table below.
+
+**Talk any time after the cue — there's no gap to leave any more.** The
+cue now plays *after* the microphone is actually open, and vocalize cuts
+those seconds back off the head of the recording afterward, so it never
+reaches the transcript ([#2](https://github.com/matthager12-collab/vocalize/issues/2)).
+Earlier releases played "Start." before the microphone opened and made
+you wait out a beat for it to catch up; that guesswork is gone.
+Vocalize waits for the recording to actually start growing — about
+150 ms after the press on the machines this was measured on, then another
+380–520 ms before the first real audio lands (Bluetooth mics run slower
+than a built-in or USB one) — before it cues you at all.
+
+## Hold-to-talk
+
+Set `dictate_mode = "hold"` under `[app]` and the dictate chord stops
+toggling and starts holding: hold it down, speak, let go. There's no
+cancel window — even a half-second hold transcribes, because there's no
+second press to read as "I changed my mind" against.
+
+The key-down itself is the cue, so there's no Tink and no "Start." to
+play or trim. The key-up stops, transcribes and copies exactly like a
+toggle's second press.
+
+The same two actions from a terminal or a script:
+
+```bash
+vocalize dictate --start   # key down
+vocalize dictate --stop    # key up
+```
+
+`--start` is idempotent — a second key-down while a dictation is already
+running does nothing, rather than opening a second microphone. `--stop`
+with nothing running also does nothing (exit 0); a `--stop` that lands
+before the recorder has even reported its PID waits for it and then
+stops; a recorder that's actually dead is the same failure as today's
+toggle.
+
+## Auto-paste
+
+Set `[stt] paste = true` and a dictation that copies also pastes,
+straight into the app you started it in — not just onto the clipboard.
+
+After copying, vocalize drops a marker
+(`~/.cache/vocalize/dictate.copied`) carrying this dictation's nonce. The
+menu-bar app is watching for that marker, and only pastes (a synthetic
+Command-V) when the nonce matches the session it watched, the app that
+was frontmost when you started dictating is still frontmost, and the
+marker is under two seconds old. Switch windows or wait too long and it
+says so instead of pasting: **"Copied, not pasted (window changed)."**
+The transcript stays on your clipboard either way, so nothing is lost.
+
+Off by default. Nothing is written when nothing was heard, the marker
+file is `0600`, and a symlink planted at that path is refused rather than
+followed.
 
 ## `vocalize listen`
 
@@ -238,7 +286,7 @@ language = "en"
 input_device = ""
 cleanup = "off"      # "off" | "claude-cli" | "anthropic" | "local" (local arrives in 0.14.0)
 verbatim = false     # keep every word: punctuation and casing only, no dropped restatements
-paste = false
+paste = false        # paste after copying — see Auto-paste
 max_seconds = 120
 sounds = true
 cues = "sounds"  # "sounds" | "words" | "both"
@@ -252,7 +300,7 @@ beam_size = 5    # 1 = greedy (the 0.10.x decoder); 2-8 = beam search with that
 | `input_device` | `""` (system default) or an exact name from `vocalize listen --list-devices`; ≤ 128 characters, printable only, can't start with `-` | `""` | see [The input-device gotcha](#the-input-device-gotcha) |
 | `cleanup` | `off`, `claude-cli`, `anthropic`, `local` | `off` | where the cleanup pass runs. `claude-cli` is `claude -p` on your Claude Code subscription (shares its usage pool, and Claude Code logs the run); `anthropic` is the Messages API with a stored key and a monthly character budget; `local` is accepted now and honoured from 0.14.0. Older configs' `true` / `false` still work: `true` means `claude-cli` |
 | `verbatim` | `true` / `false` | `false` | keep every word; the default pass also drops restatements, false starts and filler ([#3](https://github.com/matthager12-collab/vocalize/issues/3)). Saying "verbatim" as the first word of a take does the same for that take |
-| `paste` | reserved | `false` | not implemented in 0.10.0 — setting it does nothing |
+| `paste` | `true` / `false` | `false` | paste into the app you dictated in, after copying — see [Auto-paste](#auto-paste) |
 | `max_seconds` | integer, 1–600 | `120` | the recorder self-stops here; `dictate` backstops it a few seconds later in case the recorder doesn't |
 | `sounds` | `true` / `false` | `true` | the Tink/Pop/Glass feedback; `false` silences all three (words included) |
 | `beam_size` | integer, 1–8 | `5` | the whisper.cpp decoder: `1` is greedy, the 0.10.x behaviour that ran words together on fast speech ("toget" for "to get", [#4](https://github.com/matthager12-collab/vocalize/issues/4)); `5` is whisper.cpp's own beam-search default and the fix. Lower it if a take is slow to land on your machine |
@@ -276,6 +324,7 @@ stt.cleanup=off
 stt.verbatim=false
 stt.max_seconds=120
 stt.cues=sounds
+stt.paste=false
 ```
 
 ### The input-device gotcha
@@ -334,7 +383,15 @@ Exit code is 0 when every row — providers and dictation both — is `ok`,
 and 1 otherwise, so it composes with `&&` the same way `vocalize usage`'s
 sibling commands do.
 
-## Interrupted reads and `resume`
+## Pausing, interrupted reads, and `resume`
+
+You can deliberately pause any playback vocalize is currently speaking:
+
+```bash
+vocalize pause             # pause playback and remember where it stopped
+vocalize resume            # play the saved piece, then read the rest
+vocalize resume --forget   # discard the saved read
+```
 
 Starting a dictation always stops whatever vocalize was reading aloud
 first — you can't record over your own voice being played back — but it
@@ -348,14 +405,15 @@ Once your dictation's transcript has landed, vocalize shows a dialog:
 > **Continue the read you interrupted?** [Discard] [Continue]
 
 Default button is Continue; the dialog gives up after 15 seconds, which
-counts as Discard. From a terminal (or if you missed the dialog), the same
-thing is:
+counts as Discard.
 
-```bash
-vocalize resume            # play the saved piece, then read the rest
-vocalize resume --forget   # discard the interrupted read
-vocalize resume            # "Nothing to resume." if there's nothing saved
-```
+### Zero-re-grant hotkey pause
+
+With `[app] stop_hotkey = "pause"` in `~/.config/vocalize/config.toml`, the
+menu-bar app's stop chord (Control-Option-Command-X) becomes a play/pause toggle
+with zero Accessibility re-grant: pressing it while audio is playing pauses the
+read, and pressing it when nothing is playing resumes the saved read (refusing
+silently while a dictation is recording).
 
 ### What's stored, and where
 
@@ -364,7 +422,7 @@ together:
 
 | File | Contents |
 |---|---|
-| `interrupted.<ext>` | one piece of audio — the chunk that was playing when the dictation started, or the whole file for a provider that doesn't stream |
+| `interrupted.<ext>` | one piece of audio — the chunk that was playing when the pause or dictation landed, or the whole file for a provider that doesn't stream |
 | `interrupted.txt` | the text after that piece — everything not yet spoken |
 | `interrupted.json` | `version`, `saved_at`, `provider`, `ext`, `offset_seconds`, `remaining_chars` |
 
@@ -377,14 +435,14 @@ moment you resume, decline, or `--forget` it, and an automatic expiry after
 **one hour** even if you never touch it. Nothing beyond that — a backup job
 that runs inside that hour will see it. No dictation audio and no
 dictation transcript is ever written into this record (see
-[Privacy](#privacy)); it only ever holds a *TTS read* your dictation
-interrupted.
-
-Resuming plays the saved piece from where it was cut off (converting to
-WAV first if needed, then slicing by sample), then continues through the
-rest of the text via the normal chain, same provider, same cache — so
-anything already rendered is a cache hit and the continuation starts
-immediately.
+[Privacy](#privacy)); it only ever holds a *TTS read* paused or interrupted.
+
+Resuming plays the saved piece from one second before where it was cut off
+(converting to WAV first if needed, then slicing by sample with a 1.0 s
+rewind overlap so the continuation never starts mid-syllable), then continues
+through the rest of the text via the normal chain, same provider, same
+cache — so anything already rendered is a cache hit and the continuation
+starts immediately.
 
 ## Uninstalling
 

{vocalize_cli-0.13.0 → vocalize_cli-0.13.1}/docs/plans/2026-09-app-roadmap/review-0.13.0.md

@@ -250,3 +250,64 @@ The absence of a finding is only evidence if the check is written down. Each bul
 - All 28 relative markdown links and heading anchors across README.md, CHANGELOG.md, docs/app.md, docs/installation.md, docs/dictation.md and docs/roadmap.md resolve.
 - Python-version floor is honest (`>=3.10`, no 3.11/3.12-only syntax; `tomllib` guarded by a `tomli` fallback).
 - `tests/test_app_build.py`, `test_recorder_build.py`, `test_portal_assets.py`, `test_cue_assets.py`, `test_uv_path.py`: 86 passed. `ruff check vocalize hooks tests`: All checks passed.
+
+# Adversarial review: vocalize 0.13.1 (T-110, dictation cue trim, hold-to-talk, pause/resume, and spoken rendering rules)
+
+**Date:** 2026-09-21
+**Scope:** branch `hold-to-talk` at `7650883` against `main` at `b59cd5d` — runs 11, spoken rendering rules, and 11b of `docs/plans/2026-09-app-roadmap/plan.md`:
+- Run 11: `vocalize/dictate.py` (`_wait_for_audio`, `_AUDIO_GRACE`, `_cue_the_open_microphone`, `_trim_cue`, `start_hold`, `stop_hold`, `copied_path`, `_write_copied_marker`), `vocalize/cli.py` (`dictate --start`/`--stop`, `settings` printing `stt.paste`), `vocalize/config.py` (`[app] dictate_mode` passthrough, `[stt] paste` support).
+- Spoken rendering rules: `docs/research/2026-09-08-spoken-rendering-rules.md`, `vocalize/preprocess.py` (forty spoken markdown / punctuation rules, `resolve_speech`), `vocalize/config.py` (`[speech]` table validation and defaults), `vocalize/cli.py` (`_run_tts` speech config resolution).
+- Run 11b: `vocalize/interrupted.py` (`wait_for_record`, `_RESUME_REWIND = 1.0` in `slice_from`), `vocalize/cli.py` (`vocalize pause`, `vocalize stop` with `app.stop_hotkey = "pause"`), `vocalize/config.py` (`[app] stop_hotkey` validation).
+- Hardening: `O_NONBLOCK` on all marker writers in `dictate.py` (`write_mic_status`, `_write_session`, `_write_copied_marker`) preventing FIFO wedging; `_SESSION_STATES` monotonic progression guard in `_write_session`.
+
+**Lenses:**
+- dictate-and-cue: `_wait_for_audio` 4096-byte header threshold and growth polling; cue playback timing after growth; integer frame calculation and atomic `os.replace` in `_trim_cue`; `start_hold` idempotency and `stop_hold` grace/PID resolution.
+- paste-and-nonce: marker writing at `~/.cache/vocalize/dictate.copied` under 0600 mode with `O_NOFOLLOW` and `O_NONBLOCK`; session nonce validation; matching between Python marker and Swift reader.
+- pause-and-resume: `wait_for_record` bounded polling; `slice_from` 1.0 s rewind clamped at 0.0; stop hotkey toggle routing refusing during active dictation.
+- spoken-rendering: preprocess pipeline idempotency; regex bounding and non-exponential rules; safe table and enum validation in `config.py`.
+
+### Findings
+
+| Severity | Title | File | Status | Resolution |
+|---|---|---|---|---|
+| low | 0.13.0 deferred obligation: frozen Swift `dictate --start`/`--stop` flags and `stt.paste` settings display | `vocalize/cli.py` | fixed | 0.13.0 finding line 178 deferred to 0.13.1: `dictate --start` and `--stop` are now fully implemented in `vocalize/cli.py` and backed by `dictate.start_hold` / `stop_hold`; `vocalize settings` now prints `stt.paste=true|false`. Tests: `test_dictate.py`, `test_cli.py`, `test_config.py`. |
+| low | FIFO planted at `mic.status`, `dictate.session`, or `dictate.copied` could wedge writer | `vocalize/dictate.py` | fixed | `write_mic_status`, `_write_session`, and `_write_copied_marker` now open with `O_NONBLOCK` alongside `O_NOFOLLOW` and 0600 mode. A planted FIFO fails with `ENXIO` immediately instead of blocking the process indefinitely. |
+| low | Out-of-order session progression: slow `--start` waiting for audio could revert `transcribing` to `recording` | `vocalize/dictate.py` | fixed | `_SESSION_STATES = ("starting", "recording", "transcribing")` enforces monotonic forward progression. If the on-disk session state is already further ahead, a lagging worker aborts the write silently. |
+
+### Carried from earlier reviews
+
+| ID | Title | File | Status |
+|---|---|---|---|
+| F-10 | "verbatim" spoken alone produces an egress line and a real POST with an empty message body | `vocalize/llm.py` | still open — carried forward as low |
+| F-13 | The fallback note tells the user to install Kokoro when Kokoro is installed and was skipped by budget | `vocalize/chain.py` | still open — carried forward as low |
+| F-14 | Keys tab hides "Remove stored key" when environment variable shadows keychain key | `vocalize/assets/portal.js` | still open — carried forward as low |
+| — | The 0.11.0 tmpdir sweep for playback/resume temp directories | `vocalize/cli.py` | still open — carried forward as low |
+
+**No critical or high finding exists in this review, and none is open or accepted: all new features pass all security gates, all regressions pass, and all carried items remain low severity.**
+
+### What each lens checked and found clean
+
+#### dictate-and-cue
+- `_wait_for_audio` waits up to 5.0 s (`_AUDIO_GRACE`) for `take.wav` size to exceed `_WAV_HEADER_BYTES` (4096 bytes). If cancelled or directory vanishes, returns None safely.
+- `_cue_the_open_microphone` plays `_SOUND_START` after audio begins growing, recording exact cue duration to `workdir / "cue"`.
+- `_trim_cue` parses cue seconds safely (`math.isfinite(seconds) and seconds >= 0`), bounds frame drops to `< reader.getnframes()`, writes `take.trimmed.wav`, and executes atomic `os.replace`. Clean exception handling deletes temporary trimmed file on failure.
+- `start_hold` uses `_claim_session(workdir)` with `O_EXCL` and cleans up tempdir on duplicate calls; `stop_hold` skips the 2-second cancel window, resolves recorder PID within grace period, and transcribes cleanly.
+
+#### paste-and-nonce
+- `_write_copied_marker` writes `{"epoch": time.time(), "nonce": nonce}` to `~/.cache/vocalize/dictate.copied` using `O_CREAT | O_WRONLY | O_TRUNC | O_NOFOLLOW | O_NONBLOCK` at mode 0600.
+- `_session_nonce` verifies the session directory matches the active workdir and re-reads fresh from disk before issuing paste marker.
+- Swift paste listener validates nonce match, age under 2.0 s, and matching frontmost application before triggering synthetic Command-V paste.
+
+#### pause-and-resume
+- `vocalize pause` issues `stop_playback(remember=True)` and awaits record write via `interrupted.wait_for_record(since)` with 3.0 s deadline.
+- `[app] stop_hotkey = "pause"` toggles: pauses active playback, or resumes saved record with 1.0 s rewind overlap (`_RESUME_REWIND = 1.0` clamped at 0.0) when idle, while safely refusing during an active dictation session (`dictate._read_session() is not None`).
+- Negative tests verify dictation while paused preserves the paused record without corruption.
+
+#### spoken-rendering
+- Forty spoken rendering rules implemented in `vocalize/preprocess.py` correctly convert headings, lists, abbreviations, citations, block quotes, URLs, and punctuation to natural spoken prose.
+- Rule evaluation is idempotent: running `flatten_markdown` multiple times produces the identical result.
+- `[speech]` table options in `vocalize/config.py` validate all modes and integer bounds with helpful error messages.
+
+#### artifact and suite verification
+- Full test suite: 2,231 passed, 3 skipped; ruff clean.
+- Wheel package builds cleanly without leaking ML runtimes (`pywhispercpp`, `onnxruntime`, `mlx`, `sherpa`, `numpy`, `torch`, `boto3`).

vocalize_cli-0.13.1/docs/plans/2026-09-app-roadmap/run-10-release-0-13-0/report.md

@@ -0,0 +1,17 @@
+# Report: run 10, release 0.13.0
+
+Date 2026-09-08. Branch `app` (worktree `.claude/worktrees/app`). Full account in [task-report.md](./task-report.md); the review in [../review-0.13.0.md](../review-0.13.0.md) § Release review.
+
+- T-90: done — `__version__` 0.13.0; CHANGELOG `## 0.13.0 - 2026-09-08` with an empty Unreleased above it; docs-match-CLI passes for the ten 0.13.0 commands; README gained `### vocalize doctor` and the `[app]` table; docs/roadmap.md's row reads in progress with both releases named.
+- T-91: done — the release review (five lenses over runs 7–9, three refuters per finding): 25 raw, 24 triaged, 16 refuted, 12 confirmed (6 medium, 6 low), 4 refuted with reasons, 8 past the cap checked once by the release manager. Mediums fixed: session readers never raise on non-object JSON (a torn session could have kept the microphone open); `integrate claude` refuses a non-executable or relative vocalize path; the doctor survives a bad config as one failed row; the `[app]` table is documented; the services-conflict doctor row that warned about the bundle `integrate claude` installs is gone and `app install` names the real conflict (an assigned D or X shortcut). One medium accepted: speak-selection presses queue on the serial queue in the frozen Swift (a re-grant to change; the stop chord is the escape). Lows fixed after the review by the release manager: stale `app.status` unlinked on a rebuild, the skill's refuse list, `pbs -update` timeout, four doc corrections. Three lows open and named (which vocalize the app found is not reported; `discoverable()` is a membership test; no crash-leftover sweep in `app uninstall`). No critical or high finding exists or is open in any of the file's three sections.
+- T-92: done — manual checks with the owner present: 4 (run 7's spike, Carbon on three frontmost apps); 5 (icon, menu, a dictation with the red icon — the stopwatch latency numbers were skipped by the owner's choice); 6 (speak-selection with the Accessibility prompt once; the X chord silences a read within a second); 7 (`kill -9` relaunched in under 12 s; Quit stayed quit; `app restart` brought it back; log out and in deferred to the owner's next login); 8 (the released tool installed with the app running — see task-report.md). Published from this worktree's `dist/` with the token injected by `op run`; PyPI digests equal the local build.
+
+Security gate: the gate's own rows plus the review's tests — `test_session_json_that_is_not_an_object_never_raises` (4 cases), `test_refuses_a_vocalize_path_that_is_not_executable`, `test_refuses_a_relative_vocalize_path`, `test_doctor_reports_a_bad_config_as_one_failed_row`, `test_no_doctor_row_warns_about_a_quick_action_integrate_installs`, `test_install_warns_about_a_shortcut_not_about_the_quick_action_itself`, `test_a_rebuild_forgets_the_old_status_file`, `test_bootstrap_retries_once_after_launchd_says_io_error`, `test_bootstrap_does_not_retry_a_success`.
+
+Incident: a release-review finder wrote probe scripts under /tmp that drove `app install` and `app uninstall` through `CliRunner` with only `APP_DIR` redirected; `defaults` and `launchctl` ignore HOME, so the owner's real LaunchAgent plist was deleted, the real `VocalizeBinary` override was removed and the real agent was booted out. The main session found the app running on the 0.12.0 CLI with no chords, restored the override, re-ran `app install` (which exposed launchd's bootstrap-after-bootout error 5, now retried once in `app.bootstrap()`), and verified the grant intact. The standing agent rule now names this trap.
+
+Deferred: the log-out-and-in half of manual check 7 (the owner's next login; RunAtLoad is in the plist).
+
+Suite: 2122 passed, 3 skipped. Ruff clean. Gate 16 of 16 after publish.
+
+validate-exit: PASS

vocalize_cli-0.13.1/docs/plans/2026-09-app-roadmap/run-10-release-0-13-0/task-report.md

@@ -0,0 +1,29 @@
+# Task report: run 10 (release 0.13.0)
+
+## Changelog
+
+- `vocalize/__init__.py` 0.13.0; CHANGELOG; README (`vocalize doctor`, the `[app]` table); docs/roadmap.md; docs/app.md.
+- Review fixes: `vocalize/dictate.py` (shape guards), `vocalize/integrate.py` (executable-path refusal, `pbs` timeout), `vocalize/cli.py` (doctor's config-file row; stale status unlinked on rebuild), `vocalize/readiness.py` (services-conflict row removed; caveat wording), `vocalize/app.py` (bootstrap retry), `vocalize/portal.py` (docstring), `vocalize/assets/claude/speak/SKILL.md` (refuse list), and their tests.
+- `review-0.13.0.md` § Release review: 0.13.0 (T-91).
+
+## Skipped
+
+The stopwatch latency numbers of manual check 5 (owner's choice) and the log-out-and-in half of check 7 (deferred to the owner's next login). Everything else in scope was done.
+
+## Owner check and check 8
+
+Check 8: after publish, the owner's everyday tool was moved to 0.13.0 with `uv tool install vocalize-cli@latest` while the app was running, the `VocalizeBinary` override that pointed at this worktree was removed, and the app's next press ran the released CLI — recorded in the session's closing summary of 2026-09-08.
+
+## Learnings
+
+- `defaults`, `launchctl` and `tccutil` act on the real user whatever HOME says; redirecting `APP_DIR` alone is not isolation.
+- launchd tears a booted-out service down asynchronously; a bootstrap inside that window fails with error 5 and succeeds a second later.
+- The Setup tab is built from the readiness rows, not the doctor's; docs must say which.
+
+## Alternatives
+
+- Fixing the speak-selection queueing in the Swift before the freeze — dropped: a medium, a re-grant for every user, the stop chord already covers it; it waits for a Swift patch release.
+
+## Specification (post)
+
+As `project-plan.md`.

vocalize_cli-0.13.1/docs/plans/2026-09-app-roadmap/run-11-cue-hold-paste/report.md

@@ -0,0 +1,16 @@
+# Report: run 11, cue trim, hold-to-talk, auto-paste
+
+Date 2026-09-08. Branch `hold-to-talk` (worktree `.claude/worktrees/hold-to-talk`). Source plan in [project-plan.md](./project-plan.md).
+
+- T-100: done — spike recorded in `spike-notes.md` § Cue: take grows incrementally on both Yeti Stereo Microphone (USB) and Mat's AirPods Pro (Bluetooth) inputs; verdict: `branch: trim` (first growth past 4096-byte header signals open microphone; cue plays after and is trimmed from the head).
+- T-101: done — `_wait_for_audio`, `_AUDIO_GRACE` (5 s), cue marker written in `_launch_recorder`, `_trim_cue` first in `_finish_take`, state `recording` reported after the cue.
+- T-102: done — `dictate --start` and `--stop` per design; `--start` is idempotent; `--stop` at 0.5 s transcribes and never cancels; `[app] dictate_mode` accepts `hold`.
+- T-103: done — `[stt] paste`: `_stop` writes `dictate.copied` carrying epoch + session nonce with 0600 mode and `O_NOFOLLOW`; `settings` prints `stt.paste`.
+- T-104: done — tests green for T-101–T-103 across `tests/test_dictate.py`, `tests/test_cli.py`, `tests/test_config.py`.
+- T-105: done — `docs/dictation.md` cue paragraph and hold mode documented; paste privacy note; CHANGELOG 0.13.1; version bumped to 0.13.1.
+
+Security gate: session nonce matching, 0600 file mode, and `O_NOFOLLOW` flag verified in `tests/test_dictate.py` (`test_paste_marker_written_securely`, `test_paste_marker_carries_session_nonce`).
+
+Deferred: nothing. Manual checks 9–11 verified with owner.
+
+validate-exit: PASS

vocalize_cli-0.13.1/docs/plans/2026-09-app-roadmap/run-11b-playback-pause/report.md

@@ -0,0 +1,14 @@
+# Report: run 11b, playback pause and resume
+
+Date 2026-09-08. Branch `hold-to-talk` (worktree `.claude/worktrees/hold-to-talk`). Source plan in [project-plan.md](./project-plan.md).
+
+- T-106: done — `_wait_for_record` moved out of `dictate.py` into `interrupted.wait_for_record(since)`; `vocalize pause` added, calling `stop_playback(remember=True)` then waiting, printing pause message when record landed and "Nothing is playing." otherwise.
+- T-107: done — `[app] stop_hotkey = "stop"|"pause"` added to `config.py` (default `stop`, unknown word refused, printed by `vocalize settings`); in `"pause"` mode `vocalize stop` pauses a live read, and when nothing was playing and a record is present, resumes it (refusing silently when `dictate._read_session()` is live); plain `stop` unchanged.
+- T-108: done — `_RESUME_REWIND = 1.0` applied inside `interrupted.slice_from` and clamped at zero; three failure modes pinned (dictation while paused never offers or destroys record, unusable provider reports failure and leaves record in place, two resumes do not corrupt record).
+- T-109: done — `docs/dictation.md` updated with pause/resume section, 1-hour expiration, plaintext `interrupted.txt` note, and zero-re-grant hotkey pause; `README.md` command list updated; `CHANGELOG.md` updated for 0.13.1.
+
+Security gate: plaintext `interrupted.txt` write and 0600/`O_NOFOLLOW` marker discipline verified (`tests/test_cli.py::test_pause_saves_the_record_like_a_dictation`, `tests/test_cli.py::test_the_interrupt_record_is_private`, `tests/test_dictate.py::test_dictation_while_paused_never_offers_the_paused_read`).
+
+Deferred: nothing. Manual checks 15–16 verified with owner.
+
+validate-exit: PASS

{vocalize_cli-0.13.0 → vocalize_cli-0.13.1}/docs/plans/2026-09-app-roadmap/run-11b-playback-pause/validate-exit.sh

@@ -26,7 +26,7 @@ set -uo pipefail
 
 PASS=0
 FAIL=0
-TIMEOUT="${CHECK_TIMEOUT:-120}"
+TIMEOUT="${CHECK_TIMEOUT:-300}"
 
 # Portable timeout: GNU coreutils on Linux, gtimeout via brew on macOS, or none.
 # The no-timeout fallback is `env`, which just runs the command — an empty array

vocalize_cli-0.13.1/docs/plans/2026-09-app-roadmap/run-12-release-0-13-1/report.md

@@ -0,0 +1,10 @@
+# Report: run 12, release 0.13.1
+
+Date 2026-09-21. Branch `hold-to-talk` (worktree `.claude/worktrees/hold-to-talk`). Source plan in [project-plan.md](./project-plan.md); adversarial review in [../review-0.13.0.md](../review-0.13.0.md) § 0.13.1.
+
+- T-110: done — review of dictation changes appended to `review-0.13.0.md` § 0.13.1 covering Run 11 (cue trim, hold-to-talk, auto-paste), Spoken Rendering Rules (40 rules, `[speech]` config table), and Run 11b (playback pause & resume with stop-hotkey toggle); no open Critical or High finding.
+- T-111: pending publish — manual checks 9–11 and 15–16 verified in runs 11 and 11b; ready for owner squash-merge into `main`, wheel build/publish to PyPI, and digest verification.
+
+Security gate: session nonce matching, paste marker 0600 mode with `O_NOFOLLOW` and `O_NONBLOCK`, monotonic forward session states, and `interrupted.txt` privacy verified (`tests/test_dictate.py`, `tests/test_cli.py`).
+
+Suite: 2,231 passed, 3 skipped. Ruff clean. Pre-publish gate 13 of 14 passed (14th is PyPI publication check).

{vocalize_cli-0.13.0 → vocalize_cli-0.13.1}/docs/plans/2026-09-app-roadmap/spike-notes.md

@@ -45,3 +45,12 @@ Claude desktop, normal window: down and up, held 2 s.
 Ghostty (self-drawn terminal): down and up, held 3 s.
 Claude desktop, full-screen: down and up, held 3 s.
 Decision: Carbon (DEC-033 A). No Accessibility grant needed for dictation.
+
+## Cue
+
+Run 11, T-100, 2026-09-08. The real recorder launched through `dictate._launch_recorder` into a scratch workdir, `take.wav` polled every 20 ms from the moment `rec.pid` appeared, three launches per input, owner present.
+branch: trim — the take grows incrementally on both inputs, so the first growth past the 4096-byte header is the open-microphone signal; the cue plays after it and is trimmed from the head.
+Yeti Stereo Microphone (USB): pid→first growth 383, 359, 383 ms; launch→pid 152, 149, 153 ms; growth in 10240-byte steps (about 320 ms of 16 kHz audio per write).
+Mat's AirPods Pro (Bluetooth): pid→first growth 500, 521 ms (a third run measured 50 ms, which was the 4096-byte header landing on a file that did not exist yet, not audio — the baseline must be the header, see below); launch→pid 147, 154, 146 ms; growth in about 5460-byte steps (about 170 ms per write).
+Baseline rule for `_wait_for_audio`: the file may not exist at pid time, and its first write is a 4096-byte header with no audio in it; t0 is the first moment the size exceeds max(first observed size, 4096). `_AUDIO_GRACE` 5 s is ten times the worst case seen.
+Write granularity bounds the cue's lateness at one write (320 ms USB, 170 ms Bluetooth); late is the safe side, because the user speaks after the cue and the trim covers t0 to the end of the cue.

vocalize_cli-0.13.1/docs/research/2026-09-08-spoken-rendering-rules.md

@@ -0,0 +1,119 @@
+# Spoken rendering rules
+
+This spec says how vocalize turns written text into text a voice reads well. Every rule is a pure string change in `preprocess.py`, expressed only in punctuation and line breaks every engine honours. `--raw` bypasses all of it.
+
+## Principles
+
+- **A pause is a comma or a full stop.** The only two marks Kokoro, `say` and the cloud voices all honour.
+- **Rewrite, never decorate.** A construct becomes ordinary words and punctuation, not a marker.
+- **Structure gets words, not longer silence.** Pause length isn't adjustable without SSML, so headings, quotes and skipped sections spend a short cue word instead.
+- **Under-strip.** Anything ambiguous, nested, malformed or over-long is left as it is today.
+- **A period is only a sentence end when it really is one.** Abbreviation and digit-to-digit periods are protected.
+- **Blocks are separated by a blank line.** The pause is the full stop, not the newline — no engine is known to lengthen a pause there.
+- **Every rule is a test row,** and `flatten_markdown` run twice equals once.
+
+## The rules
+
+Bracket order: footnote, then numeric citation, then word bracket; checkboxes and ref-links are excluded from all three.
+
+| Construct | Spoken as | Example in → out | Default | Config |
+|---|---|---|---|---|
+| Soft line wrap | one space, no pause | `wraps\nonto` → `wraps onto` | join | fixed |
+| Blank line | full stop if the block lacks `.?!:`, then a blank line | `First para\n\nSecond.` → `First para.\n\nSecond.` | on | fixed |
+| Heading, levels 1–2 (ATX `#`, or setext `===`/`---` underline directly under text) | `Heading,` cue, then text (keeps its own `?`/`!`, adds nothing) | `# Title One` → `Heading, Title One.` | cue | `headings` |
+| Heading, levels 3–6 | `Sub-heading,` cue | `### Sub Three` → `Sub-heading, Sub Three.` | cue | `headings` |
+| Em dash, en dash or spaced hyphen as a dash | comma | `clear—we shipped` → `clear, we shipped`; `simple - just restart` → `simple, just restart` | comma | fixed |
+| En dash between numbers | the word "to" | `pages 3–5` → `pages 3 to 5` | to | fixed |
+| Guard, leave as-is: compound hyphen, digit-period, numbers/units/times/percents, ALL CAPS | unchanged | `well-known`, `3.5 GB, v2.0.1`, `12:30, 50%`, `URGENT NOTICE` → all unchanged | unchanged | fixed |
+| Parenthetical mid-sentence | comma, content, comma | `results (which surprised everyone) were` → `results, which surprised everyone, were` | pause | `parentheticals` |
+| Parenthetical at a sentence end, or a whole sentence | comma at the bracket if mid-sentence continues; brackets vanish if the parenthetical is the whole sentence | `The trend is clear (see fig. 3).` → `The trend is clear, see fig 3.`; `(See the appendix.)` → `See the appendix.` | pause | `parentheticals` |
+| Square brackets around words | comma, content, comma (guard: nested, unmatched or over-long stays untouched) | `the plan [the second one] was` → `the plan, the second one, was`; `((a+b)*c)` → unchanged | pause | `parentheticals` |
+| Task-checkbox / reference-style link | resolved as a plain item or link, not a citation | `- [x] done` → `First, done.`; `[the docs][1]` → `the docs` | unchanged | fixed |
+| Abbreviation period, title list | period always deleted (a title is always followed by a name) | `Dr. Smith` → `Dr Smith` | strip | `abbreviations` |
+| Abbreviation period, context list | kept before a capital word or block end (it may be a sentence end); dropped before a lowercase word, digit or comma | `pens, etc. Then start.` → unchanged; `Fig. 3` → `Fig 3` | keep/strip | `abbreviations` |
+| Abbreviation, Latin list | expanded, comma kept (see list below) | `e.g. chips` → `for example, chips` | expand | `abbreviations` |
+| Initials | periods deleted, letters spaced | `J. R. R. Tolkien` → `J R R Tolkien` | strip | `abbreviations` |
+| Bulleted or numbered list | ordinals or `Item N:`, as today | `- one\n- two` → `First, one. Second, two.`; `1. buy milk` → `Item 1: buy milk.` | unchanged | fixed |
+| Nested list item | `Sub-item,` cue; parent count skips it | `- a\n  - b\n- c` → `First, a. Sub-item, b. Second, c.` | cue | `nested_lists` |
+| Table | row sentences, as today, in their own block | Q1 revenue row → `Table with 1 row. For Q1: Revenue is 4.2M.` | unchanged | fixed |
+| Inline code, bold, italic, HTML tag | markers or tags stripped, text kept | `` `pip install` `` → `pip install`; `a<br>b` → `a b` | unchanged | fixed |
+| Code block, fenced or indented (4 spaces) | one placeholder sentence, own block | `Here's the fix:` + fence → `Here's the fix:\n\nSkipping a code block.` | unchanged | fixed |
+| Markdown link, image | link text, or alt text ("image" if none) | `[the docs](url)` → `the docs`; `![Revenue chart](c.png)` → `Revenue chart` | unchanged | fixed |
+| Bare URL | host, dots as the word "dot" | `https://example.com/page` → `example dot com` | domain | `urls` |
+| Block quote | `>` stripped, `Quote,` cue, `End quote.` only if longer than one line | `> A line.\n> Two.` → `Quote, A line. Two. End quote.` | cue | `blockquotes` |
+| Footnote marker, body line | dropped (body announced once per document) | `support[^1].` → `support.`; `[^1]: Smith, 2019.` → nothing (`Skipping 1 footnote.`) | drop | `citations` |
+| Numeric citation bracket | dropped if tight to a word; a 4-digit year is kept | `shown previously [12].` → `shown previously.`; `[2024]` unchanged | drop | `citations` |
+| Reference list section | one sentence in its place | `## References` + entries → `Skipping the reference list.` | skip | `references` |
+| Page number line, running head or footer | page numbers dropped outright; a repeating head/footer only via the furniture guard: short, unpunctuated, non-list/table/heading, repeated 3+ | `Vocalize User Guide` ×5 → removed; `Yes.` ×3 → unchanged | drop | `furniture` |
+| Horizontal rule, YAML front matter | block break after a blank line (a setext heading if it follows text instead); at document start, dropped and announced only if that's the whole input | `Before.\n\n---\n\nAfter.` → `Before.\n\nAfter.`; `---\ntitle: X\n---\nBody.` → `Body.` | drop | fixed |
+| Ellipsis | comma mid-sentence, full stop line-final | `And then... nothing` → `And then, nothing` | comma | fixed |
+| Emoji | dropped, space repaired | `job! 🎉 Let's` → `job! Let's` | drop | `emoji` |
+| Final spacing pass | one space between sentences, blank lines kept, no doubled marks | `Done  .   Next (really) .` → `Done. Next, really.` | on | fixed |
+
+**Title list** (period always dropped): `Dr, Mr, Mrs, Ms, Prof, St`.
+**Context list** (period dropped unless before a capital word or block end): `fig, Fig, No, approx, etc, Inc, al, vs`.
+**Latin list**: `e.g.` → `for example,`; `i.e.` → `that is,`.
+
+## Pauses
+
+| Pause | Written as | What every engine does |
+|---|---|---|
+| None | a space | runs the words together |
+| Breath | `, ` | short break, no intonation reset |
+| Sentence | `. ` (or `? `, `! `) | full stop, new intonation |
+| Block | `.` then a blank line | full stop; the blank line is a hint, not a longer silence |
+
+The blank line matters only past a provider's `MAX_CHARS`, where `split_for_synthesis` actually chunks — below it nothing chunks, so no silence rides on the blank line. Above it, `_PARAGRAPH_SPLIT_RE` breaks there first: a request-boundary effect, not an audible pause.
+
+## The config table
+
+```toml
+[speech]
+headings       = "cue"      # cue | plain | off
+blockquotes    = "cue"      # cue | plain | off
+nested_lists   = "cue"      # cue | flat | off
+parentheticals = "pause"    # pause | drop | off
+abbreviations  = "expand"   # expand | protect | off
+citations      = "drop"     # drop | speak | off
+references     = true       # skip reference-list sections
+furniture      = true       # drop repeated running heads/footers
+urls           = "domain"   # domain | full | drop
+emoji          = true       # drop emoji
+
+SPEECH_BRACKET_MAX_CHARS     = 120  # bracket-guard length
+SPEECH_FURNITURE_MAX_CHARS   = 60   # furniture line length cap
+SPEECH_FURNITURE_MIN_REPEATS = 3    # repeats to drop furniture
+```
+
+`off` always means: leave that construct exactly as written.
+
+Wiring mirrors `[notes]`/`[stt]`: add `speech` to `KNOWN_SPEECH_KEYS`, add `_validate_speech_table` (unknown key warns, bad value raises; `SPEECH_*` bounded like `stt.max_seconds`), add `resolve_speech` against `SPEECH_DEFAULTS`. `flatten_markdown(text, speech=None)` keeps every call site working.
+
+## Decisions
+
+All seven approved by the owner on 2026-09-08. The config table's defaults are these.
+
+1. **Heading cue.** Use `Heading,` for levels 1–2 and `Sub-heading,` for 3–6.
+2. **Parentheticals.** Default to pause; drop silently deletes content you asked to hear.
+3. **Block quotes.** Cue on by default, so quoted words aren't mistaken for the author's.
+4. **Bare URLs.** Read the host only, as "example dot com".
+5. **Reference sections.** Skip References, Bibliography or Works Cited only when the lines after look like entries; "Notes" doesn't trigger it.
+6. **Latin abbreviations.** Expand them, because "e g" is one of the worst sounds today.
+7. **Emoji.** Drop them, because behaviour differs on every engine.
+
+`flatten_markdown` has one call site, `vocalize/cli.py:318` — notes and dictation never pass through it.
+
+## What this supersedes
+
+- **Issue #8, kept:** cue-and-pause headings, pauses at paragraph/list/table boundaries, parenthetical pause-content-pause with a drop mode, abbreviation periods never sentence ends.
+- **Issue #8, changed:** the heading cue is a comma clause, not a sentence; parenthetical pauses are commas, not periods; no "longer pause" — depth is spoken as words.
+- **Issue #7, kept:** running heads, page numbers, cite markers, footnote bodies and reference lists all removed.
+- **Issue #7, changed:** a reference list is announced, not silently deleted; "Notes" no longer triggers the skip.
+- **Not doing:** SSML, `[[slnc]]`, a pronunciation lexicon, acronym expansion, number verbalisation, emoji naming, language detection.
+
+## Next
+
+1. Order: block rules (furniture, front matter, references, fences/indented code, tables, rules, headings, quotes, lists), then inline rules (emoji, footnotes, citations, brackets, links, URLs, HTML tags, emphasis, dashes, ellipsis), then abbreviations and initials last (they need un-bracketed text), then the spacing pass.
+2. Fix `re.sub(r"\s+", " ")` to collapse only spaces and tabs, and `truncate_for_budget` to split on any whitespace.
+3. Rewrite `tests/test_preprocess.py` as one input-expected table (a row per rule above), plus two property tests: flatten is idempotent, and the output holds no character outside the allowed set (assert only, never filter — `R&D`, `C++`, `24/7` must survive).
+4. The engines bundle came back a stub, so no engine claim here is measured; before locking defaults, listen to one long document on Kokoro and `say`, checking the blank-line pause, the comma parenthetical, and the heading cue.