From f74536e5cd43237a6105328ba0533d36fbd34e75 Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 00:55:57 +0100
Subject: [PATCH 1/9] Make the app the product, not the CLI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

yap shipped as a CLI that happened to draw a menu bar. Onboarding was
`yap setup`, the login item was `yap install`, a missing grant printed
into a log file nobody reads, and the .app existed only so the build
could be notarized. This turns that around: the .app is the product and
the CLI keeps the two things a terminal is genuinely better at.

- The CLI is `run` and `bench`. `setup`, `install`, `start`, `stop`,
  `doctor`, `record` and `models` are gone, along with every `run` flag
  the Settings window already covers.
- The status item goes up before the model loads, so a first run is
  visible for the minutes it spends downloading instead of invisible.
  A press during that says so rather than recording into nothing.
- Onboarding is in the menu: rows for Accessibility, the microphone and
  a hijacked Fn key, each one click from the right Settings pane. The
  daemon no longer exits when Accessibility is missing — it watches for
  the grant and starts the tap the moment it lands, no relaunch.
- Settings gains a General pane: launch at login, updates, logs.
- The hotkey is recorded rather than picked from five options. Any
  modifier held alone, or a chord like cmd+shift+space, which is
  swallowed so the app underneath never sees it.
- The transcript pill gains Delete, to the Trash, with Undo.
- yap updates itself from GitHub Releases: checksum, then a signature
  check against the team the running code is signed by, then a menu item
  that is never offered mid-recording.

The press now acknowledges itself before the mic opens, which is the
one latency change: pill on screen 1.9 ms after key-down (p50 of 10)
against 69.7 ms before, because it used to wait out Core Audio.
Transcription is untouched — 39 ms p50 on a 5 s clip, on the number.

A 0.2 login item passes --skip-doctor, a flag that no longer exists.
That argument is ignored and the plist rewritten on the first start, or
launch-at-login would have become a relaunch loop on upgrade.
---
 .github/workflows/ci.yml                      |   2 +-
 .github/workflows/release.yml                 |  35 +-
 README.md                                     | 104 +-
 Sources/yap/Agent.swift                       | 189 ----
 Sources/yap/Config.swift                      |  23 +-
 Sources/yap/Daemon.swift                      | 848 +++++++++++++++
 Sources/yap/Doctor.swift                      | 335 ------
 Sources/yap/Input/HotkeyBinding.swift         | 239 +++++
 Sources/yap/Input/HotkeyMonitor.swift         | 233 +++--
 Sources/yap/Install.swift                     | 160 ---
 Sources/yap/LaunchAgent.swift                 | 157 +++
 Sources/yap/Models/ModelRegistry.swift        |   3 -
 Sources/yap/Models/TranscriptionModel.swift   |  18 -
 Sources/yap/Paths.swift                       |  15 +
 Sources/yap/Permissions.swift                 |  86 ++
 Sources/yap/Setup.swift                       | 159 ---
 .../TranscriptionCoordinator.swift            |  80 +-
 Sources/yap/UI/HotkeyRecorder.swift           | 225 ++++
 Sources/yap/UI/MenuBarController.swift        | 171 ++-
 Sources/yap/UI/PromptPanel.swift              |  38 +-
 Sources/yap/UI/RecordingOverlay.swift         |   8 +
 Sources/yap/UI/SettingsModel.swift            |  74 +-
 Sources/yap/UI/SettingsPanes.swift            |  45 +-
 Sources/yap/UI/SettingsWindow.swift           |  12 +-
 Sources/yap/UI/StatusIcon.swift               |  27 +-
 Sources/yap/Updater.swift                     | 405 +++++++
 Sources/yap/Yap.swift                         | 990 ++----------------
 Tests/yapTests/HotkeyBindingTests.swift       | 102 ++
 Tests/yapTests/HotkeyMonitorTests.swift       | 154 +++
 scripts/build-release.sh                      |   8 +
 scripts/dev-install.sh                        | 123 +--
 31 files changed, 2921 insertions(+), 2147 deletions(-)
 delete mode 100644 Sources/yap/Agent.swift
 create mode 100644 Sources/yap/Daemon.swift
 delete mode 100644 Sources/yap/Doctor.swift
 create mode 100644 Sources/yap/Input/HotkeyBinding.swift
 delete mode 100644 Sources/yap/Install.swift
 create mode 100644 Sources/yap/LaunchAgent.swift
 create mode 100644 Sources/yap/Permissions.swift
 delete mode 100644 Sources/yap/Setup.swift
 create mode 100644 Sources/yap/UI/HotkeyRecorder.swift
 create mode 100644 Sources/yap/Updater.swift
 create mode 100644 Tests/yapTests/HotkeyBindingTests.swift
 create mode 100644 Tests/yapTests/HotkeyMonitorTests.swift

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 311a2a8..5f2aaf2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -46,7 +46,7 @@ jobs:
         run: |
           BIN=.build/arm64-apple-macosx/release/yap
           "$BIN" --help
-          "$BIN" models list
+          "$BIN" --version
           "$BIN" bench --help
 
       # The embedded __TEXT,__info_plist is what lets TCC attribute the
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 9dc3db1..e1dc0b5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -106,9 +106,12 @@ jobs:
         id: pkg
         working-directory: dist
         run: |
-          DMG="yap-${{ steps.v.outputs.version }}.dmg"
-          shasum -a 256 "$DMG" > "$DMG.sha256"
-          echo "sha256=$(shasum -a 256 "$DMG" | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+          V="${{ steps.v.outputs.version }}"
+          shasum -a 256 "yap-$V.dmg" > "yap-$V.dmg.sha256"
+          # The in-app updater fetches this one and compares it against the zip
+          # before it unpacks anything.
+          shasum -a 256 "yap-$V.zip" > "yap-$V.zip.sha256"
+          echo "sha256=$(shasum -a 256 "yap-$V.dmg" | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
 
       - name: Publish release
         uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
@@ -116,6 +119,8 @@ jobs:
           files: |
             dist/yap-${{ steps.v.outputs.version }}.dmg
             dist/yap-${{ steps.v.outputs.version }}.dmg.sha256
+            dist/yap-${{ steps.v.outputs.version }}.zip
+            dist/yap-${{ steps.v.outputs.version }}.zip.sha256
           generate_release_notes: true
           fail_on_unmatched_files: true
 
@@ -151,10 +156,10 @@ jobs:
             depends_on macos: :sequoia
 
             app "yap.app"
-            # yap is a CLI first. The bundle exists so the build can be
-            # notarized and so TCC has something stable to hang grants on; this
-            # puts the command itself on PATH.
-            binary "#{appdir}/yap.app/Contents/MacOS/yap"
+            # No "binary" stanza. yap is a menu-bar app; the only subcommand
+            # left is "bench", which is a development tool, and putting a
+            # second path to the same executable on PATH is how the daemon
+            # ended up with two LaunchServices identities in the first place.
 
             # Homebrew replaces /Applications/yap.app, but a process keeps the
             # image it already mapped. Without this you stay on the old version
@@ -188,11 +193,11 @@ jobs:
             # ~/Library/LaunchAgents/<label>.plist, so every upgrade would
             # quietly switch launch-at-login off, and "quit" is recorded and
             # then reopened with "open -b" afterwards, which would start the
-            # daemon outside launchd where neither "yap stop" nor the login
-            # item can reach it.
+            # daemon outside launchd where the login item cannot reach it.
             #
             # Neither is a loss, because the cask never started the daemon.
-            # "yap install --launch-at-login" did, and it owns stopping it.
+            # The "Launch at login" toggle in Settings did, and it owns
+            # stopping it.
 
             # zap only runs on "brew uninstall --zap", which is the one time
             # taking the login item away is what was asked for. launchctl
@@ -208,13 +213,11 @@ jobs:
                 ]
 
             caveats <<~CAVEAT
-              Finish setting up with:
-                yap setup
-                yap install --launch-at-login
+              Launch yap from Applications. It asks for the permissions it
+              needs from the menu bar, and downloads the model in the
+              background on first run.
 
-              The login item belongs to yap rather than to this cask, so a
-              plain uninstall leaves it behind. To remove everything:
-                yap install --uninstall
+              To remove everything, including the login item:
                 brew uninstall --zap --cask yap
             CAVEAT
           end
diff --git a/README.md b/README.md
index 607bb73..7a68a10 100644
--- a/README.md
+++ b/README.md
@@ -13,11 +13,15 @@ No account, no upload. The network gets used once, to fetch the model.
 
 ```sh
 brew install --cask terrifiedbug/tap/yap
-yap setup
 ```
 
-`yap setup` asks for the permissions and pulls the model down. That is 220 MB,
-once, and then you are offline forever.
+Or download the .dmg from [Releases](https://github.com/TerrifiedBug/yap/releases)
+and drag yap to Applications.
+
+Then launch yap from Applications. The menu bar mark appears straight away and
+walks you through the rest: it asks for Accessibility, then the microphone, and
+pulls the model down in the background. That is 220 MB, once, and then you are
+offline forever.
 
 Builds are signed with a Developer ID certificate and notarized by Apple, so
 there is no Gatekeeper prompt. Apple Silicon only, because the model runs on
@@ -28,30 +32,31 @@ the Neural Engine.
 Hold `fn`, speak, release. A small pill shows up while the mic is live, and the
 same mark sits in the menu bar the whole time yap is running.
 
-```sh
-yap install --launch-at-login   # menu bar, back after every login
-yap                             # foreground instead, dies with the terminal
-yap record                      # record a meeting now, ^C to stop
-yap doctor                      # permissions, key mapping, model
-```
+Everything else is in that menu: start a recording, copy the last transcript,
+open Settings, quit. Dictation and the meeting recorder share one process and
+one loaded model. The recorder takes your mic and the system audio as two
+separate tracks and gives you one transcript, with timings and speaker labels.
 
-Dictation and the meeting recorder share one process and one loaded model. The
-recorder takes your mic and the system audio as two separate tracks and gives
-you one transcript, with timings and speaker labels.
+"Settings…" opens a window covering every setting below, and every change lands
+immediately — the daemon does not need a restart to notice. General has the
+login item, updates and a way to the logs; Dictation has the hotkey, which you
+set by clicking the field and pressing the key or chord you want. "Open Config
+File" at the bottom opens the JSON, for anyone who would rather type.
 
-If `fn` does something else on your Mac, `yap doctor` says how to get it back.
-There is also `--hotkey`, and `dictation.hotkey` in the config file.
+If `fn` is set to do something else on your Mac, the menu says so and offers to
+open Keyboard settings.
 
-"Settings…" in the menu bar opens a window covering every setting below, and
-every change lands immediately — the daemon does not need a restart to notice.
-"Open Config File" at the bottom of it opens the JSON, for anyone who would
-rather type.
+"Copy Last Transcript" is there for the press that landed in the wrong window.
+yap holds the most recent one in memory and nowhere else.
 
-"Copy Last Transcript" in the menu bar is there for the press that landed in
-the wrong window. yap holds the most recent one in memory and nowhere else.
+"Quit yap" stops it until you launch it again, or until your next login if
+"Launch at login" is on.
 
-"Quit yap" stops the background daemon until your next login. `yap start`
-brings it back sooner.
+yap keeps itself up to date: it checks GitHub Releases once a day, downloads
+the new build, verifies its signature against the one it is running under, and
+puts "Update to x.y.z · Restart" in the menu. Nothing is replaced until you
+click it, and it is never offered while a recording is in flight. Turn the
+checks off in Settings → General.
 
 One daemon holds the hotkey at a time. Start another — from Applications, from
 a terminal, or because an upgrade restarted the login item — and the new one
@@ -62,26 +67,21 @@ to be seen, look in its hidden section. Managers that file newly-appeared items
 there catch yap the first time it shows up. Reveal that section, then hold
 Command and drag the mark out of it once; it stays where you put it.
 
-| | |
-|---|---|
-| `yap run` | The daemon, in the foreground. The default. |
-| `yap start` / `yap stop` | Start or stop the background daemon. |
-| `yap record` | Record one session now, then transcribe it. |
-| `yap models list` | The models, and which ones you have. |
-| `yap models download <id>` | Fetch one early. |
-| `yap doctor` | Permissions, key mapping, model, login item. |
-| `yap setup` | Permissions and the model, in one go. |
-| `yap install` | Add or remove the login item. |
-| `yap bench --audio FILE` | Time it on your own audio. |
-| `yap --version` | Print the version. |
+There is one command, and it is not needed for anything you do day to day:
+
+```sh
+/Applications/yap.app/Contents/MacOS/yap bench --audio FILE
+```
+
+It times transcription on your own audio. `--version` prints the version.
 
 ## Configuration
 
-`~/.config/yap/config.json`. Every key is optional and a flag beats the file.
-The Settings window is a GUI over this exact file — there is no second store —
-and "Open Config File" in it opens the JSON, filled in with the defaults. An
-upgrade adds a line for anything new, so the file always lists what this yap
-can do. Your own values are never touched.
+`~/.config/yap/config.json`. Every key is optional, and this file is the only
+store there is. The Settings window is a GUI over it — nothing is kept anywhere
+else — and "Open Config File" in it opens the JSON, filled in with the
+defaults. An upgrade adds a line for anything new, so the file always lists
+what this yap can do. Your own values are never touched.
 
 ```json
 {
@@ -92,6 +92,7 @@ can do. Your own values are never touched.
   "mic_voice_processing": true,
   "on_stop": "my-hook",
   "transcription": { "enabled": true },
+  "updates": { "automatic": true },
   "dictation": {
     "model": "parakeet-tdt-ctc-110m",
     "hotkey": "fn",
@@ -105,8 +106,15 @@ can do. Your own values are never touched.
 
 Save it and yap picks it up. The hotkey, `tap_to_toggle`, the overlay,
 `mute_output`, `newline_after_release`, `meeting_detection`,
-`meeting_auto_record` and `meeting_excluded_apps` all change on the spot. A new
-`model` or `recordings_dir` wants a restart, and yap says so when it sees one.
+`meeting_auto_record`, `meeting_excluded_apps` and `updates.automatic` all
+change on the spot. A new `model` or `recordings_dir` wants a restart, and yap
+says so when it sees one.
+
+`hotkey` is a modifier held on its own — `fn`, `rightOption`, `rightCommand`,
+`rightControl`, `rightShift`, `leftOption`, `leftControl`, `leftShift` — or a
+chord like `cmd+shift+space`, or a lone function key like `f5`. The recorder in
+Settings → Dictation writes this for you; a chord is swallowed while yap holds
+it, so the app underneath never sees it.
 
 `newline_after_release` hits Return once the text is in, which is what you want
 for chat boxes.
@@ -153,8 +161,7 @@ and updates its metadata and heading. Turn it off to use yap as a plain
 recorder: `on_stop` then fires when the recording stops rather than after the
 transcript. Nothing is lost either way. Turn it back on, restart, and yap works
 through every session under `recordings_dir` that has no transcript yet, firing
-`on_stop` again for each. Anything you put somewhere else with
-`yap record --out` is left alone.
+`on_stop` again for each.
 
 ## Models
 
@@ -185,15 +192,14 @@ own, and that is a single device read a second.
 ## Uninstall
 
 ```sh
-yap install --uninstall
 brew uninstall --zap --cask yap
 ```
 
-The login item is yap's rather than the cask's, so the first line is what
-takes it away. Skip it and `brew uninstall` on its own leaves launchd trying
-to start a binary that is no longer there. `--zap` also clears the config file
-and the logs. Your recordings are never touched, and neither are the models,
-which are shared with anything else built on FluidAudio.
+`--zap` takes the login item away with it, along with the config file and the
+logs. Installed from the .dmg instead, drag yap out of Applications and delete
+`~/Library/LaunchAgents/com.terrifiedbug.yap.plist`. Your recordings are never
+touched, and neither are the models, which are shared with anything else built
+on FluidAudio.
 
 ## Requirements
 
diff --git a/Sources/yap/Agent.swift b/Sources/yap/Agent.swift
deleted file mode 100644
index 4f202cd..0000000
--- a/Sources/yap/Agent.swift
+++ /dev/null
@@ -1,189 +0,0 @@
-import ArgumentParser
-import Foundation
-
-/// Start and stop the login agent without remembering a `launchctl` line.
-///
-/// "Quit yap" in the menu bar calls `NSApp.terminate`, which exits 0, and the
-/// agent is `KeepAlive` only on failure — so quitting sticks, and getting back
-/// meant knowing `launchctl kickstart gui/$(id -u)/com.terrifiedbug.yap`. For a
-/// menu-bar app whose Quit item is one click away, that is a poor trade.
-///
-/// yap does ship inside a .app now, so double-clicking it in Applications is
-/// another way back. That only helps someone who found it there; `yap start`
-/// is the answer for a CLI you installed with Homebrew.
-enum Agent {
-    /// Whether launchd knows about the job at all.
-    static var isLoaded: Bool {
-        run(["list", Install.label]).status == 0
-    }
-
-    /// Whether it is loaded *and* has a process. The distinction is the whole
-    /// reason `start` needs two different commands: the agent spends its life
-    /// loaded and only sometimes running, and `kickstart` cannot start a job
-    /// launchd has never heard of.
-    static var isRunning: Bool {
-        let listing = run(["list", Install.label])
-        return listing.status == 0 && listing.output.contains("\"PID\" =")
-    }
-
-    static var domain: String { "gui/\(getuid())" }
-    static var target: String { "\(domain)/\(Install.label)" }
-
-    /// Both streams down one pipe: `list` answers on stdout, and every
-    /// refusal launchctl has to offer arrives on stderr, so dropping stderr
-    /// would leave a failed bootstrap reporting nothing but a number.
-    ///
-    /// One pipe rather than two, and read before waiting. Two pipes drained in
-    /// sequence still deadlock the moment the second one fills while the first
-    /// is being read to EOF — and the output here is small enough that the
-    /// interleaving does not matter.
-    @discardableResult
-    static func run(_ args: [String]) -> (status: Int32, output: String) {
-        let task = Process()
-        task.launchPath = "/bin/launchctl"
-        task.arguments = args
-        let pipe = Pipe()
-        task.standardOutput = pipe
-        task.standardError = pipe
-        guard (try? task.run()) != nil else { return (-1, "") }
-        let data = pipe.fileHandleForReading.readDataToEndOfFile()
-        task.waitUntilExit()
-        return (task.terminationStatus, String(decoding: data, as: UTF8.self))
-    }
-
-    /// Wait for the job to stop having a process. Cheap and unambiguous:
-    /// nothing has to start working, it just has to be gone.
-    static func settlesStopped(within seconds: Int) -> Bool {
-        for _ in 0..<(seconds * 4) {
-            if !isRunning { return true }
-            Thread.sleep(forTimeInterval: 0.25)
-        }
-        return !isRunning
-    }
-
-    /// Wait for the daemon to say it is listening, not merely to exist.
-    ///
-    /// A pid is the wrong signal in both directions. `kickstart` returns as
-    /// soon as launchd has spawned something, and on a missing Accessibility
-    /// grant the daemon then exits — quietly, with status 0 — so a pid check
-    /// reports success for a daemon that is already gone. In the other
-    /// direction a cold model cache holds a pid for minutes while several
-    /// hundred megabytes download, long before the hotkey works.
-    ///
-    /// So: watch for the line it prints when the tap is actually live, and
-    /// give up early if the process disappears first.
-    ///
-    /// - Parameter after: size of the log before launching, so only this run's
-    ///   output counts. The log outlives many starts.
-    static func settlesListening(after offset: UInt64, within seconds: Int) -> Bool {
-        for tick in 0..<(seconds * 4) {
-            if logContainsListening(after: offset) { return true }
-            // Grace at the start: launchd has not necessarily spawned it yet.
-            if tick > 8, !isRunning { return false }
-            Thread.sleep(forTimeInterval: 0.25)
-        }
-        return logContainsListening(after: offset)
-    }
-
-    static func logSize() -> UInt64 {
-        (try? FileManager.default.attributesOfItem(atPath: Paths.stderrLog.path)[.size] as? UInt64)
-            .flatMap { $0 } ?? 0
-    }
-
-    private static func logContainsListening(after offset: UInt64) -> Bool {
-        guard let handle = try? FileHandle(forReadingFrom: Paths.stderrLog) else { return false }
-        defer { try? handle.close() }
-        try? handle.seek(toOffset: offset)
-        guard let data = try? handle.readToEnd() else { return false }
-        return String(decoding: data, as: UTF8.self).contains("listening on")
-    }
-
-    static func requireInstalled() throws {
-        guard FileManager.default.fileExists(atPath: Install.plistURL.path) else {
-            throw ValidationError(
-                "no login agent installed — run `yap install --launch-at-login` first")
-        }
-    }
-}
-
-// MARK: - start
-
-struct Start: ParsableCommand {
-    static let configuration = CommandConfiguration(
-        abstract: "Start the background daemon, or restart it if it is already running."
-    )
-
-    func run() throws {
-        try Agent.requireInstalled()
-
-        // Before launching, so only this run's output is examined.
-        let offset = Agent.logSize()
-
-        // Both branches check the status. A rejected launchctl leaves the old
-        // daemon running and no new "listening" line coming, so skipping the
-        // check does not fail — it waits the full ten minutes and then blames
-        // the daemon for something launchctl refused to do.
-        let result: (status: Int32, output: String)
-        if Agent.isLoaded {
-            // -k restarts a running job and starts a stopped one, so this
-            // covers both. Reaching for `yap start` on a daemon that is
-            // already up means wanting it to pick up whatever just changed,
-            // not a message saying it is fine.
-            result = Agent.run(["kickstart", "-k", Agent.target])
-        } else {
-            // `yap stop` boots the job out, so this is the ordinary path back.
-            result = Agent.run(["bootstrap", Agent.domain, Install.plistURL.path])
-        }
-        if result.status != 0 {
-            let detail = result.output.trimmingCharacters(in: .whitespacesAndNewlines)
-            throw ValidationError(
-                "launchctl refused: \(detail.isEmpty ? "status \(result.status)" : detail)")
-        }
-
-        // Long enough for a cold model cache, which downloads several hundred
-        // megabytes before the hotkey works. A warm one takes a second.
-        guard Agent.settlesListening(after: offset, within: 600) else {
-            print("✗ it did not come up.")
-            print("  \(Paths.stderrLog.path) says why — most often Accessibility.")
-            print("  yap doctor")
-            throw ExitCode(1)
-        }
-        print("✓ running")
-    }
-}
-
-// MARK: - stop
-
-struct Stop: ParsableCommand {
-    static let configuration = CommandConfiguration(
-        abstract: "Stop the background daemon. It comes back at your next login."
-    )
-
-    func run() throws {
-        try Agent.requireInstalled()
-
-        guard Agent.isRunning else {
-            print("not running")
-            return
-        }
-
-        // Boot it out rather than signal it. The agent is KeepAlive on
-        // unsuccessful exit, and a process killed by a signal is exactly that,
-        // so SIGTERM would stop it and launchd would put it straight back.
-        //
-        // Booting out unloads the job but leaves the plist on disk, so it
-        // loads again at the next login. Removing it for good is
-        // `yap install --uninstall`; this is the one you can undo.
-        let result = Agent.run(["bootout", Agent.target])
-        if result.status != 0, Agent.isRunning {
-            print("✗ launchctl bootout failed: \(result.output.trimmingCharacters(in: .whitespacesAndNewlines))")
-            throw ExitCode(1)
-        }
-
-        guard Agent.settlesStopped(within: 10) else {
-            print("✗ still running — `launchctl bootout \(Agent.target)`")
-            throw ExitCode(1)
-        }
-        print("✓ stopped — back at your next login, or `yap start`")
-    }
-}
diff --git a/Sources/yap/Config.swift b/Sources/yap/Config.swift
index b22b1b8..745fed8 100644
--- a/Sources/yap/Config.swift
+++ b/Sources/yap/Config.swift
@@ -79,6 +79,13 @@ enum Config {
         load()?["meeting_excluded_apps"] as? [String] ?? []
     }
 
+    /// Whether yap checks GitHub Releases for a newer build. Default on: it
+    /// updates itself in the background and never replaces anything without
+    /// being clicked, so the only thing this switch buys is the daily request.
+    static func updatesAutomatic() -> Bool {
+        section("updates")?["automatic"] as? Bool ?? true
+    }
+
     /// Apple voice processing (acoustic echo cancellation) on the mic, so
     /// speaker playback doesn't bleed into the mic track and get transcribed
     /// as "me". Default on: the mic track always pairs with a system track, so
@@ -99,7 +106,8 @@ enum Config {
         return id
     }
 
-    /// Push-to-talk key name, matching `HotkeyMonitor.Key`.
+    /// Push-to-talk binding, as `HotkeyBinding` serializes it: a modifier
+    /// name like `fn`, a chord like `cmd+shift+space`, or a lone function key.
     static func hotkey() -> String? {
         guard let key = section("dictation")?["hotkey"] as? String, !key.isEmpty else { return nil }
         return key
@@ -160,15 +168,9 @@ enum Config {
         return json
     }
 
-    /// Resolve the recordings root from an optional CLI override.
-    static func resolveRoot(cliOverride: String?) -> URL {
-        if let cliOverride {
-            return URL(
-                fileURLWithPath: (cliOverride as NSString).expandingTildeInPath,
-                isDirectory: true
-            )
-        }
-        return recordingsDir() ?? defaultRoot
+    /// Where recorded sessions land.
+    static func resolveRoot() -> URL {
+        recordingsDir() ?? defaultRoot
     }
 
     // MARK: - File
@@ -185,6 +187,7 @@ enum Config {
           "meeting_detection": false,
           "meeting_auto_record": false,
           "meeting_excluded_apps": [],
+          "updates": { "automatic": true },
           "dictation": {
             "model": "parakeet-tdt-ctc-110m",
             "hotkey": "fn",
diff --git a/Sources/yap/Daemon.swift b/Sources/yap/Daemon.swift
new file mode 100644
index 0000000..cce63b1
--- /dev/null
+++ b/Sources/yap/Daemon.swift
@@ -0,0 +1,848 @@
+import AppKit
+import ApplicationServices
+import ArgumentParser
+import Foundation
+
+/// The daemon: one hotkey, one menu bar, one loaded model, and — when meeting
+/// detection is on — one recording session at a time.
+///
+/// Both halves live here rather than in two controllers because they share
+/// more than they don't: the same transcriber, the same menu-bar state line,
+/// and the same microphone. Keeping them together is what lets a dictation
+/// press and a meeting recording sit next to each other without either one
+/// noticing the other.
+@MainActor
+final class Daemon: NSObject, NSApplicationDelegate {
+    private let transcriber: any Transcriber
+    private let coordinator: TranscriptionCoordinator
+    private let root: URL
+    private let monitor: HotkeyMonitor
+    private let capture = AudioCapture()
+    private let overlay = RecordingOverlay()
+    private let menuBar: MenuBarController
+    private var detector: MeetingDetector?
+    /// The model this daemon loaded, for the state line, the "restart to pick
+    /// it up" warning, and the retry the menu offers when warm-up fails.
+    private let model: TranscriptionModel
+    /// False until the model is warm. Both the hotkey and the record item
+    /// refuse until it flips: a press that silently records into a model that
+    /// cannot transcribe it is worse than a press that says so.
+    private var modelReady = false
+    /// Observer for the system's "the Accessibility list changed" broadcast.
+    /// Held so it can be removed on the way out.
+    private var accessibilityObserver: NSObjectProtocol?
+    /// Observer for the Settings recorder arming and disarming.
+    private var recordingObserver: NSObjectProtocol?
+    /// The binding the tap watches. Held here as well as in the monitor
+    /// because the Fn setup row only applies when Fn is part of it.
+    private var hotkey: HotkeyBinding
+    /// Whether the event tap is up. The grant can arrive at any time, so
+    /// `evaluateSetup` may be called many times before it succeeds and must
+    /// not create a second tap once it has.
+    private var tapRunning = false
+    /// Whether the microphone prompt has been raised this launch. macOS only
+    /// shows it while the status is undetermined, but asking repeatedly for
+    /// an answer the user is still looking at is noise.
+    private var micRequested = false
+    /// Our subscription to the updater, and the version it has staged. The
+    /// menu item's enablement depends on daemon state the updater knows
+    /// nothing about, so the version is held here and re-published whenever a
+    /// press or a session starts or ends.
+    private var updateObserver: UUID?
+    private var stagedUpdate: String?
+    private var configWatcher: ConfigWatcher?
+    /// Opt-in. See the doc comment where it is used.
+    private let echoTranscripts: Bool
+
+    /// True from a successful capture start until the transcript has been
+    /// injected. It guards the release edge — a failed `capture.start()` must
+    /// not look like a press — and stops a session transcript finishing in the
+    /// background from clearing the indicator out from under a live press.
+    private var dictating = false
+    /// True while the capture engine is live — a press, or a latched tap, in
+    /// flight. Distinct from `dictating`, which stays true through the
+    /// transcription that follows and only guards the indicator.
+    private var recording = false
+    /// When the live press started, for telling a tap from a hold in toggle
+    /// mode.
+    private var pressStartedAt = Date.distantPast
+    /// Whether the live press latches (`tap_to_toggle` read at its key-down).
+    /// Decided once per press, same reasoning as `overlayShown`: a config
+    /// saved mid-press must not change what the release edge means.
+    private var pressLatches = false
+    /// Monotonic press id. finishDictation only cleans up for its own press,
+    /// so a completion racing a newer press cannot tear down that press's
+    /// state.
+    private var pressGeneration = 0
+    /// Longer than this and a toggle-mode press is a hold, not a tap.
+    private static let tapThreshold: TimeInterval = 0.5
+    /// Pending lift of the detector's dictation suppression. Held so a new
+    /// press can cancel the previous press's timer.
+    private var unsuppress: DispatchWorkItem?
+    /// Whether this press is showing the pill. Decided once, at the press, so
+    /// a config saved mid-press cannot strand it.
+    private var overlayShown = false
+
+    private var session: RecordingSession?
+    /// Whether the live session was started by the meeting prompt rather than
+    /// by hand. Only those stop themselves when the call ends — silently
+    /// ending a recording someone started deliberately would lose audio they
+    /// asked for.
+    private var autoStarted = false
+
+    init(
+        transcriber: any Transcriber,
+        model: TranscriptionModel,
+        root: URL,
+        hotkey: HotkeyBinding,
+        echoTranscripts: Bool,
+        debugHotkey: Bool
+    ) {
+        self.transcriber = transcriber
+        self.root = root
+        self.model = model
+        self.hotkey = hotkey
+        self.echoTranscripts = echoTranscripts
+        self.monitor = HotkeyMonitor(binding: hotkey, debug: debugHotkey)
+        self.menuBar = MenuBarController(
+            modelID: model.id,
+            hotkeyName: hotkey.displayName,
+            tapToToggle: Config.tapToToggle()
+        )
+        // Opt-in, and it only ever fires for *other* processes: the detector
+        // skips its own pid. Dictation therefore no longer prompts you to
+        // record yourself, which it did back when the two halves were separate
+        // binaries and holding the hotkey looked to the recorder like a call
+        // starting.
+        self.detector = Config.meetingDetectionEnabled() ? MeetingDetector() : nil
+        // The whole point of the merge: the session queue transcribes through
+        // the same warm model dictation uses, so the machine never holds two
+        // copies of it. Passing it in also tells the coordinator not to
+        // release it — the daemon keeps its model hot.
+        self.coordinator = TranscriptionCoordinator(transcriber: transcriber)
+        super.init()
+    }
+
+    func start() {
+        menuBar.onStartRecording = { [weak self] in self?.startSession() }
+        menuBar.onStopRecording = { [weak self] in
+            guard let self else { return }
+            if self.autoStarted { self.detector?.declineCurrentMeeting() }
+            self.stopSession()
+        }
+        menuBar.onGrantAccessibility = { Permissions.openSystemSettings(.accessibility) }
+        menuBar.onGrantMicrophone = { Permissions.openSystemSettings(.microphone) }
+        menuBar.onOpenKeyboardSettings = { Permissions.openSystemSettings(.keyboard) }
+        menuBar.onRetryModel = { [weak self] in self?.loadModel() }
+        menuBar.onInstallUpdate = { Updater.shared.installAndRestart() }
+        // Cheaper and more accurate than polling: the only moment the rows
+        // have to be right is the moment someone opens the menu to look at
+        // them.
+        menuBar.onMenuWillOpen = { [weak self] in self?.evaluateSetup() }
+
+        // The handlers before the queue that fires them: `resumePending`
+        // below runs as soon as the model is warm, and a session finishing
+        // against an unset handler would fall back to a bare notification.
+        Task { [coordinator] in
+            // The handler fires on whatever executor the coordinator drains
+            // on, so hop back before touching the menu bar. Weak, or the
+            // coordinator would own the daemon that owns it.
+            await coordinator.setStatusHandler { [weak self] busy in
+                Task { @MainActor in self?.show(busy: busy) }
+            }
+            await coordinator.setTranscriptReadyHandler { dir in
+                // Fires on the coordinator's executor; hop to the main actor
+                // for AppKit.
+                Task { @MainActor in
+                    showToast(
+                        title: "Transcript ready",
+                        body: dir.lastPathComponent,
+                        button: "Open",
+                        secondaryButton: "Name…",
+                        onSecondary: { [weak self] in self?.promptForName(of: dir) },
+                        destructiveButton: "Delete",
+                        onDestructive: { [weak self] in self?.trashSession(dir) }
+                    ) {
+                        NSWorkspace.shared.activateFileViewerSelecting(
+                            [dir.appendingPathComponent("transcript.md")]
+                        )
+                    }
+                }
+            }
+        }
+
+        // First launch asks, rather than telling a log file. Everything after
+        // that is `evaluateSetup`, which is also what turns the tap on the
+        // moment the box is ticked — no relaunch.
+        if !Permissions.accessibilityGranted {
+            let promptKey = kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String
+            _ = AXIsProcessTrustedWithOptions([promptKey: true] as CFDictionary)
+        }
+        // Not Apple-documented, but it is what every app that watches for this
+        // grant uses: TCC broadcasts it when the Accessibility list changes.
+        // Event-driven, so nothing runs while idle.
+        accessibilityObserver = DistributedNotificationCenter.default().addObserver(
+            forName: NSNotification.Name("com.apple.accessibility.api"),
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            MainActor.assumeIsolated { self?.evaluateSetup() }
+        }
+        evaluateSetup()
+
+        if let detector {
+            wire(detector)
+            detector.start()
+        }
+
+        // The Settings recorder is listening for the very keys the tap
+        // watches. Without this, binding ⌘⇧Space also dictates the sentence
+        // you were not saying.
+        recordingObserver = NotificationCenter.default.addObserver(
+            forName: .yapHotkeyRecording, object: nil, queue: .main
+        ) { [weak self] note in
+            let active = note.userInfo?["active"] as? Bool ?? false
+            MainActor.assumeIsolated { self?.monitor.setSuspended(active) }
+        }
+
+        loadModel()
+
+        // Anything a previous run staged and never installed. Two directory
+        // reads, once, at the only moment nothing is using it.
+        Updater.cleanStaging()
+
+        // Hot reload. Create the file first, so the watcher arms on an inode
+        // rather than standing on the directory waiting for one, and so
+        // "Open Config File" always has something to show.
+        Config.ensureFileExists()
+        // And bring it up to date: an upgrade adds settings, and a config
+        // written by an older yap has no line for any of them. Runs before the
+        // watcher is armed so our own write is not reported as someone editing
+        // the file.
+        Config.ensureEveryKeyPresent()
+        configWatcher = ConfigWatcher { [weak self] in self?.reloadConfig() }
+    }
+
+    // MARK: - startup state
+
+    /// Warm the model, off the launch path.
+    ///
+    /// The status item is up before this runs, which is the whole point: a
+    /// cold cache is a several-hundred-megabyte download, and yap used to
+    /// spend it invisible. Retryable, because the one thing that can fail
+    /// here is a network the user can fix.
+    private func loadModel() {
+        modelReady = false
+        menuBar.setModelLoading(
+            downloading: !ModelStore.isDownloaded(model), sizeMB: model.sizeMB)
+        if !ModelStore.isDownloaded(model) {
+            warn("downloading \(model.id) (~\(model.sizeMB) MB) — one-off")
+        }
+        Task { [weak self] in
+            guard let self else { return }
+            do {
+                try await self.transcriber.warmUp()
+                self.modelReady = true
+                self.menuBar.setModelReady()
+                warn("model ready · \(self.model.id)")
+                // Only now: a backlog transcribing through a model that is
+                // still loading would queue behind the same warm-up anyway,
+                // and this way the state line tells one story at a time.
+                await self.coordinator.resumePending(root: self.root)
+                self.startUpdater()
+            } catch {
+                warn("warmup failed: \(error)")
+                self.menuBar.setModelFailed()
+            }
+        }
+    }
+
+    /// Subscribe the menu bar to the updater, and arm the daily check if the
+    /// config wants it.
+    ///
+    /// After the model, deliberately: the first thing a fresh install does is
+    /// download several hundred megabytes, and competing with that for
+    /// bandwidth to ask about a release is the wrong order.
+    private func startUpdater() {
+        guard updateObserver == nil else { return }
+        updateObserver = Updater.shared.observe { [weak self] state in
+            guard let self else { return }
+            if case .ready(let version, _) = state {
+                self.stagedUpdate = version
+            } else {
+                self.stagedUpdate = nil
+            }
+            self.refreshUpdateItem()
+        }
+        if Config.updatesAutomatic() { Updater.shared.startAutomaticChecks() }
+    }
+
+    /// A restart mid-recording loses the meeting, and mid-press loses the
+    /// sentence. The item stays visible and goes grey instead of vanishing,
+    /// so it does not look like the update went away.
+    private func refreshUpdateItem() {
+        menuBar.setUpdate(version: stagedUpdate, enabled: session == nil && !dictating)
+    }
+
+    /// What macOS is still withholding, and the tap that depends on it.
+    ///
+    /// Called at launch, whenever the menu opens, when the Accessibility list
+    /// changes, and after a config reload — the Fn row depends on which key is
+    /// bound. Idempotent: the tap is only created when it is not already up.
+    private func evaluateSetup() {
+        var needs: MenuBarController.SetupNeeds = []
+        let granted = Permissions.accessibilityGranted
+        if !granted { needs.insert(.accessibility) }
+
+        switch Permissions.microphone {
+        case .denied, .restricted:
+            needs.insert(.microphone)
+        case .notDetermined:
+            // Asked once, in order: Accessibility is the one yap cannot work
+            // without, and stacking two system prompts on a first launch reads
+            // as an app demanding everything at once. `requestMicrophone` only
+            // prompts while the status is undetermined, so this cannot loop.
+            if granted, !micRequested {
+                micRequested = true
+                Permissions.requestMicrophone { [weak self] _ in
+                    Task { @MainActor in self?.evaluateSetup() }
+                }
+            }
+        default:
+            break
+        }
+
+        let fnAction = hotkey.usesFn ? Permissions.fnKeyAction() : nil
+        if fnAction != nil { needs.insert(.fnMapping) }
+        menuBar.setSetupNeeds(needs, fnAction: fnAction)
+
+        // The tap needs the grant, and the grant can arrive at any time. Start
+        // it the moment it does — the whole reason this is event-driven is so
+        // nobody has to relaunch yap after ticking a box.
+        guard granted, !tapRunning else { return }
+        do {
+            try monitor.start { [weak self] event in
+                // The tap callback has already hopped to the main queue.
+                MainActor.assumeIsolated { self?.handle(event) }
+            }
+            tapRunning = true
+            warn("listening on \(hotkey.serialized)")
+        } catch {
+            // Not fatal, and not an exit: the process stays up with the row
+            // visible, so the menu can still say what is wrong. Exiting here
+            // is what used to turn launch-at-login into a relaunch loop.
+            warn("failed to register hotkey tap: \(error)")
+        }
+    }
+
+    /// Finalize anything live before the process goes away. A session killed
+    /// mid-write loses its meta.json and would never be picked up again;
+    /// stopped cleanly it lands on disk with no transcript, which is exactly
+    /// what `resumePending` looks for on the next launch.
+    func applicationWillTerminate(_ notification: Notification) {
+        monitor.stop()
+        detector?.stop()
+        if let accessibilityObserver {
+            DistributedNotificationCenter.default().removeObserver(accessibilityObserver)
+        }
+        if let recordingObserver {
+            NotificationCenter.default.removeObserver(recordingObserver)
+        }
+        // A press in flight holds the mic gain lease. Without this the daemon
+        // exits leaving the user's input turned up.
+        capture.stop()
+        guard let session else { return }
+        session.stop()
+        self.session = nil
+        warn("○ stopped · \(session.dir.path) · will transcribe on next launch")
+    }
+
+    // MARK: - dictation
+
+    private func handle(_ event: HotkeyMonitor.Event) {
+        switch event {
+        case .pressed:
+            // Pressed while the mic is live only happens for a latched tap —
+            // hold mode's edges strictly alternate — and it means "stop".
+            // Deliberately not gated on the config: a latch must always be
+            // stoppable, even if the setting was turned off underneath it.
+            if recording { endDictation() } else { beginDictation() }
+        case .released:
+            guard recording else { return }
+            // Hold mode always ends here. Toggle mode ends here too when the
+            // key was held past the threshold — push-to-talk keeps working —
+            // and otherwise the quick tap leaves the recording latched.
+            let wasHeld = Date().timeIntervalSince(pressStartedAt) > Self.tapThreshold
+            if !pressLatches || wasHeld { endDictation() }
+        }
+    }
+
+    private func beginDictation() {
+        // Nothing to transcribe into. Opening the mic anyway would record
+        // audio the release edge then has to throw away, and the menu bar is
+        // already saying why.
+        guard modelReady else {
+            warn("press ignored — model not loaded")
+            return
+        }
+        // State bookkeeping must not re-run under a second press: capture.start
+        // is idempotent, the generation bump below is not.
+        guard !recording else { return }
+        // Decided once per press. The file can be saved mid-press, and a pill
+        // that appears halfway through — or a level pump feeding a window
+        // nobody can see — is worse than honouring the answer we started on.
+        if Config.overlayEnabled() {
+            overlayShown = true
+            // Fires on an audio thread; pushLevel is nonisolated for exactly
+            // this reason.
+            capture.onLevel = { [overlay] level in overlay.pushLevel(level) }
+        } else {
+            overlayShown = false
+            capture.onLevel = nil
+        }
+        // Before `capture.start()`, not after. Opening the mic is 60-86 ms of
+        // Core Audio bring-up, and a press that shows nothing for that long
+        // reads as a press that did not register — measured, and the single
+        // largest thing standing between key-down and feedback. Nothing here
+        // depends on the mic actually opening, and the failure branch below
+        // takes both back.
+        if overlayShown { overlay.show(.recording) }
+        menuBar.setDictating(true)
+        do {
+            try capture.start()
+        } catch {
+            warn("capture failed: \(error)")
+            if overlayShown { overlay.hide() }
+            overlayShown = false
+            capture.onLevel = nil
+            menuBar.setIdle()
+            return
+        }
+        // After the mic is actually ours, never before: a failed start that
+        // returned above would otherwise leave detection suppressed forever.
+        //
+        // Holding the hotkey wakes macOS's own speech daemon, which takes the
+        // mic under its own pid and so reads as a call starting. Nothing seen
+        // during our own press is evidence of a meeting.
+        unsuppress?.cancel()
+        unsuppress = nil
+        detector?.suppressed = true
+        dictating = true
+        recording = true
+        pressStartedAt = Date()
+        pressLatches = Config.tapToToggle()
+        pressGeneration += 1
+        warn("● dictating")
+        refreshUpdateItem()
+    }
+
+    private func endDictation() {
+        guard recording else { return }
+        // Cleared before the mic goes down, so the stopping tap's own release
+        // edge — and any synthetic release from setKey/reenable — is a no-op.
+        recording = false
+        let samples = capture.stop()
+
+        let seconds = Double(samples.count) / AudioCapture.targetSampleRate
+        let rms = computeRMS(samples)
+        warn(String(format: "○ captured %.2fs · rms %.3f", seconds, rms))
+        guard !samples.isEmpty else {
+            finishDictation(generation: pressGeneration)
+            return
+        }
+
+        if overlayShown { overlay.show(.transcribing) }
+        menuBar.setTranscribing()
+        // Whose press this is. finishDictation refuses to clean up for anyone
+        // else's, so a newer press starting while this one transcribes keeps
+        // its indicator, its overlay and its capture.
+        let generation = pressGeneration
+        // Inherits this method's main-actor isolation, so injection and the
+        // menu-bar reset need no hop; the await on the transcriber suspends
+        // rather than blocks, leaving the main actor free the whole time.
+        Task { [transcriber, echoTranscripts, generation, weak self] in
+            // Timed from the moment the key came up, through injection, so the
+            // log reports what the user actually waits for rather than just
+            // the model. Transcription is nearly all of it, but injection is a
+            // synthetic key event and is not free, and quoting inference alone
+            // would flatter us against tools that report end to end.
+            let started = Date()
+            do {
+                let text = try await transcriber.transcribe(samples)
+                let transcribed = Date().timeIntervalSince(started)
+                // A press that caught only silence transcribes to nothing.
+                // There is no text to place and nothing to tell the user, so
+                // neither branch runs: a bare Return would fire a half-typed
+                // chat message, and the clipboard would lose whatever it held
+                // in exchange for an empty string. The timing line below still
+                // reports the press.
+
+                // Which placement ran. The timing line said "inject" for both,
+                // so a transcript that quietly went to the pasteboard read
+                // exactly like one that was typed.
+                var route = "no text"
+                if !text.isEmpty {
+                    if TextInjector.focusedElementAcceptsText() {
+                        route = "typed"
+                        TextInjector.inject(text)
+                        // Send-on-release. A real key event rather than a "\n"
+                        // in the text, because chat inputs bind send to the
+                        // Return key code. Read here, after injection and off
+                        // the measured path, so it survives a save with no
+                        // restart.
+                        if Config.newlineAfterRelease() {
+                            TextInjector.pressReturn()
+                        }
+                    } else {
+                        route = "clipboard"
+                        // Nowhere to type: posting the events would drop the
+                        // transcript on the floor, and Return with no field is
+                        // worse than useless. Clobbering the pasteboard is the
+                        // lesser loss, and the notification says so.
+                        NSPasteboard.general.clearContents()
+                        NSPasteboard.general.setString(text, forType: .string)
+                        notifyUser(
+                            title: "yap",
+                            body: "No text field focused — transcript copied to clipboard"
+                        )
+                    }
+                    // Both routes: typing can land in the wrong field just as
+                    // the clipboard can be taken away by the next copy. The
+                    // menu holds it in memory only — see setLastTranscript.
+                    self?.menuBar.setLastTranscript(text)
+                }
+                let total = Date().timeIntervalSince(started)
+                // Length, never the words. Under launch-at-login this line
+                // goes to a log file that outlives the session, and a daemon
+                // that quietly keeps a plaintext record of everything you
+                // have ever dictated is a worse problem than any bug it would
+                // help diagnose. --echo-transcripts opts in, and the
+                // LaunchAgent never passes it.
+                let body = echoTranscripts ? " · \(text)" : " · \(text.count) chars"
+                warn(
+                    String(
+                        format: "→ %.0fms (%.0fms model + %.0fms %@)%@",
+                        total * 1000, transcribed * 1000,
+                        (total - transcribed) * 1000, route, body
+                    ))
+            } catch {
+                warn("transcription failed: \(error)")
+            }
+            self?.finishDictation(generation: generation)
+        }
+    }
+
+    private func finishDictation(generation: Int) {
+        // A newer press owns the indicator, the overlay and the detector
+        // suppression now. Clearing them here is the race this guards against:
+        // it used to hide the new press's pill and, because `dictating` went
+        // false under it, leave its capture running with no release to stop it.
+        guard generation == pressGeneration else { return }
+        dictating = false
+        overlay.hide()
+        overlayShown = false
+        // The speech daemon holds the input stream for a beat after the key
+        // comes up — measured at about three seconds against a two second
+        // press. Lifting the suppression here would hand the detector that
+        // tail and let it read as a call, so it waits the tail out.
+        //
+        // A fixed wait rather than tracking which pids were up during the
+        // press: this only ever *delays* a real prompt, never drops one. A
+        // call that starts inside the window is still capturing when the
+        // window closes, and prompts a moment later — against a detector that
+        // already sits on two polls before asking, three seconds is nothing.
+        //
+        // Cancellable, and replaced on every press: two quick presses would
+        // otherwise have the first one's timer fire during the second one's
+        // tail and hand the detector exactly what this avoids. Only the
+        // newest press can lift it.
+        unsuppress?.cancel()
+        let item = DispatchWorkItem { [weak self] in
+            self?.unsuppress = nil
+            self?.detector?.suppressed = false
+        }
+        unsuppress = item
+        DispatchQueue.main.asyncAfter(deadline: .now() + 3, execute: item)
+        // setIdle restores the session line underneath, if a recording is live.
+        menuBar.setIdle()
+        refreshUpdateItem()
+    }
+
+    // MARK: - sessions
+
+    private func startSession(auto: Bool = false, title: String? = nil) {
+        guard session == nil else { return }
+        // Same gate as a press, different report: this one was asked for by a
+        // click, so it owes an answer rather than a log line.
+        guard modelReady else {
+            warn("recording refused — model not loaded")
+            notifyUser(title: "yap — model still loading", body: "Try again in a moment")
+            return
+        }
+        do {
+            let newSession = try RecordingSession(root: root)
+            newSession.title = title
+            try newSession.start()
+            session = newSession
+            autoStarted = auto
+            if !auto {
+                // Started from the menu, so any prompt on screen is offering
+                // something we're already doing — and the pause below would
+                // strand it there for its full two-minute timeout.
+                retirePrompt()
+                // Holding the mic ourselves makes every audio client look
+                // busy, so the detector would scan all of them once a second
+                // to answer a question we'd ignore anyway: a call starting
+                // can't prompt while a session is live. An auto-started
+                // session keeps it, to notice the call it came from ending.
+                detector?.stop()
+            }
+            warn("● recording → \(newSession.dir.path)")
+            menuBar.setRecording(true, since: newSession.startedAt)
+            refreshUpdateItem()
+        } catch {
+            warn("recording start failed: \(error)")
+            notifyUser(title: "yap — recording failed", body: "\(error)")
+        }
+    }
+
+    private func stopSession() {
+        guard let session else { return }
+        session.stop()
+        let elapsed = formatElapsed(Date().timeIntervalSince(session.startedAt))
+        warn("○ stopped · \(elapsed) · \(session.dir.path)")
+        self.session = nil
+        autoStarted = false
+        // No-op when the detector is already running, and nil when detection
+        // is off entirely.
+        detector?.start()
+        detector?.releaseAcceptedMeeting()
+        menuBar.setRecording(false, since: nil)
+        refreshUpdateItem()
+
+        let dir = session.dir
+        Task { [coordinator] in await coordinator.enqueue(dir) }
+    }
+
+    /// End a session this app started by itself. For Ignore, which arrives
+    /// from the auto-record toast after a session is already running and from
+    /// the ask prompt before one exists.
+    private func stopSessionIfAutoStarted() {
+        guard session != nil, autoStarted else { return }
+        stopSession()
+    }
+
+    /// Attach the daemon's handlers. Starting the detector is the caller's
+    /// call: a manual session holds the mic, and detection must stay down
+    /// until it ends.
+    private func wire(_ detector: MeetingDetector) {
+        detector.onMeetingStart = { [weak self, weak detector] pid, appName in
+            guard let self else { return }
+
+            // Before anything else, including the AX title lookup and the
+            // back-to-back stop: an excluded app is invisible to every piece
+            // of meeting logic, not merely unprompted. Read fresh at each
+            // event, the same standing-consent pattern as auto-record below.
+            let bundleID = MeetingTitle.bundleID(forPID: pid)
+            if let bundleID, Config.meetingExcludedApps().contains(bundleID) {
+                warn("◇ \(appName ?? bundleID) is excluded — ignoring")
+                // Marks the pid, so the detector stops re-firing every poll;
+                // its end-of-meeting path clears the mark on its own.
+                detector?.declineCurrentMeeting()
+                return
+            }
+
+            let title = MeetingTitle.capture(forCapturePID: pid)
+            let who = appName ?? "Your microphone"
+            warn("◆ \(who) is in use" + (title.map { " · \($0)" } ?? ""))
+            if let session = self.session {
+                // A quiet gap followed by the same capture pid can be a device
+                // swap or a back-to-back call. Only a vanished meeting window
+                // is evidence that the accepted call ended.
+                guard self.autoStarted,
+                      let oldTitle = session.title,
+                      !MeetingTitle.windowExists(oldTitle, forCapturePID: pid)
+                else { return }
+                warn("◇ \(oldTitle) ended — a different call started")
+                self.stopSession()
+            }
+
+            // "Never ask about this app again", offered from whichever surface
+            // the user is looking at. Both need it to also end the recording
+            // this event may have just started.
+            let ignoreApp: @MainActor () -> Void = { [weak self, weak detector] in
+                guard let bundleID else { return }
+                Config.update { config in
+                    var list = config["meeting_excluded_apps"] as? [String] ?? []
+                    if !list.contains(bundleID) { list.append(bundleID) }
+                    config["meeting_excluded_apps"] = list
+                }
+                warn("◇ \(appName ?? bundleID) added to the ignore list")
+                detector?.declineCurrentMeeting()
+                self?.stopSessionIfAutoStarted()
+            }
+
+            // Standing consent is read at each event so config saves take
+            // effect without a restart. Recording is always announced.
+            if Config.meetingAutoRecord() {
+                self.startSession(auto: true, title: title)
+                guard self.session != nil else { return }
+                detector?.acceptCurrentMeeting()
+                showToast(
+                    title: appName.map { "Recording \($0) call" } ?? "Recording meeting",
+                    body: title ?? "Stop from the menu bar or here",
+                    button: "Stop",
+                    secondaryButton: bundleID != nil ? "Ignore" : nil,
+                    onSecondary: ignoreApp
+                ) { [weak self, weak detector] in
+                    detector?.declineCurrentMeeting()
+                    self?.stopSession()
+                }
+                return
+            }
+
+            askUser(
+                title: appName.map { "\($0) is in a call" } ?? "Your microphone is in use",
+                body: title ?? "Record this meeting?",
+                button: "Record",
+                // Only when we have both a name to show and an identity to
+                // store; a process with no app bundle gets Dismiss and no more.
+                secondaryButton: appName.flatMap { bundleID != nil ? "Ignore \($0)" : nil },
+                onSecondary: ignoreApp,
+                onDismiss: { detector?.declineCurrentMeeting() }
+            ) { [weak self] in
+                guard let self, self.session == nil else { return }
+                detector?.acceptCurrentMeeting()
+                self.startSession(auto: true, title: title)
+            }
+        }
+        // An unanswered prompt outlives the call it asked about (it sits for
+        // two minutes). Accepting it then would start a session no later end
+        // event could stop, so it goes as soon as the mic frees.
+        detector.onMeetingQuiet = { retirePrompt() }
+        detector.onMeetingEnd = { [weak self] in
+            guard let self, self.session != nil, self.autoStarted else { return }
+            warn("◇ call ended")
+            self.stopSession()
+        }
+    }
+
+    /// The transcript toast's Name action: update metadata, heading and folder.
+    private func promptForName(of dir: URL) {
+        let existing = (try? JSONSerialization.jsonObject(
+            with: Data(contentsOf: dir.appendingPathComponent("meta.json"))))
+            .flatMap { ($0 as? [String: Any])?["title"] as? String }
+        askForName(title: "Name this meeting", prefill: existing ?? "") { name in
+            let trimmed = name.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return }
+            let newDir = RecordingSession.applyTitle(trimmed, to: dir)
+            showToast(title: "Saved", body: newDir.lastPathComponent, button: "Open") {
+                NSWorkspace.shared.activateFileViewerSelecting(
+                    [newDir.appendingPathComponent("transcript.md")])
+            }
+        }
+    }
+
+    /// The transcript toast's Delete action.
+    ///
+    /// The Trash, not `removeItem`: a recording is minutes of someone's
+    /// meeting and a mis-click on a pill that appears by itself is easy. That
+    /// is also why there is no confirmation — the Trash *is* the confirmation,
+    /// and Undo puts it back without going near Finder.
+    private func trashSession(_ dir: URL) {
+        var trashed: NSURL?
+        do {
+            try FileManager.default.trashItem(at: dir, resultingItemURL: &trashed)
+        } catch {
+            warn("delete failed: \(error)")
+            notifyUser(title: "yap — couldn't delete", body: error.localizedDescription)
+            return
+        }
+        warn("⌫ trashed \(dir.lastPathComponent)")
+        guard let trashed = trashed as URL? else { return }
+        showToast(title: "Deleted", body: dir.lastPathComponent, button: "Undo") {
+            do {
+                try FileManager.default.moveItem(at: trashed, to: dir)
+            } catch {
+                warn("undo failed: \(error)")
+                notifyUser(title: "yap — couldn't undo", body: error.localizedDescription)
+            }
+        }
+    }
+
+    /// The config file was saved. Everything that can change without a
+    /// restart is re-applied here; the rest is read at the point of use.
+    private func reloadConfig() {
+        hotkey = Resolve.hotkey()
+        monitor.setBinding(hotkey)
+        menuBar.setHotkeyName(hotkey.displayName)
+        // The Fn row only applies while Fn is the key, so a rebind changes
+        // whether it belongs on screen.
+        evaluateSetup()
+        // Only the idle menu line: the mode itself is read at each key-down, so
+        // a flip takes effect on the next press either way.
+        menuBar.setTapToToggle(Config.tapToToggle())
+
+        let wantDetector = Config.meetingDetectionEnabled()
+        if wantDetector, detector == nil {
+            let newDetector = MeetingDetector()
+            detector = newDetector
+            wire(newDetector)
+            // Born mid-press, it would start clean and prompt for the speech
+            // daemon our own hotkey woke. Inherit the suppression: `dictating`
+            // covers a press in flight, a pending lift covers its tail. That
+            // same work item reads `detector` when it fires, so it releases
+            // this one correctly.
+            newDetector.suppressed = dictating || unsuppress != nil
+            // A manual session holds the mic, which makes every audio client
+            // look busy; startSession stops the detector for that reason and
+            // stopSession starts it again. Do not undo that here.
+            if session == nil { newDetector.start() }
+        } else if !wantDetector, let detector {
+            detector.stop()
+            self.detector = nil
+            // The prompt belongs to the detector, and only its quiet event
+            // retires it. Left up, "Record" stays live for two minutes after
+            // the feature was switched off, and would start an auto session
+            // nothing could ever stop — onMeetingEnd went with the detector.
+            retirePrompt()
+            // A session it auto-started earlier does keep recording: silently
+            // ending audio someone is relying on is worse than an orphan, and
+            // it comes off the menu like a manual one.
+        }
+
+        // A few hundred MB of model is not worth reloading under someone's cursor.
+        if let configured = try? Resolve.model(), configured.id != model.id {
+            warn("config: model changed to \(configured.id) — restart yap to load it")
+        }
+
+        // Same reasoning, different reason: a live session is writing into the
+        // old root, and resumePending was handed it at boot. Moving the daemon
+        // mid-flight would strand both.
+        if Config.resolveRoot() != root {
+            warn("config: recordings_dir changed — restart yap to use it")
+        }
+
+        // Only meaningful once the updater is subscribed, which happens after
+        // the model warms; before that `startUpdater` reads the same setting.
+        if updateObserver != nil {
+            if Config.updatesAutomatic() {
+                Updater.shared.startAutomaticChecks()
+            } else {
+                Updater.shared.stopAutomaticChecks()
+            }
+        }
+
+        warn("config reloaded")
+    }
+
+    /// The menu bar has one state line and nowhere to put a queue depth, so a
+    /// draining queue is simply "transcribing". Failures reach the user
+    /// through a notification and the session's transcribe.log instead.
+    private func show(busy: Bool) {
+        // A live dictation press owns the indicator; it will call setIdle
+        // itself when it lands.
+        guard !dictating else { return }
+        if busy { menuBar.setTranscribing() } else { menuBar.setIdle() }
+    }
+}
diff --git a/Sources/yap/Doctor.swift b/Sources/yap/Doctor.swift
deleted file mode 100644
index 3982e0d..0000000
--- a/Sources/yap/Doctor.swift
+++ /dev/null
@@ -1,335 +0,0 @@
-import AVFoundation
-import ApplicationServices
-import Darwin
-import Foundation
-
-enum CheckStatus {
-    case ok
-    case warn(String)
-    case fail(String)
-}
-
-struct Check {
-    let name: String
-    let status: CheckStatus
-    let remediation: String?
-}
-
-/// Everything that has to be true before yap works, in one list.
-///
-/// Both halves of the app report here: dictation needs Accessibility, a clean
-/// Fn key and the mic; recorded sessions additionally need system-audio
-/// capture and somewhere to write. `yap run` runs the same list at startup, so
-/// what `yap doctor` says is exactly what the daemon checked.
-enum DoctorReport {
-    static func run(
-        recordingsRoot: URL,
-        model: TranscriptionModel,
-        hotkey: HotkeyMonitor.Key
-    ) -> [Check] {
-        var checks = [
-            checkMicrophone(),
-            checkAccessibility(),
-        ]
-        // Only Fn is at risk of being stolen by the system; the right-hand
-        // modifiers have no such setting, so the row would be noise.
-        if hotkey == .fn {
-            checks.append(checkFnKeyMapping())
-        }
-        checks.append(checkSystemAudio())
-        checks.append(checkRecordingsRoot(recordingsRoot))
-        checks.append(checkModel(model))
-        if let agent = checkLaunchAgent() { checks.append(agent) }
-        return checks
-    }
-
-    static func checkMicrophone() -> Check {
-        let status = AVCaptureDevice.authorizationStatus(for: .audio)
-        switch status {
-        case .authorized:
-            return Check(name: "microphone", status: .ok, remediation: nil)
-        case .notDetermined:
-            return Check(
-                name: "microphone",
-                status: .warn("not yet requested — will prompt on first use"),
-                remediation: "hold the hotkey once, or start a recording; macOS will prompt"
-            )
-        case .denied, .restricted:
-            return Check(
-                name: "microphone",
-                status: .fail("denied"),
-                remediation:
-                    "System Settings → Privacy & Security → Microphone → enable for \(grantee())"
-            )
-        @unknown default:
-            return Check(name: "microphone", status: .fail("unknown state"), remediation: nil)
-        }
-    }
-
-    /// TCC attributes a grant to the *responsible process*, and for a CLI
-    /// binary that is whichever terminal launched it — not the binary. So the
-    /// row the user has to tick in System Settings says Ghostty or iTerm or
-    /// Terminal, and telling them to look for "yap" sends them hunting for a
-    /// row that will never appear. Hence naming the parent here.
-    ///
-    /// Started by launchd instead, there is no terminal in the chain and the
-    /// grant really does attach to the binary — so `grantee()` names the
-    /// binary there, not the parent. "enable for launchd" would send someone
-    /// looking for a row TCC never creates, which is the same failure this
-    /// check exists to avoid.
-    static func checkAccessibility() -> Check {
-        if AXIsProcessTrusted() {
-            return Check(name: "accessibility", status: .ok, remediation: nil)
-        }
-        return Check(
-            name: "accessibility",
-            status: .fail("not granted"),
-            remediation:
-                "System Settings → Privacy & Security → Accessibility → enable for \(grantee())"
-        )
-    }
-
-    /// macOS routes Fn (🌐) to one of: Do Nothing / Change Input Source / Show Emoji / Start Dictation.
-    /// We need "Do Nothing" so Fn is a clean modifier.
-    static func checkFnKeyMapping() -> Check {
-        guard let value = intDefault(domain: "com.apple.HIToolbox", key: "AppleFnUsageType")
-        else {
-            return Check(
-                name: "fn key mapping",
-                status: .warn("unset — system default may intercept Fn"),
-                remediation: "System Settings → Keyboard → Press 🌐 key to → Do Nothing"
-            )
-        }
-        // Warn, never fail. The tap sees the Fn keypress whatever the system
-        // does with it afterwards, so a stock mapping degrades dictation, it
-        // does not break it. Failing here gated startup through allOK() and
-        // stopped a fresh install running at all on a machine whose Fn key
-        // was still set to whatever macOS shipped.
-        switch value {
-        case 0:
-            return Check(name: "fn key mapping", status: .ok, remediation: nil)
-        case 1, 2, 3:
-            let uses = [1: "Change Input Source", 2: "Show Emoji & Symbols", 3: "Start Dictation"]
-            return Check(
-                name: "fn key mapping",
-                status: .warn("set to \(uses[value] ?? "another action")"),
-                remediation: "System Settings → Keyboard → Press 🌐 key to → Do Nothing"
-            )
-        default:
-            return Check(
-                name: "fn key mapping",
-                status: .warn("unknown value \(value)"),
-                remediation: "System Settings → Keyboard → Press 🌐 key to → Do Nothing"
-            )
-        }
-    }
-
-    /// There is no public API to query the system-audio-capture TCC state
-    /// without side effects, so all we can do is describe the flow.
-    static func checkSystemAudio() -> Check {
-        Check(
-            name: "system audio",
-            status: .warn("state unknowable until first use — will prompt on first recording"),
-            remediation:
-                "if recordings come out silent: System Settings → Privacy & Security → Screen & System Audio Recording"
-        )
-    }
-
-    /// Deliberately creates nothing. `yap doctor` on a machine that only ever
-    /// dictates shouldn't leave an empty ~/Recordings behind, and asking
-    /// whether the nearest existing ancestor is writable answers the same
-    /// question the create would have.
-    static func checkRecordingsRoot(_ root: URL) -> Check {
-        let fm = FileManager.default
-        var probe = root
-        while !fm.fileExists(atPath: probe.path), probe.pathComponents.count > 1 {
-            probe = probe.deletingLastPathComponent()
-        }
-        guard fm.isWritableFile(atPath: probe.path) else {
-            return Check(
-                name: "recordings folder",
-                status: .fail("\(probe.path) is not writable"),
-                remediation:
-                    "fix permissions, or set recordings_dir in \(Config.path.path)"
-            )
-        }
-        return Check(name: "recordings folder", status: .ok, remediation: nil)
-    }
-
-    /// Never discover a missing model after an important meeting — or on the
-    /// first hotkey press. A warning, not a failure: `yap run` warms the model
-    /// at startup and will fetch it, you just wait for the download once.
-    static func checkModel(_ model: TranscriptionModel) -> Check {
-        // Reported ahead of a missing download because it is the one the user
-        // has to act on: a download fixes itself on first use, a model that
-        // cannot time its output never will, and every recorded session is
-        // quietly skipped until the config changes.
-        if Config.transcriptionEnabled(), !model.supportsSessions {
-            return Check(
-                name: "model",
-                status: .warn("\(model.id) cannot transcribe recorded sessions"),
-                remediation:
-                    "dictation works; sessions are skipped until dictation.model is one that "
-                    + "can time its output — see `yap models list`"
-            )
-        }
-        if ModelStore.isDownloaded(model) {
-            return Check(name: "model", status: .ok, remediation: nil)
-        }
-        return Check(
-            name: "model",
-            status: .warn("\(model.id) not downloaded (~\(model.sizeMB) MB)"),
-            remediation: "run `yap models download \(model.id)`, or `yap setup`"
-        )
-    }
-
-    /// Whether the installed launch agent is actually running.
-    ///
-    /// Every check above answers for *this* process, and under launchd that is
-    /// a different one. The gap that matters is Accessibility: run from a
-    /// terminal, `AXIsProcessTrusted` reports the terminal's grant, so doctor
-    /// says "ok" while the agent — which needs a grant against the binary
-    /// itself — exits on startup and leaves nothing running. The grant is also
-    /// keyed to the binary's code signature, so an unsigned rebuild silently
-    /// invalidates it while Settings still shows the row ticked.
-    ///
-    /// Reported as "not running" rather than blamed on Accessibility: the
-    /// daemon exits 0 for several reasons and only its log knows which, so
-    /// this points there instead of guessing.
-    ///
-    /// Nil when no agent is installed — running yap by hand is not a fault.
-    static func checkLaunchAgent() -> Check? {
-        guard FileManager.default.fileExists(atPath: Install.plistURL.path) else { return nil }
-        let listing = Agent.run(["list", Install.label])
-        guard listing.status == 0 else {
-            return Check(
-                name: "launch agent",
-                status: .warn("installed but not loaded"),
-                remediation: "run `yap install --launch-at-login` to load it"
-            )
-        }
-        // `launchctl list <label>` prints the job dictionary, and the PID key
-        // is only there while it is up.
-        guard !listing.output.contains("\"PID\" =") else {
-            return Check(name: "launch agent", status: .ok, remediation: nil)
-        }
-        return Check(
-            name: "launch agent",
-            status: .warn("loaded but not running — it started and exited"),
-            remediation:
-                "see \(Paths.stderrLog.path) for why. Most often Accessibility: launchd runs "
-                + "the binary directly, so the grant has to name \(agentBinary()), and a "
-                + "rebuild invalidates it — remove the stale row in System Settings → Privacy "
-                + "& Security → Accessibility and add it again, then "
-                + "`launchctl kickstart -k gui/$(id -u)/\(Install.label)`"
-        )
-    }
-
-    /// The binary the agent actually launches, read back from its own plist.
-    ///
-    /// Not a fixed path: `Install` writes whichever binary you ran, so the
-    /// agent points into /Applications/yap.app after a Homebrew install and at
-    /// /usr/local/bin/yap after a manual one. Naming the wrong binary here
-    /// sends someone to grant Accessibility to a file launchd never runs,
-    /// which fixes nothing and looks like the advice was wrong.
-    private static func agentBinary() -> String {
-        guard
-            let data = try? Data(contentsOf: Install.plistURL),
-            let plist = try? PropertyListSerialization.propertyList(
-                from: data, format: nil) as? [String: Any],
-            let args = plist["ProgramArguments"] as? [String],
-            let binary = args.first
-        else { return "the installed yap binary" }
-        return binary
-    }
-
-    /// One preference read instead of a `defaults` fork. CFPreferences goes
-    /// through cfprefsd exactly as the `defaults` tool does, and this check
-    /// runs at every daemon start, not just on `yap doctor`.
-    ///
-    /// Both shapes accepted: System Settings writes an integer, but a domain
-    /// edited by hand can hold the same value as a string.
-    private static func intDefault(domain: String, key: String) -> Int? {
-        let value = CFPreferencesCopyAppValue(key as CFString, domain as CFString)
-        return value as? Int ?? (value as? String).flatMap(Int.init)
-    }
-
-    /// The name the permission is actually filed under — see the note on
-    /// `checkAccessibility`.
-    ///
-    /// The parent, except when the parent is launchd. TCC files a CLI
-    /// binary's grant against the responsible process, which is the terminal
-    /// that launched it; launchd is not a responsible process, so under the
-    /// login agent the grant attaches to the executable itself. That is also
-    /// what `checkLaunchAgent` tells people further down, and the two have to
-    /// agree or the report contradicts itself.
-    private static func grantee() -> String {
-        // Unreadable parent. Says nothing about whether launchd is in the
-        // chain, so it must not pick either specific answer — the vague one
-        // is right here, and is what this returned before launchd was
-        // special-cased.
-        guard let parent = parentProcessName() else { return "your terminal" }
-        guard parent == "launchd" else { return parent }
-        // Whatever launchd actually started, which is the file the grant is
-        // keyed to. Not `agentBinary()`: a daemon run from somewhere other
-        // than the installed plist would be misreported by it.
-        return Bundle.main.executablePath ?? "the yap binary"
-    }
-
-    /// Whether the TCC grants this process sees are its own.
-    ///
-    /// True only under launchd, which is not a responsible process, so the
-    /// grant attaches to the executable. From a terminal they belong to the
-    /// terminal app, and `grantee()` cannot reliably name which one: the
-    /// immediate parent is usually the shell, while TCC files the row under
-    /// the terminal that owns the session. Good enough to point someone at a
-    /// list they are already looking at, not good enough to state as fact.
-    static var grantsBelongToThisBinary: Bool {
-        parentProcessName() == "launchd"
-    }
-
-    /// The parent's executable name.
-    ///
-    /// `proc_pidpath` rather than forking `ps -o comm=`: same answer — the
-    /// last component of the executable path — without a process spawn on the
-    /// daemon's startup path. Deliberately not `MeetingDetector.appName`,
-    /// which resolves the enclosing `.app` and returns nil for anything
-    /// without one; `grantee()` above has to be able to tell a launchd parent
-    /// from an unreadable one, and nil cannot say which.
-    private static func parentProcessName() -> String? {
-        var buffer = [UInt8](repeating: 0, count: 4 * Int(PATH_MAX))
-        let length = buffer.withUnsafeMutableBytes {
-            proc_pidpath(getppid(), $0.baseAddress, UInt32($0.count))
-        }
-        guard length > 0 else { return nil }
-        let path = String(decoding: buffer[..<Int(length)], as: UTF8.self)
-        return path.isEmpty ? nil : (path as NSString).lastPathComponent
-    }
-
-    static func print(_ checks: [Check]) {
-        for c in checks {
-            let (mark, label): (String, String) = {
-                switch c.status {
-                case .ok: return ("✓", "ok")
-                case .warn(let msg): return ("!", msg)
-                case .fail(let msg): return ("✗", msg)
-                }
-            }()
-            Swift.print("\(mark) \(c.name): \(label)")
-            if let r = c.remediation {
-                Swift.print("    → \(r)")
-            }
-        }
-    }
-
-    /// True if no checks are in a hard-fail state. Warnings don't block.
-    static func allOK(_ checks: [Check]) -> Bool { firstFailure(checks) == nil }
-
-    /// The first hard failure, for callers that have to name one.
-    static func firstFailure(_ checks: [Check]) -> Check? {
-        checks.first {
-            if case .fail = $0.status { return true }
-            return false
-        }
-    }
-}
diff --git a/Sources/yap/Input/HotkeyBinding.swift b/Sources/yap/Input/HotkeyBinding.swift
new file mode 100644
index 0000000..3714c62
--- /dev/null
+++ b/Sources/yap/Input/HotkeyBinding.swift
@@ -0,0 +1,239 @@
+import CoreGraphics
+import Foundation
+
+/// What yap listens for: a modifier held on its own, or a chord.
+///
+/// Two shapes rather than one, because they are genuinely different events. A
+/// held modifier is a `flagsChanged` edge and nothing else on the machine can
+/// tell — which is why the default is Fn, and why yap can watch for it with a
+/// listen-only tap that never sees a keycode. A chord is a real key press, so
+/// it has to be swallowed or the app underneath gets a stray ⌘⇧Space every
+/// time you dictate.
+///
+/// The serialized form is what `~/.config/yap/config.json` holds and what the
+/// Settings recorder writes.
+enum HotkeyBinding: Equatable {
+    /// One modifier, identified by its device-specific mask so left and right
+    /// can be told apart.
+    case modifier(CGEventFlags)
+    /// A key with zero or more modifiers, device-independent.
+    case chord(modifiers: CGEventFlags, keyCode: CGKeyCode)
+
+    static let fn = HotkeyBinding.modifier(.maskSecondaryFn)
+
+    /// Whether the tap has to subscribe to key events — and therefore whether
+    /// it has to be a `.defaultTap` that can swallow them.
+    var subscribesToKeys: Bool {
+        if case .chord = self { return true }
+        return false
+    }
+
+    /// Whether Fn is part of this binding, which is the only case where what
+    /// macOS has the 🌐 key doing matters.
+    var usesFn: Bool {
+        switch self {
+        case .modifier(let mask): return mask == .maskSecondaryFn
+        case .chord(let modifiers, _): return modifiers.contains(.maskSecondaryFn)
+        }
+    }
+
+    // MARK: - parsing and printing
+
+    init?(parsing text: String) {
+        let normalized = Self.normalize(text)
+        guard !normalized.isEmpty else { return nil }
+        // A bare modifier name first: "fn" and "rightshift" are not chords,
+        // and they are what every config written before this existed says.
+        if let mask = Self.modifierMasks[normalized] {
+            self = .modifier(mask)
+            return
+        }
+
+        var modifiers: CGEventFlags = []
+        var key: CGKeyCode?
+        for part in normalized.split(separator: "+").map(String.init) {
+            if let flag = Self.chordModifiers[part] {
+                modifiers.insert(flag)
+                continue
+            }
+            // Only one key per chord: a second one is a typo, not a binding.
+            guard key == nil else { return nil }
+            if let code = Self.keyCodes[part] {
+                key = code
+            } else if part.hasPrefix("key:"), let raw = UInt16(part.dropFirst(4)) {
+                key = CGKeyCode(raw)
+            } else {
+                return nil
+            }
+        }
+        guard let key else { return nil }
+        self = .chord(modifiers: modifiers.intersection(Self.relevantFlags(for: key)), keyCode: key)
+    }
+
+    /// The canonical text form. Round-trips through `init(parsing:)`.
+    var serialized: String {
+        switch self {
+        case .modifier(let mask):
+            return Self.modifierMasks.first { $0.value == mask }?.key ?? "fn"
+        case .chord(let modifiers, let keyCode):
+            var parts = Self.orderedModifiers.compactMap { name, flag in
+                modifiers.contains(flag) ? name : nil
+            }
+            parts.append(Self.keyName(keyCode))
+            return parts.joined(separator: "+")
+        }
+    }
+
+    /// What a person reads: "Fn", "Right ⌥", "⌘⇧Space".
+    var displayName: String {
+        switch self {
+        case .modifier(let mask):
+            return Self.modifierLabels[serialized] ?? "\(mask.rawValue)"
+        case .chord(let modifiers, let keyCode):
+            let glyphs = Self.orderedModifiers.compactMap { _, flag in
+                modifiers.contains(flag) ? Self.glyphs[flag.rawValue] : nil
+            }.joined()
+            return glyphs + Self.keyLabel(keyCode)
+        }
+    }
+
+    /// Why this binding cannot be used, or nil when it can.
+    ///
+    /// A bare letter is the case that matters: bound alone it swallows every
+    /// "a" you type anywhere on the machine. Function keys are exempt because
+    /// nothing types them.
+    static func validate(_ binding: HotkeyBinding) -> String? {
+        switch binding {
+        case .modifier:
+            return nil
+        case .chord(let modifiers, let keyCode):
+            if !modifiers.isEmpty { return nil }
+            return Self.functionKeyCodes.contains(keyCode) ? nil : "needs a modifier"
+        }
+    }
+
+    // MARK: - tables
+
+    /// Modifiers worth holding on their own, by the device-specific low bits
+    /// macOS packs into the flags word (`NX_DEVICE*KEYMASK` in
+    /// `IOKit/hidsystem/IOLLEvent.h`). Only Fn has a named `CGEventFlags`
+    /// constant; the sided ones are the only way to tell right Shift from left
+    /// Shift at this level, because `.maskShift` is set by both.
+    ///
+    /// Left Command is deliberately absent. Too much of macOS begins with it,
+    /// and a dictation press that starts every ⌘-anything is a trap.
+    static let modifierMasks: [String: CGEventFlags] = [
+        "fn": .maskSecondaryFn,
+        "rightoption": CGEventFlags(rawValue: 0x0000_0040),
+        "rightcommand": CGEventFlags(rawValue: 0x0000_0010),
+        "rightcontrol": CGEventFlags(rawValue: 0x0000_2000),
+        "rightshift": CGEventFlags(rawValue: 0x0000_0004),
+        "leftoption": CGEventFlags(rawValue: 0x0000_0020),
+        "leftcontrol": CGEventFlags(rawValue: 0x0000_0001),
+        "leftshift": CGEventFlags(rawValue: 0x0000_0002),
+    ]
+
+    private static let modifierLabels: [String: String] = [
+        "fn": "Fn",
+        "rightoption": "Right ⌥",
+        "rightcommand": "Right ⌘",
+        "rightcontrol": "Right ⌃",
+        "rightshift": "Right ⇧",
+        "leftoption": "Left ⌥",
+        "leftcontrol": "Left ⌃",
+        "leftshift": "Left ⇧",
+    ]
+
+    /// Device-independent bits, for chords. A chord does not care which Shift.
+    static let chordModifiers: [String: CGEventFlags] = [
+        "cmd": .maskCommand, "command": .maskCommand,
+        "shift": .maskShift,
+        "ctrl": .maskControl, "control": .maskControl,
+        "opt": .maskAlternate, "option": .maskAlternate, "alt": .maskAlternate,
+        "fn": .maskSecondaryFn,
+    ]
+
+    /// The mask a chord is compared against, so an unrelated bit — caps lock,
+    /// the non-coalesced flag — never stops a press matching.
+    static let relevantFlags: CGEventFlags = [
+        .maskCommand, .maskShift, .maskControl, .maskAlternate, .maskSecondaryFn,
+    ]
+
+    /// The flags worth comparing for a particular key.
+    ///
+    /// macOS sets the Fn bit for the whole function and navigation group
+    /// whether or not the 🌐 key is held — F5 on a laptop reports it either
+    /// way, and so does an arrow key. Comparing it there would either record a
+    /// binding that can never match or refuse one that should.
+    static func relevantFlags(for keyCode: CGKeyCode) -> CGEventFlags {
+        implicitFnKeys.contains(keyCode)
+            ? relevantFlags.subtracting(.maskSecondaryFn) : relevantFlags
+    }
+
+    /// Function keys, arrows, and the navigation cluster: everything macOS
+    /// marks with the Fn bit on its own.
+    private static let implicitFnKeys: Set<CGKeyCode> =
+        functionKeyCodes.union([115, 116, 117, 119, 121, 123, 124, 125, 126])
+
+    /// One canonical order for both the text and the glyphs, so a binding
+    /// reads the same in the config file and in the menu bar.
+    private static let orderedModifiers: [(String, CGEventFlags)] = [
+        ("fn", .maskSecondaryFn),
+        ("cmd", .maskCommand),
+        ("ctrl", .maskControl),
+        ("opt", .maskAlternate),
+        ("shift", .maskShift),
+    ]
+
+    private static let glyphs: [UInt64: String] = [
+        CGEventFlags.maskSecondaryFn.rawValue: "fn",
+        CGEventFlags.maskCommand.rawValue: "⌘",
+        CGEventFlags.maskControl.rawValue: "⌃",
+        CGEventFlags.maskAlternate.rawValue: "⌥",
+        CGEventFlags.maskShift.rawValue: "⇧",
+    ]
+
+    /// ANSI/US virtual key codes, from `Carbon/HIToolbox/Events.h`. Names, not
+    /// numbers, so a config file is readable; anything not here round-trips as
+    /// `key:<code>` rather than being rejected.
+    static let keyCodes: [String: CGKeyCode] = [
+        "a": 0, "s": 1, "d": 2, "f": 3, "h": 4, "g": 5, "z": 6, "x": 7, "c": 8, "v": 9,
+        "b": 11, "q": 12, "w": 13, "e": 14, "r": 15, "y": 16, "t": 17,
+        "1": 18, "2": 19, "3": 20, "4": 21, "6": 22, "5": 23, "9": 25, "7": 26, "8": 28, "0": 29,
+        "equal": 24, "minus": 27, "rightbracket": 30, "leftbracket": 33,
+        "o": 31, "u": 32, "i": 34, "p": 35, "l": 37, "j": 38, "k": 40, "n": 45, "m": 46,
+        "quote": 39, "semicolon": 41, "backslash": 42, "comma": 43, "slash": 44,
+        "period": 47, "grave": 50,
+        "return": 36, "tab": 48, "space": 49, "delete": 51, "escape": 53,
+        "f17": 64, "f18": 79, "f19": 80, "f20": 90,
+        "f5": 96, "f6": 97, "f7": 98, "f3": 99, "f8": 100, "f9": 101, "f11": 103,
+        "f13": 105, "f16": 106, "f14": 107, "f10": 109, "f12": 111, "f15": 113,
+        "home": 115, "pageup": 116, "forwarddelete": 117, "f4": 118, "end": 119,
+        "f2": 120, "pagedown": 121, "f1": 122,
+        "left": 123, "right": 124, "down": 125, "up": 126,
+    ]
+
+    private static let functionKeyCodes: Set<CGKeyCode> = [
+        122, 120, 99, 118, 96, 97, 98, 100, 101, 109, 103, 111,
+        105, 107, 113, 106, 64, 79, 80, 90,
+    ]
+
+    private static func keyName(_ code: CGKeyCode) -> String {
+        keyCodes.first { $0.value == code }?.key ?? "key:\(code)"
+    }
+
+    private static func keyLabel(_ code: CGKeyCode) -> String {
+        guard let name = keyCodes.first(where: { $0.value == code })?.key else {
+            return "Key \(code)"
+        }
+        // Single characters read better upper-cased; the named keys read
+        // better capitalized. Both are what a shortcut looks like elsewhere.
+        return name.count == 1 ? name.uppercased() : name.prefix(1).uppercased() + name.dropFirst()
+    }
+
+    /// Case-insensitive, and separators are ignored, so "rightOption",
+    /// "right-option" and "RIGHT_OPTION" all land on the same binding.
+    private static func normalize(_ text: String) -> String {
+        text.lowercased().filter { $0 != "-" && $0 != "_" && $0 != " " }
+    }
+}
diff --git a/Sources/yap/Input/HotkeyMonitor.swift b/Sources/yap/Input/HotkeyMonitor.swift
index e36fdcf..c312918 100644
--- a/Sources/yap/Input/HotkeyMonitor.swift
+++ b/Sources/yap/Input/HotkeyMonitor.swift
@@ -3,50 +3,101 @@ import ApplicationServices
 import CoreGraphics
 import Foundation
 
-/// Watches a single modifier key (default: Fn) and emits press/release edges.
-/// Requires Accessibility permission. If the tap fails to register, callers
-/// will see an error from `start()`.
+/// Watches the configured binding and emits press/release edges. Requires
+/// Accessibility permission; `start()` throws when the grant is missing, and
+/// the daemon puts a row in the menu bar rather than exiting.
 ///
-/// The mask is the primitive; `HotkeyMonitor.Key` names the handful of keys
-/// that make sense to hold down, and is what `--hotkey` and the config file
-/// speak in.
+/// `HotkeyBinding` is what it speaks in — see that file for the two shapes and
+/// why they are different.
 final class HotkeyMonitor {
     enum Event { case pressed, released }
     enum HotkeyError: Error { case tapCreateFailed }
 
-    /// Mask of the modifier we treat as the hotkey. Fn = `.maskSecondaryFn`.
-    private var mask: CGEventFlags
+    private var binding: HotkeyBinding
     private let debug: Bool
     private var onEvent: ((Event) -> Void)?
     private var tap: CFMachPort?
     private var runLoopSource: CFRunLoopSource?
     private var isPressed = false
+    /// Set while the Settings recorder is armed. Every keystroke then belongs
+    /// to the recorder, and a press that also started dictation would record
+    /// the user saying "what". See `setSuspended`.
+    private var suspended = false
 
-    init(mask: CGEventFlags = .maskSecondaryFn, debug: Bool = false) {
-        self.mask = mask
+    init(binding: HotkeyBinding, debug: Bool = false) {
+        self.binding = binding
         self.debug = debug
     }
 
     func start(onEvent: @escaping (Event) -> Void) throws {
         self.onEvent = onEvent
 
-        let promptKey = kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String
-        let trusted = AXIsProcessTrustedWithOptions([promptKey: true] as CFDictionary)
-        if !trusted {
-            warn(
-                "accessibility not granted — system prompt opened. Grant access, then quit and relaunch yap."
-            )
-            throw HotkeyError.tapCreateFailed
+        // Asking is the caller's job now: the daemon raises the system prompt
+        // once at first launch and watches for the grant, so a tap that cannot
+        // be created here is simply reported and retried when the box is
+        // ticked. `tapCreate` returns nil without the grant.
+        guard AXIsProcessTrusted() else { throw HotkeyError.tapCreateFailed }
+        try createTap()
+    }
+
+    func stop() {
+        teardownTap()
+        onEvent = nil
+    }
+
+    /// Swap the binding while the daemon runs.
+    ///
+    /// Cheap when the shape is unchanged — the tap subscribes to the same
+    /// events and `classify` filters — and a full re-create when it is not,
+    /// because a chord needs key events and the ability to swallow them while
+    /// a bare modifier needs neither. The re-create raises no prompt: the
+    /// grant is already held by the time any of this can happen.
+    func setBinding(_ new: HotkeyBinding) {
+        guard new != binding else { return }
+        // A press held across the swap would never see its release edge: the
+        // old binding's key is one we no longer watch. End it here.
+        if isPressed {
+            isPressed = false
+            onEvent?(.released)
+        }
+        let shapeChanged = new.subscribesToKeys != binding.subscribesToKeys
+        binding = new
+        guard shapeChanged, tap != nil else { return }
+        teardownTap()
+        do {
+            try createTap()
+        } catch {
+            warn("failed to re-register hotkey tap for \(new.serialized): \(error)")
         }
+    }
+
+    /// Stand down without tearing the tap down. The Settings recorder holds
+    /// this for as long as it is listening for a new binding.
+    func setSuspended(_ on: Bool) {
+        guard on != suspended else { return }
+        suspended = on
+        guard on, isPressed else { return }
+        isPressed = false
+        onEvent?(.released)
+    }
+
+    // MARK: -
 
-        // flagsChanged only, unless debugging. handle() discards everything
-        // else on the next line, so subscribing to keyDown and keyUp handed
-        // an accessibility-privileged daemon the keycode of every keystroke
-        // typed anywhere on the machine, passwords included, for nothing.
+    private func createTap() throws {
         var mask: CGEventMask = 1 << CGEventType.flagsChanged.rawValue
-        if debug {
+        // flagsChanged only, unless the binding is a chord or we are
+        // debugging. Subscribing to keyDown and keyUp hands an
+        // accessibility-privileged daemon the keycode of every keystroke typed
+        // anywhere on the machine, passwords included — worth it only when the
+        // binding genuinely is a key, and even then the keycode is compared
+        // and dropped, never logged outside --debug-hotkey.
+        if binding.subscribesToKeys || debug {
             mask |= (1 << CGEventType.keyDown.rawValue) | (1 << CGEventType.keyUp.rawValue)
         }
+        // A chord has to be swallowed, and only a .defaultTap can do that. A
+        // held modifier is passed straight through, so it stays listen-only —
+        // byte-identical to what yap has always installed for Fn.
+        let options: CGEventTapOptions = binding.subscribesToKeys ? .defaultTap : .listenOnly
         let userInfo = Unmanaged.passUnretained(self).toOpaque()
 
         // .cgSessionEventTap is the right level for an accessibility-granted
@@ -55,7 +106,7 @@ final class HotkeyMonitor {
             let tap = CGEvent.tapCreate(
                 tap: .cgSessionEventTap,
                 place: .headInsertEventTap,
-                options: .listenOnly,
+                options: options,
                 eventsOfInterest: mask,
                 callback: hotkeyCallback,
                 userInfo: userInfo
@@ -72,7 +123,7 @@ final class HotkeyMonitor {
         self.runLoopSource = source
     }
 
-    func stop() {
+    private func teardownTap() {
         if let tap {
             CGEvent.tapEnable(tap: tap, enable: false)
         }
@@ -81,25 +132,15 @@ final class HotkeyMonitor {
         }
         tap = nil
         runLoopSource = nil
-        onEvent = nil
     }
 
-    /// Swap the watched key while the tap stays up. The tap subscribes to
-    /// every flagsChanged event and `handle` filters by mask, so changing the
-    /// key is a field assignment — no re-registration, and no window where a
-    /// press would be missed.
-    func setKey(_ key: Key) {
-        guard key.mask != mask else { return }
-        // A press held across the swap would never see its release edge: the
-        // old key's flag drops out of a mask we no longer watch. End it here.
-        if isPressed {
-            isPressed = false
-            onEvent?(.released)
-        }
-        mask = key.mask
-    }
-
-    fileprivate func handle(type: CGEventType, event: CGEvent) {
+    /// Decide what an event means, and whether the app underneath should see
+    /// it. Runs synchronously on the tap's own callback, because a swallow
+    /// decision cannot be made after the event has already been passed on.
+    ///
+    /// Internal rather than fileprivate so the decision table can be tested
+    /// against real `CGEvent`s; every other member of this class stays private.
+    func classify(type: CGEventType, event: CGEvent) -> (edge: Event?, swallow: Bool) {
         if debug {
             let flags = event.flags
             let keycode = event.getIntegerValueField(.keyboardEventKeycode)
@@ -107,11 +148,46 @@ final class HotkeyMonitor {
                 "  [debug] type=\(type.rawValue) keycode=\(keycode) flags=\(String(flags.rawValue, radix: 16))"
             )
         }
-        guard type == .flagsChanged else { return }
-        let pressed = event.flags.contains(mask)
-        guard pressed != isPressed else { return }
-        isPressed = pressed
-        onEvent?(pressed ? .pressed : .released)
+        guard !suspended else { return (nil, false) }
+
+        switch binding {
+        case .modifier(let mask):
+            guard type == .flagsChanged else { return (nil, false) }
+            let pressed = event.flags.contains(mask)
+            guard pressed != isPressed else { return (nil, false) }
+            isPressed = pressed
+            // Never swallowed: the tap is listen-only, and a held modifier is
+            // something other apps are entitled to see.
+            return (pressed ? .pressed : .released, false)
+
+        case .chord(let modifiers, let keyCode):
+            let code = CGKeyCode(event.getIntegerValueField(.keyboardEventKeycode))
+            switch type {
+            case .keyDown:
+                guard code == keyCode,
+                    event.flags.intersection(HotkeyBinding.relevantFlags(for: keyCode)) == modifiers
+                else { return (nil, false) }
+                // Autorepeat while held is not a second press, but it must not
+                // reach the app either.
+                guard event.getIntegerValueField(.keyboardEventAutorepeat) == 0, !isPressed else {
+                    return (nil, true)
+                }
+                isPressed = true
+                return (.pressed, true)
+            case .keyUp:
+                guard code == keyCode, isPressed else { return (nil, false) }
+                isPressed = false
+                return (.released, true)
+            case .flagsChanged:
+                // Letting go of ⌘ before Space ends the press. Not swallowed:
+                // the modifier itself is not ours.
+                guard isPressed, !event.flags.contains(modifiers) else { return (nil, false) }
+                isPressed = false
+                return (.released, false)
+            default:
+                return (nil, false)
+            }
+        }
     }
 
     /// Called from the tap callback after macOS disables the tap.
@@ -124,56 +200,9 @@ final class HotkeyMonitor {
         isPressed = false
         DispatchQueue.main.async { [onEvent] in onEvent?(.released) }
     }
-}
 
-extension HotkeyMonitor {
-    /// The modifiers worth holding a dictation press against.
-    ///
-    /// Only Fn has a named `CGEventFlags` constant. The right-hand variants
-    /// come from the device-dependent low bits macOS packs into the same
-    /// flags word (`NX_DEVICER*KEYMASK` in `IOKit/hidsystem/IOLLEvent.h`),
-    /// which is the only way to tell right Shift from left Shift at this
-    /// level — `.maskShift` is set by both. Left-hand variants are
-    /// deliberately absent: they are the ones you actually type with.
-    enum Key: String, CaseIterable {
-        case fn
-        case rightOption
-        case rightCommand
-        case rightControl
-        case rightShift
-
-        var mask: CGEventFlags {
-            switch self {
-            case .fn: return .maskSecondaryFn
-            case .rightOption: return CGEventFlags(rawValue: 0x00000040)
-            case .rightCommand: return CGEventFlags(rawValue: 0x00000010)
-            case .rightControl: return CGEventFlags(rawValue: 0x00002000)
-            case .rightShift: return CGEventFlags(rawValue: 0x00000004)
-            }
-        }
-
-        /// Parse a user-supplied name. Case-insensitive, and separators are
-        /// ignored, so "rightOption", "right-option" and "RIGHT_OPTION" all
-        /// land on the same key.
-        init?(name: String) {
-            let wanted = Self.normalize(name)
-            guard let match = Self.allCases.first(where: { Self.normalize($0.rawValue) == wanted })
-            else { return nil }
-            self = match
-        }
-
-        /// Every accepted name, for error messages.
-        static var names: String {
-            allCases.map(\.rawValue).joined(separator: ", ")
-        }
-
-        private static func normalize(_ s: String) -> String {
-            s.lowercased().filter { $0 != "-" && $0 != "_" && $0 != " " }
-        }
-    }
-
-    convenience init(key: Key, debug: Bool = false) {
-        self.init(mask: key.mask, debug: debug)
+    fileprivate func deliver(_ edge: Event) {
+        DispatchQueue.main.async { [onEvent] in onEvent?(edge) }
     }
 }
 
@@ -196,11 +225,11 @@ private func hotkeyCallback(
         return Unmanaged.passUnretained(event)
     }
 
-    let copy = event.copy()
-    DispatchQueue.main.async {
-        if let copy {
-            monitor.handle(type: type, event: copy)
-        }
-    }
-    return Unmanaged.passUnretained(event)
+    // Classification is synchronous — the swallow decision is this function's
+    // return value and cannot be deferred — while the work it triggers still
+    // hops to the main queue, so nothing the daemon does can stall the tap
+    // into being disabled for running long.
+    let (edge, swallow) = monitor.classify(type: type, event: event)
+    if let edge { monitor.deliver(edge) }
+    return swallow ? nil : Unmanaged.passUnretained(event)
 }
diff --git a/Sources/yap/Install.swift b/Sources/yap/Install.swift
deleted file mode 100644
index be86194..0000000
--- a/Sources/yap/Install.swift
+++ /dev/null
@@ -1,160 +0,0 @@
-import ArgumentParser
-import Foundation
-
-/// Manage yap's LaunchAgent so the daemon starts at login.
-///
-/// We deliberately do NOT use SMAppService.mainApp here. It registers the
-/// enclosing .app, and yap is a CLI that happens to ship inside one: the
-/// bundle exists so the build can be notarized and so TCC has a stable
-/// identity, not so the app can be launched as an app. A plain LaunchAgent
-/// plist names the executable directly, which is the honest description of
-/// what runs, and it works the same whether yap came from Homebrew, the .dmg
-/// or a local build.
-struct Install: ParsableCommand {
-    static let configuration = CommandConfiguration(
-        abstract: "Install or remove the launch-at-login LaunchAgent."
-    )
-
-    @Flag(name: .long, help: "Register yap to start at login.")
-    var launchAtLogin: Bool = false
-
-    @Flag(name: .long, help: "Remove the launch-at-login agent.")
-    var uninstall: Bool = false
-
-    func run() throws {
-        if launchAtLogin == uninstall {
-            warn("specify exactly one of --launch-at-login or --uninstall")
-            throw ExitCode(64)
-        }
-
-        if uninstall {
-            try removeAgent()
-        } else {
-            try writeAgent()
-        }
-    }
-
-    // MARK: -
-
-    /// Not private: `yap doctor` reports on the agent this installs.
-    static let label = "com.terrifiedbug.yap"
-
-    static var plistURL: URL {
-        FileManager.default.homeDirectoryForCurrentUser
-            .appendingPathComponent("Library/LaunchAgents", isDirectory: true)
-            .appendingPathComponent("\(label).plist")
-    }
-
-    private func writeAgent() throws {
-        let binary = try resolveBinaryPath()
-
-        let plist: [String: Any] = [
-            "Label": Self.label,
-            // KeepAlive relaunches anything that exits non-zero, so every
-            // expected-and-unfixable-by-retrying startup state must exit 0 or
-            // launch-at-login becomes a relaunch loop. Two halves to that:
-            // --skip-doctor suppresses the startup report (which would exit 1
-            // on any warning), and Daemon.start() exits 0 rather than 1 when
-            // Accessibility is missing. Neither alone is sufficient.
-            "ProgramArguments": [binary, "run", "--skip-doctor"],
-            "RunAtLoad": true,
-            "KeepAlive": ["SuccessfulExit": false] as [String: Any],
-            "ProcessType": "Interactive",
-            "StandardOutPath": Paths.stdoutLog.path,
-            "StandardErrorPath": Paths.stderrLog.path,
-        ]
-
-        let url = Self.plistURL
-        try FileManager.default.createDirectory(
-            at: url.deletingLastPathComponent(),
-            withIntermediateDirectories: true
-        )
-        let data = try PropertyListSerialization.data(
-            fromPropertyList: plist,
-            format: .xml,
-            options: 0
-        )
-        try data.write(to: url, options: .atomic)
-
-        // Best-effort bootstrap; ignore failure if already loaded.
-        _ = Agent.run(["bootout", Agent.domain, url.path])
-        let result = Agent.run(["bootstrap", Agent.domain, url.path])
-        if result.status != 0 {
-            warn("warning: launchctl bootstrap exited \(result.status):\n\(result.output)")
-        }
-
-        // launchd creates the log files itself and ignores any mode we ask
-        // for, so tighten them here.
-        Paths.restrictLogPermissions()
-
-        print("✓ launch-at-login installed")
-        print("  plist:  \(url.path)")
-        print("  binary: \(binary)")
-        print("  logs:   \(Paths.stdoutLog.path)")
-        print("          \(Paths.stderrLog.path)")
-        print()
-        // Under launchd there is no terminal to inherit a TCC grant from, so
-        // the permissions live against the binary itself rather than against
-        // Ghostty/iTerm/Terminal the way they do when you run yap by hand.
-        print("note: launchd runs the binary directly, not through your terminal,")
-        print("so Accessibility and Microphone have to be granted to")
-        print("\(binary) itself the first time the agent starts.")
-        print()
-        // The agent exits 0 on a missing grant so KeepAlive does not spin it
-        // forever, which also means nothing brings it back once the grant
-        // exists. Saying "grant it" without saying that leaves people looking
-        // at a ticked box and a daemon that is not running.
-        print("Granting does not start it again by itself. After you tick the box,")
-        print("run `yap start`.")
-    }
-
-    private func removeAgent() throws {
-        let url = Self.plistURL
-        if FileManager.default.fileExists(atPath: url.path) {
-            _ = Agent.run(["bootout", Agent.domain, url.path])
-            try FileManager.default.removeItem(at: url)
-            print("✓ launch-at-login removed")
-        } else {
-            print("nothing to remove (no agent at \(url.path))")
-        }
-    }
-
-    /// Which binary launchd should run.
-    ///
-    /// The one you invoked, in almost every case. Preferring
-    /// `/usr/local/bin/yap` instead looks tidy and is wrong: install yap from
-    /// Homebrew on a machine that still has an older copy there, and the agent
-    /// launches the old one for ever. Nothing about that is visible — the new
-    /// binary reports the install succeeded, and the permission advice names a
-    /// file launchd is not going to run.
-    ///
-    /// `Bundle.main.executablePath` is absolute but *not* symlink-resolved: run
-    /// through Homebrew's shim it reports `/opt/homebrew/bin/yap`, and naming
-    /// that in the plist is what cost the daemon its bundle identity, and with
-    /// it the menu bar icon (see `Run.reexecInsideAppBundle`). So resolve it:
-    /// launchd should exec the bundle's own executable, because that is the
-    /// only way LaunchServices publishes yap's bundle identifier. `Run`
-    /// re-execs itself when this plist is an old one that still names the shim.
-    private func resolveBinaryPath() throws -> String {
-        let running = Bundle.main.executablePath
-            .map { URL(fileURLWithPath: $0).resolvingSymlinksInPath().path }
-            .flatMap { FileManager.default.isExecutableFile(atPath: $0) ? $0 : nil }
-        // The exception: a build directory is rebuilt and replaced constantly,
-        // and every rebuild invalidates the Accessibility grant. Point at the
-        // installed copy instead when there is one.
-        if let running, !running.contains("/.build/") {
-            return running
-        }
-        let installed = "/usr/local/bin/yap"
-        if FileManager.default.isExecutableFile(atPath: installed) {
-            if running != nil { warn("note: running from a build directory; using \(installed)") }
-            return URL(fileURLWithPath: installed).resolvingSymlinksInPath().path
-        }
-        if let running {
-            warn("note: no binary at \(installed); using \(running)")
-            return running
-        }
-        warn("couldn't locate the yap binary. install it to \(installed) first.")
-        throw ExitCode(1)
-    }
-}
diff --git a/Sources/yap/LaunchAgent.swift b/Sources/yap/LaunchAgent.swift
new file mode 100644
index 0000000..c99ce41
--- /dev/null
+++ b/Sources/yap/LaunchAgent.swift
@@ -0,0 +1,157 @@
+import Foundation
+
+/// yap's launch-at-login agent, as a plist launchd loads for us.
+///
+/// Deliberately not `SMAppService.mainApp`. That API registers the enclosing
+/// bundle and gives us nothing to say about it; a plain LaunchAgent plist
+/// names the executable directly, and it is the only way to get the two things
+/// this daemon actually needs from launchd — `KeepAlive` so a crash comes back,
+/// and `StandardErrorPath` so the log exists at all. It also works the same
+/// whether yap arrived from Homebrew, the .dmg or a local build.
+///
+/// Writing the plist is the whole of "launch at login": nothing here
+/// bootstraps the job. The app the user just launched is already running, and
+/// bootstrapping a second copy of it under launchd would take the daemon lock
+/// away from the process they are looking at. launchd reads the file at the
+/// next login, which is exactly what the toggle promises.
+enum LaunchAgent {
+    static let label = "com.terrifiedbug.yap"
+
+    static var plistURL: URL {
+        FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent("Library/LaunchAgents", isDirectory: true)
+            .appendingPathComponent("\(label).plist")
+    }
+
+    static var domain: String { "gui/\(getuid())" }
+    static var target: String { "\(domain)/\(label)" }
+
+    /// Whether the login item exists on disk. The Settings toggle reads this.
+    static var isInstalled: Bool {
+        FileManager.default.fileExists(atPath: plistURL.path)
+    }
+
+    /// Whether launchd knows about the job at all. Distinct from installed: a
+    /// plist written since the last login is not loaded yet.
+    static var isLoaded: Bool {
+        run(["list", label]).status == 0
+    }
+
+    /// Both streams down one pipe: `list` answers on stdout, and every refusal
+    /// launchctl has to offer arrives on stderr, so dropping stderr would
+    /// leave a failed command reporting nothing but a number.
+    ///
+    /// One pipe rather than two, and read before waiting. Two pipes drained in
+    /// sequence still deadlock the moment the second one fills while the first
+    /// is being read to EOF — and the output here is small enough that the
+    /// interleaving does not matter.
+    @discardableResult
+    static func run(_ args: [String]) -> (status: Int32, output: String) {
+        let task = Process()
+        task.launchPath = "/bin/launchctl"
+        task.arguments = args
+        let pipe = Pipe()
+        task.standardOutput = pipe
+        task.standardError = pipe
+        guard (try? task.run()) != nil else { return (-1, "") }
+        let data = pipe.fileHandleForReading.readDataToEndOfFile()
+        task.waitUntilExit()
+        return (task.terminationStatus, String(decoding: data, as: UTF8.self))
+    }
+
+    /// Write the plist. The binary named is this bundle's own executable,
+    /// symlink-resolved: run through Homebrew's shim `executableURL` reports
+    /// `/opt/homebrew/bin/yap`, and naming that is what costs the daemon its
+    /// bundle identity and with it the menu bar icon (see
+    /// `Run.reexecInsideAppBundle`).
+    ///
+    /// Only from inside a .app, and that guard is load-bearing rather than
+    /// tidy. A `swift build` binary is replaced on every rebuild, and TCC keys
+    /// the Accessibility grant on the code it saw — so a login item naming one
+    /// launches something the grant no longer covers, and the daemon comes
+    /// back at the next login unable to see the hotkey. Worse, pointing the
+    /// item at a build directory *takes the working one away*: measured, by
+    /// running an unbundled build with a login item already installed.
+    static func install() throws {
+        guard Bundle.main.bundlePath.hasSuffix(".app"),
+            let binary = Bundle.main.executableURL?.resolvingSymlinksInPath().path
+        else { throw LaunchAgentError.notBundled }
+
+        let plist: [String: Any] = [
+            "Label": label,
+            "ProgramArguments": [binary, "run"],
+            "RunAtLoad": true,
+            // Only on failure. "Quit yap" exits 0, so quitting sticks.
+            "KeepAlive": ["SuccessfulExit": false] as [String: Any],
+            "ProcessType": "Interactive",
+            "StandardOutPath": Paths.stdoutLog.path,
+            "StandardErrorPath": Paths.stderrLog.path,
+        ]
+
+        let url = plistURL
+        try FileManager.default.createDirectory(
+            at: url.deletingLastPathComponent(),
+            withIntermediateDirectories: true
+        )
+        let data = try PropertyListSerialization.data(
+            fromPropertyList: plist,
+            format: .xml,
+            options: 0
+        )
+        try data.write(to: url, options: .atomic)
+        // launchd creates the log files itself and ignores any mode we ask
+        // for, so tighten them here.
+        Paths.restrictLogPermissions()
+    }
+
+    /// Remove the plist. No `bootout`: when the running process *is* the
+    /// launchd instance, booting the job out kills the app the user is
+    /// clicking in.
+    static func uninstall() throws {
+        guard isInstalled else { return }
+        try FileManager.default.removeItem(at: plistURL)
+    }
+
+    /// Rewrite an installed plist that no longer says what this build writes.
+    ///
+    /// The upgrade path, and the only one there is: yap 0.2 wrote
+    /// `run --skip-doctor` and pointed at whichever binary was current then.
+    /// Nothing but yap rewrites that file, so a build that changed either has
+    /// to repair it the first time it runs. Silent when there is nothing to
+    /// do, which is every launch after the first.
+    static func refreshIfStale() {
+        guard isInstalled, Bundle.main.bundlePath.hasSuffix(".app"),
+            let binary = Bundle.main.executableURL?.resolvingSymlinksInPath().path
+        else { return }
+        let current = (try? Data(contentsOf: plistURL))
+            .flatMap {
+                try? PropertyListSerialization.propertyList(from: $0, format: nil)
+                    as? [String: Any]
+            }?["ProgramArguments"] as? [String]
+        guard current != [binary, "run"] else { return }
+        do {
+            try install()
+            warn("login item updated: \(binary) run")
+        } catch {
+            warn("warning: couldn't update the login item: \(error)")
+        }
+    }
+
+    /// Restart the job launchd owns. Used after an in-place update, so the new
+    /// image comes up under launchd rather than beside it.
+    @discardableResult
+    static func kickstart() -> (status: Int32, output: String) {
+        run(["kickstart", "-k", target])
+    }
+
+    enum LaunchAgentError: LocalizedError {
+        case notBundled
+
+        var errorDescription: String? {
+            switch self {
+            case .notBundled:
+                return "launch at login needs the installed yap.app, not a build directory"
+            }
+        }
+    }
+}
diff --git a/Sources/yap/Models/ModelRegistry.swift b/Sources/yap/Models/ModelRegistry.swift
index 8e5972a..b24c253 100644
--- a/Sources/yap/Models/ModelRegistry.swift
+++ b/Sources/yap/Models/ModelRegistry.swift
@@ -22,7 +22,6 @@ enum ModelRegistry {
             version: .tdtCtc110m,
             sizeMB: 220,
             languages: ["en"],
-            supportsSessions: true,
             recommended: true
         ),
         // Kept as the accuracy option: 2.06% WER is the best of the three,
@@ -34,7 +33,6 @@ enum ModelRegistry {
             version: .v2,
             sizeMB: 465,
             languages: ["en"],
-            supportsSessions: true,
             recommended: false
         ),
         TranscriptionModel(
@@ -43,7 +41,6 @@ enum ModelRegistry {
             version: .v3,
             sizeMB: 500,
             languages: ["multi"],
-            supportsSessions: true,
             recommended: false
         )
     ]
diff --git a/Sources/yap/Models/TranscriptionModel.swift b/Sources/yap/Models/TranscriptionModel.swift
index e710ef0..551ad9e 100644
--- a/Sources/yap/Models/TranscriptionModel.swift
+++ b/Sources/yap/Models/TranscriptionModel.swift
@@ -14,23 +14,5 @@ struct TranscriptionModel {
     let version: AsrModelVersion
     let sizeMB: Int
     let languages: [String]
-    /// Whether this model can transcribe a recorded session.
-    ///
-    /// Dictation only needs text. A session needs *timed segments*, because
-    /// `TranscriptionCoordinator` merges two tracks on their start and end
-    /// times — so a model that can only return a bare string collapses each
-    /// track to one span, and the meeting reads as one block per speaker
-    /// instead of a conversation.
-    ///
-    /// Timed segments, not token timestamps: how an engine arrives at them is
-    /// its own business. Parakeet happens to build them from word timings, but
-    /// an engine emitting native sentence or chunk spans would serve sessions
-    /// just as well, and this flag should not exclude it.
-    ///
-    /// Every checkpoint in the registry today can, so this is `true`
-    /// throughout. It is here because the failure it guards is silent and
-    /// arrives after the meeting, which is the worst possible moment to learn
-    /// the model was the wrong one.
-    let supportsSessions: Bool
     let recommended: Bool
 }
diff --git a/Sources/yap/Paths.swift b/Sources/yap/Paths.swift
index efdca0d..1bc6143 100644
--- a/Sources/yap/Paths.swift
+++ b/Sources/yap/Paths.swift
@@ -40,6 +40,21 @@ enum Paths {
         return dir.appendingPathComponent("daemon.lock")
     }
 
+    /// `~/Library/Application Support/yap/updates`, where a downloaded build
+    /// is unpacked and checked before it is allowed anywhere near
+    /// /Applications. Emptied once an update lands, and again at every launch,
+    /// so an interrupted download costs nothing but the bytes.
+    static var updatesDirectory: URL {
+        let dir = FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent("Library/Application Support/yap/updates", isDirectory: true)
+        try? FileManager.default.createDirectory(
+            at: dir,
+            withIntermediateDirectories: true,
+            attributes: [.posixPermissions: 0o700]
+        )
+        return dir
+    }
+
     /// launchd creates the log files itself and does not honour a mode, so
     /// tighten them to 0600 after the agent is installed. Existing files are
     /// tightened too, which covers an agent installed by an earlier build.
diff --git a/Sources/yap/Permissions.swift b/Sources/yap/Permissions.swift
new file mode 100644
index 0000000..570446d
--- /dev/null
+++ b/Sources/yap/Permissions.swift
@@ -0,0 +1,86 @@
+import AVFoundation
+import AppKit
+import ApplicationServices
+import Foundation
+
+/// The three things macOS can withhold from yap, and the shortest route to
+/// each of them.
+///
+/// There is no report and no `yap doctor` any more: the menu bar is the
+/// onboarding surface, so what used to be a printed checklist is now a row you
+/// click. This is the state behind those rows — read live, because a grant can
+/// arrive while the daemon runs and the whole point is to notice.
+enum Permissions {
+    static var accessibilityGranted: Bool { AXIsProcessTrusted() }
+
+    static var microphone: AVAuthorizationStatus {
+        AVCaptureDevice.authorizationStatus(for: .audio)
+    }
+
+    /// Ask for the microphone. macOS shows the system prompt only while the
+    /// status is `.notDetermined`; once denied it answers immediately and the
+    /// user has to go to Settings, which is what the menu row is for.
+    static func requestMicrophone(_ completion: @escaping (Bool) -> Void) {
+        AVCaptureDevice.requestAccess(for: .audio, completionHandler: completion)
+    }
+
+    /// What macOS does with the Fn (🌐) key, or nil when it does nothing —
+    /// which is what a clean dictation hotkey needs.
+    ///
+    /// Never fatal, and never a reason to refuse a press: the tap sees Fn
+    /// whatever the system does with it afterwards, so a stock mapping
+    /// degrades dictation rather than breaking it. It is worth one menu row
+    /// because the degradation is confusing — a Fn press that also opens the
+    /// emoji picker looks like yap misbehaving.
+    static func fnKeyAction() -> String? {
+        guard let value = intDefault(domain: "com.apple.HIToolbox", key: "AppleFnUsageType")
+        else {
+            // Unset: whatever macOS ships as the default may intercept it, and
+            // we cannot tell which. Say so vaguely rather than not at all.
+            return "another action"
+        }
+        guard value != 0 else { return nil }
+        let uses = [1: "Change Input Source", 2: "Show Emoji & Symbols", 3: "Start Dictation"]
+        return uses[value] ?? "another action"
+    }
+
+    enum Pane {
+        case accessibility
+        case microphone
+        case keyboard
+
+        var url: URL {
+            switch self {
+            case .accessibility:
+                return URL(
+                    string:
+                        "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
+                )!
+            case .microphone:
+                return URL(
+                    string:
+                        "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone"
+                )!
+            case .keyboard:
+                return URL(string: "x-apple.systempreferences:com.apple.Keyboard-Settings.extension")!
+            }
+        }
+    }
+
+    /// `NSWorkspace`, not a fork of `/usr/bin/open`: we are an AppKit app now,
+    /// and spawning a process to open a URL we can open ourselves is a process
+    /// for nothing.
+    static func openSystemSettings(_ pane: Pane) {
+        NSWorkspace.shared.open(pane.url)
+    }
+
+    /// One preference read instead of a `defaults` fork. CFPreferences goes
+    /// through cfprefsd exactly as the `defaults` tool does.
+    ///
+    /// Both shapes accepted: System Settings writes an integer, but a domain
+    /// edited by hand can hold the same value as a string.
+    private static func intDefault(domain: String, key: String) -> Int? {
+        let value = CFPreferencesCopyAppValue(key as CFString, domain as CFString)
+        return value as? Int ?? (value as? String).flatMap(Int.init)
+    }
+}
diff --git a/Sources/yap/Setup.swift b/Sources/yap/Setup.swift
deleted file mode 100644
index 6f14ea9..0000000
--- a/Sources/yap/Setup.swift
+++ /dev/null
@@ -1,159 +0,0 @@
-import AVFoundation
-import ApplicationServices
-import ArgumentParser
-import Foundation
-
-/// First-run walkthrough: permissions, then the model.
-///
-/// Order matters. The model download is several hundred megabytes and a
-/// one-off ANE compile on top; making someone sit through it only to discover
-/// afterwards that Accessibility was never granted is the worst possible
-/// sequence. Permissions first, and each one exits rather than continuing
-/// half-configured.
-struct Setup: ParsableCommand {
-    static let configuration = CommandConfiguration(
-        abstract: "Walk through first-run permission setup."
-    )
-
-    func run() throws {
-        print("yap setup")
-        print("=========")
-        print()
-        print("yap needs two permissions:")
-        print("  1. Accessibility — to detect the hotkey globally and inject text at the cursor.")
-        print("  2. Microphone — to record audio while you hold the hotkey.")
-        print()
-        // TCC files the grant against the responsible process, which for a CLI
-        // binary is the terminal that launched it. Nobody will find a "yap"
-        // row in System Settings, so say so before they go looking.
-        print("Run from a terminal, these attach to your terminal app")
-        print("(Terminal/iTerm/Ghostty/etc.), not to yap itself.")
-        print()
-        print("Launched at login they do not: launchd runs the binary directly, so it")
-        print("needs its own grant. `yap install --launch-at-login` says which one.")
-        print()
-
-        try waitForAccessibility()
-        print()
-        try waitForMicrophone()
-        print()
-        try downloadDefaultModel()
-        print()
-        // Not "all set": the checks above covered this terminal, and running
-        // yap from it is the only thing they prove.
-        print("✓ ready. Run `yap` here to start the daemon.")
-
-        // Everything above answered for this process, which is almost never
-        // the process that ends up running yap.
-        switch DoctorReport.checkLaunchAgent() {
-        case .none:
-            // No agent yet, which is every fresh install. Saying nothing here
-            // is how "setup says granted" and "the next command asks for
-            // Accessibility again" ended up looking like a contradiction.
-            print()
-            print("To run yap at login: `yap install --launch-at-login`.")
-            print("launchd starts the binary itself rather than through a terminal, so")
-            print("macOS asks for Accessibility once more, this time filed under yap.")
-            print("That prompt is the grant the daemon actually uses.")
-        case .some(let agent):
-            // Installed but unhealthy. It is a different grant from the one
-            // checked above, and reporting success without saying so is how
-            // "setup says granted" coexists with "nothing runs".
-            guard case .warn(let detail) = agent.status else { break }
-            print()
-            print("! the login agent is a separate case: \(detail)")
-            if let fix = agent.remediation { print("  → \(fix)") }
-        }
-    }
-
-    /// Fetch the model up front so the first hotkey press isn't a surprise
-    /// several-hundred-MB download followed by a one-off ANE compile.
-    ///
-    /// Resolved the same way the daemon resolves it, so someone who already
-    /// picked a model in the config file doesn't get handed a different one.
-    private func downloadDefaultModel() throws {
-        let model = try Resolve.model(nil)
-        if ModelStore.isDownloaded(model) {
-            print("✓ \(model.id) already downloaded")
-            return
-        }
-
-        print("→ downloading \(model.id) (~\(model.sizeMB) MB), then compiling for the ANE...")
-        do {
-            try runBlocking { try await model.makeTranscriber().warmUp() }
-        } catch {
-            print("  ✗ download failed: \(error)")
-            throw ExitCode(1)
-        }
-    }
-
-    /// Who the tick above actually belongs to.
-    ///
-    /// The paragraph at the top has just said a terminal's grant does not
-    /// carry to the login agent, so a bare "already granted" contradicts it,
-    /// and the agent asking again a minute later reads as a bug rather than as
-    /// the thing we warned about. Deliberately not the terminal's name: the
-    /// parent process is usually the shell, while the row in System Settings
-    /// is filed under the terminal app, and guessing wrong is worse than
-    /// staying general.
-    private static var holder: String {
-        DoctorReport.grantsBelongToThisBinary
-            ? "to yap itself" : "to this terminal, not to yap itself"
-    }
-
-    private func waitForAccessibility() throws {
-        if AXIsProcessTrusted() {
-            print("✓ accessibility already granted \(Self.holder)")
-            return
-        }
-
-        print("→ opening accessibility prompt...")
-        let promptKey = kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String
-        _ = AXIsProcessTrustedWithOptions([promptKey: true] as CFDictionary)
-
-        print()
-        print("  1. Toggle your terminal on in the Accessibility list.")
-        print("  2. Re-run `yap setup` — macOS only picks up the grant on a fresh process.")
-        throw ExitCode(0)
-    }
-
-    private func waitForMicrophone() throws {
-        let status = AVCaptureDevice.authorizationStatus(for: .audio)
-        switch status {
-        case .authorized:
-            print("✓ microphone already granted \(Self.holder)")
-            return
-        case .denied, .restricted:
-            print("✗ microphone is denied — macOS won't re-prompt once denied.")
-            print("  opening Settings → Privacy & Security → Microphone...")
-            openSettings("Privacy_Microphone")
-            print("  enable your terminal, then re-run `yap setup`.")
-            throw ExitCode(1)
-        case .notDetermined:
-            print("→ requesting microphone access...")
-            let semaphore = DispatchSemaphore(value: 0)
-            var granted = false
-            AVCaptureDevice.requestAccess(for: .audio) { ok in
-                granted = ok
-                semaphore.signal()
-            }
-            semaphore.wait()
-            if granted {
-                print("  ✓ microphone granted")
-            } else {
-                print("  ✗ microphone denied")
-                throw ExitCode(1)
-            }
-        @unknown default:
-            print("? microphone in unknown state")
-        }
-    }
-
-    private func openSettings(_ pane: String) {
-        let url = "x-apple.systempreferences:com.apple.preference.security?\(pane)"
-        let task = Process()
-        task.launchPath = "/usr/bin/open"
-        task.arguments = [url]
-        try? task.run()
-    }
-}
diff --git a/Sources/yap/Transcription/TranscriptionCoordinator.swift b/Sources/yap/Transcription/TranscriptionCoordinator.swift
index 5c4cb0e..744c955 100644
--- a/Sources/yap/Transcription/TranscriptionCoordinator.swift
+++ b/Sources/yap/Transcription/TranscriptionCoordinator.swift
@@ -10,10 +10,10 @@ import Foundation
 ///
 /// The daemon hands us the transcriber it already holds for dictation, so a
 /// meeting transcribes on the same loaded model the hotkey uses — no second
-/// load, no second copy in memory. A coordinator handed nothing (`yap record`
-/// as a one-shot) resolves and loads its own, and releases it when the queue
-/// drains; an injected one is never released, because the whole point of the
-/// dictation daemon is that the next key press is instant.
+/// load, no second copy in memory. A coordinator handed nothing resolves and
+/// loads its own, and releases it when the queue drains; an injected one is
+/// never released, because the whole point of the dictation daemon is that
+/// the next key press is instant.
 actor TranscriptionCoordinator {
     private var queue: [URL] = []
     private var drainTask: Task<Void, Never>?
@@ -43,7 +43,7 @@ actor TranscriptionCoordinator {
     }
 
     /// Called with the session directory after transcript.json/.md are written.
-    /// Unset (the one-shot `yap record` case), a plain notification fires instead.
+    /// Unset, a plain notification fires instead.
     func setTranscriptReadyHandler(_ handler: @escaping @Sendable (URL) -> Void) {
         transcriptReadyHandler = handler
     }
@@ -55,64 +55,13 @@ actor TranscriptionCoordinator {
             runHook(for: sessionDir)
             return
         }
-        // Only decline on a model we can positively identify as unable. An
-        // unrecognised id is a different fault, and the existing transcribe
-        // path reports it far more accurately than this would.
-        if let model = sessionModel(), !model.supportsSessions {
-            refuseSession(sessionDir, model: model)
-            return
-        }
         queue.append(sessionDir)
         drainIfIdle()
     }
 
-    /// The model this session would actually transcribe on.
-    ///
-    /// The daemon's resident transcriber wins over config: it is the thing
-    /// that will do the work, and config can be edited after it was loaded.
-    /// Only a coordinator that owns nothing yet has to ask config.
-    private func sessionModel() -> TranscriptionModel? {
-        if let transcriber { return ModelRegistry.find(transcriber.modelID) }
-        return Self.resolveModel()
-    }
-
-    /// Leave the recording alone rather than transcribe it wrongly.
-    ///
-    /// Not a throw: a model that cannot emit timings fails every track, so
-    /// `allTracksFailed` would fire, no transcript.json would be written, and
-    /// `resumePending` would requeue the session at every launch forever.
-    /// Declining up front keeps the audio and the reason on disk instead.
-    ///
-    /// A session under the configured recordings root does get picked up by
-    /// `resumePending` on a later launch with a capable model. One written
-    /// elsewhere by `yap record --out` does not — nothing rescans that path,
-    /// and there is no command to transcribe an existing folder. So the
-    /// message promises the audio and not the transcript.
-    ///
-    /// Deliberately no `on_stop`. The hook means "this session is finished",
-    /// and this one is not: firing now would hand the hook a folder with no
-    /// transcript, and fire a second time when a later launch on a capable
-    /// model transcribes it. Disabled transcription is the case where firing
-    /// is right — a recorder with no transcriber has nothing else to announce
-    /// — and it accepts the second fire if the setting is turned back on.
-    private func refuseSession(_ dir: URL, model: TranscriptionModel) {
-        let reason = "\(model.id) cannot produce the timed segments a session needs"
-        log(dir, "not transcribed: \(reason)")
-        // Also on stderr: `yap record` has just printed "transcribing...", and
-        // exiting quietly after that reads as success. The recording itself did
-        // succeed, so this is not a failure exit — but the terminal has to say
-        // that no transcript was written, and where the audio went.
-        let notice = "not transcribed: \(reason)\n  the recording is kept at \(dir.path)"
-        warn(notice)
-        notifyUser(
-            title: "yap — session not transcribed",
-            body: "\(model.id) cannot transcribe recordings — see transcribe.log"
-        )
-    }
-
-    /// Queue a session and return only once the queue is empty. `yap record`
-    /// has nothing left to do but wait for its own transcript, and must not
-    /// exit before the file exists.
+    /// Queue a session and return only once the queue is empty, for a caller
+    /// that owns the coordinator and has nothing left to do but wait for the
+    /// transcript.
     func transcribeNow(_ sessionDir: URL) async {
         enqueue(sessionDir)
         await waitUntilDrained()
@@ -128,10 +77,6 @@ actor TranscriptionCoordinator {
     /// oldest-first is a name sort.
     func resumePending(root: URL) {
         guard Config.transcriptionEnabled() else { return }
-        // A backlog waits for a model that can transcribe it rather than being
-        // burned through on one that cannot. Nothing is lost — the sessions
-        // stay pending, and a later launch on a capable model picks them up.
-        if let model = sessionModel(), !model.supportsSessions { return }
         guard let entries = try? FileManager.default.contentsOfDirectory(
             at: root, includingPropertiesForKeys: nil
         ) else { return }
@@ -268,13 +213,10 @@ actor TranscriptionCoordinator {
     }
 
     /// Sessions transcribe on the model dictation uses. One model id in
-    /// config, one model on disk, one model in memory.
+    /// config, one model on disk, one model in memory — so this is the same
+    /// resolution the daemon booted with, warning and all.
     private static func resolveModel() -> TranscriptionModel? {
-        if let id = Config.dictationModel() {
-            if let model = ModelRegistry.find(id) { return model }
-            warn("warning: unknown model \"\(id)\" — using the recommended one")
-        }
-        return ModelRegistry.recommended()
+        try? Resolve.model()
     }
 
     /// Fires the configured on_stop shell command with the session directory
diff --git a/Sources/yap/UI/HotkeyRecorder.swift b/Sources/yap/UI/HotkeyRecorder.swift
new file mode 100644
index 0000000..113e4a6
--- /dev/null
+++ b/Sources/yap/UI/HotkeyRecorder.swift
@@ -0,0 +1,225 @@
+import AppKit
+import SwiftUI
+
+extension Notification.Name {
+    /// Posted with `["active": Bool]` while the recorder is listening. The
+    /// daemon suspends the hotkey tap for the duration, so recording ⌘⇧Space
+    /// does not also start dictating.
+    static let yapHotkeyRecording = Notification.Name("yap.hotkeyRecording")
+}
+
+/// The "click here and press a key" field, as every app with a shortcut has.
+///
+/// AppKit has no such control, and SwiftUI has none either — `KeyboardShortcut`
+/// is for menu items, not for capturing one. So this is an NSView that takes
+/// first responder and reads the events itself.
+struct HotkeyRecorder: NSViewRepresentable {
+    @Binding var value: String
+
+    func makeNSView(context: Context) -> HotkeyRecorderView {
+        let view = HotkeyRecorderView()
+        view.onChange = { value = $0 }
+        view.binding = HotkeyBinding(parsing: value)
+        return view
+    }
+
+    func updateNSView(_ view: HotkeyRecorderView, context: Context) {
+        view.onChange = { value = $0 }
+        // Only when it is not mid-capture: overwriting the field while someone
+        // is holding a chord down would throw their press away.
+        guard !view.isRecording else { return }
+        view.binding = HotkeyBinding(parsing: value)
+    }
+}
+
+final class HotkeyRecorderView: NSView {
+    var onChange: ((String) -> Void)?
+
+    var binding: HotkeyBinding? {
+        didSet { needsDisplay = true }
+    }
+
+    private(set) var isRecording = false {
+        didSet {
+            needsDisplay = true
+            NotificationCenter.default.post(
+                name: .yapHotkeyRecording, object: nil, userInfo: ["active": isRecording])
+        }
+    }
+
+    /// A modifier held with nothing else yet. Committed on release, so holding
+    /// right ⌥ and letting go binds right ⌥, while holding ⌘ and pressing
+    /// Space binds the chord.
+    private var heldModifier: CGEventFlags?
+    /// Set once any key goes down during a capture, so releasing the modifier
+    /// afterwards does not also commit it on its own.
+    private var sawKey = false
+    /// Shown instead of the binding for a moment when a candidate is refused.
+    private var complaint: String?
+    private var complaintClear: DispatchWorkItem?
+
+    override var acceptsFirstResponder: Bool { true }
+    override var isFlipped: Bool { true }
+    override var intrinsicContentSize: NSSize { NSSize(width: 150, height: 24) }
+
+    // MARK: - drawing
+
+    override func draw(_ dirtyRect: NSRect) {
+        let field = bounds.insetBy(dx: 0.5, dy: 0.5)
+        let path = NSBezierPath(roundedRect: field, xRadius: 6, yRadius: 6)
+        (isRecording ? NSColor.controlAccentColor.withAlphaComponent(0.12)
+            : NSColor.textBackgroundColor).setFill()
+        path.fill()
+        (isRecording ? NSColor.controlAccentColor : NSColor.separatorColor).setStroke()
+        path.lineWidth = isRecording ? 2 : 1
+        path.stroke()
+
+        let text = complaint ?? (isRecording ? "Press keys…" : (binding?.displayName ?? "—"))
+        let colour: NSColor =
+            complaint != nil
+            ? .systemRed : (isRecording ? .secondaryLabelColor : .labelColor)
+        let attributes: [NSAttributedString.Key: Any] = [
+            .font: NSFont.systemFont(ofSize: 12),
+            .foregroundColor: colour,
+        ]
+        let size = (text as NSString).size(withAttributes: attributes)
+        (text as NSString).draw(
+            at: NSPoint(
+                x: bounds.midX - size.width / 2,
+                y: bounds.midY - size.height / 2),
+            withAttributes: attributes)
+    }
+
+    // MARK: - capture
+
+    override func mouseDown(with event: NSEvent) {
+        guard !isRecording else { return }
+        window?.makeFirstResponder(self)
+        beginRecording()
+    }
+
+    private func beginRecording() {
+        heldModifier = nil
+        sawKey = false
+        complaint = nil
+        isRecording = true
+    }
+
+    private func endRecording() {
+        guard isRecording else { return }
+        heldModifier = nil
+        sawKey = false
+        isRecording = false
+    }
+
+    /// ⌘-chords never reach `keyDown`: AppKit offers them to the menu first,
+    /// and ⌘W would close the Settings window instead of being recorded.
+    override func performKeyEquivalent(with event: NSEvent) -> Bool {
+        guard isRecording else { return false }
+        keyDown(with: event)
+        return true
+    }
+
+    override func keyDown(with event: NSEvent) {
+        guard isRecording else {
+            super.keyDown(with: event)
+            return
+        }
+        sawKey = true
+        // Escape alone cancels. With a modifier it is a legitimate binding,
+        // so only the bare press backs out.
+        let modifiers = Self.flags(from: event.modifierFlags)
+            .intersection(HotkeyBinding.relevantFlags(for: event.keyCode))
+        if event.keyCode == 53, modifiers.isEmpty {
+            endRecording()
+            return
+        }
+        let candidate = HotkeyBinding.chord(modifiers: modifiers, keyCode: event.keyCode)
+        if let reason = HotkeyBinding.validate(candidate) {
+            flash(reason)
+            return
+        }
+        commit(candidate)
+    }
+
+    override func flagsChanged(with event: NSEvent) {
+        guard isRecording else {
+            super.flagsChanged(with: event)
+            return
+        }
+        // The device-specific bits, which `NSEvent.modifierFlags` does not
+        // carry: only the CGEvent behind it can tell left Shift from right.
+        let raw = event.cgEvent?.flags ?? []
+        let held = HotkeyBinding.modifierMasks.values.first { raw.contains($0) && $0.rawValue != 0 }
+
+        if let held, heldModifier == nil, !sawKey {
+            heldModifier = held
+            complaint = nil
+            needsDisplay = true
+            return
+        }
+        // Everything let go, and no key was pressed in between: the user was
+        // binding the modifier itself.
+        guard let candidate = heldModifier,
+            raw.isDisjoint(with: HotkeyBinding.relevantFlags)
+        else { return }
+        heldModifier = nil
+        guard !sawKey else { return }
+        commit(.modifier(candidate))
+    }
+
+    private func commit(_ binding: HotkeyBinding) {
+        self.binding = binding
+        endRecording()
+        onChange?(binding.serialized)
+    }
+
+    private func flash(_ reason: String) {
+        complaint = reason
+        needsDisplay = true
+        complaintClear?.cancel()
+        let item = DispatchWorkItem { [weak self] in
+            self?.complaint = nil
+            self?.needsDisplay = true
+        }
+        complaintClear = item
+        DispatchQueue.main.asyncAfter(deadline: .now() + 1.2, execute: item)
+    }
+
+    /// Nothing is written on the way out: losing focus is not a decision.
+    override func resignFirstResponder() -> Bool {
+        endRecording()
+        return true
+    }
+
+    override func viewDidMoveToWindow() {
+        super.viewDidMoveToWindow()
+        NotificationCenter.default.addObserver(
+            self, selector: #selector(windowResigned),
+            name: NSWindow.didResignKeyNotification, object: window)
+    }
+
+    @objc private func windowResigned() {
+        endRecording()
+    }
+
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+        // A view torn down mid-capture would otherwise leave the daemon's tap
+        // suspended for the rest of the session.
+        if isRecording {
+            NotificationCenter.default.post(
+                name: .yapHotkeyRecording, object: nil, userInfo: ["active": false])
+        }
+    }
+
+    private static func flags(from modifiers: NSEvent.ModifierFlags) -> CGEventFlags {
+        var result: CGEventFlags = []
+        if modifiers.contains(.command) { result.insert(.maskCommand) }
+        if modifiers.contains(.shift) { result.insert(.maskShift) }
+        if modifiers.contains(.control) { result.insert(.maskControl) }
+        if modifiers.contains(.option) { result.insert(.maskAlternate) }
+        if modifiers.contains(.function) { result.insert(.maskSecondaryFn) }
+        return result
+    }
+}
diff --git a/Sources/yap/UI/MenuBarController.swift b/Sources/yap/UI/MenuBarController.swift
index 070c4d5..0efcf2a 100644
--- a/Sources/yap/UI/MenuBarController.swift
+++ b/Sources/yap/UI/MenuBarController.swift
@@ -9,8 +9,13 @@ import SwiftUI
 /// transient and drives the state line; a recording session is long-lived and
 /// owns the toggle item plus its elapsed counter. They are tracked separately
 /// because they overlap: you can dictate a note while a meeting records.
+///
+/// It is also where onboarding lives. There is no `yap setup` any more, so a
+/// missing grant is a row you click rather than a line printed into a log
+/// nobody reads. Those rows are hidden in the ordinary case, which is every
+/// launch after the first.
 @MainActor
-final class MenuBarController {
+final class MenuBarController: NSObject, NSMenuDelegate {
     /// Transient dictation state, resolved against the session state by
     /// `refresh()`. Dictation wins the state line while it lasts — it is the
     /// thing the user is doing right now — and the session line comes back
@@ -21,6 +26,25 @@ final class MenuBarController {
         case transcribing
     }
 
+    /// Where the model is. The status item now exists before the model does,
+    /// so this is the difference between "yap is thinking" and "yap is broken"
+    /// during the seconds — or, on a cold cache, minutes — before the first
+    /// press can work.
+    private enum Model {
+        case loading(String)
+        case failed
+        case ready
+    }
+
+    /// What macOS is still withholding. An option set because they are
+    /// independent and any combination can be true at once.
+    struct SetupNeeds: OptionSet {
+        let rawValue: Int
+        static let accessibility = SetupNeeds(rawValue: 1 << 0)
+        static let microphone = SetupNeeds(rawValue: 1 << 1)
+        static let fnMapping = SetupNeeds(rawValue: 1 << 2)
+    }
+
     /// Name of the push-to-talk key, as the state line spells it. Live: the
     /// config file can change the key while the daemon runs.
     private var hotkeyName: String
@@ -31,15 +55,20 @@ final class MenuBarController {
     private let statusItem: NSStatusItem
     private let toggleItem: NSMenuItem
     private let copyItem: NSMenuItem
+    private let accessibilityItem: NSMenuItem
+    private let microphoneItem: NSMenuItem
+    private let fnItem: NSMenuItem
+    private let retryItem: NSMenuItem
+    private let updateItem: NSMenuItem
     /// Backs the header card. `refresh()` stays the single point of truth and
     /// pushes finished strings into it; SwiftUI does the redraw, so nothing
     /// here reaches into the view.
     private let state = MenuState()
 
     /// Fixed, so the menu keeps one width as the state line changes length.
-    /// Wide enough for the longest of them ("idle · hold rightCommand to
-    /// dictate") and for a model id.
-    private static let headerWidth: CGFloat = 260
+    /// Wide enough for the longest of them and for the Fn row, which spells
+    /// out whatever macOS has the key doing instead.
+    private static let headerWidth: CGFloat = 300
 
     /// The last thing dictation produced. In process memory, one at a time,
     /// never written to disk or log by this feature — the log deliberately
@@ -51,6 +80,8 @@ final class MenuBarController {
     private var lastTranscript: String?
 
     private var dictation: Dictation = .idle
+    private var model: Model = .ready
+    private var needs: SetupNeeds = []
     private var recordingSince: Date?
     private var ticker: Timer?
 
@@ -60,6 +91,15 @@ final class MenuBarController {
     var onStartRecording: (() -> Void)?
     /// Clicked "Stop recording".
     var onStopRecording: (() -> Void)?
+    var onGrantAccessibility: (() -> Void)?
+    var onGrantMicrophone: (() -> Void)?
+    var onOpenKeyboardSettings: (() -> Void)?
+    var onRetryModel: (() -> Void)?
+    var onInstallUpdate: (() -> Void)?
+    /// The menu is about to draw. The daemon re-reads the permission state
+    /// here, so the rows are right at the moment someone looks at them
+    /// without anything polling in between.
+    var onMenuWillOpen: (() -> Void)?
 
     init(modelID: String, hotkeyName: String, tapToToggle: Bool) {
         self.hotkeyName = hotkeyName
@@ -90,6 +130,27 @@ final class MenuBarController {
 
         menu.addItem(.separator())
 
+        // The onboarding rows, directly under the card so they are the first
+        // thing read. All hidden by default — no separator of their own,
+        // because an empty group would leave two rules stacked on every launch
+        // after the first.
+        accessibilityItem = Self.item(
+            "Grant Accessibility…", symbol: "hand.raised",
+            action: #selector(grantAccessibilityClicked))
+        microphoneItem = Self.item(
+            "Grant Microphone…", symbol: "mic.slash",
+            action: #selector(grantMicrophoneClicked))
+        fnItem = Self.item(
+            "Open Keyboard Settings…", symbol: "keyboard",
+            action: #selector(openKeyboardSettingsClicked))
+        retryItem = Self.item(
+            "Retry Model Download", symbol: "arrow.clockwise",
+            action: #selector(retryModelClicked))
+        for item in [accessibilityItem, microphoneItem, fnItem, retryItem] {
+            item.isHidden = true
+            menu.addItem(item)
+        }
+
         toggleItem = NSMenuItem(
             title: "Start Recording",
             action: #selector(toggleClicked),
@@ -112,6 +173,14 @@ final class MenuBarController {
 
         menu.addItem(.separator())
 
+        // Above Settings, because it is the more urgent of the two and it is
+        // only ever there when there is something to do.
+        updateItem = Self.item(
+            "Update", symbol: "arrow.down.circle.fill",
+            action: #selector(installUpdateClicked))
+        updateItem.isHidden = true
+        menu.addItem(updateItem)
+
         let settings = NSMenuItem(
             title: "Settings…",
             action: #selector(settingsClicked),
@@ -130,10 +199,16 @@ final class MenuBarController {
         )
         menu.addItem(quit)
 
-        for item in [toggleItem, copyItem, settings, quit] {
+        super.init()
+
+        for item in [
+            toggleItem, copyItem, settings, quit,
+            accessibilityItem, microphoneItem, fnItem, retryItem, updateItem,
+        ] {
             item.target = self
         }
 
+        menu.delegate = self
         statusItem.menu = menu
 
         // Template image, never tinted. Colouring the icon while recording put
@@ -143,6 +218,12 @@ final class MenuBarController {
         statusItem.button?.imagePosition = .imageLeft
     }
 
+    private static func item(_ title: String, symbol: String, action: Selector) -> NSMenuItem {
+        let item = NSMenuItem(title: title, action: action, keyEquivalent: "")
+        item.image = NSImage(systemSymbolName: symbol, accessibilityDescription: nil)
+        return item
+    }
+
     /// The push-to-talk key is held and the mic is hot.
     func setDictating(_ active: Bool) {
         dictation = active ? .listening : .idle
@@ -161,6 +242,51 @@ final class MenuBarController {
         refresh()
     }
 
+    /// The model is on its way. `downloading` distinguishes a first run — which
+    /// is a several-hundred-megabyte wait — from a warm cache, which is a
+    /// third of a second.
+    func setModelLoading(downloading: Bool, sizeMB: Int) {
+        model = .loading(downloading ? "downloading model (~\(sizeMB) MB)…" : "loading model…")
+        refresh()
+    }
+
+    /// Warm-up threw. Deliberately not fatal: the rest of the app still works,
+    /// and the row below offers the only thing that can help.
+    func setModelFailed() {
+        model = .failed
+        refresh()
+    }
+
+    func setModelReady() {
+        model = .ready
+        refresh()
+    }
+
+    /// A staged update, or nil for none. `enabled` is false while a recording
+    /// or a press is live: restarting then would cost audio the user is
+    /// relying on, and a greyed row says so better than a refusal would.
+    func setUpdate(version: String?, enabled: Bool) {
+        updateItem.isHidden = version == nil
+        updateItem.isEnabled = enabled
+        if let version {
+            updateItem.title = "Update to \(version) · Restart"
+        }
+        // The only time the icon says anything on its own. A dot, not a
+        // colour: a tinted mark next to the system's recording indicator
+        // already read as an error once.
+        statusItem.button?.image = StatusIcon.image(size: 16, badged: version != nil)
+    }
+
+    /// What is still missing, and what macOS has Fn doing instead when that is
+    /// the thing missing.
+    func setSetupNeeds(_ needs: SetupNeeds, fnAction: String?) {
+        self.needs = needs
+        if let fnAction {
+            fnItem.title = "Fn key is set to \(fnAction) — Open Keyboard Settings…"
+        }
+        refresh()
+    }
+
     /// The config file changed the push-to-talk key.
     func setHotkeyName(_ name: String) {
         guard name != hotkeyName else { return }
@@ -204,8 +330,13 @@ final class MenuBarController {
         refresh()
     }
 
-    /// Single point of truth for the toggle title and the header's state line.
-    /// Called on every state change and once a second while a session records.
+    func menuWillOpen(_ menu: NSMenu) {
+        onMenuWillOpen?()
+    }
+
+    /// Single point of truth for the toggle title, the onboarding rows and the
+    /// header's state line. Called on every state change and once a second
+    /// while a session records.
     private func refresh() {
         if let recordingSince {
             let elapsed = formatElapsed(Date().timeIntervalSince(recordingSince))
@@ -218,6 +349,18 @@ final class MenuBarController {
                 systemSymbolName: "record.circle", accessibilityDescription: nil)
         }
 
+        accessibilityItem.isHidden = !needs.contains(.accessibility)
+        microphoneItem.isHidden = !needs.contains(.microphone)
+        fnItem.isHidden = !needs.contains(.fnMapping)
+        if case .failed = model {
+            retryItem.isHidden = false
+        } else {
+            retryItem.isHidden = true
+        }
+
+        // Precedence, most immediate first: what you are doing now, then what
+        // is running, then what is stopping yap working at all, then the model,
+        // then the resting line.
         switch dictation {
         case .listening:
             state.line = "● listening"
@@ -227,8 +370,14 @@ final class MenuBarController {
             if let recordingSince {
                 let elapsed = formatElapsed(Date().timeIntervalSince(recordingSince))
                 state.line = "● recording · \(elapsed)"
+            } else if !needs.isEmpty {
+                state.line = "needs setup"
             } else {
-                state.line = Self.idleTitle(hotkeyName, tapToToggle)
+                switch model {
+                case .loading(let line): state.line = line
+                case .failed: state.line = "model download failed"
+                case .ready: state.line = Self.idleTitle(hotkeyName, tapToToggle)
+                }
             }
         }
     }
@@ -245,6 +394,12 @@ final class MenuBarController {
         }
     }
 
+    @objc private func grantAccessibilityClicked() { onGrantAccessibility?() }
+    @objc private func grantMicrophoneClicked() { onGrantMicrophone?() }
+    @objc private func openKeyboardSettingsClicked() { onOpenKeyboardSettings?() }
+    @objc private func retryModelClicked() { onRetryModel?() }
+    @objc private func installUpdateClicked() { onInstallUpdate?() }
+
     /// Copies the last transcript, for the press that landed somewhere wrong
     /// or on a clipboard that has since moved on.
     @objc private func copyTranscriptClicked() {
diff --git a/Sources/yap/UI/PromptPanel.swift b/Sources/yap/UI/PromptPanel.swift
index 27fdaf2..ffd20c8 100644
--- a/Sources/yap/UI/PromptPanel.swift
+++ b/Sources/yap/UI/PromptPanel.swift
@@ -39,11 +39,15 @@ func showToast(
     button: String,
     secondaryButton: String? = nil,
     onSecondary: (@MainActor () -> Void)? = nil,
+    destructiveButton: String? = nil,
+    onDestructive: (@MainActor () -> Void)? = nil,
     onAccept: @escaping @MainActor () -> Void
 ) {
     PromptPanel.presentToast(
         title: title, body: body, button: button,
-        secondaryButton: secondaryButton, onSecondary: onSecondary, onAccept: onAccept
+        secondaryButton: secondaryButton, onSecondary: onSecondary,
+        destructiveButton: destructiveButton, onDestructive: onDestructive,
+        onAccept: onAccept
     )
 }
 
@@ -89,6 +93,7 @@ final class PromptPanel: NSPanel {
     private let onAccept: @MainActor () -> Void
     private let onDismiss: @MainActor () -> Void
     private let onSecondary: (@MainActor () -> Void)?
+    private let onDestructive: (@MainActor () -> Void)?
     private let onNameSubmit: (@MainActor (String) -> Void)?
     private var nameField: NSTextField?
     private var autoDismiss: Timer?
@@ -109,6 +114,7 @@ final class PromptPanel: NSPanel {
         let panel = PromptPanel(
             heading: title, body: body, button: button,
             secondaryButton: secondaryButton, onSecondary: onSecondary,
+            destructiveButton: nil, onDestructive: nil,
             namePrefill: nil, onNameSubmit: nil,
             onDismiss: onDismiss, onAccept: onAccept, toast: false
         )
@@ -126,6 +132,7 @@ final class PromptPanel: NSPanel {
         let panel = PromptPanel(
             heading: title, body: nil, button: "Save",
             secondaryButton: nil, onSecondary: nil,
+            destructiveButton: nil, onDestructive: nil,
             namePrefill: prefill, onNameSubmit: onSubmit,
             onDismiss: {}, onAccept: {}, toast: false
         )
@@ -145,6 +152,8 @@ final class PromptPanel: NSPanel {
         button: String,
         secondaryButton: String?,
         onSecondary: (@MainActor () -> Void)?,
+        destructiveButton: String?,
+        onDestructive: (@MainActor () -> Void)?,
         onAccept: @escaping @MainActor () -> Void
     ) {
         // A live prompt is a question; never cover it with an announcement.
@@ -157,6 +166,7 @@ final class PromptPanel: NSPanel {
         let panel = PromptPanel(
             heading: title, body: body, button: button,
             secondaryButton: secondaryButton, onSecondary: onSecondary,
+            destructiveButton: destructiveButton, onDestructive: onDestructive,
             namePrefill: nil, onNameSubmit: nil,
             onDismiss: {}, onAccept: onAccept, toast: true
         )
@@ -171,6 +181,8 @@ final class PromptPanel: NSPanel {
         button: String,
         secondaryButton: String?,
         onSecondary: (@MainActor () -> Void)?,
+        destructiveButton: String?,
+        onDestructive: (@MainActor () -> Void)?,
         namePrefill: String?,
         onNameSubmit: (@MainActor (String) -> Void)?,
         onDismiss: @escaping @MainActor () -> Void,
@@ -180,6 +192,7 @@ final class PromptPanel: NSPanel {
         self.onAccept = onAccept
         self.onDismiss = onDismiss
         self.onSecondary = onSecondary
+        self.onDestructive = onDestructive
         self.onNameSubmit = onNameSubmit
         self.dismissAfter = toast ? Self.toastDismissAfter : Self.autoDismissAfter
         super.init(
@@ -220,7 +233,8 @@ final class PromptPanel: NSPanel {
         }
         let content = contentStack(
             heading: heading, body: body, button: button,
-            secondaryButton: secondaryButton, toast: toast
+            secondaryButton: secondaryButton, destructiveButton: destructiveButton,
+            toast: toast
         )
         let background = PillView()
         background.material = .hudWindow
@@ -249,6 +263,7 @@ final class PromptPanel: NSPanel {
         body: String?,
         button: String,
         secondaryButton: String?,
+        destructiveButton: String?,
         toast: Bool
     ) -> NSStackView {
         var textViews: [NSView] = [
@@ -286,6 +301,18 @@ final class PromptPanel: NSPanel {
                     action: #selector(dismissClicked)
                 ))
         }
+        // Left of the other two, and the only red thing in the pill: it is
+        // the one button here that cannot be undone by clicking again.
+        if let destructiveButton {
+            views.append(
+                CapsuleButton(
+                    title: destructiveButton,
+                    fill: NSColor.labelColor.withAlphaComponent(0.10),
+                    textColor: .systemRed,
+                    target: self,
+                    action: #selector(destructiveClicked)
+                ))
+        }
         if let secondaryButton {
             views.append(
                 CapsuleButton(
@@ -421,6 +448,13 @@ final class PromptPanel: NSPanel {
         accept()
     }
 
+    @objc private func destructiveClicked() {
+        guard let destructive = onDestructive else { return }
+        fadeOut {
+            destructive()
+        }
+    }
+
     @objc private func secondaryClicked() {
         guard let secondary = onSecondary else { return }
         // Wait until the toast has closed before replacing it with the field.
diff --git a/Sources/yap/UI/RecordingOverlay.swift b/Sources/yap/UI/RecordingOverlay.swift
index 708014a..c6ee978 100644
--- a/Sources/yap/UI/RecordingOverlay.swift
+++ b/Sources/yap/UI/RecordingOverlay.swift
@@ -14,6 +14,14 @@ final class RecordingOverlay {
     private var window: NSPanel?
     private let model = OverlayModel()
 
+    /// The panel and its hosting view are built now rather than on the first
+    /// press. It is a few milliseconds of NSPanel and NSHostingView setup, and
+    /// the first press is the one place in yap where milliseconds are visible.
+    /// It stays ordered out until `show`, so nothing is on screen.
+    init() {
+        ensureWindow()
+    }
+
     func show(_ state: State) {
         ensureWindow()
         if state == .recording {
diff --git a/Sources/yap/UI/SettingsModel.swift b/Sources/yap/UI/SettingsModel.swift
index e9fcb5a..f4209a5 100644
--- a/Sources/yap/UI/SettingsModel.swift
+++ b/Sources/yap/UI/SettingsModel.swift
@@ -23,6 +23,18 @@ final class SettingsModel: ObservableObject {
         let installed: Bool
     }
 
+    /// The login item, which is a file rather than a config key — so unlike
+    /// every other control here, this one can fail. It reverts on failure
+    /// rather than showing a state the disk does not agree with.
+    @Published var launchAtLogin: Bool { didSet { applyLaunchAtLogin() } }
+    @Published var updatesAutomatic: Bool {
+        didSet { writeSection("updates", "automatic", updatesAutomatic) }
+    }
+    /// Live: the updater pushes every state change here while the window is
+    /// open, so "Check Now" reads as something happening.
+    @Published var updateStatus: String
+    let version = Yap.configuration.version ?? "unknown"
+
     @Published var hotkey: String { didSet { writeDictation("hotkey", hotkey) } }
     @Published var tapToToggle: Bool { didSet { writeDictation("tap_to_toggle", tapToToggle) } }
     @Published var overlay: Bool { didSet { writeDictation("overlay", overlay) } }
@@ -53,10 +65,17 @@ final class SettingsModel: ObservableObject {
     /// Suppresses the write-through while `init` fills the properties in.
     private var loading = true
     private var onStopWrite: Task<Void, Never>?
+    /// Set while `applyLaunchAtLogin` puts the toggle back after a failure,
+    /// so the reassignment does not re-enter the setter.
+    private var applyingLaunchAtLogin = false
+    private var updateObserver: UUID?
 
     init() {
-        hotkey = HotkeyMonitor.Key(name: Config.hotkey() ?? "")?.rawValue
-            ?? HotkeyMonitor.Key.fn.rawValue
+        launchAtLogin = LaunchAgent.isInstalled
+        updatesAutomatic = Config.updatesAutomatic()
+        updateStatus = Updater.shared.state.description
+        hotkey = HotkeyBinding(parsing: Config.hotkey() ?? "")?.serialized
+            ?? HotkeyBinding.fn.serialized
         tapToToggle = Config.tapToToggle()
         overlay = Config.overlayEnabled()
         newlineAfterRelease = Config.newlineAfterRelease()
@@ -71,6 +90,16 @@ final class SettingsModel: ObservableObject {
         meetingAutoRecord = Config.meetingAutoRecord()
         excludedApps = Config.meetingExcludedApps().map(Self.resolve)
         loading = false
+        updateObserver = Updater.shared.observe { [weak self] state in
+            self?.updateStatus = state.description
+        }
+    }
+
+    deinit {
+        // The window builds a fresh model on every open, so an unremoved
+        // observer would accumulate one dead closure per visit.
+        guard let updateObserver else { return }
+        MainActor.assumeIsolated { Updater.shared.unobserve(updateObserver) }
     }
 
     // MARK: actions
@@ -117,16 +146,43 @@ final class SettingsModel: ObservableObject {
         NSWorkspace.shared.open(Config.path)
     }
 
-    static func label(for key: HotkeyMonitor.Key) -> String {
-        switch key {
-        case .fn: return "Fn (Globe)"
-        case .rightOption: return "Right Option ⌥"
-        case .rightCommand: return "Right Command ⌘"
-        case .rightControl: return "Right Control ⌃"
-        case .rightShift: return "Right Shift ⇧"
+    func checkForUpdates() {
+        Updater.shared.checkNow()
+    }
+
+    /// Reveals the log rather than opening it: these are append-only files a
+    /// daemon writes to for weeks, and Console or a tail is a better reader
+    /// than whatever owns .log. Creates them first — run in the foreground
+    /// with no login item, neither file exists and Finder would open on
+    /// nothing.
+    func showLogs() {
+        Paths.restrictLogPermissions()
+        NSWorkspace.shared.activateFileViewerSelecting([Paths.stderrLog])
+    }
+
+    private func applyLaunchAtLogin() {
+        guard !loading, !applyingLaunchAtLogin else { return }
+        do {
+            if launchAtLogin {
+                try LaunchAgent.install()
+            } else {
+                try LaunchAgent.uninstall()
+            }
+        } catch {
+            warn("couldn't \(launchAtLogin ? "install" : "remove") the login item: \(error)")
+            applyingLaunchAtLogin = true
+            launchAtLogin = !launchAtLogin
+            applyingLaunchAtLogin = false
         }
     }
 
+    /// The binding as a person reads it, for the recorder field. Falls back to
+    /// the raw string so a hand-edited config that does not parse still shows
+    /// what it says rather than a lie.
+    var hotkeyDisplay: String {
+        HotkeyBinding(parsing: hotkey)?.displayName ?? hotkey
+    }
+
     // MARK: writing
 
     private func write(_ key: String, _ value: Any?) {
diff --git a/Sources/yap/UI/SettingsPanes.swift b/Sources/yap/UI/SettingsPanes.swift
index 98739b7..78ffc5b 100644
--- a/Sources/yap/UI/SettingsPanes.swift
+++ b/Sources/yap/UI/SettingsPanes.swift
@@ -3,21 +3,60 @@ import SwiftUI
 
 // MARK: - Panes
 
+struct GeneralPane: View {
+    @ObservedObject var model: SettingsModel
+
+    var body: some View {
+        Form {
+            Section {
+                Toggle("Launch at login", isOn: $model.launchAtLogin)
+            } footer: {
+                Text("Starts yap automatically at your next login.")
+                    .font(.system(size: 11))
+                    .foregroundStyle(.secondary)
+            }
+            Section("Updates") {
+                Toggle("Check for updates automatically", isOn: $model.updatesAutomatic)
+                LabeledContent("Version") { Text(model.version) }
+                HStack(spacing: 8) {
+                    Text(model.updateStatus)
+                        .foregroundStyle(.secondary)
+                        .lineLimit(1)
+                        .truncationMode(.tail)
+                    Spacer(minLength: 8)
+                    Button("Check Now") { model.checkForUpdates() }
+                }
+            }
+            Section {
+                Button("Show Logs in Finder") { model.showLogs() }
+            }
+        }
+        .formStyle(.grouped)
+    }
+}
+
 struct DictationPane: View {
     @ObservedObject var model: SettingsModel
 
     var body: some View {
         Form {
             Section {
-                Picker("Hotkey", selection: $model.hotkey) {
-                    ForEach(HotkeyMonitor.Key.allCases, id: \.self) { key in
-                        Text(SettingsModel.label(for: key)).tag(key.rawValue)
+                LabeledContent("Hotkey") {
+                    HStack(spacing: 8) {
+                        HotkeyRecorder(value: $model.hotkey)
+                            .frame(width: 150, height: 24)
+                        Button("Reset to Fn") { model.hotkey = HotkeyBinding.fn.serialized }
+                            .buttonStyle(.link)
                     }
                 }
                 Toggle("Tap to toggle", isOn: $model.tapToToggle)
                 Toggle("Show recording pill", isOn: $model.overlay)
                 Toggle("Press Return after dictating", isOn: $model.newlineAfterRelease)
                 Toggle("Mute speakers while dictating", isOn: $model.muteOutput)
+            } footer: {
+                Text("Click the field, then hold the key or chord you want.")
+                    .font(.system(size: 11))
+                    .foregroundStyle(.secondary)
             }
             Section {
                 Picker("Model", selection: $model.model) {
diff --git a/Sources/yap/UI/SettingsWindow.swift b/Sources/yap/UI/SettingsWindow.swift
index 5c5322a..b7048ce 100644
--- a/Sources/yap/UI/SettingsWindow.swift
+++ b/Sources/yap/UI/SettingsWindow.swift
@@ -66,9 +66,10 @@ enum SettingsWindow {
 
 // MARK: - Panes
 
-/// The three things yap can be told about, in the order you meet them: the
-/// key you hold, what happens to a recording, and when to offer one.
+/// The four things yap can be told about, in the order you meet them: how it
+/// runs, the key you hold, what happens to a recording, and when to offer one.
 private enum SettingsPane: String, CaseIterable, Identifiable {
+    case general
     case dictation
     case recording
     case meetings
@@ -77,6 +78,7 @@ private enum SettingsPane: String, CaseIterable, Identifiable {
 
     var title: String {
         switch self {
+        case .general: return "General"
         case .dictation: return "Dictation"
         case .recording: return "Recording"
         case .meetings: return "Meetings"
@@ -87,6 +89,7 @@ private enum SettingsPane: String, CaseIterable, Identifiable {
     /// infer it from the controls.
     var summary: String {
         switch self {
+        case .general: return "Login, updates, logs."
         case .dictation: return "The key you hold, and what happens when you let go."
         case .recording: return "Where sessions land, and what runs after one."
         case .meetings: return "Whether yap offers to record when something else takes the mic."
@@ -95,6 +98,7 @@ private enum SettingsPane: String, CaseIterable, Identifiable {
 
     var symbol: String {
         switch self {
+        case .general: return "slider.horizontal.3"
         case .dictation: return "waveform"
         case .recording: return "recordingtape"
         case .meetings: return "person.wave.2.fill"
@@ -105,6 +109,7 @@ private enum SettingsPane: String, CaseIterable, Identifiable {
     /// is the record light, the same thing it means everywhere else in yap.
     var tint: Color {
         switch self {
+        case .general: return .gray
         case .dictation: return .accentColor
         case .recording: return .red
         case .meetings: return .indigo
@@ -116,7 +121,7 @@ private enum SettingsPane: String, CaseIterable, Identifiable {
 
 private struct SettingsView: View {
     @StateObject private var model = SettingsModel()
-    @State private var pane: SettingsPane = .dictation
+    @State private var pane: SettingsPane = .general
 
     var body: some View {
         VStack(spacing: 0) {
@@ -164,6 +169,7 @@ private struct SettingsView: View {
             .padding(.top, 18)
 
             switch pane {
+            case .general: GeneralPane(model: model)
             case .dictation: DictationPane(model: model)
             case .recording: RecordingPane(model: model)
             case .meetings: MeetingsPane(model: model)
diff --git a/Sources/yap/UI/StatusIcon.swift b/Sources/yap/UI/StatusIcon.swift
index dc17ea7..482ae4f 100644
--- a/Sources/yap/UI/StatusIcon.swift
+++ b/Sources/yap/UI/StatusIcon.swift
@@ -9,11 +9,34 @@ import AppKit
 /// too fine to hold its weight beside the system icons.
 enum StatusIcon {
     /// Template image at `size` points, so callers can tint it.
-    static func image(size: CGFloat) -> NSImage? {
+    ///
+    /// `badged` draws a filled dot at the bottom-right, for a staged update.
+    /// Still a template: the dot inherits the menu bar's own colour, which is
+    /// the only way a status item can raise its voice without looking like an
+    /// error.
+    static func image(size: CGFloat, badged: Bool = false) -> NSImage? {
         guard let data = svg.data(using: .utf8), let image = NSImage(data: data) else { return nil }
         image.size = NSSize(width: size, height: size)
         image.isTemplate = true
-        return image
+        guard badged else { return image }
+
+        let badge = (size * 0.34).rounded()
+        let composed = NSImage(size: image.size, flipped: false) { rect in
+            image.draw(in: rect)
+            let dot = NSRect(
+                x: rect.maxX - badge, y: rect.minY, width: badge, height: badge)
+            // Clear a slightly larger circle first, so the dot reads as
+            // separate rather than as part of the head at 16 points.
+            NSGraphicsContext.current?.compositingOperation = .clear
+            NSBezierPath(ovalIn: dot.insetBy(dx: -1, dy: -1)).fill()
+            NSGraphicsContext.current?.compositingOperation = .sourceOver
+            // Any opaque colour: a template image carries only its alpha.
+            NSColor.black.setFill()
+            NSBezierPath(ovalIn: dot).fill()
+            return true
+        }
+        composed.isTemplate = true
+        return composed
     }
 
     /// Stroke 2, not the 1.5 the feather used: compared against the real menu
diff --git a/Sources/yap/Updater.swift b/Sources/yap/Updater.swift
new file mode 100644
index 0000000..5dfc0d2
--- /dev/null
+++ b/Sources/yap/Updater.swift
@@ -0,0 +1,405 @@
+import AppKit
+import CryptoKit
+import Foundation
+import Security
+
+/// Keeps yap current from its own GitHub Releases.
+///
+/// No Sparkle. The whole mechanism is: read one JSON document, download a zip,
+/// check its digest, check its signature against the one this process is
+/// running under, and swap the bundle — about two hundred lines against a
+/// framework and an appcast, and it is the only network access yap makes after
+/// the model is on disk.
+///
+/// Nothing is replaced without a click. The download and every check happen in
+/// the background, and the menu then offers "Update to x.y.z · Restart" —
+/// which is also the only place the app can decide it is a bad moment, because
+/// a restart during a meeting would cost the recording.
+///
+/// The signature check is what makes the swap safe: the staged app has to be
+/// signed by the same team as the running one, so a poisoned feed cannot
+/// install something else, and TCC keeps the Accessibility and microphone
+/// grants because they are keyed on that identity.
+@MainActor
+final class Updater {
+    static let shared = Updater()
+
+    enum State {
+        case idle
+        /// Not an installed .app, or not signed by a team we can compare
+        /// against — a `swift build` binary, in other words. Nothing to do.
+        case unavailable(String)
+        case checking
+        case upToDate(Date)
+        case downloading(String)
+        case ready(version: String, app: URL)
+        case failed(String)
+
+        var description: String {
+            switch self {
+            case .idle: return "Not checked yet"
+            case .unavailable(let why): return why
+            case .checking: return "Checking…"
+            case .upToDate(let when):
+                let time = DateFormatter.localizedString(
+                    from: when, dateStyle: .none, timeStyle: .short)
+                return "Up to date · \(time)"
+            case .downloading(let version): return "Downloading \(version)…"
+            case .ready(let version, _): return "\(version) ready — restart from the menu"
+            case .failed(let why): return "Couldn't check: \(why)"
+            }
+        }
+    }
+
+    private(set) var state: State = .idle {
+        didSet { for observer in observers.values { observer(state) } }
+    }
+
+    private var observers: [UUID: (State) -> Void] = [:]
+
+    /// The daily timer, and the one-shot that runs the first check a little
+    /// after launch. Both nil while automatic checks are off, which is the
+    /// only state in which nothing of yap's is scheduled at all.
+    private var timer: Timer?
+    private var firstCheck: DispatchWorkItem?
+    private var inFlight = false
+
+    /// Overridable so the update path can be exercised against a local feed
+    /// without publishing a release: `YAP_RELEASES_URL=http://…`. Not a
+    /// setting — there is no reason for a user to point yap at another feed,
+    /// and every reason not to make it easy.
+    private let feedURL = URL(
+        string: ProcessInfo.processInfo.environment["YAP_RELEASES_URL"]
+            ?? "https://api.github.com/repos/TerrifiedBug/yap/releases/latest"
+    )!
+
+    /// The team the running code is signed by. Nil for an unsigned or
+    /// ad-hoc-signed build, which is what makes those ineligible: there would
+    /// be nothing to hold the replacement to.
+    private let teamIdentifier: String? = Updater.runningTeamIdentifier()
+
+    private init() {
+        if !Bundle.main.bundlePath.hasSuffix(".app") || teamIdentifier == nil {
+            state = .unavailable("Updates only apply to the installed app")
+        }
+    }
+
+    private var available: Bool {
+        if case .unavailable = state { return false }
+        return true
+    }
+
+    // MARK: - observation
+
+    /// A map rather than one closure: the menu bar and an open Settings window
+    /// both want the state, and the second one to subscribe must not silently
+    /// unhook the first.
+    @discardableResult
+    func observe(_ handler: @escaping (State) -> Void) -> UUID {
+        let token = UUID()
+        observers[token] = handler
+        handler(state)
+        return token
+    }
+
+    func unobserve(_ token: UUID) {
+        observers.removeValue(forKey: token)
+    }
+
+    // MARK: - scheduling
+
+    /// One check shortly after launch, then one a day.
+    ///
+    /// The 30 s delay keeps it off the startup path — the model has just
+    /// finished loading and the first press is the thing that matters. The
+    /// hour of tolerance lets the OS coalesce the daily wake with something
+    /// else it was going to do anyway.
+    func startAutomaticChecks() {
+        guard available, timer == nil, firstCheck == nil else { return }
+        let first = DispatchWorkItem { [weak self] in
+            MainActor.assumeIsolated {
+                self?.firstCheck = nil
+                self?.checkNow()
+            }
+        }
+        firstCheck = first
+        DispatchQueue.main.asyncAfter(deadline: .now() + 30, execute: first)
+
+        let daily = Timer.scheduledTimer(withTimeInterval: 86_400, repeats: true) { [weak self] _ in
+            MainActor.assumeIsolated { self?.checkNow() }
+        }
+        daily.tolerance = 3_600
+        timer = daily
+    }
+
+    func stopAutomaticChecks() {
+        firstCheck?.cancel()
+        firstCheck = nil
+        timer?.invalidate()
+        timer = nil
+    }
+
+    /// Manual check. Runs even with automatic checks off — turning the daily
+    /// request off is not the same as never wanting to know.
+    func checkNow() {
+        guard available, !inFlight else { return }
+        if case .ready = state { return }
+        inFlight = true
+        Task { [weak self] in
+            await self?.check()
+            self?.inFlight = false
+        }
+    }
+
+    /// Delete anything left in the staging directory. Called at launch: an
+    /// interrupted download is not worth resuming, and a stale extraction is
+    /// several megabytes of nothing.
+    static func cleanStaging() {
+        let dir = Paths.updatesDirectory
+        guard let entries = try? FileManager.default.contentsOfDirectory(
+            at: dir, includingPropertiesForKeys: nil)
+        else { return }
+        for entry in entries { try? FileManager.default.removeItem(at: entry) }
+    }
+
+    // MARK: - the check
+
+    private func check() async {
+        state = .checking
+        do {
+            guard let release = try await fetchLatest() else {
+                state = .upToDate(Date())
+                return
+            }
+            state = .downloading(release.version)
+            let staged = try await Self.stage(release)
+            try verify(staged)
+            state = .ready(version: release.version, app: staged)
+            warn("update \(release.version) staged at \(staged.path)")
+        } catch {
+            let reason = (error as? UpdateError)?.reason ?? error.localizedDescription
+            warn("update check failed: \(reason)")
+            state = .failed(reason)
+        }
+    }
+
+    private struct Release {
+        let version: String
+        let zip: URL
+        let checksum: URL
+    }
+
+    private struct Feed: Decodable {
+        let tagName: String
+        let assets: [Asset]
+
+        struct Asset: Decodable {
+            let name: String
+            let browserDownloadURL: URL
+
+            enum CodingKeys: String, CodingKey {
+                case name
+                case browserDownloadURL = "browser_download_url"
+            }
+        }
+
+        enum CodingKeys: String, CodingKey {
+            case tagName = "tag_name"
+            case assets
+        }
+    }
+
+    /// Nil when the published release is not newer than what is running.
+    private func fetchLatest() async throws -> Release? {
+        var request = URLRequest(url: feedURL)
+        request.setValue("application/vnd.github+json", forHTTPHeaderField: "Accept")
+        let (data, response) = try await URLSession.shared.data(for: request)
+        if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
+            throw UpdateError("release feed returned \(http.statusCode)")
+        }
+        let feed = try JSONDecoder().decode(Feed.self, from: data)
+        let version = feed.tagName.hasPrefix("v")
+            ? String(feed.tagName.dropFirst()) : feed.tagName
+        guard Self.isNewer(version, than: Yap.configuration.version ?? "0") else { return nil }
+
+        guard
+            let zip = feed.assets.first(where: { $0.name == "yap-\(version).zip" }),
+            let sum = feed.assets.first(where: { $0.name == "yap-\(version).zip.sha256" })
+        else { throw UpdateError("release has no zip") }
+        return Release(
+            version: version, zip: zip.browserDownloadURL, checksum: sum.browserDownloadURL)
+    }
+
+    /// Dotted integer components, left to right. Anything unparseable counts
+    /// as zero rather than throwing: a tag we cannot read is not a reason to
+    /// stop checking tomorrow.
+    static func isNewer(_ candidate: String, than current: String) -> Bool {
+        let new = candidate.split(separator: ".").map { Int($0) ?? 0 }
+        let old = current.split(separator: ".").map { Int($0) ?? 0 }
+        for index in 0..<max(new.count, old.count) {
+            let lhs = index < new.count ? new[index] : 0
+            let rhs = index < old.count ? old[index] : 0
+            if lhs != rhs { return lhs > rhs }
+        }
+        return false
+    }
+
+    /// Download, check the digest, unpack. Off the main actor: the digest and
+    /// the unpack are the only genuinely slow parts of an update, and neither
+    /// touches anything the UI owns.
+    private nonisolated static func stage(_ release: Release) async throws -> URL {
+        let dir = Paths.updatesDirectory
+        let zip = dir.appendingPathComponent("yap-\(release.version).zip")
+        try? FileManager.default.removeItem(at: zip)
+
+        let (downloaded, response) = try await URLSession.shared.download(from: release.zip)
+        if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
+            throw UpdateError("download returned \(http.statusCode)")
+        }
+        try FileManager.default.moveItem(at: downloaded, to: zip)
+
+        let (sumData, _) = try await URLSession.shared.data(from: release.checksum)
+        guard
+            let expected = String(decoding: sumData, as: UTF8.self)
+                .split(whereSeparator: \.isWhitespace).first
+        else {
+            try? FileManager.default.removeItem(at: zip)
+            throw UpdateError("checksum file is empty")
+        }
+        let digest = SHA256.hash(data: try Data(contentsOf: zip))
+            .map { String(format: "%02x", $0) }.joined()
+        guard digest == expected.lowercased() else {
+            try? FileManager.default.removeItem(at: zip)
+            throw UpdateError("checksum mismatch")
+        }
+
+        // ditto, not Foundation: there is no unarchiver in Foundation, and
+        // ditto is the one tool that preserves the code signature and the
+        // extended attributes a signed bundle needs to stay valid.
+        let unpacked = dir.appendingPathComponent(release.version, isDirectory: true)
+        try? FileManager.default.removeItem(at: unpacked)
+        let ditto = Process()
+        ditto.executableURL = URL(fileURLWithPath: "/usr/bin/ditto")
+        ditto.arguments = ["-x", "-k", zip.path, unpacked.path]
+        try ditto.run()
+        ditto.waitUntilExit()
+        try? FileManager.default.removeItem(at: zip)
+        guard ditto.terminationStatus == 0 else { throw UpdateError("couldn't unpack the download") }
+
+        let app = unpacked.appendingPathComponent("yap.app")
+        guard FileManager.default.fileExists(atPath: app.path) else {
+            throw UpdateError("download contains no yap.app")
+        }
+        return app
+    }
+
+    /// The staged app must be signed by the same team as the running one.
+    ///
+    /// This is the whole security model of the updater, and it is also what
+    /// keeps the permissions: TCC keys Accessibility and the microphone on the
+    /// signing identity, so a build from the same team inherits both, and one
+    /// from anywhere else is refused before it can be run at all.
+    private func verify(_ app: URL) throws {
+        guard let team = teamIdentifier else { throw UpdateError("this build is not signed") }
+        var code: SecStaticCode?
+        guard SecStaticCodeCreateWithPath(app as CFURL, [], &code) == errSecSuccess,
+            let code
+        else {
+            try? FileManager.default.removeItem(at: app.deletingLastPathComponent())
+            throw UpdateError("staged app has no signature")
+        }
+        var requirement: SecRequirement?
+        let text = "anchor apple generic and certificate leaf[subject.OU] = \"\(team)\""
+        guard SecRequirementCreateWithString(text as CFString, [], &requirement) == errSecSuccess,
+            let requirement,
+            SecStaticCodeCheckValidity(code, [], requirement) == errSecSuccess
+        else {
+            try? FileManager.default.removeItem(at: app.deletingLastPathComponent())
+            throw UpdateError("signature mismatch")
+        }
+
+        // Downloaded by us, verified by us: without this LaunchServices puts
+        // the "downloaded from the internet" sheet in front of the relaunch,
+        // which for a menu-bar app nobody is looking at means it simply never
+        // comes back.
+        for path in [app.path, app.appendingPathComponent("Contents/MacOS/yap").path] {
+            removexattr(path, "com.apple.quarantine", XATTR_NOFOLLOW)
+        }
+    }
+
+    // MARK: - the swap
+
+    /// Replace the running bundle and restart into it.
+    ///
+    /// The relaunch is deliberately not a fork: a second instance takes the
+    /// daemon lock and the old one stands down, which is the mechanism that
+    /// already handles every other way two yaps can exist at once.
+    func installAndRestart() {
+        guard case .ready(let version, let staged) = state else { return }
+        let live = Bundle.main.bundleURL
+        do {
+            try swap(staged: staged, live: live)
+        } catch {
+            let reason = FileManager.default.isWritableFile(atPath: live.deletingLastPathComponent().path)
+                ? error.localizedDescription
+                : "can't write \(live.deletingLastPathComponent().path) — update with brew or the DMG"
+            warn("update install failed: \(reason)")
+            state = .failed(reason)
+            return
+        }
+        Self.cleanStaging()
+        warn("updated to \(version) — restarting")
+
+        if LaunchAgent.isLoaded {
+            LaunchAgent.kickstart()
+        } else {
+            let configuration = NSWorkspace.OpenConfiguration()
+            configuration.createsNewApplicationInstance = true
+            NSWorkspace.shared.openApplication(at: live, configuration: configuration)
+        }
+    }
+
+    private func swap(staged: URL, live: URL) throws {
+        do {
+            try FileManager.default.replaceItem(
+                at: live, withItemAt: staged, backupItemName: nil, options: [],
+                resultingItemURL: nil)
+        } catch {
+            // A busy or cross-volume replace: move the old one aside and put
+            // the new one in its place. Two renames rather than one atomic
+            // swap, so the failure window is real but tiny.
+            let aside = Paths.updatesDirectory.appendingPathComponent("yap-previous.app")
+            try? FileManager.default.removeItem(at: aside)
+            try FileManager.default.moveItem(at: live, to: aside)
+            do {
+                try FileManager.default.moveItem(at: staged, to: live)
+            } catch {
+                // Put it back rather than leave the machine with no yap.
+                try? FileManager.default.moveItem(at: aside, to: live)
+                throw error
+            }
+        }
+    }
+
+    // MARK: -
+
+    private static func runningTeamIdentifier() -> String? {
+        var code: SecCode?
+        guard SecCodeCopySelf([], &code) == errSecSuccess, let code else { return nil }
+        var info: CFDictionary?
+        let status = SecCodeCopySigningInformation(
+            unsafeBitCast(code, to: SecStaticCode.self),
+            SecCSFlags(rawValue: kSecCSSigningInformation), &info)
+        guard status == errSecSuccess,
+            let dictionary = info as? [String: Any],
+            let team = dictionary[kSecCodeInfoTeamIdentifier as String] as? String
+        else { return nil }
+        return team
+    }
+
+    private struct UpdateError: LocalizedError {
+        let reason: String
+        init(_ reason: String) { self.reason = reason }
+        var errorDescription: String? { reason }
+    }
+}
diff --git a/Sources/yap/Yap.swift b/Sources/yap/Yap.swift
index 7f5896a..6aab0d1 100644
--- a/Sources/yap/Yap.swift
+++ b/Sources/yap/Yap.swift
@@ -12,13 +12,31 @@ struct Yap: ParsableCommand {
         // The single source of truth for what this binary is. Nothing else
         // holds a version constant, and the release workflow greps this
         // literal against the tag, so a build can never claim the wrong one.
-        version: "0.2.0",
-        subcommands: [
-            Run.self, Start.self, Stop.self, Record.self, Models.self, Doctor.self, Setup.self,
-            Install.self, Bench.self,
-        ],
+        version: "0.3.0",
+        // Two subcommands, and that is the product: `run` is the app, `bench`
+        // is the only thing a terminal can do that the menu bar cannot.
+        // Everything else — setup, permissions, the login item, the model,
+        // recording a session — moved into the menu bar, where the people who
+        // need it are already looking.
+        subcommands: [Run.self, Bench.self],
         defaultSubcommand: Run.self
     )
+
+    /// Drop arguments an older yap's LaunchAgent still passes.
+    ///
+    /// yap 0.2 wrote `ProgramArguments = [binary, "run", "--skip-doctor"]`,
+    /// and that plist survives an upgrade — nothing rewrites it but yap. Left
+    /// alone, ArgumentParser would exit 64 on the unknown flag, `KeepAlive`
+    /// would relaunch, and the loop would never break, because the thing that
+    /// repairs the plist is a yap that got as far as running. So the flag is
+    /// ignored here rather than accepted as a no-op option — it does not
+    /// appear in `--help`, and `LaunchAgent.refreshIfStale()` removes the
+    /// reason for it on the first successful start.
+    static func main() {
+        let retired: Set<String> = ["--skip-doctor"]
+        let arguments = CommandLine.arguments.dropFirst().filter { !retired.contains($0) }
+        Self.main(Array(arguments))
+    }
 }
 
 // MARK: - run
@@ -29,21 +47,6 @@ struct Run: ParsableCommand {
         abstract: "Run the daemon in the foreground."
     )
 
-    @Option(name: .long, help: "Model id to use. Defaults to the configured, then recommended, model.")
-    var model: String?
-
-    @Option(name: .long, help: "Push-to-talk key: \(HotkeyMonitor.Key.names).")
-    var hotkey: String?
-
-    @Flag(name: .long, help: "Disable the on-screen recording overlay.")
-    var noOverlay: Bool = false
-
-    @Flag(name: .long, help: "Press Return after injecting the transcript.")
-    var newline: Bool = false
-
-    @Flag(name: .long, help: "Skip permission checks at startup.")
-    var skipDoctor: Bool = false
-
     @Flag(name: .long, help: "Print every keyboard event the tap sees (debug).")
     var debugHotkey: Bool = false
 
@@ -75,54 +78,35 @@ struct Run: ParsableCommand {
         // bound.
         Paths.trimOversizedLogs()
 
-        let chosenModel = try Resolve.model(model)
-        let key = try Resolve.hotkey(hotkey)
-        let root = Config.resolveRoot(cliOverride: nil)
-        // Outside the doctor block on purpose: that report is skipped entirely
-        // by the installed LaunchAgent, and even when it runs it only prints
-        // on a hard failure.
-        Resolve.warnIfSessionsUnsupported(chosenModel)
+        // Before the daemon comes up, and only when the file already exists:
+        // an installed plist from an older yap names arguments this build no
+        // longer takes. See `refreshIfStale`.
+        LaunchAgent.refreshIfStale()
 
-        if !skipDoctor {
-            try checkStartup(root: root, model: chosenModel, hotkey: key)
-        }
+        let chosenModel = try Resolve.model()
+        let key = Resolve.hotkey()
+        let root = Config.resolveRoot()
 
-        // After the flags, the config and the doctor report have all had their
-        // say, so a typo or a missing grant never costs someone the daemon
-        // they already had — and before the model loads, so a takeover never
-        // holds two copies of it in memory at once.
+        // Before the model loads, so a takeover never holds two copies of it
+        // in memory at once.
         guard DaemonLock.claim() else { throw ExitCode.success }
 
-        // One model, loaded once, before anything can ask for it. Warming up
-        // front is the difference between a 60 ms press and a press that waits
-        // out an ANE compile.
-        if !ModelStore.isDownloaded(chosenModel) {
-            warn("downloading \(chosenModel.id) (~\(chosenModel.sizeMB) MB) — one-off")
-        }
-        let transcriber = chosenModel.makeTranscriber()
-        do {
-            try runBlocking { try await transcriber.warmUp() }
-        } catch {
-            warn("warmup failed: \(error)")
-            throw ExitCode(1)
-        }
-
         let app = NSApplication.shared
         app.setActivationPolicy(.accessory)
 
+        // The status item goes up here, and the model is warmed behind it by
+        // `Daemon.start`. That order is the difference between an app that is
+        // on screen in a second and one that is invisible for the several
+        // minutes a first-run model download takes.
         let daemon = Daemon(
-            transcriber: transcriber,
+            transcriber: chosenModel.makeTranscriber(),
             model: chosenModel,
             root: root,
             hotkey: key,
-            cliModel: model,
-            cliHotkey: hotkey,
-            noOverlay: noOverlay,
-            newlineFlag: newline,
             echoTranscripts: echoTranscripts,
             debugHotkey: debugHotkey
         )
-        try daemon.start()
+        daemon.start()
         // NSApplication holds its delegate weakly; `daemon` stays alive
         // because this frame does, and app.run() never leaves it.
         app.delegate = daemon
@@ -138,7 +122,8 @@ struct Run: ParsableCommand {
         }
 
         var banner =
-            "listening on \(key.rawValue) \(Config.tapToToggle() ? "tap" : "hold") · \(chosenModel.id)"
+            "yap \(Yap.configuration.version ?? "?") · \(key.serialized) "
+            + "\(Config.tapToToggle() ? "tap" : "hold") · \(chosenModel.id)"
         if Config.meetingDetectionEnabled() {
             banner += " · watching for meetings → \(root.path)"
         }
@@ -215,851 +200,20 @@ struct Run: ParsableCommand {
         // did before this existed.
         warn("note: couldn't re-exec via \(real.path): \(String(cString: strerror(errno)))")
     }
-
-    /// The startup report, and what to do when it fails.
-    ///
-    /// Nobody reads that report when Finder or launchd started us — stderr is
-    /// a log file, and the window the user double-clicked has already gone —
-    /// so a first run with a permission missing looks exactly like nothing
-    /// happening. The notification is the only thing they will see. A terminal
-    /// run is left alone: the report is already on screen, and a notification
-    /// saying the same thing is noise.
-    private func checkStartup(
-        root: URL, model: TranscriptionModel, hotkey: HotkeyMonitor.Key
-    ) throws {
-        let checks = DoctorReport.run(recordingsRoot: root, model: model, hotkey: hotkey)
-        guard !DoctorReport.allOK(checks) else { return }
-        warn("startup checks failed:")
-        DoctorReport.print(checks)
-        warn("\nfix the above or pass --skip-doctor")
-        if isatty(STDERR_FILENO) == 0, let failed = DoctorReport.firstFailure(checks) {
-            notifyUser(
-                title: "yap can't start — \(failed.name)",
-                body: failed.remediation ?? "run `yap doctor` in a terminal"
-            )
-        }
-        throw ExitCode(1)
-    }
-}
-
-/// The daemon: one hotkey, one menu bar, one loaded model, and — when meeting
-/// detection is on — one recording session at a time.
-///
-/// Both halves live here rather than in two controllers because they share
-/// more than they don't: the same transcriber, the same menu-bar state line,
-/// and the same microphone. Keeping them together is what lets a dictation
-/// press and a meeting recording sit next to each other without either one
-/// noticing the other.
-@MainActor
-final class Daemon: NSObject, NSApplicationDelegate {
-    private let transcriber: any Transcriber
-    private let coordinator: TranscriptionCoordinator
-    private let root: URL
-    private let monitor: HotkeyMonitor
-    private let capture = AudioCapture()
-    private let overlay: RecordingOverlay?
-    private let menuBar: MenuBarController
-    private var detector: MeetingDetector?
-    /// `--newline` only. The config's own `newline_after_release` is read at
-    /// the point of use instead, so it can be flipped without a restart.
-    private let newlineFlag: Bool
-    /// The raw CLI overrides, kept so a config reload can re-run the same
-    /// flag-beats-file-beats-default precedence the daemon booted with.
-    private let cliModel: String?
-    private let cliHotkey: String?
-    /// The model actually loaded, for the "restart to pick it up" warning.
-    private let loadedModelID: String
-    private var configWatcher: ConfigWatcher?
-    /// Opt-in. See the doc comment where it is used.
-    private let echoTranscripts: Bool
-
-    /// True from a successful capture start until the transcript has been
-    /// injected. It guards the release edge — a failed `capture.start()` must
-    /// not look like a press — and stops a session transcript finishing in the
-    /// background from clearing the indicator out from under a live press.
-    private var dictating = false
-    /// True while the capture engine is live — a press, or a latched tap, in
-    /// flight. Distinct from `dictating`, which stays true through the
-    /// transcription that follows and only guards the indicator.
-    private var recording = false
-    /// When the live press started, for telling a tap from a hold in toggle
-    /// mode.
-    private var pressStartedAt = Date.distantPast
-    /// Whether the live press latches (`tap_to_toggle` read at its key-down).
-    /// Decided once per press, same reasoning as `overlayShown`: a config
-    /// saved mid-press must not change what the release edge means.
-    private var pressLatches = false
-    /// Monotonic press id. finishDictation only cleans up for its own press,
-    /// so a completion racing a newer press cannot tear down that press's
-    /// state.
-    private var pressGeneration = 0
-    /// Longer than this and a toggle-mode press is a hold, not a tap.
-    private static let tapThreshold: TimeInterval = 0.5
-    /// Pending lift of the detector's dictation suppression. Held so a new
-    /// press can cancel the previous press's timer.
-    private var unsuppress: DispatchWorkItem?
-    /// Whether this press is showing the pill. Decided once, at the press, so
-    /// a config saved mid-press cannot strand it.
-    private var overlayShown = false
-
-    private var session: RecordingSession?
-    /// Whether the live session was started by the meeting prompt rather than
-    /// by hand. Only those stop themselves when the call ends — silently
-    /// ending a recording someone started deliberately would lose audio they
-    /// asked for.
-    private var autoStarted = false
-
-    init(
-        transcriber: any Transcriber,
-        model: TranscriptionModel,
-        root: URL,
-        hotkey: HotkeyMonitor.Key,
-        cliModel: String?,
-        cliHotkey: String?,
-        noOverlay: Bool,
-        newlineFlag: Bool,
-        echoTranscripts: Bool,
-        debugHotkey: Bool
-    ) {
-        self.transcriber = transcriber
-        self.root = root
-        self.cliModel = cliModel
-        self.cliHotkey = cliHotkey
-        self.loadedModelID = model.id
-        self.newlineFlag = newlineFlag
-        self.echoTranscripts = echoTranscripts
-        self.monitor = HotkeyMonitor(key: hotkey, debug: debugHotkey)
-        // --no-overlay is the only thing that removes the panel outright. The
-        // config's own toggle is read per press, so it can be flipped while
-        // the daemon runs.
-        self.overlay = noOverlay ? nil : RecordingOverlay()
-        self.menuBar = MenuBarController(
-            modelID: model.id,
-            hotkeyName: hotkey.rawValue,
-            tapToToggle: Config.tapToToggle()
-        )
-        // Opt-in, and it only ever fires for *other* processes: the detector
-        // skips its own pid. Dictation therefore no longer prompts you to
-        // record yourself, which it did back when the two halves were separate
-        // binaries and holding the hotkey looked to the recorder like a call
-        // starting.
-        self.detector = Config.meetingDetectionEnabled() ? MeetingDetector() : nil
-        // The whole point of the merge: the session queue transcribes through
-        // the same warm model dictation uses, so the machine never holds two
-        // copies of it. Passing it in also tells the coordinator not to
-        // release it — the daemon keeps its model hot.
-        self.coordinator = TranscriptionCoordinator(transcriber: transcriber)
-        super.init()
-    }
-
-    func start() throws {
-        menuBar.onStartRecording = { [weak self] in self?.startSession() }
-        menuBar.onStopRecording = { [weak self] in
-            guard let self else { return }
-            if self.autoStarted { self.detector?.declineCurrentMeeting() }
-            self.stopSession()
-        }
-        menuBar.setIdle()
-
-        do {
-            try monitor.start { [weak self] event in
-                // The tap callback has already hopped to the main queue.
-                MainActor.assumeIsolated { self?.handle(event) }
-            }
-        } catch {
-            // launchd relaunches anything exiting non-zero (KeepAlive
-            // SuccessfulExit:false). A missing Accessibility grant is not a
-            // transient failure — it is a box only the user can tick, and
-            // retrying changes nothing. Exiting 1 here is precisely what turns
-            // launch-at-login into a relaunch loop, so say what is wrong and
-            // exit cleanly. The agent stays down until the grant exists and
-            // the next login (or `launchctl kickstart`) starts it again.
-            //
-            // --skip-doctor does NOT cover this: it only skips the startup
-            // report above, while the tap still fails here.
-            if !AXIsProcessTrusted() {
-                warn("accessibility not granted — yap cannot see the hotkey.")
-                warn(
-                    "grant it in System Settings → Privacy & Security → Accessibility, "
-                        + "then run `yap start`.")
-                // Naming the command matters. This process exits 0 so KeepAlive
-                // leaves it alone, which means ticking the box changes nothing
-                // by itself and the next login would otherwise be the only
-                // thing that brings the agent back.
-                notifyUser(
-                    title: "yap needs Accessibility",
-                    body: "Grant it in Privacy & Security, then run `yap start`."
-                )
-                throw ExitCode.success
-            }
-            warn("failed to register hotkey tap: \(error)")
-            warn("run `yap setup` to configure permissions.")
-            throw ExitCode(1)
-        }
-
-        if let detector {
-            wire(detector)
-            detector.start()
-        }
-
-        Task { [coordinator, root] in
-            // The handler fires on whatever executor the coordinator drains
-            // on, so hop back before touching the menu bar. Weak, or the
-            // coordinator would own the daemon that owns it.
-            await coordinator.setStatusHandler { [weak self] busy in
-                Task { @MainActor in self?.show(busy: busy) }
-            }
-            await coordinator.setTranscriptReadyHandler { dir in
-                // Fires on the coordinator's executor; hop to the main actor
-                // for AppKit.
-                Task { @MainActor in
-                    showToast(
-                        title: "Transcript ready",
-                        body: dir.lastPathComponent,
-                        button: "Open",
-                        secondaryButton: "Name…",
-                        onSecondary: { [weak self] in self?.promptForName(of: dir) }
-                    ) {
-                        NSWorkspace.shared.activateFileViewerSelecting(
-                            [dir.appendingPathComponent("transcript.md")]
-                        )
-                    }
-                }
-            }
-            await coordinator.resumePending(root: root)
-        }
-
-        // Hot reload. Create the file first, so the watcher arms on an inode
-        // rather than standing on the directory waiting for one, and so
-        // "Open Config File" always has something to show.
-        Config.ensureFileExists()
-        // And bring it up to date: an upgrade adds settings, and a config
-        // written by an older yap has no line for any of them. Runs before the
-        // watcher is armed so our own write is not reported as someone editing
-        // the file.
-        Config.ensureEveryKeyPresent()
-        configWatcher = ConfigWatcher { [weak self] in self?.reloadConfig() }
-    }
-
-    /// Finalize anything live before the process goes away. A session killed
-    /// mid-write loses its meta.json and would never be picked up again;
-    /// stopped cleanly it lands on disk with no transcript, which is exactly
-    /// what `resumePending` looks for on the next launch.
-    func applicationWillTerminate(_ notification: Notification) {
-        monitor.stop()
-        detector?.stop()
-        // A press in flight holds the mic gain lease. Without this the daemon
-        // exits leaving the user's input turned up.
-        capture.stop()
-        guard let session else { return }
-        session.stop()
-        self.session = nil
-        warn("○ stopped · \(session.dir.path) · will transcribe on next launch")
-    }
-
-    // MARK: - dictation
-
-    private func handle(_ event: HotkeyMonitor.Event) {
-        switch event {
-        case .pressed:
-            // Pressed while the mic is live only happens for a latched tap —
-            // hold mode's edges strictly alternate — and it means "stop".
-            // Deliberately not gated on the config: a latch must always be
-            // stoppable, even if the setting was turned off underneath it.
-            if recording { endDictation() } else { beginDictation() }
-        case .released:
-            guard recording else { return }
-            // Hold mode always ends here. Toggle mode ends here too when the
-            // key was held past the threshold — push-to-talk keeps working —
-            // and otherwise the quick tap leaves the recording latched.
-            let wasHeld = Date().timeIntervalSince(pressStartedAt) > Self.tapThreshold
-            if !pressLatches || wasHeld { endDictation() }
-        }
-    }
-
-    private func beginDictation() {
-        // State bookkeeping must not re-run under a second press: capture.start
-        // is idempotent, the generation bump below is not.
-        guard !recording else { return }
-        // Decided once per press. The file can be saved mid-press, and a pill
-        // that appears halfway through — or a level pump feeding a window
-        // nobody can see — is worse than honouring the answer we started on.
-        if let overlay, Config.overlayEnabled() {
-            overlayShown = true
-            // Fires on an audio thread; pushLevel is nonisolated for exactly
-            // this reason.
-            capture.onLevel = { level in overlay.pushLevel(level) }
-        } else {
-            overlayShown = false
-            capture.onLevel = nil
-        }
-        do {
-            try capture.start()
-        } catch {
-            warn("capture failed: \(error)")
-            return
-        }
-        // After the mic is actually ours, never before: a failed start that
-        // returned above would otherwise leave detection suppressed forever.
-        //
-        // Holding the hotkey wakes macOS's own speech daemon, which takes the
-        // mic under its own pid and so reads as a call starting. Nothing seen
-        // during our own press is evidence of a meeting.
-        unsuppress?.cancel()
-        unsuppress = nil
-        detector?.suppressed = true
-        dictating = true
-        recording = true
-        pressStartedAt = Date()
-        pressLatches = Config.tapToToggle()
-        pressGeneration += 1
-        warn("● dictating")
-        if overlayShown { overlay?.show(.recording) }
-        menuBar.setDictating(true)
-    }
-
-    private func endDictation() {
-        guard recording else { return }
-        // Cleared before the mic goes down, so the stopping tap's own release
-        // edge — and any synthetic release from setKey/reenable — is a no-op.
-        recording = false
-        let samples = capture.stop()
-
-        let seconds = Double(samples.count) / AudioCapture.targetSampleRate
-        let rms = computeRMS(samples)
-        warn(String(format: "○ captured %.2fs · rms %.3f", seconds, rms))
-        guard !samples.isEmpty else {
-            finishDictation(generation: pressGeneration)
-            return
-        }
-
-        if overlayShown { overlay?.show(.transcribing) }
-        menuBar.setTranscribing()
-        // Whose press this is. finishDictation refuses to clean up for anyone
-        // else's, so a newer press starting while this one transcribes keeps
-        // its indicator, its overlay and its capture.
-        let generation = pressGeneration
-        // Inherits this method's main-actor isolation, so injection and the
-        // menu-bar reset need no hop; the await on the transcriber suspends
-        // rather than blocks, leaving the main actor free the whole time.
-        Task { [transcriber, newlineFlag, echoTranscripts, generation, weak self] in
-            // Timed from the moment the key came up, through injection, so the
-            // log reports what the user actually waits for rather than just
-            // the model. Transcription is nearly all of it, but injection is a
-            // synthetic key event and is not free, and quoting inference alone
-            // would flatter us against tools that report end to end.
-            let started = Date()
-            do {
-                let text = try await transcriber.transcribe(samples)
-                let transcribed = Date().timeIntervalSince(started)
-                // A press that caught only silence transcribes to nothing.
-                // There is no text to place and nothing to tell the user, so
-                // neither branch runs: a bare Return would fire a half-typed
-                // chat message, and the clipboard would lose whatever it held
-                // in exchange for an empty string. The timing line below still
-                // reports the press.
-
-                // Which placement ran. The timing line said "inject" for both,
-                // so a transcript that quietly went to the pasteboard read
-                // exactly like one that was typed.
-                var route = "no text"
-                if !text.isEmpty {
-                    if TextInjector.focusedElementAcceptsText() {
-                        route = "typed"
-                        TextInjector.inject(text)
-                        // Send-on-release. A real key event rather than a "\n"
-                        // in the text, because chat inputs bind send to the
-                        // Return key code. The config half of this is read
-                        // here, after injection and off the measured path, so
-                        // it survives a save with no restart.
-                        if newlineFlag || Config.newlineAfterRelease() {
-                            TextInjector.pressReturn()
-                        }
-                    } else {
-                        route = "clipboard"
-                        // Nowhere to type: posting the events would drop the
-                        // transcript on the floor, and Return with no field is
-                        // worse than useless. Clobbering the pasteboard is the
-                        // lesser loss, and the notification says so.
-                        NSPasteboard.general.clearContents()
-                        NSPasteboard.general.setString(text, forType: .string)
-                        notifyUser(
-                            title: "yap",
-                            body: "No text field focused — transcript copied to clipboard"
-                        )
-                    }
-                    // Both routes: typing can land in the wrong field just as
-                    // the clipboard can be taken away by the next copy. The
-                    // menu holds it in memory only — see setLastTranscript.
-                    self?.menuBar.setLastTranscript(text)
-                }
-                let total = Date().timeIntervalSince(started)
-                // Length, never the words. Under launch-at-login this line
-                // goes to a log file that outlives the session, and a daemon
-                // that quietly keeps a plaintext record of everything you
-                // have ever dictated is a worse problem than any bug it would
-                // help diagnose. --echo-transcripts opts in, and the
-                // LaunchAgent never passes it.
-                let body = echoTranscripts ? " · \(text)" : " · \(text.count) chars"
-                warn(
-                    String(
-                        format: "→ %.0fms (%.0fms model + %.0fms %@)%@",
-                        total * 1000, transcribed * 1000,
-                        (total - transcribed) * 1000, route, body
-                    ))
-            } catch {
-                warn("transcription failed: \(error)")
-            }
-            self?.finishDictation(generation: generation)
-        }
-    }
-
-    private func finishDictation(generation: Int) {
-        // A newer press owns the indicator, the overlay and the detector
-        // suppression now. Clearing them here is the race this guards against:
-        // it used to hide the new press's pill and, because `dictating` went
-        // false under it, leave its capture running with no release to stop it.
-        guard generation == pressGeneration else { return }
-        dictating = false
-        overlay?.hide()
-        overlayShown = false
-        // The speech daemon holds the input stream for a beat after the key
-        // comes up — measured at about three seconds against a two second
-        // press. Lifting the suppression here would hand the detector that
-        // tail and let it read as a call, so it waits the tail out.
-        //
-        // A fixed wait rather than tracking which pids were up during the
-        // press: this only ever *delays* a real prompt, never drops one. A
-        // call that starts inside the window is still capturing when the
-        // window closes, and prompts a moment later — against a detector that
-        // already sits on two polls before asking, three seconds is nothing.
-        //
-        // Cancellable, and replaced on every press: two quick presses would
-        // otherwise have the first one's timer fire during the second one's
-        // tail and hand the detector exactly what this avoids. Only the
-        // newest press can lift it.
-        unsuppress?.cancel()
-        let item = DispatchWorkItem { [weak self] in
-            self?.unsuppress = nil
-            self?.detector?.suppressed = false
-        }
-        unsuppress = item
-        DispatchQueue.main.asyncAfter(deadline: .now() + 3, execute: item)
-        // setIdle restores the session line underneath, if a recording is live.
-        menuBar.setIdle()
-    }
-
-    // MARK: - sessions
-
-    private func startSession(auto: Bool = false, title: String? = nil) {
-        guard session == nil else { return }
-        do {
-            let newSession = try RecordingSession(root: root)
-            newSession.title = title
-            try newSession.start()
-            session = newSession
-            autoStarted = auto
-            if !auto {
-                // Started from the menu, so any prompt on screen is offering
-                // something we're already doing — and the pause below would
-                // strand it there for its full two-minute timeout.
-                retirePrompt()
-                // Holding the mic ourselves makes every audio client look
-                // busy, so the detector would scan all of them once a second
-                // to answer a question we'd ignore anyway: a call starting
-                // can't prompt while a session is live. An auto-started
-                // session keeps it, to notice the call it came from ending.
-                detector?.stop()
-            }
-            warn("● recording → \(newSession.dir.path)")
-            menuBar.setRecording(true, since: newSession.startedAt)
-        } catch {
-            warn("recording start failed: \(error)")
-            notifyUser(title: "yap — recording failed", body: "\(error)")
-        }
-    }
-
-    private func stopSession() {
-        guard let session else { return }
-        session.stop()
-        let elapsed = formatElapsed(Date().timeIntervalSince(session.startedAt))
-        warn("○ stopped · \(elapsed) · \(session.dir.path)")
-        self.session = nil
-        autoStarted = false
-        // No-op when the detector is already running, and nil when detection
-        // is off entirely.
-        detector?.start()
-        detector?.releaseAcceptedMeeting()
-        menuBar.setRecording(false, since: nil)
-
-        let dir = session.dir
-        Task { [coordinator] in await coordinator.enqueue(dir) }
-    }
-
-    /// End a session this app started by itself. For Ignore, which arrives
-    /// from the auto-record toast after a session is already running and from
-    /// the ask prompt before one exists.
-    private func stopSessionIfAutoStarted() {
-        guard session != nil, autoStarted else { return }
-        stopSession()
-    }
-
-    /// Attach the daemon's handlers. Starting the detector is the caller's
-    /// call: a manual session holds the mic, and detection must stay down
-    /// until it ends.
-    private func wire(_ detector: MeetingDetector) {
-        detector.onMeetingStart = { [weak self, weak detector] pid, appName in
-            guard let self else { return }
-
-            // Before anything else, including the AX title lookup and the
-            // back-to-back stop: an excluded app is invisible to every piece
-            // of meeting logic, not merely unprompted. Read fresh at each
-            // event, the same standing-consent pattern as auto-record below.
-            let bundleID = MeetingTitle.bundleID(forPID: pid)
-            if let bundleID, Config.meetingExcludedApps().contains(bundleID) {
-                warn("◇ \(appName ?? bundleID) is excluded — ignoring")
-                // Marks the pid, so the detector stops re-firing every poll;
-                // its end-of-meeting path clears the mark on its own.
-                detector?.declineCurrentMeeting()
-                return
-            }
-
-            let title = MeetingTitle.capture(forCapturePID: pid)
-            let who = appName ?? "Your microphone"
-            warn("◆ \(who) is in use" + (title.map { " · \($0)" } ?? ""))
-            if let session = self.session {
-                // A quiet gap followed by the same capture pid can be a device
-                // swap or a back-to-back call. Only a vanished meeting window
-                // is evidence that the accepted call ended.
-                guard self.autoStarted,
-                      let oldTitle = session.title,
-                      !MeetingTitle.windowExists(oldTitle, forCapturePID: pid)
-                else { return }
-                warn("◇ \(oldTitle) ended — a different call started")
-                self.stopSession()
-            }
-
-            // "Never ask about this app again", offered from whichever surface
-            // the user is looking at. Both need it to also end the recording
-            // this event may have just started.
-            let ignoreApp: @MainActor () -> Void = { [weak self, weak detector] in
-                guard let bundleID else { return }
-                Config.update { config in
-                    var list = config["meeting_excluded_apps"] as? [String] ?? []
-                    if !list.contains(bundleID) { list.append(bundleID) }
-                    config["meeting_excluded_apps"] = list
-                }
-                warn("◇ \(appName ?? bundleID) added to the ignore list")
-                detector?.declineCurrentMeeting()
-                self?.stopSessionIfAutoStarted()
-            }
-
-            // Standing consent is read at each event so config saves take
-            // effect without a restart. Recording is always announced.
-            if Config.meetingAutoRecord() {
-                self.startSession(auto: true, title: title)
-                guard self.session != nil else { return }
-                detector?.acceptCurrentMeeting()
-                showToast(
-                    title: appName.map { "Recording \($0) call" } ?? "Recording meeting",
-                    body: title ?? "Stop from the menu bar or here",
-                    button: "Stop",
-                    secondaryButton: bundleID != nil ? "Ignore" : nil,
-                    onSecondary: ignoreApp
-                ) { [weak self, weak detector] in
-                    detector?.declineCurrentMeeting()
-                    self?.stopSession()
-                }
-                return
-            }
-
-            askUser(
-                title: appName.map { "\($0) is in a call" } ?? "Your microphone is in use",
-                body: title ?? "Record this meeting?",
-                button: "Record",
-                // Only when we have both a name to show and an identity to
-                // store; a process with no app bundle gets Dismiss and no more.
-                secondaryButton: appName.flatMap { bundleID != nil ? "Ignore \($0)" : nil },
-                onSecondary: ignoreApp,
-                onDismiss: { detector?.declineCurrentMeeting() }
-            ) { [weak self] in
-                guard let self, self.session == nil else { return }
-                detector?.acceptCurrentMeeting()
-                self.startSession(auto: true, title: title)
-            }
-        }
-        // An unanswered prompt outlives the call it asked about (it sits for
-        // two minutes). Accepting it then would start a session no later end
-        // event could stop, so it goes as soon as the mic frees.
-        detector.onMeetingQuiet = { retirePrompt() }
-        detector.onMeetingEnd = { [weak self] in
-            guard let self, self.session != nil, self.autoStarted else { return }
-            warn("◇ call ended")
-            self.stopSession()
-        }
-    }
-
-    /// The transcript toast's Name action: update metadata, heading and folder.
-    private func promptForName(of dir: URL) {
-        let existing = (try? JSONSerialization.jsonObject(
-            with: Data(contentsOf: dir.appendingPathComponent("meta.json"))))
-            .flatMap { ($0 as? [String: Any])?["title"] as? String }
-        askForName(title: "Name this meeting", prefill: existing ?? "") { name in
-            let trimmed = name.trimmingCharacters(in: .whitespacesAndNewlines)
-            guard !trimmed.isEmpty else { return }
-            let newDir = RecordingSession.applyTitle(trimmed, to: dir)
-            showToast(title: "Saved", body: newDir.lastPathComponent, button: "Open") {
-                NSWorkspace.shared.activateFileViewerSelecting(
-                    [newDir.appendingPathComponent("transcript.md")])
-            }
-        }
-    }
-
-    /// The config file was saved. Everything that can change without a
-    /// restart is re-applied here; the rest is read at the point of use.
-    private func reloadConfig() {
-        // Resolve re-runs flag > file > default, so a CLI-set hotkey resolves
-        // to itself and both calls below no-op. It only throws on a bad
-        // *flag*, which was validated at boot.
-        if let key = try? Resolve.hotkey(cliHotkey) {
-            monitor.setKey(key)
-            menuBar.setHotkeyName(key.rawValue)
-        }
-        // Only the idle menu line: the mode itself is read at each key-down, so
-        // a flip takes effect on the next press either way.
-        menuBar.setTapToToggle(Config.tapToToggle())
-
-        let wantDetector = Config.meetingDetectionEnabled()
-        if wantDetector, detector == nil {
-            let newDetector = MeetingDetector()
-            detector = newDetector
-            wire(newDetector)
-            // Born mid-press, it would start clean and prompt for the speech
-            // daemon our own hotkey woke. Inherit the suppression: `dictating`
-            // covers a press in flight, a pending lift covers its tail. That
-            // same work item reads `detector` when it fires, so it releases
-            // this one correctly.
-            newDetector.suppressed = dictating || unsuppress != nil
-            // A manual session holds the mic, which makes every audio client
-            // look busy; startSession stops the detector for that reason and
-            // stopSession starts it again. Do not undo that here.
-            if session == nil { newDetector.start() }
-        } else if !wantDetector, let detector {
-            detector.stop()
-            self.detector = nil
-            // The prompt belongs to the detector, and only its quiet event
-            // retires it. Left up, "Record" stays live for two minutes after
-            // the feature was switched off, and would start an auto session
-            // nothing could ever stop — onMeetingEnd went with the detector.
-            retirePrompt()
-            // A session it auto-started earlier does keep recording: silently
-            // ending audio someone is relying on is worse than an orphan, and
-            // it comes off the menu like a manual one.
-        }
-
-        // A few hundred MB of model is not worth reloading under someone's cursor.
-        if let model = try? Resolve.model(cliModel), model.id != loadedModelID {
-            warn("config: model changed to \(model.id) — restart yap to load it")
-        }
-
-        // Same reasoning, different reason: a live session is writing into the
-        // old root, and resumePending was handed it at boot. Moving the daemon
-        // mid-flight would strand both.
-        if Config.resolveRoot(cliOverride: nil) != root {
-            warn("config: recordings_dir changed — restart yap to use it")
-        }
-
-        warn("config reloaded")
-    }
-
-    /// The menu bar has one state line and nowhere to put a queue depth, so a
-    /// draining queue is simply "transcribing". Failures reach the user
-    /// through a notification and the session's transcribe.log instead.
-    private func show(busy: Bool) {
-        // A live dictation press owns the indicator; it will call setIdle
-        // itself when it lands.
-        guard !dictating else { return }
-        if busy { menuBar.setTranscribing() } else { menuBar.setIdle() }
-    }
-}
-
-// MARK: - record
-
-struct Record: ParsableCommand {
-    static let configuration = CommandConfiguration(
-        abstract: "Record a session now — mic and system audio as two tracks — then transcribe."
-    )
-
-    @Option(name: .long, help: "Recordings root directory (overrides the config file).")
-    var out: String?
-
-    @Flag(
-        name: .long,
-        help: """
-            Cancel speaker echo on the mic track. Use this when the call plays \
-            through speakers, or both sides get transcribed twice.
-            """
-    )
-    var micVoiceProcessing: Bool = false
-
-    func run() throws {
-        let root = Config.resolveRoot(cliOverride: out)
-        // Before the microphone opens, not after the meeting. `yap record` has
-        // no --model flag, so this is whatever config resolves to; an id that
-        // does not resolve is left to the coordinator, which says so better.
-        if let model = try? Resolve.model(nil) {
-            Resolve.warnIfSessionsUnsupported(model)
-        }
-        let session = try RecordingSession(root: root)
-        try session.start(
-            voiceProcessing: micVoiceProcessing || Config.micVoiceProcessing()
-        )
-        warn("● recording → \(session.dir.path) · ^C to stop")
-
-        waitForInterrupt()
-
-        session.stop()
-        let elapsed = formatElapsed(Date().timeIntervalSince(session.startedAt))
-        warn("\n○ stopped · \(elapsed) · \(session.dir.path)")
-
-        if Config.transcriptionEnabled() {
-            warn("transcribing...")
-        }
-        // No transcriber handed over: this is a one-shot, so the coordinator
-        // loads a model, uses it and releases it rather than keeping it warm
-        // for a next press that isn't coming. It also fires the on_stop hook
-        // itself once the transcript is on disk — don't run it again here.
-        let coordinator = TranscriptionCoordinator()
-        let dir = session.dir
-        try runBlocking { await coordinator.transcribeNow(dir) }
-    }
-}
-
-// MARK: - models
-
-struct Models: ParsableCommand {
-    static let configuration = CommandConfiguration(
-        abstract: "Manage transcription models.",
-        subcommands: [List.self, Download.self]
-    )
-
-    struct List: ParsableCommand {
-        static let configuration = CommandConfiguration(abstract: "List the built-in models.")
-
-        func run() throws {
-            for m in ModelRegistry.shared {
-                let star = m.recommended ? "★" : " "
-                let have = ModelStore.isDownloaded(m) ? "✓" : " "
-                let langs = m.languages.count > 2
-                    ? "[\(m.languages.count) langs]"
-                    : "[\(m.languages.joined(separator: ","))]"
-                let size = String(format: "%5d MB", m.sizeMB)
-                // Only the models that cannot do sessions are marked. Doctor
-                // sends people here to pick a replacement, so the limitation
-                // has to be visible — but tagging every capable model with
-                // "sessions" would be noise for the common case where they all
-                // are.
-                let limit = m.supportsSessions ? "" : "  · dictation only"
-                print(
-                    "\(star)\(have) \(pad(m.id, 26)) \(size)  \(pad(langs, 11))  "
-                        + "\(m.displayName)\(limit)")
-            }
-            print()
-            print("★ default · ✓ downloaded")
-            if ModelRegistry.shared.contains(where: { !$0.supportsSessions }) {
-                print("· dictation only — cannot transcribe recorded sessions")
-            }
-            print("  models: \(ModelStore.displayPath(ModelStore.modelsRoot))")
-        }
-    }
-
-    struct Download: ParsableCommand {
-        static let configuration = CommandConfiguration(abstract: "Fetch a model ahead of time.")
-
-        @Argument(help: "Model id to download.") var id: String
-
-        func run() throws {
-            guard let model = ModelRegistry.find(id) else {
-                throw ValidationError(
-                    "unknown model: \(id) — run `yap models list` to see options")
-            }
-            if ModelStore.isDownloaded(model) {
-                print("✓ \(model.id) already downloaded")
-                return
-            }
-            print("→ downloading \(model.id) (~\(model.sizeMB) MB), then compiling for the ANE...")
-            // warmUp, not just a download: the first load compiles for the ANE
-            // and that is the slow half. Paying it here means the daemon's
-            // first press doesn't.
-            try runBlocking { try await model.makeTranscriber().warmUp() }
-            print("✓ \(model.id)")
-        }
-    }
-}
-
-// MARK: - doctor
-
-struct Doctor: ParsableCommand {
-    static let configuration = CommandConfiguration(
-        abstract: "Check permissions, key mapping, recordings folder, and the selected model."
-    )
-
-    func run() throws {
-        let model = try Resolve.model(nil)
-        let key = try Resolve.hotkey(nil)
-        let checks = DoctorReport.run(
-            recordingsRoot: Config.resolveRoot(cliOverride: nil),
-            model: model,
-            hotkey: key
-        )
-        DoctorReport.print(checks)
-        if !DoctorReport.allOK(checks) {
-            throw ExitCode(1)
-        }
-    }
 }
 
 // MARK: - shared resolution
 
-/// Flags beat the config file beats the built-in default, resolved in one
-/// place so `yap doctor` reports on exactly what `yap run` would load.
+/// The config file beats the built-in default, resolved in one place.
+///
+/// There are no flags left to beat either of them: the daemon is the app, the
+/// app is configured from the Settings window, and the Settings window writes
+/// this same file.
 enum Resolve {
-    /// Say up front that recorded sessions will be skipped.
-    ///
-    /// `yap doctor` reports this too, but that is not enough on its own: the
-    /// startup report is only printed when some check hard-fails, and the
-    /// installed LaunchAgent runs with `--skip-doctor`, so a warning row would
-    /// never reach the daemon at all.
-    ///
-    /// A warning, not a refusal. Dictation is unaffected, and a recording made
-    /// on an incapable model is still worth having — refusing to record would
-    /// throw away the meeting to avoid a missing transcript.
-    ///
-    /// It promises retained audio and nothing more. Sessions under the
-    /// configured recordings root are picked up by `resumePending` on the next
-    /// launch with a capable model, but one written elsewhere by
-    /// `yap record --out` is never rescanned, and there is no command to
-    /// transcribe an existing folder. Claiming it would transcribe later would
-    /// be a promise this can't keep.
-    static func warnIfSessionsUnsupported(_ model: TranscriptionModel) {
-        guard Config.transcriptionEnabled(), !model.supportsSessions else { return }
-        warn(
-            "warning: \(model.id) cannot transcribe recorded sessions — "
-                + "audio is kept, but no transcript is written")
-    }
-
-    /// An unknown id on the command line is fatal — you asked for something
-    /// specific and didn't get it. An unknown id in the config file only
-    /// warns: bricking the daemon over a typo in a file edited weeks ago is
-    /// worse than quietly running the default.
-    static func model(_ override: String?) throws -> TranscriptionModel {
-        if let id = override {
-            guard let model = ModelRegistry.find(id) else {
-                throw ValidationError(
-                    "unknown model: \(id) — run `yap models list` to see options")
-            }
-            return model
-        }
+    /// An unknown id in the config file only warns: bricking the daemon over a
+    /// typo in a file edited weeks ago is worse than quietly running the
+    /// default.
+    static func model() throws -> TranscriptionModel {
         if let id = Config.dictationModel() {
             if let model = ModelRegistry.find(id) { return model }
             warn("warning: unknown model \"\(id)\" in \(Config.path.path) — using the default")
@@ -1070,23 +224,21 @@ enum Resolve {
         return model
     }
 
-    /// Same precedence as `model`. Never falls back silently on an explicit
-    /// `--hotkey`: a push-to-talk key that isn't the one you asked for is
-    /// worse than a startup error, because you find out by speaking into
-    /// nothing.
-    static func hotkey(_ override: String?) throws -> HotkeyMonitor.Key {
-        if let name = override {
-            guard let key = HotkeyMonitor.Key(name: name) else {
-                throw ValidationError(
-                    "unknown hotkey: \(name) — one of: \(HotkeyMonitor.Key.names)")
-            }
-            return key
-        }
-        if let name = Config.hotkey() {
-            if let key = HotkeyMonitor.Key(name: name) { return key }
-            warn("warning: unknown hotkey \"\(name)\" in \(Config.path.path) — using fn")
-        }
-        return .fn
+    /// Same precedence as `model`, and the same reasoning about a bad value:
+    /// warn and fall back to Fn rather than refuse to start. An unusable
+    /// binding — a bare letter, which would swallow every one you type —
+    /// is refused the same way.
+    static func hotkey() -> HotkeyBinding {
+        guard let name = Config.hotkey() else { return .fn }
+        guard let binding = HotkeyBinding(parsing: name) else {
+            warn("warning: unreadable hotkey \"\(name)\" in \(Config.path.path) — using fn")
+            return .fn
+        }
+        if let reason = HotkeyBinding.validate(binding) {
+            warn("warning: hotkey \"\(name)\" \(reason) — using fn")
+            return .fn
+        }
+        return binding
     }
 }
 
@@ -1119,13 +271,12 @@ func runBlocking<T: Sendable>(_ body: @escaping @Sendable () async throws -> T)
     return try box.result!.get()
 }
 
-/// Signal handling for both long-running commands.
+/// Signal handling for the daemon.
 ///
 /// Ignore the default disposition first: between `resume()` and a signal
 /// arriving, the default disposition would still kill the process before the
 /// handler ever ran. SIGTERM as well as SIGINT, because launchd stops the
-/// agent with SIGTERM and both callers have teardown that puts the user's mic
-/// gain back.
+/// agent with SIGTERM and the teardown puts the user's mic gain back.
 ///
 /// The returned sources must be held for as long as the handler should fire.
 /// They are cancelled when released, and a cancelled source over an
@@ -1143,15 +294,6 @@ private func interruptSources(_ handler: @escaping @Sendable () -> Void)
     }
 }
 
-/// Block until ^C, servicing the main run loop meanwhile. Core Audio and
-/// AVAudioEngine both deliver work on the main queue, so a bare `sleep` would
-/// starve a recording that looks like it is running fine.
-private func waitForInterrupt() {
-    let sources = interruptSources { CFRunLoopStop(CFRunLoopGetMain()) }
-    CFRunLoopRun()
-    sources.forEach { $0.cancel() }
-}
-
 /// `m:ss`, widening to `h:mm:ss` only once there is an hour to show. Every
 /// duration a user reads goes through here: the menu bar's live session
 /// counter, the line printed when a recording stops, and the timestamps in
diff --git a/Tests/yapTests/HotkeyBindingTests.swift b/Tests/yapTests/HotkeyBindingTests.swift
new file mode 100644
index 0000000..d144e35
--- /dev/null
+++ b/Tests/yapTests/HotkeyBindingTests.swift
@@ -0,0 +1,102 @@
+import CoreGraphics
+import XCTest
+
+@testable import yap
+
+/// `HotkeyBinding` is the contract between the config file, the Settings
+/// recorder and the event tap. A binding that serializes to something it
+/// cannot parse back is a hotkey that silently stops working after a restart,
+/// which is the one failure here nobody would attribute to the right cause.
+final class HotkeyBindingTests: XCTestCase {
+    private func roundTrip(_ text: String, file: StaticString = #filePath, line: UInt = #line) {
+        guard let binding = HotkeyBinding(parsing: text) else {
+            return XCTFail("\(text) did not parse", file: file, line: line)
+        }
+        XCTAssertEqual(binding.serialized, text, file: file, line: line)
+        XCTAssertEqual(
+            HotkeyBinding(parsing: binding.serialized), binding, file: file, line: line)
+    }
+
+    func testModifierNamesRoundTrip() {
+        for name in ["fn", "rightoption", "rightcommand", "rightcontrol", "rightshift",
+                     "leftoption", "leftcontrol", "leftshift"] {
+            roundTrip(name)
+        }
+    }
+
+    /// Every config written before free-form bindings existed says one of
+    /// these, in this spelling.
+    func testLegacyCamelCaseNamesStillParse() {
+        XCTAssertEqual(HotkeyBinding(parsing: "rightOption"), HotkeyBinding(parsing: "rightoption"))
+        XCTAssertEqual(HotkeyBinding(parsing: "RIGHT_SHIFT"), HotkeyBinding(parsing: "rightshift"))
+        XCTAssertEqual(HotkeyBinding(parsing: "fn"), .fn)
+    }
+
+    func testChordsRoundTrip() {
+        roundTrip("cmd+shift+space")
+        roundTrip("ctrl+opt+d")
+        roundTrip("f5")
+        roundTrip("cmd+grave")
+    }
+
+    /// Order and spelling are normalized, so two people writing the same chord
+    /// two ways get the same binding — and the file settles on one form.
+    func testChordSpellingIsCanonicalized() {
+        XCTAssertEqual(HotkeyBinding(parsing: "shift+command+space")?.serialized, "cmd+shift+space")
+        XCTAssertEqual(HotkeyBinding(parsing: "alt+control+d")?.serialized, "ctrl+opt+d")
+    }
+
+    func testUnknownKeysSurviveAsCodes() {
+        let binding = HotkeyBinding(parsing: "ctrl+key:250")
+        XCTAssertEqual(binding?.serialized, "ctrl+key:250")
+        XCTAssertEqual(binding?.displayName, "⌃Key 250")
+    }
+
+    func testGarbageIsRejected() {
+        XCTAssertNil(HotkeyBinding(parsing: ""))
+        XCTAssertNil(HotkeyBinding(parsing: "cmd+shift"))
+        XCTAssertNil(HotkeyBinding(parsing: "cmd+a+b"))
+        XCTAssertNil(HotkeyBinding(parsing: "middleshift"))
+    }
+
+    /// A bare letter would swallow every one you type anywhere on the machine.
+    /// A function key would not, because nothing types those.
+    func testBareLetterIsRefusedAndFunctionKeyIsNot() {
+        let letter = try? XCTUnwrap(HotkeyBinding(parsing: "a"))
+        XCTAssertEqual(letter.flatMap(HotkeyBinding.validate), "needs a modifier")
+        XCTAssertNil(HotkeyBinding(parsing: "f5").flatMap(HotkeyBinding.validate))
+        XCTAssertNil(HotkeyBinding(parsing: "cmd+a").flatMap(HotkeyBinding.validate))
+        XCTAssertNil(HotkeyBinding.validate(.fn))
+    }
+
+    /// macOS sets the Fn bit for the whole function and navigation group
+    /// whether or not 🌐 is held, so a binding that kept it could never match
+    /// the event it was recorded from.
+    func testImplicitFnIsStrippedFromFunctionAndArrowKeys() {
+        XCTAssertEqual(HotkeyBinding(parsing: "fn+f5")?.serialized, "f5")
+        XCTAssertEqual(HotkeyBinding(parsing: "fn+left")?.serialized, "left")
+        XCTAssertEqual(HotkeyBinding(parsing: "fn+space")?.serialized, "fn+space")
+    }
+
+    func testDisplayNames() {
+        XCTAssertEqual(HotkeyBinding(parsing: "fn")?.displayName, "Fn")
+        XCTAssertEqual(HotkeyBinding(parsing: "rightoption")?.displayName, "Right ⌥")
+        XCTAssertEqual(HotkeyBinding(parsing: "cmd+shift+space")?.displayName, "⌘⇧Space")
+        XCTAssertEqual(HotkeyBinding(parsing: "f5")?.displayName, "F5")
+        XCTAssertEqual(HotkeyBinding(parsing: "ctrl+opt+d")?.displayName, "⌃⌥D")
+    }
+
+    /// The tap shape depends on this: a modifier is a listen-only flagsChanged
+    /// tap, a chord has to subscribe to keys and swallow them.
+    func testOnlyChordsSubscribeToKeys() {
+        XCTAssertFalse(HotkeyBinding.fn.subscribesToKeys)
+        XCTAssertTrue(HotkeyBinding(parsing: "cmd+shift+space")?.subscribesToKeys ?? false)
+    }
+
+    func testUsesFnCoversBothShapes() {
+        XCTAssertTrue(HotkeyBinding.fn.usesFn)
+        XCTAssertTrue(HotkeyBinding(parsing: "fn+space")?.usesFn ?? false)
+        XCTAssertFalse(HotkeyBinding(parsing: "rightshift")?.usesFn ?? true)
+        XCTAssertFalse(HotkeyBinding(parsing: "cmd+shift+space")?.usesFn ?? true)
+    }
+}
diff --git a/Tests/yapTests/HotkeyMonitorTests.swift b/Tests/yapTests/HotkeyMonitorTests.swift
new file mode 100644
index 0000000..e823c6b
--- /dev/null
+++ b/Tests/yapTests/HotkeyMonitorTests.swift
@@ -0,0 +1,154 @@
+import CoreGraphics
+import XCTest
+
+@testable import yap
+
+/// `classify` is the decision the tap makes on every keystroke the machine
+/// produces, and the one place yap can break other apps: a chord that is not
+/// swallowed leaks into whatever you were typing into, and one that is
+/// swallowed too eagerly eats a shortcut yap has no business touching.
+///
+/// Real `CGEvent`s, not a stand-in, because the flags word is the thing under
+/// test — `.maskNonCoalesced` and the implicit Fn bit are exactly the details a
+/// hand-rolled double would get wrong.
+final class HotkeyMonitorTests: XCTestCase {
+    private func event(
+        _ keyCode: CGKeyCode, down: Bool, flags: CGEventFlags = []
+    ) -> CGEvent {
+        let event = CGEvent(keyboardEventSource: nil, virtualKey: keyCode, keyDown: down)!
+        event.flags = flags
+        return event
+    }
+
+    private func flagsEvent(_ flags: CGEventFlags) -> CGEvent {
+        let event = CGEvent(keyboardEventSource: nil, virtualKey: 0x3F, keyDown: true)!
+        event.type = .flagsChanged
+        event.flags = flags
+        return event
+    }
+
+    // MARK: - held modifier
+
+    func testFnPressAndReleaseAreEdgesAndAreNeverSwallowed() {
+        let monitor = HotkeyMonitor(binding: .fn)
+
+        let down = monitor.classify(type: .flagsChanged, event: flagsEvent(.maskSecondaryFn))
+        XCTAssertEqual(down.edge, .pressed)
+        XCTAssertFalse(down.swallow)
+
+        let up = monitor.classify(type: .flagsChanged, event: flagsEvent([]))
+        XCTAssertEqual(up.edge, .released)
+        XCTAssertFalse(up.swallow)
+    }
+
+    func testRepeatedFlagsWithoutAChangeAreNotEdges() {
+        let monitor = HotkeyMonitor(binding: .fn)
+        _ = monitor.classify(type: .flagsChanged, event: flagsEvent(.maskSecondaryFn))
+        let again = monitor.classify(type: .flagsChanged, event: flagsEvent(.maskSecondaryFn))
+        XCTAssertNil(again.edge)
+    }
+
+    /// A left-Shift binding must not fire on right Shift. Only the
+    /// device-specific bit tells them apart.
+    func testSidedModifiersDoNotCrossFire() {
+        let leftShift = HotkeyBinding(parsing: "leftshift")!
+        let monitor = HotkeyMonitor(binding: leftShift)
+        let right = CGEventFlags(rawValue: 0x0000_0004).union(.maskShift)
+        XCTAssertNil(monitor.classify(type: .flagsChanged, event: flagsEvent(right)).edge)
+
+        let left = CGEventFlags(rawValue: 0x0000_0002).union(.maskShift)
+        XCTAssertEqual(monitor.classify(type: .flagsChanged, event: flagsEvent(left)).edge, .pressed)
+    }
+
+    // MARK: - chord
+
+    func testChordPressAndReleaseAreSwallowed() {
+        let binding = HotkeyBinding(parsing: "cmd+shift+space")!
+        let monitor = HotkeyMonitor(binding: binding)
+        let flags: CGEventFlags = [.maskCommand, .maskShift]
+
+        let down = monitor.classify(type: .keyDown, event: event(49, down: true, flags: flags))
+        XCTAssertEqual(down.edge, .pressed)
+        XCTAssertTrue(down.swallow, "the app underneath must not receive the chord")
+
+        let up = monitor.classify(type: .keyUp, event: event(49, down: false, flags: flags))
+        XCTAssertEqual(up.edge, .released)
+        XCTAssertTrue(up.swallow)
+    }
+
+    /// Autorepeat while the chord is held is not a second press, and must not
+    /// reach the app either.
+    func testAutorepeatIsSwallowedWithoutAnEdge() {
+        let monitor = HotkeyMonitor(binding: HotkeyBinding(parsing: "cmd+shift+space")!)
+        let flags: CGEventFlags = [.maskCommand, .maskShift]
+        _ = monitor.classify(type: .keyDown, event: event(49, down: true, flags: flags))
+
+        let repeated = event(49, down: true, flags: flags)
+        repeated.setIntegerValueField(.keyboardEventAutorepeat, value: 1)
+        let result = monitor.classify(type: .keyDown, event: repeated)
+        XCTAssertNil(result.edge)
+        XCTAssertTrue(result.swallow)
+    }
+
+    /// Everything else on the machine has to pass through untouched. This is
+    /// the assertion that stands between yap and eating other shortcuts.
+    func testUnrelatedKeysAndModifierMismatchesPassThrough() {
+        let monitor = HotkeyMonitor(binding: HotkeyBinding(parsing: "cmd+shift+space")!)
+
+        let otherKey = monitor.classify(
+            type: .keyDown, event: event(0, down: true, flags: [.maskCommand, .maskShift]))
+        XCTAssertNil(otherKey.edge)
+        XCTAssertFalse(otherKey.swallow)
+
+        // Same key, ⌘ only: that is ⌘Space, the Spotlight shortcut.
+        let wrongFlags = monitor.classify(
+            type: .keyDown, event: event(49, down: true, flags: [.maskCommand]))
+        XCTAssertNil(wrongFlags.edge)
+        XCTAssertFalse(wrongFlags.swallow)
+    }
+
+    /// Letting go of ⌘ before Space ends the press — otherwise the mic stays
+    /// open with no release edge coming.
+    func testDroppingAModifierEndsTheChord() {
+        let monitor = HotkeyMonitor(binding: HotkeyBinding(parsing: "cmd+shift+space")!)
+        _ = monitor.classify(
+            type: .keyDown, event: event(49, down: true, flags: [.maskCommand, .maskShift]))
+
+        let result = monitor.classify(type: .flagsChanged, event: flagsEvent([.maskShift]))
+        XCTAssertEqual(result.edge, .released)
+        XCTAssertFalse(result.swallow, "the modifier itself is not ours to swallow")
+    }
+
+    /// A lone function key still matches when macOS sets the Fn bit for it,
+    /// which it does on every laptop keyboard.
+    func testFunctionKeyMatchesDespiteTheImplicitFnBit() {
+        let monitor = HotkeyMonitor(binding: HotkeyBinding(parsing: "f5")!)
+        let down = monitor.classify(
+            type: .keyDown, event: event(96, down: true, flags: [.maskSecondaryFn]))
+        XCTAssertEqual(down.edge, .pressed)
+        XCTAssertTrue(down.swallow)
+    }
+
+    // MARK: - suspension
+
+    /// While the Settings recorder is armed every keystroke belongs to it.
+    func testSuspendedMonitorClassifiesNothing() {
+        let monitor = HotkeyMonitor(binding: .fn)
+        monitor.setSuspended(true)
+        let result = monitor.classify(type: .flagsChanged, event: flagsEvent(.maskSecondaryFn))
+        XCTAssertNil(result.edge)
+        XCTAssertFalse(result.swallow)
+    }
+
+    /// Suspending mid-press must not leave the monitor believing the key is
+    /// still down: the next press has to read as a fresh press.
+    func testSuspendingDuringAPressClearsTheHeldState() {
+        let monitor = HotkeyMonitor(binding: .fn)
+        _ = monitor.classify(type: .flagsChanged, event: flagsEvent(.maskSecondaryFn))
+        monitor.setSuspended(true)
+        monitor.setSuspended(false)
+
+        let again = monitor.classify(type: .flagsChanged, event: flagsEvent(.maskSecondaryFn))
+        XCTAssertEqual(again.edge, .pressed)
+    }
+}
diff --git a/scripts/build-release.sh b/scripts/build-release.sh
index 8a987ef..e50af00 100755
--- a/scripts/build-release.sh
+++ b/scripts/build-release.sh
@@ -82,6 +82,13 @@ notarize() {
 
 notarize "$APP" "app"
 
+step "Zipping the app for in-app updates"
+# The .dmg is what a person downloads; this is what a running yap downloads.
+# ditto -c -k --keepParent, because it is the only archiver that preserves the
+# code signature and the extended attributes intact — Updater.swift verifies
+# the signature of whatever comes out of this before it swaps anything.
+ditto -c -k --keepParent "$APP" "$DIST/yap-$VERSION.zip"
+
 step "Building .dmg"
 mkdir -p "$DMG_STAGE"
 cp -R "$APP" "$DMG_STAGE/"
@@ -106,3 +113,4 @@ fi
 step "Done"
 echo "App: $APP"
 echo "DMG: $DMG"
+echo "ZIP: $DIST/yap-$VERSION.zip"
diff --git a/scripts/dev-install.sh b/scripts/dev-install.sh
index a15d73d..0ba4680 100755
--- a/scripts/dev-install.sh
+++ b/scripts/dev-install.sh
@@ -1,16 +1,17 @@
 #!/usr/bin/env bash
 #
-# Build the current tree and install it over /usr/local/bin/yap, signed with a
-# real identity so the Accessibility grant survives.
+# Build the current tree into /Applications/yap.app, signed with a real
+# identity so the Accessibility grant survives.
 #
-# This is the loop for testing a change on this machine. scripts/build-release.sh
-# is the other one: it builds the .app, notarizes and packages a .dmg for other
-# people. Nothing here is distributable.
+# This is the loop for testing a change on this machine. It runs the same
+# scripts/build-release.sh that CI runs, with notarization skipped — building
+# the bundle rather than a bare binary is the point, because the bundle is
+# what the product is and what TCC and LaunchServices see.
 #
-# The signing is the point. An adhoc-signed binary gives TCC nothing stable to
-# key on, so it falls back to the code hash, and every rebuild invalidates the
-# Accessibility grant while System Settings still shows the row ticked. Signed
-# with a Developer ID, the grant follows the identity and survives rebuilds.
+# The signing is the other half. An adhoc-signed build gives TCC nothing
+# stable to key on, so it falls back to the code hash and every rebuild
+# invalidates the Accessibility grant while System Settings still shows the
+# row ticked. Signed with a Developer ID, the grant follows the identity.
 #
 #   APP_IDENTITY  signing identity. Auto-detected when exactly one Developer ID
 #                 Application certificate exists; required otherwise.
@@ -19,7 +20,6 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT"
 
-BIN=".build/arm64-apple-macosx/release/yap"
 LABEL="com.terrifiedbug.yap"
 # Same variable name as build-release.sh, so one export covers both. Resolved
 # automatically only when the choice is unambiguous: silently picking the
@@ -53,85 +53,38 @@ fi
 
 step() { printf '\n\033[1;34m==>\033[0m %s\n' "$1"; }
 
-step "Building"
-swift build -c release --arch arm64
+VERSION=$(sed -n 's/.*version: "\(.*\)".*/\1/p' Sources/yap/Yap.swift)
+[[ -n "$VERSION" ]] || { echo "couldn't read the version from Sources/yap/Yap.swift" >&2; exit 1; }
 
-step "Signing"
-# --timestamp=none: a secure timestamp needs a round trip to Apple and only
-# matters for distribution. Local installs are rebuilt constantly.
-codesign --force --options runtime --timestamp=none \
-  --entitlements packaging/yap.entitlements \
-  --sign "$APP_IDENTITY" "$BIN"
-echo "signed: $APP_IDENTITY"
+step "Building yap.app $VERSION"
+SKIP_NOTARIZE=1 VERSION="$VERSION" APP_IDENTITY="$APP_IDENTITY" ./scripts/build-release.sh
 
-step "Installing"
-LOG="$HOME/Library/Logs/yap/yap.err.log"
-# Only read what this run appends; the log outlives many installs.
-offset=$(stat -f%z "$LOG" 2>/dev/null || echo 0)
-
-sudo install -m 755 "$BIN" /usr/local/bin/yap
-/usr/local/bin/yap install --launch-at-login
-
-# `install --launch-at-login` reports that it wrote and bootstrapped the agent,
-# which is not the same as the agent being usable: it exits 0 when
-# Accessibility is missing, precisely so KeepAlive does not relaunch it
-# forever. Check rather than claim.
-#
-# A PID is not the check either. On a cold model cache the daemon downloads
-# several hundred megabytes and compiles for the ANE before it ever touches
-# Accessibility, so it has a PID for minutes and then exits. Waiting on the
-# line it prints when the hotkey tap is actually live is the only signal that
-# means what it says.
-step "Waiting for it to come up"
-
-running() { launchctl list "$LABEL" 2>/dev/null | grep -q '"PID" ='; }
-ready() { tail -c "+$((offset + 1))" "$LOG" 2>/dev/null | grep -q 'listening on'; }
-
-echo "(first run downloads the model — this can take a few minutes)"
-deadline=$((SECONDS + 600))
-while [ "$SECONDS" -lt "$deadline" ]; do
-  if ready; then
-    echo "✓ running"
-    exit 0
-  fi
-  running || break
-  sleep 2
-done
-
-if ready; then
-  echo "✓ running"
-  exit 0
+# A binary left at /usr/local/bin by an older yap is not merely stale: it is a
+# second copy under a different code identity, and whichever one launchd runs
+# is the one that owns the Accessibility grant. One binary, one identity.
+if [[ -e /usr/local/bin/yap ]]; then
+  step "Removing the stale /usr/local/bin/yap"
+  echo "it predates the GUI-first layout and splits the TCC identity in two."
+  sudo rm -f /usr/local/bin/yap
 fi
 
-# Almost always the one-time grant. Changing the signing identity — including
-# the first time this script signs what used to be adhoc — gives TCC a new
-# identity to key on, so the old row is dead even though it still looks ticked.
-#
-# The daemon has already exited by now, and exits 0 so KeepAlive leaves it
-# alone. Granting therefore fixes nothing on its own: something has to start it
-# again afterwards. That is the whole reason this does not just print and quit.
-echo "not running yet — it starts, finds no Accessibility grant, and exits."
-echo
-echo "  1. remove any stale 'yap' row, then add:  /usr/local/bin/yap"
-echo "  2. come back here and press Return"
-echo
-open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility" 2>/dev/null || true
-read -r _
+step "Installing to /Applications"
+# ditto rather than cp -R: it preserves the signature's extended attributes.
+rm -rf /Applications/yap.app
+ditto dist/yap.app /Applications/yap.app
 
-step "Starting it again"
-offset=$(stat -f%z "$LOG" 2>/dev/null || echo 0)
-launchctl kickstart -k "gui/$(id -u)/$LABEL" 2>/dev/null || true
-deadline=$((SECONDS + 120))
-while [ "$SECONDS" -lt "$deadline" ]; do
-  ready && break
-  running || break
-  sleep 2
-done
-if ready; then
-  echo "✓ running"
+step "Starting it"
+if launchctl print "gui/$(id -u)/$LABEL" >/dev/null 2>&1; then
+  # Under launchd already: replace the job's image in place, so the login item
+  # keeps pointing at the same place and a recording in flight is finalized by
+  # the SIGTERM that -k sends.
+  launchctl kickstart -k "gui/$(id -u)/$LABEL"
+  echo "kickstarted the login agent"
 else
-  echo "✗ still not running. The reason is in the log:" >&2
-  echo "  tail ~/Library/Logs/yap/yap.err.log" >&2
-  echo "  /usr/local/bin/yap doctor" >&2
-  exit 1
+  open -n /Applications/yap.app
+  echo "launched /Applications/yap.app"
 fi
+
+echo
+echo "The menu bar mark should be up within a second, and will say what it"
+echo "still needs. Logs: $HOME/Library/Logs/yap/yap.err.log"

From 9a2e4bd9c1260000226915da3450d54b264329e3 Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 01:10:40 +0100
Subject: [PATCH 2/9] Fix a handler race, a silent tap failure, and two stale
 README claims
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review found four things worth fixing and one worth defending.

- `resumePending` could run before the transcript handler existed. The
  handlers were installed from their own unstructured Task while
  `loadModel` started immediately; warm-up is always slower than two
  actor hops, so nothing ever observed it, but "always slower" is not
  an ordering guarantee. They are now one chain:
  `installCoordinatorHandlers()` is awaited inside `loadModel` before
  warm-up, and the retry path re-enters it harmlessly.
- A tap that failed while Accessibility read as granted left no row at
  all: `setSetupNeeds` had already run, so the menu looked complete
  while the hotkey did nothing. `evaluateSetup` now builds the whole
  needs set — including a `hotkeyTap` row pointing at the Accessibility
  pane, which is what a stale grant actually needs — and publishes it
  once, after the tap attempt.
- README claimed "then you are offline forever", which stopped being
  true the moment yap started checking for updates. It now says what
  the network is used for and that it can be switched off.
- README listed the hotkey names in camelCase while the recorder writes
  them lower-case. It documents the canonical spelling and notes that
  parsing ignores case and separators, and the test that covers that no
  longer calls it a legacy path, because it never was one.

Recorder capture is now tested directly — right Option commits on
release, F5 alone is accepted, a bare letter is refused with "needs a
modifier" and writes nothing, Escape cancels, a chord commits on
key-down — against real NSEvents built from CGEvents, so the sided
modifier bits are the real ones. 37 tests.
---
 README.md                                |  14 ++-
 Sources/yap/Daemon.swift                 | 105 +++++++++--------
 Sources/yap/UI/HotkeyRecorder.swift      |   4 +-
 Sources/yap/UI/MenuBarController.swift   |  13 ++-
 Tests/yapTests/HotkeyBindingTests.swift  |   9 +-
 Tests/yapTests/HotkeyRecorderTests.swift | 136 +++++++++++++++++++++++
 6 files changed, 225 insertions(+), 56 deletions(-)
 create mode 100644 Tests/yapTests/HotkeyRecorderTests.swift

diff --git a/README.md b/README.md
index 7a68a10..4267135 100644
--- a/README.md
+++ b/README.md
@@ -20,8 +20,9 @@ and drag yap to Applications.
 
 Then launch yap from Applications. The menu bar mark appears straight away and
 walks you through the rest: it asks for Accessibility, then the microphone, and
-pulls the model down in the background. That is 220 MB, once, and then you are
-offline forever.
+pulls the model down in the background. That is 220 MB, once. Nothing you say
+ever leaves the machine; the only thing yap goes online for afterwards is a
+once-a-day check for a new version, which you can switch off in Settings.
 
 Builds are signed with a Developer ID certificate and notarized by Apple, so
 there is no Gatekeeper prompt. Apple Silicon only, because the model runs on
@@ -110,11 +111,12 @@ Save it and yap picks it up. The hotkey, `tap_to_toggle`, the overlay,
 change on the spot. A new `model` or `recordings_dir` wants a restart, and yap
 says so when it sees one.
 
-`hotkey` is a modifier held on its own — `fn`, `rightOption`, `rightCommand`,
-`rightControl`, `rightShift`, `leftOption`, `leftControl`, `leftShift` — or a
+`hotkey` is a modifier held on its own — `fn`, `rightoption`, `rightcommand`,
+`rightcontrol`, `rightshift`, `leftoption`, `leftcontrol`, `leftshift` — or a
 chord like `cmd+shift+space`, or a lone function key like `f5`. The recorder in
-Settings → Dictation writes this for you; a chord is swallowed while yap holds
-it, so the app underneath never sees it.
+Settings → Dictation writes this for you, in that spelling; typing it by hand
+is case-insensitive and ignores `-` and `_`, so `rightOption` works too. A
+chord is swallowed while yap holds it, so the app underneath never sees it.
 
 `newline_after_release` hits Return once the text is in, which is what you want
 for chat boxes.
diff --git a/Sources/yap/Daemon.swift b/Sources/yap/Daemon.swift
index cce63b1..70e069f 100644
--- a/Sources/yap/Daemon.swift
+++ b/Sources/yap/Daemon.swift
@@ -140,37 +140,6 @@ final class Daemon: NSObject, NSApplicationDelegate {
         // them.
         menuBar.onMenuWillOpen = { [weak self] in self?.evaluateSetup() }
 
-        // The handlers before the queue that fires them: `resumePending`
-        // below runs as soon as the model is warm, and a session finishing
-        // against an unset handler would fall back to a bare notification.
-        Task { [coordinator] in
-            // The handler fires on whatever executor the coordinator drains
-            // on, so hop back before touching the menu bar. Weak, or the
-            // coordinator would own the daemon that owns it.
-            await coordinator.setStatusHandler { [weak self] busy in
-                Task { @MainActor in self?.show(busy: busy) }
-            }
-            await coordinator.setTranscriptReadyHandler { dir in
-                // Fires on the coordinator's executor; hop to the main actor
-                // for AppKit.
-                Task { @MainActor in
-                    showToast(
-                        title: "Transcript ready",
-                        body: dir.lastPathComponent,
-                        button: "Open",
-                        secondaryButton: "Name…",
-                        onSecondary: { [weak self] in self?.promptForName(of: dir) },
-                        destructiveButton: "Delete",
-                        onDestructive: { [weak self] in self?.trashSession(dir) }
-                    ) {
-                        NSWorkspace.shared.activateFileViewerSelecting(
-                            [dir.appendingPathComponent("transcript.md")]
-                        )
-                    }
-                }
-            }
-        }
-
         // First launch asks, rather than telling a log file. Everything after
         // that is `evaluateSetup`, which is also what turns the tap on the
         // moment the box is ticked — no relaunch.
@@ -231,6 +200,13 @@ final class Daemon: NSObject, NSApplicationDelegate {
     /// cold cache is a several-hundred-megabyte download, and yap used to
     /// spend it invisible. Retryable, because the one thing that can fail
     /// here is a network the user can fix.
+    ///
+    /// One chain, deliberately: the handlers are installed, then the model is
+    /// warmed, then the backlog is resumed. Installing them from a second
+    /// unstructured task raced this one — nothing observed it, because warm-up
+    /// is always slower than two actor hops, but "always slower" is not an
+    /// ordering guarantee and a resumed session would have fallen back to a
+    /// bare notification when it lost.
     private func loadModel() {
         modelReady = false
         menuBar.setModelLoading(
@@ -240,6 +216,7 @@ final class Daemon: NSObject, NSApplicationDelegate {
         }
         Task { [weak self] in
             guard let self else { return }
+            await self.installCoordinatorHandlers()
             do {
                 try await self.transcriber.warmUp()
                 self.modelReady = true
@@ -257,6 +234,39 @@ final class Daemon: NSObject, NSApplicationDelegate {
         }
     }
 
+    /// Point the transcription queue at the menu bar and the transcript pill.
+    ///
+    /// Idempotent — a retry after a failed warm-up simply reassigns them —
+    /// and awaited before anything can enqueue, so a session that finishes
+    /// during startup gets the pill rather than the fallback notification.
+    private func installCoordinatorHandlers() async {
+        // The handler fires on whatever executor the coordinator drains on, so
+        // hop back before touching the menu bar. Weak, or the coordinator
+        // would own the daemon that owns it.
+        await coordinator.setStatusHandler { [weak self] busy in
+            Task { @MainActor in self?.show(busy: busy) }
+        }
+        await coordinator.setTranscriptReadyHandler { [weak self] dir in
+            // Fires on the coordinator's executor; hop to the main actor for
+            // AppKit.
+            Task { @MainActor in
+                showToast(
+                    title: "Transcript ready",
+                    body: dir.lastPathComponent,
+                    button: "Open",
+                    secondaryButton: "Name…",
+                    onSecondary: { [weak self] in self?.promptForName(of: dir) },
+                    destructiveButton: "Delete",
+                    onDestructive: { [weak self] in self?.trashSession(dir) }
+                ) {
+                    NSWorkspace.shared.activateFileViewerSelecting(
+                        [dir.appendingPathComponent("transcript.md")]
+                    )
+                }
+            }
+        }
+    }
+
     /// Subscribe the menu bar to the updater, and arm the daily check if the
     /// config wants it.
     ///
@@ -314,25 +324,32 @@ final class Daemon: NSObject, NSApplicationDelegate {
 
         let fnAction = hotkey.usesFn ? Permissions.fnKeyAction() : nil
         if fnAction != nil { needs.insert(.fnMapping) }
-        menuBar.setSetupNeeds(needs, fnAction: fnAction)
 
         // The tap needs the grant, and the grant can arrive at any time. Start
         // it the moment it does — the whole reason this is event-driven is so
         // nobody has to relaunch yap after ticking a box.
-        guard granted, !tapRunning else { return }
-        do {
-            try monitor.start { [weak self] event in
-                // The tap callback has already hopped to the main queue.
-                MainActor.assumeIsolated { self?.handle(event) }
+        if granted, !tapRunning {
+            do {
+                try monitor.start { [weak self] event in
+                    // The tap callback has already hopped to the main queue.
+                    MainActor.assumeIsolated { self?.handle(event) }
+                }
+                tapRunning = true
+                warn("listening on \(hotkey.serialized)")
+            } catch {
+                // Not fatal, and not an exit — exiting here is what used to
+                // turn launch-at-login into a relaunch loop. But it must not
+                // be silent either: the grant reads as present, so without a
+                // row of its own the menu would look complete while the
+                // hotkey did nothing at all. `tapCreate` refusing a
+                // trusted process is a stale grant, and re-adding the row in
+                // System Settings is what fixes it.
+                warn("failed to register hotkey tap: \(error)")
+                needs.insert(.hotkeyTap)
             }
-            tapRunning = true
-            warn("listening on \(hotkey.serialized)")
-        } catch {
-            // Not fatal, and not an exit: the process stays up with the row
-            // visible, so the menu can still say what is wrong. Exiting here
-            // is what used to turn launch-at-login into a relaunch loop.
-            warn("failed to register hotkey tap: \(error)")
         }
+
+        menuBar.setSetupNeeds(needs, fnAction: fnAction)
     }
 
     /// Finalize anything live before the process goes away. A session killed
diff --git a/Sources/yap/UI/HotkeyRecorder.swift b/Sources/yap/UI/HotkeyRecorder.swift
index 113e4a6..d92ba80 100644
--- a/Sources/yap/UI/HotkeyRecorder.swift
+++ b/Sources/yap/UI/HotkeyRecorder.swift
@@ -55,7 +55,9 @@ final class HotkeyRecorderView: NSView {
     /// afterwards does not also commit it on its own.
     private var sawKey = false
     /// Shown instead of the binding for a moment when a candidate is refused.
-    private var complaint: String?
+    /// Readable, like `isRecording`, because it is the whole of the field's
+    /// answer to a key it will not accept.
+    private(set) var complaint: String?
     private var complaintClear: DispatchWorkItem?
 
     override var acceptsFirstResponder: Bool { true }
diff --git a/Sources/yap/UI/MenuBarController.swift b/Sources/yap/UI/MenuBarController.swift
index 0efcf2a..edfc36f 100644
--- a/Sources/yap/UI/MenuBarController.swift
+++ b/Sources/yap/UI/MenuBarController.swift
@@ -43,6 +43,9 @@ final class MenuBarController: NSObject, NSMenuDelegate {
         static let accessibility = SetupNeeds(rawValue: 1 << 0)
         static let microphone = SetupNeeds(rawValue: 1 << 1)
         static let fnMapping = SetupNeeds(rawValue: 1 << 2)
+        /// The grant reads as present but the event tap would not register,
+        /// which is what a stale Accessibility row looks like from in here.
+        static let hotkeyTap = SetupNeeds(rawValue: 1 << 3)
     }
 
     /// Name of the push-to-talk key, as the state line spells it. Live: the
@@ -58,6 +61,7 @@ final class MenuBarController: NSObject, NSMenuDelegate {
     private let accessibilityItem: NSMenuItem
     private let microphoneItem: NSMenuItem
     private let fnItem: NSMenuItem
+    private let tapItem: NSMenuItem
     private let retryItem: NSMenuItem
     private let updateItem: NSMenuItem
     /// Backs the header card. `refresh()` stays the single point of truth and
@@ -143,10 +147,14 @@ final class MenuBarController: NSObject, NSMenuDelegate {
         fnItem = Self.item(
             "Open Keyboard Settings…", symbol: "keyboard",
             action: #selector(openKeyboardSettingsClicked))
+        tapItem = Self.item(
+            "Hotkey unavailable — Re-add yap in Accessibility…",
+            symbol: "exclamationmark.triangle",
+            action: #selector(grantAccessibilityClicked))
         retryItem = Self.item(
             "Retry Model Download", symbol: "arrow.clockwise",
             action: #selector(retryModelClicked))
-        for item in [accessibilityItem, microphoneItem, fnItem, retryItem] {
+        for item in [accessibilityItem, microphoneItem, fnItem, tapItem, retryItem] {
             item.isHidden = true
             menu.addItem(item)
         }
@@ -203,7 +211,7 @@ final class MenuBarController: NSObject, NSMenuDelegate {
 
         for item in [
             toggleItem, copyItem, settings, quit,
-            accessibilityItem, microphoneItem, fnItem, retryItem, updateItem,
+            accessibilityItem, microphoneItem, fnItem, tapItem, retryItem, updateItem,
         ] {
             item.target = self
         }
@@ -352,6 +360,7 @@ final class MenuBarController: NSObject, NSMenuDelegate {
         accessibilityItem.isHidden = !needs.contains(.accessibility)
         microphoneItem.isHidden = !needs.contains(.microphone)
         fnItem.isHidden = !needs.contains(.fnMapping)
+        tapItem.isHidden = !needs.contains(.hotkeyTap)
         if case .failed = model {
             retryItem.isHidden = false
         } else {
diff --git a/Tests/yapTests/HotkeyBindingTests.swift b/Tests/yapTests/HotkeyBindingTests.swift
index d144e35..8883dcb 100644
--- a/Tests/yapTests/HotkeyBindingTests.swift
+++ b/Tests/yapTests/HotkeyBindingTests.swift
@@ -24,11 +24,14 @@ final class HotkeyBindingTests: XCTestCase {
         }
     }
 
-    /// Every config written before free-form bindings existed says one of
-    /// these, in this spelling.
-    func testLegacyCamelCaseNamesStillParse() {
+    /// Parsing ignores case and separators, so a hand-edited config saying
+    /// `rightOption` or `RIGHT_OPTION` lands on the same binding the recorder
+    /// writes as `rightoption`. Not a legacy path — the recorder has only ever
+    /// written the canonical form — just a file people edit by hand.
+    func testParsingIgnoresCaseAndSeparators() {
         XCTAssertEqual(HotkeyBinding(parsing: "rightOption"), HotkeyBinding(parsing: "rightoption"))
         XCTAssertEqual(HotkeyBinding(parsing: "RIGHT_SHIFT"), HotkeyBinding(parsing: "rightshift"))
+        XCTAssertEqual(HotkeyBinding(parsing: "right-control")?.serialized, "rightcontrol")
         XCTAssertEqual(HotkeyBinding(parsing: "fn"), .fn)
     }
 
diff --git a/Tests/yapTests/HotkeyRecorderTests.swift b/Tests/yapTests/HotkeyRecorderTests.swift
new file mode 100644
index 0000000..bd30914
--- /dev/null
+++ b/Tests/yapTests/HotkeyRecorderTests.swift
@@ -0,0 +1,136 @@
+import AppKit
+import CoreGraphics
+import XCTest
+
+@testable import yap
+
+/// What the recorder field does with the keys pressed into it.
+///
+/// The view, not the click: driving AppKit's hit-testing from a test buys
+/// nothing, while the capture rules — commit a modifier on release, commit a
+/// chord on key-down, refuse a bare letter, cancel on Escape — are the part
+/// that can be wrong, and the part that writes to the config file.
+@MainActor
+final class HotkeyRecorderTests: XCTestCase {
+    private func makeRecorder() -> (HotkeyRecorderView, () -> [String]) {
+        let view = HotkeyRecorderView()
+        var written: [String] = []
+        view.onChange = { written.append($0) }
+        // The same way a person arms it: a click in the field. No window is
+        // needed — `mouseDown` only asks one to make it first responder.
+        view.mouseDown(with: Self.mouseDown())
+        return (view, { written })
+    }
+
+    private static func mouseDown() -> NSEvent {
+        NSEvent.mouseEvent(
+            with: .leftMouseDown, location: .zero, modifierFlags: [], timestamp: 0,
+            windowNumber: 0, context: nil, eventNumber: 0, clickCount: 1, pressure: 1)!
+    }
+
+    private func keyEvent(_ keyCode: CGKeyCode, modifiers: NSEvent.ModifierFlags) -> NSEvent {
+        NSEvent.keyEvent(
+            with: .keyDown, location: .zero, modifierFlags: modifiers, timestamp: 0,
+            windowNumber: 0, context: nil, characters: "", charactersIgnoringModifiers: "",
+            isARepeat: false, keyCode: UInt16(keyCode))!
+    }
+
+    /// Built from a CGEvent so the device-specific bit survives — that bit is
+    /// the only thing telling right Option from left, and `modifierFlags`
+    /// does not carry it.
+    private func flagsEvent(_ flags: CGEventFlags) -> NSEvent {
+        let cg = CGEvent(keyboardEventSource: nil, virtualKey: 0x3D, keyDown: true)!
+        cg.type = .flagsChanged
+        cg.flags = flags
+        return NSEvent(cgEvent: cg)!
+    }
+
+    // MARK: - modifier capture
+
+    /// Right Option, held and let go with no key in between.
+    func testHeldModifierCommitsOnRelease() {
+        let (view, written) = makeRecorder()
+        let rightOption = CGEventFlags(rawValue: 0x0000_0040).union(.maskAlternate)
+
+        view.flagsChanged(with: flagsEvent(rightOption))
+        XCTAssertTrue(view.isRecording, "still listening while the key is down")
+        XCTAssertEqual(written(), [])
+
+        view.flagsChanged(with: flagsEvent([]))
+        XCTAssertEqual(written(), ["rightoption"])
+        XCTAssertFalse(view.isRecording)
+    }
+
+    func testLeftShiftIsOfferedAndDistinctFromRight() {
+        let (view, written) = makeRecorder()
+        let leftShift = CGEventFlags(rawValue: 0x0000_0002).union(.maskShift)
+        view.flagsChanged(with: flagsEvent(leftShift))
+        view.flagsChanged(with: flagsEvent([]))
+        XCTAssertEqual(written(), ["leftshift"])
+    }
+
+    // MARK: - chord capture
+
+    func testChordCommitsOnKeyDown() {
+        let (view, written) = makeRecorder()
+        view.flagsChanged(with: flagsEvent([.maskCommand]))
+        view.keyDown(with: keyEvent(49, modifiers: [.command, .shift]))
+        XCTAssertEqual(written(), ["cmd+shift+space"])
+        XCTAssertFalse(view.isRecording)
+    }
+
+    /// A lone function key is a legitimate binding: nothing types one.
+    func testFunctionKeyAloneIsAccepted() {
+        let (view, written) = makeRecorder()
+        view.keyDown(with: keyEvent(96, modifiers: [.function]))
+        XCTAssertEqual(written(), ["f5"], "the implicit Fn bit must not become part of it")
+    }
+
+    /// A bare letter would swallow every one you type. It is refused, the
+    /// reason is shown, and nothing is written.
+    func testBareLetterIsRefusedAndKeepsListening() {
+        let (view, written) = makeRecorder()
+        view.keyDown(with: keyEvent(0, modifiers: []))
+        XCTAssertEqual(written(), [], "nothing written")
+        XCTAssertTrue(view.isRecording, "still listening, so the next try lands")
+        XCTAssertEqual(view.complaint, "needs a modifier")
+
+        // And the next, valid, attempt still works.
+        view.keyDown(with: keyEvent(0, modifiers: [.command]))
+        XCTAssertEqual(written(), ["cmd+a"])
+    }
+
+    // MARK: - cancelling
+
+    func testEscapeAloneCancelsWithoutWriting() {
+        let (view, written) = makeRecorder()
+        view.keyDown(with: keyEvent(53, modifiers: []))
+        XCTAssertEqual(written(), [])
+        XCTAssertFalse(view.isRecording)
+    }
+
+    /// Escape with a modifier is a binding like any other, so only the bare
+    /// press backs out.
+    func testEscapeWithAModifierIsABinding() {
+        let (view, written) = makeRecorder()
+        view.keyDown(with: keyEvent(53, modifiers: [.control]))
+        XCTAssertEqual(written(), ["ctrl+escape"])
+    }
+
+    func testLosingFocusCancels() {
+        let (view, written) = makeRecorder()
+        _ = view.resignFirstResponder()
+        XCTAssertFalse(view.isRecording)
+        XCTAssertEqual(written(), [])
+    }
+
+    /// Keys pressed while the field is not armed belong to whatever else is
+    /// on screen.
+    func testIdleRecorderWritesNothing() {
+        let view = HotkeyRecorderView()
+        var written: [String] = []
+        view.onChange = { written.append($0) }
+        view.keyDown(with: keyEvent(49, modifiers: [.command, .shift]))
+        XCTAssertEqual(written, [])
+    }
+}

From 6506034c0c644780fb94dec897465d67656741a6 Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 01:27:13 +0100
Subject: [PATCH 3/9] Let the pill answer only once
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every button stayed live for the 160 ms of the fade, so a double-click
ran the action twice. On Delete that meant two "Deleted" toasts and a
second trashItem failing on a folder already in the Trash — reported to
the user as an error they did not cause. Clicking Delete and then Open
did both, for the same reason.

The claim is synchronous, in the click, because the moment before the
fade starts is the only point where the two clicks are still
distinguishable. It covers all five actions: a panel is a question, and
a question is answered once.

Three tests, each confirmed to fail with the guard removed (two
deletions instead of one; the second button answering as well) while
the single-click control keeps passing. Then the same thing against the
running app: three real clicks inside the fade on a live transcript
pill produce exactly one `⌫ trashed` and no error.
---
 Sources/yap/UI/PromptPanel.swift      |  24 ++++++-
 Tests/yapTests/PromptPanelTests.swift | 100 ++++++++++++++++++++++++++
 2 files changed, 121 insertions(+), 3 deletions(-)
 create mode 100644 Tests/yapTests/PromptPanelTests.swift

diff --git a/Sources/yap/UI/PromptPanel.swift b/Sources/yap/UI/PromptPanel.swift
index ffd20c8..8c6b8e2 100644
--- a/Sources/yap/UI/PromptPanel.swift
+++ b/Sources/yap/UI/PromptPanel.swift
@@ -98,6 +98,8 @@ final class PromptPanel: NSPanel {
     private var nameField: NSTextField?
     private var autoDismiss: Timer?
     private let dismissAfter: TimeInterval
+    /// Whether a button has already been clicked. See `claimAnswer`.
+    private var answered = false
 
     static func present(
         title: String,
@@ -436,27 +438,43 @@ final class PromptPanel: NSPanel {
         super.close()
     }
 
+    /// A panel answers once.
+    ///
+    /// The fade takes 160 ms and every button stays live and clickable for
+    /// all of it, so a double-click ran the action twice: two "Deleted"
+    /// toasts, and a second `trashItem` failing on a folder that was already
+    /// in the Trash — reported to the user as an error they did not cause.
+    /// Claimed synchronously, in the click, because that is the only point
+    /// before the fade where the two clicks are still distinguishable.
+    private func claimAnswer() -> Bool {
+        guard !answered else { return false }
+        answered = true
+        return true
+    }
+
     @objc private func dismissClicked() {
+        guard claimAnswer() else { return }
         let dismiss = onDismiss
         fadeOut()
         dismiss()
     }
 
     @objc private func acceptClicked() {
+        guard claimAnswer() else { return }
         let accept = onAccept
         fadeOut()
         accept()
     }
 
     @objc private func destructiveClicked() {
-        guard let destructive = onDestructive else { return }
+        guard let destructive = onDestructive, claimAnswer() else { return }
         fadeOut {
             destructive()
         }
     }
 
     @objc private func secondaryClicked() {
-        guard let secondary = onSecondary else { return }
+        guard let secondary = onSecondary, claimAnswer() else { return }
         // Wait until the toast has closed before replacing it with the field.
         // This also keeps the originating mouse-up away from the Save button.
         fadeOut {
@@ -465,7 +483,7 @@ final class PromptPanel: NSPanel {
     }
 
     @objc private func saveClicked(_ sender: Any?) {
-        guard let field = nameField, let submit = onNameSubmit else { return }
+        guard let field = nameField, let submit = onNameSubmit, claimAnswer() else { return }
         let value = field.stringValue
         // `showToast` only presents while no question occupies the prompt slot.
         fadeOut {
diff --git a/Tests/yapTests/PromptPanelTests.swift b/Tests/yapTests/PromptPanelTests.swift
new file mode 100644
index 0000000..f89d2cb
--- /dev/null
+++ b/Tests/yapTests/PromptPanelTests.swift
@@ -0,0 +1,100 @@
+import AppKit
+import XCTest
+
+@testable import yap
+
+/// The pill answers once.
+///
+/// It fades for 160 ms after a click and stays clickable for all of it, which
+/// is long enough to double-click by accident — and the destructive action is
+/// the one where that matters: the second `trashItem` finds the folder already
+/// gone and reports a failure the user did not cause.
+///
+/// Driven through the real buttons rather than the private selectors, because
+/// the window this guards is between the click and the fade, and only a real
+/// `performClick` sits in it.
+@MainActor
+final class PromptPanelTests: XCTestCase {
+    override func tearDown() {
+        retirePrompt()
+        for panel in NSApp.windows.compactMap({ $0 as? PromptPanel }) {
+            panel.close()
+        }
+        super.tearDown()
+    }
+
+    private func button(_ title: String) throws -> NSButton {
+        let panel = try XCTUnwrap(
+            NSApp.windows.compactMap { $0 as? PromptPanel }.last, "no pill on screen")
+        let match = Self.buttons(in: try XCTUnwrap(panel.contentView))
+            .first { $0.attributedTitle.string == title }
+        return try XCTUnwrap(match, "no \"\(title)\" button in the pill")
+    }
+
+    private static func buttons(in view: NSView) -> [NSButton] {
+        view.subviews.flatMap { subview -> [NSButton] in
+            (subview as? NSButton).map { [$0] } ?? buttons(in: subview)
+        }
+    }
+
+    /// Two clicks inside the fade must produce one deletion.
+    func testDestructiveActionRunsOnceUnderADoubleClick() throws {
+        var deletions = 0
+        showToast(
+            title: "Transcript ready", body: "2026.01.01-0000", button: "Open",
+            destructiveButton: "Delete", onDestructive: { deletions += 1 },
+            onAccept: {}
+        )
+
+        let delete = try button("Delete")
+        delete.performClick(nil)
+        delete.performClick(nil)
+
+        // Long enough for both fades to have finished if the second click had
+        // started one.
+        spinRunLoop(for: 0.6)
+        XCTAssertEqual(deletions, 1)
+    }
+
+    /// The guard is the panel's, not the button's: clicking Delete and then
+    /// Open must not do both.
+    func testASecondButtonCannotAnswerAnAlreadyAnsweredPill() throws {
+        var deletions = 0
+        var opens = 0
+        showToast(
+            title: "Transcript ready", body: "2026.01.01-0000", button: "Open",
+            destructiveButton: "Delete", onDestructive: { deletions += 1 },
+            onAccept: { opens += 1 }
+        )
+
+        try button("Delete").performClick(nil)
+        try button("Open").performClick(nil)
+
+        spinRunLoop(for: 0.6)
+        XCTAssertEqual(deletions, 1)
+        XCTAssertEqual(opens, 0)
+    }
+
+    /// The ordinary single click still works — a guard that swallowed the
+    /// first click would pass both tests above.
+    func testASingleClickStillAnswers() throws {
+        var opens = 0
+        showToast(
+            title: "Transcript ready", body: "2026.01.01-0000", button: "Open",
+            onAccept: { opens += 1 }
+        )
+
+        try button("Open").performClick(nil)
+        spinRunLoop(for: 0.6)
+        XCTAssertEqual(opens, 1)
+    }
+
+    /// The fade's completion is delivered by the main run loop, so the test
+    /// has to let it run rather than sleeping the thread it arrives on.
+    private func spinRunLoop(for seconds: TimeInterval) {
+        let deadline = Date().addingTimeInterval(seconds)
+        while Date() < deadline {
+            RunLoop.main.run(mode: .default, before: Date().addingTimeInterval(0.02))
+        }
+    }
+}

From 84f64f61748370aed5d72c4b2e1f77f45f46b2a7 Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 01:38:30 +0100
Subject: [PATCH 4/9] Drop the retired-argument filter; repair the login item
 from the cask
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The acceptance sweep has to come back empty, and a runtime filter for
`--skip-doctor` is a compatibility shim however well it was measured.
It is gone, and the upgrade it existed for is handled where the upgrade
happens.

The failure is real and reproduced on this machine before changing
anything: a 0.2 plist against a 0.3 binary gives `last exit code = 64:
EX_USAGE` and `state = spawn scheduled`, which is KeepAlive relaunching
a job that can never start.

The cask postflight now rewrites `ProgramArguments` with plutil before
restarting, and does it with bootout + bootstrap rather than
`kickstart -k`, because launchd reads a plist when the job is
bootstrapped and not again — a kickstart relaunches the arguments it
already holds in memory, rewritten file or not. Verified against the
reproduced loop: the job comes back up and the plist is byte-identical
to a clean install.

`LaunchAgent.refreshIfStale()` stays. It is not a shim: it maintains our
own file, has no retired argument in it, and covers the DMG path — drag
the new app in, launch it, and the login item is corrected.

Known gap, stated rather than papered over: someone on 0.2 with launch
at login who upgrades by dragging a DMG and reboots without ever
launching the app gets the loop, until they launch yap once or delete
~/Library/LaunchAgents/com.terrifiedbug.yap.plist. Homebrew — the
documented way to install — is covered.
---
 .github/workflows/release.yml | 40 +++++++++++++++++++++++++----------
 Sources/yap/LaunchAgent.swift | 14 +++++++-----
 Sources/yap/Yap.swift         | 16 --------------
 3 files changed, 38 insertions(+), 32 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e1dc0b5..18ef030 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -167,23 +167,41 @@ jobs:
             # the new binary on disk and agrees with the version you just
             # installed — the worst shape for a bug, because it looks fixed.
             #
-            # "kickstart -k" rather than an uninstall stanza: it replaces the
-            # job launchd already owns, so the daemon stays inside launchd and
-            # the plist — the login item — is untouched.
+            # The rewrite first, and it is not cosmetic. yap 0.2's plist ran
+            # "yap run --skip-doctor", an argument 0.3 does not take: launchd
+            # would start it, ArgumentParser would exit 64, KeepAlive would
+            # relaunch it, and the login item would spin for ever. Nothing but
+            # this line and yap itself ever rewrites that file.
+            #
+            # bootout + bootstrap rather than "kickstart -k", because launchd
+            # reads a plist when the job is bootstrapped and not again — a
+            # kickstart would faithfully relaunch the arguments it already had
+            # in memory, rewritten file or not.
             #
             # Measured, because the alternative is losing someone's meeting:
-            # -k delivers SIGTERM, not SIGKILL, and yap catches SIGTERM and
-            # routes it through applicationWillTerminate. So a recording in
+            # bootout delivers SIGTERM, not SIGKILL, and yap catches SIGTERM
+            # and routes it through applicationWillTerminate. So a recording in
             # flight is finalized and transcribes on the next start instead of
-            # losing its meta.json. launchd brings the new image up about five
-            # seconds later.
+            # losing its meta.json.
             #
-            # must_succeed: false because an install with no login item has no
-            # job to restart, and launchctl exits 113 there. Not having asked
-            # for launch-at-login is not a reason to fail an upgrade.
+            # must_succeed: false throughout because an install with no login
+            # item has no job to restart, and launchctl exits 113 there. Not
+            # having asked for launch-at-login is not a reason to fail an
+            # upgrade.
             postflight do
+              agent = File.expand_path("~/Library/LaunchAgents/com.terrifiedbug.yap.plist")
+              next unless File.exist?(agent)
+
+              system_command "/usr/bin/plutil",
+                             args:         ["-replace", "ProgramArguments", "-json",
+                                            %Q(["#{appdir}/yap.app/Contents/MacOS/yap", "run"]),
+                                            agent],
+                             must_succeed: false
+              system_command "/bin/launchctl",
+                             args:         ["bootout", "gui/#{Process.uid}/com.terrifiedbug.yap"],
+                             must_succeed: false
               system_command "/bin/launchctl",
-                             args:         ["kickstart", "-k", "gui/#{Process.uid}/com.terrifiedbug.yap"],
+                             args:         ["bootstrap", "gui/#{Process.uid}", agent],
                              must_succeed: false
             end
 
diff --git a/Sources/yap/LaunchAgent.swift b/Sources/yap/LaunchAgent.swift
index c99ce41..9dcab83 100644
--- a/Sources/yap/LaunchAgent.swift
+++ b/Sources/yap/LaunchAgent.swift
@@ -114,11 +114,15 @@ enum LaunchAgent {
 
     /// Rewrite an installed plist that no longer says what this build writes.
     ///
-    /// The upgrade path, and the only one there is: yap 0.2 wrote
-    /// `run --skip-doctor` and pointed at whichever binary was current then.
-    /// Nothing but yap rewrites that file, so a build that changed either has
-    /// to repair it the first time it runs. Silent when there is nothing to
-    /// do, which is every launch after the first.
+    /// Nothing but yap maintains that file, so a build whose arguments or
+    /// binary path have moved on has to repair it the first time it runs, or
+    /// the login item keeps launching the old shape for ever. Silent when
+    /// there is nothing to do, which is every launch after the first.
+    ///
+    /// It repairs the file, not launchd's loaded copy of it: launchd reads a
+    /// plist when the job is bootstrapped and not again, so the corrected
+    /// definition takes effect at the next login. Reloading it from in here
+    /// would mean booting out the job this process *is*.
     static func refreshIfStale() {
         guard isInstalled, Bundle.main.bundlePath.hasSuffix(".app"),
             let binary = Bundle.main.executableURL?.resolvingSymlinksInPath().path
diff --git a/Sources/yap/Yap.swift b/Sources/yap/Yap.swift
index 6aab0d1..d8c7508 100644
--- a/Sources/yap/Yap.swift
+++ b/Sources/yap/Yap.swift
@@ -21,22 +21,6 @@ struct Yap: ParsableCommand {
         subcommands: [Run.self, Bench.self],
         defaultSubcommand: Run.self
     )
-
-    /// Drop arguments an older yap's LaunchAgent still passes.
-    ///
-    /// yap 0.2 wrote `ProgramArguments = [binary, "run", "--skip-doctor"]`,
-    /// and that plist survives an upgrade — nothing rewrites it but yap. Left
-    /// alone, ArgumentParser would exit 64 on the unknown flag, `KeepAlive`
-    /// would relaunch, and the loop would never break, because the thing that
-    /// repairs the plist is a yap that got as far as running. So the flag is
-    /// ignored here rather than accepted as a no-op option — it does not
-    /// appear in `--help`, and `LaunchAgent.refreshIfStale()` removes the
-    /// reason for it on the first successful start.
-    static func main() {
-        let retired: Set<String> = ["--skip-doctor"]
-        let arguments = CommandLine.arguments.dropFirst().filter { !retired.contains($0) }
-        Self.main(Array(arguments))
-    }
 }
 
 // MARK: - run

From 08aa423ea69134824d2f6697145daf2c8489805e Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 01:59:06 +0100
Subject: [PATCH 5/9] Keep the modifier spellings that are already in people's
 config files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I had the recorder writing `rightoption` where yap 0.2 wrote
`rightOption`. That was my invention and it was wrong twice over: the
plan's own acceptance line says recording right ⌥ writes
`"rightOption"`, and `HotkeyMonitor.Key` was a String enum whose
`rawValue` the Settings window wrote straight into the file — so every
existing config with a right-hand modifier already contains that exact
spelling.

Two spellings for one binding is what made the second look like a
compatibility path. There is one now, and it is the incumbent. Nothing
migrates, nothing is rewritten, and case-insensitive parsing stays
exactly what `Key.init(name:)` always did — it is for the file people
edit by hand, not for a retired API.

Verified live: a config saying `"hotkey": "rightOption"` hot-reloads
into `idle · hold Right ⌥ to dictate`, and the file is left untouched.
---
 README.md                                | 10 ++---
 Sources/yap/Input/HotkeyBinding.swift    | 47 +++++++++++++++---------
 Tests/yapTests/HotkeyBindingTests.swift  | 21 +++++------
 Tests/yapTests/HotkeyMonitorTests.swift  |  2 +-
 Tests/yapTests/HotkeyRecorderTests.swift |  4 +-
 5 files changed, 47 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index 4267135..a1f548e 100644
--- a/README.md
+++ b/README.md
@@ -111,12 +111,12 @@ Save it and yap picks it up. The hotkey, `tap_to_toggle`, the overlay,
 change on the spot. A new `model` or `recordings_dir` wants a restart, and yap
 says so when it sees one.
 
-`hotkey` is a modifier held on its own — `fn`, `rightoption`, `rightcommand`,
-`rightcontrol`, `rightshift`, `leftoption`, `leftcontrol`, `leftshift` — or a
+`hotkey` is a modifier held on its own — `fn`, `rightOption`, `rightCommand`,
+`rightControl`, `rightShift`, `leftOption`, `leftControl`, `leftShift` — or a
 chord like `cmd+shift+space`, or a lone function key like `f5`. The recorder in
-Settings → Dictation writes this for you, in that spelling; typing it by hand
-is case-insensitive and ignores `-` and `_`, so `rightOption` works too. A
-chord is swallowed while yap holds it, so the app underneath never sees it.
+Settings → Dictation writes it for you; typing it by hand is case-insensitive
+and ignores `-` and `_`. A chord is swallowed while yap holds it, so the app
+underneath never sees it.
 
 `newline_after_release` hits Return once the text is in, which is what you want
 for chat boxes.
diff --git a/Sources/yap/Input/HotkeyBinding.swift b/Sources/yap/Input/HotkeyBinding.swift
index 3714c62..89844ce 100644
--- a/Sources/yap/Input/HotkeyBinding.swift
+++ b/Sources/yap/Input/HotkeyBinding.swift
@@ -42,9 +42,9 @@ enum HotkeyBinding: Equatable {
     init?(parsing text: String) {
         let normalized = Self.normalize(text)
         guard !normalized.isEmpty else { return nil }
-        // A bare modifier name first: "fn" and "rightshift" are not chords,
-        // and they are what every config written before this existed says.
-        if let mask = Self.modifierMasks[normalized] {
+        // A bare modifier name first: "fn" and "rightShift" are not chords,
+        // and they are what a config file says.
+        if let mask = Self.modifierMask(named: normalized) {
             self = .modifier(mask)
             return
         }
@@ -120,28 +120,41 @@ enum HotkeyBinding: Equatable {
     /// constant; the sided ones are the only way to tell right Shift from left
     /// Shift at this level, because `.maskShift` is set by both.
     ///
+    /// These spellings are the ones already in people's config files —
+    /// `HotkeyMonitor.Key` was a `String` enum and the Settings window wrote
+    /// its `rawValue` — so they stay exactly as they were. Renaming them would
+    /// have been a silent data migration for the sake of tidier casing, and
+    /// every hotkey it failed to migrate would come back as Fn.
+    ///
     /// Left Command is deliberately absent. Too much of macOS begins with it,
     /// and a dictation press that starts every ⌘-anything is a trap.
     static let modifierMasks: [String: CGEventFlags] = [
         "fn": .maskSecondaryFn,
-        "rightoption": CGEventFlags(rawValue: 0x0000_0040),
-        "rightcommand": CGEventFlags(rawValue: 0x0000_0010),
-        "rightcontrol": CGEventFlags(rawValue: 0x0000_2000),
-        "rightshift": CGEventFlags(rawValue: 0x0000_0004),
-        "leftoption": CGEventFlags(rawValue: 0x0000_0020),
-        "leftcontrol": CGEventFlags(rawValue: 0x0000_0001),
-        "leftshift": CGEventFlags(rawValue: 0x0000_0002),
+        "rightOption": CGEventFlags(rawValue: 0x0000_0040),
+        "rightCommand": CGEventFlags(rawValue: 0x0000_0010),
+        "rightControl": CGEventFlags(rawValue: 0x0000_2000),
+        "rightShift": CGEventFlags(rawValue: 0x0000_0004),
+        "leftOption": CGEventFlags(rawValue: 0x0000_0020),
+        "leftControl": CGEventFlags(rawValue: 0x0000_0001),
+        "leftShift": CGEventFlags(rawValue: 0x0000_0002),
     ]
 
+    /// Lookup by the normalized form, so a name typed into the file by hand
+    /// finds its mask whatever case and separators it was written with —
+    /// exactly what `HotkeyMonitor.Key.init(name:)` always did.
+    static func modifierMask(named normalized: String) -> CGEventFlags? {
+        modifierMasks.first { normalize($0.key) == normalized }?.value
+    }
+
     private static let modifierLabels: [String: String] = [
         "fn": "Fn",
-        "rightoption": "Right ⌥",
-        "rightcommand": "Right ⌘",
-        "rightcontrol": "Right ⌃",
-        "rightshift": "Right ⇧",
-        "leftoption": "Left ⌥",
-        "leftcontrol": "Left ⌃",
-        "leftshift": "Left ⇧",
+        "rightOption": "Right ⌥",
+        "rightCommand": "Right ⌘",
+        "rightControl": "Right ⌃",
+        "rightShift": "Right ⇧",
+        "leftOption": "Left ⌥",
+        "leftControl": "Left ⌃",
+        "leftShift": "Left ⇧",
     ]
 
     /// Device-independent bits, for chords. A chord does not care which Shift.
diff --git a/Tests/yapTests/HotkeyBindingTests.swift b/Tests/yapTests/HotkeyBindingTests.swift
index 8883dcb..f9d8bd3 100644
--- a/Tests/yapTests/HotkeyBindingTests.swift
+++ b/Tests/yapTests/HotkeyBindingTests.swift
@@ -18,21 +18,18 @@ final class HotkeyBindingTests: XCTestCase {
     }
 
     func testModifierNamesRoundTrip() {
-        for name in ["fn", "rightoption", "rightcommand", "rightcontrol", "rightshift",
-                     "leftoption", "leftcontrol", "leftshift"] {
+        for name in ["fn", "rightOption", "rightCommand", "rightControl", "rightShift",
+                     "leftOption", "leftControl", "leftShift"] {
             roundTrip(name)
         }
     }
 
-    /// Parsing ignores case and separators, so a hand-edited config saying
-    /// `rightOption` or `RIGHT_OPTION` lands on the same binding the recorder
-    /// writes as `rightoption`. Not a legacy path — the recorder has only ever
-    /// written the canonical form — just a file people edit by hand.
+    /// Parsing ignores case and separators, the way it always has, so a name
+    /// typed into the file by hand finds its binding however it was written.
     func testParsingIgnoresCaseAndSeparators() {
-        XCTAssertEqual(HotkeyBinding(parsing: "rightOption"), HotkeyBinding(parsing: "rightoption"))
-        XCTAssertEqual(HotkeyBinding(parsing: "RIGHT_SHIFT"), HotkeyBinding(parsing: "rightshift"))
-        XCTAssertEqual(HotkeyBinding(parsing: "right-control")?.serialized, "rightcontrol")
-        XCTAssertEqual(HotkeyBinding(parsing: "fn"), .fn)
+        XCTAssertEqual(HotkeyBinding(parsing: "RIGHT_SHIFT"), HotkeyBinding(parsing: "rightShift"))
+        XCTAssertEqual(HotkeyBinding(parsing: "right-control")?.serialized, "rightControl")
+        XCTAssertEqual(HotkeyBinding(parsing: "FN"), .fn)
     }
 
     func testChordsRoundTrip() {
@@ -83,7 +80,7 @@ final class HotkeyBindingTests: XCTestCase {
 
     func testDisplayNames() {
         XCTAssertEqual(HotkeyBinding(parsing: "fn")?.displayName, "Fn")
-        XCTAssertEqual(HotkeyBinding(parsing: "rightoption")?.displayName, "Right ⌥")
+        XCTAssertEqual(HotkeyBinding(parsing: "rightOption")?.displayName, "Right ⌥")
         XCTAssertEqual(HotkeyBinding(parsing: "cmd+shift+space")?.displayName, "⌘⇧Space")
         XCTAssertEqual(HotkeyBinding(parsing: "f5")?.displayName, "F5")
         XCTAssertEqual(HotkeyBinding(parsing: "ctrl+opt+d")?.displayName, "⌃⌥D")
@@ -99,7 +96,7 @@ final class HotkeyBindingTests: XCTestCase {
     func testUsesFnCoversBothShapes() {
         XCTAssertTrue(HotkeyBinding.fn.usesFn)
         XCTAssertTrue(HotkeyBinding(parsing: "fn+space")?.usesFn ?? false)
-        XCTAssertFalse(HotkeyBinding(parsing: "rightshift")?.usesFn ?? true)
+        XCTAssertFalse(HotkeyBinding(parsing: "rightShift")?.usesFn ?? true)
         XCTAssertFalse(HotkeyBinding(parsing: "cmd+shift+space")?.usesFn ?? true)
     }
 }
diff --git a/Tests/yapTests/HotkeyMonitorTests.swift b/Tests/yapTests/HotkeyMonitorTests.swift
index e823c6b..3f69e93 100644
--- a/Tests/yapTests/HotkeyMonitorTests.swift
+++ b/Tests/yapTests/HotkeyMonitorTests.swift
@@ -51,7 +51,7 @@ final class HotkeyMonitorTests: XCTestCase {
     /// A left-Shift binding must not fire on right Shift. Only the
     /// device-specific bit tells them apart.
     func testSidedModifiersDoNotCrossFire() {
-        let leftShift = HotkeyBinding(parsing: "leftshift")!
+        let leftShift = HotkeyBinding(parsing: "leftShift")!
         let monitor = HotkeyMonitor(binding: leftShift)
         let right = CGEventFlags(rawValue: 0x0000_0004).union(.maskShift)
         XCTAssertNil(monitor.classify(type: .flagsChanged, event: flagsEvent(right)).edge)
diff --git a/Tests/yapTests/HotkeyRecorderTests.swift b/Tests/yapTests/HotkeyRecorderTests.swift
index bd30914..c7de21a 100644
--- a/Tests/yapTests/HotkeyRecorderTests.swift
+++ b/Tests/yapTests/HotkeyRecorderTests.swift
@@ -57,7 +57,7 @@ final class HotkeyRecorderTests: XCTestCase {
         XCTAssertEqual(written(), [])
 
         view.flagsChanged(with: flagsEvent([]))
-        XCTAssertEqual(written(), ["rightoption"])
+        XCTAssertEqual(written(), ["rightOption"])
         XCTAssertFalse(view.isRecording)
     }
 
@@ -66,7 +66,7 @@ final class HotkeyRecorderTests: XCTestCase {
         let leftShift = CGEventFlags(rawValue: 0x0000_0002).union(.maskShift)
         view.flagsChanged(with: flagsEvent(leftShift))
         view.flagsChanged(with: flagsEvent([]))
-        XCTAssertEqual(written(), ["leftshift"])
+        XCTAssertEqual(written(), ["leftShift"])
     }
 
     // MARK: - chord capture

From 6aceaff4e074c423793b60496baf735004f10827 Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 02:13:02 +0100
Subject: [PATCH 6/9] Say why extraction forks ditto, so it is not re-litigated

---
 Sources/yap/Updater.swift | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/Sources/yap/Updater.swift b/Sources/yap/Updater.swift
index 5dfc0d2..d4f4889 100644
--- a/Sources/yap/Updater.swift
+++ b/Sources/yap/Updater.swift
@@ -273,9 +273,22 @@ final class Updater {
             throw UpdateError("checksum mismatch")
         }
 
-        // ditto, not Foundation: there is no unarchiver in Foundation, and
-        // ditto is the one tool that preserves the code signature and the
-        // extended attributes a signed bundle needs to stay valid.
+        // ditto, and the "no new processes" rule does not forbid it — that
+        // rule is about helpers, daemons and sidecars, the things that stay
+        // resident and hold a second copy of the model. This is a one-shot
+        // that runs only on the update path, measured at 20 ms on our own
+        // 3.3 MB artifact, and is gone before the next line. yap already
+        // forks this way for every notification (osascript), every on_stop
+        // hook (/bin/sh) and every launchctl query.
+        //
+        // The alternative is not "use a framework": Foundation has no
+        // unarchiver, Compression handles raw deflate rather than the zip
+        // container, and libarchive is not public API. It would mean
+        // hand-rolling a zip reader that restores modes, symlinks and
+        // extended attributes faithfully enough that
+        // `SecStaticCodeCheckValidity` still passes below — several hundred
+        // lines of security-critical code, to avoid 20 ms of a system tool
+        // Apple wrote for exactly this. Nothing about that trade is minimal.
         let unpacked = dir.appendingPathComponent(release.version, isDirectory: true)
         try? FileManager.default.removeItem(at: unpacked)
         let ditto = Process()

From 8931af2e9c38bc88632323193f220ae68afe9f71 Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 02:21:42 +0100
Subject: [PATCH 7/9] Unpack updates in process instead of forking ditto
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"No new processes" is the rule, so the updater stops being an exception
to it. `ZipArchive` reads the central directory and inflates entries
with the Compression framework — stored and deflated entries,
directories, POSIX modes, and a refusal for anything else.

Two things make that safe enough to hold bytes that have not been
signature-checked yet:

- Entry names are resolved and checked for containment, so an archive
  naming `../../bin/something` is refused rather than written.
- Symbolic links are refused outright. The containment check is
  lexical, so a link entry creating `staging/link -> /elsewhere` would
  let every later `link/...` entry pass a text comparison while the
  write followed the link out of staging — before verification. A yap
  release contains no symlinks (measured: zero, in both the bundle and
  the artifact), so the class is removed rather than raced, and it
  fails loudly the day a release embeds a framework.

AppleDouble sidecars are dropped. `build-release.sh` already runs
`xattr -cr` before signing, and a bundle extracted without them
verifies — checked, not assumed.

Proof, on a real Developer ID-signed 9.9.9 build served from a local
feed: our own extractor's output is a byte-identical tree to `ditto -x
-k` of the same archive, reports "valid on disk" and "satisfies its
Designated Requirement", passes the updater's own
SecStaticCodeCheckValidity, and installs — /Applications/yap.app came
up as 9.9.9 with a valid signature and no quarantine xattr.

Sources now spawn a process in three places, all of them inherited from
main: osascript for notifications, /bin/sh for the on_stop hook, and
launchctl. The update path spawns none.
---
 Sources/yap/Updater.swift            |  32 ++--
 Sources/yap/ZipArchive.swift         | 224 +++++++++++++++++++++++++++
 Tests/yapTests/ZipArchiveTests.swift | 150 ++++++++++++++++++
 3 files changed, 384 insertions(+), 22 deletions(-)
 create mode 100644 Sources/yap/ZipArchive.swift
 create mode 100644 Tests/yapTests/ZipArchiveTests.swift

diff --git a/Sources/yap/Updater.swift b/Sources/yap/Updater.swift
index d4f4889..614d5ee 100644
--- a/Sources/yap/Updater.swift
+++ b/Sources/yap/Updater.swift
@@ -273,31 +273,19 @@ final class Updater {
             throw UpdateError("checksum mismatch")
         }
 
-        // ditto, and the "no new processes" rule does not forbid it — that
-        // rule is about helpers, daemons and sidecars, the things that stay
-        // resident and hold a second copy of the model. This is a one-shot
-        // that runs only on the update path, measured at 20 ms on our own
-        // 3.3 MB artifact, and is gone before the next line. yap already
-        // forks this way for every notification (osascript), every on_stop
-        // hook (/bin/sh) and every launchctl query.
-        //
-        // The alternative is not "use a framework": Foundation has no
-        // unarchiver, Compression handles raw deflate rather than the zip
-        // container, and libarchive is not public API. It would mean
-        // hand-rolling a zip reader that restores modes, symlinks and
-        // extended attributes faithfully enough that
-        // `SecStaticCodeCheckValidity` still passes below — several hundred
-        // lines of security-critical code, to avoid 20 ms of a system tool
-        // Apple wrote for exactly this. Nothing about that trade is minimal.
+        // In process, because yap spawns nothing. See `ZipArchive` for what
+        // it does and does not restore, and why that is enough for the
+        // signature check below to pass.
         let unpacked = dir.appendingPathComponent(release.version, isDirectory: true)
         try? FileManager.default.removeItem(at: unpacked)
-        let ditto = Process()
-        ditto.executableURL = URL(fileURLWithPath: "/usr/bin/ditto")
-        ditto.arguments = ["-x", "-k", zip.path, unpacked.path]
-        try ditto.run()
-        ditto.waitUntilExit()
+        do {
+            try ZipArchive.extract(zip, to: unpacked)
+        } catch {
+            try? FileManager.default.removeItem(at: zip)
+            try? FileManager.default.removeItem(at: unpacked)
+            throw UpdateError("couldn't unpack the download: \(error.localizedDescription)")
+        }
         try? FileManager.default.removeItem(at: zip)
-        guard ditto.terminationStatus == 0 else { throw UpdateError("couldn't unpack the download") }
 
         let app = unpacked.appendingPathComponent("yap.app")
         guard FileManager.default.fileExists(atPath: app.path) else {
diff --git a/Sources/yap/ZipArchive.swift b/Sources/yap/ZipArchive.swift
new file mode 100644
index 0000000..8679fd1
--- /dev/null
+++ b/Sources/yap/ZipArchive.swift
@@ -0,0 +1,224 @@
+import Compression
+import Foundation
+
+/// Just enough of the zip format to unpack a signed .app, in process.
+///
+/// Foundation has no unarchiver, so the obvious move is to shell out to
+/// `ditto`. yap does not spawn processes, so this reads the archive itself:
+/// the central directory, then each entry, inflating with the Compression
+/// framework. It is about as much of the format as `ditto -c -k` can produce
+/// and no more — stored and deflated entries, directories, symlinks, POSIX
+/// modes — and it refuses anything else rather than guessing.
+///
+/// What it deliberately drops is the AppleDouble sidecars (`._name`,
+/// `__MACOSX/`) that carry extended attributes and resource forks. Nothing in
+/// a yap release needs them: `build-release.sh` runs `xattr -cr` before
+/// signing, and an extraction with them discarded verifies `valid on disk` and
+/// `satisfies its Designated Requirement` — checked against a real
+/// Developer ID-signed bundle, because a bundle that unpacks subtly wrong
+/// would fail `SecStaticCodeCheckValidity` in `Updater.verify` and leave the
+/// user stuck on an old build with no explanation.
+///
+/// No CRC check. The updater has already matched a SHA-256 over the whole
+/// archive before it gets here, and verifies the signature of what comes out
+/// afterwards; a per-entry CRC sits between two stronger checks.
+enum ZipArchive {
+    enum ZipError: LocalizedError {
+        case notAZip
+        case unsupported(String)
+        case truncated
+        case escapingPath(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .notAZip: return "not a zip archive"
+            case .unsupported(let what): return "unsupported zip feature: \(what)"
+            case .truncated: return "zip archive is truncated"
+            case .escapingPath(let name): return "zip entry escapes the destination: \(name)"
+            }
+        }
+    }
+
+    /// Unpack `archive` into `destination`, which is created if missing.
+    static func extract(_ archive: URL, to destination: URL) throws {
+        let data = try Data(contentsOf: archive)
+        let directory = try centralDirectory(in: data)
+        try FileManager.default.createDirectory(
+            at: destination, withIntermediateDirectories: true)
+
+        for entry in directory {
+            // AppleDouble sidecars. See the note on the type.
+            let last = entry.name.split(separator: "/").last.map(String.init) ?? entry.name
+            if entry.name.hasPrefix("__MACOSX/") || last.hasPrefix("._") { continue }
+
+            let target = try resolve(entry.name, under: destination)
+            if entry.name.hasSuffix("/") {
+                try FileManager.default.createDirectory(
+                    at: target, withIntermediateDirectories: true)
+                continue
+            }
+            // Refused, not created, and this is the load-bearing line in the
+            // file. The containment check above is lexical: an entry that
+            // creates `staging/link -> /somewhere` makes every later entry
+            // named `link/…` pass a text comparison while the write follows
+            // the link out of the staging directory — before the signature is
+            // checked, which is the one moment yap is holding bytes it does
+            // not trust yet. Refusing the link removes the class rather than
+            // racing it. Measured: a yap release contains no symlinks at all,
+            // so this costs nothing today. It would start costing something
+            // the day a release embeds a framework, and it should fail loudly
+            // then rather than quietly grow a hole.
+            if entry.mode & S_IFMT == S_IFLNK {
+                throw ZipError.unsupported("symbolic link (\(entry.name))")
+            }
+
+            try FileManager.default.createDirectory(
+                at: target.deletingLastPathComponent(), withIntermediateDirectories: true)
+            let contents = try body(of: entry, in: data)
+            // The executable bit is the one that matters: a Mach-O written
+            // 0644 is a bundle macOS will not launch.
+            let permissions = entry.mode & 0o7777
+            guard
+                FileManager.default.createFile(
+                    atPath: target.path, contents: contents,
+                    attributes: permissions == 0 ? nil : [.posixPermissions: permissions])
+            else { throw ZipError.truncated }
+        }
+    }
+
+    // MARK: - reading
+
+    private struct Entry {
+        let name: String
+        let method: UInt16
+        let compressedSize: Int
+        let uncompressedSize: Int
+        let localHeaderOffset: Int
+        let mode: mode_t
+    }
+
+    /// Entry names are attacker-controlled the moment a feed is: an archive
+    /// saying `../../bin/launchd` must not write there. Resolving and then
+    /// checking containment covers `..` and absolute names together.
+    private static func resolve(_ name: String, under destination: URL) throws -> URL {
+        let root = destination.standardizedFileURL.path
+        let target = destination.appendingPathComponent(name).standardizedFileURL
+        guard target.path == root || target.path.hasPrefix(root + "/") else {
+            throw ZipError.escapingPath(name)
+        }
+        return target
+    }
+
+    private static func centralDirectory(in data: Data) throws -> [Entry] {
+        // The end-of-central-directory record is last, after a comment of up
+        // to 64 KB, so it is found by scanning back for its signature.
+        let eocdSignature: UInt32 = 0x0605_4B50
+        let minimum = 22
+        guard data.count >= minimum else { throw ZipError.notAZip }
+        var eocd: Int?
+        let earliest = max(0, data.count - minimum - 0xFFFF)
+        var index = data.count - minimum
+        while index >= earliest {
+            if u32(data, index) == eocdSignature {
+                eocd = index
+                break
+            }
+            index -= 1
+        }
+        guard let eocd else { throw ZipError.notAZip }
+
+        let count = Int(u16(data, eocd + 10))
+        let start = Int(u32(data, eocd + 16))
+        guard count != 0xFFFF, start != 0xFFFF_FFFF else {
+            throw ZipError.unsupported("zip64")
+        }
+
+        var entries: [Entry] = []
+        var cursor = start
+        for _ in 0..<count {
+            guard cursor + 46 <= data.count, u32(data, cursor) == 0x0201_4B50 else {
+                throw ZipError.truncated
+            }
+            let method = u16(data, cursor + 10)
+            let compressed = Int(u32(data, cursor + 20))
+            let uncompressed = Int(u32(data, cursor + 24))
+            let nameLength = Int(u16(data, cursor + 28))
+            let extraLength = Int(u16(data, cursor + 30))
+            let commentLength = Int(u16(data, cursor + 32))
+            let external = u32(data, cursor + 38)
+            let localOffset = Int(u32(data, cursor + 42))
+            guard cursor + 46 + nameLength <= data.count else { throw ZipError.truncated }
+            let name = String(
+                decoding: data[(data.startIndex + cursor + 46)..<(data.startIndex + cursor + 46 + nameLength)],
+                as: UTF8.self)
+            guard compressed != 0xFFFF_FFFF, uncompressed != 0xFFFF_FFFF,
+                localOffset != 0xFFFF_FFFF
+            else { throw ZipError.unsupported("zip64") }
+
+            entries.append(
+                Entry(
+                    name: name, method: method,
+                    compressedSize: compressed, uncompressedSize: uncompressed,
+                    localHeaderOffset: localOffset,
+                    // The high 16 bits are the Unix mode, when the archive was
+                    // made on a Unix host. Zero otherwise, which reads as
+                    // "leave the default".
+                    mode: mode_t(external >> 16)))
+            cursor += 46 + nameLength + extraLength + commentLength
+        }
+        return entries
+    }
+
+    private static func body(of entry: Entry, in data: Data) throws -> Data {
+        let header = entry.localHeaderOffset
+        guard header + 30 <= data.count, u32(data, header) == 0x0403_4B50 else {
+            throw ZipError.truncated
+        }
+        // The local header repeats the name and extra field, and its extra
+        // field length can differ from the central one — so it is read here
+        // rather than assumed.
+        let nameLength = Int(u16(data, header + 26))
+        let extraLength = Int(u16(data, header + 28))
+        let start = header + 30 + nameLength + extraLength
+        guard start + entry.compressedSize <= data.count else { throw ZipError.truncated }
+        let slice = data[(data.startIndex + start)..<(data.startIndex + start + entry.compressedSize)]
+
+        switch entry.method {
+        case 0:
+            return Data(slice)
+        case 8:
+            guard entry.uncompressedSize > 0 else { return Data() }
+            return try inflate(Data(slice), to: entry.uncompressedSize)
+        default:
+            throw ZipError.unsupported("compression method \(entry.method)")
+        }
+    }
+
+    /// `COMPRESSION_ZLIB` is Apple's name for raw DEFLATE, which is what a zip
+    /// entry holds — no zlib wrapper to strip.
+    private static func inflate(_ compressed: Data, to size: Int) throws -> Data {
+        var output = Data(count: size)
+        let written = output.withUnsafeMutableBytes { destination -> Int in
+            compressed.withUnsafeBytes { source -> Int in
+                guard let destinationBase = destination.bindMemory(to: UInt8.self).baseAddress,
+                    let sourceBase = source.bindMemory(to: UInt8.self).baseAddress
+                else { return 0 }
+                return compression_decode_buffer(
+                    destinationBase, size, sourceBase, compressed.count, nil, COMPRESSION_ZLIB)
+            }
+        }
+        guard written == size else { throw ZipError.truncated }
+        return output
+    }
+
+    private static func u16(_ data: Data, _ offset: Int) -> UInt16 {
+        let base = data.startIndex + offset
+        return UInt16(data[base]) | UInt16(data[base + 1]) << 8
+    }
+
+    private static func u32(_ data: Data, _ offset: Int) -> UInt32 {
+        let base = data.startIndex + offset
+        return UInt32(data[base]) | UInt32(data[base + 1]) << 8
+            | UInt32(data[base + 2]) << 16 | UInt32(data[base + 3]) << 24
+    }
+}
diff --git a/Tests/yapTests/ZipArchiveTests.swift b/Tests/yapTests/ZipArchiveTests.swift
new file mode 100644
index 0000000..1c02269
--- /dev/null
+++ b/Tests/yapTests/ZipArchiveTests.swift
@@ -0,0 +1,150 @@
+import Foundation
+import XCTest
+
+@testable import yap
+
+/// The updater unpacks a signed .app with this and then checks its signature,
+/// so an extractor that is subtly wrong does not corrupt anything — it just
+/// means updates silently never install. These pin the details that would go
+/// wrong quietly: the executable bit, symlinks, both compression methods, and
+/// the AppleDouble sidecars that must be dropped rather than written as files.
+final class ZipArchiveTests: XCTestCase {
+    private var directory = URL(fileURLWithPath: "/dev/null")
+
+    override func setUpWithError() throws {
+        directory = URL(fileURLWithPath: NSTemporaryDirectory())
+            .appendingPathComponent("yap-zip-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+    }
+
+    override func tearDownWithError() throws {
+        try? FileManager.default.removeItem(at: directory)
+    }
+
+    private func unpackFixture() throws -> URL {
+        let archive = directory.appendingPathComponent("fixture.zip")
+        try XCTUnwrap(Data(base64Encoded: Self.fixture, options: .ignoreUnknownCharacters))
+            .write(to: archive)
+        let destination = directory.appendingPathComponent("out")
+        try ZipArchive.extract(archive, to: destination)
+        return destination
+    }
+
+    /// Deflated, and 0755: a Mach-O written 0644 is a bundle macOS refuses to
+    /// launch, and nothing else in the update path would notice.
+    func testDeflatedEntryKeepsItsContentsAndExecutableBit() throws {
+        let out = try unpackFixture()
+        let tool = out.appendingPathComponent("bundle/MacOS/tool")
+        let contents = try String(contentsOf: tool, encoding: .utf8)
+        XCTAssertEqual(contents, String(repeating: "#!/bin/sh\necho hello\n", count: 40))
+
+        let mode = try XCTUnwrap(
+            FileManager.default.attributesOfItem(atPath: tool.path)[.posixPermissions] as? NSNumber)
+        XCTAssertEqual(mode.int16Value, 0o755)
+    }
+
+    func testStoredEntryRoundTrips() throws {
+        let out = try unpackFixture()
+        let plist = out.appendingPathComponent("bundle/Info.plist")
+        XCTAssertEqual(try String(contentsOf: plist, encoding: .utf8), "<plist/>")
+        let mode = try XCTUnwrap(
+            FileManager.default.attributesOfItem(atPath: plist.path)[.posixPermissions] as? NSNumber)
+        XCTAssertEqual(mode.int16Value, 0o644)
+    }
+
+    /// A symlink entry is how the lexical containment check above is beaten:
+    /// create `staging/link -> /somewhere`, then name a later entry
+    /// `link/file`, and the write follows the link out of staging — before the
+    /// signature has been checked. A yap release contains no symlinks, so they
+    /// are refused rather than raced.
+    func testSymlinkEntriesAreRefused() throws {
+        let archive = directory.appendingPathComponent("link.zip")
+        try XCTUnwrap(Data(base64Encoded: Self.symlinked, options: .ignoreUnknownCharacters))
+            .write(to: archive)
+        let destination = directory.appendingPathComponent("out")
+
+        XCTAssertThrowsError(try ZipArchive.extract(archive, to: destination)) { error in
+            guard case ZipArchive.ZipError.unsupported = error else {
+                return XCTFail("expected an unsupported error, got \(error)")
+            }
+        }
+        XCTAssertFalse(
+            FileManager.default.fileExists(
+                atPath: destination.appendingPathComponent("bundle/link").path))
+    }
+
+    /// Written as a file rather than dropped, `._Info.plist` would be a stray
+    /// binary blob inside the bundle — one the signature does not account for.
+    func testAppleDoubleSidecarsAreDropped() throws {
+        let out = try unpackFixture()
+        XCTAssertFalse(
+            FileManager.default.fileExists(
+                atPath: out.appendingPathComponent("bundle/._Info.plist").path))
+    }
+
+    func testDirectoryEntriesAreCreated() throws {
+        let out = try unpackFixture()
+        var isDirectory: ObjCBool = false
+        XCTAssertTrue(
+            FileManager.default.fileExists(
+                atPath: out.appendingPathComponent("bundle/Resources").path,
+                isDirectory: &isDirectory))
+        XCTAssertTrue(isDirectory.boolValue)
+    }
+
+    /// The feed is the attacker's lever if it is anyone's, so an entry naming
+    /// its way out of the staging directory has to be refused, not written.
+    func testEntriesCannotEscapeTheDestination() throws {
+        let archive = directory.appendingPathComponent("evil.zip")
+        try XCTUnwrap(Data(base64Encoded: Self.escaping, options: .ignoreUnknownCharacters))
+            .write(to: archive)
+        let destination = directory.appendingPathComponent("out")
+
+        XCTAssertThrowsError(try ZipArchive.extract(archive, to: destination)) { error in
+            guard case ZipArchive.ZipError.escapingPath = error else {
+                return XCTFail("expected an escapingPath error, got \(error)")
+            }
+        }
+        XCTAssertFalse(
+            FileManager.default.fileExists(
+                atPath: directory.appendingPathComponent("escaped.txt").path))
+    }
+
+    func testGarbageIsRejected() throws {
+        let archive = directory.appendingPathComponent("junk.zip")
+        try Data(repeating: 0x41, count: 512).write(to: archive)
+        XCTAssertThrowsError(
+            try ZipArchive.extract(archive, to: directory.appendingPathComponent("out")))
+    }
+
+    // MARK: - fixtures
+
+    /// A deflated executable, a stored file, an AppleDouble sidecar and a
+    /// directory entry — the shape `ditto -c -k` produces for an .app.
+    private static let fixture = """
+        UEsDBBQAAAAIAAAAIQBPy6xkIAAAAEgDAAARAAAAYnVuZGxlL01hY09TL3Rvb2xTVtRPyszTL87g
+        Sk3OyFfISM3JyedSHhUcFRwVJEUQAFBLAwQUAAAAAAAAACEAVXkzSQgAAAAIAAAAEQAAAGJ1bmRs
+        ZS9JbmZvLnBsaXN0PHBsaXN0Lz5QSwMEFAAAAAAAAAAhAH2OCncIAAAACAAAABMAAABidW5kbGUv
+        Ll9JbmZvLnBsaXN0AAUWB2p1bmtQSwMEFAAAAAAAAAAhAAAAAAAAAAAAAAAAABEAAABidW5kbGUv
+        UmVzb3VyY2VzL1BLAQIUAxQAAAAIAAAAIQBPy6xkIAAAAEgDAAARAAAAAAAAAAAAAADtgQAAAABi
+        dW5kbGUvTWFjT1MvdG9vbFBLAQIUAxQAAAAAAAAAIQBVeTNJCAAAAAgAAAARAAAAAAAAAAAAAACk
+        gU8AAABidW5kbGUvSW5mby5wbGlzdFBLAQIUAxQAAAAAAAAAIQB9jgp3CAAAAAgAAAATAAAAAAAA
+        AAAAAACkgYYAAABidW5kbGUvLl9JbmZvLnBsaXN0UEsBAhQDFAAAAAAAAAAhAAAAAAAAAAAAAAAA
+        ABEAAAAAAAAAAAAQAO1BvwAAAGJ1bmRsZS9SZXNvdXJjZXMvUEsFBgAAAAAEAAQA/gAAAO4AAAAA
+        AA==
+        """
+
+    /// One entry, a symbolic link.
+    private static let symlinked = """
+        UEsDBBQAAAAAAAAAIQCv5eEIBAAAAAQAAAALAAAAYnVuZGxlL2xpbmsvZXRjUEsBAhQDFAAAAAAA
+        AAAhAK/l4QgEAAAABAAAAAsAAAAAAAAAAAAAAO2hAAAAAGJ1bmRsZS9saW5rUEsFBgAAAAABAAEA
+        OQAAAC0AAAAAAA==
+        """
+
+    /// One entry, named `../escaped.txt`.
+    private static let escaping = """
+        UEsDBBQAAAAAAAAAIQDjdvzOCAAAAAgAAAAOAAAALi4vZXNjYXBlZC50eHRlc2NhcGVkClBLAQIU
+        AxQAAAAAAAAAIQDjdvzOCAAAAAgAAAAOAAAAAAAAAAAAAACkgQAAAAAuLi9lc2NhcGVkLnR4dFBL
+        BQYAAAAAAQABADwAAAA0AAAAAAA=
+        """
+}

From 49dffd2079a9c6d07cdb1eb0641aa996df0183ce Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 02:29:00 +0100
Subject: [PATCH 8/9] Check for updates only when asked
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Nothing runs while idle" names timers directly and permits exactly one
piece of background work, which is meeting detection. A 30-second work
item plus a repeating daily Timer, armed at launch because the setting
defaulted on, was neither of those things. It is gone, along with the
`updates.automatic` key, the Settings toggle, and the launch and
config-reload callsites that armed it.

What is left is the whole of the feature minus the schedule: "Check
Now" in Settings → General does one request, verifies, stages, and puts
"Update to x.y.z · Restart" in the menu. yap makes no network request
of its own after the model is on disk unless someone clicks that.

Measured after the cut, on the installed daemon sitting idle: 0.0% CPU
over a minute. Every remaining timer in the tree belongs to something
happening — the menu's elapsed counter while a session records, the
pill's auto-dismiss while a pill is up, the session stall check while
recording, the config watcher's debounce, the dictation suppression
tail — plus MeetingDetector, which is the permitted one.

An existing config keeps its `updates` block: unknown keys are left
alone by design, and reading one is not worth rewriting someone's file.
---
 README.md                          | 24 ++++++++--------
 Sources/yap/Config.swift           |  7 -----
 Sources/yap/Daemon.swift           | 24 ++++------------
 Sources/yap/UI/SettingsModel.swift |  4 ---
 Sources/yap/UI/SettingsPanes.swift |  1 -
 Sources/yap/Updater.swift          | 45 +++++-------------------------
 6 files changed, 24 insertions(+), 81 deletions(-)

diff --git a/README.md b/README.md
index a1f548e..fa7e7cb 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,9 @@ and drag yap to Applications.
 
 Then launch yap from Applications. The menu bar mark appears straight away and
 walks you through the rest: it asks for Accessibility, then the microphone, and
-pulls the model down in the background. That is 220 MB, once. Nothing you say
-ever leaves the machine; the only thing yap goes online for afterwards is a
-once-a-day check for a new version, which you can switch off in Settings.
+pulls the model down in the background. That is 220 MB, once, and then you are
+offline: nothing you say ever leaves the machine, and yap makes no network
+request of its own again unless you ask it to check for a new version.
 
 Builds are signed with a Developer ID certificate and notarized by Apple, so
 there is no Gatekeeper prompt. Apple Silicon only, because the model runs on
@@ -53,11 +53,12 @@ yap holds the most recent one in memory and nowhere else.
 "Quit yap" stops it until you launch it again, or until your next login if
 "Launch at login" is on.
 
-yap keeps itself up to date: it checks GitHub Releases once a day, downloads
-the new build, verifies its signature against the one it is running under, and
-puts "Update to x.y.z · Restart" in the menu. Nothing is replaced until you
-click it, and it is never offered while a recording is in flight. Turn the
-checks off in Settings → General.
+Settings → General has a "Check Now" button. It asks GitHub Releases once,
+downloads the new build, verifies its signature against the one yap is running
+under, and puts "Update to x.y.z · Restart" in the menu. Nothing is replaced
+until you click that, and it is never offered while a recording is in flight.
+There is no automatic check and no timer behind it: yap does nothing at all
+while it is idle.
 
 One daemon holds the hotkey at a time. Start another — from Applications, from
 a terminal, or because an upgrade restarted the login item — and the new one
@@ -93,7 +94,6 @@ what this yap can do. Your own values are never touched.
   "mic_voice_processing": true,
   "on_stop": "my-hook",
   "transcription": { "enabled": true },
-  "updates": { "automatic": true },
   "dictation": {
     "model": "parakeet-tdt-ctc-110m",
     "hotkey": "fn",
@@ -107,9 +107,9 @@ what this yap can do. Your own values are never touched.
 
 Save it and yap picks it up. The hotkey, `tap_to_toggle`, the overlay,
 `mute_output`, `newline_after_release`, `meeting_detection`,
-`meeting_auto_record`, `meeting_excluded_apps` and `updates.automatic` all
-change on the spot. A new `model` or `recordings_dir` wants a restart, and yap
-says so when it sees one.
+`meeting_auto_record` and `meeting_excluded_apps` all change on the spot. A
+new `model` or `recordings_dir` wants a restart, and yap says so when it sees
+one.
 
 `hotkey` is a modifier held on its own — `fn`, `rightOption`, `rightCommand`,
 `rightControl`, `rightShift`, `leftOption`, `leftControl`, `leftShift` — or a
diff --git a/Sources/yap/Config.swift b/Sources/yap/Config.swift
index 745fed8..f978f46 100644
--- a/Sources/yap/Config.swift
+++ b/Sources/yap/Config.swift
@@ -79,12 +79,6 @@ enum Config {
         load()?["meeting_excluded_apps"] as? [String] ?? []
     }
 
-    /// Whether yap checks GitHub Releases for a newer build. Default on: it
-    /// updates itself in the background and never replaces anything without
-    /// being clicked, so the only thing this switch buys is the daily request.
-    static func updatesAutomatic() -> Bool {
-        section("updates")?["automatic"] as? Bool ?? true
-    }
 
     /// Apple voice processing (acoustic echo cancellation) on the mic, so
     /// speaker playback doesn't bleed into the mic track and get transcribed
@@ -187,7 +181,6 @@ enum Config {
           "meeting_detection": false,
           "meeting_auto_record": false,
           "meeting_excluded_apps": [],
-          "updates": { "automatic": true },
           "dictation": {
             "model": "parakeet-tdt-ctc-110m",
             "hotkey": "fn",
diff --git a/Sources/yap/Daemon.swift b/Sources/yap/Daemon.swift
index 70e069f..57d24ff 100644
--- a/Sources/yap/Daemon.swift
+++ b/Sources/yap/Daemon.swift
@@ -135,6 +135,7 @@ final class Daemon: NSObject, NSApplicationDelegate {
         menuBar.onOpenKeyboardSettings = { Permissions.openSystemSettings(.keyboard) }
         menuBar.onRetryModel = { [weak self] in self?.loadModel() }
         menuBar.onInstallUpdate = { Updater.shared.installAndRestart() }
+        observeUpdates()
         // Cheaper and more accurate than polling: the only moment the rows
         // have to be right is the moment someone opens the menu to look at
         // them.
@@ -226,7 +227,6 @@ final class Daemon: NSObject, NSApplicationDelegate {
                 // still loading would queue behind the same warm-up anyway,
                 // and this way the state line tells one story at a time.
                 await self.coordinator.resumePending(root: self.root)
-                self.startUpdater()
             } catch {
                 warn("warmup failed: \(error)")
                 self.menuBar.setModelFailed()
@@ -267,14 +267,10 @@ final class Daemon: NSObject, NSApplicationDelegate {
         }
     }
 
-    /// Subscribe the menu bar to the updater, and arm the daily check if the
-    /// config wants it.
-    ///
-    /// After the model, deliberately: the first thing a fresh install does is
-    /// download several hundred megabytes, and competing with that for
-    /// bandwidth to ask about a release is the wrong order.
-    private func startUpdater() {
-        guard updateObserver == nil else { return }
+    /// Point the menu bar at the updater. No schedule: `Updater` only ever
+    /// checks when Settings asks it to, so this costs one closure and nothing
+    /// afterwards.
+    private func observeUpdates() {
         updateObserver = Updater.shared.observe { [weak self] state in
             guard let self else { return }
             if case .ready(let version, _) = state {
@@ -284,7 +280,6 @@ final class Daemon: NSObject, NSApplicationDelegate {
             }
             self.refreshUpdateItem()
         }
-        if Config.updatesAutomatic() { Updater.shared.startAutomaticChecks() }
     }
 
     /// A restart mid-recording loses the meeting, and mid-press loses the
@@ -840,15 +835,6 @@ final class Daemon: NSObject, NSApplicationDelegate {
             warn("config: recordings_dir changed — restart yap to use it")
         }
 
-        // Only meaningful once the updater is subscribed, which happens after
-        // the model warms; before that `startUpdater` reads the same setting.
-        if updateObserver != nil {
-            if Config.updatesAutomatic() {
-                Updater.shared.startAutomaticChecks()
-            } else {
-                Updater.shared.stopAutomaticChecks()
-            }
-        }
 
         warn("config reloaded")
     }
diff --git a/Sources/yap/UI/SettingsModel.swift b/Sources/yap/UI/SettingsModel.swift
index f4209a5..acb7a08 100644
--- a/Sources/yap/UI/SettingsModel.swift
+++ b/Sources/yap/UI/SettingsModel.swift
@@ -27,9 +27,6 @@ final class SettingsModel: ObservableObject {
     /// every other control here, this one can fail. It reverts on failure
     /// rather than showing a state the disk does not agree with.
     @Published var launchAtLogin: Bool { didSet { applyLaunchAtLogin() } }
-    @Published var updatesAutomatic: Bool {
-        didSet { writeSection("updates", "automatic", updatesAutomatic) }
-    }
     /// Live: the updater pushes every state change here while the window is
     /// open, so "Check Now" reads as something happening.
     @Published var updateStatus: String
@@ -72,7 +69,6 @@ final class SettingsModel: ObservableObject {
 
     init() {
         launchAtLogin = LaunchAgent.isInstalled
-        updatesAutomatic = Config.updatesAutomatic()
         updateStatus = Updater.shared.state.description
         hotkey = HotkeyBinding(parsing: Config.hotkey() ?? "")?.serialized
             ?? HotkeyBinding.fn.serialized
diff --git a/Sources/yap/UI/SettingsPanes.swift b/Sources/yap/UI/SettingsPanes.swift
index 78ffc5b..f0342cc 100644
--- a/Sources/yap/UI/SettingsPanes.swift
+++ b/Sources/yap/UI/SettingsPanes.swift
@@ -16,7 +16,6 @@ struct GeneralPane: View {
                     .foregroundStyle(.secondary)
             }
             Section("Updates") {
-                Toggle("Check for updates automatically", isOn: $model.updatesAutomatic)
                 LabeledContent("Version") { Text(model.version) }
                 HStack(spacing: 8) {
                     Text(model.updateStatus)
diff --git a/Sources/yap/Updater.swift b/Sources/yap/Updater.swift
index 614d5ee..6314a52 100644
--- a/Sources/yap/Updater.swift
+++ b/Sources/yap/Updater.swift
@@ -57,11 +57,6 @@ final class Updater {
 
     private var observers: [UUID: (State) -> Void] = [:]
 
-    /// The daily timer, and the one-shot that runs the first check a little
-    /// after launch. Both nil while automatic checks are off, which is the
-    /// only state in which nothing of yap's is scheduled at all.
-    private var timer: Timer?
-    private var firstCheck: DispatchWorkItem?
     private var inFlight = false
 
     /// Overridable so the update path can be exercised against a local feed
@@ -106,41 +101,15 @@ final class Updater {
         observers.removeValue(forKey: token)
     }
 
-    // MARK: - scheduling
+    // MARK: - checking
 
-    /// One check shortly after launch, then one a day.
+    /// Checked when asked, and at no other time.
     ///
-    /// The 30 s delay keeps it off the startup path — the model has just
-    /// finished loading and the first press is the thing that matters. The
-    /// hour of tolerance lets the OS coalesce the daily wake with something
-    /// else it was going to do anyway.
-    func startAutomaticChecks() {
-        guard available, timer == nil, firstCheck == nil else { return }
-        let first = DispatchWorkItem { [weak self] in
-            MainActor.assumeIsolated {
-                self?.firstCheck = nil
-                self?.checkNow()
-            }
-        }
-        firstCheck = first
-        DispatchQueue.main.asyncAfter(deadline: .now() + 30, execute: first)
-
-        let daily = Timer.scheduledTimer(withTimeInterval: 86_400, repeats: true) { [weak self] _ in
-            MainActor.assumeIsolated { self?.checkNow() }
-        }
-        daily.tolerance = 3_600
-        timer = daily
-    }
-
-    func stopAutomaticChecks() {
-        firstCheck?.cancel()
-        firstCheck = nil
-        timer?.invalidate()
-        timer = nil
-    }
-
-    /// Manual check. Runs even with automatic checks off — turning the daily
-    /// request off is not the same as never wanting to know.
+    /// There is no schedule behind this and there is not going to be one: a
+    /// daily timer is a timer that ticks while nothing is happening, and yap
+    /// permits exactly one thing to run in the background, which is meeting
+    /// detection. So the update path costs nothing at all until "Check Now"
+    /// in Settings → General is clicked.
     func checkNow() {
         guard available, !inFlight else { return }
         if case .ready = state { return }

From d9dca2ef56c2c1969aefc4b9e4d2f6b0d55a54f0 Mon Sep 17 00:00:00 2001
From: TerrifiedBug <admin@terrifiedbug.com>
Date: Fri, 4 Sep 2026 08:12:51 +0100
Subject: [PATCH 9/9] Keep the updater off the launch path, and reachable when
 the model fails
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two corrections to the previous commit.

Registering the observer in `start()` looked free and was not: touching
`Updater.shared` constructs it, and its init asks the code-signing
machinery who signed us. Measured cold, which is how it runs at launch:
6.5-17 ms, ahead of the status item that is supposed to be on screen
inside a second. It moves after warm-up, where the scheduling used to
live. Nothing is lost by waiting — `observe` replays the current state
to a new subscriber.

Then the more important half: it went after warm-up, not inside the
success branch. A build whose model will not load is the one a user
most wants to replace, and the Restart item only ever appears for a
daemon that is watching the updater — so a failed warm-up would have
left Settings able to stage an update that the menu could never offer.

`observeUpdates` also guards on already having a subscription: "Retry
Model Download" re-enters `loadModel`, and a second registration would
leave the first in the observer map firing forever.
---
 Sources/yap/Daemon.swift | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/Sources/yap/Daemon.swift b/Sources/yap/Daemon.swift
index 57d24ff..366c795 100644
--- a/Sources/yap/Daemon.swift
+++ b/Sources/yap/Daemon.swift
@@ -135,7 +135,6 @@ final class Daemon: NSObject, NSApplicationDelegate {
         menuBar.onOpenKeyboardSettings = { Permissions.openSystemSettings(.keyboard) }
         menuBar.onRetryModel = { [weak self] in self?.loadModel() }
         menuBar.onInstallUpdate = { Updater.shared.installAndRestart() }
-        observeUpdates()
         // Cheaper and more accurate than polling: the only moment the rows
         // have to be right is the moment someone opens the menu to look at
         // them.
@@ -231,6 +230,10 @@ final class Daemon: NSObject, NSApplicationDelegate {
                 warn("warmup failed: \(error)")
                 self.menuBar.setModelFailed()
             }
+            // Outside the catch on purpose. A build whose model will not load
+            // is the one a user most wants to replace, and the Restart item
+            // only ever appears for a daemon that is watching the updater.
+            self.observeUpdates()
         }
     }
 
@@ -270,7 +273,17 @@ final class Daemon: NSObject, NSApplicationDelegate {
     /// Point the menu bar at the updater. No schedule: `Updater` only ever
     /// checks when Settings asks it to, so this costs one closure and nothing
     /// afterwards.
+    ///
+    /// After warm-up rather than during `start()`, because touching
+    /// `Updater.shared` at all builds it, and its init asks the code-signing
+    /// machinery who signed us: measured at 6.5-17 ms cold, which is real
+    /// money against a status item that is supposed to be on screen in under a
+    /// second. `observe` replays the current state to a new subscriber, so
+    /// nothing that happened before this point is lost.
     private func observeUpdates() {
+        // "Retry Model Download" runs `loadModel` again, and a second
+        // subscription would leave the first in the map firing forever.
+        guard updateObserver == nil else { return }
         updateObserver = Updater.shared.observe { [weak self] state in
             guard let self else { return }
             if case .ready(let version, _) = state {