Onboarding
The first time kiln launches it raises a single sheet, then never shows it again. It's a calm, five-step arrival rather than a form: a welcome beat that says what kiln is, the three choices that actually change how the app behaves, and a hand-off to Potter. Each choice is an ordinary preference you can revisit in Settings.
The steps
Welcome. A warm kiln-ember glow (the one moment of motion in the app, and a nod to the name) over three lines on what kiln is: it runs on this Mac, it's your real shell and your real agents, and it reads code three ways.
Which agents do you want? Three provider cards, each with its real brand mark — the on-device Apple chip, the Claude sunburst, the Codex glyph. Each toggle gates that provider everywhere kiln reaches for a model: the assistant picker, the squad, ambient agents, and the terminal handoffs. The cards spell out that every agent powers both the in-app assistant and its command-line agent in your terminal — the Claude toggle covers Claude Code, the Codex toggle the Codex CLI.
The sheet reads your environment. When a cloud provider has no key, you can paste one and verify it inline (the cheapest authenticated call, no tokens), and a good key is saved to the Keychain through the same CredentialStore seam Settings uses. No more "export a key and relaunch" dead-end. On-device says so if Apple Intelligence is off. At least one agent has to stay on to move past this step.
Will you be coding? "Yes" opens the squad panel alongside the editor and leans the default view toward CODE. "Mostly reading and writing" keeps things quiet and leans toward DOC. It only nudges the next step; your explicit pick wins.
Default view. Which face the editor opens in: CODE (a plain editor), NOTES (section labels), or DOC (reads like a document). A live mini-preview shows the same snippet in each as you toggle, so the choice is something you see rather than imagine. Switch any time with ⌘1–⌘3. Opening a markdown file still lands in DOC regardless.
Meet Potter. The payoff: finishing posts a warm greeting from Potter into the squad feed, so the assistant is already there, on-device, the moment the sheet closes. This step also quietly probes your machine: if a tool or key kiln leans on isn't ready, a small card offers a Review setup button that finishes onboarding and opens the environment doctor with each gap and its fix in front of you. A fully-equipped machine never sees it.
Afterwards
Finishing — or skipping — sets the hasOnboarded flag so the sheet stays shut. Everything it wrote lives in Settings ▸ General: the provider toggles, the default view, and a Show onboarding again button that resets the flag and re-raises the sheet.
Where it lives
Onboarding (Config/Onboarding.swift) holds the completion gating — shouldShow, markCompleted, reset. OnboardingFlow (Config/OnboardingFlow.swift) is the pure step navigation and gating, tested without a window. OnboardingView is the sheet and KilnEmber the welcome animation. RootView raises it once on first launch (and skips snapshot renders); AppState.showOnboarding is the shared flag both the first-launch path and the Settings button flip.