@kidsinai/kids-client 0.0.2 → 0.0.3

package/package.json

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

@@ -50,7 +50,7 @@ export function readEnv(): KidsClientEnv {
   }
 }
 
-export function validateEnv(env: KidsClientEnv): { ok: true } | { ok: false; reason: string; variant: "config_missing" | "auth_failed" } {
+export function validateEnv(env: KidsClientEnv): { ok: true } | { ok: false; reason: string; variant: "config_missing" | "auth_failed" | "needs_setup" } {
   if (!env.opencodeServerPassword) {
     return {
       ok: false,
@@ -58,11 +58,18 @@ export function validateEnv(env: KidsClientEnv): { ok: true } | { ok: false; rea
       variant: "config_missing",
     }
   }
-  if (!env.bypassGateway && !env.deeprouterApiKey) {
+  // 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.
+  const hasAnyKey =
+    env.deeprouterApiKey
+    || process.env.ANTHROPIC_API_KEY
+    || process.env.OPENAI_API_KEY
+  if (!env.bypassGateway && !hasAnyKey) {
     return {
       ok: false,
-      reason: "DEEPROUTER_API_KEY is empty. Run `kids-opencode register` first, or set KIDS_LLM_BYPASS_GATEWAY=1 with a provider key for dogfood.",
-      variant: "auth_failed",
+      reason: "No LLM provider key found. The first-run setup wizard will walk you through this.",
+      variant: "needs_setup",
     }
   }
   return { ok: true }

package/src/core/setup.ts

@@ -0,0 +1,185 @@
+/**
+ * First-run setup wizard backend.
+ *
+ * Writes:
+ *   ~/.config/kids-opencode/env          (KEY=value, chmod 600)
+ *   ~/.config/kids-opencode/opencode.json (provider + model rewritten)
+ *
+ * The env file is sourced by bin/kids-opencode before exec'ing
+ * kids-client, so the LLM key becomes available to the AI engine
+ * (which reads it via opencode.json's `{env:NAME}` interpolation) without
+ * polluting the user's shell rc.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+export type ProviderId = "anthropic" | "openai" | "deeprouter"
+
+export interface ProviderChoice {
+  id: ProviderId
+  label: string
+  hint: string
+  envVar: string
+  apiKeyUrl: string
+  /** opencode.json provider block to use. apiKey defaults to "{env:<envVar>}". */
+  config: (envVar: string) => Record<string, unknown>
+  /** Default model id for this provider. */
+  defaultModel: string
+}
+
+export const PROVIDERS: ProviderChoice[] = [
+  {
+    id: "anthropic",
+    label: "Anthropic Claude (recommended)",
+    hint: "Best for ages 12+. ~$5/month for typical kid use.",
+    envVar: "ANTHROPIC_API_KEY",
+    apiKeyUrl: "https://console.anthropic.com/settings/keys",
+    config: (env) => ({
+      anthropic: { apiKey: `{env:${env}}` },
+    }),
+    defaultModel: "anthropic/claude-3-5-sonnet-20241022",
+  },
+  {
+    id: "openai",
+    label: "OpenAI GPT-4",
+    hint: "Also works. ~$5-10/month for typical kid use.",
+    envVar: "OPENAI_API_KEY",
+    apiKeyUrl: "https://platform.openai.com/api-keys",
+    config: (env) => ({
+      openai: { apiKey: `{env:${env}}` },
+    }),
+    defaultModel: "openai/gpt-4o",
+  },
+  {
+    id: "deeprouter",
+    label: "DeepRouter (Airbotix's own gateway)",
+    hint: "Not yet live for public use; recommended for staff dogfood only.",
+    envVar: "DEEPROUTER_API_KEY",
+    apiKeyUrl: "https://app.airbotix.ai/portal/wallet",
+    config: (env) => ({
+      deeprouter: {
+        type: "openai-compatible",
+        baseURL: "https://api.deeprouter.ai/v1",
+        apiKey: `{env:${env}}`,
+      },
+    }),
+    defaultModel: "deeprouter/claude-3-5-sonnet",
+  },
+]
+
+export function findProvider(id: ProviderId): ProviderChoice {
+  const p = PROVIDERS.find((p) => p.id === id)
+  if (!p) throw new Error(`unknown provider: ${id}`)
+  return p
+}
+
+export interface SaveOptions {
+  configDir: string
+  provider: ProviderId
+  apiKey: string
+}
+
+/**
+ * Persist the user's choice. Idempotent — re-running overwrites with the
+ * latest. The env file is line-based KEY=value; we preserve unrelated
+ * lines so multi-provider setups don't lose state.
+ */
+export function saveSetup(opts: SaveOptions): void {
+  const provider = findProvider(opts.provider)
+  ensureConfigDir(opts.configDir)
+
+  // 1. Write the env file with the provider's key.
+  const envPath = join(opts.configDir, "env")
+  const existing = readEnvFile(envPath)
+  existing[provider.envVar] = opts.apiKey
+  writeEnvFile(envPath, existing)
+
+  // 2. Rewrite opencode.json provider section.
+  const configPath = join(opts.configDir, "opencode.json")
+  const config = readJsonOrEmpty(configPath)
+  config.provider = provider.config(provider.envVar)
+  config.model = provider.defaultModel
+  if (!config.permission) {
+    config.permission = {
+      default: "ask",
+      tools: { read: "ask", write: "ask", edit: "ask", glob: "ask", grep: "ask", webfetch: "ask" },
+    }
+  }
+  if (!config.agent) {
+    config.agent = { tools: ["read", "write", "edit", "glob", "grep", "webfetch"] }
+  }
+  if (!Array.isArray(config.plugin)) {
+    config.plugin = ["@kidsinai/kids-opencode-plugin"]
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8")
+  chmodSync(configPath, 0o600)
+}
+
+/** True if the user already has a valid key for any supported provider. */
+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
+  // 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
+  )
+}
+
+/** Crude check of API key shape — refuses obvious typos. */
+export function looksLikeApiKey(provider: ProviderId, key: string): boolean {
+  const trimmed = key.trim()
+  if (trimmed.length < 20) return false
+  switch (provider) {
+    case "anthropic":  return trimmed.startsWith("sk-ant-")
+    case "openai":     return trimmed.startsWith("sk-") || trimmed.startsWith("sk-proj-")
+    case "deeprouter": return trimmed.length >= 24
+  }
+}
+
+// ─── internals ────────────────────────────────────────────────────────────
+
+function ensureConfigDir(dir: string): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  try { chmodSync(dir, 0o700) } catch { /* not fatal */ }
+}
+
+function readEnvFile(path: string): Record<string, string> {
+  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
+  }
+  return out
+}
+
+function writeEnvFile(path: string, vars: Record<string, string>): void {
+  ensureConfigDir(dirname(path))
+  const lines: string[] = [
+    "# Generated by kids-opencode setup wizard. Edit at your own risk.",
+    "# The wrapper sources this file before launching the AI engine.",
+  ]
+  for (const [k, v] of Object.entries(vars)) {
+    lines.push(`${k}="${v}"`)
+  }
+  writeFileSync(path, lines.join("\n") + "\n", "utf8")
+  try { chmodSync(path, 0o600) } catch { /* not fatal */ }
+}
+
+function readJsonOrEmpty(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {}
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>
+  } catch {
+    return {}
+  }
+}

package/src/core/store.ts

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

package/src/index.tsx

@@ -29,6 +29,7 @@ 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 type { InstalledPack } from "./core/course-pack.ts"
 import { findMission, loadCoursePack } from "@kidsinai/kids-opencode-plugin"
 
@@ -44,6 +45,14 @@ async function main(): Promise<void> {
 
   const 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))
     return
@@ -197,6 +206,28 @@ interface AppHandlers {
   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)
+    },
+  }
 }
 
 /**
@@ -212,6 +243,7 @@ function baseHandlers(
   serve: ServeManager | null,
 ): AppHandlers {
   const noop = (): void => {}
+  const setup = makeSetupHandlers(store, env)
   return {
     onStart: noop,
     onPrompt: noop,
@@ -245,6 +277,7 @@ function baseHandlers(
     onPickerBack: () => store.update({ screen: { kind: "startup" } }),
     onMissionNext: noop,
     onMissionBack: noop,
+    ...setup,
   }
 }
 
@@ -447,6 +480,7 @@ function fullHandlers(
       })
     },
     onMissionBack: () => store.update({ screen: { kind: "mission" } }),
+    ...makeSetupHandlers(store, env),
   }
 }
 

package/src/render/ink/App.tsx

@@ -21,6 +21,8 @@ import { HelpScreen } from "./screens/HelpScreen.tsx"
 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 type { ProviderId } from "../../core/setup.ts"
 
 export interface AppDeps {
   store: Store
@@ -38,6 +40,8 @@ export interface AppDeps {
   onPickerBack: () => void
   onMissionNext: () => void
   onMissionBack: () => void
+  onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
+  onSetupSkip: () => void
 }
 
 export function App(deps: AppDeps): React.ReactElement {
@@ -69,6 +73,8 @@ export function App(deps: AppDeps): React.ReactElement {
   switch (state.screen.kind) {
     case "loading":
       return <LoadingScreen locale={deps.locale} message={state.screen.message} />
+    case "setup":
+      return <SetupScreen locale={deps.locale} onSave={deps.onSetupSave} onSkip={deps.onSetupSkip} />
     case "startup":
       return <StartupScreen locale={deps.locale} coursePack={state.coursePack} onStart={deps.onStart} />
     case "mission":

package/src/render/ink/components/KidsLogo.tsx

@@ -0,0 +1,70 @@
+/**
+ * "Kids OpenCode" ASCII art logo, color-matched to the brand mark.
+ *
+ * Brand colors (per the official logo):
+ *   K — cyan/blue
+ *   I — orange/yellow
+ *   D — green
+ *   S — magenta/purple
+ *
+ * Each letter is 6 rows × ~7-8 cols of block characters. We render row-by-row
+ * with separate <Text> colors per letter to get the multi-color effect Ink
+ * can't otherwise produce inside a single string.
+ */
+
+import React from "react"
+import { Box, Text } from "ink"
+import { getTheme } from "../theme.ts"
+
+// Block-letter rows. Each letter is a fixed-width column for clean alignment.
+const ROWS: Array<{ K: string; I: string; D: string; S: string }> = [
+  { K: "██╗  ██╗", I: "██╗", D: "██████╗ ", S: "███████╗" },
+  { K: "██║ ██╔╝", I: "██║", D: "██╔══██╗", S: "██╔════╝" },
+  { K: "█████╔╝ ", I: "██║", D: "██║  ██║", S: "███████╗" },
+  { K: "██╔═██╗ ", I: "██║", D: "██║  ██║", S: "╚════██║" },
+  { K: "██║  ██╗", I: "██║", D: "██████╔╝", S: "███████║" },
+  { K: "╚═╝  ╚═╝", I: "╚═╝", D: "╚═════╝ ", S: "╚══════╝" },
+]
+
+const SPARKLE_ROW_TOP    = "      ✦       ⭐         ✦         ⭐      "
+const SPARKLE_ROW_BOTTOM = "    ⭐      ✦        ⭐       ✦       "
+
+export function KidsLogo(): React.ReactElement {
+  const theme = getTheme()
+  // Colors approximate the brand logo. Use "Bright" variants so dark terminals pop.
+  const cK = "cyanBright"
+  const cI = "yellow"
+  const cD = "greenBright"
+  const cS = "magentaBright"
+  const gap = "  " // 2-col gap between letters
+  return (
+    <Box flexDirection="column" alignItems="center">
+      <Text color={theme.accent}>{SPARKLE_ROW_TOP}</Text>
+      {ROWS.map((row, i) => (
+        <Box key={i} flexDirection="row">
+          <Text color={cK}>{row.K}</Text>
+          <Text>{gap}</Text>
+          <Text color={cI}>{row.I}</Text>
+          <Text>{gap}</Text>
+          <Text color={cD}>{row.D}</Text>
+          <Text>{gap}</Text>
+          <Text color={cS}>{row.S}</Text>
+        </Box>
+      ))}
+      <Box marginTop={1}>
+        <Text color={cK} bold>{"<"}</Text>
+        <Text color={cK} bold>{" O"}</Text>
+        <Text color={cD} bold>{"p"}</Text>
+        <Text color={cD} bold>{"e"}</Text>
+        <Text color={cD} bold>{"n"}</Text>
+        <Text color={cD} bold>{"C"}</Text>
+        <Text color={cK} bold>{"o"}</Text>
+        <Text color={cS} bold>{"d"}</Text>
+        <Text color={cS} bold>{"e "}</Text>
+        <Text color={cS} bold>{">"}</Text>
+      </Box>
+      <Text color={cS}>{"     ━━━━━━━━━━━━━     "}</Text>
+      <Text color={theme.accent}>{SPARKLE_ROW_BOTTOM}</Text>
+    </Box>
+  )
+}

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

@@ -0,0 +1,232 @@
+/**
+ * First-run setup wizard. Triggered when kids-client detects no LLM
+ * provider key is configured.
+ *
+ * Audience: a parent (the kid sees the intro and is told to grab a
+ * grown-up). The wizard walks through:
+ *   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).
+ */
+
+import React, { useState } from "react"
+import { Box, Text, useInput } from "ink"
+import TextInput from "ink-text-input"
+import { getTheme } from "../theme.ts"
+import { KidsLogo } from "../components/KidsLogo.tsx"
+import {
+  findProvider,
+  looksLikeApiKey,
+  PROVIDERS,
+  type ProviderId,
+} from "../../../core/setup.ts"
+
+type Step = "intro" | "provider" | "apikey" | "saving" | "done" | "error"
+
+interface SetupScreenProps {
+  locale: "zh-Hans" | "en"
+  onSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
+  onSkip: () => void
+}
+
+export function SetupScreen({ locale, onSave, onSkip }: SetupScreenProps): React.ReactElement {
+  const theme = getTheme()
+  const t = STRINGS[locale]
+  const [step, setStep] = useState<Step>("intro")
+  const [providerIdx, setProviderIdx] = useState(0)
+  const [apiKey, setApiKey] = useState("")
+  const [errorMsg, setErrorMsg] = useState("")
+
+  useInput((input, key) => {
+    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.escape) setStep("intro")
+    } else if (step === "done") {
+      if (key.return) onSkip() // continue to startup
+    } else if (step === "error") {
+      if (key.return) setStep("apikey")
+    }
+  })
+
+  const provider = PROVIDERS[providerIdx]!
+  const providerObj = findProvider(provider.id)
+
+  if (step === "intro") {
+    return (
+      <Box flexDirection="column" alignItems="center" paddingY={1}>
+        <KidsLogo />
+        <Box marginTop={2} borderStyle="round" borderColor={theme.warn} paddingX={2} paddingY={1} flexDirection="column">
+          <Text color={theme.warn} bold>{t.introTitle}</Text>
+          <Box marginTop={1} flexDirection="column">
+            <Text color={theme.fg}>{t.introLine1}</Text>
+            <Text color={theme.fg}>{t.introLine2}</Text>
+          </Box>
+          <Box marginTop={1}>
+            <Text color={theme.fgDim}>{t.introCost}</Text>
+          </Box>
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.accent}>{t.introContinue}</Text>
+        </Box>
+      </Box>
+    )
+  }
+
+  if (step === "provider") {
+    return (
+      <Box flexDirection="column" borderStyle="double" borderColor={theme.accent} paddingX={2} paddingY={1}>
+        <Text color={theme.accent} bold>{t.providerTitle}</Text>
+        <Box marginTop={1} flexDirection="column">
+          {PROVIDERS.map((p, i) => {
+            const active = i === providerIdx
+            return (
+              <Box key={p.id}>
+                <Text color={active ? theme.kid : theme.fg}>{active ? "▶ " : "  "}</Text>
+                <Box flexDirection="column" flexGrow={1}>
+                  <Text color={active ? theme.accent : theme.fg} bold={active}>{p.label}</Text>
+                  <Text color={theme.fgDim} dimColor={!active}>  {p.hint}</Text>
+                  {active && <Text color={theme.fgDim}>  {t.getKey}: {p.apiKeyUrl}</Text>}
+                </Box>
+              </Box>
+            )
+          })}
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.accent}>{t.providerKeys}</Text>
+        </Box>
+      </Box>
+    )
+  }
+
+  if (step === "apikey") {
+    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}>
+          <Text color={theme.kid}>🔑  </Text>
+          <TextInput
+            value={apiKey}
+            onChange={setApiKey}
+            onSubmit={(v) => {
+              const k = v.trim()
+              if (!looksLikeApiKey(provider.id, k)) {
+                setErrorMsg(t.apiKeyInvalid(providerObj.envVar))
+                setStep("error")
+                return
+              }
+              setStep("saving")
+              void onSave(provider.id, k).then((res) => {
+                if (res.ok) {
+                  setStep("done")
+                } else {
+                  setErrorMsg(res.reason)
+                  setStep("error")
+                }
+              })
+            }}
+            placeholder={t.apiKeyPlaceholder(providerObj.envVar)}
+            mask="*"
+          />
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.fgDim}>{t.apiKeyEnter}</Text>
+        </Box>
+      </Box>
+    )
+  }
+
+  if (step === "saving") {
+    return (
+      <Box paddingY={1} paddingX={2}>
+        <Text color={theme.accent}>{t.saving}</Text>
+      </Box>
+    )
+  }
+
+  if (step === "error") {
+    return (
+      <Box flexDirection="column" borderStyle="round" borderColor={theme.danger} paddingX={2} paddingY={1}>
+        <Text color={theme.danger} bold>{t.errTitle}</Text>
+        <Box marginTop={1}>
+          <Text color={theme.fg}>{errorMsg}</Text>
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.accent}>{t.errRetry}</Text>
+        </Box>
+      </Box>
+    )
+  }
+
+  // step === "done"
+  return (
+    <Box flexDirection="column" alignItems="center" paddingY={1}>
+      <KidsLogo />
+      <Box marginTop={2} flexDirection="column" alignItems="center">
+        <Text color={theme.success} bold>{t.doneTitle}</Text>
+        <Box marginTop={1}>
+          <Text color={theme.fg}>{t.doneNext}</Text>
+        </Box>
+        <Box marginTop={1}>
+          <Text color={theme.accent}>{t.doneHint}</Text>
+        </Box>
+      </Box>
+    </Box>
+  )
+}
+
+const STRINGS = {
+  "zh-Hans": {
+    introTitle: "👋  这一步需要家长帮忙",
+    introLine1: "AI 老师要用一个 \"API key\" 才能工作 —— 就像给它一把钥匙。",
+    introLine2: "家长打开账号给 AI 服务（Anthropic / OpenAI 等），拿到 key 粘进来就行。",
+    introCost: "通常 ~$5/月，普通孩子用够了。",
+    introContinue: "[Enter] 让家长来  ·  [s] 暂时跳过",
+    providerTitle: "选一个 AI 服务",
+    providerKeys: "[↑↓] 选 · [Enter] 下一步 · [Esc] 返回",
+    getKey: "去拿 key",
+    apiKeyTitle: (label: string) => `输入 ${label} 的 API key`,
+    apiKeyHint: (url: string) => `没 key？打开浏览器：${url}`,
+    apiKeyPlaceholder: (env: string) => `${env}（粘进来后按 Enter）`,
+    apiKeyEnter: "[Enter] 保存 · 你的 key 只存在本地",
+    apiKeyInvalid: (env: string) => `这看起来不是有效的 ${env}。再试一次。`,
+    saving: "保存中…",
+    errTitle: "出了点问题",
+    errRetry: "[Enter] 再试",
+    doneTitle: "🎉  搞定！家长任务完成。",
+    doneNext: "你可以让孩子继续了。下一屏是启动屏。",
+    doneHint: "[Enter] 开始",
+  },
+  en: {
+    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.",
+    introCost: "Usually ~$5/month for typical kid use.",
+    introContinue: "[Enter] Hand to a grown-up  ·  [s] Skip for now",
+    providerTitle: "Pick an AI service",
+    providerKeys: "[↑↓] choose · [Enter] next · [Esc] back",
+    getKey: "Get key at",
+    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.",
+    apiKeyInvalid: (env: string) => `That doesn't look like a valid ${env}. Try again.`,
+    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.",
+    doneHint: "[Enter] Start",
+  },
+} as const

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

@@ -2,15 +2,16 @@
  * §3.1 Startup screen — first impression. Must paint within 5s.
  *
  * Quick keys:
- *   Enter → start a free-play session
- *   c     → choose a Course Pack (V0 MVP: hardcoded portfolio-site)
- *   r     → resume the last session (V0 MVP: not implemented yet)
- *   h     → show help (kid-friendly)
+ *   Enter → start a free-play session OR continue if a course pack is set
+ *   c     → choose a Course Pack
+ *   r     → resume the last session
+ *   h     → show kid-friendly help
  */
 
 import React from "react"
 import { Box, Text, useInput } from "ink"
 import { getTheme } from "../theme.ts"
+import { KidsLogo } from "../components/KidsLogo.tsx"
 import { KeyHints } from "../components/KeyHints.tsx"
 
 interface StartupScreenProps {
@@ -29,23 +30,23 @@ export function StartupScreen({ locale, coursePack, onStart }: StartupScreenProp
   })
   const t = STRINGS[locale]
   return (
-    <Box flexDirection="column" paddingY={1}>
-      <Box borderStyle="double" borderColor={theme.border} paddingX={2} paddingY={1} flexDirection="column">
-        <Text color={theme.accent} bold>
-          Airbotix Kids OpenCode
-        </Text>
-        <Box marginTop={1} flexDirection="column">
-          <Text color={theme.fg}>{t.greet1}</Text>
-          <Text color={theme.fg}>{t.greet2}</Text>
-        </Box>
-        <Box marginTop={1}>
-          <Text color={theme.fgDim}>{t.disclaim}</Text>
-        </Box>
-        <Box marginTop={1}>
-          <Text color={theme.warn}>{t.helpline}</Text>
-        </Box>
+    <Box flexDirection="column" alignItems="center" paddingY={1}>
+      <KidsLogo />
+      <Box marginTop={1} flexDirection="column" alignItems="center">
+        <Text color={theme.kid} bold>{t.tagline}</Text>
+      </Box>
+      <Box marginTop={1} flexDirection="column" alignItems="center">
+        <Text color={theme.fg}>{t.line1}</Text>
+        <Text color={theme.fg}>{t.line2}</Text>
+        <Text color={theme.fg}>{t.line3}</Text>
+      </Box>
+      <Box marginTop={1}>
+        <Text color={theme.fgDim}>{t.disclaim}</Text>
       </Box>
       <Box marginTop={1}>
+        <Text color={theme.warn} bold>{t.helpline}</Text>
+      </Box>
+      <Box marginTop={2}>
         <KeyHints hints={[
           { key: "Enter", label: coursePack ? t.startCourse : t.startFree },
           { key: "c", label: t.pickCourse },
@@ -59,10 +60,12 @@ export function StartupScreen({ locale, coursePack, onStart }: StartupScreenProp
 
 const STRINGS = {
   "zh-Hans": {
-    greet1: "你好！我是 Kids OpenCode —— 帮你做编程项目的 AI 老师。",
-    greet2: "",
-    disclaim: "我不是真人，有时候会答错。遇到不懂的，问家长或老师。",
-    helpline: "澳大利亚紧急求助：Kids Helpline 1800 55 1800",
+    tagline: "🤖  你的 AI 编程伙伴  🤖",
+    line1: "✨  跟 AI 一起做真实的项目",
+    line2: "💡  没有工程师术语，听得懂",
+    line3: "🎯  做完一关 → 庆祝下一关",
+    disclaim: "我不是真人，有时候会答错。问家长或老师。",
+    helpline: "🇦🇺  紧急求助：Kids Helpline 1800 55 1800",
     startFree: "开始新项目",
     startCourse: "继续 Course Pack",
     pickCourse: "选 Course Pack",
@@ -70,10 +73,12 @@ const STRINGS = {
     help: "帮助",
   },
   en: {
-    greet1: "Hi! I'm Kids OpenCode — the AI teacher who helps you build coding projects.",
-    greet2: "",
-    disclaim: "I'm not a real person and I can be wrong. Ask a parent or teacher if you're unsure.",
-    helpline: "In Australia: Kids Helpline 1800 55 1800",
+    tagline: "🤖  Your AI coding buddy  🤖",
+    line1: "✨  Build real projects with AI help",
+    line2: "💡  No engineering jargon — easy to follow",
+    line3: "🎯  Finish a mission → celebrate the next one",
+    disclaim: "I'm not a real person and I can be wrong. Ask a parent or teacher.",
+    helpline: "🇦🇺  Emergency: Kids Helpline 1800 55 1800",
     startFree: "Start a new project",
     startCourse: "Continue Course Pack",
     pickCourse: "Pick a Course Pack",