Firekeeper Quest

Tracks

1. 01🕯️The Keep

   0/4 lessons

   What Firekeeper is, where its name comes from, and why it exists

   Before any Swift, the orientation. Firekeeper is a system-wide dictation app for macOS — not a chat window with a mic, not a second Pippa brain, not a cloud subscription. This track decodes the Dark Souls name, places Firekeeper in the five-repo sibling family, answers the first question anyone asks a self-built tool — why not just rent Wispr Flow? — and draws the one product boundary that keeps the whole thing sane: dictation now, voice chat later.

   Lesson list (4)

   • 01
     A Mic Is Not the Product~11 min · identity, voice-loop, orientation
   • 02
     Why 'Firekeeper'~10 min · name, lineage, family, thesis
   • 03
     Build vs. Rent~11 min · build-vs-rent, privacy, conceptual-opensourcing, strategy
   • 04
     Two Stages, One Boundary~11 min · two-stage, product-boundary, response-contract, roadmap

   ✓Quiz · 4 questions→

2. 02🔁Clone the Loop, Not the Cloud

   0/4 lessons

   Reverse-spec an interaction model without copying anyone's backend

   Wispr Flow is closed-source, so you can't read its code — and you shouldn't want to. This track is about the discipline of cloning a product's observable interaction model: how to reverse-spec from public docs and behavior alone, the exact anatomy of the dictation loop, what's worth cloning versus what to deliberately leave behind (cloud transcription, account gating, hidden data collection), and the three-mode taxonomy every good dictation tool converges on.

   Lesson list (4)

   • 01
     Reverse-Spec, Not Reverse-Engineer~10 min · reverse-spec, ethics, observable, research
   • 02
     Anatomy of One Dictation~12 min · loop-anatomy, target-snapshot, pre-roll, capture
   • 03
     Two Lists: Clone and Leave~11 min · what-to-clone, scope, privacy, cloud
   • 04
     Three Modes, Kept Apart~11 min · mode-taxonomy, command-mode, transform, hotkeys

   ✓Quiz · 4 questions→

3. 03👂Hearing on Apple Silicon

   0/5 lessons

   On-device speech-to-text, and the traps that make it sound broken

   The ear is where the whole privacy bet is won or lost: if transcription is on-device, your voice never has to leave the machine. This track surveys the Apple Silicon STT engines (WhisperKit, whisper.cpp, MLX, Apple SpeechAnalyzer), then digs into the two gotchas that make on-device STT look broken when it isn't — the silent English default that turns Korean into garbage, and the Hangul-transliteration trap — before covering how batch models fake real-time and how to manage model weights without bloating your repo.

   Lesson list (5)

   • 01
     Four Ways to Hear~12 min · stt-engines, whisperkit, on-device, apple-silicon
   • 02
     The Silent English Default~11 min · language-forcing, whisperkit, gotcha, korean
   • 03
     When 'SwiftUI' Becomes '스위트 트라이'~10 min · transliteration, speechanalyzer, mixed-language, default-choice
   • 04
     Faking Real-Time From a Batch Model~12 min · batch-vs-streaming, localagreement, real-time, preview
   • 05
     Weights Are Not Source~10 min · model-weights, cache, prewarm, packaging

   ✓Quiz · 4 questions→

4. 04🔌Everything Is an Adapter

   0/4 lessons

   One narrow seam, many swappable engines and brains

   Firekeeper inherits a philosophy from the Pippa house: put the abstraction boundary in exactly one narrow place and let everything specialize downstream of it. This track shows how that seam works in a voice app — STT engines behind one interface, cleanup brains behind another, and connection modes as an explicit settings choice rather than a hidden fallback chain — so any piece can be swapped without the product logic noticing.

   Lesson list (4)

   • 01
     One Seam, Not Ten~11 min · narrow-seam, rule-2, adapter-pattern, architecture
   • 02
     No Engine Leaks Upward~11 min · stt-adapter, leaky-abstraction, contract, engine
   • 03
     The Cleanup Contract~12 min · cleanup-contract, insertion, safety, provider
   • 04
     Modes Are Chosen, Not Guessed~11 min · connection-modes, explicit, privacy, tailscale

   ✓Quiz · 4 questions→

5. 05🪜The Insertion Ladder

   0/5 lessons

   Getting text into the active app is the riskiest layer in the whole loop

   This is the track no other quest has, because insertion is where a voice app touches the whole rest of the operating system. It's the riskiest and most interesting layer: capturing the right target before focus can drift, climbing a ladder of insertion methods that each fail gracefully into the next, keeping undo intact, handling terminals and coding agents as first-class citizens, and treating the pasteboard with the etiquette it demands. Get insertion wrong and every other part of the loop is wasted.

   Lesson list (5)

   • 01
     Snapshot the Target First~11 min · target-capture, accessibility, wrong-app-guard, focus
   • 02
     Four Rungs, Each Failing Gracefully~12 min · ladder, insertion-methods, graceful-degradation, cgevent
   • 03
     One Cmd+Z Should Undo the Whole Thing~10 min · undo, single-action, pasteboard, ux
   • 04
     Terminals Are First-Class Targets~11 min · terminal-profile, coding-agents, safety, bracketed-paste
   • 05
     Borrow the Clipboard, Return It Clean~10 min · pasteboard, clipboard, etiquette, privacy

   ✓Quiz · 4 questions→

6. 06📴Offline Is Not Theater

   0/4 lessons

   The fallback path has to actually work, or it's a lie

   Lots of apps claim to work offline and mean it as a marketing checkbox — the offline path is a hidden retry that quietly phones home the moment it can. Firekeeper inherits a hard rule from its writing sibling Rekindle: provider selection happens before a single byte leaves the process, offline never leaks to online, and the offline cleanup is a real provider with real behavior — not a crash-recovery afterthought. This track is how you build an offline path you can actually trust on a plane.

   Lesson list (4)

   • 01
     Decide Before You Send~11 min · selection-before-send, rekindle-lesson, privacy, offline
   • 02
     Capable, Not Constrained~10 min · offline-capable, not-constrained, tradeoff, quality
   • 03
     The No-Model Floor~11 min · deterministic, floor, no-model, filler
   • 04
     A Small Brain With a Tight Leash~11 min · mini-pippa, ollama, contract, local-model

   ✓Quiz · 4 questions→

7. 07⚡The Latency War

   0/5 lessons

   How the fast path got shipped slow, and the hotkey race that nearly broke it

   This is the war-story track: the part where Firekeeper got shipped wrong and had to be rebuilt. Every dictation was routed through the full Pippa brain — a 100KB+ vault prompt, a subprocess, and a deep reasoning pass, all to strip the word 'um' — and it cost 10 to 40 seconds against a competitor's 1. This track walks the diagnosis, the lane split that fixed it, the latency budgets that keep it honest, and the parallel war over hotkeys: why a suppressing event tap was the wrong tool, and how a double-tap race condition got settled with generation tokens and a typed state machine.

   Lesson list (5)

   • 01
     A Cathedral to Hang a Picture~12 min · war-story, latency, diagnosis, reuse-trap
   • 02
     Four Lanes, One Road~12 min · lane-split, fix, architecture, cleanup
   • 03
     Budgets Keep You Honest~10 min · latency-budgets, measurement, benchmarks, discipline
   • 04
     Don't Put a Tap in Everyone's Keyboard~11 min · hotkey, event-tap, permissions, flagschanged
   • 05
     The Ghost That Cancelled the Living~12 min · race-condition, generation-token, state-machine, async

   ✓Quiz · 4 questions→

8. 08🛡️Trust at the OS Boundary

   0/5 lessons

   You asked the machine to listen and to type. Now earn it.

   A dictation app asks for two of the most invasive permissions an operating system grants: hear everything, and act on every app. That's a trust boundary, and this closing track is about earning it rather than assuming it — the permission surface and how to ask for it honestly, the code-signing trap that makes macOS forget your grants, the visible-recording and no-retention contract, the secure fields you must refuse, and finally why owning your own voice layer is the whole point of having built any of this.

   Lesson list (5)

   • 01
     Two Terrifying Permissions~11 min · permissions, tcc, accessibility, microphone
   • 02
     Why macOS Keeps Forgetting You~12 min · codesign, tcc, gotcha, designated-requirement
   • 03
     Visible While Listening, Forgetful After~11 min · retention, privacy, opt-in, history
   • 04
     The Rooms You Refuse to Enter~11 min · secure-field, denylist, refusal, privacy
   • 05
     Own the Thing That Hears You~12 min · no-own-brain, closer, ownership, build-your-own

   ✓Quiz · 4 questions→