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..18ef030 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
@@ -162,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
 
@@ -188,11 +211,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 +231,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..fa7e7cb 100644
--- a/README.md
+++ b/README.md
@@ -13,11 +13,16 @@ 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: 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
@@ -28,30 +33,32 @@ 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.
+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
@@ -62,26 +69,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
 {
@@ -105,8 +107,16 @@ 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` 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
+chord like `cmd+shift+space`, or a lone function key like `f5`. The recorder in
+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.
@@ -153,8 +163,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 +194,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..f978f46 100644
--- a/Sources/yap/Config.swift
+++ b/Sources/yap/Config.swift
@@ -79,6 +79,7 @@ enum Config {
         load()?["meeting_excluded_apps"] as? [String] ?? []
     }
 
+
     /// 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 +100,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 +162,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
diff --git a/Sources/yap/Daemon.swift b/Sources/yap/Daemon.swift
new file mode 100644
index 0000000..366c795
--- /dev/null
+++ b/Sources/yap/Daemon.swift
@@ -0,0 +1,864 @@
+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() }
+
+        // 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.
+    ///
+    /// 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(
+            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 }
+            await self.installCoordinatorHandlers()
+            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)
+            } catch {
+                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()
+        }
+    }
+
+    /// 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")]
+                    )
+                }
+            }
+        }
+    }
+
+    /// 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 {
+                self.stagedUpdate = version
+            } else {
+                self.stagedUpdate = nil
+            }
+            self.refreshUpdateItem()
+        }
+    }
+
+    /// 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) }
+
+        // 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.
+        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)
+            }
+        }
+
+        menuBar.setSetupNeeds(needs, fnAction: fnAction)
+    }
+
+    /// 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")
+        }
+
+
+        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..89844ce
--- /dev/null
+++ b/Sources/yap/Input/HotkeyBinding.swift
@@ -0,0 +1,252 @@
+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 a config file says.
+        if let mask = Self.modifierMask(named: 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.
+    ///
+    /// 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),
+    ]
+
+    /// 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 ⇧",
+    ]
+
+    /// 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..9dcab83
--- /dev/null
+++ b/Sources/yap/LaunchAgent.swift
@@ -0,0 +1,161 @@
+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.
+    ///
+    /// 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
+        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..d92ba80
--- /dev/null
+++ b/Sources/yap/UI/HotkeyRecorder.swift
@@ -0,0 +1,227 @@
+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.
+    /// 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 }
+    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..edfc36f 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,28 @@ 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)
+        /// 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
     /// config file can change the key while the daemon runs.
     private var hotkeyName: String
@@ -31,15 +58,21 @@ 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 tapItem: 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 +84,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 +95,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 +134,31 @@ 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))
+        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, tapItem, retryItem] {
+            item.isHidden = true
+            menu.addItem(item)
+        }
+
         toggleItem = NSMenuItem(
             title: "Start Recording",
             action: #selector(toggleClicked),
@@ -112,6 +181,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 +207,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, tapItem, retryItem, updateItem,
+        ] {
             item.target = self
         }
 
+        menu.delegate = self
         statusItem.menu = menu
 
         // Template image, never tinted. Colouring the icon while recording put
@@ -143,6 +226,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 +250,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 +338,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 +357,19 @@ final class MenuBarController {
                 systemSymbolName: "record.circle", accessibilityDescription: nil)
         }
 
+        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 {
+            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 +379,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 +403,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..8c6b8e2 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,10 +93,13 @@ 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?
     private let dismissAfter: TimeInterval
+    /// Whether a button has already been clicked. See `claimAnswer`.
+    private var answered = false
 
     static func present(
         title: String,
@@ -109,6 +116,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 +134,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 +154,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 +168,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 +183,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 +194,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 +235,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 +265,7 @@ final class PromptPanel: NSPanel {
         body: String?,
         button: String,
         secondaryButton: String?,
+        destructiveButton: String?,
         toast: Bool
     ) -> NSStackView {
         var textViews: [NSView] = [
@@ -286,6 +303,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(
@@ -409,20 +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, 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 {
@@ -431,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/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..acb7a08 100644
--- a/Sources/yap/UI/SettingsModel.swift
+++ b/Sources/yap/UI/SettingsModel.swift
@@ -23,6 +23,15 @@ 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() } }
+    /// 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 +62,16 @@ 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
+        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 +86,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 +142,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..f0342cc 100644
--- a/Sources/yap/UI/SettingsPanes.swift
+++ b/Sources/yap/UI/SettingsPanes.swift
@@ -3,21 +3,59 @@ 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") {
+                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..6314a52
--- /dev/null
+++ b/Sources/yap/Updater.swift
@@ -0,0 +1,375 @@
+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] = [:]
+
+    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: - checking
+
+    /// Checked when asked, and at no other time.
+    ///
+    /// 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 }
+        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")
+        }
+
+        // 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)
+        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)
+
+        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..d8c7508 100644
--- a/Sources/yap/Yap.swift
+++ b/Sources/yap/Yap.swift
@@ -12,11 +12,13 @@ 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
     )
 }
@@ -29,21 +31,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 +62,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 +106,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 +184,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 +208,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 +255,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 +278,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/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/HotkeyBindingTests.swift b/Tests/yapTests/HotkeyBindingTests.swift
new file mode 100644
index 0000000..f9d8bd3
--- /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)
+        }
+    }
+
+    /// 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: "RIGHT_SHIFT"), HotkeyBinding(parsing: "rightShift"))
+        XCTAssertEqual(HotkeyBinding(parsing: "right-control")?.serialized, "rightControl")
+        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..3f69e93
--- /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/Tests/yapTests/HotkeyRecorderTests.swift b/Tests/yapTests/HotkeyRecorderTests.swift
new file mode 100644
index 0000000..c7de21a
--- /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, [])
+    }
+}
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))
+        }
+    }
+}
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=
+        """
+}
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"