@kidsinai/kids-client 0.0.3 → 0.0.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "description": "Own-client TUI for Kids OpenCode — talks to local `opencode serve` via @opencode-ai/sdk v2 with kid-warm rendering, mission progress, permission dialog, and stderr-tail audit pipeline.",
   "license": "MIT",

package/src/core/env-reload.ts

@@ -0,0 +1,26 @@
+/**
+ * Re-read ~/.config/kids-opencode/env after the setup wizard saves it,
+ * and inject the values into process.env. This lets the SAME process
+ * continue with the new LLM key — no `kids-opencode` re-run needed.
+ */
+
+import { readFileSync, existsSync } from "node:fs"
+import { join } from "node:path"
+
+export function reloadEnvFile(configDir: string): Record<string, string> {
+  const path = join(configDir, "env")
+  if (!existsSync(path)) return {}
+  const out: Record<string, string> = {}
+  for (const raw of readFileSync(path, "utf8").split("\n")) {
+    const line = raw.trim()
+    if (!line || line.startsWith("#")) continue
+    const eq = line.indexOf("=")
+    if (eq <= 0) continue
+    const key = line.slice(0, eq).trim()
+    let value = line.slice(eq + 1).trim()
+    if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1)
+    out[key] = value
+    process.env[key] = value
+  }
+  return out
+}

package/src/core/env.ts

@@ -60,11 +60,14 @@ export function validateEnv(env: KidsClientEnv): { ok: true } | { ok: false; rea
   }
   // Accept any supported provider's API key, not just DeepRouter. The
   // setup wizard writes whatever the parent picked into ~/.config/kids-opencode/env
-  // which the wrapper sources before exec.
+  // which the wrapper sources before exec. KIDS_OAUTH_PROVIDER marks an
+  // OAuth flow that opencode handles via its own auth.json store —
+  // we trust opencode to gate on actual token validity at serve time.
   const hasAnyKey =
     env.deeprouterApiKey
     || process.env.ANTHROPIC_API_KEY
     || process.env.OPENAI_API_KEY
+    || process.env.KIDS_OAUTH_PROVIDER
   if (!env.bypassGateway && !hasAnyKey) {
     return {
       ok: false,

package/src/core/opencode-installer.ts

@@ -0,0 +1,82 @@
+/**
+ * In-TUI installer for the upstream `opencode` CLI binary.
+ *
+ * The kid (or their parent) should never have to drop back to a shell
+ * prompt and paste a `curl ... | sh` line. If the AI engine isn't
+ * installed when the wizard starts, we run the installer ourselves and
+ * stream its progress to the SetupScreen.
+ */
+
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/** True if the upstream opencode binary is on PATH or in its standard install location. */
+export function hasOpencodeBinary(): boolean {
+  // PATH lookup (POSIX). `which` and `command -v` aren't reliable as
+  // child_process commands without a shell, so just check $PATH dirs.
+  const pathDirs = (process.env.PATH ?? "").split(":")
+  const candidates = [
+    ...pathDirs.map((d) => join(d, "opencode")),
+    join(homedir(), ".opencode", "bin", "opencode"),
+    "/usr/local/bin/opencode",
+    "/opt/homebrew/bin/opencode",
+  ]
+  return candidates.some((p) => existsSync(p))
+}
+
+export interface InstallResult {
+  ok: boolean
+  error?: string
+}
+
+/**
+ * Run the upstream installer in a subprocess, streaming each output line
+ * to `onProgress`. Resolves when the subprocess exits.
+ *
+ * Uses /bin/sh + curl pipe to match upstream's official install command.
+ * The whole thing typically takes 15-45 seconds depending on network.
+ */
+export function installOpencode(onProgress: (line: string) => void): Promise<InstallResult> {
+  return new Promise((resolve) => {
+    const child = spawn("sh", ["-c", "curl -fsSL https://opencode.ai/install | sh"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env },
+    })
+
+    const handleStream = (stream: NodeJS.ReadableStream): void => {
+      let buf = ""
+      stream.on("data", (chunk: Buffer | string) => {
+        buf += chunk.toString()
+        let nl: number
+        while ((nl = buf.indexOf("\n")) >= 0) {
+          const line = buf.slice(0, nl)
+          buf = buf.slice(nl + 1)
+          const trimmed = line.replace(/\r/g, "").trim()
+          if (trimmed) onProgress(trimmed)
+        }
+      })
+    }
+    if (child.stdout) handleStream(child.stdout)
+    if (child.stderr) handleStream(child.stderr)
+
+    child.on("error", (err) => {
+      resolve({ ok: false, error: err.message })
+    })
+    child.on("close", (code) => {
+      if (code === 0) {
+        // Make sure the new bin dir is on PATH for the remainder of THIS run,
+        // so subsequent calls (postinstall plugin registration etc.) can find
+        // opencode without waiting for a shell restart.
+        const newBin = join(homedir(), ".opencode", "bin")
+        if (!process.env.PATH?.includes(newBin)) {
+          process.env.PATH = `${newBin}:${process.env.PATH ?? ""}`
+        }
+        resolve({ ok: true })
+      } else {
+        resolve({ ok: false, error: `installer exited with code ${code}` })
+      }
+    })
+  })
+}

package/src/core/setup.ts

@@ -16,6 +16,17 @@ import { dirname, join } from "node:path"
 
 export type ProviderId = "anthropic" | "openai" | "deeprouter"
 
+/**
+ * Wire protocol between SetupScreen and bin/kids-opencode wrapper:
+ * kids-client exits with this code to ask the wrapper to run
+ * `opencode auth login --provider <p>` (interactive OAuth that needs the
+ * TTY), then re-exec kids-client. See bin/kids-opencode §11 loop.
+ */
+export const OAUTH_HANDOFF_EXIT_CODE = 123
+
+/** Providers that support OAuth login via the upstream opencode kernel. */
+export const OAUTH_PROVIDERS: ReadonlyArray<ProviderId> = ["anthropic"] as const
+
 export interface ProviderChoice {
   id: ProviderId
   label: string
@@ -53,10 +64,10 @@ export const PROVIDERS: ProviderChoice[] = [
   },
   {
     id: "deeprouter",
-    label: "DeepRouter (Airbotix's own gateway)",
-    hint: "Not yet live for public use; recommended for staff dogfood only.",
+    label: "DeepRouter (OpenAI-compatible gateway)",
+    hint: "Cheaper than going direct + one key for all models (Anthropic, OpenAI, Google). Built-in kid-safe filters (NSFW + prompt-injection guard). Limited beta — invite-only.",
     envVar: "DEEPROUTER_API_KEY",
-    apiKeyUrl: "https://app.airbotix.ai/portal/wallet",
+    apiKeyUrl: "https://deeprouter.ai/",
     config: (env) => ({
       deeprouter: {
         type: "openai-compatible",
@@ -93,12 +104,54 @@ export function saveSetup(opts: SaveOptions): void {
   const envPath = join(opts.configDir, "env")
   const existing = readEnvFile(envPath)
   existing[provider.envVar] = opts.apiKey
+  // If the user previously chose OAuth and is now switching to API key, drop
+  // the marker so validateEnv doesn't keep routing through OAuth handoff.
+  delete existing.KIDS_OAUTH_PROVIDER
   writeEnvFile(envPath, existing)
 
   // 2. Rewrite opencode.json provider section.
-  const configPath = join(opts.configDir, "opencode.json")
+  writeOpencodeConfig(opts.configDir, provider, { withApiKey: true })
+}
+
+export interface SaveOauthOptions {
+  configDir: string
+  provider: ProviderId
+}
+
+/**
+ * Stage the OAuth handoff. We write opencode.json without an apiKey block
+ * (opencode reads OAuth tokens from its own auth.json), drop any stale
+ * provider API keys, and write a KIDS_OAUTH_PROVIDER marker so the
+ * wrapper knows which provider to log into. The actual
+ * `opencode auth login --provider <p>` invocation happens in
+ * bin/kids-opencode after kids-client exits with OAUTH_HANDOFF_EXIT_CODE.
+ */
+export function saveSetupOauth(opts: SaveOauthOptions): void {
+  const provider = findProvider(opts.provider)
+  ensureConfigDir(opts.configDir)
+
+  // 1. Update env file: clear this provider's API key (avoid stale leakage),
+  //    set marker pointing at the OAuth provider.
+  const envPath = join(opts.configDir, "env")
+  const existing = readEnvFile(envPath)
+  delete existing[provider.envVar]
+  existing.KIDS_OAUTH_PROVIDER = opts.provider
+  writeEnvFile(envPath, existing)
+
+  // 2. opencode.json without apiKey — opencode uses its auth.json store.
+  writeOpencodeConfig(opts.configDir, provider, { withApiKey: false })
+}
+
+function writeOpencodeConfig(
+  configDir: string,
+  provider: ProviderChoice,
+  flags: { withApiKey: boolean },
+): void {
+  const configPath = join(configDir, "opencode.json")
   const config = readJsonOrEmpty(configPath)
-  config.provider = provider.config(provider.envVar)
+  config.provider = flags.withApiKey
+    ? provider.config(provider.envVar)
+    : { [provider.id]: {} }
   config.model = provider.defaultModel
   if (!config.permission) {
     config.permission = {
@@ -120,11 +173,15 @@ export function saveSetup(opts: SaveOptions): void {
 export function hasAnyProviderKey(configDir: string): boolean {
   const env = readEnvFile(join(configDir, "env"))
   if (env.ANTHROPIC_API_KEY || env.OPENAI_API_KEY || env.DEEPROUTER_API_KEY) return true
+  // OAuth handoff completed earlier? The marker means opencode has its own
+  // auth.json credentials; opencode itself will gate on actual token validity.
+  if (env.KIDS_OAUTH_PROVIDER) return true
   // Also accept keys present in the parent shell env (advanced users).
   return !!(
     process.env.ANTHROPIC_API_KEY
     || process.env.OPENAI_API_KEY
     || process.env.DEEPROUTER_API_KEY
+    || process.env.KIDS_OAUTH_PROVIDER
   )
 }
 

package/src/index.tsx

@@ -1,23 +1,26 @@
 /**
  * kids-client entry. Composes core/* and renders the Ink app.
  *
- * Boot sequence:
- *   1. readEnv()      — pull KIDS_* + OPENCODE_* from process.env
- *   2. validateEnv()  — hard-fail with ErrorScreen if password/key missing
- *   3. ServeManager.ensureReady() — spawn `opencode serve` if down, poll /app
- *   4. createKidsClient() — instantiate SDK v2 client w/ Basic Auth
- *   5. SessionManager — ready to prompt
- *   6. EventSubscriber.run() — SSE loop dispatches to store
- *   7. Ink render(<App />) — kid sees Startup screen, picks a flow
+ * Boot orchestration (V0.0.3):
+ *   1. readEnv + initial render in "loading"
+ *   2. validateEnv:
+ *      - "needs_setup" → render SetupScreen, await user completion,
+ *         reload env from file, re-validate, continue inline
+ *      - "config_missing" / "auth_failed" → error screen, exit
+ *      - ok → fall through to bootServices
+ *   3. bootServices: audit pipeline + opencode serve subprocess +
+ *      SDK v2 client + SSE subscriber + SIGINT/SIGTERM
+ *   4. Render startup screen; user picks a flow.
  *
- * Cleanup on SIGINT / SIGTERM: stop subscriber, stop audit pipeline,
- * kill serve child, exit. (V0 MVP: client crash takes serve with it.)
+ * Inline boot guarantee: the user never sees "run kids-opencode again".
+ * SetupScreen → save → reload env → boot serve → MissionScreen,
+ * all in the SAME process.
  */
 
 import React from "react"
 import { render } from "ink"
 import { join } from "node:path"
-import { readEnv, validateEnv } from "./core/env.ts"
+import { readEnv, validateEnv, type KidsClientEnv } from "./core/env.ts"
 import { ServeManager } from "./core/serve-manager.ts"
 import { createKidsClient, type OpencodeClient } from "./core/connection.ts"
 import { SessionManager } from "./core/session.ts"
@@ -29,58 +32,189 @@ import { readLastSession, writeLastSession } from "./core/last-session.ts"
 import { isCompletionTrigger, runCheck } from "./core/check-runner.ts"
 import { App } from "./render/ink/App.tsx"
 import { detectDangerousTopicEn, detectDangerousTopicZh } from "./dangerous-topic-bridge.ts"
-import { saveSetup, type ProviderId } from "./core/setup.ts"
+import { OAUTH_HANDOFF_EXIT_CODE, saveSetup, saveSetupOauth, type ProviderId } from "./core/setup.ts"
+import { reloadEnvFile } from "./core/env-reload.ts"
 import type { InstalledPack } from "./core/course-pack.ts"
-import { findMission, loadCoursePack } from "@kidsinai/kids-opencode-plugin"
+import { loadCoursePack } from "@kidsinai/kids-opencode-plugin"
+
+interface ServiceSet {
+  audit: AuditPipeline
+  serve: ServeManager
+  client: OpencodeClient
+  session: SessionManager
+  subscriber: EventSubscriber
+  quit: () => Promise<void>
+  handlers: FullHandlers
+}
+
+interface FullHandlers {
+  onStart: (mode: "free" | "course" | "resume" | "help") => void
+  onPrompt: (text: string) => Promise<void>
+  onPermissionReply: (decision: "allow" | "deny" | "edit") => Promise<void>
+  onAbort: () => Promise<void>
+  onErrorRetry: () => Promise<void>
+  onPickPack: (packId: string) => void
+  onMissionNext: () => void
+}
+
+interface AppHandlers {
+  onStart: (mode: "free" | "course" | "resume" | "help") => void
+  onPrompt: (text: string) => void
+  onPermissionReply: (decision: "allow" | "deny" | "edit") => void
+  onDangerousAcknowledge: () => void
+  onErrorRetry: () => void | Promise<void>
+  onQuit: () => void | Promise<void>
+  onAbort: () => void
+  onHelpBack: () => void
+  onPickPack: (packId: string) => void
+  onPickerBack: () => void
+  onMissionNext: () => void
+  onMissionBack: () => void
+  onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
+  onSetupContinue: () => Promise<void>
+  onSetupSkip: () => void
+  onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
+}
 
 async function main(): Promise<void> {
-  const env = readEnv()
+  const env: KidsClientEnv = readEnv()
   const store = new Store()
   const installedPacks = listInstalledPacks()
+
   store.update({
     coursePack: env.coursePack,
     mission: env.mission,
     screen: { kind: "loading", message: env.locale === "zh-Hans" ? "正在唤醒 AI 老师…" : "Waking up the AI teacher…" },
   })
 
-  const check = validateEnv(env)
+  // Resolve course pack metadata upfront if available.
+  applyCoursePackContext(env, store)
+
+  // Mutable holder for service set; populated by bootServices().
+  const servicesHolder: { current: ServiceSet | null } = { current: null }
+
+  // Promise that the SetupScreen flow resolves when the user has completed
+  // (or chosen to skip) setup. main() awaits it before continuing.
+  let resolveSetup: (() => void) | null = null
+  const setupGate = new Promise<void>((r) => { resolveSetup = r })
+
+  const handlers: AppHandlers = makeHandlers(store, env, servicesHolder, resolveSetupFn => {
+    resolveSetup = resolveSetupFn
+  }, () => resolveSetup)
+
+  renderApp(store, env, installedPacks, handlers)
+
+  // First validation pass.
+  let check = validateEnv(env)
+  if (!check.ok && check.variant === "needs_setup") {
+    store.update({ screen: { kind: "setup" } })
+    await setupGate
+
+    // Re-source env file (the setup wizard wrote it).
+    reloadEnvFile(env.configDir)
+    Object.assign(env, readEnv())
+    check = validateEnv(env)
+  }
+
   if (!check.ok) {
-    if (check.variant === "needs_setup") {
-      // First-run wizard. Render the setup screen; the wizard's onSave
-      // writes config + env file, then re-launches main() to pick up
-      // the new key.
-      store.update({ screen: { kind: "setup" } })
-      renderApp(store, env, installedPacks, baseHandlers(store, env, null, null, null))
-      return
-    }
-    store.update({ screen: { kind: "error", variant: check.variant, detail: check.reason } })
-    renderApp(store, env, installedPacks, baseHandlers(store, env, null, null, null))
+    const variant = check.variant === "needs_setup" ? "auth_failed" : check.variant
+    store.update({ screen: { kind: "error", variant, detail: check.reason } })
     return
   }
 
-  // Resolve course pack context up front (free-play if coursePack is null).
-  const ctx = resolveContext(env.coursePack, env.mission)
-  if (ctx) {
-    store.update({
-      packTitle: ctx.packTitle,
-      missionTitle: ctx.missionTitle,
-      missionIndex: ctx.missionIndex,
-      missionTotal: ctx.missionTotal,
-      starsBudget: ctx.starsBudget,
-      starsBalance: ctx.starsBudget, // start full; charges deduct via audit hook
-    })
-  } else if (env.coursePack) {
-    // Pack id provided but not found — surface as a toast on the startup screen.
-    store.update({
-      toast: {
-        kind: "warn",
-        text: env.locale === "zh-Hans"
-          ? `没找到 Course Pack: ${env.coursePack}（按 c 重新选）`
-          : `Course Pack not found: ${env.coursePack} (press c to pick)`,
-      },
-    })
+  // Bootstrap services in-process. Loading screen is shown while we wait.
+  store.update({
+    screen: {
+      kind: "loading",
+      message: env.locale === "zh-Hans" ? "启动 AI 引擎…" : "Starting AI engine…",
+    },
+  })
+
+  const services = await bootServices(env, store)
+  if (!services) {
+    // bootServices already updated the store with the failure screen.
+    return
+  }
+  servicesHolder.current = services
+
+  // SIGINT / SIGTERM cleanly tears down.
+  process.on("SIGINT", () => void services.quit())
+  process.on("SIGTERM", () => void services.quit())
+
+  // Land on startup screen.
+  store.update({ screen: { kind: "startup" } })
+}
+
+// ─── handler factory ──────────────────────────────────────────────────────
+
+function makeHandlers(
+  store: Store,
+  env: KidsClientEnv,
+  servicesHolder: { current: ServiceSet | null },
+  _setResolveSetup: (fn: (() => void) | null) => void,
+  getResolveSetup: () => (() => void) | null,
+): AppHandlers {
+  const ifBooted = <A extends unknown[]>(fn: (s: ServiceSet, ...args: A) => unknown) => (...args: A) => {
+    const s = servicesHolder.current
+    if (s) return fn(s, ...args)
+    return undefined
   }
 
+  return {
+    onStart: ifBooted((s, mode: "free" | "course" | "resume" | "help") => s.handlers.onStart(mode)),
+    onPrompt: ifBooted((s, text: string) => s.handlers.onPrompt(text)),
+    onPermissionReply: ifBooted((s, d: "allow" | "deny" | "edit") => s.handlers.onPermissionReply(d)),
+    onDangerousAcknowledge: () => store.update({ dangerousTopic: null }),
+    onErrorRetry: async () => {
+      const s = servicesHolder.current
+      if (s) return s.handlers.onErrorRetry()
+      // Pre-boot error retry: re-run main isn't trivial; just exit.
+      process.exit(1)
+    },
+    onQuit: async () => {
+      const s = servicesHolder.current
+      if (s) return s.quit()
+      process.exit(0)
+    },
+    onAbort: ifBooted((s) => s.handlers.onAbort()),
+    onHelpBack: () => store.update({ screen: { kind: "startup" } }),
+    onPickPack: ifBooted((s, id: string) => s.handlers.onPickPack(id)),
+    onPickerBack: () => store.update({ screen: { kind: "startup" } }),
+    onMissionNext: ifBooted((s) => s.handlers.onMissionNext()),
+    onMissionBack: () => store.update({ screen: { kind: "mission" } }),
+    onSetupSave: async (provider, apiKey) => {
+      try {
+        saveSetup({ configDir: env.configDir, provider, apiKey })
+        return { ok: true }
+      } catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+      }
+    },
+    onSetupContinue: async () => {
+      const r = getResolveSetup()
+      if (r) r()
+    },
+    onSetupSkip: () => {
+      const r = getResolveSetup()
+      if (r) r()
+    },
+    onSetupOAuthHandoff: async (provider) => {
+      try {
+        saveSetupOauth({ configDir: env.configDir, provider })
+      } catch (err) {
+        console.error("kids-client: OAuth handoff prep failed:", err)
+        process.exit(1)
+      }
+      // Hand the TTY to bin/kids-opencode so it can run
+      // `opencode auth login --provider <p>` interactively, then re-exec us.
+      process.exit(OAUTH_HANDOFF_EXIT_CODE)
+    },
+  }
+}
+
+// ─── service bootstrap ────────────────────────────────────────────────────
+
+async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSet | null> {
   const audit = new AuditPipeline({
     bufferPath: join(env.configDir, "audit-buffer.jsonl"),
   })
@@ -100,8 +234,7 @@ async function main(): Promise<void> {
   const readiness = await serve.ensureReady()
   if (readiness.kind === "timeout") {
     store.update({ screen: { kind: "error", variant: "serve_unreachable", detail: readiness.lastError } })
-    renderApp(store, env, installedPacks, baseHandlers(store, env, null, null, serve))
-    return
+    return null
   }
 
   const client = createKidsClient({
@@ -114,8 +247,8 @@ async function main(): Promise<void> {
     onSessionCreated: (e) => {
       store.update({ sessionId: e.sessionID })
       writeLastSession(env.configDir, {
-        coursePack: env.coursePack,
-        mission: env.mission,
+        coursePack: store.getSnapshot().coursePack,
+        mission: store.getSnapshot().mission,
         lastActiveAt: new Date().toISOString(),
         projectDir: process.cwd(),
       })
@@ -137,7 +270,6 @@ async function main(): Promise<void> {
     },
     onTextEnded: (e) => store.endStream(e.messageID),
     onPermissionAsked: (e) => {
-      // pickup of stars_estimated from the latest plugin audit event.
       const recentAudit = store.getSnapshot().auditBuffer.slice(-10).reverse() as Array<Record<string, unknown>>
       const matching = recentAudit.find(
         (a) => a && typeof a === "object" && a.event === "tool.execute.before" && a.tool === e.tool,
@@ -174,121 +306,25 @@ async function main(): Promise<void> {
   })
   void subscriber.run()
 
-  // First screen: startup. If env already had a course pack, kid can either
-  // jump straight in (Enter) or pick a different one (c).
-  store.update({ screen: { kind: "startup" } })
-
-  const handleQuit = async (): Promise<void> => {
+  const quit = async (): Promise<void> => {
     subscriber.stop()
     await audit.stop()
     await serve.shutdown()
     process.exit(0)
   }
-  process.on("SIGINT", () => void handleQuit())
-  process.on("SIGTERM", () => void handleQuit())
 
-  const handlers = fullHandlers(store, env, session, client, serve, handleQuit)
-  renderApp(store, env, installedPacks, handlers)
-}
-
-// ─── handler factories ───────────────────────────────────────────────────
+  const handlers = makeFullHandlers(store, env, session, client, serve)
 
-interface AppHandlers {
-  onStart: (mode: "free" | "course" | "resume" | "help") => void
-  onPrompt: (text: string) => void
-  onPermissionReply: (decision: "allow" | "deny" | "edit") => void
-  onDangerousAcknowledge: () => void
-  onErrorRetry: () => void | Promise<void>
-  onQuit: () => void | Promise<void>
-  onAbort: () => void
-  onHelpBack: () => void
-  onPickPack: (packId: string) => void
-  onPickerBack: () => void
-  onMissionNext: () => void
-  onMissionBack: () => void
-  onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
-  onSetupSkip: () => void
-}
-
-function makeSetupHandlers(store: Store, env: ReturnType<typeof readEnv>): Pick<AppHandlers, "onSetupSave" | "onSetupSkip"> {
-  return {
-    onSetupSave: async (provider, apiKey) => {
-      try {
-        saveSetup({ configDir: env.configDir, provider, apiKey })
-        return { ok: true }
-      } catch (err) {
-        return { ok: false, reason: err instanceof Error ? err.message : String(err) }
-      }
-    },
-    onSetupSkip: () => {
-      // After setup completes (or user skips), tell the user to restart so
-      // the wrapper picks up the new env file. Re-launching main() in-process
-      // would require tearing down Ink which is messy; a re-exec is cleaner.
-      process.stderr.write("\nKids OpenCode: setup saved. Please run `kids-opencode` again to start.\n")
-      process.exit(0)
-    },
-  }
+  return { audit, serve, client, session, subscriber, quit, handlers }
 }
 
-/**
- * Minimal handlers for the pre-validation / pre-readiness error path.
- * Many actions are no-ops because the app isn't fully booted; quit is
- * the realistic action.
- */
-function baseHandlers(
+function makeFullHandlers(
   store: Store,
-  env: ReturnType<typeof readEnv>,
-  _session: SessionManager | null,
-  _client: OpencodeClient | null,
-  serve: ServeManager | null,
-): AppHandlers {
-  const noop = (): void => {}
-  const setup = makeSetupHandlers(store, env)
-  return {
-    onStart: noop,
-    onPrompt: noop,
-    onPermissionReply: noop,
-    onDangerousAcknowledge: () => store.update({ dangerousTopic: null }),
-    onErrorRetry: async () => {
-      if (!serve) {
-        process.exit(1)
-        return
-      }
-      store.update({
-        screen: {
-          kind: "loading",
-          message: env.locale === "zh-Hans" ? "再试一次…" : "Trying again…",
-        },
-      })
-      const again = await serve.ensureReady()
-      if (again.kind === "timeout") {
-        store.update({ screen: { kind: "error", variant: "serve_unreachable", detail: again.lastError } })
-      } else {
-        store.update({ screen: { kind: "startup" } })
-      }
-    },
-    onQuit: async () => {
-      if (serve) await serve.shutdown()
-      process.exit(0)
-    },
-    onAbort: noop,
-    onHelpBack: () => store.update({ screen: { kind: "startup" } }),
-    onPickPack: noop,
-    onPickerBack: () => store.update({ screen: { kind: "startup" } }),
-    onMissionNext: noop,
-    onMissionBack: noop,
-    ...setup,
-  }
-}
-
-function fullHandlers(
-  store: Store,
-  env: ReturnType<typeof readEnv>,
+  env: KidsClientEnv,
   session: SessionManager,
   client: OpencodeClient,
   serve: ServeManager,
-  quit: () => Promise<void>,
-): AppHandlers {
+): FullHandlers {
   const updateLastSession = (): void => {
     writeLastSession(env.configDir, {
       coursePack: store.getSnapshot().coursePack,
@@ -329,10 +365,9 @@ function fullHandlers(
           refreshContext()
           flashToast(store, {
             kind: "info",
-            text:
-              env.locale === "zh-Hans"
-                ? `继续上次：${last.coursePack}${last.mission ? " · " + last.mission : ""}`
-                : `Resuming: ${last.coursePack}${last.mission ? " · " + last.mission : ""}`,
+            text: env.locale === "zh-Hans"
+              ? `继续上次：${last.coursePack}${last.mission ? " · " + last.mission : ""}`
+              : `Resuming: ${last.coursePack}${last.mission ? " · " + last.mission : ""}`,
           })
         } else {
           flashToast(store, {
@@ -343,14 +378,12 @@ function fullHandlers(
         store.update({ screen: { kind: "mission" } })
         return
       }
-      // mode === "free" (or unrecognised) — enter MissionScreen.
       store.update({ screen: { kind: "mission" } })
     },
     onPrompt: async (text) => {
       const snap = store.getSnapshot()
       store.appendMessage({ id: `kid-${Date.now()}`, actor: "kid", text, streaming: false, ts: Date.now() })
 
-      // In-TUI mission check intercept. Don't even hit the LLM.
       if (snap.mission && isCompletionTrigger(text, env.locale)) {
         const outcome = runCheck({
           missionId: snap.mission,
@@ -384,14 +417,12 @@ function fullHandlers(
         return
       }
 
-      // Dangerous topic intercept on kid input.
       const hit = env.locale === "zh-Hans" ? detectDangerousTopicZh(text) : detectDangerousTopicEn(text)
       if (hit) {
         store.update({ dangerousTopic: { category: hit, snippet: text } })
         return
       }
 
-      // Normal LLM prompt.
       store.update({ thinking: true })
       updateLastSession()
       try {
@@ -412,17 +443,23 @@ function fullHandlers(
         if (decision === "edit") {
           flashToast(store, {
             kind: "info",
-            text:
-              env.locale === "zh-Hans"
-                ? "你来改这一步，告诉 AI 你想怎么做"
-                : "You take this step — tell the AI what you'd prefer",
+            text: env.locale === "zh-Hans"
+              ? "你来改这一步，告诉 AI 你想怎么做"
+              : "You take this step — tell the AI what you'd prefer",
           })
         }
-      } catch {
-        // SSE will surface the timeout / error via onLlmError.
-      }
+      } catch { /* SSE surfaces errors */ }
+    },
+    onAbort: async () => {
+      try {
+        await session.abort()
+        store.update({ thinking: false })
+        flashToast(store, {
+          kind: "warn",
+          text: env.locale === "zh-Hans" ? "已停止" : "Stopped",
+        })
+      } catch { /* ignore */ }
     },
-    onDangerousAcknowledge: () => store.update({ dangerousTopic: null }),
     onErrorRetry: async () => {
       store.update({
         screen: {
@@ -437,26 +474,11 @@ function fullHandlers(
         store.update({ screen: { kind: "startup" } })
       }
     },
-    onQuit: quit,
-    onAbort: async () => {
-      try {
-        await session.abort()
-        store.update({ thinking: false })
-        flashToast(store, {
-          kind: "warn",
-          text: env.locale === "zh-Hans" ? "已停止" : "Stopped",
-        })
-      } catch {
-        // ignore
-      }
-    },
-    onHelpBack: () => store.update({ screen: { kind: "startup" } }),
     onPickPack: (packId) => {
       store.update({ coursePack: packId, mission: null })
       refreshContext()
       store.update({ screen: { kind: "mission" } })
     },
-    onPickerBack: () => store.update({ screen: { kind: "startup" } }),
     onMissionNext: () => {
       const snap = store.getSnapshot()
       if (!snap.coursePack || !snap.mission) {
@@ -479,16 +501,37 @@ function fullHandlers(
         text: env.locale === "zh-Hans" ? `开始：${next.title}` : `Starting: ${next.title}`,
       })
     },
-    onMissionBack: () => store.update({ screen: { kind: "mission" } }),
-    ...makeSetupHandlers(store, env),
   }
 }
 
-// ─── utilities ───────────────────────────────────────────────────────────
+// ─── helpers ──────────────────────────────────────────────────────────────
+
+function applyCoursePackContext(env: KidsClientEnv, store: Store): void {
+  const ctx = resolveContext(env.coursePack, env.mission)
+  if (ctx) {
+    store.update({
+      packTitle: ctx.packTitle,
+      missionTitle: ctx.missionTitle,
+      missionIndex: ctx.missionIndex,
+      missionTotal: ctx.missionTotal,
+      starsBudget: ctx.starsBudget,
+      starsBalance: ctx.starsBudget,
+    })
+  } else if (env.coursePack) {
+    store.update({
+      toast: {
+        kind: "warn",
+        text: env.locale === "zh-Hans"
+          ? `没找到 Course Pack: ${env.coursePack}（按 c 重新选）`
+          : `Course Pack not found: ${env.coursePack} (press c to pick)`,
+      },
+    })
+  }
+}
 
 function renderApp(
   store: Store,
-  env: ReturnType<typeof readEnv>,
+  env: KidsClientEnv,
   installedPacks: InstalledPack[],
   handlers: AppHandlers,
 ): void {
@@ -536,11 +579,6 @@ function errMessage(err: unknown): string {
   return String(err)
 }
 
-// Touch findMission so TS doesn't complain about the import being unused
-// when typecheck runs against the v0.0.1 SDK that doesn't expose v2 yet.
-void findMission
-void loadCoursePack
-
 void main().catch((err) => {
   console.error("kids-client: fatal startup error:", err)
   process.exit(1)

package/src/render/ink/App.tsx

@@ -41,7 +41,9 @@ export interface AppDeps {
   onMissionNext: () => void
   onMissionBack: () => void
   onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
+  onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
+  onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
 }
 
 export function App(deps: AppDeps): React.ReactElement {
@@ -74,7 +76,7 @@ export function App(deps: AppDeps): React.ReactElement {
     case "loading":
       return <LoadingScreen locale={deps.locale} message={state.screen.message} />
     case "setup":
-      return <SetupScreen locale={deps.locale} onSave={deps.onSetupSave} onSkip={deps.onSetupSkip} />
+      return <SetupScreen locale={deps.locale} onSave={deps.onSetupSave} onContinue={deps.onSetupContinue} onSkip={deps.onSetupSkip} onOAuthHandoff={deps.onSetupOAuthHandoff} />
     case "startup":
       return <StartupScreen locale={deps.locale} coursePack={state.coursePack} onStart={deps.onStart} />
     case "mission":

package/src/render/ink/screens/SetupScreen.tsx

@@ -4,62 +4,218 @@
  *
  * Audience: a parent (the kid sees the intro and is told to grab a
  * grown-up). The wizard walks through:
+ *   0. engine_install (auto, only if upstream opencode CLI missing)
  *   1. Welcome / "this part needs a grown-up"
  *   2. Pick provider (Anthropic / OpenAI / DeepRouter)
  *   3. Paste API key (with link to where to get one)
- *   4. Save → re-validate → route to startup
- *
- * The choice is persisted via core/setup.ts (writes ~/.config/kids-opencode/env
- * + updates opencode.json provider section).
+ *   4. Save → continue inline (no re-exec) → MissionScreen
  */
 
-import React, { useState } from "react"
+import React, { useEffect, useState } from "react"
 import { Box, Text, useInput } from "ink"
 import TextInput from "ink-text-input"
+import Spinner from "ink-spinner"
 import { getTheme } from "../theme.ts"
 import { KidsLogo } from "../components/KidsLogo.tsx"
 import {
   findProvider,
   looksLikeApiKey,
+  OAUTH_PROVIDERS,
   PROVIDERS,
   type ProviderId,
 } from "../../../core/setup.ts"
+import { hasOpencodeBinary, installOpencode } from "../../../core/opencode-installer.ts"
 
-type Step = "intro" | "provider" | "apikey" | "saving" | "done" | "error"
+type Step =
+  | "engine_install"
+  | "engine_done"
+  | "intro"
+  | "provider"
+  | "auth_choice"
+  | "oauth_handoff"
+  | "apikey"
+  | "saving"
+  | "done"
+  | "error"
 
 interface SetupScreenProps {
   locale: "zh-Hans" | "en"
   onSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
+  /** After save, kicks off inline boot. Resolves when AI is ready. */
+  onContinue: () => Promise<void>
+  /** Skip key — useful for advanced users who set env vars themselves. */
   onSkip: () => void
+  /**
+   * Hand off to bin/kids-opencode for `opencode auth login --provider <p>`.
+   * Implementation writes opencode.json + the KIDS_OAUTH_PROVIDER marker,
+   * then process.exit(OAUTH_HANDOFF_EXIT_CODE). Never returns.
+   */
+  onOAuthHandoff: (provider: ProviderId) => Promise<void>
 }
 
-export function SetupScreen({ locale, onSave, onSkip }: SetupScreenProps): React.ReactElement {
+export function SetupScreen({ locale, onSave, onContinue, onSkip, onOAuthHandoff }: SetupScreenProps): React.ReactElement {
   const theme = getTheme()
   const t = STRINGS[locale]
-  const [step, setStep] = useState<Step>("intro")
+  const initialStep: Step = hasOpencodeBinary() ? "intro" : "engine_install"
+  const [step, setStep] = useState<Step>(initialStep)
   const [providerIdx, setProviderIdx] = useState(0)
+  const [authChoiceIdx, setAuthChoiceIdx] = useState(0)  // 0 = subscription, 1 = api key
   const [apiKey, setApiKey] = useState("")
   const [errorMsg, setErrorMsg] = useState("")
+  const [engineLog, setEngineLog] = useState<string[]>([])
+  const [engineRunning, setEngineRunning] = useState(false)
+
+  // Auto-trigger engine install once on first render.
+  useEffect(() => {
+    if (initialStep === "engine_install" && !engineRunning) {
+      setEngineRunning(true)
+      void installOpencode((line) => {
+        setEngineLog((prev) => {
+          const next = [...prev, line]
+          return next.length > 8 ? next.slice(next.length - 8) : next
+        })
+      }).then((result) => {
+        setEngineRunning(false)
+        if (result.ok) {
+          setStep("engine_done")
+        } else {
+          setErrorMsg(result.error ?? "engine install failed")
+          setStep("error")
+        }
+      })
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
 
   useInput((input, key) => {
-    if (step === "intro") {
+    if (step === "engine_done") {
+      if (key.return) setStep("intro")
+    } else if (step === "intro") {
       if (key.return) setStep("provider")
       else if (input === "s" || input === "S") onSkip()
     } else if (step === "provider") {
       if (key.upArrow) setProviderIdx((i) => Math.max(0, i - 1))
       else if (key.downArrow) setProviderIdx((i) => Math.min(PROVIDERS.length - 1, i + 1))
-      else if (key.return) setStep("apikey")
+      else if (key.return) {
+        // Anthropic supports both Pro/Max subscription OAuth and API key —
+        // surface the choice. Other providers go straight to api-key input.
+        const picked = PROVIDERS[providerIdx]!
+        if (OAUTH_PROVIDERS.includes(picked.id)) {
+          setAuthChoiceIdx(0)
+          setStep("auth_choice")
+        } else {
+          setStep("apikey")
+        }
+      }
       else if (key.escape) setStep("intro")
+    } else if (step === "auth_choice") {
+      if (key.upArrow) setAuthChoiceIdx((i) => Math.max(0, i - 1))
+      else if (key.downArrow) setAuthChoiceIdx((i) => Math.min(1, i + 1))
+      else if (key.return) {
+        if (authChoiceIdx === 0) {
+          // Pro/Max OAuth — render a brief handoff screen, then exit so
+          // the wrapper can run `opencode auth login` with full TTY.
+          setStep("oauth_handoff")
+          // Fire-and-forget — onOAuthHandoff calls process.exit, never returns.
+          void onOAuthHandoff(PROVIDERS[providerIdx]!.id)
+        } else {
+          setStep("apikey")
+        }
+      }
+      else if (key.escape) setStep("provider")
+    } else if (step === "apikey") {
+      // Picked the wrong provider? Esc bounces back to the picker.
+      // (Enter is consumed by TextInput's onSubmit below, so we only need Esc here.)
+      if (key.escape) {
+        setApiKey("")
+        setStep("provider")
+      } else if (
+        (input === "d" || input === "D")
+        && provider.id !== "deeprouter"
+        && apiKey === ""
+      ) {
+        // Funnel: parent decides Anthropic/OpenAI billing is too much friction
+        // — switch to DeepRouter inline without re-traversing the picker.
+        // Guarded by `apiKey === ""` so the keystroke only diverts before
+        // the user has started typing; otherwise `d` is just a character.
+        const dIdx = PROVIDERS.findIndex((p) => p.id === "deeprouter")
+        if (dIdx >= 0) {
+          setProviderIdx(dIdx)
+          setApiKey("")
+        }
+      }
     } else if (step === "done") {
-      if (key.return) onSkip() // continue to startup
+      if (key.return) {
+        // Inline boot — no exit.
+        void onContinue()
+      }
     } else if (step === "error") {
-      if (key.return) setStep("apikey")
+      if (key.return) {
+        // From any failure step, retry from apikey unless engine failed
+        setStep(engineLog.length > 0 && !hasOpencodeBinary() ? "engine_install" : "apikey")
+        if (engineLog.length > 0 && !hasOpencodeBinary()) {
+          // Restart engine install
+          setEngineLog([])
+          setEngineRunning(true)
+          void installOpencode((line) => {
+            setEngineLog((prev) => {
+              const next = [...prev, line]
+              return next.length > 8 ? next.slice(next.length - 8) : next
+            })
+          }).then((result) => {
+            setEngineRunning(false)
+            if (result.ok) setStep("engine_done")
+            else {
+              setErrorMsg(result.error ?? "engine install failed")
+              setStep("error")
+            }
+          })
+        }
+      }
     }
   })
 
   const provider = PROVIDERS[providerIdx]!
   const providerObj = findProvider(provider.id)
 
+  if (step === "engine_install") {
+    return (
+      <Box flexDirection="column" alignItems="center" paddingY={1}>
+        <KidsLogo />
+        <Box marginTop={2} borderStyle="round" borderColor={theme.accent} paddingX={2} paddingY={1} flexDirection="column">
+          <Box>
+            <Text color={theme.accent}>{engineRunning ? <Spinner type="dots" /> : "  "}</Text>
+            <Text color={theme.accent} bold> {t.engineInstalling}</Text>
+          </Box>
+          <Box marginTop={1}>
+            <Text color={theme.fgDim}>{t.engineHint}</Text>
+          </Box>
+          {engineLog.length > 0 && (
+            <Box marginTop={1} flexDirection="column">
+              {engineLog.map((line, i) => (
+                <Text key={i} color={theme.fgDim} dimColor>  {line}</Text>
+              ))}
+            </Box>
+          )}
+        </Box>
+      </Box>
+    )
+  }
+
+  if (step === "engine_done") {
+    return (
+      <Box flexDirection="column" alignItems="center" paddingY={1}>
+        <KidsLogo />
+        <Box marginTop={2} borderStyle="round" borderColor={theme.success} paddingX={2} paddingY={1}>
+          <Text color={theme.success} bold>{t.engineDone}</Text>
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.accent}>{t.continueHint}</Text>
+        </Box>
+      </Box>
+    )
+  }
+
   if (step === "intro") {
     return (
       <Box flexDirection="column" alignItems="center" paddingY={1}>
@@ -107,13 +263,68 @@ export function SetupScreen({ locale, onSave, onSkip }: SetupScreenProps): React
     )
   }
 
+  if (step === "auth_choice") {
+    const choices = t.authChoice.options
+    return (
+      <Box flexDirection="column" borderStyle="double" borderColor={theme.accent} paddingX={2} paddingY={1}>
+        <Text color={theme.accent} bold>{t.authChoice.title(providerObj.label)}</Text>
+        <Box marginTop={1} flexDirection="column">
+          {choices.map((c, i) => {
+            const active = i === authChoiceIdx
+            return (
+              <Box key={i}>
+                <Text color={active ? theme.kid : theme.fg}>{active ? "▶ " : "  "}</Text>
+                <Box flexDirection="column" flexGrow={1}>
+                  <Text color={active ? theme.accent : theme.fg} bold={active}>{c.label}</Text>
+                  <Text color={theme.fgDim} dimColor={!active}>  {c.hint}</Text>
+                </Box>
+              </Box>
+            )
+          })}
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.accent}>{t.authChoice.keys}</Text>
+        </Box>
+      </Box>
+    )
+  }
+
+  if (step === "oauth_handoff") {
+    return (
+      <Box flexDirection="column" alignItems="center" paddingY={1}>
+        <KidsLogo />
+        <Box marginTop={2} borderStyle="round" borderColor={theme.accent} paddingX={2} paddingY={1} flexDirection="column">
+          <Box>
+            <Text color={theme.accent}>
+              <Spinner type="dots" />
+            </Text>
+            <Text color={theme.accent} bold> {t.oauthHandoff.title}</Text>
+          </Box>
+          <Box marginTop={1}>
+            <Text color={theme.fgDim}>{t.oauthHandoff.line1}</Text>
+          </Box>
+          <Box>
+            <Text color={theme.fgDim}>{t.oauthHandoff.line2}</Text>
+          </Box>
+        </Box>
+      </Box>
+    )
+  }
+
   if (step === "apikey") {
+    const steps = t.providerSteps[provider.id]
     return (
       <Box flexDirection="column" borderStyle="double" borderColor={theme.accent} paddingX={2} paddingY={1}>
         <Text color={theme.accent} bold>{t.apiKeyTitle(providerObj.label)}</Text>
         <Box marginTop={1} flexDirection="column">
           <Text color={theme.fgDim}>{t.apiKeyHint(providerObj.apiKeyUrl)}</Text>
         </Box>
+        <Box marginTop={1} flexDirection="column" paddingX={1}>
+          <Text color={theme.accent}>{t.stepsHeader}</Text>
+          {steps.map((line, i) => (
+            <Text key={i} color={theme.fgDim}>  {line}</Text>
+          ))}
+        </Box>
         <Box marginTop={1}>
           <Text color={theme.kid}>🔑  </Text>
           <TextInput
@@ -143,6 +354,14 @@ export function SetupScreen({ locale, onSave, onSkip }: SetupScreenProps): React
         <Box marginTop={1}>
           <Text color={theme.fgDim}>{t.apiKeyEnter}</Text>
         </Box>
+        <Box>
+          <Text color={theme.fgDim}>{t.apiKeyBack}</Text>
+        </Box>
+        {provider.id !== "deeprouter" && (
+          <Box>
+            <Text color={theme.accent}>{t.apiKeyToDR}</Text>
+          </Box>
+        )}
       </Box>
     )
   }
@@ -150,7 +369,10 @@ export function SetupScreen({ locale, onSave, onSkip }: SetupScreenProps): React
   if (step === "saving") {
     return (
       <Box paddingY={1} paddingX={2}>
-        <Text color={theme.accent}>{t.saving}</Text>
+        <Text color={theme.accent}>
+          <Spinner type="dots" />
+        </Text>
+        <Text color={theme.accent}> {t.saving}</Text>
       </Box>
     )
   }
@@ -188,6 +410,10 @@ export function SetupScreen({ locale, onSave, onSkip }: SetupScreenProps): React
 
 const STRINGS = {
   "zh-Hans": {
+    engineInstalling: "正在安装 AI 引擎…",
+    engineHint: "从 opencode.ai 下载（大约 30 秒）。卡住的话按 Enter 重试。",
+    engineDone: "✓ AI 引擎安装完成",
+    continueHint: "[Enter] 下一步",
     introTitle: "👋  这一步需要家长帮忙",
     introLine1: "AI 老师要用一个 \"API key\" 才能工作 —— 就像给它一把钥匙。",
     introLine2: "家长打开账号给 AI 服务（Anthropic / OpenAI 等），拿到 key 粘进来就行。",
@@ -196,19 +422,67 @@ const STRINGS = {
     providerTitle: "选一个 AI 服务",
     providerKeys: "[↑↓] 选 · [Enter] 下一步 · [Esc] 返回",
     getKey: "去拿 key",
+    authChoice: {
+      title: (label: string) => `${label} 怎么用？`,
+      keys: "[↑↓] 选 · [Enter] 确认 · [Esc] 返回",
+      options: [
+        {
+          label: "用我的 Claude Pro/Max 订阅（推荐）",
+          hint: "不用 API key、不用充值；用现有 claude.ai 账号一键登录",
+        },
+        {
+          label: "用 API key（按量计费 ~$5/月）",
+          hint: "公司账号、没订阅、或想分账时选这个",
+        },
+      ],
+    },
+    oauthHandoff: {
+      title: "正在让 Claude 登录接管屏幕…",
+      line1: "马上会跳出浏览器让你登录 claude.ai 账号。",
+      line2: "登录完后我会自动接回来，给孩子继续。",
+    },
     apiKeyTitle: (label: string) => `输入 ${label} 的 API key`,
     apiKeyHint: (url: string) => `没 key？打开浏览器：${url}`,
     apiKeyPlaceholder: (env: string) => `${env}（粘进来后按 Enter）`,
     apiKeyEnter: "[Enter] 保存 · 你的 key 只存在本地",
+    apiKeyBack: "[Esc] 选错了？回去重选",
+    apiKeyToDR: "[d] 不想充值？改用 DeepRouter — 无需信用卡（输入前按）",
     apiKeyInvalid: (env: string) => `这看起来不是有效的 ${env}。再试一次。`,
+    stepsHeader: "在哪里点开：",
+    providerSteps: {
+      anthropic: [
+        "1. 打开浏览器 → console.anthropic.com",
+        "2. 用 Google 账号登录，或邮箱注册（免费）",
+        "3. 右上角点头像 → Billing → Add credits → 充 $5 起（信用卡 / Apple Pay）",
+        "4. 左侧菜单点 API Keys → 按 \"Create Key\" 按钮 → 起个名（比如 kids）",
+        "5. 弹窗里复制 sk-ant- 开头的整串，回到这里粘上",
+      ],
+      openai: [
+        "1. 打开浏览器 → platform.openai.com/api-keys",
+        "2. 用 Google 账号登录，或邮箱注册",
+        "3. 左侧 Billing → Add to credit balance → 充 $5 起（信用卡）",
+        "4. 回到 API Keys → 按 \"+ Create new secret key\" → 起个名（比如 kids）",
+        "5. 弹窗里复制 sk- 开头的整串（只显示一次！），回来粘上",
+      ],
+      deeprouter: [
+        "1. 打开浏览器 → deeprouter.ai（目前内测，需要邀请码）",
+        "2. 拿邀请码注册账号",
+        "3. 控制台 → API Keys → 创建新 key",
+        "4. 复制 key，回到这里粘上",
+      ],
+    },
     saving: "保存中…",
     errTitle: "出了点问题",
     errRetry: "[Enter] 再试",
     doneTitle: "🎉  搞定！家长任务完成。",
-    doneNext: "你可以让孩子继续了。下一屏是启动屏。",
-    doneHint: "[Enter] 开始",
+    doneNext: "马上启动，让孩子继续。",
+    doneHint: "[Enter] 启动",
   },
   en: {
+    engineInstalling: "Setting up the AI engine…",
+    engineHint: "Downloading from opencode.ai (about 30 seconds). Stuck? Press Enter to retry.",
+    engineDone: "✓ AI engine ready",
+    continueHint: "[Enter] Next",
     introTitle: "👋  Grown-up help needed for this part",
     introLine1: "The AI teacher needs an \"API key\" to work — think of it as a password.",
     introLine2: "A parent opens an account with an AI service (Anthropic / OpenAI), copies the key, pastes it here.",
@@ -217,16 +491,60 @@ const STRINGS = {
     providerTitle: "Pick an AI service",
     providerKeys: "[↑↓] choose · [Enter] next · [Esc] back",
     getKey: "Get key at",
+    authChoice: {
+      title: (label: string) => `How will you connect to ${label}?`,
+      keys: "[↑↓] choose · [Enter] confirm · [Esc] back",
+      options: [
+        {
+          label: "Use my Claude Pro/Max subscription (recommended)",
+          hint: "No API key, no top-up — sign in with your existing claude.ai account",
+        },
+        {
+          label: "Use an API key (pay-as-you-go ~$5/month)",
+          hint: "Pick this for company accounts, no subscription, or separate billing",
+        },
+      ],
+    },
+    oauthHandoff: {
+      title: "Handing off to Claude login…",
+      line1: "A browser window will open to sign in to your claude.ai account.",
+      line2: "I'll pick back up automatically once you're done.",
+    },
     apiKeyTitle: (label: string) => `Enter your ${label} API key`,
     apiKeyHint: (url: string) => `Don't have a key yet? Open: ${url}`,
     apiKeyPlaceholder: (env: string) => `${env} (paste then Enter)`,
     apiKeyEnter: "[Enter] save · Your key stays on this machine.",
+    apiKeyBack: "[Esc] Picked wrong one? Go back and re-pick.",
+    apiKeyToDR: "[d] Skip the billing — use DeepRouter instead (no credit card). Press before typing.",
     apiKeyInvalid: (env: string) => `That doesn't look like a valid ${env}. Try again.`,
+    stepsHeader: "Where to click:",
+    providerSteps: {
+      anthropic: [
+        "1. Open in browser → console.anthropic.com",
+        "2. Sign in with Google, or sign up with email (free)",
+        "3. Top-right profile → Billing → Add credits → top up $5+ (card / Apple Pay)",
+        "4. Left menu → API Keys → \"Create Key\" → name it (e.g. kids)",
+        "5. Copy the sk-ant-… string from the popup, paste it here",
+      ],
+      openai: [
+        "1. Open in browser → platform.openai.com/api-keys",
+        "2. Sign in with Google, or sign up with email",
+        "3. Left menu → Billing → Add to credit balance → top up $5+ (card)",
+        "4. Back to API Keys → \"+ Create new secret key\" → name it (e.g. kids)",
+        "5. Copy the sk- string from the popup (shown only once!), paste it here",
+      ],
+      deeprouter: [
+        "1. Open in browser → deeprouter.ai (closed beta — invite code required)",
+        "2. Sign up with the invite code",
+        "3. Dashboard → API Keys → Create new key",
+        "4. Copy the key, paste it here",
+      ],
+    },
     saving: "Saving…",
     errTitle: "Something went wrong",
     errRetry: "[Enter] Try again",
     doneTitle: "🎉  All set! Grown-up step done.",
-    doneNext: "You can hand it back to the kid now. Next screen is the welcome.",
+    doneNext: "Starting up now.",
     doneHint: "[Enter] Start",
   },
 } as const