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

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

@@ -7,6 +7,76 @@ All notable changes to this project are documented here. Format follows
 
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.12.0
+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
@@ -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
 
@@ -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 ("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
@@ -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
@@ -704,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
@@ -924,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.

{vocalize_cli-0.12.0 → vocalize_cli-0.13.0}/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
 
@@ -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 ("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
@@ -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
@@ -668,15 +721,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 +942,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.0/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` (`hold` arrives in 0.13.1) | `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.

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

@@ -90,6 +90,19 @@ recorder did not start."
 
 ## The hotkey
 
+```bash
+vocalize app install
+```
+
+builds and loads **Vocalize.app**, a menu-bar app that owns the dictation
+hotkey system-wide — no Services menu, no shortcut assignment, no
+per-app Electron gap. It starts at login and stays running; see
+[docs/app.md](app.md) for install, uninstall, status and restart, and
+`vocalize app status` for whether it's currently loaded and which chord
+(if any) failed to register.
+
+Prefer the Quick Action instead?
+
 ```bash
 python3 hooks/install_quick_action.py
 ```
@@ -107,7 +120,7 @@ project was built and tested around, but any unused combination works.
 
 From a terminal, the identical command is `vocalize dictate` (an alias for
 `vocalize listen --toggle`) — useful for testing the toggle without
-touching System Settings at all.
+touching System Settings at all, whichever way you trigger it.
 
 ## Using it
 
@@ -514,8 +527,31 @@ unconditionally and is always safe to run.
 
 ### The hotkey does nothing
 
+**If you installed the app** (`vocalize app install`), start with:
+
+```bash
+vocalize app status
+```
+
 In rough order of likelihood:
 
+1. **`agent: not running`.** The LaunchAgent isn't loaded. Run
+   `vocalize app install` again, or `vocalize app restart` if it was
+   loaded a moment ago.
+2. **`accessibility: not granted`.** Grant it in System Settings ›
+   Privacy & Security › Accessibility. A rebuild resets this grant — see
+   [docs/app.md](app.md#the-re-grant-rule).
+3. **`hotkeys: failed:<name>`.** That chord is already claimed by
+   another app — Hammerspoon and the old Quick Action are the two this
+   project itself might have left behind; see
+   [docs/app.md](app.md#conflicts-hammerspoon-and-the-old-quick-action).
+4. **`bundle: stale` or `not built`.** Run `vocalize app install`.
+5. **Speech-to-text was never installed.** `vocalize listen --check` will
+   say so plainly (exit 1).
+
+**If you installed the Quick Action** (`hooks/install_quick_action.py`)
+instead:
+
 1. **No shortcut is assigned yet**, or it's assigned to something else.
    Check System Settings › Keyboard › Keyboard Shortcuts › Services ›
    Text › "Dictate with Vocalize" — if it isn't listed at all, re-run
@@ -533,7 +569,7 @@ In rough order of likelihood:
    cause for a no-input Service like this one.
 
 `vocalize dictate` from a plain terminal isolates whether the problem is
-the hotkey/Service layer or dictation itself — if that works, the Quick
+the hotkey layer or dictation itself — if that works, the app or Quick
 Action installation is where to look next.
 
 ### Rebuilds and re-granting the microphone