Build your own Wispr Flow.

# Build a fully local voice dictation menu bar app for macOS (replacing Wispr Flow)

You are building a macOS menu bar app for one person. It replaces Wispr Flow: hold a hotkey, talk, release, and cleaned-up text is inserted into whatever app has focus. Everything runs on the Mac. Speech to text is NVIDIA's Parakeet TDT 0.6B v3 running on CoreML through the FluidAudio Swift package. The cleanup pass uses Apple's on-device Foundation Model when it's available, Ollama on localhost when it isn't, and a rule-based cleaner when neither is. There are no API keys, no accounts, no Keychain, and no cloud calls. The only network request the app ever makes is a one-time model download on first run. It keeps a history with a raw vs cleaned toggle. Build it end to end. Latency, reliable insertion, and the privacy guarantee matter more than features.

## Stack

### Requirements

- An Apple Silicon Mac. Parakeet on CoreML uses the Neural Engine, and Intel Macs are too slow for the once-a-second interim pass.
- macOS 15 or newer. macOS 26 if you want the Apple Foundation Model as the cleaner; on macOS 15 the Ollama path is the default.
- Xcode from the App Store (free). CoreML, the CoreML compiler, and the macOS 26 SDK that has the Foundation Models framework all ship with it, and the Command Line Tools alone don't include them. You never have to open the Xcode GUI. Run `sudo xcode-select -s /Applications/Xcode.app` once, and everything after that is `swift build` from the terminal.
- Ollama (`brew install ollama`) is optional. It's only needed on macOS 15, or on macOS 26 with Apple Intelligence off.

A Python route exists for people who refuse to install Xcode (`parakeet-mlx` for speech, `rumps` for the menu bar, `pynput` for the hotkey), but inserting text into other apps is much less reliable from Python, and this prompt does not cover it.

### Why Swift instead of Electron

- Every hard part of this app is a native macOS API: the global hotkey event tap, the Accessibility API, microphone capture, the menu bar item, CoreML, and the Foundation Models framework.
- In Electron each of those needs a third-party native module (uiohook, robotjs or nut.js, a Node CoreML binding that doesn't really exist). Those modules are where builds break and where an agent gets stuck for hours.
- Swift Package Manager compiles from the terminal with `swift build` and runs tests with `swift test`.

Concretely:

- Swift 6.0 or newer, macOS 15 deployment target. Guard the Foundation Models code with `#available(macOS 26, *)` so one binary runs on both.
- SwiftUI for windows (Onboarding, Settings, History, Dictionary). AppKit for the status item (`NSStatusItem`), the overlay (`NSPanel`), and everything that touches the Accessibility API.
- One Swift package with three targets: `Flow` (executable, AppKit allowed), `FlowCore` (library, all logic, no AppKit imports), `FlowCoreTests`.
- Dependencies: `GRDB.swift` for SQLite and `FluidAudio` (`https://github.com/FluidInference/FluidAudio`) for Parakeet, VAD, and audio conversion. Nothing else unless you must.
- Ollama is called with plain `URLSession` against `http://127.0.0.1:11434`. No SDK. The Foundation Models framework is imported directly.
- `URLSession` is allowed in exactly two places: `ModelDownloader` and `OllamaCleaner`. Put a comment at the top of each saying so. Nothing else in the package may import a networking API. Tests enforce this.
- `scripts/bundle.sh` assembles `build/Flow.app` from the SwiftPM binary: copy the executable into `Contents/MacOS`, write `Contents/Info.plist`, copy `Resources/AppIcon.icns`, then `codesign --force --deep --sign - build/Flow.app` (ad hoc).
- `Makefile` with `make build`, `make bundle`, `make run` (bundle then `open build/Flow.app`), and `make test`.
- `Info.plist` must set `LSUIElement = true` (no Dock icon), `NSMicrophoneUsageDescription`, and `CFBundleIdentifier = com.yourname.flow`. The bundle id matters: macOS ties the Accessibility and Microphone grants to it, and an ad hoc signature that changes will make macOS ask again.

Repo layout:

```
Package.swift
Sources/Flow/            App.swift, StatusItem.swift, Overlay.swift, Hotkey.swift, AXInserter.swift, AudioEngineSource.swift, AppleCleaner.swift, Windows/
Sources/FlowCore/        Pipeline.swift, Prompts.swift, Cleaners/, Transcribers/, Audio/, Models/, Store/, Snippets.swift, Clock.swift
Tests/FlowCoreTests/
Tests/FlowTests/
fixtures/
scripts/bundle.sh
Makefile
README.md
```

## Data model

SQLite at `~/Library/Application Support/Flow/flow.sqlite`, managed with GRDB migrations.

- `dictations`: `id` (uuid text PK), `started_at` (text, ISO 8601 UTC with fractional seconds), `duration_ms` (int), `app_bundle_id` (text), `app_name` (text), `raw_text` (text, nullable), `cleaned_text` (text, nullable), `inserted_text` (text, nullable), `insert_method` (text: `ax` | `paste` | `clipboard_only` | `failed` | `cancelled`), `stt_model` (text, e.g. `parakeet-tdt-0.6b-v3`), `cleanup_backend` (text: `apple` | `ollama` | `rules` | `off`), `cleanup_model` (text, nullable), `stt_ms` (int), `cleanup_ms` (int, nullable), `word_count` (int), `error` (text, nullable). Index on `started_at`.
- `dictionary_entries`: `id`, `term` (text, unique, case-sensitive), `sounds_like` (text, nullable), `use_count` (int default 0), `created_at`.
- `app_styles`: `bundle_id` (text PK, `*` for the default), `app_name`, `tone` (`formal` | `neutral` | `casual` | `raw`), `hint` (text), `format` (`plain` | `markdown`), `updated_at`.
- `snippets`: `id`, `trigger_phrase` (text, unique, stored lowercased), `expansion` (text), `created_at`.

Timestamps are stored in UTC and shown in the user's local timezone. The history window groups by local day, so compute "Today" with `Calendar.current` on the converted date instead of matching a string prefix on the UTC value.

All settings live in `UserDefaults`. There are no secrets anywhere in this app:

- `modelPath` (default `~/Library/Application Support/Flow/models/parakeet-tdt-0.6b-v3`), `modelChecksum` (text, the SHA-256 of the manifest, set after download or import)
- `cleanupBackend` (`apple` | `ollama` | `rules` | `off`; default `apple` on macOS 26 with Apple Intelligence on, otherwise `ollama`), `ollamaModel` (default `qwen3:4b`), `ollamaBaseURL` (default `http://127.0.0.1:11434`, must resolve to a loopback address or the app refuses it)
- `hotkey` (key code plus modifier flags, default Right Option), `hotkeyMode` (`hold` | `toggle`, default `hold`)
- `trailingSpace` (default true), `playSounds` (default true), `launchAtLogin` (default false)
- `storeTranscripts` (default true), `historyRetentionDays` (default 90, 0 means forever)
- `historyShowsRaw` (the Raw | Cleaned toggle, default false)

Seed `app_styles` on first launch:

| bundle_id | tone | format | hint |
| --- | --- | --- | --- |
| `*` | neutral | plain | Everyday written English. |
| `com.tinyspeck.slackmacgap` | casual | plain | Slack message. Short. No sign-off. A lowercase first letter is fine for one-liners. |
| `com.apple.MobileSMS` | casual | plain | Text message. Very short. No period on a single short sentence. |
| `com.apple.mail` | formal | plain | Email. Complete sentences. Keep greetings and sign-offs the speaker says. |
| `com.apple.Terminal`, `com.googlecode.iterm2` | neutral | plain | Terminal. Output one line. No trailing punctuation. Never wrap in quotes or code fences. |
| `com.apple.Notes`, `notion.id`, `md.obsidian` | neutral | markdown | Notes. Use markdown lists and headings when the speaker enumerates. |

## Screens

### 1. Onboarding (first launch only)

A window with three steps and a progress row at the top.

- **Microphone**: request with `AVCaptureDevice.requestAccess(for: .audio)`. Show granted or denied, with a button to the Microphone privacy pane if denied.
- **Accessibility**: call `AXIsProcessTrustedWithOptions` with the prompt option, plus a button that opens `x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility`. Poll `AXIsProcessTrusted()` every second so the checkmark flips without a restart.
- **Speech model**: one paragraph that says what will be downloaded (Parakeet TDT 0.6B v3, about 600 MB, from Hugging Face), where it goes (`modelPath`), and that this is the only time the app will ever use the network. A "Download" button with a progress bar and a "Load from folder…" button for machines that can't reach the internet. When the download finishes, show the checksum and a "Cleanup" line that says which backend was auto-detected ("Apple Intelligence found", "Ollama found with qwen3:4b", or "No local model found. Using rules. Install Ollama to do better." with a link to `https://ollama.com`).
- Last step shows the hotkey and a plain text field labeled "Try it here".

Show this window again from the menu ("Check permissions…") if either permission is missing at launch, or if the model folder is missing.

### 2. Menu bar item

- Icon states: idle (outline mic), listening (filled mic, pulsing with a 1 s animation), processing (indeterminate spinner), error (mic with a small badge for 5 seconds).
- Menu items, top to bottom: the hotkey hint ("Hold ⌥ (right) to dictate"), a disabled line with the last dictation's timings ("Last: 0.4 s speech, 0.9 s cleanup"), a separator, "Cleanup" submenu (Apple / Ollama / Rules / Off, with a checkmark and the unavailable ones disabled), a separator, History…, Dictionary…, Settings…, Check permissions…, a separator, Quit.
- Clicking the icon with Option held starts a dictation in toggle mode regardless of `hotkeyMode`. Useful when the hotkey is broken.

### 3. Overlay

A small pill at the bottom center of the screen that has the frontmost app's window.

- `NSPanel` subclass with `.nonactivatingPanel` in the style mask, `level = .floating`, `hidesOnDeactivate = false`, `collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]`, `isMovableByWindowBackground = false`, `ignoresMouseEvents = true`.
- Override `canBecomeKey` and `canBecomeMain` to return false. The target app keeps keyboard focus the entire time. This is the single most important detail in the UI.
- Contents while listening: a 12-bar level meter driven by RMS, then the interim transcript in one line, truncated at the front so the newest words stay visible.
- After key up: "Transcribing…", then "Cleaning…", then the final text for 800 ms with a checkmark, then hide. On error: the error message in red for 3 seconds.
- Size: 420 pt wide max, grows with text up to 3 lines.

### 4. History window

- A list of dictations, newest first, grouped by local day ("Today", "Yesterday", then "Tuesday, Sep 8").
- Each row: app icon (from `NSWorkspace.shared.icon(forFile:)` on the app's bundle path, cached), app name, local time, duration, word count, and the text.
- A segmented control at the top, **Raw | Cleaned**, switches every row between `raw_text` and `cleaned_text`. Persist the choice in `historyShowsRaw`. Rows where the two are identical show a small "no changes" tag. Rows with null text (transcript storage off) show "Not stored".
- Per row actions: Copy, Insert again (runs the inserter against the current frontmost app after a 1 s delay so the user can switch windows), Delete. Right-click a word: "Add '<word>' to dictionary".
- Search box filters on both raw and cleaned text, case-insensitive.
- Rows with an error show it inline in a muted color, e.g. "Cleanup timed out. Inserted raw text."
- Footer: count of rows and total words this week.

### 5. Dictionary window

- Table with columns `term`, `sounds like`, `uses`. Add, edit inline, delete.
- Import and export a plain text file: one term per line, optional `term | sounds like`. Import skips duplicates and reports how many were added.
- Show a count. Every entry goes to the cleanup prompt; the prompt caps at 200 entries, longest first.

### 6. Settings window

Tabs:

- **General**: hotkey recorder (captures the next key press, shows a symbol string like `⌥ (right)` or `⌃⌥ Space`), hold vs toggle mode, trailing space, sounds, launch at login (`SMAppService.mainApp`).
- **Speech**: the model name and version, `modelPath` with a "Reveal in Finder" button, the checksum in monospace with a copy button, the compile status ("Compiled, loads in 0.8 s"), a "Re-download" button, and "Load from folder…". A "Test" button transcribes `fixtures/hello_world.wav` and shows the text and the time it took.
- **Cleanup**: backend picker (Apple / Ollama / Rules / Off). Each option shows its availability and a reason when it's greyed out: "Needs macOS 26 with Apple Intelligence on", "Ollama isn't running. Install it from ollama.com and run `ollama pull qwen3:4b`." Ollama model name (free text with suggestions `qwen3:4b`, `gemma3:4b`, `llama3.2:3b`) and a "Pull" button that runs the pull through Ollama's API with progress. Default tone. A "Test" button that runs `fixtures/transcripts/sample.txt` through the active cleaner and shows before and after with the round-trip time.
- **Apps**: table of `app_styles` with app name, tone, format, hint. "Add current app" reads the frontmost app's bundle id and name. Tone `raw` means skip cleanup for that app. Delete removes the row (the `*` row can't be deleted).
- **Privacy**: store transcripts on/off, retention days, "Delete all history", and a plain statement of the guarantee: "Audio and text never leave this Mac. The app made one network request, on <date>, to download the speech model. With Ollama as the cleaner, text goes to a local process on 127.0.0.1." Show the date of the download from `UserDefaults`.

## The dictation pipeline

Put this in `FlowCore` as `DictationPipeline`, with injected protocols so it can be tested without a mic, a model, or Accessibility permission:

```swift
protocol AudioSource { func start() throws -> AsyncStream<[Float]>; func stop() }
protocol Transcriber {
  func transcribe(audio: AsyncStream<[Float]>) -> AsyncThrowingStream<TranscriptEvent, Error>
}
enum TranscriptEvent { case interim(String), final(String) }
struct CleanupContext { let tone: String; let hint: String; let format: String; let dictionary: [DictionaryEntry] }
protocol Cleaner { var backend: CleanupBackend { get }; func clean(_ raw: String, context: CleanupContext) async throws -> String }
enum CleanupBackend: String { case apple, ollama, rules, off }
enum InsertResult { case ax, paste, clipboardOnly, failed(String) }
protocol TextInserter { func insert(_ text: String) async -> InsertResult }
protocol FrontmostApp { var bundleId: String? { get }; var name: String? { get } }
protocol Clock { func now() -> Date; func sleep(ms: Int) async }
```

State machine: `idle → listening → finalizing → cleaning → inserting → idle`, plus `cancelled` reachable from `listening` and `finalizing`.

1. **Key down** (hold mode) or first tap (toggle mode): read the frontmost app, start audio, open the transcriber stream, show the overlay, play the start tick. If the key is released within 250 ms in hold mode, treat it as an accidental tap and cancel silently with no history row.
2. **While listening**: forward 100 ms audio chunks to the transcriber. Show interim text in the overlay. Cap a single dictation at 5 minutes; at the cap, act as if the key was released. Escape cancels: stop audio, close the stream, hide the overlay, write a `cancelled` row with null text, insert nothing.
3. **Key up** (or second tap): stop audio, tell the transcriber the stream is done, wait up to 3 seconds for the `final` event. If the result is empty or whitespace, hide the overlay and write nothing.
4. **Snippets**: case-insensitive whole-phrase match of each `trigger_phrase` in the raw text (word boundaries on both sides); replace with `expansion`. Do this before cleanup so the model sees the expansion.
5. **Cleanup**: if `cleanupBackend` isn't `off` and the app's tone isn't `raw`, call the cleaner with a 4 second timeout. On any error, timeout, or guard failure, use the raw text and store the reason in `error` (`cleanup_error`, `cleanup_timeout`, `cleanup_guard`). Never block insertion for longer than the timeout. If the Apple or Ollama cleaner throws because it's unavailable, retry once with `RulesCleaner` before falling back to raw, and record `cleanup_backend = rules` on the row.
6. **Insert**: call the inserter. Append a trailing space when `trailingSpace` is on and the text doesn't end in a newline. Increment `use_count` on every dictionary term that appears in the inserted text.
7. **Record**: write the `dictations` row. If `storeTranscripts` is off, leave the three text columns null but keep timings and word count.

Timings to hit on an M1 or newer: final transcript within 700 ms of key up for a 15 second dictation, cleanup under 1.5 s with the Apple model or a 4B Ollama model, insert under 200 ms. Log all three per dictation.

If the hotkey is pressed while the pipeline is anywhere but `idle`, ignore it.

## Hotkey

- Use a `CGEvent` tap: `CGEvent.tapCreate` on `.cgSessionEventTap` at `.headInsertEventTap`, listening to `.keyDown`, `.keyUp`, and `.flagsChanged`. This needs the Accessibility permission, which you already require.
- Support modifier-only hotkeys and regular keys with modifiers. Default is Right Option (`flagsChanged` with key code 61). Also handle Fn (`.maskSecondaryFn`), Right Command (key code 54), and any key plus modifiers.
- For a modifier-only hotkey, "down" is the flag appearing and "up" is the flag disappearing. If any other key is pressed while the modifier is held, treat it as a normal shortcut: cancel the dictation silently (no row) and pass the events through. This is what makes Right Option safe as a default.
- Swallow the hotkey's own events (return nil from the callback) so the target app doesn't see them.
- Re-enable the tap when macOS disables it: handle `.tapDisabledByTimeout` and `.tapDisabledByUserInput` by calling `CGEvent.tapEnable` again.
- If the tap can't be created (permission missing), show the onboarding window and set the icon's error state.

## Audio

All of this runs locally in `FlowCore/Audio/` with AVFoundation and Accelerate, before any sample reaches Parakeet.

- `AVAudioEngine` input node tap with the hardware format, converted to 16 kHz mono `Float32` with `AVAudioConverter`. Parakeet expects 16 kHz mono floats in the -1 to 1 range.
- Emit chunks of 1,600 samples (100 ms). Compute RMS per chunk with `vDSP_rmsqv` for the level meter.
- `GainNormalizer`: on key up, compute the peak of the whole buffer with `vDSP_maxmgv` and scale so the peak is -3 dBFS, but never amplify by more than 20 dB (a silent room shouldn't become a hiss). Apply with `vDSP_vsmul`.
- `SilenceTrimmer`: run FluidAudio's `VadManager` over the buffer on key up and keep the span from 200 ms before the first speech segment to 200 ms after the last one. If VAD finds no speech, the transcript is empty and nothing is inserted. Skip VAD on the interim passes; it's only for the final.
- If the default input device changes mid-dictation, keep going with whatever the engine gives you and log it. If the engine throws on start, fail the dictation with "Couldn't open the microphone" and set the error icon.
- Play two short sounds (start and stop) with `NSSound` at 30% volume when `playSounds` is on. Ship them as small AIFF files in `Resources/`.

## Transcriber

One transcriber, `ParakeetTranscriber`, in `FlowCore/Transcribers/`. It wraps FluidAudio.

### Model files

- The model is `FluidInference/parakeet-tdt-0.6b-v3-coreml` on Hugging Face: the encoder, decoder, joint, and preprocessor `.mlmodelc` packages plus the vocabulary. About 600 MB.
- `ModelDownloader` (in `FlowCore/Models/`) fetches the repo's file list, downloads each file into `modelPath` with resumable `URLSessionDownloadTask`s and a progress callback, then computes a SHA-256 over every file (sorted by path, hash of the concatenated per-file hashes) and stores it as `modelChecksum`. Write `manifest.json` next to the files with the file names, sizes, per-file hashes, and the download date.
- Check FluidAudio's `AsrModels` for a way to load from a custom directory. If it has one, use it with `modelPath`. If it only loads from its own cache (`~/.cache/fluidaudio/Models/`), symlink or copy `modelPath` into that location on load and say so in the README. Don't let the library download on its own; the app owns the one network request.
- "Load from folder…" copies a folder the user picks into `modelPath`, validates that the expected files are present, computes the same checksum, and writes the manifest with `source = "folder"`.
- Compile happens on first load and takes 10 to 30 seconds. Show "Compiling model…" in the overlay and the menu bar if a dictation starts before it's done. Cache the compiled model so every later launch loads in about a second.
- Load the model once, on launch, on a background task. Keep it in memory for the life of the process.

### Inference

- **Interim pass**: every 1,000 ms while listening, run `AsrManager.transcribe` over the whole buffer so far (up to the last 30 seconds) on a serial background queue. Emit the result as `.interim`. If a pass takes longer than 1,000 ms, skip the next tick instead of queueing. FluidAudio's `SlidingWindowAsrManager` is the streaming alternative; use it only if its partial text is stable between passes.
- **Final pass**: on key up, trim silence, normalize gain, run `transcribe` once over the full buffer, and emit `.final`. Parakeet TDT returns punctuation and capitalization on its own. Keep them; the cleaner does the rest.
- Language: Parakeet v3 detects the language itself among its 25. Don't add a language picker.
- If the model folder is missing or fails to load, fail with "No speech model. Download one in Settings → Speech" and a notification that opens Settings.
- Must work with no network at all. There's no code path in this file that can open a socket.

### If FluidAudio doesn't fit

If FluidAudio's API has moved, or its CoreML build doesn't run on the target machine, swap the implementation for `sherpa-onnx` with its Parakeet TDT 0.6B v3 int8 ONNX export and the sherpa-onnx Swift bindings. Keep the `Transcriber` protocol identical so nothing else changes. Note the swap in the README.

## Cleaners

Three `Cleaner` implementations behind one `CleanerFactory` that picks by `cleanupBackend` and availability. The prompt is the same for all of them.

### AppleCleaner (macOS 26, Foundation Models)

- Lives in the `Flow` target because it imports `FoundationModels`. Wrapped in `#available(macOS 26, *)`.
- Available when `SystemLanguageModel.default.availability == .available`. Otherwise report the reason (`.deviceNotEligible`, `.appleIntelligenceNotEnabled`, `.modelNotReady`) in Settings and don't offer it.
- One `LanguageModelSession(instructions:)` per cleanup with the system prompt below as the instructions and the raw transcript as the prompt. Use `respond(to:)` with `GenerationOptions(temperature: 0)`. Set `maximumResponseTokens` to `min(4096, rawTokens * 2 + 64)` where `rawTokens` is `rawCharacters / 4`.
- If the model refuses because of its safety guardrails (a `guardrailViolation` error), fall back to the rules cleaner for that dictation. Don't retry.

### OllamaCleaner (macOS 15, or Apple Intelligence off)

- `POST http://127.0.0.1:11434/api/chat` with `model = ollamaModel`, `stream: false`, `messages` = system prompt plus the raw transcript, `options: { temperature: 0, num_predict: <same cap as above> }`, and `think: false` for models that support it (qwen3 will otherwise spend seconds thinking).
- Availability check: `GET /api/tags` with a 500 ms timeout on launch and whenever Settings opens. If it fails, mark the backend unavailable with the one-line hint "Ollama isn't running. Install it from ollama.com and run `ollama pull qwen3:4b`." If the server is up but `ollamaModel` isn't in the tag list, the hint says which model to pull.
- Refuse any `ollamaBaseURL` whose host isn't `127.0.0.1`, `localhost`, or `::1`. This is the only place the app talks to a socket after the model download, and it must stay on the loopback interface.

### RulesCleaner (always available, no model)

In `FlowCore/Cleaners/RulesCleaner.swift`, pure Swift:

1. Replace each dictionary `sounds_like` with its `term`, case-insensitive, whole phrase.
2. Remove filler tokens from a list in `Prompts.swift`: `um`, `uh`, `umm`, `uhh`, `er`, `ah`, `hmm`, `you know`, `I mean`, `sort of`, `kind of`, and `like` or `so` only at the start of a sentence. Match on word boundaries.
3. Apply the self-correction pattern `X, no, Y` and `X no Y` when `no` sits between two short phrases of the same shape (a weekday, a number, a single capitalized word): keep `Y`.
4. Spoken punctuation: `period`, `comma`, `question mark`, `new line`, `new paragraph` become the symbol when they end a clause.
5. Collapse whitespace, capitalize the first letter of each sentence, add a terminal period if the text ends in a letter or digit and `tone` isn't `casual`.
6. If `format` is `markdown` and the text contains `first`, `second`, `third` or `one`, `two`, `three` as clause starters, split them into a `- ` list.

It won't match a model, but it makes the app usable with nothing installed, and it's what the tests run against for determinism.

### The prompt

System prompt (put it in `Prompts.swift` and keep exactly this shape so tests can assert on it):

```
You clean up dictated speech into written text. Rules:
- Remove filler words (um, uh, like, you know, so at the start of a sentence) and false starts.
- Apply self-corrections: "send it Tuesday, no, Wednesday" becomes "send it Wednesday".
- Add punctuation and capitalization. Split into sentences and paragraphs where the speaker clearly paused or changed topic.
- When the speaker lists items ("three things", "first... second..."), format a list if FORMAT is markdown, otherwise keep it as a sentence.
- Spoken punctuation ("period", "comma", "new line", "new paragraph") becomes the symbol only when it clearly isn't part of the sentence.
- Format emails, URLs, numbers, and times the way a person would type them.
- Keep the speaker's words and meaning. Do not add, summarize, answer, or explain. Do not translate.
- Output only the cleaned text. No quotes, no preamble, no markdown fences.

TONE: {tone}. {hint}
FORMAT: {format}
DICTIONARY (spell these exactly as written when the speaker says them): {term (sounds like: sounds_like)}, ...
```

The user message is the raw transcript. If the dictionary is empty, omit the DICTIONARY line entirely. Entries without `sounds_like` are listed as just the term.

Guards after the response, for every backend:

- Trim whitespace. Strip one pair of wrapping quotes or a code fence if the model added one. Strip a `<think>…</think>` block if a model emitted one anyway.
- If the raw text has more than 5 words and the cleaned word count is under 40% or over 200% of the raw word count, reject and fall back to raw with `error = "cleanup_guard"`.
- If the response is empty, fall back to raw.
- If the response starts with "I'm sorry" or "I can't" and the raw text doesn't, fall back to raw. Models sometimes answer instead of clean.

Counting words: split on whitespace. Good enough.

## Text inserter

`AXInserter` in the `Flow` target, since it needs AppKit and `ApplicationServices`.

1. Get the system-wide element's `kAXFocusedUIElementAttribute`. If there's no focused element at all, go to step 4.
2. If the element's role is `AXTextField`, `AXTextArea`, `AXComboBox`, or it reports `AXFocused = true` and `kAXSelectedTextAttribute` is settable (`AXUIElementIsAttributeSettable`), try `AXUIElementSetAttributeValue(element, kAXSelectedTextAttribute, text)`. Then read back `kAXValueAttribute`; if the value now contains `text`, return `.ax`. Many browser and Electron text fields report success without inserting, which is why you read back. If the read-back fails or the value is huge (over 200 KB), don't compare, just go to step 3.
3. Clipboard paste. Snapshot every item and every type on `NSPasteboard.general`. Write the text as a single string item. Post Cmd+V as `CGEvent` key down and key up (key code 9 with `.maskCommand`) to `.cghidEventTap`. Wait 150 ms. Restore the snapshot. Return `.paste`. If restoring throws, leave the text on the clipboard rather than leaving it empty.
4. No focused element (Finder, an empty desktop, a video player): don't post Cmd+V. Write the text to the clipboard and leave it there. Send a `UNUserNotification` saying "No text field was focused. The text is on your clipboard." Return `.clipboardOnly`.

Rules:

- Secure text fields (`AXSecureTextField`): never insert. Return `.failed("secure field")`, notify, and don't store the text in history.
- Terminals: paste is the right path. Multi-line text into a terminal will run lines as commands, so when the frontmost app is a terminal and the text has more than one line, join lines with spaces first.
- Restore the clipboard even if the paste keystroke fails. Use `defer`.

## Notifications and logging

- Use `UNUserNotificationCenter` for the four user-facing cases: no text field, secure field, missing model, cleanup backend went away. Ask for notification permission the first time you need to send one instead of at launch.
- Log to `~/Library/Logs/Flow/flow.log` with `os.Logger` mirrored to the file. One line per pipeline stage with timings. Never log transcript text unless `FLOW_DEBUG=1` is set in the environment, and say so in the README.
- Rotate the log at 5 MB, keep two.

## History retention

On launch and once a day, delete `dictations` rows older than `historyRetentionDays` when it's above 0. "Delete all history" truncates the table and runs `VACUUM`.

## Non-goals

Do not build: a Windows or Linux version (keep `FlowCore` free of AppKit so a Windows port can reuse it later), iOS or Android keyboards, a meeting notetaker, team accounts, shared dictionaries, SSO, billing, auto-updates, or command mode that edits selected text. Leave a `// TODO: command mode` where the pipeline would branch on a second hotkey. No cloud APIs of any kind: no Deepgram, no OpenAI, no OpenRouter, no hosted anything, even as an option behind a setting. No API keys, no Keychain, no accounts, no Stripe, no server of your own. No telemetry and no crash reporter.

## Acceptance criteria

1. On first launch the app appears in the menu bar with no Dock icon, and the onboarding window walks through Microphone, Accessibility, and Speech model. The Accessibility checkmark flips within 2 seconds of granting it in System Settings, without restarting.
2. After the model download, Settings → Speech shows a SHA-256 checksum that matches `manifest.json`, and "Load from folder…" with a copy of the same folder produces the same checksum.
3. Holding the hotkey in TextEdit, saying a sentence, and releasing inserts the text at the caret within 2 seconds of release on an M1 or newer. TextEdit stays the frontmost app the whole time.
4. While holding the key, interim words appear in the overlay within 1.5 seconds of being spoken. The overlay never becomes the key window (`NSApp.keyWindow` stays nil and `NSWorkspace.shared.frontmostApplication` is unchanged).
5. `fixtures/hello_world.wav` through `ParakeetTranscriber` yields a transcript containing `hello world`. `fixtures/silence.wav` (3 seconds of room noise) yields an empty transcript and no history row.
6. Raw transcript `um so send it uh Tuesday no Wednesday` becomes `So send it Wednesday.` with the default style, through both the rules cleaner and whichever model cleaner is available.
7. With `Wolchonok` (sounds like `wall chunk`) in the dictionary, the cleanup prompt's DICTIONARY line contains `Wolchonok (sounds like: wall chunk)`, and the rules cleaner turns `call wall chunk back` into `Call Wolchonok back.`
8. The same raw transcript produces a prompt with `TONE: casual` when Slack is frontmost and `TONE: formal` when Mail is frontmost. With `format = markdown`, a spoken list of three items becomes a three-line markdown list; with `plain`, it stays one sentence.
9. If the cleanup call throws, times out at 4 seconds, or trips the length guard, the raw transcript is inserted, `error` is set on the history row, and the app doesn't crash or hang. If Ollama is quit mid-session, the next dictation uses the rules cleaner and records `cleanup_backend = rules`.
10. With all network blocked after the model download (Wi-Fi off, or a firewall rule that drops everything except loopback), dictation and cleanup still work.
11. During a dictation the app opens no sockets to any host other than 127.0.0.1. Verified with `nettop -p Flow` or `lsof -i -a -p <pid>`: with the Apple or rules cleaner the list is empty, with Ollama it shows exactly one loopback connection.
12. After a clipboard paste, the previous clipboard contents are restored within 500 ms, including an image item.
13. With Finder frontmost and no text field focused, nothing is typed, the text is on the clipboard, `insert_method = clipboard_only`, and a notification appears.
14. Pressing Escape while holding the hotkey inserts nothing and writes a `cancelled` row with null text. A dictation that returns an empty transcript inserts nothing and writes no row. The History window's Raw | Cleaned toggle switches every row, search filters on both columns, and Delete removes a row.

## Deliverables

- The Swift package with `Flow` and `FlowCore` targets, `scripts/bundle.sh`, `Makefile`, sounds, and an app icon.
- `FlowCoreTests` covering the pipeline state machine, snippet expansion, prompt building, the cleanup guards, the rules cleaner, the gain normalizer and silence trimmer, and the checksum, all with fakes. Plus one test that scans `Sources/` and fails if any file other than `ModelDownloader.swift` and `OllamaCleaner.swift` mentions `URLSession`, `Network`, `NWConnection`, or `CFStream`.
- A `fixtures/` folder with `hello_world.wav` (3 seconds, 16 kHz mono), `silence.wav`, `parakeet/hello_world.json` (the recorded Parakeet output for that WAV: text, per-token timestamps, and the inference time on the machine it was recorded on), and three raw transcripts with expected cleaned output.
- README with: the Requirements section above, build and run steps, how to grant and reset the permissions (`tccutil reset Accessibility com.yourname.flow`, `tccutil reset Microphone com.yourname.flow`), the model download and the "Load from folder" path for offline Macs, how to install Ollama and pull a model, the default hotkey and how to change it, the `FLOW_DEBUG` flag, how to verify the no-network claim with `nettop`, and a short note on what a Windows port would need (a `SendInput` inserter, a `RegisterHotKey` or low-level keyboard hook, WASAPI capture, and sherpa-onnx in place of CoreML, with `FlowCore` reused as is).

Build `FlowCore` and its tests first (pipeline, prompt, rules cleaner, guards, audio processing) with fakes for every protocol. Then the model downloader and the Parakeet transcriber, tested against the real model on `fixtures/hello_world.wav`. Then the inserter and hotkey. Then the overlay and menu bar. Then the Apple and Ollama cleaners. Then History, Dictionary, and Settings. Run `make run` after each step and dictate into TextEdit with Wi-Fi off before moving on.