@homie-rocks/studio 0.10.0 → 0.11.0

package/lib/doctor.mjs

@@ -0,0 +1,279 @@
+/**
+ * `homie-studio setup status` (also `homie-studio doctor`): what this computer and this person's accounts have for
+ * a studio, as one checklist, before anything is made. For each thing: green, missing, or "do this now", what it
+ * unlocks, and the exact fix: one command the AI runs, or one page the person taps.
+ *
+ *   Node.js            required    the toolkit runs on it
+ *   Homie connector    required    the directory, cards and the pinned toolkit's address (the AI says whether its
+ *                                  Homie tools are there: --connector yes|no)
+ *   Cloudflare         to go online: signed in, and the account's email verified (Cloudflare checks that at the
+ *                                  first deploy; a deploy that went through proves it)
+ *   Chrome             for checks  the two-browser check, the look pictures and playtests
+ *   ffmpeg             recommended sound effects and the theme, trailers and hero footage
+ *   GitHub             optional    a private backup, publishing by pull request, building from the Claude app
+ *   ElevenLabs         optional    songs and game scores
+ *   fal                optional    painted art and generated video
+ *   status line        optional    (Claude Code only) the build's progress under the prompt
+ *
+ * It is safe at any time, inside a studio or before one exists: it only reads (local files, `--version` of a few
+ * tools, `wrangler whoami`, `gh auth status`, `elevenlabs auth status`, one GET to the directory and, when a fal key
+ * is set, fal's free pricing API), never changes anything, and never prints a key, a token or an account's name.
+ * Every check has a time limit, so it answers in seconds even with no network.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findChrome } from './chrome.mjs';
+import { isOurs } from './statusline.mjs';
+import { findStudio, readLocal, readStudio } from './studio.mjs';
+import { STUDIO_VERSION } from './version.mjs';
+
+/** A command's result, never throwing: code 127 when the program is not installed, 124 when it ran out of time. */
+export function defaultExec(cmd, args, { cwd, timeout = 8000, env } = {}) {
+  return new Promise((done) => {
+    let stdout = ''; let stderr = ''; let settled = false;
+    const finish = (r) => { if (!settled) { settled = true; clearTimeout(timer); done(r); } };
+    let child;
+    try { child = spawn(cmd, args, { cwd, env: env ?? process.env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); } catch (error) { finish({ code: 127, stdout: '', stderr: String(error?.message ?? error) }); return; }
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } finish({ code: 124, stdout, stderr }); }, timeout);
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', (error) => finish({ code: error.code === 'ENOENT' ? 127 : 1, stdout, stderr: String(error.message) }));
+    child.on('close', (code) => finish({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+const MARK = { ok: '✓', act: '→', missing: '✗', optional: '○', later: '…', unknown: '?' };
+const RANK = { missing: 0, act: 1, unknown: 2, later: 3, optional: 4, ok: 5 };
+const worst = (states) => states.reduce((a, b) => (RANK[b] < RANK[a] ? b : a), 'ok');
+
+async function reach(url, fetchFn, ms = 5000) {
+  try {
+    const res = await fetchFn(url, { method: 'GET', headers: { 'user-agent': `homie-studio/${STUDIO_VERSION}`, accept: 'application/json' }, signal: AbortSignal.timeout(ms) });
+    const deny = res.headers?.get?.('x-deny-reason') ?? '';
+    if (res.status === 403 && /host_not_allowed/i.test(deny)) return { ok: false, blocked: true };
+    return { ok: true, status: res.status };
+  } catch (error) { return { ok: false, why: error?.name === 'TimeoutError' ? 'did not answer in time' : 'did not answer' }; }
+}
+
+/**
+ * The checklist. `connector`: what the AI knows about its own tools ('yes' when the Homie MCP tools such as
+ * studio_scaffold are in its tool list, 'no' when they are not, null when unsaid). `exec` and `fetchFn` are
+ * replaceable for tests.
+ */
+export async function setupStatus({
+  cwd = process.cwd(), env = process.env, platform = process.platform, connector = null, homie = null,
+  exec = defaultExec, fetchFn = globalThis.fetch, chrome = findChrome, node = process.versions.node,
+} = {}) {
+  const root = findStudio(cwd);
+  let studio = null;
+  try { studio = root ? readStudio(root) : null; } catch { studio = null; }
+  const cli = root ? 'npx --no-install homie-studio' : `npx -y @homie-rocks/studio@${STUDIO_VERSION}`;
+  let directory = String(homie || (studio?.homie?.directory && typeof studio.homie.directory === 'string' ? studio.homie.directory : 'https://homie.rocks')).replace(/\/+$/, '');
+  try { new URL(directory); } catch { directory = 'https://homie.rocks'; }
+  const mac = platform === 'darwin';
+  const win = platform === 'win32';
+  const rows = [];
+
+  // Node.js
+  const major = Number(String(node).split('.')[0]);
+  rows.push({
+    id: 'node', label: 'Node.js', need: 'required', state: major >= 22 ? 'ok' : 'missing', detail: `v${node}${major >= 22 ? '' : ' (22 or newer is needed)'}`,
+    unlocks: 'everything: the studio\'s toolkit runs on it',
+    fix: major >= 22 ? null : { who: 'person', open: 'https://nodejs.org/en/download', say: 'Install Node.js 22 or newer (the LTS download), then start a new session.' },
+  });
+
+  // The Homie connector (the AI says; the network is checked here), Cloudflare, GitHub and the providers, at once.
+  const said = connector === true || connector === 'yes' ? 'yes' : connector === false || connector === 'no' ? 'no' : null;
+  const [net, who, gh, eleven, fal] = await Promise.all([
+    reach(`${directory}/mcp`, fetchFn),
+    (async () => {
+      if (env.CLOUDFLARE_API_TOKEN) return { signedIn: true, how: 'an API token in the environment' };
+      const bin = root ? join(root, 'node_modules', '.bin', win ? 'wrangler.cmd' : 'wrangler') : null;
+      if (!bin || !existsSync(bin)) return { signedIn: null };
+      const r = await exec(bin, ['whoami', '--json'], { cwd: root, timeout: 25_000, env: { ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' } });
+      if (r.code === 124) return { signedIn: null, why: 'Wrangler did not answer in time' };
+      try { const d = JSON.parse(r.stdout.slice(Math.max(0, r.stdout.indexOf('{')))); return { signedIn: Boolean(d.loggedIn), accounts: Array.isArray(d.accounts) ? d.accounts.length : null }; } catch { return { signedIn: false }; }
+    })(),
+    (async () => {
+      const git = await exec('git', ['--version']);
+      // The studio's own repository: on GitHub (a Claude app studio always is: its setup card made it there).
+      const remote = root && git.code === 0 ? (await exec('git', ['remote', 'get-url', 'origin'], { cwd: root })).stdout.trim() : '';
+      const onGitHub = /(^|[/@.])github\.com[/:]/i.test(remote);
+      if (env.GH_TOKEN || env.GITHUB_TOKEN) return { git: git.code === 0, gh: true, signedIn: true, onGitHub };
+      const v = await exec('gh', ['--version']);
+      if (v.code !== 0) return { git: git.code === 0, gh: false, signedIn: false, onGitHub };
+      return { git: git.code === 0, gh: true, signedIn: (await exec('gh', ['auth', 'status'], { timeout: 10_000 })).code === 0, onGitHub };
+    })(),
+    (async () => {
+      const cliBin = env.ELEVENLABS_CLI || 'elevenlabs';
+      const v = await exec(cliBin, ['--version']);
+      let signedIn = false;
+      if (v.code === 0) {
+        const s = await exec(cliBin, ['auth', 'status', '--format', 'json'], { timeout: 10_000 });
+        try { signedIn = Boolean(JSON.parse(s.stdout)?.schemes?.some((x) => x.logged_in)); } catch { signedIn = false; }
+      }
+      return { cli: v.code === 0, signedIn, key: Boolean(env.ELEVENLABS_API_KEY) };
+    })(),
+    (async () => {
+      const key = String(env.FAL_KEY ?? '').trim();
+      if (!key) return { key: false };
+      const base = String(env.FAL_API_URL || 'https://api.fal.ai').replace(/\/+$/, '');
+      try {
+        const res = await fetchFn(`${base}/v1/models/pricing?endpoint_id=fal-ai/flux/dev`, { headers: { Authorization: `Key ${key}` }, signal: AbortSignal.timeout(6000) });
+        return { key: true, valid: res.ok ? true : res.status === 401 || res.status === 403 ? false : null };
+      } catch { return { key: true, valid: null }; }
+    })(),
+  ]);
+
+  // The Homie connector.
+  {
+    const fixConnector = {
+      who: 'person',
+      say: 'Turn the Homie connector on. Claude Code: run /plugin, install or enable "homie" (marketplace homie-rocks/homie), then /mcp shows homie connected. Codex: install the Homie plugin from the same marketplace. The Claude app: Settings, Connectors, Add custom connector, https://homie.rocks/mcp; then its setup card (studio_setup) makes the studio on your own Cloudflare and GitHub in three taps.',
+    };
+    let state; let detail;
+    if (net.blocked) { state = 'act'; detail = `this environment's network does not reach ${new URL(directory).host}`; }
+    else if (said === 'yes') { state = 'ok'; detail = net.ok ? 'the Homie tools are here, and the directory answers' : `the Homie tools are here; ${new URL(directory).host} ${net.why ?? 'did not answer'} just now`; }
+    else if (said === 'no') { state = 'act'; detail = 'the Homie tools are not in this session'; }
+    else { state = net.ok ? 'unknown' : 'act'; detail = net.ok ? `${new URL(directory).host} answers; your AI knows whether its Homie tools (studio_scaffold) are here` : `${new URL(directory).host} ${net.why ?? 'did not answer'}`; }
+    rows.push({
+      id: 'connector', label: 'Homie connector', need: 'required', state, detail,
+      unlocks: 'making the studio with the right toolkit version, listing games in the homie.rocks directory, and the cards in the Claude app',
+      fix: state === 'ok' ? null : net.blocked
+        ? { who: 'person', say: `In claude.ai/code, open this environment's settings, set Network access to Custom, add ${new URL(directory).host} (keep the default package managers), and start a new session.` }
+        : fixConnector,
+    });
+  }
+
+  // Cloudflare: signed in, and the account's email verified.
+  {
+    const local = root ? readLocal(root) : {};
+    const created = studio?.cloudflare?.created ?? [];
+    const deployed = Boolean(local.deployedAt || created.some((c) => String(c).startsWith('worker:')));
+    // A studio the Claude app's setup card made (`setup attach` wrote connectedAt): Cloudflare's Deploy button made
+    // it on the person's account and Workers Builds deploys every merge, so no sign-in is needed on this computer.
+    const attached = Boolean(local.connectedAt);
+    const signedIn = attached || who.signedIn === true ? 'ok' : who.signedIn === false ? 'act' : 'later';
+    const verified = deployed || attached ? 'ok' : local.needs === 'cloudflare-verify-email' ? 'act' : 'later';
+    const parts = attached ? [
+      { label: 'connected', state: 'ok', detail: 'through the Claude app\'s setup card (Deploy to Cloudflare); Workers Builds deploys every merge' },
+      { label: 'email verified', state: 'ok', detail: 'the site is live' },
+    ] : [
+      { label: 'signed in', state: signedIn, detail: who.signedIn === true ? (who.how ?? `${who.accounts ?? 1} account${who.accounts === 1 || who.accounts === null || who.accounts === undefined ? '' : 's'}`) : who.signedIn === false ? 'not signed in' : root ? (who.why ?? 'run npm install in the studio, then this again') : 'checked once the studio exists (it brings its own Wrangler)' },
+      { label: 'email verified', state: verified, detail: deployed ? 'a deploy went through' : verified === 'act' ? 'the last deploy was refused until it is' : 'Cloudflare checks it at the first deploy' },
+    ];
+    const fix = attached ? null : signedIn === 'act'
+      ? { who: 'ai', run: 'npx wrangler login', say: 'Cloudflare opens in your browser: approve once. A free account works; no payment method.', open: 'https://dash.cloudflare.com/sign-up' }
+      : verified === 'act'
+        ? { who: 'person', open: 'https://dash.cloudflare.com/profile', say: 'Open the email Cloudflare sent and click its link (or Profile, "Send verification email"); then deploy again.' }
+        : signedIn === 'later' || verified === 'later'
+          ? { who: 'person', open: 'https://dash.cloudflare.com/sign-up', say: 'No Cloudflare account yet? Make a free one now (no payment method) and click the link in the email it sends. Your AI signs in for you later; you approve once.' }
+          : null;
+    rows.push({
+      id: 'cloudflare', label: 'Cloudflare', need: 'to go online', state: worst(parts.map((p) => p.state)), detail: parts.map((p) => `${p.label}: ${p.detail}`).join('; '), parts,
+      unlocks: 'putting the studio\'s site and public rooms online, on its own free Cloudflare account', fix,
+    });
+  }
+
+  // Chrome, for the checks.
+  {
+    const found = chrome();
+    rows.push({
+      id: 'chrome', label: 'Chrome', need: 'for checks', state: found ? 'ok' : 'act', detail: found ? 'found' : 'no Chrome on this computer',
+      unlocks: 'the two-browser check, the look pictures and playtests (games build and run without it)',
+      fix: found ? null : { who: 'ai', run: `${cli} chrome install`, say: 'Chrome for Testing goes into a cache folder (about 150 MB), only for the checks.', open: mac || win ? 'https://www.google.com/chrome/' : undefined },
+    });
+  }
+
+  // ffmpeg.
+  {
+    const ok = (await exec('ffmpeg', ['-version'])).code === 0;
+    rows.push({
+      id: 'ffmpeg', label: 'ffmpeg', need: 'recommended', state: ok ? 'ok' : 'optional', detail: ok ? 'found' : 'not installed',
+      unlocks: 'sound effects and a synthesized theme (free, on this computer), trailers, and footage in a landing page\'s hero',
+      fix: ok ? null : mac ? { who: 'ai', run: 'brew install ffmpeg', say: 'about a minute with Homebrew; you approve the install.' }
+        : win ? { who: 'ai', run: 'winget install --id Gyan.FFmpeg -e', say: 'you approve the install.' }
+          : { who: 'person', say: 'Install your system\'s ffmpeg package (for example: sudo apt-get install -y ffmpeg).' },
+    });
+  }
+
+  // GitHub.
+  rows.push({
+    id: 'github', label: 'GitHub', need: 'optional', state: gh.signedIn || gh.onGitHub ? 'ok' : 'optional',
+    detail: [gh.onGitHub ? 'this studio\'s repository is on GitHub' : null, gh.signedIn ? 'the GitHub CLI is signed in' : gh.gh ? 'the GitHub CLI is here, not signed in' : gh.git ? 'git is here; no GitHub CLI' : 'no git'].filter(Boolean).join('; '),
+    unlocks: 'a private backup of the studio, publishing changes by pull request, and building from the Claude app',
+    fix: gh.signedIn || gh.onGitHub ? null : gh.gh
+      ? { who: 'ai', run: 'gh auth login --hostname github.com --git-protocol https --web', say: 'GitHub shows a one-time code: open https://github.com/login/device, type it and approve.' }
+      : { who: 'person', open: 'https://github.com/signup', say: `Make a free GitHub account; your AI installs the GitHub CLI${mac ? ' (brew install gh)' : ''} when you want the backup.` },
+  });
+
+  // ElevenLabs.
+  rows.push({
+    id: 'elevenlabs', label: 'ElevenLabs', need: 'optional', state: eleven.signedIn || eleven.key ? 'ok' : 'optional',
+    detail: eleven.signedIn ? 'the elevenlabs CLI is signed in' : eleven.key ? 'ELEVENLABS_API_KEY is set' : eleven.cli ? 'the elevenlabs CLI is here, not signed in' : 'not connected',
+    unlocks: 'songs and game scores (the music skill), billed to your own ElevenLabs plan; every render is quoted first',
+    fix: eleven.signedIn || eleven.key ? null : eleven.cli
+      ? { who: 'ai', run: 'elevenlabs auth login', say: 'ElevenLabs opens in your browser; sign in once. No key is pasted anywhere.' }
+      : { who: mac ? 'ai' : 'person', run: mac ? 'brew install elevenlabs/tap/elevenlabs && elevenlabs auth login' : undefined, open: 'https://elevenlabs.io/sign-up', say: 'Make an ElevenLabs account when you want songs; your AI installs their CLI and you sign in once in the browser.' },
+  });
+
+  // fal.
+  rows.push({
+    id: 'fal', label: 'fal', need: 'optional', state: fal.key ? (fal.valid === false ? 'act' : 'ok') : 'optional',
+    detail: !fal.key ? 'no FAL_KEY in this environment' : fal.valid === true ? 'FAL_KEY is set and fal accepts it' : fal.valid === false ? 'fal refused the FAL_KEY that is set (wrong or revoked)' : 'FAL_KEY is set (fal did not answer just now)',
+    unlocks: 'painted art and backdrops (the art skill) and generated video clips (the video skill), on your own fal account under a budget; covers from a real frame and captured trailers are free',
+    fix: fal.key && fal.valid !== false ? null : { who: 'person', open: 'https://fal.ai/dashboard/keys', say: 'Make a key, put FAL_KEY in the environment your AI runs in (for example a line in your shell profile), and start a new session. Never paste it into the chat.' },
+  });
+
+  // The Claude Code status line (only in Claude Code, only in a studio).
+  if (root && env.CLAUDECODE === '1') {
+    let on = false;
+    try { on = isOurs(JSON.parse(readFileSync(join(root, '.claude', 'settings.local.json'), 'utf8')).statusLine); } catch { on = false; }
+    rows.push({
+      id: 'statusline', label: 'Status line', need: 'optional', state: on ? 'ok' : 'optional', detail: on ? 'on in this studio' : 'off',
+      unlocks: 'the current build\'s stage and a progress bar under the prompt in Claude Code',
+      fix: on ? null : { who: 'ai', run: 'npx --no-install homie-studio statusline --install', say: 'one line under the prompt; off again with --remove.' },
+    });
+  }
+
+  const by = Object.fromEntries(rows.map((r) => [r.id, r]));
+  const ready = (state) => (state === 'ok' ? 'ready' : state === 'later' ? 'later' : 'not yet');
+  const features = [
+    { feature: 'Make games and play them here', state: ready(by.node.state), needs: ['node'] },
+    { feature: 'Two-browser checks and playtests', state: ready(by.chrome.state), needs: ['chrome'] },
+    { feature: 'Sound effects and a theme (free)', state: ready(by.ffmpeg.state), needs: ['ffmpeg'] },
+    { feature: 'Put the studio online', state: ready(by.cloudflare.parts[0].state === 'ok' ? by.cloudflare.parts[1].state : by.cloudflare.parts[0].state), needs: ['cloudflare'] },
+    { feature: 'List games in the homie.rocks directory', state: ready(by.connector.state), needs: ['connector'] },
+    { feature: 'Backup and pull requests', state: ready(by.github.state), needs: ['github'] },
+    { feature: 'Songs and game scores', state: ready(by.elevenlabs.state), needs: ['elevenlabs'] },
+    { feature: 'Painted art and generated video', state: ready(by.fal.state), needs: ['fal'] },
+  ];
+  const now = rows.filter((r) => ['missing', 'act'].includes(r.state) && r.fix);
+  const meanwhile = rows.filter((r) => r.fix?.open && r.state !== 'ok' && (r.fix.who === 'person' || r.state === 'later'));
+  return {
+    ok: true, command: 'setup status', version: STUDIO_VERSION,
+    studio: root ? { name: studio?.name ?? null, root } : null,
+    rows, features,
+    blocking: rows.filter((r) => r.state === 'missing').map((r) => r.id),
+    next: now.map((r) => ({ id: r.id, who: r.fix.who, run: r.fix.run ?? null, open: r.fix.open ?? null, say: r.fix.say })),
+    meanwhile: meanwhile.map((r) => ({ id: r.id, open: r.fix.open, say: r.fix.say })),
+    note: 'Optional rows never block anything: each one is set up the first time a feature needs it.',
+  };
+}
+
+/** The checklist as a person reads it in a terminal. */
+export function formatStatus(r) {
+  const lines = [`Setup status${r.studio?.name ? ` for ${r.studio.name}` : ' (before the studio exists)'}`, ''];
+  const pad = Math.max(...r.rows.map((x) => x.label.length)) + 2;
+  for (const row of r.rows) {
+    lines.push(`  ${MARK[row.state] ?? '?'} ${row.label.padEnd(pad)}${row.need === 'optional' ? '(optional) ' : row.need === 'recommended' ? '(recommended) ' : ''}${row.parts ? row.parts.map((p) => `${MARK[p.state]} ${p.label}: ${p.detail}`).join('  ') : row.detail}`);
+    lines.push(`    ${''.padEnd(pad)}unlocks ${row.unlocks}`);
+    if (row.fix && row.state !== 'ok') lines.push(`    ${''.padEnd(pad)}${row.fix.run ? `fix: ${row.fix.run}  ` : ''}${row.fix.open ? `${row.fix.run ? '' : 'fix: '}${row.fix.open}  ` : ''}${row.fix.say}`);
+  }
+  lines.push('', `Ready: ${r.features.map((f) => `${f.feature} ${f.state === 'ready' ? MARK.ok : f.state === 'later' ? MARK.later : MARK.optional}`).join(' · ')}`);
+  if (r.next.length) lines.push('', 'Do this now:', ...r.next.map((n) => `  ${MARK.act} ${n.run ?? n.open ?? ''}  ${n.say}`));
+  if (r.meanwhile.length) lines.push('', 'Safe to do any time, even while you wait for something else:', ...r.meanwhile.map((m) => `  ${m.open}  ${m.say}`));
+  lines.push('', r.note, `(${MARK.ok} ready  ${MARK.act} do this now  ${MARK.missing} missing  ${MARK.optional} optional, not set up  ${MARK.later} checked later  ? your AI knows)`);
+  return lines.join('\n');
+}

package/lib/feed-summary.mjs

@@ -0,0 +1,88 @@
+/**
+ * A build's progress feed (lib/progress.mjs), read for a person at a glance: how far along it is (a percentage and
+ * the stage it is in), its checks, its preview and what it spent. The Game Codex page (lib/codex.mjs) and the Claude
+ * Code status line (lib/statusline.mjs) both draw from this, so they always agree.
+ *
+ * Read-only and small on purpose: the status line runs it every few seconds, so it imports nothing but node:fs.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const KIND = 'homie-studio-progress';
+const DIR = join('.studio', 'progress');
+const BUILD_ID = /^[a-z0-9][a-z0-9-]{5,63}$/;
+
+function read(root, id) {
+  if (!BUILD_ID.test(String(id ?? ''))) return null;
+  try { const d = JSON.parse(readFileSync(join(root, DIR, `${id}.json`), 'utf8')); return d?.kind === KIND ? d : null; } catch { return null; }
+}
+
+/** The open build's feed (`.studio/progress/current`), or null. */
+export function currentFeedDoc(root) {
+  try {
+    const id = readFileSync(join(root, DIR, 'current'), 'utf8').trim();
+    const doc = read(root, id);
+    return doc?.state === 'running' ? doc : null;
+  } catch { return null; }
+}
+
+/** The newest feed of one game, song or video (`id`), or of anything (`id` null): the open one first. */
+export function latestFeedFor(root, id = null) {
+  const open = currentFeedDoc(root);
+  if (open && (id === null || open.id === id)) return open;
+  let names = [];
+  try { names = readdirSync(join(root, DIR)).filter((n) => n.endsWith('.json')); } catch { return null; }
+  let best = null;
+  for (const name of names) {
+    const doc = read(root, name.slice(0, -5));
+    if (!doc || (id !== null && doc.id !== id)) continue;
+    if (!best || String(doc.updatedAt ?? '') > String(best.updatedAt ?? '')) best = doc;
+  }
+  return best;
+}
+
+const PASSED = new Set(['pass', 'skip']);
+
+/**
+ * One feed as a person reads it. `percent` counts every stage alike: a finished or skipped stage is whole, the
+ * running one is part done (by its checks going green, when it has checks), and a build is 100 only once it passed.
+ */
+export function summarize(doc) {
+  if (!doc || !Array.isArray(doc.stages)) return null;
+  const checks = Array.isArray(doc.checks) ? doc.checks : [];
+  let units = 0;
+  for (const s of doc.stages) {
+    if (s.state === 'done' || s.state === 'skipped') units += 1;
+    else if (s.state === 'running') {
+      const own = checks.filter((c) => c.stage === s.id);
+      units += own.length ? 0.1 + 0.85 * (own.filter((c) => PASSED.has(c.state)).length / own.length) : 0.35;
+    }
+  }
+  const total = Math.max(1, doc.stages.length);
+  const percent = doc.state === 'passed' ? 100 : Math.max(0, Math.min(99, Math.round((units / total) * 100)));
+  const at = doc.stages.find((s) => s.id === doc.stage) ?? doc.stages.find((s) => s.state === 'running') ?? null;
+  const done = doc.stages.filter((s) => s.state === 'done' || s.state === 'skipped').length;
+  const spend = doc.spend ?? { unit: 'usd', used: 0, budget: null };
+  const money = (n) => (spend.unit === 'credits' ? `${n} credits` : `$${Number(n).toFixed(2)}`);
+  return {
+    build: doc.build, what: doc.what, id: doc.id ?? null, title: doc.title ?? doc.id ?? 'Build', studio: doc.studio ?? '',
+    state: doc.state, percent, stagesDone: done, stagesTotal: doc.stages.length,
+    stage: at ? { id: at.id, label: at.label, state: at.state, note: at.note ?? '' } : null,
+    // A build that passed without a stage (a check run that never deployed) skipped it.
+    stages: doc.stages.map((s) => ({ id: s.id, label: s.label, state: doc.state === 'passed' && s.state === 'pending' ? 'skipped' : s.state, note: s.note ?? '', checks: checks.filter((c) => c.stage === s.id) })),
+    checks: {
+      total: checks.length,
+      pass: checks.filter((c) => PASSED.has(c.state)).length,
+      fail: checks.filter((c) => c.state === 'fail').length,
+      running: checks.filter((c) => c.state === 'running').length,
+    },
+    spend: { unit: spend.unit, used: Number(spend.used) || 0, budget: spend.budget ?? null, text: Number(spend.used) || spend.budget !== null ? `${money(Number(spend.used) || 0)}${spend.budget !== null && spend.budget !== undefined ? ` of ${money(spend.budget)}` : ''}` : '' },
+    preview: doc.preview?.url ?? null,
+    previewImage: doc.preview?.image ?? null,
+    previewCaption: doc.preview?.caption ?? '',
+    stopping: Boolean(doc.stop?.requested) && doc.state === 'running',
+    last: Array.isArray(doc.log) && doc.log.length ? doc.log[doc.log.length - 1].text : '',
+    error: doc.error ?? null,
+    startedAt: doc.startedAt ?? null, updatedAt: doc.updatedAt ?? null, endedAt: doc.endedAt ?? null,
+  };
+}

package/lib/progress.mjs

@@ -19,6 +19,10 @@
  * knows (the plan, money spent, a song's lyric check, a video's shots) with the other `progress` commands.
  * WITHOUT AN OPEN FEED NOTHING CHANGES: every command behaves exactly as before.
  *
+ * WHERE A PERSON SEES IT: the Claude app's build card (shared feeds), the Build status tab of the game's codex page
+ * (lib/codex.mjs: it redraws itself at every change), and Claude Code's status line (lib/statusline.mjs), all read
+ * through lib/feed-summary.mjs so they agree.
+ *
  * SHARED (`progress start --share`): the directory named in studio.json (homie.rocks by default) keeps a copy for
  * 24 hours, so the Homie MCP tool `build_progress { build }` can show it in the Claude app, and answers every
  * write with whether the person pressed Stop there. It receives the feed and nothing else: never a key, a file
@@ -51,6 +55,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { extname, join } from 'node:path';
+import { refreshCodexFile } from './codex.mjs';
 import { readStudio, siteUrl } from './studio.mjs';
 
 export const PROGRESS_KIND = 'homie-studio-progress';
@@ -245,6 +250,8 @@ export class Feed {
   change(fn, { soon = false } = {}) {
     const d = mutateDoc(this.root, this.id, fn);
     if (d) schedule(this.root, this.id, { soon });
+    // The game's codex page on this computer (.studio/codex/<id>.html), when there is one, shows the change too.
+    if (d?.what === 'game' && d.id) refreshCodexFile(this.root, d.id);
     return d;
   }
 

package/lib/scaffold.mjs

@@ -192,6 +192,24 @@ studio's pinned copy, never a registry lookup of the bare name.
 - Change a game in small steps, build, and look at it (\`dev\`, then \`check\`).
 - A game's id is its URL (\`/<id>/\`); keep it once published.
 
+## The Game Codex and progress
+
+- **Every game has a Game Codex:** \`games/<id>/CODEX.md\`, its plan in plain words for everyone who makes it, coder
+  or not: concept, world, characters, art direction, controls per device, rooms and players, music and sound,
+  milestones, open questions, and under Latest the decisions as they are made, newest first, each with its date.
+  It is the source of truth: when a decision changes, change the codex in the same change.
+  \`npx --no-install homie-studio codex new <id>\` starts one with every section.
+- \`npx --no-install homie-studio codex <id>\` draws it as a page in the game's own look
+  (\`.studio/codex/<id>.html\`, \`--open\` opens it; \`--artifact\` makes a copy to publish as a Claude artifact).
+  The site has it too, for the owner only and never listed: \`codex link <id>\` gives the one-time sign-in link.
+- **Progress:** \`npx --no-install homie-studio progress start <id> --title "<what this build does>"\` opens a
+  build's progress feed; build, check and deploy report into it. The codex page's Build status tab redraws itself
+  as it moves (stages, checks going green, how to try it, spend), and \`homie-studio statusline --install\` puts
+  one line of it under the prompt in Claude Code.
+- \`npx --no-install homie-studio setup status\` says what this computer and the person's accounts have (Node,
+  Cloudflare, Chrome, ffmpeg, GitHub, ElevenLabs, fal), what each unlocks, and the exact fix. Optional ones never
+  block anything.
+
 ## Rules
 
 - Keys stay in the providers' own logins (Wrangler, ElevenLabs, fal) or the OS
@@ -288,6 +306,8 @@ anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site
 const GITIGNORE = `node_modules/
 # This computer's own state: the site's workers.dev address (it names the Cloudflare account, often after its owner).
 .studio/
+# This person's own Claude Code settings for this studio (the status line, for one).
+.claude/settings.local.json
 site/dist/
 site/.wrangler/
 .wrangler/

package/lib/statusline.mjs

@@ -0,0 +1,155 @@
+/**
+ * THE CLAUDE CODE STATUS LINE: one quiet line under the prompt with the studio's current build, from its progress
+ * feed (lib/progress.mjs), for example
+ *
+ *   ▶ Ember Run · Checks ▰▰▰▰▰▰▱▱▱▱ 62% · 3/5 checks · $0.40 of $2.00
+ *
+ * Optional, and only on the person's yes: `homie-studio statusline --install` writes the `statusLine` setting into
+ * this studio's `.claude/settings.local.json` (this person, this studio; Claude Code keeps that file out of git, and
+ * the studio's .gitignore does too). Claude Code runs the command after each message and, with `refreshInterval`,
+ * every few seconds while a long check runs; it sends the session as JSON on stdin (`workspace.current_dir`), and
+ * shows what the command prints. With no build running it shows only the studio's name, dimmed; a build that ended
+ * stays for a few minutes (passed, failed or stopped), then goes.
+ *
+ * Plugins cannot set a status line (a plugin's settings take only `agent` and `subagentStatusLine`), so this is a
+ * one-line project setting the person agrees to, never something the plugin switches on.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { currentFeedDoc, latestFeedFor, summarize } from './feed-summary.mjs';
+import { PACKAGE_ROOT, findStudio } from './studio.mjs';
+
+const ANSI = { reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', cyan: '\x1b[36m' };
+/** How long an ended build stays on the line. */
+export const RECENT_MS = 10 * 60_000;
+
+function bar(percent, width) {
+  const full = Math.round((percent / 100) * width);
+  return { done: '▰'.repeat(full), left: '▱'.repeat(Math.max(0, width - full)) };
+}
+
+/**
+ * The line for the studio at or above `dir`, or '' outside a studio. Parts are dropped from the end (spend, then
+ * checks) until the line fits in `columns`.
+ */
+export function statusLine({ dir = process.cwd(), now = Date.now(), columns = 100, color = true } = {}) {
+  const root = findStudio(dir);
+  if (!root) return '';
+  let name = 'Studio';
+  try { name = JSON.parse(readFileSync(join(root, 'studio.json'), 'utf8')).name || name; } catch { /* keep */ }
+  const s = summarize(currentFeedDoc(root) ?? latestFeedFor(root, null));
+  const paint = (code, text) => (color && text ? `${code}${text}${ANSI.reset}` : text);
+  const fit = (parts) => {
+    // parts: [[plain, painted], …]; keep the first two whole, then as many as fit.
+    const width = Math.max(20, columns - 2);
+    let keep = parts.length;
+    const len = (n) => parts.slice(0, n).reduce((a, [plain]) => a + plain.length, 0) + (n - 1) * 3;
+    while (keep > 1 && len(keep) > width) keep -= 1;
+    const out = parts.slice(0, keep).map(([, painted]) => painted).join(paint(ANSI.dim, ' · '));
+    const plain = parts.slice(0, keep).map(([p]) => p).join(' · ');
+    return plain.length > width ? `${plain.slice(0, width - 1)}…` : out;
+  };
+  const ended = s && s.state !== 'running' ? Date.parse(s.endedAt ?? s.updatedAt ?? 0) : null;
+  if (!s || (ended !== null && !(now - ended < RECENT_MS))) return fit([[`◇ ${name}`, paint(ANSI.dim, `◇ ${name}`)]]);
+
+  const title = s.title.length > 40 ? `${s.title.slice(0, 39)}…` : s.title;
+  if (s.state === 'passed') {
+    return fit([[`✓ ${title} done`, paint(ANSI.green, `✓ ${title} done`)], ...(s.preview ? [[s.preview, paint(ANSI.dim, s.preview)]] : [])]);
+  }
+  if (s.state === 'failed') {
+    const why = `failed${s.stage ? ` at ${s.stage.label}` : ''}${s.error ? `: ${s.error}` : ''}`;
+    return fit([[`✗ ${title}`, paint(ANSI.red, `✗ ${title}`)], [why, paint(ANSI.red, why)]]);
+  }
+  if (s.state === 'stopped') return fit([[`■ ${title} stopped`, paint(ANSI.yellow, `■ ${title} stopped`)]]);
+
+  const width = columns < 70 ? 6 : 10;
+  const b = bar(s.percent, width);
+  const stage = s.stopping ? 'stopping…' : (s.stage?.label ?? 'Starting');
+  const progress = `${stage} ${b.done}${b.left} ${s.percent}%`;
+  const parts = [
+    [`▶ ${title}`, paint(ANSI.bold, `▶ ${title}`)],
+    [progress, `${paint(ANSI.cyan, stage)} ${paint(ANSI.green, b.done)}${paint(ANSI.dim, b.left)} ${s.percent}%`],
+  ];
+  if (s.checks.total) {
+    const text = `${s.checks.pass}/${s.checks.total} checks${s.checks.fail ? `, ${s.checks.fail} failing` : ''}`;
+    parts.push([text, paint(s.checks.fail ? ANSI.red : ANSI.dim, text)]);
+  }
+  if (s.spend.text) parts.push([s.spend.text, paint(ANSI.dim, s.spend.text)]);
+  return fit(parts);
+}
+
+/* ------------------------------------------------------------------ the setting */
+
+const LOCAL = join('.claude', 'settings.local.json');
+const readJson = (path) => { if (!existsSync(path)) return {}; return JSON.parse(readFileSync(path, 'utf8')); };
+/** Our own status line: a command that runs this toolkit's statusline. */
+export const isOurs = (statusLine) => typeof statusLine?.command === 'string' && /homie-studio|@homie-rocks[\\/]studio/.test(statusLine.command) && /statusline/.test(statusLine.command);
+
+/**
+ * The command the setting runs: this studio's pinned toolkit, by an absolute path (forward slashes, for Windows
+ * too). Set in another folder (the one Claude Code was started in, above the studio), it names the studio too.
+ */
+export function statusLineCommand(root, { named = false } = {}) {
+  const pinned = join(root, 'node_modules', '@homie-rocks', 'studio', 'bin', 'statusline.mjs');
+  const script = existsSync(pinned) ? pinned : join(PACKAGE_ROOT, 'bin', 'statusline.mjs');
+  const slash = (p) => p.replace(/\\/g, '/');
+  return `node "${slash(script)}"${named ? ` --studio "${slash(root)}"` : ''}`;
+}
+
+/** Every settings file that may already hold a status line for this studio, most specific first. */
+function settingsFiles(project, env) {
+  const user = env.CLAUDE_CONFIG_DIR ? join(env.CLAUDE_CONFIG_DIR, 'settings.json') : join(env.HOME || homedir(), '.claude', 'settings.json');
+  return [
+    { where: 'this project, this person (.claude/settings.local.json)', path: join(project, LOCAL) },
+    { where: 'this project (.claude/settings.json)', path: join(project, '.claude', 'settings.json') },
+    { where: 'every project of this person (the user settings)', path: user },
+  ];
+}
+
+/**
+ * `homie-studio statusline --install`: the status line in this studio's .claude/settings.local.json. It never
+ * replaces a status line the person already has (anywhere Claude Code would read one) unless `replace`.
+ * `remove`: take ours out again.
+ */
+export function installStatusLine(root, { replace = false, remove = false, project = null, env = process.env } = {}) {
+  // Claude Code reads project settings from the folder it was started in. A studio made as a subfolder of that
+  // folder is named in the command, and the setting goes where Claude Code reads it (`--project <that folder>`).
+  const here = project ? resolve(project) : root;
+  if (!existsSync(here)) return { ok: false, command: 'statusline install', why: `no folder ${here}` };
+  const files = settingsFiles(here, env);
+  const local = files[0].path;
+  let mine;
+  try { mine = readJson(local); } catch { return { ok: false, command: 'statusline install', why: `${LOCAL} is not valid JSON; fix it by hand first (nothing was changed)` }; }
+  if (remove) {
+    if (!isOurs(mine.statusLine)) return { ok: true, command: 'statusline remove', removed: false, message: 'No Homie status line in this studio; nothing changed.' };
+    delete mine.statusLine;
+    writeFileSync(local, `${JSON.stringify(mine, null, 2)}\n`);
+    return { ok: true, command: 'statusline remove', removed: true, file: LOCAL, message: `Removed the Homie status line from ${LOCAL}.` };
+  }
+  const command = statusLineCommand(root, { named: here !== root });
+  if (isOurs(mine.statusLine) && mine.statusLine.command === command) return { ok: true, command: 'statusline install', already: true, file: LOCAL, statusLine: mine.statusLine, message: 'The status line is already on in this studio.' };
+  if (!replace) {
+    for (const f of files) {
+      let s = null;
+      try { s = readJson(f.path).statusLine ?? null; } catch { s = null; }
+      if (s && !isOurs(s)) {
+        return { ok: false, command: 'statusline install', exists: { where: f.where, command: String(s.command ?? s.type ?? '').slice(0, 120) }, why: `there is already a status line (${f.where}). Nothing was changed. With --replace, this studio shows the build's progress instead (only here; the other one stays everywhere else).` };
+      }
+    }
+  }
+  mine.statusLine = { type: 'command', command, padding: 0, refreshInterval: 5 };
+  mkdirSync(join(here, '.claude'), { recursive: true });
+  writeFileSync(local, `${JSON.stringify(mine, null, 2)}\n`);
+  // Claude Code keeps settings.local.json out of git when it makes the file; this one we made, so say it here too.
+  const ignore = join(here, '.gitignore');
+  let ignored = false;
+  if (existsSync(ignore) || here === root) try {
+    const text = existsSync(ignore) ? readFileSync(ignore, 'utf8') : '';
+    if (!/^\.claude\/settings\.local\.json\s*$/m.test(text)) { writeFileSync(ignore, `${text}${text && !text.endsWith('\n') ? '\n' : ''}# This person's own Claude Code settings for this studio (the status line).\n.claude/settings.local.json\n`); ignored = true; }
+  } catch { /* no .gitignore to keep */ }
+  return {
+    ok: true, command: 'statusline install', file: here === root ? LOCAL : join(here, LOCAL), statusLine: mine.statusLine, gitignore: ignored,
+    message: `The status line is on ${here === root ? `in this studio (${LOCAL})` : `for Claude Code started in ${here} (${LOCAL} there)`}: one line under the prompt with the current build's stage, a progress bar, its checks and what it spent. Claude Code reloads settings by itself; it shows from the next message. Turn it off with: npx --no-install homie-studio statusline --remove`,
+  };
+}

package/lib/template-history.json

@@ -175,6 +175,30 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.11.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "2af7c804c1e81d86",
+     "## The site": "7d3525ba39b7f262",
+     "## Making games": "c204473d9b468f49",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, optional R2 storage for large media, deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",