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

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

@@ -3,6 +3,108 @@
 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.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.12.0/PKG-INFO

@@ -1,11 +1,48 @@
+Metadata-Version: 2.5
+Name: vocalize-cli
+Version: 0.12.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
@@ -517,10 +570,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 +583,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` |
@@ -908,9 +965,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).

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

@@ -1,47 +1,12 @@
-Metadata-Version: 2.5
-Name: vocalize-cli
-Version: 0.11.0
-Summary: A CLI that turns text, markdown, or piped stdin into speech via the ElevenLabs API, with markdown-table-aware preprocessing.
-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,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
 
@@ -50,17 +15,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
 
@@ -98,33 +65,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
 
@@ -242,7 +184,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
@@ -314,8 +257,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.
@@ -394,6 +339,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
@@ -457,7 +437,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.
 
@@ -479,7 +460,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
@@ -553,10 +534,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
@@ -564,10 +547,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` |
@@ -944,9 +929,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).