diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 1c5c12ff..21ec5496 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -12,6 +12,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@iarna/toml": "^2.2.5",
     "@open-codesign/artifacts": "workspace:*",
     "@open-codesign/core": "workspace:*",
     "@open-codesign/providers": "workspace:*",
diff --git a/apps/desktop/src/main/config.ts b/apps/desktop/src/main/config.ts
new file mode 100644
index 00000000..641e19dd
--- /dev/null
+++ b/apps/desktop/src/main/config.ts
@@ -0,0 +1,67 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import * as TOML from '@iarna/toml';
+import { CodesignError, type Config, ConfigSchema } from '@open-codesign/shared';
+
+const XDG_DEFAULT = join(homedir(), '.config', 'open-codesign');
+
+export function configDir(): string {
+  const xdg = process.env['XDG_CONFIG_HOME'];
+  if (xdg && xdg.length > 0) return join(xdg, 'open-codesign');
+  return XDG_DEFAULT;
+}
+
+export function configPath(): string {
+  return join(configDir(), 'config.toml');
+}
+
+export async function readConfig(): Promise<Config | null> {
+  const path = configPath();
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (isNotFound(err)) return null;
+    throw new CodesignError(`Failed to read config at ${path}`, 'CONFIG_READ_FAILED', {
+      cause: err,
+    });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = TOML.parse(raw);
+  } catch (err) {
+    throw new CodesignError(`Config at ${path} is not valid TOML`, 'CONFIG_PARSE_FAILED', {
+      cause: err,
+    });
+  }
+
+  const validated = ConfigSchema.safeParse(parsed);
+  if (!validated.success) {
+    throw new CodesignError(
+      `Config at ${path} does not match the expected schema: ${validated.error.message}`,
+      'CONFIG_SCHEMA_INVALID',
+      { cause: validated.error },
+    );
+  }
+  return validated.data;
+}
+
+export async function writeConfig(config: Config): Promise<void> {
+  const validated = ConfigSchema.parse(config);
+  const dir = configDir();
+  await mkdir(dir, { recursive: true });
+  const path = configPath();
+  const body = TOML.stringify(validated as unknown as TOML.JsonMap);
+  await writeFile(path, body, { encoding: 'utf8', mode: 0o600 });
+}
+
+function isNotFound(err: unknown): boolean {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    'code' in err &&
+    (err as { code?: unknown }).code === 'ENOENT'
+  );
+}
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index f23cae02..09f117f7 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -5,6 +5,7 @@ import { detectProviderFromKey } from '@open-codesign/providers';
 import { BRAND, CodesignError, GeneratePayload } from '@open-codesign/shared';
 import { BrowserWindow, app, ipcMain, shell } from 'electron';
 import { autoUpdater } from 'electron-updater';
+import { getApiKeyForProvider, loadConfigOnBoot, registerOnboardingIpc } from './onboarding-ipc';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -52,11 +53,12 @@ function registerIpcHandlers(): void {
 
   ipcMain.handle('codesign:generate', async (_e, raw: unknown) => {
     const payload = GeneratePayload.parse(raw);
+    const apiKey = getApiKeyForProvider(payload.model.provider);
     return generate({
       prompt: payload.prompt,
       history: payload.history,
       model: payload.model,
-      apiKey: payload.apiKey,
+      apiKey,
       ...(payload.baseUrl !== undefined ? { baseUrl: payload.baseUrl } : {}),
     });
   });
@@ -76,8 +78,10 @@ function setupAutoUpdater(): void {
   ipcMain.handle('codesign:install-update', () => autoUpdater.quitAndInstall());
 }
 
-void app.whenReady().then(() => {
+void app.whenReady().then(async () => {
+  await loadConfigOnBoot();
   registerIpcHandlers();
+  registerOnboardingIpc();
   setupAutoUpdater();
   createWindow();
 
diff --git a/apps/desktop/src/main/keychain.ts b/apps/desktop/src/main/keychain.ts
new file mode 100644
index 00000000..b711ece0
--- /dev/null
+++ b/apps/desktop/src/main/keychain.ts
@@ -0,0 +1,29 @@
+import { CodesignError } from '@open-codesign/shared';
+import { safeStorage } from 'electron';
+
+export function ensureKeychainAvailable(): void {
+  if (!safeStorage.isEncryptionAvailable()) {
+    throw new CodesignError(
+      'OS keychain (safeStorage) is not available. Cannot persist API keys securely.',
+      'KEYCHAIN_UNAVAILABLE',
+    );
+  }
+}
+
+export function encryptSecret(plaintext: string): string {
+  ensureKeychainAvailable();
+  if (plaintext.length === 0) {
+    throw new CodesignError('Cannot encrypt empty secret', 'KEYCHAIN_EMPTY_INPUT');
+  }
+  const buf = safeStorage.encryptString(plaintext);
+  return buf.toString('base64');
+}
+
+export function decryptSecret(ciphertextBase64: string): string {
+  ensureKeychainAvailable();
+  if (ciphertextBase64.length === 0) {
+    throw new CodesignError('Cannot decrypt empty ciphertext', 'KEYCHAIN_EMPTY_INPUT');
+  }
+  const buf = Buffer.from(ciphertextBase64, 'base64');
+  return safeStorage.decryptString(buf);
+}
diff --git a/apps/desktop/src/main/onboarding-ipc.ts b/apps/desktop/src/main/onboarding-ipc.ts
new file mode 100644
index 00000000..6a2018e8
--- /dev/null
+++ b/apps/desktop/src/main/onboarding-ipc.ts
@@ -0,0 +1,157 @@
+import { type ValidateResult, pingProvider } from '@open-codesign/providers';
+import {
+  CodesignError,
+  type Config,
+  type OnboardingState,
+  type SupportedOnboardingProvider,
+  isSupportedOnboardingProvider,
+} from '@open-codesign/shared';
+import { ipcMain } from 'electron';
+import { readConfig, writeConfig } from './config';
+import { decryptSecret, encryptSecret } from './keychain';
+
+interface SaveKeyInput {
+  provider: SupportedOnboardingProvider;
+  apiKey: string;
+  modelPrimary: string;
+  modelFast: string;
+}
+
+interface ValidateKeyInput {
+  provider: SupportedOnboardingProvider;
+  apiKey: string;
+  baseUrl?: string;
+}
+
+let cachedConfig: Config | null = null;
+let configLoaded = false;
+
+export async function loadConfigOnBoot(): Promise<void> {
+  cachedConfig = await readConfig();
+  configLoaded = true;
+}
+
+export function getCachedConfig(): Config | null {
+  if (!configLoaded) {
+    throw new CodesignError('getCachedConfig called before loadConfigOnBoot', 'CONFIG_NOT_LOADED');
+  }
+  return cachedConfig;
+}
+
+export function getApiKeyForProvider(provider: string): string {
+  const cfg = getCachedConfig();
+  if (cfg === null) {
+    throw new CodesignError('No configuration found. Complete onboarding first.', 'CONFIG_MISSING');
+  }
+  const ref = cfg.secrets[provider as keyof typeof cfg.secrets];
+  if (ref === undefined) {
+    throw new CodesignError(
+      `No API key stored for provider "${provider}". Re-run onboarding to add one.`,
+      'PROVIDER_KEY_MISSING',
+    );
+  }
+  return decryptSecret(ref.ciphertext);
+}
+
+function toState(cfg: Config | null): OnboardingState {
+  if (cfg === null) {
+    return { hasKey: false, provider: null, modelPrimary: null, modelFast: null };
+  }
+  if (!isSupportedOnboardingProvider(cfg.provider)) {
+    return { hasKey: false, provider: null, modelPrimary: null, modelFast: null };
+  }
+  const ref = cfg.secrets[cfg.provider];
+  if (ref === undefined) {
+    return { hasKey: false, provider: cfg.provider, modelPrimary: null, modelFast: null };
+  }
+  return {
+    hasKey: true,
+    provider: cfg.provider,
+    modelPrimary: cfg.modelPrimary,
+    modelFast: cfg.modelFast,
+  };
+}
+
+function parseSaveKey(raw: unknown): SaveKeyInput {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new CodesignError('save-key expects an object payload', 'IPC_BAD_INPUT');
+  }
+  const r = raw as Record<string, unknown>;
+  const provider = r['provider'];
+  const apiKey = r['apiKey'];
+  const modelPrimary = r['modelPrimary'];
+  const modelFast = r['modelFast'];
+  if (typeof provider !== 'string' || !isSupportedOnboardingProvider(provider)) {
+    throw new CodesignError(
+      `Provider "${String(provider)}" is not supported in v0.1.`,
+      'PROVIDER_NOT_SUPPORTED',
+    );
+  }
+  if (typeof apiKey !== 'string' || apiKey.trim().length === 0) {
+    throw new CodesignError('apiKey must be a non-empty string', 'IPC_BAD_INPUT');
+  }
+  if (typeof modelPrimary !== 'string' || modelPrimary.trim().length === 0) {
+    throw new CodesignError('modelPrimary must be a non-empty string', 'IPC_BAD_INPUT');
+  }
+  if (typeof modelFast !== 'string' || modelFast.trim().length === 0) {
+    throw new CodesignError('modelFast must be a non-empty string', 'IPC_BAD_INPUT');
+  }
+  return { provider, apiKey, modelPrimary, modelFast };
+}
+
+function parseValidateKey(raw: unknown): ValidateKeyInput {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new CodesignError('validate-key expects an object payload', 'IPC_BAD_INPUT');
+  }
+  const r = raw as Record<string, unknown>;
+  const provider = r['provider'];
+  const apiKey = r['apiKey'];
+  const baseUrl = r['baseUrl'];
+  if (typeof provider !== 'string') {
+    throw new CodesignError('provider must be a string', 'IPC_BAD_INPUT');
+  }
+  if (typeof apiKey !== 'string' || apiKey.trim().length === 0) {
+    throw new CodesignError('apiKey must be a non-empty string', 'IPC_BAD_INPUT');
+  }
+  if (!isSupportedOnboardingProvider(provider)) {
+    throw new CodesignError(
+      `Provider "${provider}" is not supported in v0.1. Only anthropic, openai, openrouter.`,
+      'PROVIDER_NOT_SUPPORTED',
+    );
+  }
+  const out: ValidateKeyInput = { provider, apiKey };
+  if (typeof baseUrl === 'string' && baseUrl.length > 0) out.baseUrl = baseUrl;
+  return out;
+}
+
+export function registerOnboardingIpc(): void {
+  ipcMain.handle('onboarding:get-state', (): OnboardingState => toState(getCachedConfig()));
+
+  ipcMain.handle('onboarding:validate-key', async (_e, raw: unknown): Promise<ValidateResult> => {
+    const input = parseValidateKey(raw);
+    return pingProvider(input.provider, input.apiKey, input.baseUrl);
+  });
+
+  ipcMain.handle('onboarding:save-key', async (_e, raw: unknown): Promise<OnboardingState> => {
+    const input = parseSaveKey(raw);
+    const ciphertext = encryptSecret(input.apiKey);
+    const next: Config = {
+      version: 1,
+      provider: input.provider,
+      modelPrimary: input.modelPrimary,
+      modelFast: input.modelFast,
+      secrets: {
+        ...(cachedConfig?.secrets ?? {}),
+        [input.provider]: { ciphertext },
+      },
+    };
+    await writeConfig(next);
+    cachedConfig = next;
+    configLoaded = true;
+    return toState(cachedConfig);
+  });
+
+  ipcMain.handle('onboarding:skip', async (): Promise<OnboardingState> => {
+    return toState(cachedConfig);
+  });
+}
diff --git a/apps/desktop/src/preload/index.ts b/apps/desktop/src/preload/index.ts
index 1c32bf40..a86afc68 100644
--- a/apps/desktop/src/preload/index.ts
+++ b/apps/desktop/src/preload/index.ts
@@ -1,6 +1,21 @@
-import type { ChatMessage, ModelRef } from '@open-codesign/shared';
+import type {
+  ChatMessage,
+  ModelRef,
+  OnboardingState,
+  SupportedOnboardingProvider,
+} from '@open-codesign/shared';
 import { contextBridge, ipcRenderer } from 'electron';
 
+export interface ValidateKeyResult {
+  ok: true;
+  modelCount: number;
+}
+export interface ValidateKeyError {
+  ok: false;
+  code: '401' | '402' | '429' | 'network';
+  message: string;
+}
+
 const api = {
   detectProvider: (key: string) =>
     ipcRenderer.invoke('codesign:detect-provider', key) as Promise<string | null>,
@@ -8,7 +23,6 @@ const api = {
     prompt: string;
     history: ChatMessage[];
     model: ModelRef;
-    apiKey: string;
     baseUrl?: string;
   }) => ipcRenderer.invoke('codesign:generate', payload),
   checkForUpdates: () => ipcRenderer.invoke('codesign:check-for-updates'),
@@ -19,6 +33,24 @@ const api = {
     ipcRenderer.on('codesign:update-available', listener);
     return () => ipcRenderer.removeListener('codesign:update-available', listener);
   },
+  onboarding: {
+    getState: () => ipcRenderer.invoke('onboarding:get-state') as Promise<OnboardingState>,
+    validateKey: (input: {
+      provider: SupportedOnboardingProvider;
+      apiKey: string;
+      baseUrl?: string;
+    }) =>
+      ipcRenderer.invoke('onboarding:validate-key', input) as Promise<
+        ValidateKeyResult | ValidateKeyError
+      >,
+    saveKey: (input: {
+      provider: SupportedOnboardingProvider;
+      apiKey: string;
+      modelPrimary: string;
+      modelFast: string;
+    }) => ipcRenderer.invoke('onboarding:save-key', input) as Promise<OnboardingState>,
+    skip: () => ipcRenderer.invoke('onboarding:skip') as Promise<OnboardingState>,
+  },
 };
 
 contextBridge.exposeInMainWorld('codesign', api);
diff --git a/apps/desktop/src/renderer/src/App.tsx b/apps/desktop/src/renderer/src/App.tsx
index e761430c..7385a6ed 100644
--- a/apps/desktop/src/renderer/src/App.tsx
+++ b/apps/desktop/src/renderer/src/App.tsx
@@ -2,7 +2,8 @@ import { buildSrcdoc } from '@open-codesign/runtime';
 import { BUILTIN_DEMOS } from '@open-codesign/templates';
 import { Button } from '@open-codesign/ui';
 import { Send, Sparkles } from 'lucide-react';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
+import { Onboarding } from './onboarding';
 import { useCodesignStore } from './store';
 
 export function App() {
@@ -10,8 +11,15 @@ export function App() {
   const previewHtml = useCodesignStore((s) => s.previewHtml);
   const isGenerating = useCodesignStore((s) => s.isGenerating);
   const sendPrompt = useCodesignStore((s) => s.sendPrompt);
+  const config = useCodesignStore((s) => s.config);
+  const configLoaded = useCodesignStore((s) => s.configLoaded);
+  const loadConfig = useCodesignStore((s) => s.loadConfig);
   const [prompt, setPrompt] = useState('');
 
+  useEffect(() => {
+    void loadConfig();
+  }, [loadConfig]);
+
   function handleSubmit(e: React.FormEvent) {
     e.preventDefault();
     if (!prompt.trim() || isGenerating) return;
@@ -19,6 +27,18 @@ export function App() {
     setPrompt('');
   }
 
+  if (!configLoaded) {
+    return (
+      <div className="h-full flex items-center justify-center bg-[var(--color-background)] text-sm text-[var(--color-text-muted)]">
+        Loading…
+      </div>
+    );
+  }
+
+  if (config === null || !config.hasKey) {
+    return <Onboarding />;
+  }
+
   return (
     <div className="h-full grid grid-cols-[380px_1fr] bg-[var(--color-background)]">
       <aside className="flex flex-col border-r border-[var(--color-border)] bg-[var(--color-background-secondary)]">
diff --git a/apps/desktop/src/renderer/src/onboarding/ChooseModel.tsx b/apps/desktop/src/renderer/src/onboarding/ChooseModel.tsx
new file mode 100644
index 00000000..918d3044
--- /dev/null
+++ b/apps/desktop/src/renderer/src/onboarding/ChooseModel.tsx
@@ -0,0 +1,103 @@
+import { PROVIDER_SHORTLIST, type SupportedOnboardingProvider } from '@open-codesign/shared';
+import { Button } from '@open-codesign/ui';
+import { useState } from 'react';
+
+interface ChooseModelProps {
+  provider: SupportedOnboardingProvider;
+  saving: boolean;
+  errorMessage: string | null;
+  onConfirm: (modelPrimary: string, modelFast: string) => void;
+  onBack: () => void;
+}
+
+export function ChooseModel({
+  provider,
+  saving,
+  errorMessage,
+  onConfirm,
+  onBack,
+}: ChooseModelProps) {
+  const shortlist = PROVIDER_SHORTLIST[provider];
+  const [modelPrimary, setModelPrimary] = useState(shortlist.defaultPrimary);
+  const [modelFast, setModelFast] = useState(shortlist.defaultFast);
+
+  return (
+    <div className="flex flex-col gap-5">
+      <div>
+        <h2 className="text-xl font-semibold text-[var(--color-text-primary)] mb-1">
+          Pick default models
+        </h2>
+        <p className="text-sm text-[var(--color-text-secondary)]">
+          Recommended starters for {shortlist.label}. Switchable per-design later.
+        </p>
+      </div>
+
+      <ModelPicker
+        label="Primary design model"
+        hint="Used for full design generation."
+        value={modelPrimary}
+        options={shortlist.primary}
+        onChange={setModelPrimary}
+      />
+      <ModelPicker
+        label="Fast completion model"
+        hint="Used for quick edits and inline tweaks."
+        value={modelFast}
+        options={shortlist.fast}
+        onChange={setModelFast}
+      />
+
+      <p className="text-xs text-[var(--color-text-muted)]">
+        Estimated cost: ~$0.01–0.05 per design session (varies by provider and prompt length).
+      </p>
+
+      {errorMessage !== null ? (
+        <p className="text-sm text-[var(--color-error)]">{errorMessage}</p>
+      ) : null}
+
+      <div className="flex justify-between gap-2 pt-2">
+        <Button type="button" variant="ghost" onClick={onBack} disabled={saving}>
+          Back
+        </Button>
+        <Button
+          type="button"
+          variant="primary"
+          onClick={() => onConfirm(modelPrimary, modelFast)}
+          disabled={saving}
+        >
+          {saving ? 'Saving…' : 'Finish'}
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+interface ModelPickerProps {
+  label: string;
+  hint: string;
+  value: string;
+  options: string[];
+  onChange: (next: string) => void;
+}
+
+function ModelPicker({ label, hint, value, options, onChange }: ModelPickerProps) {
+  return (
+    <label className="flex flex-col gap-2">
+      <span className="text-xs uppercase tracking-wide text-[var(--color-text-muted)]">
+        {label}
+      </span>
+      <select
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        className="w-full px-3 py-2 rounded-[var(--radius-md)] bg-[var(--color-surface)] border border-[var(--color-border)] text-sm text-[var(--color-text-primary)] focus:outline-none focus:border-[var(--color-accent)]"
+      >
+        {options.map((opt) => (
+          <option key={opt} value={opt}>
+            {opt}
+          </option>
+        ))}
+      </select>
+      <span className="text-xs text-[var(--color-text-muted)]">{hint}</span>
+    </label>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/onboarding/PasteKey.tsx b/apps/desktop/src/renderer/src/onboarding/PasteKey.tsx
new file mode 100644
index 00000000..102d108d
--- /dev/null
+++ b/apps/desktop/src/renderer/src/onboarding/PasteKey.tsx
@@ -0,0 +1,238 @@
+import {
+  PROVIDER_SHORTLIST,
+  type SupportedOnboardingProvider,
+  isSupportedOnboardingProvider,
+} from '@open-codesign/shared';
+import { Button } from '@open-codesign/ui';
+import { AlertCircle, CheckCircle2, ExternalLink, Loader2 } from 'lucide-react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { ValidateKeyError, ValidateKeyResult } from '../../../preload/index';
+
+const VALIDATE_DEBOUNCE_MS = 500;
+
+type ValidationState =
+  | { kind: 'idle' }
+  | { kind: 'detecting' }
+  | { kind: 'validating' }
+  | { kind: 'ok'; modelCount: number }
+  | { kind: 'error'; code: ValidateKeyError['code'] | 'unsupported'; message: string };
+
+interface PasteKeyProps {
+  onValidated: (provider: SupportedOnboardingProvider, apiKey: string) => void;
+  onBack: () => void;
+}
+
+export function PasteKey({ onValidated, onBack }: PasteKeyProps) {
+  const [apiKey, setApiKey] = useState('');
+  const [provider, setProvider] = useState<SupportedOnboardingProvider | null>(null);
+  const [state, setState] = useState<ValidationState>({ kind: 'idle' });
+  const reqIdRef = useRef(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  const trimmed = apiKey.trim();
+
+  useEffect(() => {
+    if (trimmed.length === 0) {
+      setProvider(null);
+      setState({ kind: 'idle' });
+      return;
+    }
+
+    setState({ kind: 'detecting' });
+    const reqId = ++reqIdRef.current;
+
+    const handle = window.setTimeout(async () => {
+      if (!window.codesign) {
+        setState({
+          kind: 'error',
+          code: 'network',
+          message: 'Renderer is not connected to the main process.',
+        });
+        return;
+      }
+      let detected: string | null;
+      try {
+        detected = await window.codesign.detectProvider(trimmed);
+      } catch (err) {
+        if (reqId !== reqIdRef.current) return;
+        setState({
+          kind: 'error',
+          code: 'network',
+          message: err instanceof Error ? err.message : 'Provider detection failed.',
+        });
+        return;
+      }
+      if (reqId !== reqIdRef.current) return;
+
+      if (detected === null) {
+        setProvider(null);
+        setState({
+          kind: 'error',
+          code: 'unsupported',
+          message:
+            'Unrecognized key prefix. Supported: sk-ant- (Anthropic), sk- (OpenAI), sk-or- (OpenRouter).',
+        });
+        return;
+      }
+      if (!isSupportedOnboardingProvider(detected)) {
+        setProvider(null);
+        setState({
+          kind: 'error',
+          code: 'unsupported',
+          message: `${detected} is not supported in v0.1. Use Anthropic, OpenAI, or OpenRouter.`,
+        });
+        return;
+      }
+      setProvider(detected);
+      setState({ kind: 'validating' });
+
+      let result: ValidateKeyResult | ValidateKeyError;
+      try {
+        result = await window.codesign.onboarding.validateKey({
+          provider: detected,
+          apiKey: trimmed,
+        });
+      } catch (err) {
+        if (reqId !== reqIdRef.current) return;
+        setState({
+          kind: 'error',
+          code: 'network',
+          message: err instanceof Error ? err.message : 'Validation request failed.',
+        });
+        return;
+      }
+      if (reqId !== reqIdRef.current) return;
+
+      if (result.ok) {
+        setState({ kind: 'ok', modelCount: result.modelCount });
+      } else {
+        setState({ kind: 'error', code: result.code, message: result.message });
+      }
+    }, VALIDATE_DEBOUNCE_MS);
+
+    return () => window.clearTimeout(handle);
+  }, [trimmed]);
+
+  const helpUrl = useMemo(() => {
+    if (provider === null) return null;
+    return PROVIDER_SHORTLIST[provider].keyHelpUrl;
+  }, [provider]);
+
+  function handleContinue() {
+    if (state.kind !== 'ok' || provider === null) return;
+    onValidated(provider, trimmed);
+  }
+
+  return (
+    <div className="flex flex-col gap-5">
+      <div>
+        <h2 className="text-xl font-semibold text-[var(--color-text-primary)] mb-1">
+          Paste your API key
+        </h2>
+        <p className="text-sm text-[var(--color-text-secondary)]">
+          We auto-detect the provider and validate against /v1/models. Your key is encrypted with
+          the OS keychain.
+        </p>
+      </div>
+
+      <label className="flex flex-col gap-2">
+        <span className="text-xs uppercase tracking-wide text-[var(--color-text-muted)]">
+          API key
+        </span>
+        <input
+          ref={inputRef}
+          type="password"
+          value={apiKey}
+          onChange={(e) => setApiKey(e.target.value)}
+          placeholder="sk-ant-…  /  sk-…  /  sk-or-…"
+          spellCheck={false}
+          className="w-full px-3 py-2 rounded-[var(--radius-md)] bg-[var(--color-surface)] border border-[var(--color-border)] text-sm font-mono text-[var(--color-text-primary)] placeholder:text-[var(--color-text-muted)] focus:outline-none focus:border-[var(--color-accent)]"
+        />
+      </label>
+
+      <StatusLine provider={provider} state={state} helpUrl={helpUrl} />
+
+      <div className="flex justify-between gap-2 pt-2">
+        <Button type="button" variant="ghost" onClick={onBack}>
+          Back
+        </Button>
+        <Button
+          type="button"
+          variant="primary"
+          onClick={handleContinue}
+          disabled={state.kind !== 'ok'}
+        >
+          Continue
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+interface StatusLineProps {
+  provider: SupportedOnboardingProvider | null;
+  state: ValidationState;
+  helpUrl: string | null;
+}
+
+function StatusLine({ provider, state, helpUrl }: StatusLineProps) {
+  if (state.kind === 'idle') {
+    return (
+      <p className="text-xs text-[var(--color-text-muted)]">
+        Paste a key to detect the provider and validate live.
+      </p>
+    );
+  }
+  if (state.kind === 'detecting') {
+    return <Pending text="Detecting provider…" />;
+  }
+  if (state.kind === 'validating') {
+    return (
+      <Pending
+        text={`Recognized: ${provider ? PROVIDER_SHORTLIST[provider].label : 'unknown'} — validating…`}
+      />
+    );
+  }
+  if (state.kind === 'ok') {
+    return (
+      <div className="text-sm text-[var(--color-success)] flex items-center gap-2">
+        <CheckCircle2 className="w-4 h-4 shrink-0" />
+        <span>
+          Recognized: {provider ? PROVIDER_SHORTLIST[provider].label : 'provider'} — Connected (
+          {state.modelCount} models)
+        </span>
+      </div>
+    );
+  }
+  return (
+    <div className="text-sm text-[var(--color-error)] flex flex-col gap-1">
+      <span className="flex items-start gap-2">
+        <AlertCircle className="w-4 h-4 shrink-0 mt-0.5" />
+        <span>{state.message}</span>
+      </span>
+      {helpUrl !== null ? (
+        <a
+          href={helpUrl}
+          target="_blank"
+          rel="noreferrer"
+          className="ml-6 inline-flex items-center gap-1 text-xs text-[var(--color-accent)] hover:underline"
+        >
+          How to get a key <ExternalLink className="w-3 h-3" />
+        </a>
+      ) : null}
+    </div>
+  );
+}
+
+function Pending({ text }: { text: string }) {
+  return (
+    <div className="text-sm text-[var(--color-text-secondary)] flex items-center gap-2">
+      <Loader2 className="w-4 h-4 animate-spin" />
+      <span>{text}</span>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/onboarding/Welcome.tsx b/apps/desktop/src/renderer/src/onboarding/Welcome.tsx
new file mode 100644
index 00000000..3b9dbebb
--- /dev/null
+++ b/apps/desktop/src/renderer/src/onboarding/Welcome.tsx
@@ -0,0 +1,91 @@
+import { PROVIDER_SHORTLIST, type SupportedOnboardingProvider } from '@open-codesign/shared';
+import { Button } from '@open-codesign/ui';
+import { ExternalLink, KeyRound, Rocket, Server } from 'lucide-react';
+
+interface WelcomeProps {
+  onPickKey: () => void;
+  onPickFreeTier: () => void;
+  ollamaDetected: boolean;
+}
+
+export function Welcome({ onPickKey, onPickFreeTier, ollamaDetected }: WelcomeProps) {
+  return (
+    <div className="flex flex-col gap-6">
+      <div>
+        <h2 className="text-2xl font-semibold text-[var(--color-text-primary)] mb-2">
+          Welcome to open-codesign
+        </h2>
+        <p className="text-sm text-[var(--color-text-secondary)]">
+          Pick how you want to power your designs. You can change this later in Settings.
+        </p>
+      </div>
+
+      <div className="grid gap-3">
+        <PathButton
+          icon={<Rocket className="w-5 h-5 text-[var(--color-accent)]" />}
+          title="Try free now"
+          subtitle="OpenRouter free tier — paste an OpenRouter key, then pick a free model."
+          onClick={onPickFreeTier}
+        />
+        <PathButton
+          icon={<KeyRound className="w-5 h-5 text-[var(--color-accent)]" />}
+          title="Use my API key"
+          subtitle="Anthropic, OpenAI, or OpenRouter. Auto-detected from the key prefix."
+          onClick={onPickKey}
+        />
+        {ollamaDetected ? (
+          <PathButton
+            icon={<Server className="w-5 h-5 text-[var(--color-text-muted)]" />}
+            title="Use local model (Ollama detected)"
+            subtitle="Coming in v0.2 — Ollama integration is on the roadmap."
+            disabled
+          />
+        ) : null}
+      </div>
+
+      <div className="text-xs text-[var(--color-text-muted)] flex flex-wrap gap-x-4 gap-y-1">
+        {(
+          Object.values(PROVIDER_SHORTLIST) as Array<
+            (typeof PROVIDER_SHORTLIST)[SupportedOnboardingProvider]
+          >
+        ).map((p) => (
+          <a
+            key={p.provider}
+            href={p.keyHelpUrl}
+            target="_blank"
+            rel="noreferrer"
+            className="inline-flex items-center gap-1 text-[var(--color-text-muted)] hover:text-[var(--color-accent)]"
+          >
+            How to get a {p.label} key <ExternalLink className="w-3 h-3" />
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+interface PathButtonProps {
+  icon: React.ReactNode;
+  title: string;
+  subtitle: string;
+  onClick?: () => void;
+  disabled?: boolean;
+}
+
+function PathButton({ icon, title, subtitle, onClick, disabled }: PathButtonProps) {
+  return (
+    <Button
+      variant="secondary"
+      size="lg"
+      onClick={onClick}
+      disabled={disabled}
+      className="!h-auto !justify-start text-left py-4"
+    >
+      <span className="shrink-0">{icon}</span>
+      <span className="flex flex-col items-start gap-0.5">
+        <span className="text-sm font-medium text-[var(--color-text-primary)]">{title}</span>
+        <span className="text-xs text-[var(--color-text-muted)] font-normal">{subtitle}</span>
+      </span>
+    </Button>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/onboarding/index.tsx b/apps/desktop/src/renderer/src/onboarding/index.tsx
new file mode 100644
index 00000000..75bf9168
--- /dev/null
+++ b/apps/desktop/src/renderer/src/onboarding/index.tsx
@@ -0,0 +1,93 @@
+import { PROVIDER_SHORTLIST, type SupportedOnboardingProvider } from '@open-codesign/shared';
+import { Sparkles } from 'lucide-react';
+import { useState } from 'react';
+import { useCodesignStore } from '../store';
+import { ChooseModel } from './ChooseModel';
+import { PasteKey } from './PasteKey';
+import { Welcome } from './Welcome';
+
+type Step = 'welcome' | 'paste' | 'model';
+
+export function Onboarding() {
+  const completeOnboarding = useCodesignStore((s) => s.completeOnboarding);
+  const [step, setStep] = useState<Step>('welcome');
+  const [provider, setProvider] = useState<SupportedOnboardingProvider | null>(null);
+  const [apiKey, setApiKey] = useState('');
+  const [saving, setSaving] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  function handleValidated(p: SupportedOnboardingProvider, key: string) {
+    setProvider(p);
+    setApiKey(key);
+    setStep('model');
+  }
+
+  async function handleConfirm(modelPrimary: string, modelFast: string) {
+    if (provider === null) return;
+    if (!window.codesign) {
+      setErrorMessage('Renderer is not connected to the main process.');
+      return;
+    }
+    setSaving(true);
+    setErrorMessage(null);
+    try {
+      const next = await window.codesign.onboarding.saveKey({
+        provider,
+        apiKey,
+        modelPrimary,
+        modelFast,
+      });
+      completeOnboarding(next);
+    } catch (err) {
+      setErrorMessage(err instanceof Error ? err.message : 'Failed to save key.');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <div className="h-full flex items-center justify-center bg-[var(--color-background)] px-6 py-8">
+      <div className="w-full max-w-md bg-[var(--color-surface)] border border-[var(--color-border)] rounded-[var(--radius-2xl)] shadow-[var(--shadow-card)] p-8 flex flex-col gap-6">
+        <header className="flex items-center gap-2">
+          <Sparkles className="w-5 h-5 text-[var(--color-accent)]" />
+          <span className="font-semibold text-[var(--color-text-primary)]">open-codesign</span>
+          <span className="ml-auto text-xs text-[var(--color-text-muted)]">
+            Step {stepIndex(step)} of 3
+          </span>
+        </header>
+
+        {step === 'welcome' ? (
+          <Welcome
+            onPickKey={() => setStep('paste')}
+            onPickFreeTier={() => {
+              setProvider('openrouter');
+              setStep('paste');
+            }}
+            ollamaDetected={false}
+          />
+        ) : null}
+        {step === 'paste' ? (
+          <PasteKey onValidated={handleValidated} onBack={() => setStep('welcome')} />
+        ) : null}
+        {step === 'model' && provider !== null ? (
+          <ChooseModel
+            provider={provider}
+            saving={saving}
+            errorMessage={errorMessage}
+            onConfirm={handleConfirm}
+            onBack={() => setStep('paste')}
+          />
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function stepIndex(step: Step): number {
+  if (step === 'welcome') return 1;
+  if (step === 'paste') return 2;
+  return 3;
+}
+
+// Re-export for convenience.
+export { PROVIDER_SHORTLIST };
diff --git a/apps/desktop/src/renderer/src/store.ts b/apps/desktop/src/renderer/src/store.ts
index f6e701d6..d98d7b21 100644
--- a/apps/desktop/src/renderer/src/store.ts
+++ b/apps/desktop/src/renderer/src/store.ts
@@ -1,4 +1,9 @@
-import type { ChatMessage } from '@open-codesign/shared';
+import type {
+  ChatMessage,
+  ModelRef,
+  OnboardingState,
+  SupportedOnboardingProvider,
+} from '@open-codesign/shared';
 import { create } from 'zustand';
 import type { CodesignApi } from '../../preload/index';
 
@@ -13,14 +18,40 @@ interface CodesignState {
   previewHtml: string | null;
   isGenerating: boolean;
   errorMessage: string | null;
+  config: OnboardingState | null;
+  configLoaded: boolean;
+  loadConfig: () => Promise<void>;
+  completeOnboarding: (next: OnboardingState) => void;
   sendPrompt: (prompt: string) => Promise<void>;
 }
 
+function modelRef(provider: SupportedOnboardingProvider, modelId: string): ModelRef {
+  return { provider, modelId };
+}
+
 export const useCodesignStore = create<CodesignState>((set, get) => ({
   messages: [],
   previewHtml: null,
   isGenerating: false,
   errorMessage: null,
+  config: null,
+  configLoaded: false,
+
+  async loadConfig() {
+    if (!window.codesign) {
+      set({
+        configLoaded: true,
+        errorMessage: 'Renderer is not connected to the main process.',
+      });
+      return;
+    }
+    const state = await window.codesign.onboarding.getState();
+    set({ config: state, configLoaded: true });
+  },
+
+  completeOnboarding(next: OnboardingState) {
+    set({ config: next });
+  },
 
   async sendPrompt(prompt: string) {
     if (get().isGenerating) return;
@@ -28,6 +59,11 @@ export const useCodesignStore = create<CodesignState>((set, get) => ({
       set({ errorMessage: 'Renderer is not connected to the main process.' });
       return;
     }
+    const cfg = get().config;
+    if (cfg === null || !cfg.hasKey || cfg.provider === null || cfg.modelPrimary === null) {
+      set({ errorMessage: 'Onboarding is not complete.' });
+      return;
+    }
 
     const userMessage: ChatMessage = { role: 'user', content: prompt };
     set((s) => ({
@@ -36,30 +72,11 @@ export const useCodesignStore = create<CodesignState>((set, get) => ({
       errorMessage: null,
     }));
 
-    // Tier 1 wiring: hardcoded provider/model and key-from-env until the
-    // onboarding flow lands. The real flow will read from the keychain.
-    const apiKey = '';
-    if (!apiKey) {
-      set((s) => ({
-        messages: [
-          ...s.messages,
-          {
-            role: 'assistant',
-            content:
-              'No API key configured yet. Onboarding flow coming in v0.1 — see docs/research/06-api-onboarding-ux.md.',
-          },
-        ],
-        isGenerating: false,
-      }));
-      return;
-    }
-
     try {
       const result = await window.codesign.generate({
         prompt,
         history: get().messages,
-        model: { provider: 'anthropic', modelId: 'claude-sonnet-4-6' },
-        apiKey,
+        model: modelRef(cfg.provider, cfg.modelPrimary),
       });
       const firstArtifact = (result as { artifacts: Array<{ content: string }> }).artifacts[0];
       const message = (result as { message: string }).message;
diff --git a/docs/CONFIG.md b/docs/CONFIG.md
new file mode 100644
index 00000000..1403e269
--- /dev/null
+++ b/docs/CONFIG.md
@@ -0,0 +1,64 @@
+# Configuration
+
+open-codesign stores configuration in a TOML file at `~/.config/open-codesign/config.toml`
+(or `$XDG_CONFIG_HOME/open-codesign/config.toml` if set). The file is created on first
+successful onboarding and is the single source of truth for provider, model, and key
+references.
+
+## Layout
+
+```toml
+version = 1
+provider = "anthropic"
+modelPrimary = "claude-sonnet-4-6"
+modelFast = "claude-haiku-3"
+
+[secrets.anthropic]
+ciphertext = "<base64 ciphertext>"
+```
+
+## Keys
+
+| Key | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `version` | integer | yes | `1` | Schema version. Must be `1` in v0.1. |
+| `provider` | string | yes | — | Active provider id. Tier 1: `anthropic`, `openai`, `openrouter`. |
+| `modelPrimary` | string | yes | — | Primary design model id (provider-specific). |
+| `modelFast` | string | yes | — | Fast completion model id (provider-specific). |
+| `secrets.<provider>.ciphertext` | string | yes for active provider | — | Base64-encoded ciphertext from Electron `safeStorage` (macOS Keychain / Windows Credential Manager / DPAPI on Linux when available). |
+
+## Security model
+
+- API keys are **never written in plaintext**. The renderer pastes a key,
+  the main process encrypts it with Electron `safeStorage.encryptString` and
+  stores only the base64 ciphertext.
+- The keychain is bound to the OS user account. Copying `config.toml` to
+  another machine does **not** decrypt the secret — the user must re-onboard.
+- File permissions are set to `0600` on POSIX systems.
+
+## Behavior on first run
+
+If the file does not exist, the renderer shows the 3-step onboarding wizard
+(Welcome → Paste API key → Choose models). On completion the file is written
+and subsequent launches skip the wizard.
+
+If the file exists but is malformed, parsing throws `CONFIG_PARSE_FAILED` /
+`CONFIG_SCHEMA_INVALID` and the app surfaces the error in the UI — there is
+**no silent fallback** to defaults.
+
+## Adding new providers
+
+Tier 1 hard-codes `anthropic`, `openai`, `openrouter`. Other providers are
+parsed by the schema (so a future config file with `provider = "google"` is
+not rejected outright) but the onboarding wizard refuses them with
+`PROVIDER_NOT_SUPPORTED`. Wider provider support lands in Phase 0.3.
+
+## Resetting
+
+Delete the file:
+
+```bash
+rm ~/.config/open-codesign/config.toml
+```
+
+The next launch returns to the onboarding wizard.
diff --git a/packages/providers/src/index.ts b/packages/providers/src/index.ts
index 33286a18..08d296fa 100644
--- a/packages/providers/src/index.ts
+++ b/packages/providers/src/index.ts
@@ -98,6 +98,9 @@ export function detectProviderFromKey(key: string): ModelRef['provider'] | null
   return null;
 }
 
+export { pingProvider } from './validate';
+export type { ValidateResult } from './validate';
+
 // Tier 2 surface (not yet implemented):
 //   structuredComplete<T>(model, schema, messages, opts): Promise<T>
 //   streamArtifacts(model, messages, opts): AsyncIterable<ArtifactEvent>
diff --git a/packages/providers/src/validate.test.ts b/packages/providers/src/validate.test.ts
new file mode 100644
index 00000000..9fb2a105
--- /dev/null
+++ b/packages/providers/src/validate.test.ts
@@ -0,0 +1,97 @@
+import { CodesignError } from '@open-codesign/shared';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { pingProvider } from './validate';
+
+const originalFetch = globalThis.fetch;
+
+function mockFetch(impl: (url: string, init?: RequestInit) => Promise<Response> | Response) {
+  globalThis.fetch = vi.fn(impl) as unknown as typeof fetch;
+}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe('pingProvider', () => {
+  it('throws CodesignError for unsupported providers', async () => {
+    await expect(pingProvider('google', 'AIza-foo')).rejects.toBeInstanceOf(CodesignError);
+  });
+
+  it('throws when key is empty', async () => {
+    await expect(pingProvider('anthropic', '')).rejects.toBeInstanceOf(CodesignError);
+  });
+
+  it('returns ok with model count for Anthropic 200', async () => {
+    mockFetch(async (url, init) => {
+      expect(url).toBe('https://api.anthropic.com/v1/models');
+      const headers = (init?.headers ?? {}) as Record<string, string>;
+      expect(headers['x-api-key']).toBe('sk-ant-test');
+      expect(headers['anthropic-version']).toBe('2023-06-01');
+      return new Response(JSON.stringify({ data: [{ id: 'a' }, { id: 'b' }, { id: 'c' }] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+    const result = await pingProvider('anthropic', 'sk-ant-test');
+    expect(result).toEqual({ ok: true, modelCount: 3 });
+  });
+
+  it('returns 401 code on Anthropic 401', async () => {
+    mockFetch(async () => new Response('unauth', { status: 401 }));
+    const result = await pingProvider('anthropic', 'sk-ant-bad');
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.code).toBe('401');
+      expect(result.message).toContain('anthropic');
+    }
+  });
+
+  it('returns 402 code on payment required', async () => {
+    mockFetch(async () => new Response('no credit', { status: 402 }));
+    const result = await pingProvider('openai', 'sk-test');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.code).toBe('402');
+  });
+
+  it('returns 429 code on rate limit', async () => {
+    mockFetch(async () => new Response('slow', { status: 429 }));
+    const result = await pingProvider('openrouter', 'sk-or-test');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.code).toBe('429');
+  });
+
+  it('returns network code when fetch throws', async () => {
+    mockFetch(async () => {
+      throw new Error('ECONNREFUSED');
+    });
+    const result = await pingProvider('openai', 'sk-test');
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.code).toBe('network');
+      expect(result.message).toContain('ECONNREFUSED');
+    }
+  });
+
+  it('uses Bearer auth header for OpenAI', async () => {
+    mockFetch(async (url, init) => {
+      expect(url).toBe('https://api.openai.com/v1/models');
+      const headers = (init?.headers ?? {}) as Record<string, string>;
+      expect(headers['authorization']).toBe('Bearer sk-test');
+      return new Response(JSON.stringify({ data: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+    const result = await pingProvider('openai', 'sk-test');
+    expect(result).toEqual({ ok: true, modelCount: 0 });
+  });
+
+  it('respects custom baseUrl', async () => {
+    mockFetch(async (url) => {
+      expect(url).toBe('https://proxy.example/v1/models');
+      return new Response(JSON.stringify({ data: [{ id: 'x' }] }), { status: 200 });
+    });
+    const result = await pingProvider('openrouter', 'sk-or-test', 'https://proxy.example');
+    expect(result).toEqual({ ok: true, modelCount: 1 });
+  });
+});
diff --git a/packages/providers/src/validate.ts b/packages/providers/src/validate.ts
new file mode 100644
index 00000000..2cc6f136
--- /dev/null
+++ b/packages/providers/src/validate.ts
@@ -0,0 +1,114 @@
+import {
+  CodesignError,
+  type SupportedOnboardingProvider,
+  isSupportedOnboardingProvider,
+} from '@open-codesign/shared';
+
+export type ValidateResult =
+  | { ok: true; modelCount: number }
+  | { ok: false; code: '401' | '402' | '429' | 'network'; message: string };
+
+interface ProviderEndpoint {
+  url: string;
+  headers: (apiKey: string) => Record<string, string>;
+}
+
+function endpoint(provider: SupportedOnboardingProvider, baseUrl?: string): ProviderEndpoint {
+  switch (provider) {
+    case 'anthropic':
+      return {
+        url: `${baseUrl ?? 'https://api.anthropic.com'}/v1/models`,
+        headers: (apiKey) => ({
+          'x-api-key': apiKey,
+          'anthropic-version': '2023-06-01',
+        }),
+      };
+    case 'openai':
+      return {
+        url: `${baseUrl ?? 'https://api.openai.com'}/v1/models`,
+        headers: (apiKey) => ({ authorization: `Bearer ${apiKey}` }),
+      };
+    case 'openrouter':
+      return {
+        url: `${baseUrl ?? 'https://openrouter.ai/api'}/v1/models`,
+        headers: (apiKey) => ({ authorization: `Bearer ${apiKey}` }),
+      };
+  }
+}
+
+function statusToCode(status: number): '401' | '402' | '429' | null {
+  if (status === 401 || status === 403) return '401';
+  if (status === 402) return '402';
+  if (status === 429) return '429';
+  return null;
+}
+
+function statusMessage(provider: SupportedOnboardingProvider, status: number): string {
+  if (status === 401 || status === 403) {
+    return `Invalid ${provider} API key (HTTP ${status}). Double-check the key, then try again.`;
+  }
+  if (status === 402) {
+    return `${provider} reports the account has no credit (HTTP 402). Add billing or pick another provider.`;
+  }
+  if (status === 429) {
+    return `${provider} rate-limited the validation request (HTTP 429). Wait a moment and retry.`;
+  }
+  return `${provider} returned HTTP ${status}.`;
+}
+
+export async function pingProvider(
+  provider: string,
+  apiKey: string,
+  baseUrl?: string,
+): Promise<ValidateResult> {
+  if (!isSupportedOnboardingProvider(provider)) {
+    throw new CodesignError(
+      `Provider "${provider}" is not supported in v0.1. Supported: anthropic, openai, openrouter.`,
+      'PROVIDER_NOT_SUPPORTED',
+    );
+  }
+  if (!apiKey || apiKey.trim().length === 0) {
+    throw new CodesignError('API key is empty', 'PROVIDER_AUTH_MISSING');
+  }
+
+  const ep = endpoint(provider, baseUrl);
+  let res: Response;
+  try {
+    res = await fetch(ep.url, { method: 'GET', headers: ep.headers(apiKey) });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Network request failed';
+    return { ok: false, code: 'network', message };
+  }
+
+  if (!res.ok) {
+    const code = statusToCode(res.status);
+    if (code !== null) {
+      return { ok: false, code, message: statusMessage(provider, res.status) };
+    }
+    return {
+      ok: false,
+      code: 'network',
+      message: `${provider} returned an unexpected HTTP ${res.status}.`,
+    };
+  }
+
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Invalid JSON in response';
+    return { ok: false, code: 'network', message };
+  }
+
+  const modelCount = countModels(body);
+  return { ok: true, modelCount };
+}
+
+function countModels(body: unknown): number {
+  if (body === null || typeof body !== 'object') return 0;
+  const data = (body as { data?: unknown }).data;
+  if (Array.isArray(data)) return data.length;
+  const models = (body as { models?: unknown }).models;
+  if (Array.isArray(models)) return models.length;
+  return 0;
+}
diff --git a/packages/shared/src/config.ts b/packages/shared/src/config.ts
new file mode 100644
index 00000000..8f17b7da
--- /dev/null
+++ b/packages/shared/src/config.ts
@@ -0,0 +1,83 @@
+import { z } from 'zod';
+
+const ProviderIdEnum = z.enum([
+  'anthropic',
+  'openai',
+  'google',
+  'openrouter',
+  'groq',
+  'cerebras',
+  'xai',
+  'mistral',
+  'amazon-bedrock',
+  'azure-openai-responses',
+  'vercel-ai-gateway',
+]);
+
+export const SUPPORTED_ONBOARDING_PROVIDERS = ['anthropic', 'openai', 'openrouter'] as const;
+export type SupportedOnboardingProvider = (typeof SUPPORTED_ONBOARDING_PROVIDERS)[number];
+
+export const SecretRef = z.object({
+  ciphertext: z.string().min(1),
+});
+export type SecretRef = z.infer<typeof SecretRef>;
+
+export const ConfigSchema = z.object({
+  version: z.literal(1).default(1),
+  provider: ProviderIdEnum,
+  modelPrimary: z.string().min(1),
+  modelFast: z.string().min(1),
+  secrets: z.record(ProviderIdEnum, SecretRef).default({}),
+});
+export type Config = z.infer<typeof ConfigSchema>;
+
+export interface OnboardingState {
+  hasKey: boolean;
+  provider: SupportedOnboardingProvider | null;
+  modelPrimary: string | null;
+  modelFast: string | null;
+}
+
+export interface ProviderShortlist {
+  provider: SupportedOnboardingProvider;
+  label: string;
+  keyHelpUrl: string;
+  primary: string[];
+  fast: string[];
+  defaultPrimary: string;
+  defaultFast: string;
+}
+
+export const PROVIDER_SHORTLIST: Record<SupportedOnboardingProvider, ProviderShortlist> = {
+  anthropic: {
+    provider: 'anthropic',
+    label: 'Anthropic Claude',
+    keyHelpUrl: 'https://console.anthropic.com/settings/keys',
+    primary: ['claude-sonnet-4-6', 'claude-opus-4-1'],
+    fast: ['claude-haiku-3', 'claude-sonnet-4-6'],
+    defaultPrimary: 'claude-sonnet-4-6',
+    defaultFast: 'claude-haiku-3',
+  },
+  openai: {
+    provider: 'openai',
+    label: 'OpenAI',
+    keyHelpUrl: 'https://platform.openai.com/api-keys',
+    primary: ['gpt-4o', 'gpt-4.1'],
+    fast: ['gpt-4o-mini', 'gpt-4.1-mini'],
+    defaultPrimary: 'gpt-4o',
+    defaultFast: 'gpt-4o-mini',
+  },
+  openrouter: {
+    provider: 'openrouter',
+    label: 'OpenRouter',
+    keyHelpUrl: 'https://openrouter.ai/keys',
+    primary: ['anthropic/claude-sonnet-4.6', 'openai/gpt-4o'],
+    fast: ['anthropic/claude-haiku-3', 'openai/gpt-4o-mini'],
+    defaultPrimary: 'anthropic/claude-sonnet-4.6',
+    defaultFast: 'anthropic/claude-haiku-3',
+  },
+};
+
+export function isSupportedOnboardingProvider(p: string): p is SupportedOnboardingProvider {
+  return (SUPPORTED_ONBOARDING_PROVIDERS as readonly string[]).includes(p);
+}
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index ce140d9f..fb90f245 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -84,7 +84,6 @@ export const GeneratePayload = z.object({
   prompt: z.string().min(1).max(32_000),
   history: z.array(ChatMessage).max(200),
   model: ModelRef,
-  apiKey: z.string().min(1).max(500),
   baseUrl: z.string().url().optional(),
 });
 export type GeneratePayload = z.infer<typeof GeneratePayload>;
@@ -103,3 +102,17 @@ export class CodesignError extends Error {
     this.name = 'CodesignError';
   }
 }
+
+export {
+  ConfigSchema,
+  PROVIDER_SHORTLIST,
+  SUPPORTED_ONBOARDING_PROVIDERS,
+  SecretRef,
+  isSupportedOnboardingProvider,
+} from './config';
+export type {
+  Config,
+  OnboardingState,
+  ProviderShortlist,
+  SupportedOnboardingProvider,
+} from './config';
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 29b55268..48e06684 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -23,6 +23,9 @@ importers:
 
   apps/desktop:
     dependencies:
+      '@iarna/toml':
+        specifier: ^2.2.5
+        version: 2.2.5
       '@open-codesign/artifacts':
         specifier: workspace:*
         version: link:../../packages/artifacts
@@ -913,6 +916,9 @@ packages:
       '@modelcontextprotocol/sdk':
         optional: true
 
+  '@iarna/toml@2.2.5':
+    resolution: {integrity: sha512-trnsAYxU3xnS1gPHPyU961coFyLkh4gAD/0zQ5mymY4yOZ+CYvsPqUbOFSw0aDM4y0tV7tiFxL/1XfXPNC6IPg==}
+
   '@inquirer/external-editor@1.0.3':
     resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==}
     engines: {node: '>=18'}
@@ -4590,6 +4596,8 @@ snapshots:
       - supports-color
       - utf-8-validate
 
+  '@iarna/toml@2.2.5': {}
+
   '@inquirer/external-editor@1.0.3(@types/node@22.19.17)':
     dependencies:
       chardet: 2.1.1