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

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

@@ -3,6 +3,178 @@
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## Unreleased
+
+Nothing yet.
+
+## 0.13.0 - 2026-09-08
+
+### Added
+
+- **The `[app]` config table** for the menu-bar app that arrives in 0.13.0:
+  `dictate`, `speak` and `stop` chords (`ctrl+alt+cmd+d`, `+s`, `+x` by
+  default; tokens joined by `+`, modifiers ctrl/alt/cmd/shift with their
+  long-form aliases, a key of a–z, 0–9 or f1–f12, ctrl or cmd required,
+  `""` disables) and `dictate_mode` (`toggle`; `hold` parses and resolves
+  to toggle with one warning until 0.13.1). The wizard renders it and
+  `vocalize settings` prints `app.<key>=…` in one canonical spelling.
+- **`vocalize app install / uninstall / status [--json] / restart`** —
+  a menu-bar app (`Vocalize.app`) that owns the dictation, speak and stop
+  hotkeys system-wide, as a LaunchAgent, so a hotkey works from any app
+  with no Services menu and no per-app shortcut assignment. `install`
+  builds the bundle, warns about a running Hammerspoon or a Services
+  shortcut assigned to the "Dictate with Vocalize" Quick Action, resets
+  the Accessibility grant
+  only on a rebuild, and loads the LaunchAgent; `status` reports what's
+  built, whether the agent is loaded, and the app's own hotkey and
+  Accessibility state; `restart` kicks the running app without touching
+  the LaunchAgent; `uninstall` removes everything `install` put down
+  and leaves the Accessibility entry in System Settings alone. See
+  [docs/app.md](docs/app.md).
+- **`dictate.session` gains a `state` and a per-dictation `nonce`.**
+  `state` moves through `starting` → `recording` → `transcribing` as a
+  dictation runs, so anything reading the session file (the app included)
+  knows which stage it's watching, not just that one is in progress.
+  `nonce` ties one dictation's session to its eventual `dictate.copied`
+  write. Unknown keys in the file are still ignored.
+- **`vocalize doctor [--json]`** — every readiness row plus the toolchain
+  and environment checks `status` doesn't cover: `cli path`, `uv`,
+  `swiftc`, `claude` on PATH, the running console script's shebang
+  (brew rot), a Hammerspoon or old Quick Action conflict, `vocalize
+  --version` cold-start time, app bundle state with its repair command,
+  and the notes folder's size on disk. Exits 1 only on a failing row;
+  warn rows print but don't fail a script.
+- **`vocalize integrate claude [--yes]`** — one command in place of the
+  hand-rolled `/speak` skill and the standalone Quick Action installer.
+  Checks `vocalize`, `claude`, `node`, and `python3` on PATH, installs
+  `~/.claude/skills/speak/SKILL.md` from the package (kept unless
+  `--yes`), installs the four Quick Actions into `~/Library/Services`,
+  and prints the GUI-only hotkey and Accessibility steps. The Quick
+  Action installer and its `.workflow` bundles moved into the package
+  (`vocalize/assets/quick_actions/`); `hooks/install_quick_action.py` is
+  now a thin wrapper around it. The baked `claude` path is the stable
+  symlink, not `.resolve()`'s version-pinned Caskroom target, so a
+  `brew upgrade claude-code` no longer silently breaks the summary
+  picker.
+- **The Setup tab** in `vocalize portal` — a nine-step checklist
+  (toolchain, both bundles, login item, chords, model download,
+  microphone, `/speak` and Quick Actions, Accessibility, self-test)
+  built from the readiness rows the sidebar shows; its first step points at
+  `vocalize doctor`. Its install
+  buttons drive the existing `/api/local/install` routes, now including
+  target `app`. See [docs/app.md](docs/app.md#the-setup-tab).
+
+### Changed
+
+- **The recorder is built by a general bundle builder.** `build_bundle(BundleSpec)`
+  replaces the recorder-only code path; `build_recorder` is the recorder's
+  door onto it and its build is unchanged byte for byte (a golden test pins
+  the `swiftc` and `codesign` argv, because any drift is a new ad-hoc
+  signature and a microphone re-grant). `vocalize local uninstall --stt`
+  now removes only the recorder bundle and its stamp, never the whole
+  `~/.cache/vocalize/bin`.
+- **`vocalize clip` exits 3, not 1, when it refuses a credential-shaped
+  clipboard.** A script that already treats exit 1 as "something went
+  wrong, try again" can now tell that refusal apart from a real failure.
+
+## 0.12.0 - 2026-09-07
+
+### Changed
+
+- **The default chain is now `kokoro`, then `say`.** A config with no
+  `chain` used to try ElevenLabs first; it now tries the on-device voice
+  first and falls back to macOS `say`. When `say` speaks because the Kokoro
+  model was never installed, the fallback line says so once and names the
+  fix: `vocalize local install`. Users who never set a chain hear `say`
+  after upgrading until they run that install; anyone with an explicit
+  `chain` sees no change. `vocalize usage`, `vocalize status` and the portal
+  now list the local providers first.
+- **Dictation decodes with beam search.** whisper.cpp ran with its greedy
+  decoder, which merged words on fast speech ("toget" for "to get",
+  [#4](https://github.com/matthager12-collab/vocalize/issues/4)). The worker
+  now uses beam search with five beams, whisper.cpp's own default for that
+  strategy. `[stt] beam_size` (1–8) is the escape hatch: `1` restores the
+  greedy decoder if a take is slow to land on your machine. Honest result:
+  on the owner's own voice both decoders still produced "themerge" for
+  "the merge", so beam search improves decoding but does not close #4;
+  that issue stays open. The cost was measured on a 43 s synthetic clip
+  and recorded in `docs/plans/2026-09-app-roadmap/spike-notes.md`.
+
+- **The default dictation model is now `large-v3-turbo-q5_0`.** On the
+  owner's own voice it was the first model to keep "the merge" as two
+  words ([#4](https://github.com/matthager12-collab/vocalize/issues/4));
+  beam search alone did not. It is no slower than `small.en` on an M4 and
+  uses about 90 MB more. **Upgrade note:** if your `[stt]` table sets no
+  `model`, dictation looks for the new default — run
+  `vocalize local install --stt` once (547 MB), or set
+  `model = "small.en"` to keep the lighter model.
+- **`[stt] cleanup` names where the cleanup pass runs.** It was `true` or
+  `false`; it is now `off`, `claude-cli`, `anthropic` or `local` (`local`
+  is accepted today and honoured from 0.14.0). Older `true` / `false`
+  values keep working. The pass lives in a new `vocalize/llm.py`, one seam
+  for every language-model call, and the default prompt now also drops
+  restatements, false starts and filler
+  ([#3](https://github.com/matthager12-collab/vocalize/issues/3)); say
+  "verbatim" as the first word of a take, pass `--verbatim`, or set
+  `[stt] verbatim = true` to keep every word.
+- **Every cloud send is visible.** One stderr line, `vocalize: sent to
+  <backend>`, prints immediately before text leaves the machine and never
+  otherwise; the clipboard notification for a cleaned take says "cleaned
+  up by Claude — sent off this Mac".
+- **`claude -p` sessions are tighter.** The cleanup pass and the plan-
+  speaking hook now pass `--strict-mcp-config`, run from the system
+  temporary directory, and the cleanup pass excludes your own hooks,
+  skills and `CLAUDE.md` (`--setting-sources ""`) and strips any stored
+  Anthropic key from the child's environment.
+- **Provider settings are type-checked** (issue
+  [#5](https://github.com/matthager12-collab/vocalize/issues/5)): a
+  `voice`, `model`, `engine`, `language`, `region` or `profile` that is not
+  a short printable string is refused with a message naming the file and
+  the key, in the CLI and the portal alike.
+- **Sentences no longer run together with the turbo models.** Their
+  segments arrive without a leading space and the worker joined them with
+  nothing ("working.I want"); segments are now joined with one space.
+
+### Fixed
+
+- **A stored key is readable from every Python on the Mac.** macOS pins a
+  keychain item to the binary that created it, so a key stored from the
+  terminal could be invisible, or behind an "Allow" dialog, when Claude
+  Code's shell or an upgraded vocalize asked for it. Keys are now written
+  and read through Apple's own `security` tool (secret on stdin, never on a
+  command line), which is the same accessing application whatever spawned
+  it; the item also records the date the key was last validated, shown by
+  `vocalize auth status`. An older item is replaced in place on the next
+  `vocalize auth login`.
+
+### Added
+
+- **An Anthropic key slot, and a Keys tab that can test and remove.**
+  `vocalize auth login --provider anthropic` stores the key the `anthropic`
+  cleanup backend uses, under its own keychain item; `auth status`,
+  `auth logout` and `vocalize usage` know the slot too. It is a key, not a
+  voice: the chain does not accept it. On the portal's Keys tab every slot
+  (the three voice providers and Anthropic) gets **Test without storing**,
+  which checks a key and keeps nothing, and **Remove stored key**, which
+  reads the keychain back before it says the key is gone; each card shows
+  when its key was last checked. The key field is `autocomplete=
+  "new-password"`, the value Safari and Chrome honour on a password field.
+  The Local tab gained a select for the cleanup backend.
+
+- **An Anthropic API backend for the cleanup pass** (`[stt] cleanup =
+  "anthropic"`): one Messages API call with a key from `ANTHROPIC_API_KEY`
+  or the keychain slot `anthropic-api-key`, under a monthly character
+  budget (`[providers.anthropic] monthly_chars`, 2,000,000 when unset)
+  counted in the usage ledger. The key is stored from the CLI or the
+  portal's Keys tab, as described above.
+- **A `[notes]` config table** (`folder`, `template`, `summarizer`,
+  `keep_audio`, `model`) is parsed, validated and preserved by every writer
+  of the config file. `vocalize notes` itself arrives in 0.14.0.
+- **`large-v3-turbo-q8_0`** joins the dictation models: the same turbo model
+  as `q5_0` with 8-bit weights (834 MB on disk), for machines with 16 GB or
+  more. `vocalize local install --stt --model large-v3-turbo-q8_0`. Pinned
+  from a completed download like the other three.
+
 ## 0.11.0 - 2026-09-05
 
 ### Added

vocalize_cli-0.11.0/README.md → vocalize_cli-0.13.0/PKG-INFO

@@ -1,11 +1,48 @@
+Metadata-Version: 2.5
+Name: vocalize-cli
+Version: 0.13.0
+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
+Author: Mat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,cli,elevenlabs,kokoro,local,markdown,text-to-speech
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: elevenlabs>=2.0
+Requires-Dist: keyring>=25
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0; extra == 'dotenv'
+Provides-Extra: polly
+Requires-Dist: boto3>=1.34; extra == 'polly'
+Description-Content-Type: text/markdown
+
 # vocalize
 
 [![CI](https://github.com/matthager12-collab/vocalize/actions/workflows/ci.yml/badge.svg)](https://github.com/matthager12-collab/vocalize/actions/workflows/ci.yml)
 
 A command-line tool that turns text, markdown files, or piped stdin into
-natural-sounding speech using the [ElevenLabs](https://elevenlabs.io) API —
-plus a hook that wires it directly into [Claude Code](https://claude.com/claude-code),
-so Claude's responses get read aloud automatically in your terminal or IDE.
+natural-sounding speech on your own machine by default, with cloud voices as
+an option — plus a hook that wires it directly into
+[Claude Code](https://claude.com/claude-code), so Claude's responses get read
+aloud in your terminal or IDE.
 
 ## Quickstart
 
@@ -14,17 +51,19 @@ pipx install vocalize-cli
 ```
 
 ```bash
-vocalize config
+vocalize local install
 ```
 
-Walks you through your API key, a voice, and a speed, and saves it all.
+Downloads the on-device Kokoro voice once (about 350 MB; needs
+[`uv`](https://docs.astral.sh/uv/)). Skip it and `vocalize` speaks through
+macOS `say` until you come back to it — the fallback line tells you so.
 
 ```bash
 vocalize speak "hello"
 ```
 
-To set up just the key, skip the wizard and run `vocalize auth login` — it
-stores the key in your OS keychain.
+Prefer a cloud voice? See [Providers and fallback](#providers-and-fallback):
+`vocalize config` walks you through a key, a voice and a speed.
 
 ## Why this exists
 
@@ -62,33 +101,8 @@ cd vocalize
 pip install -e .
 ```
 
-Get a free ElevenLabs API key at
-[elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
-(free tier: 10,000 characters/month, API access included, no commercial
-license). Then, recommended, store it in your OS keychain:
-
-```bash
-vocalize auth login
-```
-
-This prompts for the key (input hidden), validates it against the
-ElevenLabs API, and stores it via your OS's own keychain (macOS Keychain,
-Windows Credential Locker, Linux Secret Service) — no plaintext file to
-manage. Piping it in from a secret manager works too:
-
-```bash
-op read op://vault/elevenlabs/key | vocalize auth login --stdin
-```
-
-An environment variable or `.env` file work as well, and take priority over
-the keychain if both are set:
-
-```bash
-export ELEVENLABS_API_KEY=your-key-here
-```
-
-or copy `.env.example` to `.env` and fill it in (requires the optional
-`python-dotenv` extra: `pip install -e ".[dotenv]"`).
+Cloud voices need an API key; storing one is covered under
+[Providers and fallback](#providers-and-fallback).
 
 ## Usage
 
@@ -206,7 +220,8 @@ back to `~/.config/vocalize/config.toml`. Flat keys, no sections:
 ```toml
 chain = ["elevenlabs", "google", "say"]
 
-# Flat keys = ElevenLabs, unchanged since before there was a chain.
+# Flat keys are the original cloud voice's settings, unchanged since
+# before there was a chain; see Providers and fallback.
 voice = "21m00Tcm4TlvDq8ikWAM"
 model = "eleven_flash_v2_5"
 speed = 0.95
@@ -278,8 +293,10 @@ Five tabs:
 - **Chain** — reorder providers, or add and remove one.
 - **Providers** — each provider's voice, model, speed, and monthly budget,
   with a live preview of the voice you're looking at.
-- **Keys** — store or check an API key; the field is masked and never
-  offers to autocomplete.
+- **Keys** — store, test or remove an API key for each provider and for
+  Anthropic (the dictation cleanup backend, not a voice); the field is
+  masked and never offers to autocomplete, a stored key is never shown
+  again, and each card says when the key was last checked.
 - **Usage** — this month's spend and quota per provider.
 - **Local** — install or update the on-device Kokoro and whisper models,
   with progress.
@@ -358,6 +375,41 @@ For the click-by-click setup of each provider — where to go, what to click,
 the one command that stores the credential, the one command that proves it
 works — see [docs/provider-credentials.md](docs/provider-credentials.md).
 
+### Storing a cloud API key
+
+For ElevenLabs, get a free API key at
+[elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys)
+(free tier: 10,000 characters/month, API access included, no commercial
+license). Then, recommended, store it in your OS keychain:
+
+```bash
+vocalize auth login
+```
+
+This prompts for the key (input hidden), validates it against the
+ElevenLabs API, and stores it via your OS's own keychain (macOS Keychain,
+Windows Credential Locker, Linux Secret Service) — no plaintext file to
+manage. On macOS the item is written and read through Apple's own
+`security` tool, so the same key is readable from every Python and app
+that runs vocalize — your terminal, Claude Code's shell, the portal —
+with no keychain dialog, and `vocalize auth status` shows the date it was
+last validated. Piping it in from a secret manager works too:
+
+```bash
+op read op://vault/elevenlabs/key | vocalize auth login --stdin
+```
+
+An environment variable or `.env` file work as well, and take priority over
+the keychain if both are set:
+
+```bash
+export ELEVENLABS_API_KEY=your-key-here
+```
+
+or copy `.env.example` to `.env` and fill it in (requires the optional
+`python-dotenv` extra: `pip install -e ".[dotenv]"`).
+
+
 ## Budgets and the usage ledger
 
 Cloud providers don't stop at their free tier — they bill past it. vocalize
@@ -421,7 +473,8 @@ Use it for one read with `--provider kokoro`, or add it to your chain in
 Long text streams: it's broken into ~400-character pieces, and playback
 starts after the first one is ready — roughly 20–25 seconds of speech —
 instead of waiting for the whole thing to render. Measured on this Mac
-(M3): about 5x faster than real time, peaking around 870 MB of RAM while
+(M3): about 5x faster than real time, peaking around 760 MB of RAM (measured
+on an M4 on 2026-09-07; the M3 spike saw 870 MB) while
 rendering. `vocalize stop`, run from any terminal, halts a Kokoro read
 mid-sentence the same as any other provider.
 
@@ -443,7 +496,7 @@ vocalize local install --stt
 A separate opt-in from Kokoro's `vocalize local install` — nothing here is
 downloaded or built until you run this. It:
 
-1. Downloads one whisper.cpp model (`small.en` by default, ~465 MB) from a
+1. Downloads one whisper.cpp model (`large-v3-turbo-q5_0` by default, ~547 MB) from a
    pinned Hugging Face revision, verified against a pinned sha256 before
    it's kept.
 2. Compiles and ad-hoc signs a small Swift recorder bundle, **Vocalize
@@ -460,13 +513,24 @@ more accurate) or `--model base.en` (~141 MB, fastest, least accurate).
 ### The hotkey
 
 ```bash
-python3 hooks/install_quick_action.py
+vocalize app install
+```
+
+installs and starts **Vocalize.app**, a menu-bar app that owns the
+dictation hotkey (and speak/stop) system-wide, no Services menu or
+per-app shortcut assignment needed — see [docs/app.md](docs/app.md) for
+install, uninstall, status and restart. `vocalize dictate` is the same
+command from a terminal, if you'd rather trigger it that way.
+
+Prefer a Quick Action instead? That still works:
+
+```bash
+vocalize integrate claude
 ```
 
 then assign a shortcut under **System Settings › Keyboard › Keyboard
 Shortcuts › Services › Text › "Dictate with Vocalize"** — ⌃⌥⌘D is free by
-default and a sensible pick. `vocalize dictate` is the same command from a
-terminal, if you'd rather trigger it that way.
+default and a sensible pick.
 
 ### How a dictation works
 
@@ -517,10 +581,12 @@ overrides `[stt] max_seconds` for one invocation.
 
 ```toml
 [stt]
-model = "small.en"     # base.en | small.en | large-v3-turbo-q5_0
-language = "en"        # a whisper.cpp language code
+model = "large-v3-turbo-q5_0"  # base.en | small.en | large-v3-turbo-q5_0 | large-v3-turbo-q8_0
+language = "en"        # a whisper.cpp language code ("auto" to detect)
 input_device = ""      # "" = system default; else an exact name from --list-devices
-cleanup = false        # send the transcript (never audio) to Claude first
+cleanup = "off"        # off | local | claude-cli | anthropic — what tidies the transcript (never audio)
+verbatim = false       # true keeps every word even when cleanup is on
+beam_size = 5          # 1-8 whisper.cpp beams; 1 is the greedy decoder
 max_seconds = 120      # 1-600; the recorder self-stops here, dictate backstops it
 sounds = true          # the Tink/Pop/Glass feedback sounds
 cues = "sounds"        # "sounds" | "words" | "both" — speak "Start."/"Stopped."/"Ready." instead
@@ -528,10 +594,12 @@ cues = "sounds"        # "sounds" | "words" | "both" — speak "Start."/"Stopped
 
 | Key | Allowed values | Default |
 |---|---|---|
-| `model` | `base.en`, `small.en`, `large-v3-turbo-q5_0` | `small.en` |
+| `model` | `base.en`, `small.en`, `large-v3-turbo-q5_0`, `large-v3-turbo-q8_0` | `large-v3-turbo-q5_0` |
 | `language` | a whisper.cpp language code (`en`, `es`, `fr`, …); an `.en` model must stay `en` | `en` |
 | `input_device` | `""` (system default) or an exact name from `vocalize listen --list-devices`; ≤ 128 characters, printable, can't start with `-` | `""` |
-| `cleanup` | `true` / `false` | `false` |
+| `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` |
 | `max_seconds` | integer, 1–600 | `120` |
 | `sounds` | `true` / `false` | `true` |
@@ -552,6 +620,37 @@ set it:
 input_device = "MacBook Pro Microphone"
 ```
 
+### Configuration: the `[app]` table
+
+The chords the menu-bar app owns, system-wide. A change needs
+`vocalize app restart` before the app picks it up.
+
+```toml
+[app]
+dictate = "ctrl+alt+cmd+d"   # start/stop dictation
+dictate_mode = "toggle"      # toggle | hold ("hold" arrives in 0.13.1)
+speak = "ctrl+alt+cmd+s"     # speak the selection
+stop = "ctrl+alt+cmd+x"      # stop whatever is playing
+```
+
+| Key | Allowed values | Default |
+|---|---|---|
+| `dictate` | a chord, or `""` to disable | `ctrl+alt+cmd+d` |
+| `dictate_mode` | `toggle`, `hold` | `toggle` |
+| `speak` | a chord, or `""` to disable | `ctrl+alt+cmd+s` |
+| `stop` | a chord, or `""` to disable | `ctrl+alt+cmd+x` |
+
+**Chord grammar:** tokens joined by `+`. Modifiers are `ctrl`, `alt`,
+`cmd`, `shift` (long spellings `control`, `option`, `command` also work);
+the key is one of `a`-`z`, `0`-`9`, `f1`-`f12`. A chord must include
+`ctrl` or `cmd` — macOS refuses to register the rest. The three chords
+must differ from each other, and `""` disables one.
+
+A bad chord is a `ConfigError` naming the key, the value and the legal
+keys — and, like any bad config value, it stops the command you ran, so
+fix it before anything else works. `vocalize settings` prints the four
+`app.*` values in their canonical spelling.
+
 ### `vocalize status`
 
 ```bash
@@ -574,6 +673,17 @@ get four permanent red rows for a feature nobody asked for):
 providers and dictation both — is `ok`, 1 otherwise, so it composes with
 `&&` in a script.
 
+### `vocalize doctor`
+
+Everything `status` checks plus the machine itself: the CLI's own path and
+start-up time, `uv`, `swiftc`, `claude`, the console script's interpreter,
+Hammerspoon, the app bundle and the notes folder. Every row regardless of the
+chain, exit 1 when any row fails. `--json` for scripts.
+
+```bash
+vocalize doctor
+```
+
 ### Continuing an interrupted read
 
 Starting a dictation stops any read in progress, but doesn't throw the rest
@@ -647,15 +757,16 @@ Four Services let you use vocalize from any app without a terminal:
 Install all four:
 
 ```bash
-python3 hooks/install_quick_action.py
+vocalize integrate claude
 ```
 
-This copies the bundles from `hooks/quick_actions/` into
-`~/Library/Services/` with this machine's absolute `vocalize`, `claude`,
-and helper paths baked in, then refreshes the Services registry. Run it
-from a normal terminal — its PATH is what gets captured. To trigger the
-actions from the keyboard, assign shortcuts under System Settings →
-Keyboard → Keyboard Shortcuts → Services (Stop Vocalize is worth a
+This installs the `/speak` skill plus the four Quick Action bundles into
+`~/Library/Services/`, with this machine's `vocalize`, `claude`, and
+helper paths baked in (the stable symlinks, not their resolved targets —
+survives a `brew upgrade claude-code`), then refreshes the Services
+registry. Run it from a normal terminal — its PATH is what gets captured.
+To trigger the actions from the keyboard, assign shortcuts under System
+Settings → Keyboard → Keyboard Shortcuts → Services (Stop Vocalize is worth a
 shortcut of its own so you can silence a read from anywhere).
 
 Some Electron apps (Claude Code desktop among them) don't expose the
@@ -867,9 +978,10 @@ model.
   there. Use `--no-play` and open the saved file with whatever's on hand.
 - **The disk cache under `~/.cache/vocalize` grows unbounded.** It's
   content-addressed (keyed by a hash of text, voice, model, format, and
-  speed),
-  so it's always safe to delete some or all of it — nothing will break,
-  you'll just re-pay for a re-synthesized clip.
+  speed), so it's always safe to delete — except `bin/`, which holds
+  Vocalize Recorder and is tied to your microphone grant; deleting that
+  forces a rebuild and a re-grant. Delete anything else and nothing will
+  break, you'll just re-pay for a re-synthesized clip.
 - **`--api-key` on the command line is visible to other local processes**
   (anything that can run `ps`). Prefer `vocalize auth login`, the
   `ELEVENLABS_API_KEY` environment variable, or a `.env` file instead.
@@ -908,9 +1020,11 @@ model.
   re-approve it in System Settings › Privacy & Security › Microphone. An
   install that doesn't change the source never re-signs, so this isn't
   every upgrade — only ones that touch the recorder.
-- **`small.en` mishears jargon.** The default model does fine on ordinary
-  speech but can mangle project-specific words (`pyproject`, a function
-  name) — pick `large-v3-turbo-q5_0` for better accuracy, or turn on
+- **The smaller models mishear jargon.** `large-v3-turbo-q5_0` is the
+  default because it was the first model to keep "the merge" as two words
+  on the owner's own voice; `small.en` (465 MB) is the lighter choice for a
+  slow Mac but can mangle project-specific words (`pyproject`, a function
+  name) — stay on the default for accuracy, or turn on
   `[stt] cleanup` so Claude fixes obvious transcription noise before it
   reaches your clipboard (it still can't guess a word it never heard
   correctly).