@homie-rocks/studio 0.12.1 → 0.14.0

package/lib/mcp.mjs

@@ -0,0 +1,180 @@
+/**
+ * `homie-studio mcp` — the studio toolkit as a LOCAL MCP server (stdio), so the chat that shows Homie's cards also
+ * does the building: in the Claude desktop app through the Homie extension (.mcpb, desktop/ in this repository), in
+ * Claude Code, Codex or any MCP client. The remote Homie MCP (homie.rocks/mcp) coordinates (directory, grants, hub,
+ * progress relay for phones); this one does the work on this computer: studios, games, builds, checks with real
+ * browsers, deploys. Tools that overlap the remote ones keep their names and input shapes (lib/mcp-tools.mjs).
+ *
+ *   homie-studio mcp [--studios <folder>] [--skills <folder>]
+ *     --studios   the folder the person's studios live in (the extension's setting; `${HOME}/Studios` is expanded);
+ *                 without it, the studio the server was started in (the working directory, or one above it)
+ *     --skills    Homie's guides (the plugin's skills folder): studio_guide and the media tools read them
+ *     --no-install never run npm install in a studio (tests, and a studio whose node_modules are linked by hand)
+ *     --homie     the directory a new studio names (default https://homie.rocks)
+ *
+ * The transport is the MCP stdio transport: one JSON-RPC 2.0 message per line on stdin and stdout; logs go to
+ * stderr. No SDK. MCP Apps cards (spec 2026-01-26, `text/html;profile=mcp-app`) are served as ui:// resources from
+ * mcp/ui/ (real files, read as they are: a card's script is never built from a function's source), and every tool
+ * also answers in plain text for a host without cards.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACKAGE_ROOT } from './studio.mjs';
+import { StudioContext, UI, availability, toolDefs } from './mcp-tools.mjs';
+import { stopAllJobs, toolPath } from './jobs.mjs';
+import { STUDIO_VERSION } from './version.mjs';
+
+export const PROTOCOLS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+export const MCP_APP_MIME = 'text/html;profile=mcp-app';
+
+export const INSTRUCTIONS = `Homie Studio, on this computer: make game studios and their multiplayer web games, music and videos, run them here, and put them online on the studio's own Cloudflare. These tools do the work in this chat; the person never types a command and never needs a terminal. A studio is a folder in the studios folder; the file tools (file_list, file_read, file_edit, file_write, file_search) work inside it.
+
+A new studio follows one checklist, in order and never ahead. Show it in your first reply and again, ticked, as each step ends:
+0. Setup status (setup_status): what this computer and their accounts have; optional rows never block.
+1. The studio (studio_scaffold): it has NO game; its home page says "First game coming soon".
+2. See a working game (game_demo): a live game on Homie Arcade with its Play link, nothing copied in. Copy a starter in (game_make) only if they ask.
+3. One small change from one sentence of theirs: to the copied game, or to the studio's home (site/theme.json colours, a tagline in studio.json, a first post in posts/). Then build and preview_run, and they reload.
+4. Plan their game (game_plan): a short interview, two or three questions a message with options and your pick; then fill games/<id>/CODEX.md and show it (game_codex).
+5. Build it: build_open, then game_make under the planned id (the codex stays), file edits, build, preview_run, check. The card follows every build.
+6. Playtest it (playtest), then put it online: studio_deploy with plan: true first (say what it creates and costs, free), cloudflare_login when not signed in (they approve once in their browser), studio_deploy, then studio_publish.
+If they ask for everything at once, show the list, make your own choices for steps 2 to 4 in one line each, and go on.
+
+A studio made elsewhere (on a phone, with Deploy to Cloudflare, so it lives on GitHub): studio_open with its repo clones it into the studios folder with this computer's own GitHub sign-in; github_login signs the computer in with GitHub's one-time code. Never ask for a token.
+
+Long work (npm install, check, playtest, deploy, renders) runs in the background: the tool answers at once with a card that follows it, and build_progress or studio_job reads where it is. studio_guide has Homie's full guide for each job (game, plan, port, playtest, publish, music, sound, art, video). Never put a key or password in a file or the chat. If Homie's homie.rocks connector is connected too, its tools of the same names say what to run; these run it.`;
+
+const CARD_FILES = { [UI.setup]: 'setup.js', [UI.build]: 'build.js', [UI.studio]: 'studio.js', [UI.codex]: 'codex.js' };
+const CARD_TITLES = { [UI.setup]: 'Studio setup', [UI.build]: 'Build progress', [UI.studio]: 'Studio', [UI.codex]: 'Game Codex' };
+const UI_DIR = join(PACKAGE_ROOT, 'mcp', 'ui');
+
+/** One card's whole document: the shared look and bridge, and the card's own script, as the files are. */
+export function cardHtml(uri) {
+  const own = CARD_FILES[uri];
+  if (!own) return null;
+  const css = readFileSync(join(UI_DIR, 'card.css'), 'utf8');
+  const bridge = readFileSync(join(UI_DIR, 'bridge.js'), 'utf8');
+  const script = readFileSync(join(UI_DIR, own), 'utf8');
+  const safe = (s) => s.replace(/<\/(script|style)/gi, '<\\/$1');
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${CARD_TITLES[uri]} · Homie</title><style>${safe(css)}</style></head><body><main id="root" class="card" aria-live="polite"><div class="skel"></div><div class="skel"></div></main><script>${safe(bridge)}\n${safe(script)}</script></body></html>`;
+}
+
+/** What a card may load: nothing from the network, except the codex page's Google Fonts. */
+export function cardCsp(uri) {
+  if (uri === UI.codex) return { connectDomains: [], resourceDomains: ['https://fonts.googleapis.com', 'https://fonts.gstatic.com'] };
+  return { connectDomains: [], resourceDomains: [] };
+}
+
+export const PROMPTS = [
+  { name: 'new-studio', title: 'Set up a game studio', description: 'Make a game studio on this computer and go through Homie\'s new-studio checklist.', arguments: [{ name: 'name', description: 'The studio\'s name', required: false }] },
+  { name: 'make-multiplayer', title: 'Make my game multiplayer', description: 'Port an existing single-player web game on this computer into a studio.', arguments: [{ name: 'folder', description: 'The game\'s folder', required: true }] },
+];
+
+function promptText(name, args = {}) {
+  if (name === 'new-studio') return `Set up a game studio${args.name ? ` called ${String(args.name).slice(0, 60)}` : ''} with Homie, step by step.`;
+  if (name === 'make-multiplayer') return `Make the game in ${String(args.folder ?? '').slice(0, 200)} multiplayer on my Homie studio.`;
+  return null;
+}
+
+/**
+ * The server. `input`/`output` are streams (stdin/stdout by default). Returns a promise that ends with the input.
+ */
+export async function serveMcp({ studios = null, skills = null, cwd = process.cwd(), input = process.stdin, output = process.stdout, waitMs, directory = null, install = true, log = (line) => process.stderr.write(`[homie-studio mcp] ${line}\n`) } = {}) {
+  // A GUI app starts this with a short PATH: everything it runs sees the usual places Node, npm and ffmpeg live.
+  process.env.PATH = toolPath();
+  const skillsDir = skills ?? [join(PACKAGE_ROOT, '..', '..', 'plugins', 'homie', 'skills'), join(PACKAGE_ROOT, '..', 'skills')].find((d) => existsSync(join(d, 'studio-setup', 'SKILL.md'))) ?? null;
+  const ctx = new StudioContext({ studiosDir: studios, cwd, skillsDir, waitMs: waitMs ?? Number(process.env.HOMIE_MCP_WAIT_MS || 40_000), directory, install });
+  let avail = availability();
+  let names = '';
+  const send = (message) => output.write(`${JSON.stringify(message)}\n`);
+  const tools = () => {
+    const list = toolDefs(ctx, avail);
+    const now = list.map((t) => t.name).join(',');
+    names = now;
+    return list;
+  };
+  tools();
+  log(`ready: toolkit ${STUDIO_VERSION}, studios ${ctx.studiosDir ?? '(none set)'}${ctx.cwdStudio ? `, started in ${ctx.cwdStudio}` : ''}${skillsDir ? ', guides on' : ''}`);
+
+  async function handle(message) {
+    const { id, method, params } = message ?? {};
+    const isRequest = message && Object.hasOwn(message, 'id') && id !== null && id !== undefined;
+    const reply = (result) => { if (isRequest) send({ jsonrpc: '2.0', id, result }); };
+    const error = (code, text) => { if (isRequest) send({ jsonrpc: '2.0', id, error: { code, message: text } }); };
+    try {
+      switch (method) {
+        case 'initialize': {
+          const asked = params?.protocolVersion;
+          return reply({
+            protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
+            capabilities: { tools: { listChanged: true }, resources: { listChanged: false }, prompts: { listChanged: false } },
+            serverInfo: { name: 'homie-studio', title: 'Homie Studio', version: STUDIO_VERSION },
+            instructions: INSTRUCTIONS,
+          });
+        }
+        case 'ping': return reply({});
+        case 'tools/list':
+          return reply({ tools: tools().map(({ run, ...t }) => t) });
+        case 'tools/call': {
+          const name = params?.name;
+          const tool = tools().find((t) => t.name === name);
+          if (!tool) return reply({ content: [{ type: 'text', text: `No tool ${name} here.` }], isError: true });
+          const t0 = Date.now();
+          let result;
+          try { result = await tool.run(params?.arguments ?? {}); } catch (e) { result = { content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }], isError: true }; }
+          log(`${name} ${result?.isError ? 'failed' : 'ok'} in ${Date.now() - t0} ms`);
+          reply(result);
+          // A media provider set up meanwhile adds its tool.
+          const before = names;
+          avail = availability();
+          tools();
+          if (names !== before) send({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' });
+          return undefined;
+        }
+        case 'resources/list':
+          return reply({ resources: Object.values(UI).map((uri) => ({ uri, name: uri.split('/').pop(), title: CARD_TITLES[uri], mimeType: MCP_APP_MIME })) });
+        case 'resources/templates/list': return reply({ resourceTemplates: [] });
+        case 'resources/read': {
+          const uri = String(params?.uri ?? '');
+          const html = cardHtml(uri);
+          if (!html) return error(-32002, `no resource ${uri}`);
+          return reply({ contents: [{ uri, mimeType: MCP_APP_MIME, text: html, _meta: { ui: { csp: cardCsp(uri), prefersBorder: false } } }] });
+        }
+        case 'prompts/list': return reply({ prompts: PROMPTS });
+        case 'prompts/get': {
+          const p = PROMPTS.find((x) => x.name === params?.name);
+          if (!p) return error(-32602, `no prompt ${params?.name}`);
+          return reply({ description: p.description, messages: [{ role: 'user', content: { type: 'text', text: promptText(p.name, params?.arguments) } }] });
+        }
+        case 'logging/setLevel': return reply({});
+        default:
+          if (!isRequest) return undefined; // notifications/initialized, notifications/cancelled, …
+          return error(-32601, `method not found: ${method}`);
+      }
+    } catch (e) {
+      return error(-32603, e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  let buffer = '';
+  const pending = new Set();
+  await new Promise((done) => {
+    input.setEncoding?.('utf8');
+    input.on('data', (chunk) => {
+      buffer += chunk;
+      let nl;
+      while ((nl = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, nl).trim();
+        buffer = buffer.slice(nl + 1);
+        if (!line) continue;
+        let msg;
+        try { msg = JSON.parse(line); } catch { send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } }); continue; }
+        const p = handle(msg).finally(() => pending.delete(p));
+        pending.add(p);
+      }
+    });
+    input.on('end', done);
+    input.on('close', done);
+  });
+  await Promise.allSettled([...pending]);
+  stopAllJobs();
+}

package/lib/office.mjs

@@ -0,0 +1,172 @@
+/**
+ * `homie-studio office` — the studio's back office from the studio folder (worker/office.mjs says what it is).
+ *
+ *   homie-studio office [--url <site>]                 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 phone)
+ *   homie-studio office key [--hours 1]                an office key for the Homie MCP's owner tools (studio_office,
+ *                                                      room_kick, room_announce, room_close, game_launch_state)
+ *   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]
+ *   homie-studio office revoke                         every office key ends; every play ticket and pending ask too
+ *
+ * THE PROOF OF OWNERSHIP IS THE STUDIO'S OWN CLOUDFLARE LOGIN, as for the stats: a key is minted here and only its
+ * SHA-256 goes into the studio's D1. Looking, announcing and inviting happen at once. Kick, mute, closing a room and
+ * a game's launch state, remix switch or room size are only ASKED for here: the answer is a one-time sign-in link
+ * that opens the ask in the owner's own browser, where one tap does it (the AI that ran this cannot).
+ */
+import { readStudio } from './studio.mjs';
+import { runner } from './cloudflare.mjs';
+import { drop, loopback, mint, siteOf } from './stats.mjs';
+
+const HOUR = 3600_000;
+const GAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+/** Call the studio's office API with a key that lives ten minutes and is dropped as soon as the answer is in. */
+async function withKey(root, url, fn) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, 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);
+  const k = mint(root, studio, 'office', 10 * 60_000, { local });
+  if (!k.ok) return { ok: false, why: /no such table: stats_keys/.test(k.why) ? k.why : k.why };
+  try {
+    const call = async (path, body = null) => {
+      const res = await fetch(`${site}${path}`, {
+        method: body ? 'POST' : 'GET',
+        headers: { authorization: `Bearer ${k.key}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
+        ...(body ? { body: JSON.stringify(body) } : {}), signal: AbortSignal.timeout(20_000),
+      });
+      const out = await res.json().catch(() => ({ ok: false, message: `${site}${path} answered ${res.status}` }));
+      return { status: res.status, ...out };
+    };
+    return await fn(call, { studio, site, local });
+  } catch (error) {
+    return { ok: false, why: `could not reach ${site}: ${error.message}` };
+  } finally { drop(root, studio, k.hash, { local }); }
+}
+
+/** A one-time sign-in link for the owner's browser that lands on `to` (30 minutes). */
+function signinTo(root, url, to) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, why: 'this studio has no live site yet: `npm run deploy` first' };
+  const k = mint(root, studio, 'signin', 30 * 60_000, { local: loopback(site) });
+  if (!k.ok) return k;
+  return { ok: true, site, link: `${site}/_studio/signin?k=${k.key}${to && to !== '/_studio/stats' ? `&to=${encodeURIComponent(to)}` : ''}`, expiresAt: k.expiresAt };
+}
+
+const askedFor = (root, url, r, command) => {
+  if (!r.ok) return { ok: false, command, why: r.message ?? r.why ?? `the studio said ${r.error ?? r.status}` };
+  if (r.needs !== 'owner' || !r.ask) return { ok: true, command, done: true, result: r, message: r.what ? `Done: ${r.what}` : 'Done.' };
+  const link = signinTo(root, url, `/_studio/confirm/${r.ask.id}`);
+  return {
+    ok: true, command, asked: true, ask: r.ask, what: r.ask.what,
+    link: link.ok ? link.link : r.ask.confirm,
+    use: `Waiting for the owner: ${r.ask.what} Give the owner this link to open in their own browser: it signs that browser in (once, within 30 minutes) and shows the ask with one button. It lasts 15 minutes; nothing happens unless the owner taps.`,
+  };
+};
+
+export async function officeShow(root, { url } = {}) {
+  const r = await withKey(root, url, (call) => call('/_studio/api/office'));
+  if (!r.ok) return { ok: false, command: 'office', why: r.why ?? r.message ?? 'the office did not answer' };
+  return { command: 'office', ...r, ok: true };
+}
+
+export function officeLink(root, { url, to } = {}) {
+  const target = to && /^\/[A-Za-z0-9_/-]{1,80}$/.test(String(to)) ? String(to) : '/_studio/office';
+  const r = signinTo(root, url, target);
+  if (!r.ok) return { ok: false, command: 'office link', why: r.why };
+  return {
+    ...r, command: 'office link', to: target,
+    use: 'Give this link to the studio\'s owner to open in their own browser: it works once, within 30 minutes, and keeps that browser signed in as the owner for 30 days (the office, the stats, and the owner\'s tools inside their own games). It is theirs alone; do not post it anywhere.',
+  };
+}
+
+export function officeKey(root, { url, hours } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'office key', why: 'this studio has no live site yet: `npm run deploy` first' };
+  const h = Math.max(1, Math.min(24 * 30, Math.floor(Number(hours) || 1)));
+  const k = mint(root, studio, 'office', h * HOUR, { local: loopback(site) });
+  if (!k.ok) return { ok: false, command: 'office key', why: k.why };
+  return {
+    ok: true, command: 'office key', site, key: k.key, expiresAt: k.expiresAt, hours: h,
+    use: `Pass { "site": "${site}", "key": "<this key>" } to the Homie MCP's owner tools (studio_office, room_announce, room_kick, room_close, game_launch_state). With it the AI sees the live rooms, announces and makes invites; a kick, a closed room or a launch state change is only asked for, and the owner confirms it with one tap. It also reads the stats (studio_stats). It ends at ${k.expiresAt}; \`homie-studio office revoke\` ends it sooner. Never paste it anywhere else.`,
+  };
+}
+
+export async function officeAnnounce(root, text, { url, game, room, seconds } = {}) {
+  if (!String(text ?? '').trim()) return { ok: false, command: 'office announce', why: 'usage: homie-studio office announce "<text>" [--game <id>] [--room <code>]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/announce', { text, ...(game ? { game } : {}), ...(room ? { room } : {}), ...(seconds ? { seconds: Number(seconds) } : {}) }));
+  return r.ok ? { ok: true, command: 'office announce', ...r, message: `Announced to ${r.people ?? 0} people in ${r.rooms ?? 0} room(s).` } : { ok: false, command: 'office announce', why: r.message ?? r.why };
+}
+
+export async function officeInvite(root, game, { url, label, uses, count, days } = {}) {
+  if (!GAME.test(String(game ?? ''))) return { ok: false, command: 'office invite', why: 'usage: homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/invites', {
+    game, ...(label ? { label } : {}), uses: uses === 'any' ? 'any' : uses ? Number(uses) : 1, ...(count ? { count: Number(count) } : {}), ...(days ? { days: Number(days) } : {}),
+  }));
+  if (!r.ok) return { ok: false, command: 'office invite', why: r.message ?? r.why };
+  return { ok: true, command: 'office invite', game, launch: r.launch, invites: r.invites, note: r.launch === 'invite' ? null : `${game} is ${r.launch} now: invites let people in once it is an invite-only beta (homie-studio office launch ${game} invite).` };
+}
+
+export async function officeLaunch(root, game, state, { url, remixable, max } = {}) {
+  if (!GAME.test(String(game ?? '')) || (state !== undefined && state !== null && !['private', 'invite', 'public'].includes(state))) {
+    return { ok: false, command: 'office launch', why: 'usage: homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]' };
+  }
+  const body = { game, ...(state ? { launch: state } : {}), ...(remixable !== undefined ? { remix: remixable === 'on' || remixable === true } : {}), ...(max !== undefined ? { maxPlayers: max === 'game' ? null : Number(max) } : {}) };
+  const r = await withKey(root, url, (call) => call('/_studio/api/game', body));
+  return askedFor(root, url, r, 'office launch');
+}
+
+export async function officeKick(root, game, room, who, { url, minutes } = {}) {
+  if (!GAME.test(String(game ?? '')) || !room || who === undefined) return { ok: false, command: 'office kick', why: 'usage: homie-studio office kick <game> <room> <seat number | name> [--minutes 10]' };
+  const r = await withKey(root, url, async (call) => {
+    const office = await call('/_studio/api/office');
+    const g = (office.games ?? []).find((x) => x.id === game);
+    const rm = (g?.rooms ?? []).find((x) => x.room === room || x.label.toLowerCase() === String(room).toLowerCase());
+    if (!rm) return { ok: false, message: `nobody is in ${room} of ${game} now (homie-studio office lists the rooms)` };
+    const seat = /^\d+$/.test(String(who)) ? Number(who) - 1 : null;
+    const c = rm.clients.find((x) => (seat !== null && x.seat === seat) || String(x.name).toLowerCase() === String(who).toLowerCase());
+    if (!c) return { ok: false, message: `no "${who}" in ${rm.label} (seats are numbered from 1)` };
+    return call('/_studio/api/kick', { game, room: rm.room, id: c.id, minutes: Number(minutes) || 10 });
+  });
+  return askedFor(root, url, r, 'office kick');
+}
+
+export async function officeClose(root, game, room, { url, minutes, reopen } = {}) {
+  if (!GAME.test(String(game ?? '')) || !room) return { ok: false, command: 'office close', why: 'usage: homie-studio office close <game> <room> [--minutes 10] [--reopen]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/close', { game, room, minutes: Number(minutes) || 10, reopen: Boolean(reopen) }));
+  return askedFor(root, url, r, 'office close');
+}
+
+/** Every office key ends, and the office secret is made anew: every play ticket and every signed control ends with it. */
+export function officeRevoke(root, { url } = {}) {
+  const { studio, site } = siteOf(root, url);
+  const local = site ? loopback(site) : false;
+  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', "DELETE FROM stats_keys WHERE kind = 'office'; DELETE FROM meta WHERE key = 'office_key'; UPDATE office_asks SET state = 'expired' WHERE state = 'pending';"]);
+  return res.code === 0
+    ? { ok: true, command: 'office revoke', site, message: 'Every office key has ended, and every play ticket and pending ask with it (a browser let into a private or invite-only game gets a new ticket the next time it opens the game). Invite passes and the owner\'s signed-in browsers stay; `homie-studio stats revoke` ends those sessions.' }
+    : { ok: false, command: 'office revoke', why: res.out.trim().split('\n').slice(-3).join(' ') };
+}
+
+/** One line per room for a person (the CLI's print). */
+export function officeLines(r) {
+  const lines = [`${r.studio}: ${r.playing ? `${r.playing} playing now` : 'nobody playing right now'} (${r.site})`];
+  const now = r.now ?? Date.now();
+  const mins = (ms) => `${Math.max(0, Math.round(ms / 60000))} min`;
+  for (const g of r.games ?? []) {
+    lines.push(`  ${g.name} (${g.id}): ${g.launch}${g.launch === 'public' ? '' : ' (not listed)'}, ${g.remix ? 'remixable' : 'source closed'}, rooms of ${g.maxPlayers}${g.maxSet ? ` (the game's own: ${g.seats})` : ''}`);
+    for (const i of (g.invites ?? []).filter((x) => x.open)) lines.push(`    invite ${i.code}${i.label ? ` (${i.label})` : ''}: ${i.uses}${i.maxUses ? ` of ${i.maxUses}` : ''} used · ${i.link}`);
+    if (!g.rooms.length) lines.push('    no live rooms');
+    for (const rm of g.rooms) {
+      const round = rm.round ? `round ${rm.round.n} ${rm.round.phase}` : 'no round';
+      lines.push(`    ${rm.label}${rm.public ? '' : ' (named)'}: ${rm.players}/${rm.max} players, ${rm.bots} bots, ${round}, up ${rm.openedAt ? mins(now - rm.openedAt) : '?'}${rm.closedUntil ? `, CLOSED for ${mins(rm.closedUntil - now)}` : ''}`);
+      for (const c of rm.clients) lines.push(`      ${c.seat !== null ? `seat ${c.seat + 1}` : 'watching'}: ${c.name} · ${c.device}${c.role === 'host' ? ' · host' : ''} · ${c.as}${c.muted ? ' · muted' : ''} · here ${mins(now - c.joinedAt)}`);
+      for (const b of rm.bans ?? []) lines.push(`      kicked: ${b.name} (back in ${mins(b.until - now)})`);
+    }
+  }
+  return lines;
+}

package/lib/scaffold.mjs

@@ -4,6 +4,7 @@
  *
  *   AGENTS.md            what this studio is and how to work in it (both apps)
  *   CLAUDE.md            imports AGENTS.md (Claude Code's documented way to share it)
+ *   HANDOFF.md           what a Claude Code session started from the Claude app does with its one-line prompt
  *   studio.json          the studio's name, slug, and its Cloudflare resources
  *   package.json         @homie-rocks/studio and wrangler, pinned
  *   games/<id>/          one folder per game (game.json, index.html, src/)
@@ -25,8 +26,8 @@ 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 { OFFICE_MIGRATION, OFFICE_MIGRATION_FILE } from '../worker/office-schema.mjs';
 import { themeFile } from './site.mjs';
-import { PACKAGE_ROOT } from './studio.mjs';
 
 export const COMPAT_DATE = '2026-06-01';
 /** 4.135.0 or later: Worker Previews (`wrangler preview`, a Durable Object namespace per Preview). */
@@ -113,8 +114,11 @@ directory lists its games; homie.rocks does not host them.
 Use \`npm run <script>\` or \`npx --no-install homie-studio <command>\`: \`--no-install\` makes sure it is this
 studio's pinned copy, never a registry lookup of the bare name.
 
+- \`npx --no-install homie-studio demo\` — a live multiplayer game to try right now (on Homie Arcade, with
+  whoever is playing and bots in the empty seats). Nothing is copied into this studio.
 - \`npx --no-install homie-studio game new <id> --from gem-rush --name "<Name>"\` — a new game from a
-  multiplayer starter (one live public room from its first build, bots fill seats).
+  multiplayer starter (one live public room from its first build, bots fill seats). A new studio starts with no
+  game: copy a starter only when the person asks for one, or once their game is planned.
 - \`npx --no-install homie-studio port plan <folder>\` — read an existing single-player web game and grade
   how hard making it multiplayer will be; \`port import\` brings it into \`games/\`, \`port check\` runs the
   owner tests (real touch, a late joiner, a killed host, two browsers finishing a round). The Homie
@@ -167,6 +171,8 @@ studio's pinned copy, never a registry lookup of the bare name.
 - **Sections, like homie.rocks:** Home (the featured game, live rooms, latest posts), Games, Music, Videos,
   Rooms (every public room playing now, joinable) and Posts. A section with nothing in it has no tab, and its
   page is not found.
+- **A new studio goes live with its Home only:** its name and "First game coming soon", with what is on the way
+  (games, posts, music and videos), until its first game, song or video is published. A post shows there at once.
 - **Every game gets a landing** at \`/<id>/\`: a full-bleed hero from the game's own footage
   (\`games/<id>/hero/wide.mp4\` and \`tall.mp4\`, or a trailer in \`videos/\` with \`for.game\`), else its cover
   with slow motion; the pitch, a big Play button into a public room, phone / computer / TV with the join code,
@@ -222,6 +228,35 @@ studio's pinned copy, never a registry lookup of the bare name.
   Cloudflare, Chrome, ffmpeg, GitHub, ElevenLabs, fal), what each unlocks, and the exact fix. Optional ones never
   block anything.
 
+## Running live games (the back office)
+
+- The owner runs the studio's live games from \`/_studio/office\` (\`npx --no-install homie-studio office link\` gives
+  the owner a one-time sign-in link): every live room of every game, who is in it (handles; accounts once players
+  sign in), bots, the round and uptime, refreshing by itself; Kick (that player cannot come back to that room for
+  the minutes chosen), Mute (their chat and emotes reach nobody), Announce (one line every player sees), Close a
+  room; and per game: launch state, Remixable, players per room and invites.
+- **Launch states:** \`private\` (only the owner, signed in; \`office link --to /<id>/play\` signs the owner's phone
+  in), \`invite\` (an invite-only beta: \`office invite <id>\` makes invite links and codes, each for one browser or
+  as many as \`--uses\` says), \`public\` (the default; listed). 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 stays private
+  from its first deploy with \`"launch": "private"\` in its game.json. **Remixable** publishes or withdraws its source.
+- The owner is recognised in their own games: signed in, their play page has a small Owner button (tap a player:
+  Mute, Kick; Announce). Nobody else's page has it.
+- **From the AI:** \`npx --no-install homie-studio office\` lists who is playing now; \`office announce "<text>"\` and
+  \`office invite <id>\` happen at once; \`office kick\`, \`office close\` and \`office launch\` only ASK, and print a
+  one-time link that opens the ask in the owner's own browser, where one tap does it. An ask is not done until the
+  owner tapped. \`office key\` gives a key for the Homie MCP's owner tools (\`studio_office\`, \`room_announce\`,
+  \`room_kick\`, \`room_close\`, \`game_launch_state\`), which ask the same way; never paste a key anywhere else.
+- A game can listen (\`NETPLAY.md\` section 15): \`net.on('announce', …)\`, \`net.isMuted(seat)\` to hide a muted
+  player's chat, and \`net.pickPlayer(seat)\` when a player is clicked (the owner's page opens their card).
+
+## Continuing a build from the Claude app
+
+A Claude Code session started from the Claude app's card gets one short line, like
+\`Continue building Night Owls: build hb_…\`. \`HANDOFF.md\` says what to do with it:
+\`npx --no-install homie-studio handoff hb_…\` fetches the brief the person gave in the chat, takes the build (the
+chat's card follows the work from then on) and, for a studio still being set up, checks in from this repository.
+
 ## Rules
 
 - Keys stay in the providers' own logins (Wrangler, ElevenLabs, fal) or the OS
@@ -257,6 +292,39 @@ and ask for a game; \`AGENTS.md\` says how everything here works.
 `;
 }
 
+/**
+ * HANDOFF.md: what a Claude Code session started from the Claude app does with the one line it is given
+ * ("Continue building <Studio>: build hb_…"). The brief stays with the build in the directory; the session fetches it
+ * (`homie-studio handoff`, lib/handoff.mjs), so no wall of text ever goes through a prompt.
+ */
+export const HANDOFF_MD = `# Continuing a build from the Claude app
+
+The Claude app (claude.ai on a phone or the web) hands a build to a Claude Code session in this repository with
+one short line:
+
+    Continue building <Studio>: build hb_<32 hex digits>
+
+That line is all the session is given. The brief (what the person asked for, in their words) stays with the build:
+
+1. \`npm install\` (once per session).
+2. \`npx --no-install homie-studio handoff hb_…\` prints the brief and the steps for this kind of build (a new
+   studio's first session, a new game, a port, a remix or a change). It takes the build once, so the chat's card
+   follows the work, and for a studio still being set up it checks in from this repository.
+3. If it says this session's network does not reach homie.rocks and the Homie connector's tools are in this session,
+   call \`build_progress\` with \`{ "build": "hb_…" }\`: its answer carries the same brief. Otherwise tell the person
+   in one line and ask what to build; the card in their chat shows the brief.
+4. Do the work the brief asks for, as AGENTS.md says: \`npm run build\`, \`npm run dev\` in the background, and
+   \`npx --no-install homie-studio check <id> --url http://127.0.0.1:8787\` (on Linux without Chrome, first
+   \`npx --no-install homie-studio chrome install\`).
+5. \`npx --no-install homie-studio progress change "<what it does, one line>"\`; commit on a new branch, push,
+   \`gh pr create\`; then \`npx --no-install homie-studio progress pr --url <the pull request>\`.
+
+Never merge the pull request: the person publishes it from the chat's card, in GitHub. A new studio has no game
+yet: copy a starter only when the brief or the person asks for one.
+
+On a computer, the Claude desktop app with the Homie extension builds in the same chat, with no hand-off at all.
+`;
+
 const MIGRATION = `-- A studio's own D1: the directory claim, and every finished round of every public room.
 CREATE TABLE IF NOT EXISTS meta (
   key TEXT PRIMARY KEY,
@@ -379,10 +447,11 @@ export function studioFiles({ name, slug, homie, template = false }) {
     'AGENTS.md': agentsMd({ name, slug }),
     'CLAUDE.md': claudeMd(),
     'README.md': template ? templateReadme() : readme({ name }),
+    'HANDOFF.md': HANDOFF_MD,
     'studio.json': `${JSON.stringify(studio, null, 2)}\n`,
     'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
     '.gitignore': GITIGNORE,
-    'games/README.md': 'One folder per game. Start one with `npx --no-install homie-studio game new <id> --from gem-rush`.\n',
+    'games/README.md': 'One folder per game. A new studio has none (its home page says "First game coming soon"). Start one with `npx --no-install homie-studio game new <id> --from gem-rush` when the person asks for a copy of the starter, or once their game is planned.\n',
     'music/README.md': 'Songs, game scores, loops and stems, one folder each (`music/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/music/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
     'music/manifest.json': '{ "v": 1, "items": [] }\n',
     'videos/README.md': 'Trailers, music videos and cutscenes, one folder each (`videos/<slug>/`). `manifest.json` lists them (`node_modules/@homie-rocks/studio/media/MEDIA.md`); a published entry gets a page at `/videos/<slug>/`. The site serves files up to 25 MiB itself; larger ones go to the studio\'s storage with `npx --no-install homie-studio media put` (after `npx --no-install homie-studio storage add`). Never into git.\n',
@@ -397,33 +466,19 @@ 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,
+    [`site/migrations/${OFFICE_MIGRATION_FILE}`]: OFFICE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
   };
   if (template) {
-    // A first game, so the site plays the moment Cloudflare deploys it; and a band on Home that connects the new
-    // studio to the Claude chat that set it up (`setup attach` removes both once Claude works in the studio).
-    for (const [rel, text] of starterFiles('gem-rush')) files[`games/gem-rush/${rel}`] = text;
+    // No game: a new studio goes live with its own Home ("first game coming soon"), and a band there that connects
+    // it to the Claude chat that set it up (`setup attach` removes the band once Claude works in the studio). A
+    // starter is copied in only when the person asks for one (`homie-studio game new`).
     files['site/partials/home.html'] = CONNECT_BAND;
   }
   return files;
 }
 
-/** A starter's files, as text, relative to its folder. */
-function starterFiles(id) {
-  const dir = join(PACKAGE_ROOT, 'starters', id);
-  const out = [];
-  const walk = (rel) => {
-    for (const entry of readdirSync(join(dir, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      const path = rel ? `${rel}/${entry.name}` : entry.name;
-      if (entry.isDirectory()) walk(path);
-      else out.push([path, readFileSync(join(dir, path), 'utf8')]);
-    }
-  };
-  walk('');
-  return out;
-}
-
 /** The template's first-run band on Home: one link that connects this studio to the Claude chat that set it up. */
 export const CONNECT_BAND = `<!-- A new studio from the Homie template. This band goes away once Claude works in the studio
      (homie-studio setup attach removes it); delete it by hand any time. -->
@@ -445,7 +500,7 @@ and a site with public multiplayer rooms that runs on **your own Cloudflare acco
 
 The button copies this studio into your GitHub, creates its Worker, database and rooms on your Cloudflare, and
 deploys it with Workers Builds: every push to \`main\` goes live, and every other branch gets its own Preview.
-The site plays a first game the moment it is up.
+The site goes live at once with its own home page ("first game coming soon"); the games come next.
 
 Then open the site and tap **Connect to Claude**, or ask Claude in the Claude app to set up your studio with the
 Homie connector: it makes games, songs and videos here, in a pull request you merge with one tap.
@@ -466,6 +521,18 @@ export function ensureStatsMigration(root) {
   return `site/migrations/${STATS_MIGRATION_FILE}`;
 }
 
+/**
+ * A studio made before 0.13.0 has no back-office migration (worker/office.mjs): add it, so the next
+ * `d1 migrations apply` makes its tables. Returns the file it wrote, or null when it was there.
+ */
+export function ensureOfficeMigration(root) {
+  const file = join(root, 'site', 'migrations', OFFICE_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, OFFICE_MIGRATION);
+  return `site/migrations/${OFFICE_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.
@@ -480,7 +547,12 @@ export function ensurePlayersMigration(root) {
 
 /** 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);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root)].filter(Boolean);
+}
+
+/** What a migration file the template added is for, in a few words (deploy and dev say it). */
+export function migrationWord(file) {
+  return /players/.test(file) ? 'player accounts and cloud saves' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**
@@ -540,8 +612,9 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
   const q = JSON.stringify(realpathSync(dir));
   return { ok: true, command: 'new', dir: realpathSync(dir), name, slug, wrote, git, installed, studio: STUDIO_VERSION, next: [
     `cd ${q}${install ? '' : ' && npm install'}`,
-    'npx --no-install homie-studio game new <id> --from gem-rush --name "<Game Name>"',
-    'npm run dev   (then: npx --no-install homie-studio check <id> --url http://127.0.0.1:8787)',
+    'see a working game first, with nothing copied here: npx --no-install homie-studio demo (a live game on Homie Arcade)',
+    'a copy of a starter only when the person asks for one: npx --no-install homie-studio game new <id> --from gem-rush --name "<Game Name>"',
+    'npm run dev   (the home page, "first game coming soon", at http://127.0.0.1:8787/; with a game: npx --no-install homie-studio check <id> --url http://127.0.0.1:8787)',
     'npm run deploy   (then the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish)',
   ], online: 'Going online creates one Worker, one D1 database and two Durable Objects on your own Cloudflare account: free plan, no payment method, no R2. `npx --no-install homie-studio deploy --plan` says exactly what, and changes nothing.' };
 }

package/lib/stats.mjs

@@ -48,7 +48,7 @@ export function mint(root, studio, kind, ttlMs, { local }) {
   return { ok: true, key, hash, expiresAt: new Date(now + ttlMs).toISOString() };
 }
 
-function drop(root, studio, hash, { local }) {
+export function drop(root, studio, hash, { local }) {
   const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
   w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', `DELETE FROM stats_keys WHERE hash = '${hash}';`]);
 }

package/lib/studio.mjs

@@ -108,7 +108,10 @@ export function newGame(root, id, { from = 'gem-rush', name } = {}) {
   const src = join(PACKAGE_ROOT, 'starters', from);
   if (!existsSync(join(src, 'game.json'))) throw new Error(`no starter "${from}"; starters: ${starters().map((s) => s.id).join(', ')}`);
   const dest = join(root, 'games', id);
-  if (existsSync(dest)) throw new Error(`games/${id} already exists; pick another id or change that game`);
+  if (existsSync(join(dest, 'game.json'))) throw new Error(`games/${id} already exists; pick another id or change that game`);
+  // A planned game (its folder holds the Game Codex, maybe art, and no game.json yet): the starter goes in around
+  // what is there, and nothing of the plan is overwritten.
+  if (existsSync(dest) && readdirSync(dest).some((f) => existsSync(join(src, f)))) throw new Error(`games/${id} holds files of its own that a starter would overwrite; pick another id`);
   cpSync(src, dest, { recursive: true });
   const meta = JSON.parse(readFileSync(join(dest, 'game.json'), 'utf8'));
   meta.id = id;