Flint Quest

Tracks

1. 01⚡The Strike

   0/4 lessons

   What Flint is, and why the name points at the gesture instead of the machine

   Before a single line of Swift, you have to understand what Flint actually is — and, just as important, everything it refuses to be. It is a native macOS menu-bar utility that owns exactly one gesture: select text anywhere, strike a hotkey, get one safe replacement. It is not a chat window, not a second Pippa brain, not a model server. This track sets the posture: the gesture is the product, the brain is borrowed, and the name is a verb, not a box.

   

   Lesson list (4)

   • 01
     One Gesture, Nothing Else~12 min · identity, menu-bar, thin-client, posture
   • 02
     The Verb Above the Noun~11 min · design, context-switch, fire-family, latency
   • 03
     Remake, Not Remaster~12 min · remake, decommission, legacy, posture
   • 04
     Own the Loop, Don't Rent It~11 min · build-vs-rent, local-first, ownership, cost-model

   ✓Quiz · 4 questions→

2. 02⌨️The Global Chord

   0/4 lessons

   Owning a system-wide hotkey with the oldest API macOS still hands you

   A gesture needs a trigger that works everywhere, in every app, even when Flint isn't frontmost. On macOS, claiming a system-wide key chord that actually gets consumed is a surprisingly old and narrow corner of the platform — you reach past the modern Swift frameworks and into Carbon, a deprecated API that has no replacement for this exact job. This track walks that corner honestly: why Carbon, how RegisterEventHotKey actually works, what to do when two chords collide, and the searchable palette that means you don't need a chord for every macro.

   Lesson list (4)

   • 01
     Three Doors to a Global Key~12 min · carbon, cgevent-tap, nsevent, deprecated-not-removed
   • 02
     How RegisterEventHotKey Actually Works~13 min · carbon, register-event-hotkey, event-handler, modifiers
   • 03
     When Two Chords Want the Same Keys~10 min · collisions, osstatus, reserved-shortcuts, honesty
   • 04
     One Shortcut You Can't Lose~10 min · palette, discovery, non-activating, overflow

   ✓Quiz · 4 questions→

3. 03🔎Reading the Selection

   0/5 lessons

   How one app reads the text you highlighted in a completely different app

   The strike is nothing without input. Flint has to reach into whatever app you're in — a text editor, a browser, a chat window — and read the text you selected, even though it's someone else's app. macOS lets you do this through the Accessibility API, with the user's explicit permission. This track is the honest tour: how AX reading works, the exact path to the current selection, the apps that hide their selection from you entirely, and the reversible clipboard probe that recovers it without leaving a trace.

   Lesson list (5)

   • 01
     The Accessibility API Is a Granted Power~11 min · accessibility, ax-tree, trust, permission
   • 02
     From System-Wide to the Selection~12 min · axuielement, focused-element, selected-text, range
   • 03
     The Apps That Hide Their Selection~11 min · chromium, electron, opaque-controls, boundary
   • 04
     The Reversible Copy Probe~12 min · copy-probe, cgevent, changecount, reversible
   • 05
     Restore the Whole Clipboard, Not Just the Text~11 min · pasteboard, preservation, fidelity, etiquette

   ✓Quiz · 4 questions→

4. 04🔌Not My Brain

   0/4 lessons

   Where Flint stops and the borrowed intelligence begins

   Flint does the reaching, the reading, and the careful putting-back — but it does not think. The thinking is borrowed from a brain that already exists in another app, across a boundary drawn on purpose to be narrow. This track is about that boundary: exactly what lives on each side, the apply-free contract Flint speaks across it, why Flint's macros and the brain's macros are two independent catalogs that must never share an id, and why a thin client that borrows a brain has to resist growing one of its own.

   Lesson list (4)

   • 01
     Two Halves, One Call~11 min · boundary, client-server, separation, narrow-interface
   • 02
     Send a Prompt, Not a Reference~11 min · apply-free, contract, vault-bypass, wire
   • 03
     Two Catalogs That Never Touch~10 min · independent-catalogs, coupling, ownership, dry-trap
   • 04
     Say No to the Second Brain~11 min · stay-thin, non-goals, no-second-brain, discipline

   ✓Quiz · 4 questions→

5. 05🧩The Macro

   0/4 lessons

   The small, stable object that turns a transformation into one strike

   A macro is the unit Flint runs: a name, a prompt template with an {input} slot, an optional chord, and a switch for how much context it needs. It's a tiny object, and its smallness is the point — everything a transformation needs to be triggered, rendered, and tuned lives in one stable record. This track builds the macro from the inside: the domain type and its stable identity, how {input} carries the selection, the per-macro vault dial that trades latency for knowledge, and the app-wide execution profile that everything else rides on.

   Lesson list (4)

   • 01
     One Small Record~11 min · flint-macro, value-type, uuid, persistence
   • 02
     Where the Selection Goes~10 min · input-token, template, rendering, append
   • 03
     The Latency Dial Lives on the Macro~11 min · vault-mode, latency, context, per-macro
   • 04
     The Profile Everything Rides On~11 min · execution-profile, scope, no-side-effects, simple-verbose

   ✓Quiz · 4 questions→

6. 06🛡️Prove Before You Paste

   0/5 lessons

   The target you captured may be gone by the time the answer comes back

   This is the riskiest and most interesting layer in the whole app, and the reason it exists is a single hard fact: between the strike and the answer, real time passes, and the world can change under you. The selection you captured might be gone, the window might have moved, focus might have wandered. Insertion's whole job is to refuse to paste into a target it can no longer prove is the one you meant. This track walks that discipline: the async gap, re-validating a native target, re-copying to prove an opaque one, falling back to the clipboard when proof fails, and inserting as a single undoable action.

   Lesson list (5)

   • 01
     The Gap Between Intent and Effect~12 min · async-gap, intent-vs-effect, boundary, core-problem
   • 02
     Re-Read the Native Target~12 min · revalidate, native-target, range-match, ax-set
   • 03
     Prove an Opaque Target by Reproduction~11 min · recopy-compare, opaque-target, window-match, reproduction
   • 04
     When Proof Fails, Fall to the Clipboard~10 min · clipboard-fallback, safety-over-convenience, graceful-degradation, visible-failure
   • 05
     One Strike, One Undo~10 min · one-undo, single-action, pasteboard, acceptance

   ✓Quiz · 4 questions→

7. 07🔒Never Read the Secret

   0/4 lessons

   The moment you can read any app is the moment you owe it restraint

   Flint holds enormous power — it can read the text in any app and type into any field. Power like that is defined by what it refuses to do. This track is the security spine: secure and password fields are never read and, where a control declares itself secure, never written; permission is proven before a model call is ever spent; the remote PIN lives in the Keychain and the pattern is taught without ever teaching a parameter; and local-first is reframed as what it really is — a posture of trust you earn by staying narrow and visible.

   Lesson list (4)

   • 01
     The Field You Must Not Touch~10 min · secure-field, subrole, capture-time, refuse
   • 02
     Don't Spend a Call You Can't Land~10 min · permission-before-inference, preconditions, dont-waste, gate
   • 03
     The PIN, the Keychain, and the Wire~11 min · keychain, pin-session, tailscale, secret-handling
   • 04
     Trust You Earn by Staying Narrow~11 min · local-first, trust, reciprocity, earned-not-assumed

   ✓Quiz · 4 questions→

8. 08🔥Strike Anywhere

   0/4 lessons

   The doctrine that keeps the legacy dead, the latency owned, and the loop yours

   The last track steps back from the mechanics to the doctrine that holds them together. Decommissioning the old tool wasn't a one-time delete — it's an invariant that has to stay green. Owning the latency means never hiding the tradeoff behind a default. And the whole loop, from a chord to a proven insertion, teaches a handful of transferable lessons about boundaries, borrowing, and trust. It closes where every self-referential quest closes: not with a repo to clone, but with enough of the shape that you could strike your own.

   Lesson list (4)

   • 01
     Decommission Is an Invariant, Not an Event~10 min · decommission, invariant, stays-green, doctrine
   • 02
     Own the Latency, Don't Hide It~10 min · own-the-latency, explicit-control, no-hidden-default, doctrine
   • 03
     What Owning the Loop Teaches~11 min · synthesis, transferable-lessons, boundaries, trust
   • 04
     Go Strike Your Own~11 min · build-your-own, conceptual-opensourcing, closer, where-to-next

   ✓Quiz · 4 questions→