@homie-rocks/studio 0.10.0 → 0.12.0

package/README.md

@@ -72,8 +72,8 @@ site. A game made with Homie's arcade controls that knocks for a Homie box (`/__
 A studio pins one version, so nothing changes until it asks. To take a newer one:
 
 ```sh
-npx -y @homie-rocks/studio@0.10.0 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.10.0 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.12.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.12.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -94,6 +94,32 @@ Bots, a late joiner taking a bot's body and a new host after the old one leaves
 the same at 32 as at 4. One address may hold every seat plus four sockets, so a party
 on one Wi-Fi (or strangers behind one carrier's address) fills a room with a TV beside it.
 
+## Player accounts and cloud saves
+
+A game whose progress must last (a character that levels up for days, unlocks, a collection, a hardcore mode)
+keeps it in **saves**, not in its room: a room forgets everything 60 s after its last player leaves.
+
+```json
+{ "id": "my-rpg", "saves": true }
+```
+
+```ts
+import { createSaves } from '@homie-rocks/studio/saves';
+const saves = createSaves({ game: 'my-rpg' });
+const hero = (await saves.get('hero')) ?? newHero();
+await saves.set('hero', hero);                       // on this device at once, in the studio's D1 when online
+saves.stats.add({ kills: 1 });                       // lifetime numbers that outlive any hero
+await saves.fall({ character: hero.name, summary: { level: hero.level }, wipe: true });   // hardcore
+```
+
+Pressing Play needs no account. A player who saves something is a guest on that browser; with a **passkey**
+(Face ID, a fingerprint, a PIN, no password, no email) it becomes an account on this studio only, and the same
+saves follow them to every device they sign in on. Saves are per player and game, versioned (a stale offline
+copy is a conflict, never an overwrite), capped in size, and offline-tolerant. Players see, download and delete
+everything at `/account/`; the owner sees counts (`homie-studio players`) and, through the back office, names,
+never a passkey or an email. The `ember-vale` starter is a small persistent-character game on the same public
+rooms. Everything, including what is stored and the back office's API: [saves/SAVES.md](saves/SAVES.md).
+
 ## The studio's own stats
 
 The site counts, and never tracks: pages opened, Play presses, rooms opened, the most
@@ -113,6 +139,60 @@ npx homie-studio stats share on                         # tell the directory "pl
 Each key is minted on the owner's computer; only its SHA-256 goes into D1, through the
 studio's own Cloudflare login. `worker/stats.mjs` says exactly what is counted.
 
+## Setup status
+
+```sh
+npx -y @homie-rocks/studio@0.12.0 setup status --connector yes   # before a studio exists
+npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
+```
+
+One checklist of what this computer and the person's accounts have for a studio: Node.js, the Homie
+connector (the AI says whether its Homie tools are there; the directory is reached), Cloudflare (signed in
+with the studio's own Wrangler, and the account's email verified: a deploy that went through proves it, a
+deploy refused for it is remembered), Chrome for the checks, ffmpeg, and the optional GitHub, ElevenLabs and
+fal (and, in Claude Code, the status line). Each row is green, missing or "do this now", says what it
+unlocks, and gives the exact fix: a command the AI runs or a page the person taps. It only reads, answers in
+seconds, and never prints a key, a token or an account's name. A studio the Claude app's setup card made
+(`setup attach`) counts as connected to Cloudflare and GitHub there. `--json` gives the rows.
+
+## The Game Codex
+
+`games/<id>/CODEX.md` is a game's plan: Markdown with a small frontmatter for its look (palette, fonts, a
+cover, pixel art) and a few conventions that become cards (`### Name` with a picture, `` `M-01` `` id and tag
+chips, an italic subtitle and `**Key:** value` stats), tables, checklists, a dated decision log and open
+questions (`lib/codex.mjs` has the whole format).
+
+```sh
+npx homie-studio codex new crown-thief          # every section, in the studio's colours
+npx homie-studio codex crown-thief --open       # .studio/codex/crown-thief.html, in the browser
+npx homie-studio codex crown-thief --artifact   # one self-contained page to publish as a Claude artifact
+npx homie-studio codex link crown-thief         # a one-time link to the site's private copy
+```
+
+The page has a tab per section and a **Build status** tab from the game's progress feed; the local copy
+redraws itself whenever the feed changes and refreshes in the browser while a build runs. `npm run build`
+puts each game's codex on the site at `/_studio/codex/<id>/`, served only to the studio's owner (the same
+one-time sign-in as the stats page), never listed or indexed. Text is escaped and the page runs only its own
+script (the site allows it by its hash); pictures and fonts come only from inside the studio and are
+embedded, so it loads nothing but Google Fonts. CODEX.md is never in a game's remix source or among a
+static game's served files.
+
+## The Claude Code status line
+
+```sh
+npx homie-studio statusline --install    # .claude/settings.local.json: this person, this studio
+npx homie-studio statusline --install --project ..   # Claude Code started in the folder above the studio
+npx homie-studio statusline --remove
+```
+
+One line under the prompt, from the current build's feed: `▶ Crown Thief · Checks ▰▰▰▰▰▰▱▱▱▱ 62% · 3/5 checks
+· $0.40 of $2.00`; the studio's name, dimmed, when nothing runs; a finished build's result for ten minutes.
+Claude Code runs `bin/statusline.mjs` with the session as JSON on stdin (it reads only the studio's progress
+files, in about 40 ms) and, with the 5 s `refreshInterval` it sets, keeps it moving while a long check runs.
+It never replaces a status line the person already has (`--replace` puts this one in for this studio only).
+Plugins cannot set a status line, so it is always the person's yes. Codex CLI's status line takes only its
+own built-in items, so there the codex page is the progress view.
+
 ## A build the person can watch (the progress feed)
 
 A build of a game, song or video can keep a small progress feed, so the person follows it
@@ -151,9 +231,10 @@ Workers Builds deploys the branch as a Preview; the card's **Publish** opens the
 person's merge is the approval; Workers Builds deploys `main`, and the card says **Live** when the live site's
 manifest lists the change's mark (`homie-studio build` lists the newest marks from `changes/`).
 
-A Claude Code cloud session's default network ("Trusted") does not reach homie.rocks; the toolkit says so, and
-names the setting (the environment's Network access: Custom, add homie.rocks), instead of "did not answer". The
-build goes on with its local feed.
+A Claude Code cloud session's default network ("Trusted") reaches homie.rocks. If a session's network blocks it
+(its proxy answers 403 `host_not_allowed`, and the progress card stops updating), the toolkit says so and names the
+setting (the environment's Network access: Custom, add homie.rocks), instead of "did not answer". The build goes on
+with its local feed.
 
 The feed is `.studio/progress/<build>.json` (git-ignored). With `--share` the studio's
 directory (studio.json `homie.directory`, homie.rocks by default) keeps a copy for 24

package/bin/homie-studio.mjs

@@ -37,6 +37,8 @@
  *   homie-studio stats link               (a one-time link to the private stats page, for the owner's browser)
  *   homie-studio stats revoke             (every stats key and page session ends)
  *   homie-studio stats share on|off       (tell the homie.rocks directory "played this week", or stop)
+ *   homie-studio players                  (player accounts and guests with saves: counts, never a passkey or an email)
+ *   homie-studio players owner [--revoke] (a one-time link that marks the owner's own player account as the owner's)
  *
  *   homie-studio progress start [<id>] [--what game|song|video] [--title "<what this build does>"]
  *                                        [--budget <dollars>] [--unit usd|credits] [--share]
@@ -62,6 +64,24 @@
  *
  *   homie-studio setup attach <hs_…>      (this repository is the studio the Claude app's setup card is making: say so, once,
  *                                          learn its live address, and give a template copy its real name)
+ *   homie-studio setup status [--connector yes|no]   (also: homie-studio doctor)
+ *                                         what this computer and the person's accounts have for a studio: Node, the Homie
+ *                                         connector, Cloudflare (signed in, email verified), Chrome, ffmpeg, GitHub,
+ *                                         ElevenLabs, fal; green, missing or "do this now", what each unlocks and its
+ *                                         exact fix. Read-only and safe any time, inside a studio or before one exists.
+ *
+ *   homie-studio codex new <id>           games/<id>/CODEX.md: the Game Codex, every section, in the game's colours
+ *   homie-studio codex <id> [--artifact] [--open]
+ *                                         the codex as a page in the game's own look (.studio/codex/<id>.html; it redraws
+ *                                         itself as the build's progress changes); --artifact: a copy to publish as a
+ *                                         Claude artifact; --open: open it in this computer's browser
+ *   homie-studio codex link <id>          a one-time link to the codex on the live site (a private page for the owner)
+ *
+ *   homie-studio statusline               the current build in one line (what Claude Code's status line shows)
+ *   homie-studio statusline --install [--project <folder>]
+ *                                         turn it on in Claude Code for this studio (.claude/settings.local.json);
+ *                                         --project: the folder Claude Code was started in, when that is above the
+ *                                         studio; --remove turns it off; --replace when another status line is set
  *
  * Every command prints a few lines for a person; --json prints the result.
  */
@@ -78,16 +98,20 @@ import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
 import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
-import { ensureStatsMigration, newStudio } from '../lib/scaffold.mjs';
+import { ensureMigrations, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
+import { playersOwner, playersShow } from '../lib/players.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
+import { formatStatus, setupStatus } from '../lib/doctor.mjs';
+import { codexTarget, newCodex, writeCodexPage } from '../lib/codex.mjs';
+import { installStatusLine, statusLine } from '../lib/statusline.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh'];
+const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -128,6 +152,7 @@ function print(result) {
       for (const m of result.mediaSkipped ?? []) lines.push(`  left out: ${m.kind}/${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
       for (const m of result.postsSkipped ?? []) lines.push(`  left out: posts/${m.post}: ${m.why}`);
       for (const m of result.siteSkipped ?? []) lines.push(`  left out: ${m.what}: ${m.why}`);
+      if (result.codexes?.length) lines.push(`Game Codex (the owner's private pages; codex link <id> opens one): ${result.codexes.map((x) => `/_studio/codex/${x}/`).join(', ')}`);
       break;
     case 'media list':
       for (const kind of ['music', 'videos']) {
@@ -185,8 +210,17 @@ function print(result) {
       for (const e of result.songs) lines.push(`  song ${e.slug}: ${n(e.visits)} page visits, played ${n(e.plays)}`);
       for (const e of result.videos) lines.push(`  video ${e.slug}: ${n(e.visits)} page visits, watched ${n(e.views)}`);
       for (const r of result.referrers.slice(0, 10)) lines.push(`  from ${r.from} (${r.kind}): ${n(r.visits)} visits, ${n(r.plays)} plays`);
+      if (result.players) lines.push(`  players: ${n(result.players.accounts)} accounts (${n(result.players.newAccounts7d)} new this week), ${n(result.players.guests)} guests with saves, ${n(result.players.active7d)} played this week`);
       break;
     }
+    case 'players': {
+      const p = result.players;
+      lines.push(`${p.accounts} player accounts (${p.newAccounts7d} new this week), ${p.guests} guests with saves, ${p.active7d} played this week.`, result.note);
+      break;
+    }
+    case 'players owner':
+      lines.push(result.revoked ? result.message : `One-time link (until ${result.expiresAt}): ${result.link}`, ...(result.revoked ? [] : [result.use]));
+      break;
     case 'stats key':
       lines.push(`Read key (until ${result.expiresAt}): ${result.key}`, result.use);
       break;
@@ -197,6 +231,27 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    case 'setup status':
+      lines.push(formatStatus(result));
+      break;
+    case 'codex':
+      lines.push(`The Game Codex for ${result.title}: ${result.file}${result.opened ? ' (opened in the browser)' : ''}`,
+        `  tabs: ${result.sections.map((x) => x.title).join(' · ')} · Build status${result.build ? ` (${result.build.state}, ${result.build.percent}%)` : ''}`,
+        ...(result.missing.length ? [`  not decided yet: ${result.missing.join(', ')}`] : ['  every section has something in it']),
+        `  open questions: ${result.openQuestions}`,
+        ...result.warnings.map((w) => `  warning: ${w}`),
+        result.mode === 'artifact' ? '  publish this file as an artifact where your app can (Claude: the Artifact tool); it is one self-contained page' : '  on the site, for the owner only, after the next deploy: npx --no-install homie-studio codex link ' + result.id);
+      break;
+    case 'codex new':
+      lines.push(`Wrote ${result.file}.`, ...result.next.map((n) => `  next: ${n}`));
+      break;
+    case 'codex link':
+      lines.push(`One-time link (until ${result.expiresAt}): ${result.link}`, result.use);
+      break;
+    case 'statusline install':
+    case 'statusline remove':
+      lines.push(result.message);
+      break;
     case 'setup attach':
       lines.push(result.message, ...(result.site ? [`  live site: ${result.site}`] : []), ...(result.renamed?.length ? ['  changed (commit these on a branch):', ...result.renamed.map((f) => `    ${f}`)] : []), ...(result.next ?? []).map((n) => `  next: ${n}`));
       break;
@@ -282,7 +337,16 @@ async function main() {
   if (cmd === 'port' && sub === 'plan') return planPort(positional[2] ?? '.');
   if (cmd === 'chrome' && sub === 'install') return installChrome({ log, fresh: flags.has('fresh') });
   if (cmd === 'chrome') { const chrome = findChrome(); return chrome ? { ok: true, command: 'chrome', chrome, args: chromeArgs() } : { ok: false, command: 'chrome', why: noChrome() }; }
+  if ((cmd === 'setup' && sub === 'status') || cmd === 'doctor') return setupStatus({ connector: flags.get('connector') ?? null, homie: flags.get('homie') ?? null });
+  if (cmd === 'statusline' && !flags.has('install') && !flags.has('remove')) {
+    const line = statusLine({ columns: Number(process.env.COLUMNS) || 100, color: !process.env.NO_COLOR && !asJson && process.stdout.isTTY });
+    if (asJson) return { ok: true, command: 'statusline', line };
+    if (line) process.stdout.write(`${line}\n`);
+    return { ok: true, command: 'help' };
+  }
   const root = requireStudio();
+  if (cmd === 'statusline') return installStatusLine(root, { remove: flags.has('remove'), replace: flags.has('replace'), project: flags.get('project') ?? null });
+  if (cmd === 'codex') return codexCommand(root, sub);
   if (cmd === 'progress') return progressCommand(root, sub);
   if (cmd === 'setup' && sub === 'attach') return setupAttach(root, positional[2], { homie: flags.get('homie') });
   if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
@@ -336,6 +400,8 @@ async function main() {
     return { ok: true, command: 'storage', storage: has ? { kind: 'r2', bucket: cf.r2 } : null, why: has ? undefined : 'no storage yet: the studio runs without it; `homie-studio storage add` adds an R2 bucket for large media (Cloudflare asks for a payment method before R2 works)' };
   }
   if (cmd === 'publish') return publish(root, { homie: flags.get('homie'), site: flags.get('site') });
+  if (cmd === 'players' && sub === 'owner') return playersOwner(root, { url: flags.get('url'), revoke: flags.has('revoke') });
+  if (cmd === 'players' && !sub) return playersShow(root, { url: flags.get('url') });
   if (cmd === 'stats' && sub === 'key') return statsKey(root, { url: flags.get('url'), hours: flags.get('hours') });
   if (cmd === 'stats' && sub === 'link') return statsLink(root, { url: flags.get('url') });
   if (cmd === 'stats' && sub === 'revoke') return statsRevoke(root, { url: flags.get('url') });
@@ -351,6 +417,28 @@ async function main() {
   return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
 }
 
+/** `homie-studio codex …` (lib/codex.mjs): the Game Codex of one game. */
+function codexCommand(root, sub) {
+  const games = listGames(root);
+  if (sub === 'new') return newCodex(root, positional[2] ?? (games.length === 1 ? games[0].id : undefined));
+  if (sub === 'link') {
+    const id = positional[2] ?? (games.length === 1 ? games[0].id : null);
+    if (!id || !games.some((g) => g.id === id)) return { ok: false, command: 'codex link', why: 'name the game: homie-studio codex link <id>' };
+    const r = statsLink(root, { url: flags.get('url') });
+    if (!r.ok) return { ...r, command: 'codex link' };
+    return { ...r, command: 'codex link', link: `${r.link}&to=${encodeURIComponent(codexTarget(id))}`, use: 'Give this link to the studio\'s owner to open in their own browser: it works once, within 30 minutes, opens the codex, and keeps that browser signed in to the studio\'s private pages (the codex and the stats) for 30 days. Do not post it anywhere.' };
+  }
+  const id = sub ?? (games.length === 1 ? games[0].id : null);
+  if (!id) return { ok: false, command: 'codex', why: `name the game: homie-studio codex <id> (${games.map((g) => g.id).join(', ') || 'no games yet'})` };
+  let r;
+  try { r = writeCodexPage(root, id, { mode: flags.has('artifact') ? 'artifact' : 'file' }); } catch (error) { return { ok: false, command: 'codex', why: error.message }; }
+  if (flags.has('open')) {
+    const opener = process.platform === 'darwin' ? ['open', [r.path]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', r.path]] : ['xdg-open', [r.path]];
+    r.opened = spawnSync(opener[0], opener[1], { stdio: 'ignore', timeout: 10_000 }).status === 0;
+  }
+  return r;
+}
+
 /*
  * THE PROGRESS FEED (lib/progress.mjs). A command that is a stage of the open build (build, check, port check,
  * deploy) says so: the stage runs, then is done or failed with one line; a check's steps go green as they pass; a
@@ -488,8 +576,7 @@ async function dev(root) {
   if (!bin) return { ok: false, command: 'dev', why: 'run npm install in the studio first' };
   const studio = readStudio(root);
   const env = { ...process.env, WRANGLER_SEND_METRICS: 'false', CI: '1' };
-  const added = ensureStatsMigration(root);
-  if (added) log(`added ${added} (the studio's own stats)`);
+  for (const added of ensureMigrations(root)) log(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own stats'})`);
   await new Promise((done) => {
     const m = spawn(bin, ['d1', 'migrations', 'apply', 'DB', '--local'], { cwd: workerDir(root), env, stdio: ['ignore', 'ignore', 'inherit'] });
     m.on('close', done);

package/bin/statusline.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * The Claude Code status line for a Homie studio (lib/statusline.mjs). Claude Code runs it with the session as
+ * JSON on stdin and shows what it prints; it must be quick and must never fail loudly, so it reads only the
+ * studio's own progress files and prints nothing at all when anything goes wrong.
+ *
+ *   echo '{"workspace":{"current_dir":"."}}' | node node_modules/@homie-rocks/studio/bin/statusline.mjs
+ */
+import { statusLine } from '../lib/statusline.mjs';
+
+let input = '';
+let printed = false;
+function print() {
+  if (printed) return;
+  printed = true;
+  let dirs = [process.cwd()];
+  try {
+    const session = JSON.parse(input || '{}');
+    dirs = [session?.workspace?.current_dir, session?.workspace?.project_dir, session?.cwd, process.cwd()].filter((d) => typeof d === 'string' && d);
+  } catch { /* no session: this folder */ }
+  // `--studio <folder>`: set up in the folder above the studio, the setting names the studio.
+  const named = process.argv.indexOf('--studio');
+  if (named > 0 && process.argv[named + 1]) dirs.push(process.argv[named + 1]);
+  try {
+    const columns = Number(process.env.COLUMNS) || 100;
+    const color = !process.env.NO_COLOR;
+    for (const dir of dirs) {
+      const line = statusLine({ dir, columns, color });
+      if (line) { process.stdout.write(`${line}\n`); break; }
+    }
+  } catch { /* quiet: a status line never shows a stack */ }
+  // A caller that never closes stdin must not keep this process alive.
+  if (!process.stdin.isTTY) process.stdin.destroy();
+}
+if (process.stdin.isTTY) print();
+else {
+  const timer = setTimeout(print, 400);
+  process.stdin.on('data', (d) => { input += d; });
+  process.stdin.on('end', () => { clearTimeout(timer); print(); });
+  process.stdin.on('error', () => { clearTimeout(timer); print(); });
+}

package/lib/build.mjs

@@ -10,6 +10,8 @@
  *                                          posts/*.md and the studio's site/ folder (site/SITE.md)
  *   site/dist/games/<id>/_landing/...      what the game's landing shows (hero footage, its cover, licence texts)
  *   site/dist/_site/                       posts.json (the posts' HTML), the studio's own pages (site/pages)
+ *   site/dist/_studio/codex/<id>/          each game's Game Codex (games/<id>/CODEX.md, lib/codex.mjs): served only to
+ *                                          the studio's owner (worker/stats-page.mjs), never listed or indexed
  *   site/dist/<file>                       site/public, as it is (fonts, a logo, hero footage)
  *   site/dist/music/..., site/dist/videos/...   media files the site serves itself (R2 keys are served from R2)
  *
@@ -25,6 +27,7 @@ import { spawnSync } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
+import { buildCodexPages } from './codex.mjs';
 import { buildMedia } from './media.mjs';
 import { buildSiteFiles, landingOf, readPosts, readTheme } from './site.mjs';
 import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
@@ -33,7 +36,7 @@ import { STUDIO_VERSION } from './version.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
-const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md']);
+const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md']);
 const LOADERS = { '.png': 'file', '.jpg': 'file', '.jpeg': 'file', '.gif': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.m4a': 'file', '.glb': 'file', '.gltf': 'file', '.bin': 'file', '.hdr': 'file', '.svg': 'file', '.json': 'json', '.woff2': 'file', '.ttf': 'file' };
 
 /** The port toolkit as one classic script (window.HomiePort), for static games. Built once per build. */
@@ -67,7 +70,7 @@ export function sourceOf(dir, id) {
   let total = 0;
   const walk = (rel) => {
     for (const entry of readdirSync(join(dir, rel), { withFileTypes: true })) {
-      if (entry.name.startsWith('.') || SOURCE_SKIP.has(entry.name)) continue;
+      if (entry.name.startsWith('.') || SOURCE_SKIP.has(entry.name) || (!rel && entry.name === 'CODEX.md')) continue;
       const path = rel ? `${rel}/${entry.name}` : entry.name;
       if (entry.isDirectory()) walk(path);
       else if (TEXT.test(entry.name)) {
@@ -217,11 +220,16 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
       roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
       ...(g.screen ? { screen: g.screen } : {}),
+      // game.json "saves": true — player accounts and cloud saves (saves/SAVES.md): the play shell answers the game's
+      // saves calls, and the site's nav and the game's landing offer a player account.
+      ...(g.saves === true || (g.saves && typeof g.saves === 'object') ? { saves: true } : {}),
       landing: landingOf(g, join(dist, 'games', g.id), { videos: media.videos, songs: media.songs, log }),
     };
   });
   const { posts, skipped: postsSkipped } = readPosts(root, { games: rows, songs: media.songs, videos: media.videos, log });
   const site = buildSiteFiles(root, dist, { gameIds: rows.map((g) => g.id), log });
+  // Each game's Game Codex (games/<id>/CODEX.md), as the owner's private page at /_studio/codex/<id>/ (never listed).
+  const codexes = buildCodexPages(root, dist, games.map((g) => g.id), { log });
   mkdirSync(join(dist, '_site'), { recursive: true });
   writeFileSync(join(dist, '_site', 'posts.json'), `${JSON.stringify({ v: 1, posts })}\n`);
   const s = studio.site && typeof studio.site === 'object' ? studio.site : {};
@@ -257,7 +265,7 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   return {
     ok: true, command: 'build', dist, games: built, catalogue: catalogue.games.map((g) => g.id),
     songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped,
-    posts: posts.map((p) => p.slug), postsSkipped, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
+    posts: posts.map((p) => p.slug), postsSkipped, codexes, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
     landings: rows.map((g) => ({ id: g.id, hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length), source: g.landing.source })),
   };
 }

package/lib/cloudflare.mjs

@@ -22,7 +22,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.mjs';
-import { ensureLocalIgnored, ensureStatsMigration, wranglerConfig } from './scaffold.mjs';
+import { ensureLocalIgnored, ensureMigrations, wranglerConfig } from './scaffold.mjs';
 import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -96,7 +96,7 @@ export function deployPlan(root) {
     ok: true, command: 'deploy plan', studio: studio.name, account: cf.accountId ?? null,
     cloudflare: [
       { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`), plan: 'Workers Free' },
-      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, and the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor)', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
+      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor), and, for games that keep saves, player accounts (a passkey\'s public key, never a password) and their saves', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
       { kind: 'Durable Object', name: 'Table', what: 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
       storage
@@ -129,7 +129,12 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
     return { ok: false, command: 'deploy', needs: 'cloudflare-account', why: `This Cloudflare login can reach ${who.accounts.length} accounts; ask the person which one this studio uses and put its id in studio.json (cloudflare.accountId).`, accounts: who.accounts };
   }
   const w = runner(root, { CLOUDFLARE_ACCOUNT_ID: accountId });
-  const refuse = (why, out) => ({ ok: false, command: 'deploy', ...(explainCloudflare(out, accountId) ?? { why }) });
+  const refuse = (why, out) => {
+    const r = { ok: false, command: 'deploy', ...(explainCloudflare(out, accountId) ?? { why }) };
+    // What the account asked for (an email to verify…) stays on this computer, for `setup status`.
+    if (r.needs) { try { writeLocal(root, { needs: r.needs, needsAt: new Date().toISOString() }); } catch { /* not recorded */ } }
+    return r;
+  };
   // Record every resource the moment it exists, so a deploy cut short (an expired login, a network drop) resumes
   // instead of refusing its own database as "someone else's" next time.
   const remember = (key) => {
@@ -187,8 +192,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
   writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root) }));
-  const added = ensureStatsMigration(root);
-  if (added) step(`added ${added} (the studio's own stats: counts, never tracks)`);
+  for (const added of ensureMigrations(root)) step(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own stats: counts, never tracks'})`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
   if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   step('D1 migrations applied');
@@ -201,7 +205,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   // .studio/local.json (git-ignored), and never in the committed studio.json. A custom domain stays in studio.json.
   if (ensureLocalIgnored(root)) step(`added .studio/ to .gitignore (${LOCAL_STATE} keeps this computer's own state)`);
   const workersDev = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? readLocal(root).url ?? (isWorkersDev(cf.url) ? cf.url : null);
-  if (workersDev) writeLocal(root, { url: workersDev, deployedAt: new Date().toISOString() });
+  if (workersDev) writeLocal(root, { url: workersDev, deployedAt: new Date().toISOString(), needs: null, needsAt: null });
   const movedOut = isWorkersDev(cf.url);
   if (movedOut) {
     cf.url = null;
@@ -278,7 +282,7 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   const step = (what) => { steps.push({ what }); log(what); };
   const refuse = (why, out) => ({ ok: false, command: 'deploy', ci: true, ...(explainCloudflare(out) ?? { why }), steps });
   if (!existsSync(join(root, 'site', 'dist', 'games.json'))) return { ok: false, command: 'deploy', ci: true, why: 'nothing is built: the build command is `npm run build` (homie-studio build), and it runs before this', steps };
-  if (ensureStatsMigration(root)) step('added the stats migration (the studio\'s own counters)');
+  for (const added of ensureMigrations(root)) step(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own counters'})`);
   const apply = () => w(['d1', 'migrations', 'apply', names.binding, '--remote']);
   let migrate = apply();
   const first = migrate.code !== 0 && /not found|could(?:n't| not) find|does not exist|no database|database_id/i.test(migrate.out);