@homie-rocks/studio 0.13.0 → 0.14.0

package/README.md

@@ -23,6 +23,32 @@ npx homie-studio office                                 # who is playing now, in
 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
@@ -39,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.
@@ -73,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.13.0 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.13.0 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
 ```
 
@@ -203,7 +230,7 @@ device; the owner's own passkey account (`homie-studio players owner`) counts as
 ## Setup status
 
 ```sh
-npx -y @homie-rocks/studio@0.13.0 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
@@ -75,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)
@@ -83,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
@@ -123,6 +134,9 @@ 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();
@@ -142,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) {
@@ -271,6 +285,12 @@ function print(result) {
     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}%)` : ''}`,
@@ -370,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') });
@@ -386,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;
@@ -469,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>' };
@@ -620,7 +647,7 @@ 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);

package/lib/cloudflare.mjs

@@ -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}`)) {

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');
+}

package/lib/files.mjs

@@ -0,0 +1,154 @@
+/**
+ * THE STUDIO'S FILES, FOR THE LOCAL MCP SERVER (lib/mcp.mjs). The Claude desktop app's chat has no file tools of its
+ * own, so the server gives it these, and only inside ONE studio folder: list, read, write, edit and search. A path
+ * is relative to the studio; nothing outside it is ever read or written (a symbolic link that leads out is refused
+ * too). Secrets never pass: .env and .dev.vars files and the progress feeds' write keys are neither read nor
+ * written, and git's own folder and node_modules are never written.
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+
+export const FILE_LIMITS = Object.freeze({ write: 2 * 1024 * 1024, read: 400 * 1024, image: 1536 * 1024, lines: 2000, list: 600, matches: 200 });
+const IMAGES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' };
+const SKIP_DIRS = new Set(['node_modules', '.git', '.wrangler', '.studio', 'dist']);
+
+const inside = (base, p) => p === base || p.startsWith(base.endsWith(sep) ? base : `${base}${sep}`);
+
+function secret(rel) {
+  const parts = rel.split(/[\\/]/);
+  const name = parts[parts.length - 1];
+  return /^\.env(\..*)?$/.test(name) || name === '.dev.vars' || /\.key$/.test(name) && parts.includes('progress');
+}
+
+/** A path in the studio, checked: { abs, rel }. `write`: also refuse git's folder and node_modules. */
+export function studioPath(root, path, { write = false } = {}) {
+  const raw = String(path ?? '').trim() || '.';
+  if (raw.includes('\0')) throw new Error('that path has a NUL in it');
+  const base = realpathSync(root);
+  const abs = resolve(base, raw);
+  if (!inside(base, abs)) throw new Error(`${raw} is outside the studio (${base}); only the studio's own files are reachable`);
+  // The nearest existing folder on the way must also be inside (a symbolic link must not lead out).
+  let at = abs;
+  while (!existsSync(at)) at = dirname(at);
+  const real = realpathSync(at);
+  if (!inside(base, real)) throw new Error(`${raw} leads outside the studio through a link`);
+  const rel = relative(base, abs) || '.';
+  if (secret(rel)) throw new Error(`${rel} holds a secret: it is never read or written here`);
+  if (write) {
+    const top = rel.split(/[\\/]/)[0];
+    if (top === '.git' || rel.split(/[\\/]/).includes('node_modules')) throw new Error(`${rel} is git's or npm's own: never written by hand`);
+    if (rel === '.') throw new Error('name a file');
+  }
+  return { abs, rel, base };
+}
+
+export function listFiles(root, path = '.', { depth = 2 } = {}) {
+  const { abs, rel } = studioPath(root, path);
+  if (!existsSync(abs)) throw new Error(`${rel} does not exist`);
+  if (!statSync(abs).isDirectory()) throw new Error(`${rel} is a file (file_read reads it)`);
+  const out = [];
+  const walk = (dir, d) => {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => (b.isDirectory() - a.isDirectory()) || a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (out.length >= FILE_LIMITS.list) return;
+      if (e.name === '.DS_Store') continue;
+      const p = join(dir, e.name);
+      const r = relative(realpathSync(root), p);
+      if (secret(r)) continue;
+      if (e.isDirectory()) {
+        out.push({ path: `${r}/`, type: 'dir' });
+        if (d < depth && !SKIP_DIRS.has(e.name)) walk(p, d + 1);
+      } else {
+        let size = null;
+        try { size = lstatSync(p).size; } catch { /* gone */ }
+        out.push({ path: r, type: e.isSymbolicLink() ? 'link' : 'file', size });
+      }
+    }
+  };
+  walk(abs, 1);
+  return { path: rel, entries: out, truncated: out.length >= FILE_LIMITS.list };
+}
+
+/** Text (with line numbers from `offset`), or a picture as MCP image content. */
+export function readStudioFile(root, path, { offset = 1, limit = FILE_LIMITS.lines } = {}) {
+  const { abs, rel } = studioPath(root, path);
+  if (!existsSync(abs)) throw new Error(`${rel} does not exist`);
+  const st = statSync(abs);
+  if (st.isDirectory()) throw new Error(`${rel} is a folder (file_list lists it)`);
+  const mime = IMAGES[extname(abs).toLowerCase()];
+  if (mime) {
+    if (st.size > FILE_LIMITS.image) throw new Error(`${rel} is ${Math.round(st.size / 1024)} KB, over the ${FILE_LIMITS.image / 1024} KB a picture may be here`);
+    return { rel, image: { mimeType: mime, data: readFileSync(abs).toString('base64') }, bytes: st.size };
+  }
+  if (st.size > FILE_LIMITS.read * 8) throw new Error(`${rel} is ${Math.round(st.size / 1024)} KB: too big to read here`);
+  const buf = readFileSync(abs);
+  if (buf.subarray(0, 8000).includes(0)) throw new Error(`${rel} is not a text file`);
+  const lines = buf.toString('utf8').split('\n');
+  const from = Math.max(1, Number(offset) || 1);
+  const n = Math.min(Math.max(1, Number(limit) || FILE_LIMITS.lines), FILE_LIMITS.lines);
+  let text = '';
+  let shown = 0;
+  for (let i = from - 1; i < lines.length && shown < n; i++, shown++) {
+    const line = `${String(i + 1).padStart(5)}\t${lines[i]}\n`;
+    if (text.length + line.length > FILE_LIMITS.read) break;
+    text += line;
+  }
+  return { rel, text, from, to: from + shown - 1, lines: lines.length, more: from + shown - 1 < lines.length };
+}
+
+export function writeStudioFile(root, path, content) {
+  const { abs, rel } = studioPath(root, path, { write: true });
+  const text = String(content ?? '');
+  if (Buffer.byteLength(text) > FILE_LIMITS.write) throw new Error(`at most ${FILE_LIMITS.write / 1024 / 1024} MB a file`);
+  if (existsSync(abs) && statSync(abs).isDirectory()) throw new Error(`${rel} is a folder`);
+  const existed = existsSync(abs);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, text);
+  return { rel, bytes: Buffer.byteLength(text), created: !existed };
+}
+
+export function editStudioFile(root, path, oldText, newText, { all = false } = {}) {
+  const { abs, rel } = studioPath(root, path, { write: true });
+  if (!existsSync(abs)) throw new Error(`${rel} does not exist (file_write makes a new file)`);
+  const was = readFileSync(abs, 'utf8');
+  const from = String(oldText ?? '');
+  if (!from) throw new Error('old is the exact text to replace (it cannot be empty)');
+  const count = was.split(from).length - 1;
+  if (!count) throw new Error(`the text to replace is not in ${rel} (it must match exactly, spaces and line breaks too)`);
+  if (count > 1 && !all) throw new Error(`the text to replace is in ${rel} ${count} times: give more of it so it is unique, or all: true`);
+  const next = all ? was.split(from).join(String(newText ?? '')) : was.replace(from, () => String(newText ?? ''));
+  if (Buffer.byteLength(next) > FILE_LIMITS.write) throw new Error(`at most ${FILE_LIMITS.write / 1024 / 1024} MB a file`);
+  writeFileSync(abs, next);
+  return { rel, replaced: all ? count : 1 };
+}
+
+/** Lines matching a regular expression, in the studio's text files (never node_modules, git, builds or .studio). */
+export function searchStudio(root, pattern, { path = '.', ignoreCase = false } = {}) {
+  let re;
+  try { re = new RegExp(String(pattern ?? ''), ignoreCase ? 'i' : ''); } catch (error) { throw new Error(`not a regular expression: ${error.message}`); }
+  const { abs } = studioPath(root, path);
+  const base = realpathSync(root);
+  const matches = [];
+  const walk = (dir) => {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (matches.length >= FILE_LIMITS.matches) return;
+      const p = join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(p); continue; }
+      if (!e.isFile() || IMAGES[extname(e.name).toLowerCase()]) continue;
+      const r = relative(base, p);
+      if (secret(r)) continue;
+      let buf;
+      try { if (statSync(p).size > 1024 * 1024) continue; buf = readFileSync(p); } catch { continue; }
+      if (buf.subarray(0, 8000).includes(0)) continue;
+      const lines = buf.toString('utf8').split('\n');
+      for (let i = 0; i < lines.length && matches.length < FILE_LIMITS.matches; i++) if (re.test(lines[i])) matches.push({ path: r, line: i + 1, text: lines[i].slice(0, 300) });
+    }
+  };
+  if (statSync(abs).isDirectory()) walk(abs);
+  else walk(dirname(abs));
+  return { pattern: String(pattern), matches, truncated: matches.length >= FILE_LIMITS.matches };
+}

package/lib/handoff.mjs

@@ -0,0 +1,128 @@
+/**
+ * `homie-studio handoff <hb_…>` — what a Claude Code session started from the Claude app does with the ONE line it
+ * was given ("Continue building <Studio>: build hb_…", HANDOFF.md in every studio):
+ *
+ *   1. fetch the brief the person gave in the chat from the directory (GET /api/studio/progress/<hb>/brief: the
+ *      build id is the read capability, and it is only ever shown in the person's own chat and that link);
+ *   2. for a build that belongs to a studio still being set up, check in from this repository (`setup attach`);
+ *   3. take the build once (`progress attach`), so the chat's card follows the work;
+ *   4. print the brief and the steps for its kind, in this toolkit's own commands.
+ *
+ * No key travels in a prompt, and no wall of text either. When this session's network does not reach the directory,
+ * it says so and names the other road: the Homie connector's build_progress, which answers with the same brief.
+ */
+import { request } from './net.mjs';
+import { startProgress } from './progress.mjs';
+import { spawnSync } from 'node:child_process';
+import { studioRepo } from './repo.mjs';
+
+/** The repository this checkout IS (its origin remote), even Homie's engine one: the session must be in the studio's. */
+function originRepo(root) {
+  const r = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: root, encoding: 'utf8', timeout: 5000 });
+  if (r.status !== 0) return null;
+  // Not repoFromUrl: that one never names the engine repository, and this must, to refuse it.
+  const m = /[/:]([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]{1,100})$/.exec(r.stdout.trim().replace(/\.git$/, '').replace(/\/+$/, ''));
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+import { setupAttach } from './setup.mjs';
+import { listGames, readStudio } from './studio.mjs';
+import { STUDIO_VERSION } from './version.mjs';
+
+const BUILD = /^hb_[a-f0-9]{32}$/;
+const SETUP = /^hs_[a-f0-9]{32}$/;
+
+const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const line = (v, max) => String(v ?? '').replace(/[\x00-\x1f\x7f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+const lines = (v, max) => String(v ?? '').split(/\r?\n/).map((l) => line(l, max)).filter(Boolean).join('\n').slice(0, max);
+
+/** The steps for a kind of build, in this toolkit's commands (the brief says what; these say how). */
+export function stepsFor(h, { games = [] } = {}) {
+  const id = ID.test(String(h.id ?? '')) ? h.id : null;
+  const has = id && games.includes(id);
+  const q = (s) => JSON.stringify(String(s));
+  const work = {
+    setup: [
+      'This studio was just set up from the Claude app. Go through the new-studio checklist with the person, one step at a time and never ahead (the plugin\'s studio-setup skill): it has no game yet, and its home page says "First game coming soon".',
+      'See a working game: `npx --no-install homie-studio demo` names a live one on Homie Arcade; copy a starter in only if they ask.',
+      'One small change from one sentence of theirs (the studio\'s colours in site/theme.json, a tagline in studio.json, or a first post in posts/), then plan their game into its Game Codex (`npx --no-install homie-studio codex new <id> --name "<Name>"`) before any game is made.',
+    ],
+    make: [
+      has ? `games/${id} is here already: change it as the brief says.` : id ? `npx --no-install homie-studio game new ${id} --from ${ID.test(String(h.from ?? '')) ? h.from : 'gem-rush'}${h.name ? ` --name ${q(line(h.name, 60))}` : ''}` : 'Pick an id and a name from the brief, then npx --no-install homie-studio game new <id> --from gem-rush --name "<Name>".',
+      'Make it the game the brief describes (its Game Codex, games/<id>/CODEX.md, when there is one).',
+    ],
+    port: [
+      `npx --no-install homie-studio port plan ${h.folder ? q(line(h.folder, 200)) : '<the game\'s folder>'}, then port import${id ? ` --id ${id}` : ''} (the plugin's port skill has the whole job).`,
+    ],
+    remix: [
+      h.source && id ? `npx --no-install homie-studio game remix ${line(h.source, 300)} --id ${id}` : 'npx --no-install homie-studio game remix <source.json> --id <new id>',
+      'Then make it the brief\'s own.',
+    ],
+    change: ['Make the change the brief asks for, in small steps.'],
+  }[h.kind] ?? ['Do what the brief asks.'];
+  return [
+    ...work,
+    'npm run build; npm run dev in the background; 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).',
+    '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.',
+  ];
+}
+
+export async function handoff(root, build, { homie, fetchFn = globalThis.fetch, attach = startProgress, checkIn = setupAttach, repoOf = originRepo } = {}) {
+  const studio = readStudio(root);
+  // "Continue building <Studio>: setup hs_…": a studio being set up, before any build: check in, then the checklist.
+  if (SETUP.test(String(build ?? ''))) {
+    const r = await checkIn(root, build, { homie });
+    if (!r.ok) return { ok: false, command: 'handoff', setup: build, why: r.why, ...(r.needs ? { needs: r.needs } : {}) };
+    const h = { kind: 'setup', what: 'game', title: 'first steps', studio: r.name ?? studio.name, brief: '', setup: build };
+    return { ok: true, command: 'handoff', build: null, ...h, setup: { ok: true, message: r.message, renamed: r.renamed ?? [] }, attached: null, attachWhy: 'no build was opened in the chat yet (the setup card\'s Start building opens one)', steps: stepsFor(h) };
+  }
+  if (!BUILD.test(String(build ?? ''))) return { ok: false, command: 'handoff', why: 'the id from the one line the Claude app gave: hb_ (a build) or hs_ (a setup) and 32 hex digits' };
+  const directory = String(homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  // lib/net.mjs: through the environment's proxy, and an honest reason when it fails (the directory's own words, or
+  // the connection's error; only a refusal by the proxy names the network setting).
+  const got = await request(`${directory}/api/studio/progress/${build}/brief`, { headers: { accept: 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION}` } }, { fetchFn });
+  const instead = `If the Homie connector's tools are in this session, call build_progress with { "build": "${build}" }: it answers with the brief. Otherwise ask the person what to build; the card in their chat shows it.`;
+  if (!got.ok) return { ok: false, command: 'handoff', build, why: got.why, ...(got.needs ? { needs: got.needs } : {}), ...(got.status === 404 ? {} : { instead }) };
+  const body = got.body ?? {};
+  // The build is for one repository: a session in any other stops here (claude.ai may open the person's last one).
+  const want = studioRepo(body.repo)?.toLowerCase() ?? null;
+  const here = want ? (repoOf(root) ?? null)?.toLowerCase() ?? null : null;
+  if (want && here && here !== want) return { ok: false, command: 'handoff', build, why: `this build is for ${body.repo}, but this session is in ${here}: open it in ${body.repo} (the card's Build it does), and change nothing here` };
+  const h = {
+    kind: ['make', 'port', 'remix', 'change', 'setup'].includes(body.kind) ? body.kind : 'change',
+    what: ['game', 'song', 'video'].includes(body.what) ? body.what : 'game',
+    title: line(body.title, 120), studio: line(body.studio, 60) || studio.name, brief: lines(body.brief, 1200),
+    id: ID.test(String(body.id ?? '')) ? body.id : null, name: line(body.name, 60) || null, from: ID.test(String(body.from ?? '')) ? body.from : null,
+    source: /^https:\/\/\S{8,300}$/.test(String(body.source ?? '')) ? body.source : null, folder: line(body.folder, 200) || null,
+    setup: /^hs_[a-f0-9]{32}$/.test(String(body.setup ?? '')) ? body.setup : null,
+  };
+  let setup = null;
+  if (h.setup) {
+    const r = await checkIn(root, h.setup, { homie: directory });
+    setup = { ok: r.ok, message: r.ok ? r.message : r.why, renamed: r.renamed ?? [] };
+  }
+  const taken = await attach(root, { attach: build, what: h.what, id: h.id, directory });
+  let games = [];
+  try { games = listGames(root).map((g) => g.id); } catch { games = []; }
+  return {
+    ok: true, command: 'handoff', build, ...h, setup,
+    attached: taken.ok ? { feed: taken.build, shared: taken.shared?.build ?? build } : null,
+    attachWhy: taken.ok ? null : taken.why,
+    steps: stepsFor(h, { games }),
+  };
+}
+
+/** The hand-off as the session reads it. */
+export function formatHandoff(r) {
+  return [
+    `Continue building ${r.studio}: ${r.title || r.kind}`,
+    '',
+    r.brief ? `The person's brief, from the chat:\n${r.brief.split('\n').map((l) => `  ${l}`).join('\n')}` : 'No brief beyond the title: ask the person one question if anything is unclear.',
+    '',
+    r.setup ? `Setup: ${r.setup.message}${r.setup.renamed?.length ? ` (changed: ${r.setup.renamed.join(', ')}; commit them on the branch)` : ''}` : null,
+    r.attached ? `This session took build ${r.build}: the chat's card follows the work.` : r.build ? `The chat's card will not follow this session: ${r.attachWhy}` : null,
+    '',
+    'Steps:',
+    ...r.steps.map((s, i) => `  ${i + 1}. ${s}`),
+  ].filter((l) => l !== null).join('\n');
+}