@homie-rocks/studio 0.12.1 → 0.14.0

package/README.md

@@ -19,9 +19,36 @@ npx homie-studio deploy --plan                         # what deploy will create
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
 npx homie-studio stats                                 # the studio's own numbers, for its owner
+npx homie-studio office                                 # who is playing now, in every live room (the back office)
 npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
+A new studio has no game: its home page says "First game coming soon" until the first one is made, and
+`homie-studio demo` names a live game on Homie Arcade to try meanwhile. A starter is copied in only when the person
+asks (`game new <id> --from gem-rush`, or `--from ember-vale` for a hero who lasts, with cloud saves).
+
+## In one chat: `homie-studio mcp`
+
+```sh
+npx -y @homie-rocks/studio mcp --studios "<the folder the studios live in>"   # the toolkit as a local MCP server (stdio)
+```
+
+The toolkit as MCP tools, so the chat that shows Homie's cards also does the work: the setup status, a new studio,
+the live demo, make / remix / port / plan a game and its Game Codex, build, run it here, the two-browser check, a
+playtest, deploy, publish, the progress feed, the studio's files, and the music, sound, art and video scripts where
+their provider is set up. Where a tool overlaps the remote Homie MCP (homie.rocks/mcp) it has the same name and
+input shape. Long work (npm install, a check, a deploy) runs in the background and reports through the progress
+feed; MCP Apps cards (setup, build progress, studio, codex) are served as `ui://homie-studio/*`, and every tool also
+answers in plain text. Homie for Claude Desktop (`desktop/` in this repository) is this server as a Desktop
+Extension: the plain Claude app gets it with one install, and no terminal.
+
+## From a phone: a one-line hand-off
+
+The Claude app on a phone hands a build to a Claude Code cloud session with one line, `Continue building <Studio>:
+build hb_…`. In the session, `homie-studio handoff hb_…` fetches the brief from the directory by the build id, checks
+in for a studio still being set up, takes the build so the chat's card follows it, and prints the steps (every
+studio's `HANDOFF.md` says so).
+
 ## From GitHub, with Cloudflare's own CI (Workers Builds, Previews, Deploy to Cloudflare)
 
 A studio keeps `wrangler.jsonc` at its root (a studio made before 0.10.0 keeps `site/wrangler.jsonc`, and every
@@ -38,7 +65,8 @@ computer involved:
 
 The button copies the public template (`template/` in this repository, exactly what `homie-studio new --template`
 writes) into the person's GitHub, makes the Worker, the D1 database and the rooms on their Cloudflare account,
-and connects Workers Builds. The site plays its first game (Gem Rush) the moment it is up, and its Home has a
+and connects Workers Builds. The site goes live with its own home page ("First game coming soon": no starter game
+is put in a studio unless the person asks for one), and its Home has a
 **Connect to Claude** band: one tap links it to the Claude chat that set it up (the Homie MCP tool `studio_setup`).
 In the Claude Code session that works in the repository, `homie-studio setup attach <hs_…>` then gives the studio
 the name chosen in the chat and removes the band.
@@ -72,8 +100,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.12.1 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.12.1 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.14.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.14.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -139,10 +167,70 @@ 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.
 
+## The back office: run your live games
+
+The owner sees and runs the studio's live games from `/_studio/office`, a private page
+that refreshes itself: every live room of every game (players, bots, the round, how long
+it has been up) and who is in it (each seat's handle, its device, whether it hosts, the
+browser it came from; signed-in players once a studio has player accounts). From there,
+and from a small Owner button in the owner's own play page (nobody else's page carries
+it):
+
+- **Kick** a player: they get a polite notice and cannot come back to that room for the
+  minutes the owner chose (their seat, their browser, their account; their network only
+  when asked, since a household shares one).
+- **Mute** a player: their chat and emotes reach nobody (the `say`, `chat` and `emote`
+  events; a game hides the rest with `net.isMuted(seat)`).
+- **Announce** one line to a room, a game or the whole studio: every player sees it as a
+  banner, and a game can show it its own way (`net.on('announce')`).
+- **Close** a room: everyone is sent out with a thank-you; nobody gets in until it opens.
+- Per game: **players per room**, the **launch state** (`private`: only the owner;
+  `invite`: an invite-only beta, where each invite link or code lets a browser in;
+  `public`: anyone, listed), and **remixable** (publish or withdraw the game's source).
+  A game that is not public is in no list and not in the directory manifest, so the
+  directory drops it the next time it reads the studio. A new game is private from its
+  first deploy with `"launch": "private"` in its game.json.
+
+```sh
+npx homie-studio office link                            # a one-time link that signs the owner's browser in
+npx homie-studio office link --to /crown-thief/play     # ... onto a private game, on the owner's phone
+npx homie-studio office                                 # every live room and who is in it, now
+npx homie-studio office announce "Double gems this round!" --game crown-thief
+npx homie-studio office invite crown-thief --label "Sam" --uses 1
+npx homie-studio office launch crown-thief invite       # asks: the owner confirms with one tap
+npx homie-studio office kick crown-thief pub-3 2        # asks: seat 2 of Room 3
+npx homie-studio office key                             # a key for the Homie MCP's owner tools
+```
+
+Going private or invite-only never cuts a round short: each live room finishes its current round with a notice to
+the players, then everyone the new state leaves out is sent out with a thank-you (the owner, and in a beta the
+invited, play on). Mute drops a player's `say…`, `chat…` and `emote…` events, so a game that sends its chat and
+emotes under those kinds needs nothing more (`netplay/NETPLAY.md` section 15). Kicking a whole network address is in
+the studio's API (`address: true`) and deliberately not in the office. A Preview (a branch's own unlisted address, with
+no D1) enforces no launch state and has no office.
+
+**Privacy.** The site still sets no cookie on a visitor to count or follow them. Two things are kept for the back
+office, both functional: a random room key in the play page's own storage (what a kick holds; it says nothing about
+who the player is), and, for an invited player of an invite-only beta only, their pass to that game: an HttpOnly
+cookie for that game's pages alone, for 90 days. D1 keeps only a hash of each pass.
+
+**Only the owner.** The owner's browser is signed in with the same one-time link as the
+stats (an HttpOnly session no page or game can read; games run in a sandboxed, opaque
+frame). An office key (minted with the studio's own Cloudflare login) lets the owner's AI
+look, announce and invite at once; a kick, a mute, a closed room or a launch change is only
+**asked** for, and the owner confirms it with one tap in their own browser. No key can
+confirm. The Worker signs each control with the studio's own secret and the room verifies
+it before it acts (`netplay/NETPLAY.md` section 15). Everything is in the studio's own
+Worker and D1 (migration `0003_studio_office.sql`); homie.rocks stores none of it.
+
+With player accounts (0.12.0), a signed-in player's play page names their account in its room ticket (an invited
+player's names the invite and the account), so the office shows them by name and a kick holds the account on every
+device; the owner's own passkey account (`homie-studio players owner`) counts as the owner.
+
 ## Setup status
 
 ```sh
-npx -y @homie-rocks/studio@0.12.1 setup status --connector yes   # before a studio exists
+npx -y @homie-rocks/studio@0.14.0 setup status --connector yes   # before a studio exists
 npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
 ```
 

package/bin/homie-studio.mjs

@@ -5,8 +5,14 @@
  * list its games in the homie.rocks directory.
  *
  *   homie-studio new <folder> --name "<Studio Name>" [--homie <directory url>] [--no-install] [--template]
- *                                         (--template: the public "Deploy to Cloudflare" template: a first game and a Connect band)
+ *                                         (--template: the public "Deploy to Cloudflare" template, with a Connect band;
+ *                                          a new studio has no game: its home says "First game coming soon")
  *   homie-studio starters
+ *   homie-studio demo                     a live multiplayer game to try now (Homie Arcade), nothing copied into the studio
+ *   homie-studio mcp [--studios <folder>] [--skills <folder>]
+ *                                         this toolkit as a local MCP server (stdio): the Claude desktop app's Homie
+ *                                          extension, Claude Code or any MCP client builds in the same chat that shows
+ *                                          the cards (lib/mcp.mjs); --studios: the folder the studios live in
  *   homie-studio game new <id> [--from gem-rush] [--name "<Game Name>"]
  *   homie-studio game remix <source.json url> --id <new id>
  *   homie-studio games
@@ -40,6 +46,19 @@
  *   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 office [--url <site>]    the back office: every live room of every game and who is in it, now
+ *   homie-studio office link [--to <path>]   a one-time link that signs the owner's browser in (the office; or
+ *                                          --to /<game>/play: a private game on the owner's own phone)
+ *   homie-studio office key [--hours 1]   a key for the Homie MCP's owner tools (studio_office, room_kick, ...)
+ *   homie-studio office announce "<text>" [--game <id>] [--room <code>] [--seconds 30]
+ *   homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1] [--days <n>]
+ *   homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]
+ *   homie-studio office kick <game> <room> <seat number | name> [--minutes 10]
+ *   homie-studio office close <game> <room> [--minutes 10] [--reopen]
+ *                                         (kick, close and launch are ASKED for: the owner confirms each with one
+ *                                          tap in their own browser, from the link this prints)
+ *   homie-studio office revoke            (every office key, play ticket and pending ask ends)
+ *
  *   homie-studio progress start [<id>] [--what game|song|video] [--title "<what this build does>"]
  *                                        [--budget <dollars>] [--unit usd|credits] [--share]
  *                                         (a progress feed for one build; --share shows it in the Claude app
@@ -62,6 +81,9 @@
  *                                         into it (stage, each check going green, a preview picture) and stop
  *                                         when asked. Without one, nothing changes.
  *
+ *   homie-studio handoff <hb_…>           (a Claude Code session started from the Claude app with one line, "Continue building
+ *                                          <Studio>: build hb_…": fetch the person's brief, check in for a new studio, take
+ *                                          the build so the chat's card follows it, and print the steps; HANDOFF.md)
  *   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)
@@ -70,7 +92,9 @@
  *                                         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 new <id> [--name "<Name>"]
+ *                                         games/<id>/CODEX.md: the Game Codex, every section, in the game's colours (a game
+ *                                          is planned before it is made: with no game <id> yet, it starts its folder)
  *   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
@@ -98,21 +122,25 @@ 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 { ensureMigrations, newStudio } from '../lib/scaffold.mjs';
+import { ensureMigrations, migrationWord, 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 { officeAnnounce, officeClose, officeInvite, officeKey, officeKick, officeLaunch, officeLines, officeLink, officeRevoke, officeShow } from '../lib/office.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';
 import { restartWithProxy } from '../lib/net.mjs';
+import { demoGames, formatDemo } from '../lib/demo.mjs';
+import { serveMcp } from '../lib/mcp.mjs';
+import { formatHandoff, handoff } from '../lib/handoff.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open'];
+const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -128,7 +156,7 @@ const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
   if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
-  if (result.ok === false && result.command !== 'port check' && !(result.command === 'look' && result.rows)) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
+  if (result.ok === false && result.command !== 'port check' && !(result.command === 'look' && result.rows)) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}${result.instead ? `\n${result.instead}` : ''}\n`); return; }
   if (result.ok === false && result.command === 'port check' && !result.rows) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
   const lines = [];
   switch (result.command) {
@@ -232,9 +260,37 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    case 'office':
+      lines.push(...officeLines(result));
+      break;
+    case 'office link':
+      lines.push(`One-time link (until ${result.expiresAt}): ${result.link}`, result.use);
+      break;
+    case 'office key':
+      lines.push(`Office key (until ${result.expiresAt}): ${result.key}`, result.use);
+      break;
+    case 'office announce':
+    case 'office revoke':
+      lines.push(result.message);
+      break;
+    case 'office invite':
+      for (const i of result.invites) lines.push(`Invite ${i.code}${i.label ? ` (${i.label})` : ''}, ${i.maxUses ? `${i.maxUses} use${i.maxUses === 1 ? '' : 's'}` : 'any number of uses'}: ${i.link}`);
+      if (result.note) lines.push(result.note);
+      break;
+    case 'office launch':
+    case 'office kick':
+    case 'office close':
+      lines.push(result.asked ? `Asked: ${result.what}` : result.message, ...(result.asked ? [`Owner's one-tap link (until the ask ends, 15 min): ${result.link}`, result.use] : []));
+      break;
     case 'setup status':
       lines.push(formatStatus(result));
       break;
+    case 'demo':
+      lines.push(formatDemo(result));
+      break;
+    case 'handoff':
+      lines.push(formatHandoff(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}%)` : ''}`,
@@ -334,6 +390,12 @@ async function main() {
   if (cmd === 'version' || flags.has('version')) return { ok: true, command: 'version', version: STUDIO_VERSION };
   if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install'), template: flags.has('template') });
   if (cmd === 'starters') return { ok: true, command: 'starters', starters: starters() };
+  if (cmd === 'demo') return demoGames();
+  if (cmd === 'mcp') {
+    // stdout carries MCP messages only from here on (lib/mcp.mjs); every word for a person goes to stderr.
+    await serveMcp({ studios: flags.get('studios') ?? process.env.HOMIE_STUDIOS ?? null, skills: flags.get('skills') ?? process.env.HOMIE_SKILLS ?? null, install: !flags.has('no-install'), directory: flags.get('homie') ?? null });
+    return { ok: true, command: 'help' };
+  }
 
   if (cmd === 'port' && sub === 'plan') return planPort(positional[2] ?? '.');
   if (cmd === 'chrome' && sub === 'install') return installChrome({ log, fresh: flags.has('fresh') });
@@ -350,6 +412,7 @@ async function main() {
   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 === 'handoff') return handoff(root, sub, { 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') });
   if (cmd === 'port' && sub === 'check') {
     const game = positional[2] ?? listGames(root)[0]?.id;
@@ -408,6 +471,18 @@ async function main() {
   if (cmd === 'stats' && sub === 'revoke') return statsRevoke(root, { url: flags.get('url') });
   if (cmd === 'stats' && sub === 'share') return statsShare(root, positional[2]);
   if (cmd === 'stats' && !sub) return statsShow(root, { url: flags.get('url'), range: flags.get('range'), game: flags.get('game'), song: flags.get('song'), video: flags.get('video') });
+  if (cmd === 'office') {
+    const url = flags.get('url');
+    if (!sub) return officeShow(root, { url });
+    if (sub === 'link') return officeLink(root, { url, to: flags.get('to') });
+    if (sub === 'key') return officeKey(root, { url, hours: flags.get('hours') });
+    if (sub === 'announce') return officeAnnounce(root, positional.slice(2).join(' '), { url, game: flags.get('game'), room: flags.get('room'), seconds: flags.get('seconds') });
+    if (sub === 'invite') return officeInvite(root, positional[2], { url, label: flags.get('label'), uses: flags.get('uses'), count: flags.get('count'), days: flags.get('days') });
+    if (sub === 'launch') return officeLaunch(root, positional[2], positional[3], { url, remixable: flags.get('remixable'), max: flags.get('max') });
+    if (sub === 'kick') return officeKick(root, positional[2], positional[3], positional.slice(4).join(' ') || undefined, { url, minutes: flags.get('minutes') });
+    if (sub === 'close') return officeClose(root, positional[2], positional[3], { url, minutes: flags.get('minutes'), reopen: flags.has('reopen') });
+    if (sub === 'revoke') return officeRevoke(root, { url });
+  }
   if (cmd === 'media' && sub === 'put') return mediaPut(root, positional[2], flags.get('as'));
   if (cmd === 'media' && sub === 'list') {
     const studio = readStudio(root);
@@ -421,7 +496,7 @@ async function main() {
 /** `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 === 'new') return newCodex(root, positional[2] ?? (games.length === 1 ? games[0].id : undefined), { name: flags.get('name') ?? null });
   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>' };
@@ -572,12 +647,12 @@ async function stopDev(root) {
 async function dev(root) {
   const port = String(flags.get('port') ?? 8787);
   const b = await build(root, { log });
-  if (!b.catalogue.length && !b.songs.length && !b.videos.length) return { ok: false, command: 'dev', why: 'nothing to show yet: npx homie-studio game new <id> --from gem-rush, or publish a song or video (media/MEDIA.md)' };
+  if (!b.catalogue.length && !b.songs.length && !b.videos.length) log('No game yet: the home page says "First game coming soon" until the first one is made.');
   const bin = wranglerBin(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' };
-  for (const added of ensureMigrations(root)) log(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own stats'})`);
+  for (const added of ensureMigrations(root)) log(`added ${added} (${migrationWord(added)})`);
   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/lib/build.mjs

@@ -223,6 +223,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       // 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 } : {}),
+      // game.json `"launch": "private" | "invite"`: the game's launch state until its owner sets one live (the office).
+      ...(g.launch === 'private' || g.launch === 'invite' ? { launch: g.launch } : {}),
       landing: landingOf(g, join(dist, 'games', g.id), { videos: media.videos, songs: media.songs, log }),
     };
   });

package/lib/cloudflare.mjs

@@ -23,7 +23,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.mjs';
 import { repoOf } from './repo.mjs';
-import { ensureLocalIgnored, ensureMigrations, wranglerConfig } from './scaffold.mjs';
+import { ensureLocalIgnored, ensureMigrations, migrationWord, 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;
@@ -159,8 +159,8 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   }
 
   const b = await build(root, { log });
-  if (!b.catalogue.length && !b.songs.length && !b.videos.length) return { ok: false, command: 'deploy', why: 'nothing to put online yet: make a game (`npx --no-install homie-studio game new <id> --from gem-rush`) or publish a song or video in music/ or videos/ (media/MEDIA.md)' };
-  step(`built ${b.catalogue.length} game(s), ${b.songs.length} song(s), ${b.videos.length} video(s)`);
+  // A new studio goes live with its own Home ("First game coming soon") before it has a game.
+  step(b.catalogue.length || b.songs.length || b.videos.length ? `built ${b.catalogue.length} game(s), ${b.songs.length} song(s), ${b.videos.length} video(s)` : 'built the home page (no game yet: "First game coming soon")');
 
   // The Worker: never one this studio did not make.
   if (!created.has(`worker:${cf.worker}`)) {
@@ -193,7 +193,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) }));
-  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'})`);
+  for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   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');
@@ -293,7 +293,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 };
-  for (const added of ensureMigrations(root)) step(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own counters'})`);
+  for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   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);

package/lib/codex.mjs

@@ -471,6 +471,20 @@ function lookOf(root, game, meta, emb) {
   return { palette, fonts: { display: fam.display ?? stack.display, body: fam.body ?? stack.body, mono: fam.mono ?? stack.mono }, links: [...new Set(links)], faces };
 }
 
+/**
+ * The game a codex belongs to. A new studio has no game, and the plan comes before the game is made, so a codex may
+ * sit in games/<id>/ before its game.json does: then the "game" is that planned folder. `create`: a codex is being
+ * started for an id with no folder yet.
+ */
+function codexGame(root, id, { create = false } = {}) {
+  const game = listGames(root).find((g) => g.id === id);
+  if (game) return game;
+  if (!GAME_ID.test(String(id ?? ''))) return null;
+  const dir = join(root, 'games', id);
+  if (existsSync(join(dir, 'game.json'))) return null;
+  return existsSync(join(dir, CODEX_FILE)) || create ? { id, dir, name: null, planned: true } : null;
+}
+
 /**
  * The page for one game. `mode`: 'file' (this computer; reloads while a build runs), 'artifact' (one file to publish
  * as a Claude artifact), 'site' (the studio site's private page). `feed`: a progress feed document, else the game's
@@ -478,8 +492,8 @@ function lookOf(root, game, meta, emb) {
  */
 export function renderCodex(root, id, { mode = 'file', feed, now = new Date() } = {}) {
   if (!GAME_ID.test(String(id ?? ''))) throw new Error(`no game id ${JSON.stringify(id)}`);
-  const game = listGames(root).find((g) => g.id === id);
-  if (!game) throw new Error(`no game "${id}" in games/`);
+  const game = codexGame(root, id);
+  if (!game) throw new Error(`no game "${id}" in games/, and no codex planning it`);
   const file = join(game.dir, CODEX_FILE);
   if (!existsSync(file)) throw new Error(`games/${id}/${CODEX_FILE} does not exist yet: npx --no-install homie-studio codex new ${id}`);
   if (statSync(file).size > LIMITS.source) throw new Error(`games/${id}/${CODEX_FILE} is over ${LIMITS.source / 1024} KB`);
@@ -576,9 +590,12 @@ export function buildCodexPages(root, dist, ids, { log = () => {} } = {}) {
 /* ------------------------------------------------------------------ a new codex */
 
 /** `homie-studio codex new <id>`: CODEX.md with every section, its look taken from the game and the studio. */
-export function newCodex(root, id) {
-  const game = listGames(root).find((g) => g.id === id);
-  if (!game) return { ok: false, command: 'codex new', why: `no game "${id}" in games/ (make it first: npx --no-install homie-studio game new ${id} --from gem-rush)` };
+export function newCodex(root, id, { name = null } = {}) {
+  // A game is planned before it is made: with no game of this id, the codex starts its folder (games/<id>/CODEX.md),
+  // and `game new <id>` later makes the game around it.
+  const game = codexGame(root, id, { create: true });
+  if (!game) return { ok: false, command: 'codex new', why: `"${id}" is not a game id (lowercase letters, digits and hyphens, up to 40)` };
+  if (game.planned) { game.name = name ? String(name).slice(0, 60) : id.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' '); mkdirSync(game.dir, { recursive: true }); }
   const file = join(game.dir, CODEX_FILE);
   if (existsSync(file)) return { ok: false, command: 'codex new', why: `games/${id}/${CODEX_FILE} exists already: change it, never replace it` };
   const theme = readTheme(root);
@@ -608,7 +625,7 @@ ${game.blurb ?? ''}
 
 ## Latest
 
-- ${today}: The codex starts. The game is a copy of the ${game.from?.starter ?? 'starter'} starter for now.
+- ${today}: The codex starts. ${game.planned ? 'The game is planned here first; it is made once the plan is agreed.' : `The game is a copy of the ${game.from?.starter ?? 'starter'} starter for now.`}
 
 ## Concept
 
@@ -645,18 +662,20 @@ ${game.blurb ?? ''}
 
 ## Milestones
 
-- [x] Step 1: a working copy of the starter plays in two browsers
+${game.planned ? `- [ ] The plan (this codex)
+- [ ] The first playable version of the plan, checked with two browsers
+- [ ] Art, sound and its landing page; online` : `- [x] Step 1: a working copy of the starter plays in two browsers
 - [ ] Step 2: one small change from one sentence
 - [ ] Step 3: the plan (this codex)
 - [ ] Step 4: the first playable version of the plan, checked with two browsers
-- [ ] Step 5: art, sound and its landing page; online
+- [ ] Step 5: art, sound and its landing page; online`}
 
 ## Open questions
 
 -
 `;
   writeFileSync(file, text);
-  return { ok: true, command: 'codex new', id, file: relative(root, file), next: [`fill it from the plan interview, then: npx --no-install homie-studio codex ${id}`] };
+  return { ok: true, command: 'codex new', id, file: relative(root, file), planned: Boolean(game.planned), next: [`fill it from the plan interview, then: npx --no-install homie-studio codex ${id}`, ...(game.planned ? [`once the plan is agreed: npx --no-install homie-studio game new ${id} --from gem-rush --name "<Name>" makes the game around it (the codex stays)`] : [])] };
 }
 
 /** A sign-in link that opens one game's codex on the live site (the stats page's one-time sign-in, then the codex). */

package/lib/demo.mjs

@@ -0,0 +1,85 @@
+/**
+ * `homie-studio demo` — "see a working game" with nothing copied into the studio: a live multiplayer game on Homie
+ * Arcade (arcade.homie.rocks), the house's own studio of small public games, made with this same toolkit. Press Play
+ * and you are in a live public room with whoever is playing, bots in the empty seats; open it in two tabs (or a
+ * phone and a computer) and you are two players in the same room.
+ *
+ * A new studio starts with no game (its home page says "First game coming soon"). A starter is copied INTO the
+ * studio only when the person asks for one: `homie-studio game new <id> --from gem-rush`.
+ *
+ * It reads the arcade's own public manifest (/.well-known/homie-studio.json) and its live rooms (/api/rooms), so the
+ * links are the ones live right now; when the arcade does not answer, it names its usual first pick. Read-only.
+ */
+import { STUDIO_VERSION } from './version.mjs';
+
+export const DEMO_STUDIO = 'https://arcade.homie.rocks';
+/** The arcade's games that show a stranger the most in a minute, in order. */
+export const DEMO_PICKS = ['asteroids-arena', 'bone-burglar', 'tiny-platformer', '2048-race', 'octree-arena'];
+export const DEMO_FALLBACK = Object.freeze({
+  id: 'asteroids-arena', name: 'Asteroids Arena', blurb: 'Up to six ships on one wrap-around rock field. Top score in two minutes wins.',
+  page: `${DEMO_STUDIO}/asteroids-arena/`, play: `${DEMO_STUDIO}/asteroids-arena/play`, cover: null, players: { min: 1, max: 6 },
+});
+
+const HOW = 'Open Play in two browser tabs, or on a phone and a computer: you are two players in the same live public room, and bots fill the empty seats. Keys on a computer, touch on a phone.';
+const COPY = 'Want a working game inside your own studio instead? Only when you ask: `npx --no-install homie-studio game new <id> --from gem-rush` copies the Gem Rush starter (an arena: rounds, bots, one readable file), or `--from ember-vale` the Ember Vale starter (a hero who lasts for days, with cloud saves), into games/<id>/.';
+
+const text = (v, max) => String(v ?? '').replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+const onSite = (url, site) => (typeof url === 'string' && url.startsWith(`${site}/`) ? url : null);
+
+async function getJson(fetchFn, url, ms) {
+  const res = await fetchFn(url, { headers: { accept: 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION} (demo)` }, signal: AbortSignal.timeout(ms) });
+  if (!res.ok) throw new Error(`${url} answered ${res.status}`);
+  return res.json();
+}
+
+export async function demoGames({ fetchFn = globalThis.fetch, studio = DEMO_STUDIO, timeoutMs = 6000 } = {}) {
+  const site = String(studio).replace(/\/+$/, '');
+  let manifest = null; let rooms = null; let why = null;
+  try {
+    [manifest, rooms] = await Promise.all([
+      getJson(fetchFn, `${site}/.well-known/homie-studio.json`, timeoutMs),
+      getJson(fetchFn, `${site}/api/rooms`, timeoutMs).catch(() => null),
+    ]);
+  } catch (error) { why = error?.message ?? String(error); }
+  const live = new Map();
+  for (const r of Array.isArray(rooms?.rooms) ? rooms.rooms : []) {
+    const id = text(r?.game, 40);
+    if (id) live.set(id, (live.get(id) ?? 0) + (Number(r?.players) || 0));
+  }
+  const listed = (Array.isArray(manifest?.games) ? manifest.games : [])
+    .map((g) => ({
+      id: text(g?.id, 40), name: text(g?.name, 60), blurb: text(g?.blurb, 200),
+      page: onSite(g?.page, site), play: onSite(g?.play, site), cover: onSite(g?.cover, site),
+      players: g?.players && Number.isFinite(g.players.max) ? { min: Number(g.players.min) || 1, max: Number(g.players.max) } : null,
+    }))
+    .filter((g) => /^[a-z0-9][a-z0-9-]{0,39}$/.test(g.id) && g.play);
+  const rank = (g) => { const i = DEMO_PICKS.indexOf(g.id); return i < 0 ? DEMO_PICKS.length : i; };
+  // A game people are playing right now goes first: that is the best demo of all.
+  const games = listed.map((g) => ({ ...g, playingNow: live.get(g.id) ?? 0 }))
+    .sort((a, b) => (b.playingNow > 0) - (a.playingNow > 0) || rank(a) - rank(b) || a.name.localeCompare(b.name))
+    .slice(0, 5);
+  const pick = games[0] ?? { ...DEMO_FALLBACK, playingNow: 0 };
+  return {
+    ok: true, command: 'demo',
+    studio: { name: text(manifest?.name, 60) || 'Homie Arcade', site },
+    pick, games: games.length ? games : [pick],
+    ...(why ? { note: `the arcade did not answer just now (${why}); this is its usual first pick` } : {}),
+    how: HOW, copy: COPY,
+  };
+}
+
+/** The demo as a person reads it in a terminal. */
+export function formatDemo(r) {
+  const p = r.pick;
+  return [
+    `See a working game: ${p.name} on ${r.studio.name}${p.playingNow ? ` (${p.playingNow} playing right now)` : ''}`,
+    `  Play: ${p.play}`,
+    ...(p.blurb ? [`  ${p.blurb}`] : []),
+    '',
+    r.how,
+    ...(r.games.length > 1 ? ['', 'More to try:', ...r.games.slice(1).map((g) => `  ${g.name}: ${g.play}`)] : []),
+    ...(r.note ? ['', `(${r.note})`] : []),
+    '',
+    r.copy,
+  ].join('\n');
+}