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

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

@@ -5,7 +5,106 @@ 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
+
+### 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
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.12.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
@@ -513,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
 
@@ -589,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` |
@@ -609,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
+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
@@ -631,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
@@ -640,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
 ```
@@ -704,15 +758,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
@@ -924,9 +979,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.

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

@@ -477,13 +477,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
 
@@ -553,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` |
@@ -573,6 +584,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
+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
@@ -595,6 +637,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
@@ -604,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
 ```
@@ -668,15 +722,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
@@ -888,9 +943,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.

vocalize_cli-0.13.1/docs/app.md

@@ -0,0 +1,205 @@
+# The menu-bar app
+
+`Vocalize.app` is a small Swift menu-bar app that owns the dictation and
+speak-selection hotkeys system-wide. It replaces both the Hammerspoon
+config and the Quick Action as the way to trigger vocalize from the
+keyboard — it runs all the time, as a LaunchAgent, so a hotkey works from
+any app without a terminal or a Service menu.
+
+It does one job: listen for its three chords, then run the matching
+`vocalize` command (`dictate`, `clip`, `stop`) as a subprocess. It never
+touches your microphone or clipboard itself and never reads the audio or
+the transcript — `vocalize` does that work, same as if you'd typed the
+command.
+
+## Install
+
+```bash
+vocalize app install
+```
+
+This:
+
+1. Checks that the `vocalize` you're running right now is one the app can
+   find. The app only looks in `~/.local/bin`, `/opt/homebrew/bin` and
+   `/usr/local/bin`; if yours isn't one of those, install prints a
+   `defaults write` line (see [Pointing the app at a different
+   vocalize](#pointing-the-app-at-a-different-vocalize) below) and stops —
+   pass `--yes` to print the same line and continue anyway.
+2. Warns if Hammerspoon is running, or if the "Dictate with Vocalize"
+   Quick Action has a keyboard shortcut on one of the app's chords —
+   either can steal it (see
+   [Conflicts](#conflicts-hammerspoon-and-the-old-quick-action)).
+3. Builds `Vocalize.app` under `~/Library/Application Support/vocalize`
+   if it isn't already current — see [The re-grant
+   rule](#the-re-grant-rule) for what happens when a build replaces one
+   that was already there.
+4. Writes the LaunchAgent plist at
+   `~/Library/LaunchAgents/cards.arda.vocalize.app.plist` and loads it,
+   so the app starts now and again at every login.
+
+It asks to confirm first, listing exactly what it's about to write.
+`--yes` skips that prompt.
+
+## Status
+
+```bash
+vocalize app status
+vocalize app status --json
+```
+
+Reports what's built, whether the LaunchAgent is loaded, and what the
+app itself last wrote about its hotkeys and Accessibility grant:
+
+| Row | Reports |
+|---|---|
+| `bundle` | `current`, `stale`, or `not built` — read-only, this never triggers a build |
+| `agent` | `loaded`, `not running`, or `unknown` — from `launchctl`; a result it can't parse reads as `unknown`, never `not running` |
+| `accessibility` | `granted`, `not granted`, or `unknown` |
+| `hotkeys` | `ok`, `failed:<name>`, or `unknown` — which chord, if any, failed to register |
+| `hotkey_backend` | `carbon` or `monitor` — which macOS API is handling the keys |
+| `vocalize` | the path the app resolved, or `none` |
+
+The last four come from the app's own status file and can be stale
+between runs — the app only rewrites it when something changes.
+
+`--json` prints the same six keys as one object. Exit code is 0 when
+`bundle` is `current` and `agent` is `loaded`, 1 otherwise, so it
+composes with `&&` in a script.
+
+## Chords
+
+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` | `toggle` |
+| `speak` | speak the selection | `ctrl+alt+cmd+s` |
+| `stop` | stop whatever is playing | `ctrl+alt+cmd+x` |
+
+```toml
+[app]
+dictate = "ctrl+alt+cmd+d"
+dictate_mode = "toggle"
+speak = "ctrl+alt+cmd+s"
+stop = "ctrl+alt+cmd+x"
+```
+
+Tokens join with `+`. Modifiers are `ctrl`, `alt`, `cmd`, `shift` (or the
+long `control`, `option`, `command`); the key is one of `a`-`z`, `0`-`9`,
+`f1`-`f12`. Every chord needs `ctrl` or `cmd`, because macOS refuses to
+register the rest. The three must differ from each other; `""` disables
+one.
+
+A chord the parser rejects is a config error, and config is read by
+almost every command — so a typo here stops `vocalize speak` and
+`vocalize status` too, with a message naming the key and the legal keys.
+`vocalize doctor` still runs, and reports it as a failed `config file`
+row. The running app keeps the chords it already registered until the
+file is valid again and you run `vocalize app restart`.
+
+## Restart
+
+```bash
+vocalize app restart
+```
+
+Stops and starts the running app without touching the LaunchAgent or
+rebuilding anything — the equivalent of quitting it from its own menu
+and having it come back. Use this after a config change (a new chord
+under `[app]`) instead of a full `install`.
+
+## Uninstall
+
+```bash
+vocalize app uninstall
+```
+
+Unloads the app and removes what `install` put on this machine: the
+bundle, the LaunchAgent plist, the app's status and log files, and the
+`VocalizeBinary` override if one was set. It lists exactly what it's
+about to remove and asks first; `--yes` skips the prompt.
+
+The Accessibility entry itself stays in System Settings — macOS keeps a
+record of every app that ever asked, uninstalled or not — remove it
+there if you want it gone too. Dictation and the recorder's own
+microphone grant are a separate install (`vocalize local install --stt`)
+and are untouched by this command.
+
+## The re-grant rule
+
+The app's Accessibility permission is tied to its ad-hoc code signature,
+the same way the recorder's microphone permission is (see
+[docs/dictation.md](dictation.md#rebuilds-and-re-granting-the-microphone)).
+`install` only rebuilds the bundle — and only resets the grant — when one
+of these is true:
+
+- the Swift source changed since the bundle was last built, or
+- the bundle or its stamp file is missing (deleted by hand, or by
+  `app uninstall`, or by clearing `~/Library/Application Support`
+  yourself).
+
+Either one produces a new signature, so `install` runs
+`tccutil reset Accessibility cards.arda.vocalize.app` before loading it
+and prints:
+
+```
+Vocalize.app was rebuilt — its Accessibility grant was reset; re-grant it in
+System Settings › Privacy & Security › Accessibility the next time it asks
+```
+
+A plain `install` on an already-current bundle never touches `tccutil` —
+most upgrades don't touch the Swift source, so most re-installs cost you
+nothing.
+
+## Pointing the app at a different vocalize
+
+The app doesn't search your `PATH` — it only checks three fixed
+locations. If `install` reports your `vocalize` isn't one of them, run
+the line it prints:
+
+```bash
+defaults write cards.arda.vocalize.app VocalizeBinary /path/to/vocalize
+```
+
+Uninstalling removes this override automatically.
+
+## The Setup tab
+
+`vocalize portal` has a **Setup** tab, after Local. It walks the nine
+setup steps — toolchain, building both bundles, the login item, chords,
+the model download, the microphone, `/speak` and Quick Actions,
+Accessibility, and a self-test — as a checklist built from the readiness
+rows the sidebar shows (step 1 points at `vocalize doctor`), so it's always
+current with what's actually on the machine. Its "Install the app" button drives this same `app install`
+sequence (build, plist, bootout, bootstrap, and the Accessibility reset on
+a rebuild) through the portal instead of the CLI; the GUI-only steps still
+print from `vocalize integrate claude`, not the page.
+
+## Quit stays quit
+
+The app's own menu has a Quit item, and quitting it stays quit — it does
+not relaunch itself the next time it crashes on purpose or the way a
+typical LaunchAgent does on every exit. It comes back at your next login,
+or the next time you run `vocalize app restart` or `install`.
+
+## Conflicts: Hammerspoon and the old Quick Action
+
+Two older ways of binding the same keys can steal a chord out from under
+the app, so its hotkey silently does nothing:
+
+- **Hammerspoon**, if it's still running and still has the old
+  `hs.hotkey.bind` lines for dictate/speak. `install` checks for a
+  running Hammerspoon and, if found, tells you to remove the
+  `ctrl-alt-cmd-S` and `ctrl-alt-cmd-X` bind lines from
+  `~/.hammerspoon/init.lua` and reload Hammerspoon.
+- **A Services keyboard shortcut** on the "Dictate with Vocalize" or
+  "Stop Vocalize" Quick Action. `vocalize integrate claude` installs both
+  on purpose, and keeping them is fine — they stay reachable from the
+  Services menu. What conflicts is *assigning* ctrl-alt-cmd-D or
+  ctrl-alt-cmd-X to one in System Settings › Keyboard › Keyboard
+  Shortcuts › Services: the assignment wins and the app's hotkey never
+  fires. `install` says so when the Quick Action is present.
+
+Neither check blocks the install; they're warnings, not a hard stop.