@homie-rocks/studio 0.13.0 → 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/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/)
@@ -27,7 +28,6 @@ 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). */
@@ -114,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
@@ -168,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,
@@ -245,6 +250,13 @@ studio's pinned copy, never a registry lookup of the bare name.
 - 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
@@ -280,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,
@@ -402,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',
@@ -425,29 +471,14 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     '.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. -->
@@ -469,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.
@@ -581,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/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;

package/lib/template-history.json

@@ -272,6 +272,33 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.14.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "e579cd6ce3ce342a",
+     "## The site": "7c1618431bae6324",
+     "## Making games": "63069b31c87a2aa2",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/lib/upgrade.mjs

@@ -31,7 +31,7 @@ import { readStudio } from './studio.mjs';
 import { STUDIO_VERSION, packageSpec } from './version.mjs';
 
 /** Whole files the template writes and a studio may keep as they are: updated only while the studio never changed them. */
-export const TEMPLATE_FILES = ['AGENTS.md', 'CLAUDE.md', 'README.md', 'games/README.md', 'music/README.md', 'videos/README.md', 'posts/README.md', 'site/README.md', 'site/src/worker.mjs'];
+export const TEMPLATE_FILES = ['AGENTS.md', 'CLAUDE.md', 'README.md', 'HANDOFF.md', 'games/README.md', 'music/README.md', 'videos/README.md', 'posts/README.md', 'site/README.md', 'site/src/worker.mjs'];
 /** Files the template adds when missing and never changes once they exist (a migration is applied; a manifest is the studio's). */
 export const ADD_ONLY = ['music/manifest.json', 'videos/manifest.json', '.claude/skills/.gitkeep'];
 const MIGRATIONS = /^site\/migrations\/[^/]+\.sql$/;

package/mcp/ui/bridge.js

@@ -0,0 +1,148 @@
+/*
+ * Homie's local cards: the MCP Apps bridge (spec 2026-01-26) every card shares. JSON-RPC 2.0 over postMessage
+ * with the host: ui/initialize, the tool's input and result, the host's theme, tools/call (the host proxies it to
+ * the local Homie server), ui/open-link for every link, ui/update-model-context to tell the model once, and the
+ * card's size. No network of its own; every text is set as text, never as HTML.
+ */
+var Card = (function () {
+  var seq = 0; var pending = {}; var ctx = {}; var caps = {};
+  var S = { result: null, data: null, timer: null, torn: false, visible: true, told: {}, busy: false };
+  var spec = null;
+  var root = document.getElementById('root');
+
+  function post(m) { window.parent.postMessage(m, '*'); }
+  function rpc(method, params) {
+    var id = ++seq;
+    post({ jsonrpc: '2.0', id: id, method: method, params: params || {} });
+    return new Promise(function (resolve, reject) {
+      pending[id] = { resolve: resolve, reject: reject };
+      setTimeout(function () { if (pending[id]) { delete pending[id]; reject(new Error('timeout')); } }, 65000);
+    });
+  }
+  function note(method, params) { post({ jsonrpc: '2.0', method: method, params: params || {} }); }
+  function el(tag, cls, text) { var e = document.createElement(tag); if (cls) e.className = cls; if (text !== undefined && text !== null) e.textContent = String(text); return e; }
+  function add(parent) { for (var i = 1; i < arguments.length; i++) { var k = arguments[i]; if (k) parent.appendChild(k); } return parent; }
+  function btn(label, cls, onclick) { var b = el('button', cls || '', label); b.type = 'button'; b.onclick = onclick; return b; }
+  function pill(text, cls, live) { var p = el('span', 'pill ' + (cls || '')); if (live) p.appendChild(el('span', 'dot')); p.appendChild(el('span', '', text)); return p; }
+  function top(label, right) { return add(el('div', 'top'), add(el('div', 'eyebrow'), el('span', 'mark'), el('span', '', 'Homie · ' + label)), right || null); }
+  function img(src, alt) {
+    if (typeof src !== 'string' || !/^data:image\/(png|jpeg|webp|gif);base64,/.test(src)) return null;
+    var i = el('img'); i.alt = alt || ''; i.decoding = 'async'; i.src = src; i.onerror = function () { i.remove(); size(); };
+    return i;
+  }
+  function open(url) { if (typeof url === 'string' && /^https?:\/\//.test(url)) rpc('ui/open-link', { url: url }).catch(function () {}); }
+  function call(name, args) { return rpc('tools/call', { name: name, arguments: args || {} }); }
+  function tell(key, text) {
+    if (S.told[key]) return; S.told[key] = true;
+    rpc('ui/update-model-context', { content: [{ type: 'text', text: text }] }).catch(function () {});
+  }
+  function ago(iso) {
+    var t = Date.parse(iso || ''); if (!isFinite(t)) return '';
+    var s = Math.max(0, Math.round((Date.now() - t) / 1000));
+    return s < 5 ? 'just now' : s < 60 ? s + ' s ago' : s < 3600 ? Math.round(s / 60) + ' min ago' : Math.round(s / 3600) + ' h ago';
+  }
+  function dur(ms) { if (!(ms >= 0)) return ''; var s = Math.round(ms / 1000); return s < 60 ? s + ' s' : Math.floor(s / 60) + ':' + String(s % 60).padStart(2, '0'); }
+  // As the ext-apps SDK measures: the content's own height (html at max-content) and the frame's width, once a
+  // frame, only when either changed.
+  var sized = { w: 0, h: 0, queued: false };
+  function size() {
+    if (sized.queued) return; sized.queued = true;
+    requestAnimationFrame(function () {
+      sized.queued = false;
+      var html = document.documentElement; var was = html.style.height;
+      html.style.height = 'max-content';
+      var h = Math.ceil(html.getBoundingClientRect().height);
+      html.style.height = was;
+      var w = Math.ceil(window.innerWidth);
+      if (w === sized.w && h === sized.h) return;
+      sized.w = w; sized.h = h;
+      note('ui/notifications/size-changed', { width: w, height: h });
+    });
+  }
+  function theme(c) {
+    if (!c) return;
+    if (c.theme === 'light' || c.theme === 'dark') { document.documentElement.setAttribute('data-theme', c.theme); document.documentElement.style.colorScheme = c.theme; }
+    var v = c.styles && c.styles.variables;
+    if (v) for (var k in v) if (v[k] !== undefined && /^--[a-z0-9-]+$/.test(k)) document.documentElement.style.setProperty(k, v[k]);
+    if (c.styles && c.styles.css && c.styles.css.fonts && !document.getElementById('host-fonts')) { var st = el('style'); st.id = 'host-fonts'; st.textContent = c.styles.css.fonts; document.head.appendChild(st); }
+  }
+  function fullscreenButton() {
+    var modes = (ctx && ctx.availableDisplayModes) || [];
+    if (modes.indexOf('fullscreen') < 0) return null;
+    var full = ctx.displayMode === 'fullscreen';
+    return btn(full ? 'Smaller' : 'Full screen', 'ghost small', function () {
+      rpc('ui/request-display-mode', { mode: full ? 'inline' : 'fullscreen' }).then(function (r) { ctx.displayMode = r && r.mode; render(); }).catch(function () {});
+    });
+  }
+  function textOf(r) { return (r && r.content && r.content[0] && r.content[0].text) || ''; }
+  function render() {
+    if (!spec) return;
+    var card;
+    if (!S.data) {
+      card = el('main', 'card');
+      if (S.result && S.result.isError) add(card, top(spec.label, pill('Not done', 'bad')), el('p', 'note bad', textOf(S.result) || 'That did not work.'));
+      else add(card, top(spec.label, pill('Loading', 'live', true)), el('div', 'skel'), el('div', 'skel'));
+    } else {
+      try { card = spec.render(S.data, S.result); } catch (e) { card = add(el('main', 'card'), top(spec.label), el('p', 'note bad', String(e && e.message || e))); }
+      if (S.result && S.result.isError && S.data) card.appendChild(el('p', 'note bad', textOf(S.result)));
+    }
+    card.id = 'root';
+    if (ctx.displayMode === 'fullscreen') card.classList.add('full');
+    root.replaceWith(card); root = card; size();
+  }
+  function take(result) {
+    S.result = result;
+    if (result && result.structuredContent && result.structuredContent.kind === spec.kind) S.data = result.structuredContent;
+    render();
+    schedule();
+  }
+  function schedule() {
+    if (S.timer) { clearTimeout(S.timer); S.timer = null; }
+    if (S.torn || !spec.poll || !S.data) return;
+    var p = spec.poll(S.data);
+    if (!p) return;
+    S.timer = setTimeout(function () {
+      S.timer = null;
+      if (!S.visible) { schedule(); return; }
+      call(p.tool, p.args).then(function (r) { if (r && r.structuredContent && r.structuredContent.kind === spec.kind) take(r); else schedule(); })
+        .catch(function () { schedule(); });
+    }, p.every || 2000);
+  }
+  document.addEventListener('visibilitychange', function () { S.visible = !document.hidden; });
+  window.addEventListener('resize', size);
+  window.addEventListener('message', function (ev) {
+    if (ev.source !== window.parent) return;
+    var m = ev.data; if (!m || m.jsonrpc !== '2.0') return;
+    if (m.id !== undefined && m.id !== null && !m.method) {
+      var p = pending[m.id]; if (!p) return; delete pending[m.id];
+      if (m.error) p.reject(m.error); else p.resolve(m.result);
+      return;
+    }
+    if (m.method === 'ui/notifications/tool-input') { if (!S.result) render(); }
+    else if (m.method === 'ui/notifications/tool-result') take(m.params);
+    else if (m.method === 'ui/notifications/tool-cancelled') { if (!S.result) { S.result = { isError: true, content: [{ type: 'text', text: 'Cancelled.' }] }; render(); } }
+    else if (m.method === 'ui/notifications/host-context-changed') { for (var k in m.params || {}) ctx[k] = m.params[k]; theme(m.params); render(); }
+    else if (m.method === 'ui/resource-teardown') { S.torn = true; if (S.timer) clearTimeout(S.timer); if (m.id !== undefined) post({ jsonrpc: '2.0', id: m.id, result: {} }); }
+    else if (m.method === 'ping' && m.id !== undefined) post({ jsonrpc: '2.0', id: m.id, result: {} });
+  });
+
+  return {
+    el: el, add: add, btn: btn, pill: pill, top: top, img: img, open: open, call: call, tell: tell, ago: ago, dur: dur,
+    size: size, render: render, take: take, fullscreenButton: fullscreenButton, textOf: textOf,
+    ctx: function () { return ctx; },
+    state: S,
+    /** spec: { kind, label, render(data, result) -> element, poll(data) -> { tool, args, every } | null } */
+    start: function (s) {
+      spec = s;
+      rpc('ui/initialize', {
+        protocolVersion: '2026-01-26',
+        appInfo: { name: 'homie-studio-' + s.kind + '-card', version: '1' },
+        appCapabilities: { availableDisplayModes: s.fullscreen ? ['inline', 'fullscreen'] : ['inline'] },
+      }).then(function (res) {
+        caps = (res && res.hostCapabilities) || {}; ctx = (res && res.hostContext) || {};
+        theme(ctx); note('ui/notifications/initialized', {}); render();
+      }).catch(function () { note('ui/notifications/initialized', {}); render(); });
+      void caps;
+    },
+  };
+})();

package/mcp/ui/build.js

@@ -0,0 +1,63 @@
+/* The build card: one build's stages, each check going green, a picture and where to play it, money against the
+ * budget, and Stop. It follows the build every 2 s while it runs and tells the model once when it ends. */
+(function () {
+  var C = Card;
+  var ICON = { pass: '✓', done: '✓', fail: '✕', failed: '✕', running: '●', pending: '·', skip: '–', skipped: '–', stopped: '■' };
+  var STATE = { running: ['Running', 'live', true], passed: ['Done', 'ok'], failed: ['Failed', 'bad'], stopped: ['Stopped', ''] };
+  function money(n, unit) { return unit === 'credits' ? Math.round(n).toLocaleString('en-US') + ' credits' : '$' + Number(n || 0).toFixed(2); }
+  function render(sc) {
+    var f = sc.feed; var card = C.el('main', 'card');
+    var st = STATE[f.state] || ['…', ''];
+    C.add(card, C.top('Build', C.add(C.el('div', 'actions'), C.pill(st[0], st[1], st[2]), C.fullscreenButton())), C.el('h1', '', f.title || 'A build'),
+      C.el('p', 'sub', [f.studio, f.what === 'game' ? null : f.what, f.state === 'running' ? 'started ' + C.ago(f.startedAt) : f.endedAt ? 'took ' + C.dur(Date.parse(f.endedAt) - Date.parse(f.startedAt)) : null].filter(Boolean).join(' · ')));
+    var stages = C.el('div', 'stages');
+    (f.stages || []).forEach(function (s) { stages.appendChild(C.add(C.el('div', 'stage ' + s.state), C.el('div', 'bar'), C.el('span', '', (ICON[s.state] && s.state !== 'pending' ? ICON[s.state] + ' ' : '') + s.label))); });
+    card.appendChild(stages);
+    var cur = (f.stages || []).filter(function (s) { return s.note && s.state !== 'pending'; }).pop();
+    if (cur) card.appendChild(C.el('p', 'fine', cur.label + ': ' + cur.note));
+    if ((f.checks || []).length) {
+      var list = C.el('div');
+      f.checks.forEach(function (c) { list.appendChild(C.add(C.el('div', 'check ' + c.state), C.el('span', 'i', ICON[c.state] || '·'), C.el('span', '', c.label + (c.note ? ' — ' + c.note : '')), c.ms ? C.el('span', 'n', C.dur(c.ms)) : null)); });
+      card.appendChild(list);
+    }
+    var p = f.preview;
+    if (p && (p.image || p.url)) {
+      var box = C.el('div', 'preview');
+      var pic = C.img(p.image, p.caption || 'The game');
+      if (pic) box.appendChild(pic);
+      if (p.caption) box.appendChild(C.el('span', 'fine', p.caption));
+      card.appendChild(box);
+    }
+    if (f.spend && (f.spend.used > 0 || f.spend.budget !== null)) card.appendChild(C.el('p', 'fine', 'Spent ' + money(f.spend.used, f.spend.unit) + (f.spend.budget !== null ? ' of ' + money(f.spend.budget, f.spend.unit) : '')));
+    if (f.error) card.appendChild(C.el('p', 'note bad', f.error));
+    var failed = (sc.jobs || []).filter(function (j) { return j.state === 'failed'; });
+    if (failed.length && !f.error) card.appendChild(C.el('pre', 'log', failed.map(function (j) { return j.label + ': ' + ((j.result && j.result.why) || (j.tail || []).slice(-3).join('\n')); }).join('\n')));
+    else if ((f.log || []).length && f.state === 'running') card.appendChild(C.el('pre', 'log', f.log.slice(-3).map(function (l) { return l.text; }).join('\n')));
+    var foot = C.el('div', 'foot');
+    foot.appendChild(C.el('span', 'when', f.state === 'running' ? 'Updated ' + C.ago(f.updatedAt) : 'Ended ' + C.ago(f.endedAt)));
+    var acts = C.el('div', 'actions');
+    if (f.state === 'running' && !(f.stop && f.stop.requested)) {
+      acts.appendChild(C.btn(C.state.stopping ? 'Stopping…' : 'Stop', 'danger small', function () {
+        if (C.state.stopping) return; C.state.stopping = true; C.render();
+        C.call('build_stop', { build: sc.build }).then(function (r) { C.state.stopping = false; C.take(r); }).catch(function () { C.state.stopping = false; C.render(); });
+      }));
+    } else if (f.stop && f.stop.requested && f.state === 'running') acts.appendChild(C.pill('Stopping at the next safe point', 'warn'));
+    if (p && p.url && /^https?:/.test(p.url)) acts.appendChild(C.btn('Play it', f.state === 'passed' ? '' : 'ghost small', function () { C.open(p.url); }));
+    foot.appendChild(acts);
+    card.appendChild(foot);
+    var r = sc.run;
+    if (r && r.state !== 'running' && f.state === 'running') {
+      card.insertBefore(C.el('p', 'note' + (r.state === 'failed' ? ' bad' : ' ok'), (r.state === 'passed' ? '✓ ' : '') + r.title + ': ' + (r.state === 'passed' ? 'passed' : 'failed' + (r.why ? ' — ' + r.why : ''))), foot);
+      C.tell('run-' + sc.build + '-' + r.kind, r.title + ' ' + r.state + (r.why ? ': ' + r.why : '') + ' (build ' + sc.build + ' stays open).');
+    }
+    if (f.state !== 'running') {
+      var passed = (f.checks || []).filter(function (c) { return c.state === 'pass'; }).length;
+      C.tell('end-' + sc.build, 'Build ' + sc.build + ' (' + f.title + ') ended: ' + f.state + (f.checks && f.checks.length ? ', ' + passed + ' of ' + f.checks.length + ' checks passed' : '') + (f.error ? '. Error: ' + f.error : '') + (p && p.url ? '. Play: ' + p.url : '') + '. Tell the person in a line or two.');
+    }
+    return card;
+  }
+  C.start({
+    kind: 'build', label: 'Build', fullscreen: true, render: render,
+    poll: function (sc) { return sc.feed && sc.feed.state === 'running' ? { tool: 'build_progress', args: { build: sc.build }, every: 2000 } : null; },
+  });
+})();