@kidsinai/kids-client 0.0.4 → 0.0.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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.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/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/core/store.ts

@@ -10,6 +10,7 @@
 export type Screen =
   | { kind: "loading"; message?: string }
   | { kind: "setup" }
+  | { kind: "tour" }
   | { kind: "startup" }
   | { kind: "mission" }
   | { kind: "help" }

package/src/core/tour-marker.ts

@@ -0,0 +1,27 @@
+/**
+ * First-run welcome-tour marker. File existence at
+ * `<configDir>/tour-seen` means the kid has been through the intro at
+ * least once; the next launch goes straight to StartupScreen.
+ *
+ * The tour only fires when (a) marker absent AND (b) the SetupScreen
+ * just ran. Returning users who inherited env vars skip it.
+ */
+
+import { existsSync, writeFileSync, chmodSync } from "node:fs"
+import { join } from "node:path"
+
+const FILE_NAME = "tour-seen"
+
+export function hasSeenTour(configDir: string): boolean {
+  return existsSync(join(configDir, FILE_NAME))
+}
+
+export function markTourSeen(configDir: string): void {
+  const path = join(configDir, FILE_NAME)
+  try {
+    writeFileSync(path, new Date().toISOString() + "\n", "utf8")
+    chmodSync(path, 0o600)
+  } catch {
+    /* non-fatal — re-show is a feature, not a bug */
+  }
+}

package/src/index.tsx

@@ -32,8 +32,9 @@ 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 { hasSeenTour, markTourSeen } from "./core/tour-marker.ts"
 import type { InstalledPack } from "./core/course-pack.ts"
 import { loadCoursePack } from "@kidsinai/kids-opencode-plugin"
 
@@ -73,6 +74,8 @@ interface AppHandlers {
   onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
   onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
+  onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
+  onTourDone: () => void
 }
 
 async function main(): Promise<void> {
@@ -97,17 +100,24 @@ async function main(): Promise<void> {
   let resolveSetup: (() => void) | null = null
   const setupGate = new Promise<void>((r) => { resolveSetup = r })
 
+  // Same pattern for the first-run welcome tour. Only awaited if we actually
+  // route to it (returning users with valid env skip both setup and tour).
+  let resolveTour: (() => void) | null = null
+  const tourGate = new Promise<void>((r) => { resolveTour = r })
+
   const handlers: AppHandlers = makeHandlers(store, env, servicesHolder, resolveSetupFn => {
     resolveSetup = resolveSetupFn
-  }, () => resolveSetup)
+  }, () => resolveSetup, () => resolveTour)
 
   renderApp(store, env, installedPacks, handlers)
 
   // First validation pass.
   let check = validateEnv(env)
+  let didSetup = false
   if (!check.ok && check.variant === "needs_setup") {
     store.update({ screen: { kind: "setup" } })
     await setupGate
+    didSetup = true
 
     // Re-source env file (the setup wizard wrote it).
     reloadEnvFile(env.configDir)
@@ -121,6 +131,14 @@ async function main(): Promise<void> {
     return
   }
 
+  // First-run tour: only fires if the kid just went through setup AND hasn't
+  // seen the tour. Returning users with inherited env vars skip it entirely.
+  if (didSetup && !hasSeenTour(env.configDir)) {
+    store.update({ screen: { kind: "tour" } })
+    await tourGate
+    markTourSeen(env.configDir)
+  }
+
   // Bootstrap services in-process. Loading screen is shown while we wait.
   store.update({
     screen: {
@@ -152,6 +170,7 @@ function makeHandlers(
   servicesHolder: { current: ServiceSet | null },
   _setResolveSetup: (fn: (() => void) | null) => void,
   getResolveSetup: () => (() => void) | null,
+  getResolveTour: () => (() => void) | null,
 ): AppHandlers {
   const ifBooted = <A extends unknown[]>(fn: (s: ServiceSet, ...args: A) => unknown) => (...args: A) => {
     const s = servicesHolder.current
@@ -197,6 +216,21 @@ function makeHandlers(
       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)
+    },
+    onTourDone: () => {
+      const r = getResolveTour()
+      if (r) r()
+    },
   }
 }
 
@@ -274,7 +308,8 @@ async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSe
       })
     },
     onLlmError: (e) => {
-      store.update({ thinking: false, screen: { kind: "error", variant: "network_down", detail: e.message } })
+      const variant = classifyLlmError(e.message)
+      store.update({ thinking: false, screen: { kind: "error", variant, detail: e.message } })
     },
     onCompactionEnded: () => {
       flashToast(store, {
@@ -548,7 +583,38 @@ function handlePluginAudit(event: unknown, store: Store): void {
     const snap = store.getSnapshot()
     const newBalance = Math.max(0, snap.starsBalance - e.stars_charged)
     store.update({ starsBalance: newBalance })
+    // Preemptive switch the moment the balance lands at zero — kid sees the
+    // friendly "out of stars" screen before the next tool call fails server-side.
+    if (newBalance === 0 && snap.starsBudget > 0 && snap.screen.kind === "mission") {
+      store.update({
+        screen: { kind: "error", variant: "stars_exhausted" },
+        thinking: false,
+      })
+    }
+  }
+}
+
+/**
+ * Pattern-match the LLM/plugin error message against known billing failures
+ * so the kid lands on the friendly "out of stars" screen instead of the
+ * generic "network down" one. The plugin / DeepRouter wraps these with
+ * codes like WALLET_INSUFFICIENT / FAMILY_PAUSED (platform-backend §7) or
+ * plain English ("insufficient credits", "rate limit", "402").
+ */
+function classifyLlmError(msg: string): "stars_exhausted" | "network_down" {
+  const m = msg.toLowerCase()
+  if (
+    m.includes("wallet_insufficient")
+    || m.includes("family_paused")
+    || m.includes("insufficient")
+    || m.includes("out of credit")
+    || m.includes("out of stars")
+    || m.includes("quota")
+    || m.includes("402")
+  ) {
+    return "stars_exhausted"
   }
+  return "network_down"
 }
 
 const TOAST_TTL_MS = 3500

package/src/render/ink/App.tsx

@@ -22,6 +22,7 @@ import { CoursePackPicker } from "./screens/CoursePackPicker.tsx"
 import { MissionCompleteScreen } from "./screens/MissionCompleteScreen.tsx"
 import { LoadingScreen } from "./screens/LoadingScreen.tsx"
 import { SetupScreen } from "./screens/SetupScreen.tsx"
+import { TourScreen } from "./screens/TourScreen.tsx"
 import type { ProviderId } from "../../core/setup.ts"
 
 export interface AppDeps {
@@ -43,6 +44,8 @@ export interface AppDeps {
   onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
   onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
+  onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
+  onTourDone: () => void
 }
 
 export function App(deps: AppDeps): React.ReactElement {
@@ -75,7 +78,9 @@ 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} onContinue={deps.onSetupContinue} onSkip={deps.onSetupSkip} />
+      return <SetupScreen locale={deps.locale} onSave={deps.onSetupSave} onContinue={deps.onSetupContinue} onSkip={deps.onSetupSkip} onOAuthHandoff={deps.onSetupOAuthHandoff} />
+    case "tour":
+      return <TourScreen locale={deps.locale} onDone={deps.onTourDone} />
     case "startup":
       return <StartupScreen locale={deps.locale} coursePack={state.coursePack} onStart={deps.onStart} />
     case "mission":

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

@@ -78,8 +78,8 @@ const STRINGS = {
     },
     stars_exhausted: {
       title: "今天的 ⭐ 用完了",
-      body: "明天再来，或者请家长在 airbotix.ai/portal/wallet 充值。",
-      retry: "重试",
+      body: "今天先到这里啦！\n你做得很好，我们明天接着来。\n或者找家长打开 airbotix.ai/portal/wallet 多充一点 ⭐，然后按 Enter 接着做。",
+      retry: "找完家长了，再试一次",
     },
     auth_failed: {
       title: "AI 老师认不出你",
@@ -111,8 +111,8 @@ const STRINGS = {
     },
     stars_exhausted: {
       title: "Out of ⭐ for today",
-      body: "Come back tomorrow, or ask a parent to top up at airbotix.ai/portal/wallet.",
-      retry: "Retry",
+      body: "Great work today!\nWe'll pick this up tomorrow.\nOr ask a parent to top up at airbotix.ai/portal/wallet, then press Enter to keep going.",
+      retry: "Asked a parent — try again",
     },
     auth_failed: {
       title: "AI doesn't recognise you",

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

@@ -7,6 +7,11 @@
  * e → close modal, send a fresh kid prompt of the form "no, do it differently"
  *
  * The PRD uses "y/n/e" to avoid the engineering-vibes of allow/deny.
+ *
+ * For write/edit tools we now render a short preview of the exact file
+ * change the kid is about to approve. Black-box `y` was a trust-without-
+ * verify hole — this closes it AND doubles as a learning surface (the kid
+ * sees what code the AI is producing).
  */
 
 import React from "react"
@@ -22,6 +27,8 @@ interface PermissionModalProps {
   onEdit: () => void
 }
 
+const DIFF_MAX_LINES = 14
+
 export function PermissionModal({ permission, locale, onAllow, onDeny, onEdit }: PermissionModalProps): React.ReactElement {
   const theme = getTheme()
   useInput((input) => {
@@ -31,6 +38,7 @@ export function PermissionModal({ permission, locale, onAllow, onDeny, onEdit }:
     else if (ch === "e") onEdit()
   })
   const t = STRINGS[locale]
+  const preview = extractFilePreview(permission)
   return (
     <Box flexDirection="column" borderStyle="double" borderColor={theme.warn} paddingX={2} paddingY={1}>
       <Text color={theme.warn} bold>{t.title}</Text>
@@ -42,6 +50,22 @@ export function PermissionModal({ permission, locale, onAllow, onDeny, onEdit }:
           <Text color={theme.fgDim}>tool: {permission.tool}</Text>
         </Box>
       )}
+      {preview && (
+        <Box marginTop={1} flexDirection="column" borderStyle="single" borderColor={theme.fgDim} paddingX={1}>
+          <Box>
+            <Text color={theme.accent} bold>{preview.kind === "edit" ? t.editingFile : t.writingFile}: </Text>
+            <Text color={theme.fg}>{preview.path}</Text>
+          </Box>
+          <Box marginTop={1} flexDirection="column">
+            {renderDiffLines(preview, theme)}
+          </Box>
+          {preview.truncated > 0 && (
+            <Box marginTop={1}>
+              <Text color={theme.fgDim} dimColor>{t.truncated(preview.truncated)}</Text>
+            </Box>
+          )}
+        </Box>
+      )}
       {permission.starsEstimated && permission.starsEstimated > 0 && (
         <Box marginTop={1}>
           <Text color={theme.stars}>{t.starsCost(permission.starsEstimated)}</Text>
@@ -59,6 +83,82 @@ export function PermissionModal({ permission, locale, onAllow, onDeny, onEdit }:
   )
 }
 
+type FilePreview =
+  | {
+      kind: "write"
+      path: string
+      lines: string[]
+      truncated: number
+    }
+  | {
+      kind: "edit"
+      path: string
+      removed: string[]
+      added: string[]
+      truncated: number
+    }
+
+/**
+ * opencode write tool metadata: { filePath/path, content }
+ * opencode edit tool metadata: { filePath/path, oldString/old_text, newString/new_text }
+ * Defensive shape extraction — the SDK exposes these as Record<string, unknown>.
+ */
+function extractFilePreview(permission: PendingPermission): FilePreview | null {
+  if (!permission.tool) return null
+  const tool = permission.tool.toLowerCase()
+  const m = permission.metadata ?? {}
+  const path = pickString(m, ["filePath", "path", "file_path", "filename"])
+  if (!path) return null
+
+  if (tool === "write") {
+    const content = pickString(m, ["content", "text", "newContent", "new_content"])
+    if (content === null) return null
+    const all = content.split("\n")
+    const shown = all.slice(0, DIFF_MAX_LINES)
+    return { kind: "write", path, lines: shown, truncated: Math.max(0, all.length - shown.length) }
+  }
+
+  if (tool === "edit") {
+    const oldStr = pickString(m, ["oldString", "old_string", "oldText", "old_text"]) ?? ""
+    const newStr = pickString(m, ["newString", "new_string", "newText", "new_text"]) ?? ""
+    const removed = oldStr.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === ""))
+    const added = newStr.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === ""))
+    const totalLines = removed.length + added.length
+    if (totalLines === 0) return null
+    const half = Math.max(1, Math.floor(DIFF_MAX_LINES / 2))
+    const removedShown = removed.slice(0, half)
+    const addedShown = added.slice(0, DIFF_MAX_LINES - removedShown.length)
+    const truncated = (removed.length - removedShown.length) + (added.length - addedShown.length)
+    return { kind: "edit", path, removed: removedShown, added: addedShown, truncated }
+  }
+
+  return null
+}
+
+function renderDiffLines(preview: FilePreview, theme: ReturnType<typeof getTheme>): React.ReactElement[] {
+  if (preview.kind === "write") {
+    return preview.lines.map((line, i) => (
+      <Text key={`w-${i}`} color={theme.success}>{`+ ${line}`}</Text>
+    ))
+  }
+  const out: React.ReactElement[] = []
+  preview.removed.forEach((line, i) => out.push(
+    <Text key={`r-${i}`} color={theme.danger}>{`- ${line}`}</Text>
+  ))
+  preview.added.forEach((line, i) => out.push(
+    <Text key={`a-${i}`} color={theme.success}>{`+ ${line}`}</Text>
+  ))
+  return out
+}
+
+function pickString(obj: Record<string, unknown>, keys: string[]): string | null {
+  for (const k of keys) {
+    const v = obj[k]
+    if (typeof v === "string") return v
+  }
+  return null
+}
+
 const STRINGS = {
   "zh-Hans": {
     title: "AI 想做这件事",
@@ -66,6 +166,9 @@ const STRINGS = {
     no: "不要",
     edit: "我来改",
     starsCost: (n: number) => `预估消耗 ${n}⭐`,
+    writingFile: "新建文件",
+    editingFile: "改这个文件",
+    truncated: (n: number) => `… 还有 ${n} 行没显示。完整改动会在文件里。`,
   },
   en: {
     title: "The AI wants to do this",
@@ -73,5 +176,8 @@ const STRINGS = {
     no: "Stop",
     edit: "I'll do it",
     starsCost: (n: number) => `Estimated cost: ${n}⭐`,
+    writingFile: "Creating file",
+    editingFile: "Editing file",
+    truncated: (n: number) => `… ${n} more lines not shown. Full change lands in the file.`,
   },
 } as const

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

@@ -20,6 +20,7 @@ import { KidsLogo } from "../components/KidsLogo.tsx"
 import {
   findProvider,
   looksLikeApiKey,
+  OAUTH_PROVIDERS,
   PROVIDERS,
   type ProviderId,
 } from "../../../core/setup.ts"
@@ -30,6 +31,8 @@ type Step =
   | "engine_done"
   | "intro"
   | "provider"
+  | "auth_choice"
+  | "oauth_handoff"
   | "apikey"
   | "saving"
   | "done"
@@ -42,14 +45,21 @@ interface SetupScreenProps {
   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, onContinue, onSkip }: SetupScreenProps): React.ReactElement {
+export function SetupScreen({ locale, onSave, onContinue, onSkip, onOAuthHandoff }: SetupScreenProps): React.ReactElement {
   const theme = getTheme()
   const t = STRINGS[locale]
   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[]>([])
@@ -86,8 +96,54 @@ export function SetupScreen({ locale, onSave, onContinue, onSkip }: SetupScreenP
     } 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) {
         // Inline boot — no exit.
@@ -207,13 +263,68 @@ export function SetupScreen({ locale, onSave, onContinue, onSkip }: SetupScreenP
     )
   }
 
+  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
@@ -243,6 +354,14 @@ export function SetupScreen({ locale, onSave, onContinue, onSkip }: SetupScreenP
         <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>
     )
   }
@@ -303,11 +422,55 @@ 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] 再试",
@@ -328,11 +491,55 @@ 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",

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

@@ -0,0 +1,155 @@
+/**
+ * First-run welcome tour — 3 steps between SetupScreen and StartupScreen.
+ *
+ * Triggered exactly once per install (gated by ~/.config/kids-opencode/tour-seen).
+ * A returning kid who already has env vars set skips this entirely; only
+ * fires when the wizard just ran. Skip ([s]) marks-seen the same as Done.
+ *
+ * Step content maps to the three things a 12-yo first-timer needs to know
+ * before they look at the StartupScreen and freeze:
+ *   1. What is a Course Pack?
+ *   2. How do I talk to the AI?
+ *   3. What do y / n / e mean when the AI asks permission?
+ */
+
+import React, { useState } from "react"
+import { Box, Text, useInput } from "ink"
+import { getTheme } from "../theme.ts"
+import { KidsLogo } from "../components/KidsLogo.tsx"
+
+interface TourScreenProps {
+  locale: "zh-Hans" | "en"
+  onDone: () => void
+}
+
+export function TourScreen({ locale, onDone }: TourScreenProps): React.ReactElement {
+  const theme = getTheme()
+  const t = STRINGS[locale]
+  const [step, setStep] = useState(0)
+  const last = t.steps.length - 1
+
+  useInput((input, key) => {
+    if (input === "s" || input === "S") {
+      onDone()
+      return
+    }
+    if (key.return || key.rightArrow) {
+      if (step >= last) onDone()
+      else setStep((s) => Math.min(last, s + 1))
+      return
+    }
+    if (key.leftArrow) {
+      setStep((s) => Math.max(0, s - 1))
+    }
+  })
+
+  const current = t.steps[step]!
+  const isLast = step === last
+
+  return (
+    <Box flexDirection="column" alignItems="center" paddingY={1}>
+      <KidsLogo />
+      <Box marginTop={1}>
+        <Text color={theme.fgDim}>{t.progress(step + 1, t.steps.length)}</Text>
+      </Box>
+      <Box marginTop={1} borderStyle="round" borderColor={theme.accent} paddingX={3} paddingY={1} flexDirection="column" width={68}>
+        <Text color={theme.accent} bold>{current.title}</Text>
+        <Box marginTop={1} flexDirection="column">
+          {current.body.map((line, i) => (
+            <Text key={i} color={theme.fg}>{line}</Text>
+          ))}
+        </Box>
+      </Box>
+      <Box marginTop={2}>
+        <Text color={theme.accent}>{isLast ? t.startNow : t.next}</Text>
+        <Text color={theme.fg}>  ·  </Text>
+        <Text color={theme.fgDim}>{t.skip}</Text>
+      </Box>
+    </Box>
+  )
+}
+
+const STRINGS = {
+  "zh-Hans": {
+    progress: (cur: number, total: number) => `${cur} / ${total}`,
+    next: "[Enter] 下一步  [←] 上一步",
+    startNow: "[Enter] 开始玩  [←] 上一步",
+    skip: "[s] 跳过引导",
+    steps: [
+      {
+        title: "📦  什么是 Course Pack？",
+        body: [
+          "Course Pack 是老师为你设计好的一组小项目。",
+          "比如：「做一个网站介绍你的小狗」、「画一只 AI 恐龙」。",
+          "",
+          "每个 Pack 里有几个 Mission，一步一步带你完成。",
+          "做完一个 Mission，✨ 就解锁下一个。",
+        ],
+      },
+      {
+        title: "💬  怎么跟我说话？",
+        body: [
+          "直接打中文或英文，按 Enter 发给我。比如：",
+          "  「帮我做一个红色按钮」",
+          "  「换一个更可爱的字体」",
+          "",
+          "想验收一关：打 「我做完了」 或 /check",
+          "想叫我停下来：按 Esc",
+        ],
+      },
+      {
+        title: "🔐  y / n / e — 你说了算",
+        body: [
+          "我要动你的文件之前，会先问你。三个按键：",
+          "",
+          "  [y]  可以做  — 我一次操作",
+          "  [n]  不要    — 我会停下来，换个办法",
+          "  [e]  我来改  — 你自己写这一步，告诉我你想怎么做",
+          "",
+          "我永远不会绕过这一步偷偷改文件。",
+        ],
+      },
+    ],
+  },
+  en: {
+    progress: (cur: number, total: number) => `${cur} / ${total}`,
+    next: "[Enter] next  [←] back",
+    startNow: "[Enter] start playing  [←] back",
+    skip: "[s] skip tour",
+    steps: [
+      {
+        title: "📦  What's a Course Pack?",
+        body: [
+          "A Course Pack is a set of small projects a teacher made for you.",
+          "Like: \"Build a website about your dog\" or \"Draw an AI dinosaur\".",
+          "",
+          "Each Pack has a few Missions, walking you through step by step.",
+          "Finish one Mission, ✨ unlock the next.",
+        ],
+      },
+      {
+        title: "💬  How do I talk to you?",
+        body: [
+          "Just type in English or Chinese and press Enter. For example:",
+          "  \"Make me a red button\"",
+          "  \"Use a cuter font\"",
+          "",
+          "To check off a mission: type \"I'm done\" or /check",
+          "To stop me mid-reply: press Esc",
+        ],
+      },
+      {
+        title: "🔐  y / n / e — you're in charge",
+        body: [
+          "Before I touch your files I'll ask you. Three keys:",
+          "",
+          "  [y]  go ahead   — I'll do it once",
+          "  [n]  stop        — I'll back off and try another way",
+          "  [e]  I'll do it  — you write this step and tell me what you want",
+          "",
+          "I'll never sneak past this to change files on my own.",
+        ],
+      },
+    ],
+  },
+} as const