@homie-rocks/studio 0.10.0 → 0.12.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/players.mjs

@@ -0,0 +1,38 @@
+/**
+ * `homie-studio players` — the studio's players, for its owner (worker/players.mjs, saves/SAVES.md).
+ *
+ *   homie-studio players [--url <site>]          how many have accounts, guests with saves, who played this week
+ *   homie-studio players owner [--url <site>]    a one-time link that marks the owner's OWN player account as the
+ *                                                owner's (open it in the browser where they are signed in on the site)
+ *   homie-studio players owner --revoke          no account is the owner's any more
+ *
+ * The proof of ownership is the studio's own Cloudflare login, as for `stats`: the link's key is minted here and
+ * only its SHA-256 goes into the studio's D1 (through Wrangler). The link works once, for 30 minutes.
+ */
+import { runner } from './cloudflare.mjs';
+import { loopback, mint, siteOf, statsShow } from './stats.mjs';
+
+export async function playersShow(root, { url } = {}) {
+  const s = await statsShow(root, { url, range: '7d' });
+  if (!s.ok) return { ...s, command: 'players' };
+  if (!s.players) return { ok: false, command: 'players', why: 'this studio\'s D1 has no player tables yet: `npm run deploy` applies migration 0004_players.sql (or `npm run dev` for a local site)' };
+  return { ok: true, command: 'players', site: s.site, players: s.players, note: 'Counts only. A player\'s name, passkeys and saves are theirs; the back office lists names, never a passkey or an email.' };
+}
+
+export function playersOwner(root, { url, revoke = false } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'players owner', why: 'this studio has no live site yet: `npm run deploy` first, or give --url http://127.0.0.1:8787 for `npm run dev`' };
+  const local = loopback(site);
+  if (revoke) {
+    const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+    const res = w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', "UPDATE players SET owner = 0; DELETE FROM stats_keys WHERE kind = 'player-owner';"]);
+    return res.code === 0 ? { ok: true, command: 'players owner', site, revoked: true, message: 'No player account is the owner\'s now. `homie-studio players owner` marks one again.' }
+      : { ok: false, command: 'players owner', why: res.out.trim().split('\n').slice(-3).join(' ') };
+  }
+  const k = mint(root, studio, 'player-owner', 30 * 60_000, { local });
+  if (!k.ok) return { ok: false, command: 'players owner', why: k.why };
+  return {
+    ok: true, command: 'players owner', site, link: `${site}/account/?owner=${k.key}`, expiresAt: k.expiresAt,
+    use: 'Give this link to the studio\'s owner to open in the browser where they play: they sign in (or make an account with a passkey) on that page, then press "Yes, this account is mine". It works once, within 30 minutes. It is theirs alone; do not post it anywhere.',
+  };
+}

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';
@@ -85,9 +90,10 @@ const currentPath = (root) => join(dir(root), 'current');
 const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
 
 /*
- * A CLAUDE CODE CLOUD SESSION ON THE DEFAULT NETWORK. Its "Trusted" network reaches package registries and GitHub,
- * not homie.rocks: the session's proxy answers 403 with `x-deny-reason: host_not_allowed`. Say which setting lets
- * the card follow the build, instead of "did not answer"; the build itself goes on with its local feed.
+ * A CLAUDE CODE CLOUD SESSION WHOSE NETWORK BLOCKS THE DIRECTORY. The default "Trusted" network reached homie.rocks
+ * in a real cloud session (2026-10-01); a stricter one makes the session's proxy answer 403 with
+ * `x-deny-reason: host_not_allowed`. Then, and only then, say which setting lets the card follow the build,
+ * instead of "did not answer"; the build itself goes on with its local feed.
  */
 export function networkWhy(res, at) {
   if (res?.status === 403 && /host_not_allowed/i.test(res.headers?.get?.('x-deny-reason') ?? '')) {
@@ -245,6 +251,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

@@ -24,6 +24,7 @@ import { homedir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
 import { STUDIO_VERSION, packageSpec } from './version.mjs';
 import { STATS_MIGRATION, STATS_MIGRATION_FILE } from '../worker/stats.mjs';
+import { PLAYERS_MIGRATION, PLAYERS_MIGRATION_FILE } from '../worker/players.mjs';
 import { themeFile } from './site.mjs';
 import { PACKAGE_ROOT } from './studio.mjs';
 
@@ -149,6 +150,10 @@ studio's pinned copy, never a registry lookup of the bare name.
   \`studio_stats\` (never paste a key anywhere else). \`stats share on\` tells the directory two numbers
   (played this week). The site counts and never tracks: no cookie on a visitor, no person identified,
   nothing sent anywhere; house QA and \`check\` runs are not counted.
+- \`npx --no-install homie-studio players\` — how many players have accounts here (and guests, and who played
+  this week): counts and names for the owner, never a passkey or an email. \`players owner\` gives the owner a
+  one-time link that marks their own player account (a passkey on this site) as the owner's, so their games and
+  the studio's back office recognise them.
 - \`npx --no-install homie-studio upgrade\` — after pinning a newer \`@homie-rocks/studio\` (or through
   \`npx -y --package=<its tarball> homie-studio upgrade\`): what the newer template adds to this studio (AGENTS.md
   sections, READMEs, .gitignore lines) and what it keeps. It changes nothing until \`--apply\`, and never
@@ -191,6 +196,31 @@ studio's pinned copy, never a registry lookup of the bare name.
   a small icon (\`node_modules/@homie-rocks/studio/site/SITE.md\`). Look at it on a phone and a computer.
 - 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.
+- **Progress that lasts** (a character, unlocks, a collection, days of play) goes in **saves**, never in the room:
+  a room forgets everything 60 s after its last player leaves. game.json \`"saves": true\` and
+  \`createSaves\` from \`@homie-rocks/studio/saves\` (\`node_modules/@homie-rocks/studio/saves/SAVES.md\`): per
+  player and game, versioned, offline-tolerant, in this studio's own D1. Pressing Play needs no account; a guest's
+  progress stays on that device until they make a passkey account (at \`/account/\`, or the game's own button), and
+  then it follows them to every device. Lifetime stats and a hardcore "hall of the fallen" are in it too. The
+  \`ember-vale\` starter shows the whole pattern.
+
+## 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
 
@@ -288,6 +318,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/
@@ -339,7 +371,7 @@ export function studioFiles({ name, slug, homie, template = false }) {
       products: ['Workers', 'D1', 'Durable Objects'],
       bindings: {
         STUDIO_NAME: { description: 'Your studio\'s name, as its site shows it (for example **Night Owls**). Claude can change it later.' },
-        DB: { description: 'The studio\'s own database: finished rounds, the studio\'s own stats (counts, never a visitor) and its claim in the [homie.rocks](https://homie.rocks/studios/) directory. Free plan.' },
+        DB: { description: 'The studio\'s own database: finished rounds, the studio\'s own stats (counts, never a visitor), player accounts and cloud saves for games that keep them, and its claim in the [homie.rocks](https://homie.rocks/studios/) directory. Free plan.' },
       },
     },
   };
@@ -364,6 +396,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
 `,
     'site/migrations/0001_studio.sql': MIGRATION,
     [`site/migrations/${STATS_MIGRATION_FILE}`]: STATS_MIGRATION,
+    [`site/migrations/${PLAYERS_MIGRATION_FILE}`]: PLAYERS_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
   };
@@ -433,6 +466,23 @@ export function ensureStatsMigration(root) {
   return `site/migrations/${STATS_MIGRATION_FILE}`;
 }
 
+/**
+ * A studio made before 0.12.0 has no players migration (player accounts and cloud saves, saves/SAVES.md): add it,
+ * so the next `d1 migrations apply` makes the tables. Returns the file it wrote, or null when it was there.
+ */
+export function ensurePlayersMigration(root) {
+  const file = join(root, 'site', 'migrations', PLAYERS_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, PLAYERS_MIGRATION);
+  return `site/migrations/${PLAYERS_MIGRATION_FILE}`;
+}
+
+/** Every migration the template owns that this studio lacks, added: the files written (deploy and dev say so). */
+export function ensureMigrations(root) {
+  return [ensureStatsMigration(root), ensurePlayersMigration(root)].filter(Boolean);
+}
+
 /**
  * A studio made before 0.6.0 committed nothing under .studio/ yet: make sure git leaves it out before the first
  * deploy writes the workers.dev address there. Returns true when it added the line.

package/lib/site.mjs

@@ -214,9 +214,9 @@ export function readPosts(root, { games = [], songs = [], videos = [], log = ()
 
 export const PARTIALS = ['head', 'header', 'footer', 'home', 'game', 'post'];
 /** Paths a page of the studio's own can never take: the rooms, the game files, the API and the owner's pages. */
-const RESERVED_PAGE = /^\/(?:api|_studio|_homie|_site|media|\.well-known|games\/[^/]+)\/|^\/[a-z0-9][a-z0-9-]{0,39}\/(?:play|tv|live|api|__[a-z]+)(?:\/|$)/;
+const RESERVED_PAGE = /^\/(?:api|account|_studio|_homie|_site|media|\.well-known|games\/[^/]+)\/|^\/[a-z0-9][a-z0-9-]{0,39}\/(?:play|tv|live|api|__[a-z]+)(?:\/|$)/;
 /** Top-level names site/public must not take (the build's own output). */
-const RESERVED_PUBLIC = new Set(['games', 'music', 'videos', 'games.json', '_site', '_homie', '_studio', 'api', 'media']);
+const RESERVED_PUBLIC = new Set(['games', 'music', 'videos', 'games.json', '_site', '_homie', '_studio', 'api', 'media', 'account']);
 
 function walk(dir, fn, rel = '') {
   for (const e of readdirSync(join(dir, rel), { withFileTypes: true })) {

package/lib/stats.mjs

@@ -21,9 +21,9 @@ const HOUR = 3600_000;
 const RANGES = new Set(['1d', '7d', '30d', '90d']);
 const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
 
-const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
+export const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
 
-function siteOf(root, url) {
+export function siteOf(root, url) {
   const studio = readStudio(root);
   const site = String(url || siteUrl(root, studio) || '').replace(/\/+$/, '');
   if (!/^https?:\/\//.test(site)) return { studio, site: null };
@@ -31,7 +31,7 @@ function siteOf(root, url) {
 }
 
 /** Put a key's hash into the studio's D1 (remote, or local for a loopback site). The key never leaves this machine. */
-function mint(root, studio, kind, ttlMs, { local }) {
+export function mint(root, studio, kind, ttlMs, { local }) {
   const key = `hsk_${randomBytes(24).toString('hex')}`;
   const hash = createHash('sha256').update(key).digest('hex');
   const now = Date.now();