@homie-rocks/studio 0.9.0 → 0.11.0

package/lib/progress.mjs

@@ -19,6 +19,10 @@
  * knows (the plan, money spent, a song's lyric check, a video's shots) with the other `progress` commands.
  * WITHOUT AN OPEN FEED NOTHING CHANGES: every command behaves exactly as before.
  *
+ * WHERE A PERSON SEES IT: the Claude app's build card (shared feeds), the Build status tab of the game's codex page
+ * (lib/codex.mjs: it redraws itself at every change), and Claude Code's status line (lib/statusline.mjs), all read
+ * through lib/feed-summary.mjs so they agree.
+ *
  * SHARED (`progress start --share`): the directory named in studio.json (homie.rocks by default) keeps a copy for
  * 24 hours, so the Homie MCP tool `build_progress { build }` can show it in the Claude app, and answers every
  * write with whether the person pressed Stop there. It receives the feed and nothing else: never a key, a file
@@ -34,12 +38,25 @@
  *     stop: { requested, at, by },
  *     song?: { peaks: [0..1], lyrics: [{ line, sung: true|false|null }] },
  *     video?: { shots: [{ id, label, state, image }] },
+ *     change?: { url, number, title, repo, branch, state: open|merged|closed, files, additions, deletions, preview, mark, at },
+ *     site?: the studio's live address (for the Claude app's card to tell when a merged change is live),
  *     log: [{ at, text }], error, shared?: { build, directory } }
+ *
+ * A BUILD OPENED IN THE CHAT (`build_open`, the Claude app's "Build it" card): the chat gets the build id first
+ * and shows its card; the Claude Code session that does the work attaches to it ONCE with
+ * `progress attach <hb_…>`, and the directory hands the write key to that first attach only. No key ever travels
+ * in a prompt; a second attach is refused.
+ *
+ * A CHANGE THAT GOES OUT AS A PULL REQUEST: `progress change "<what it does>"` writes changes/<date>-<mark>.json
+ * (committed with the change; the site lists the newest marks in its manifest), and `progress pr --url <pr>` puts
+ * the pull request on the card, whose Publish button opens it in GitHub for the person's one-tap merge. When the
+ * live site lists the change's mark, Workers Builds has deployed it: the card says Live by itself.
  */
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { extname, join } from 'node:path';
-import { readStudio } from './studio.mjs';
+import { refreshCodexFile } from './codex.mjs';
+import { readStudio, siteUrl } from './studio.mjs';
 
 export const PROGRESS_KIND = 'homie-studio-progress';
 export const PROGRESS_DIR = join('.studio', 'progress');
@@ -72,6 +89,28 @@ const keyPath = (root, id) => join(dir(root), `${id}.key`);
 const currentPath = (root) => join(dir(root), 'current');
 const loopback = (url) => { try { return ['127.0.0.1', 'localhost', '[::1]'].includes(new URL(url).hostname); } catch { return false; } };
 
+/*
+ * A CLAUDE CODE CLOUD SESSION ON THE DEFAULT NETWORK. Its "Trusted" network reaches package registries and GitHub,
+ * not homie.rocks: the session's proxy answers 403 with `x-deny-reason: host_not_allowed`. Say which setting lets
+ * the card follow the build, instead of "did not answer"; the build itself goes on with its local feed.
+ */
+export function networkWhy(res, at) {
+  if (res?.status === 403 && /host_not_allowed/i.test(res.headers?.get?.('x-deny-reason') ?? '')) {
+    let host = at;
+    try { host = new URL(at).host; } catch { /* as given */ }
+    return `this Claude Code cloud environment's network does not reach ${host}. In claude.ai/code, open the environment's settings, set Network access to Custom, add ${host} (keep "Also include default list of common package managers"), and start a new session; until then the build goes on with its local feed only`;
+  }
+  return null;
+}
+
+/** The studio's live address for the card: an https origin (or this computer's own dev site), else null. */
+export function liveSite(url) {
+  try { const u = new URL(String(url ?? '')); return u.protocol === 'https:' || (u.protocol === 'http:' && loopback(u.href)) ? u.origin : null; } catch { return null; }
+}
+
+/** A change's mark: what the site lists once the change is live. It names the build without being able to read it. */
+export const changeMark = (build) => createHash('sha256').update(`homie-change\n${build}`).digest('hex').slice(0, 16);
+
 function writeAtomic(file, text) {
   const tmp = `${file}.${process.pid}.${randomBytes(3).toString('hex')}.tmp`;
   writeFileSync(tmp, text);
@@ -120,6 +159,11 @@ async function pushDoc(root, id) {
     body: JSON.stringify({ ...body, build: shared.build }),
     signal: AbortSignal.timeout(8000),
   });
+  const blocked = networkWhy(res, shared.directory);
+  if (blocked) {
+    mutateDoc(root, id, (d) => { d.shared = { ...d.shared, ended: true }; pushLog(d, `The Claude app cannot follow this build: ${blocked}`); });
+    return null;
+  }
   if (res.status === 404 || res.status === 410) {
     // The shared copy ended (24 hours, or the directory dropped it): keep the local feed, stop sending.
     mutateDoc(root, id, (d) => { d.shared = { ...d.shared, ended: true }; });
@@ -206,6 +250,8 @@ export class Feed {
   change(fn, { soon = false } = {}) {
     const d = mutateDoc(this.root, this.id, fn);
     if (d) schedule(this.root, this.id, { soon });
+    // The game's codex page on this computer (.studio/codex/<id>.html), when there is one, shows the change too.
+    if (d?.what === 'game' && d.id) refreshCodexFile(this.root, d.id);
     return d;
   }
 
@@ -309,6 +355,33 @@ export class Feed {
     });
   }
 
+  /** The pull request this build's change went out as: the card's Publish button opens it for the person's merge. */
+  pr({ url, number, title, repo, branch, state = 'open', files, additions, deletions, preview, site } = {}) {
+    let u;
+    try { u = new URL(String(url ?? '')); } catch { throw new Error('--url is the pull request\'s https://github.com/<owner>/<repo>/pull/<n> address'); }
+    const m = /^\/([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100})\/pull\/(\d{1,7})\/?$/.exec(u.pathname);
+    if (u.protocol !== 'https:' || u.hostname !== 'github.com' || !m) throw new Error('--url is the pull request\'s https://github.com/<owner>/<repo>/pull/<n> address');
+    if (!['open', 'merged', 'closed'].includes(state)) throw new Error('a pull request is open, merged or closed');
+    const count = (n) => (n === undefined || n === null || n === true ? null : Number.isFinite(Number(n)) && Number(n) >= 0 ? Math.round(Number(n)) : null);
+    return this.change((doc) => {
+      const before = doc.change ?? {};
+      doc.change = {
+        url: `https://github.com/${m[1]}/${m[2]}/pull/${m[3]}`, number: Number(m[3]), repo: `${m[1]}/${m[2]}`,
+        title: plain(title ?? before.title ?? doc.title, LIMITS.title), branch: branch ? plain(branch, 100) : before.branch ?? null, state,
+        files: count(files) ?? before.files ?? null, additions: count(additions) ?? before.additions ?? null, deletions: count(deletions) ?? before.deletions ?? null,
+        preview: preview ? String(preview).slice(0, 300) : before.preview ?? null, mark: before.mark ?? null, at: now(),
+      };
+      // The live address may have been learned after the build was opened (`setup attach`): the card reads it.
+      if (liveSite(site)) doc.site = liveSite(site);
+      const deploy = doc.stages.find((s) => s.id === 'deploy' || s.id === 'publish');
+      if (deploy && state === 'open' && deploy.state === 'pending') { deploy.state = 'running'; deploy.startedAt = now(); deploy.note = 'Waiting for the merge: Publish on the card opens the pull request'; doc.stage = deploy.id; }
+      pushLog(doc, `Pull request #${m[3]} ${state}`);
+    }, { soon: true });
+  }
+
+  /** The studio's live address, so the card can read the site's own manifest for the change once it is merged. */
+  site(url) { return this.change((doc) => { doc.site = url ? String(url).slice(0, 200) : null; }); }
+
   stopRequested() { return Boolean(this.doc?.stop?.requested); }
 
   /**
@@ -362,7 +435,9 @@ export function publicFeed(doc) {
  * Open a feed for one build. `share` asks the studio's directory (studio.json `homie.directory`, or `directory`)
  * to keep a copy for the Claude app's widget; if it cannot, the build goes on with the local feed only.
  */
-export async function startProgress(root, { what = 'game', id, title, budget, unit, share = false, directory } = {}) {
+export async function startProgress(root, { what = 'game', id, title, budget, unit, share = false, directory, attach = null } = {}) {
+  if (attach !== null && !REMOTE_ID.test(String(attach))) return { ok: false, command: 'progress attach', why: 'attach to the build id the Claude app showed: hb_ and 32 hex digits' };
+  if (attach) share = true;
   if (!STAGES[what]) return { ok: false, command: 'progress start', why: `what is being made: ${Object.keys(STAGES).join(', ')}` };
   if (id !== undefined && id !== null && !SLUG.test(String(id))) return { ok: false, command: 'progress start', why: 'the id is the game, song or video id (lowercase letters, digits and hyphens)' };
   const studio = readStudio(root);
@@ -384,6 +459,9 @@ export async function startProgress(root, { what = 'game', id, title, budget, un
     log: [{ at: now(), text: `Started: ${plain(title || id || what, 100)}` }],
     error: null,
   };
+  let live = null;
+  try { live = siteUrl(root, studio); } catch { live = null; }
+  if (liveSite(live)) doc.site = liveSite(live);
   mkdirSync(dir(root), { recursive: true });
   writeAtomic(docPath(root, build), `${JSON.stringify(doc, null, 1)}\n`);
   writeAtomic(currentPath(root), `${build}\n`);
@@ -394,12 +472,16 @@ export async function startProgress(root, { what = 'game', id, title, budget, un
     if (!/^https:\/\//.test(at) && !(/^http:\/\//.test(at) && loopback(at))) why = `the directory ${at} is not https`;
     else {
       try {
-        const res = await fetch(`${at}/api/studio/progress`, {
+        // A build the chat opened is attached (once); otherwise a new one is opened here.
+        const res = await fetch(attach ? `${at}/api/studio/progress/${attach}/attach` : `${at}/api/studio/progress`, {
           method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': 'homie-studio' },
           body: JSON.stringify({ what, id: id ?? null, title: doc.title, studio: doc.studio }), signal: AbortSignal.timeout(10_000),
         });
         const body = await res.json().catch(() => null);
-        if (res.ok && body?.ok && REMOTE_ID.test(String(body.build)) && /^hbk_[a-f0-9]{48}$/.test(String(body.key))) {
+        if (!res.ok && networkWhy(res, at)) why = networkWhy(res, at);
+        else if (res.ok && body?.ok && REMOTE_ID.test(String(body.build)) && /^hbk_[a-f0-9]{48}$/.test(String(body.key))) {
+          // The chat named the build: its title is the one the person saw.
+          if (attach && body.title && !title) mutateDoc(root, build, (d) => { d.title = plain(body.title, LIMITS.title); });
           writeFileSync(keyPath(root, build), `${body.key}\n`, { mode: 0o600 });
           try { chmodSync(keyPath(root, build), 0o600); } catch { /* not on this filesystem */ }
           shared = { build: body.build, directory: at, expiresAt: body.expiresAt ?? null };
@@ -410,11 +492,45 @@ export async function startProgress(root, { what = 'game', id, title, budget, un
       } catch (error) { why = `${at} did not answer (${error?.message ?? error})`; }
     }
   }
+  if (attach && !shared) {
+    // Attaching is the point of `progress attach`: without it, say why and leave no open feed behind.
+    rmSync(docPath(root, build), { force: true });
+    rmSync(currentPath(root), { force: true });
+    return { ok: false, command: 'progress attach', build: attach, why: `could not attach to ${attach}: ${why}` };
+  }
   return {
-    ok: true, command: 'progress start', build, file: join(PROGRESS_DIR, `${build}.json`), what, id: id ?? null, title: doc.title,
+    ok: true, command: attach ? 'progress attach' : 'progress start', build, file: join(PROGRESS_DIR, `${build}.json`), what, id: id ?? null, title: readFeed(root, build)?.title ?? doc.title,
     stages: doc.stages.map((s) => s.id), budget: doc.spend.budget, unit: doc.spend.unit,
     shared: shared ? { build: shared.build, directory: shared.directory, expiresAt: shared.expiresAt } : null,
     ...(share && !shared ? { sharedWhy: `not shared: ${why}; the feed is local only` } : {}),
     widget: shared ? `In the Claude app: call the Homie MCP tool build_progress with { "build": "${shared.build}" }` : null,
   };
 }
+
+/**
+ * `progress change "<what it does>"`: the change's mark, as a small file the change commits (changes/<date>-<mark>.json).
+ * `homie-studio build` lists the newest marks in the site's manifest; when the live site lists this one, the change
+ * is deployed, and the Claude app's card says so. Returns the file, relative to the studio.
+ */
+export function recordChange(root, id, title) {
+  const doc = readFeed(root, id);
+  if (!doc) throw new Error('no build is open: start or attach one first');
+  const mark = changeMark(doc.shared?.build ?? doc.build);
+  const folder = join(root, 'changes');
+  mkdirSync(folder, { recursive: true });
+  if (!existsSync(join(folder, 'README.md'))) writeFileSync(join(folder, 'README.md'), CHANGES_README);
+  const rel = join('changes', `${now().slice(0, 10)}-${mark.slice(0, 8)}.json`);
+  const text = `${JSON.stringify({ v: 1, change: mark, title: plain(title || doc.title, LIMITS.title), at: now() }, null, 2)}\n`;
+  writeFileSync(join(root, rel), text);
+  mutateDoc(root, id, (d) => { d.change = { ...(d.change ?? {}), mark }; pushLog(d, `Change recorded: ${plain(title || doc.title, 100)}`); });
+  schedule(root, id, { soon: true });
+  return { file: rel, mark };
+}
+
+export const CHANGES_README = `# changes/
+
+One small file per change this studio made through a pull request, written by \`homie-studio progress change\`:
+what it does, when, and its mark. \`npm run build\` lists the newest marks in the site's
+\`/.well-known/homie-studio.json\`, so the Claude app's card can tell when a merged change is live. Nothing in
+here is secret; old files may be deleted.
+`;

package/lib/scaffold.mjs

@@ -25,40 +25,66 @@ 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 { themeFile } from './site.mjs';
+import { PACKAGE_ROOT } from './studio.mjs';
 
 export const COMPAT_DATE = '2026-06-01';
-export const WRANGLER_VERSION = '4.126.0';
+/** 4.135.0 or later: Worker Previews (`wrangler preview`, a Durable Object namespace per Preview). */
+export const WRANGLER_VERSION = '4.145.0';
 
 export function slugify(name) {
   return String(name ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
     .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '') || 'studio';
 }
 
-/** The Worker config, generated so a later deploy can rewrite exactly what it owns. */
-export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null }) {
+/*
+ * The Worker config, generated so a later deploy can rewrite exactly what it owns.
+ *
+ * `layout: 'root'` (every studio from 0.10.0) keeps it at the studio's root, where Cloudflare's Workers Builds and
+ * the "Deploy to Cloudflare" button look for it; `'site'` is the older site/wrangler.jsonc.
+ *
+ * PREVIEWS (Cloudflare Worker Previews, Wrangler 4.135.0+): a branch deploys with `npx wrangler preview` (Workers
+ * Builds does it on every push that is not to the production branch) to its own URL, and Cloudflare gives every
+ * Preview its OWN Durable Object namespace, so a Preview's public rooms never meet production's. The `previews`
+ * block binds the same Table and Lobby classes and names the Preview (HOMIE_PREVIEW). It binds no D1 on purpose:
+ * a Preview counts nothing into the studio's stats, records no rounds and never claims itself in the directory;
+ * its pages and rooms work without it.
+ *
+ * No `database_id` until one is known: Wrangler (4.45.0+) and the Deploy to Cloudflare flow create the database
+ * the binding names and keep it linked.
+ */
+export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root' }) {
+  const at = layout === 'site' ? { schema: '../node_modules', main: 'src/worker.mjs', dist: './dist', migrations: 'migrations' }
+    : { schema: 'node_modules', main: 'site/src/worker.mjs', dist: './site/dist', migrations: 'site/migrations' };
+  const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }];
   const config = {
-    $schema: '../node_modules/wrangler/config-schema.json',
+    $schema: `${at.schema}/wrangler/config-schema.json`,
     name: worker,
-    main: 'src/worker.mjs',
+    main: at.main,
     compatibility_date: COMPAT_DATE,
+    // The site's own fetches (its directory claim, "played this week") go out as any browser's would, so a studio
+    // whose directory is on the same zone (a house studio on *.homie.rocks, or two Workers on one workers.dev
+    // subdomain) reaches it instead of failing with 1042.
+    compatibility_flags: ['global_fetch_strictly_public'],
     workers_dev: true,
-    preview_urls: false,
-    assets: { directory: './dist', binding: 'ASSETS', run_worker_first: true },
-    durable_objects: { bindings: [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }] },
+    preview_urls: true,
+    assets: { directory: at.dist, binding: 'ASSETS', run_worker_first: true },
+    durable_objects: { bindings: rooms },
     migrations: [{ tag: 'v1', new_sqlite_classes: ['Table', 'Lobby'] }],
-    d1_databases: [{ binding: 'DB', database_name: d1, ...(d1Id ? { database_id: d1Id } : {}), migrations_dir: 'migrations' }],
+    d1_databases: [{ binding: 'DB', database_name: d1, ...(d1Id ? { database_id: d1Id } : {}), migrations_dir: at.migrations }],
     ...(r2 ? { r2_buckets: [{ binding: 'MEDIA', bucket_name: r2 }] } : {}),
     vars: { STUDIO_NAME: name },
     observability: { enabled: true },
+    previews: { vars: { STUDIO_NAME: name, HOMIE_PREVIEW: '1' }, durable_objects: { bindings: rooms } },
   };
-  return `// This studio's site on its own Cloudflare account (written by homie-studio; \`homie-studio deploy\`
-// fills in the D1 id). Everything here runs on Cloudflare's Workers Free plan. There is no R2 binding
+  return `// This studio's site on its own Cloudflare account (written by homie-studio). Everything here runs on
+// Cloudflare's Workers Free plan. \`npm run deploy\` (on this computer, or in Workers Builds) puts it live;
+// \`npx wrangler preview\` puts a branch on its own Preview URL with its own rooms. There is no R2 binding
 // until \`homie-studio storage add\` gives the studio storage for large media.
 ${JSON.stringify(config, null, 2)}
 `;
 }
 
-function agentsMd({ name, slug }) {
+export function agentsMd({ name, slug }) {
   return `# ${name}
 
 This folder is a studio: **${name}** (\`${slug}\`). It is one repository.
@@ -75,7 +101,9 @@ directory lists its games; homie.rocks does not host them.
 | \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`. |
 | \`music/\`, \`videos/\` | Songs, scores, loops; trailers, music videos, cutscenes. \`manifest.json\` lists each one (\`node_modules/@homie-rocks/studio/media/MEDIA.md\`); a published entry gets a page at \`/music/<slug>/\` or \`/videos/<slug>/\`, served from the site itself (files up to 25 MiB) or, for larger media, from the studio's storage once it has storage (see below; \`npx --no-install homie-studio media put <file>\`). Large files never go into git. The Homie plugin's \`music\` and \`video\` skills make them. |
 | \`posts/\` | The studio's news and drops: one markdown file each (\`posts/2026-09-30-we-are-live.md\`: \`title:\`, \`date:\`, \`summary:\`, and \`game:\` / \`song:\` / \`video:\` to link one). They are the site's Posts, with Atom and JSON feeds. |
-| \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`), D1 migrations, \`wrangler.jsonc\`. |
+| \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`) and its D1 migrations. |
+| \`wrangler.jsonc\` | The Worker's Cloudflare config (the Worker, D1, the Table and Lobby Durable Objects, and \`previews\` for branch Previews), at the root, where Cloudflare's Workers Builds reads it. A studio made before 0.10.0 keeps it in \`site/\` and deploys from a computer; every command finds either. |
+| \`changes/\` | One small file per change that went out through a pull request (\`homie-studio progress pr\` writes it): the site lists the newest, so the Claude app can tell when a merged change is live. |
 | \`studio.json\` | The studio's name, slug, Cloudflare resource names, custom domain and stats sharing. \`.studio/\` (git-ignored) is this computer's own state. |
 | \`.claude/skills/\` | Skills only this studio uses. Homie's own skills come from the Homie plugin. |
 
@@ -103,6 +131,11 @@ studio's pinned copy, never a registry lookup of the bare name.
   SQLite-backed Durable Objects, all on the free Workers plan (no payment method needed).
   If Wrangler is not signed in, run \`npx wrangler login\`: the person approves once in
   their browser. It never overwrites a Worker or database this studio did not create.
+- **Workers Builds** (Cloudflare's own CI, set up by the "Deploy to Cloudflare" button or in the dashboard): on
+  every push to \`main\` it runs \`npm run build\` and \`npm run deploy\`, which in Workers Builds only applies
+  the D1 migrations and deploys (it never creates or refuses anything); on every other branch it runs
+  \`npm run build\` and \`npx wrangler preview\`, a Preview URL with its own rooms. The live site claims itself
+  in the homie.rocks directory the first time it is read, so nothing is stored by hand.
 - \`npx --no-install homie-studio storage add\` — only when the studio needs large media (songs,
   videos): an R2 bucket for \`media put\`, served at \`/media/<key>\`. Cloudflare asks for a
   payment method on the account before R2 works (its first 10 GB a month are free), so this
@@ -159,6 +192,24 @@ studio's pinned copy, never a registry lookup of the bare name.
 - Change a game in small steps, build, and look at it (\`dev\`, then \`check\`).
 - A game's id is its URL (\`/<id>/\`); keep it once published.
 
+## The Game Codex and progress
+
+- **Every game has a Game Codex:** \`games/<id>/CODEX.md\`, its plan in plain words for everyone who makes it, coder
+  or not: concept, world, characters, art direction, controls per device, rooms and players, music and sound,
+  milestones, open questions, and under Latest the decisions as they are made, newest first, each with its date.
+  It is the source of truth: when a decision changes, change the codex in the same change.
+  \`npx --no-install homie-studio codex new <id>\` starts one with every section.
+- \`npx --no-install homie-studio codex <id>\` draws it as a page in the game's own look
+  (\`.studio/codex/<id>.html\`, \`--open\` opens it; \`--artifact\` makes a copy to publish as a Claude artifact).
+  The site has it too, for the owner only and never listed: \`codex link <id>\` gives the one-time sign-in link.
+- **Progress:** \`npx --no-install homie-studio progress start <id> --title "<what this build does>"\` opens a
+  build's progress feed; build, check and deploy report into it. The codex page's Build status tab redraws itself
+  as it moves (stages, checks going green, how to try it, spend), and \`homie-studio statusline --install\` puts
+  one line of it under the prompt in Claude Code.
+- \`npx --no-install homie-studio setup status\` says what this computer and the person's accounts have (Node,
+  Cloudflare, Chrome, ffmpeg, GitHub, ElevenLabs, fal), what each unlocks, and the exact fix. Optional ones never
+  block anything.
+
 ## Rules
 
 - Keys stay in the providers' own logins (Wrangler, ElevenLabs, fal) or the OS
@@ -186,7 +237,7 @@ Claude-only notes go below this line. -->
 `;
 }
 
-function readme({ name }) {
+export function readme({ name }) {
   return `# ${name}
 
 A game studio made with [Homie](https://homie.rocks). Open this folder in Claude Code or Codex
@@ -249,12 +300,14 @@ anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site
 | \`pages/<path>/index.html\` | A whole page at \`/<path>/\`, instead of the generated one (\`pages/<id>/index.html\` replaces a game's landing) or beside them (\`pages/about/index.html\`). It may borrow \`<!-- homie:style -->\`, \`<!-- homie:header -->\`, \`<!-- homie:footer -->\`, \`<!-- homie:script -->\`. |
 | \`public/\` | Files served as they are, at the same path (\`public/fonts/x.woff2\` is \`/fonts/x.woff2\`). |
 
-\`src/worker.mjs\`, \`migrations/\` and \`wrangler.jsonc\` are the Worker; \`dist/\` is the build (not committed).
+\`src/worker.mjs\` and \`migrations/\` are the Worker (its config is \`wrangler.jsonc\`, at the studio's root); \`dist/\` is the build (not committed).
 `;
 
 const GITIGNORE = `node_modules/
 # This computer's own state: the site's workers.dev address (it names the Cloudflare account, often after its owner).
 .studio/
+# This person's own Claude Code settings for this studio (the status line, for one).
+.claude/settings.local.json
 site/dist/
 site/.wrangler/
 .wrangler/
@@ -278,10 +331,13 @@ videos/**/*.webm
 `;
 
 /** Every file a new studio gets, relative to its folder. */
-export function studioFiles({ name, slug, homie }) {
+export function studioFiles({ name, slug, homie, template = false }) {
   const worker = slug;
   const studio = {
     name, slug,
+    // A copy of the public template (Deploy to Cloudflare) until `homie-studio setup attach` names it for real:
+    // meanwhile its site shows the name the person typed in Cloudflare's form (STUDIO_NAME).
+    ...(template ? { template: true } : {}),
     homie: { studio: STUDIO_VERSION, directory: homie },
     // r2 stays null until `homie-studio storage add`: a new studio deploys with no R2 at all.
     // `domain`: the studio's own domain once it has one (e.g. "night-owls.example"). The workers.dev address never
@@ -297,11 +353,20 @@ export function studioFiles({ name, slug, homie }) {
     type: 'module',
     scripts: { dev: 'homie-studio dev', build: 'homie-studio build', deploy: 'homie-studio deploy', check: 'homie-studio check', studio: 'homie-studio' },
     devDependencies: { '@homie-rocks/studio': packageSpec(homie), wrangler: WRANGLER_VERSION },
+    // What Cloudflare's "Deploy to Cloudflare" form says about each setting (package.json `cloudflare.bindings`).
+    cloudflare: {
+      label: 'Homie studio',
+      products: ['Workers', 'D1', 'Durable Objects'],
+      bindings: {
+        STUDIO_NAME: { description: 'Your studio\'s name, as its site shows it (for example **Night Owls**). Claude can change it later.' },
+        DB: { description: 'The studio\'s own database: finished rounds, the studio\'s own stats (counts, never a visitor) and its claim in the [homie.rocks](https://homie.rocks/studios/) directory. Free plan.' },
+      },
+    },
   };
-  return {
+  const files = {
     'AGENTS.md': agentsMd({ name, slug }),
     'CLAUDE.md': claudeMd(),
-    'README.md': readme({ name }),
+    'README.md': template ? templateReadme() : readme({ name }),
     'studio.json': `${JSON.stringify(studio, null, 2)}\n`,
     'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
     '.gitignore': GITIGNORE,
@@ -319,9 +384,61 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
 `,
     'site/migrations/0001_studio.sql': MIGRATION,
     [`site/migrations/${STATS_MIGRATION_FILE}`]: STATS_MIGRATION,
-    'site/wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2 }),
+    '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;
+    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. -->
+<div class="band-in" style="text-align:center">
+  <p class="kicker">New studio</p>
+  <h2>{{studio.name}} is live</h2>
+  <p>It runs on your own Cloudflare account. Connect it to the Claude chat that set it up, and Claude takes it from here.</p>
+  <p><a class="btn" href="/_studio/connect">Connect to Claude</a></p>
+</div>
+`;
+
+export function templateReadme() {
+  return `# A Homie studio
+
+This repository is a game studio made with [Homie](https://homie.rocks): its games, music, videos and posts,
+and a site with public multiplayer rooms that runs on **your own Cloudflare account**, on the free plan.
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/homie-rocks/homie/tree/main/template)
+
+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.
+
+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.
+
+\`AGENTS.md\` says how everything here works.
+`;
 }
 
 /**
@@ -352,7 +469,7 @@ function insideGit(dir) {
   try { return execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() === 'true'; } catch { return false; }
 }
 
-export function newStudio(folder, { name, homie, slug: askedSlug, install = true } = {}) {
+export function newStudio(folder, { name, homie, slug: askedSlug, install = true, template = false } = {}) {
   if (typeof folder !== 'string' || !folder.trim()) throw new Error('name the folder for the new studio, e.g. `homie-studio new ~/studios/night-owls --name "Night Owls"`. Nothing was written.');
   if (!name || !String(name).trim()) throw new Error('give the studio a name: --name "Night Owls". Nothing was written.');
   const dir = resolve(folder.replace(/^~(?=\/|$)/, homedir()));
@@ -367,7 +484,7 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
     if (entries.length) throw new Error(`${real} is not empty (${entries.slice(0, 5).join(', ')}${entries.length > 5 ? ', …' : ''}). A new studio goes in a new or empty folder. Nothing was written.`);
   }
   const slug = slugify(askedSlug || name);
-  const files = studioFiles({ name: String(name).trim(), slug, homie: homie || 'https://homie.rocks' });
+  const files = studioFiles({ name: String(name).trim(), slug, homie: homie || 'https://homie.rocks', template });
   mkdirSync(dir, { recursive: true });
   const wrote = [];
   for (const [rel, content] of Object.entries(files)) {

package/lib/setup.mjs

@@ -0,0 +1,90 @@
+/**
+ * `homie-studio setup attach <hs_…>` — this repository is the studio the Claude app's setup card (the Homie MCP
+ * tool studio_setup) is making, said once from the Claude Code session that works in it:
+ *
+ *   - the directory records that Claude works in this repository (the card's "Let Claude work in it" goes green),
+ *     and answers with the studio's live address once its site is connected (the card's Cloudflare step);
+ *   - a copy of the public template (studio.json `template: true`) gets the name the person chose in the chat:
+ *     studio.json, the Worker's STUDIO_NAME, and AGENTS.md and README.md while they are untouched; its first-run
+ *     "Connect to Claude" band goes; studio.json takes the Worker and database names Cloudflare's form chose;
+ *   - the live address goes into .studio/local.json (git-ignored), so `check --url` and the card know it.
+ *
+ * It sends the repository's owner/name and the studio's name and slug, nothing else: no key, no path, no code.
+ * A setup id is single use per repository: a second attach from the same repository answers the same; another
+ * repository is refused.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configNames } from './cloudflare.mjs';
+import { networkWhy } from './progress.mjs';
+import { CONNECT_BAND, agentsMd, readme, slugify, templateReadme } from './scaffold.mjs';
+import { configPath, readStudio, writeLocal, writeStudio } from './studio.mjs';
+import { STUDIO_VERSION } from './version.mjs';
+
+const SETUP_ID = /^hs_[a-f0-9]{32}$/;
+
+/** owner/repo of this checkout's GitHub remote (a Claude Code cloud session's remote goes through its own proxy). */
+export function repoOf(root) {
+  const r = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: root, encoding: 'utf8', timeout: 5000 });
+  if (r.status !== 0) return null;
+  const url = r.stdout.trim().replace(/\.git$/, '').replace(/\/+$/, '');
+  const m = /[/:]([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9._-]{1,100})$/.exec(url);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+export async function setupAttach(root, id, { homie } = {}) {
+  if (!SETUP_ID.test(String(id ?? ''))) return { ok: false, command: 'setup attach', why: 'attach to the setup id the Claude app\'s setup card showed: hs_ and 32 hex digits' };
+  const studio = readStudio(root);
+  const directory = String(homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  const repo = repoOf(root);
+  let res; let body = null;
+  try {
+    res = await fetch(`${directory}/api/studio/setup/${id}/attach`, {
+      method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': `homie-studio/${STUDIO_VERSION}` },
+      body: JSON.stringify({ repo, studio: { name: studio.name, slug: studio.slug, template: studio.template === true }, version: STUDIO_VERSION }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    body = await res.json().catch(() => null);
+  } catch (error) { return { ok: false, command: 'setup attach', why: `${directory} did not answer (${error?.message ?? error})` }; }
+  const blocked = networkWhy(res, directory);
+  if (blocked) return { ok: false, command: 'setup attach', needs: 'network', why: blocked };
+  if (!res.ok || !body?.ok) return { ok: false, command: 'setup attach', why: body?.message ?? `${directory} answered ${res.status}` };
+
+  const renamed = [];
+  const name = typeof body.name === 'string' && body.name.trim() ? body.name.trim().slice(0, 60) : null;
+  if (studio.template === true) {
+    const next = { ...readStudio(root) };
+    delete next.template;
+    const was = { name: next.name, slug: next.slug };
+    if (name) { next.name = name; next.slug = slugify(name); }
+    // The Worker and database are whatever Cloudflare's form named them: studio.json follows wrangler.jsonc.
+    const names = configNames(root);
+    next.cloudflare = { ...next.cloudflare, ...(names.worker ? { worker: names.worker } : {}), ...(names.d1 ? { d1: names.d1 } : {}) };
+    writeStudio(root, next);
+    renamed.push('studio.json');
+    if (name) {
+      const cfg = configPath(root);
+      const text = readFileSync(cfg, 'utf8');
+      const fixed = text.replace(/("STUDIO_NAME"\s*:\s*)"(?:[^"\\]|\\.)*"/g, (_, k) => `${k}${JSON.stringify(name)}`);
+      if (fixed !== text) { writeFileSync(cfg, fixed); renamed.push('wrangler.jsonc'); }
+      const untouched = (file, before, after) => {
+        const path = join(root, file);
+        if (existsSync(path) && readFileSync(path, 'utf8') === before) { writeFileSync(path, after); renamed.push(file); }
+      };
+      untouched('AGENTS.md', agentsMd(was), agentsMd({ name: next.name, slug: next.slug }));
+      untouched('README.md', templateReadme(), readme({ name: next.name }));
+    }
+    const band = join(root, 'site', 'partials', 'home.html');
+    if (existsSync(band) && readFileSync(band, 'utf8') === CONNECT_BAND) { rmSync(band); renamed.push('site/partials/home.html (removed)'); }
+  }
+  if (body.site) writeLocal(root, { url: body.site, connectedAt: new Date().toISOString() });
+  return {
+    ok: true, command: 'setup attach', setup: id, repo, site: body.site ?? null, name: name ?? studio.name, renamed,
+    message: body.site ? `This repository is ${name ?? studio.name}, live at ${body.site}. The Claude app's card shows it.` : `This repository is ${name ?? studio.name}. Its site is not connected yet: ${body.connect ?? 'open the site and tap Connect to Claude'}.`,
+    next: [
+      ...(renamed.length ? ['commit the renamed files on a branch and open a pull request (merging it names the live site)'] : []),
+      'npm install, then npx --no-install homie-studio progress attach <hb_…> when the chat opened a build',
+    ],
+  };
+}