@homie-rocks/studio 0.58.20 → 0.58.23

package/lib/mcp-tools.mjs

@@ -26,7 +26,8 @@ import { renderCodex, newCodex } from './codex.mjs';
 import { demoGames, formatDemo } from './demo.mjs';
 import { formatStatus, setupStatus } from './doctor.mjs';
 import { editStudioFile, listFiles, readStudioFile, searchStudio, writeStudioFile } from './files.mjs';
-import { cliJob, findNode, getJob, installJob, installed, jobView, runningJobs, startJob, toolEnv, waitJob, which } from './jobs.mjs';
+import { cliJob, cliOf, findNode, getJob, installJob, installed, jobView, runningJobs, startJob, stepJobs, toolEnv, waitJob, which } from './jobs.mjs';
+import { endFeed } from './job-runner.mjs';
 import { Feed, currentId, publicFeed, readFeed, startProgress } from './progress.mjs';
 import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
@@ -179,6 +180,13 @@ async function cli(ctx, root, label, args, { wait = ctx.waitMs, onEnd = null, cl
   return { ended, job, result: job.result };
 }
 
+/** Where a job an earlier server started may be: the studios, and where a clone or a sign-in runs. */
+function jobRoots(ctx) {
+  let studios = [];
+  try { studios = ctx.studios().map((s) => s.root); } catch { /* none */ }
+  return [ctx.current, ...studios, ctx.studiosDir, homedir()];
+}
+
 function stillRunning(job, what) {
   return ok(`${what} is still running (job ${job.id}, ${jobView(job).seconds} s so far). studio_job { "job": "${job.id}" } says when it is done; tell the person what is happening meanwhile.`, { kind: 'job', ...jobView(job) });
 }
@@ -404,13 +412,7 @@ async function feedForRun(ctx, root, { id, title }) {
 
 function endRun(root, run, state, note) {
   if (!run.auto) return;
-  try {
-    const feed = new Feed(root, run.build);
-    const doc = feed.doc;
-    if (!doc || doc.state !== 'running') return;
-    feed.change((d) => { for (const s of d.stages) if (s.state === 'pending') s.state = 'skipped'; });
-    feed.end(state, note);
-  } catch { /* the feed stays as it was */ }
+  endFeed(Feed, root, run.build, state, note);
 }
 
 function buildCard(ctx, root, found) {
@@ -439,23 +441,30 @@ function buildCard(ctx, root, found) {
   return ok(runLine ? `${runLine}\n${text}` : text, { kind: 'build', build: found.id, feed, jobs, run: runView, now: new Date().toISOString() });
 }
 
-/** Start a check / playtest / deploy: its feed first, then the work, and the card at once. */
+/**
+ * Start a check / playtest / deploy: its feed first, then the work, and the card at once. The steps run as one job
+ * (lib/jobs.mjs), which outlives this server and ends the feed itself; while this server is here it also keeps the
+ * run's own words (run.state, run.why, run.look) for the card.
+ */
 async function startRun(ctx, root, { kind, game, title, steps }) {
-  const run = { kind, title, state: 'running', ...(await feedForRun(ctx, root, { id: game ?? null, title })), jobs: [] };
+  const run = { kind, title, state: 'running', ...(await feedForRun(ctx, root, { id: game ?? null, title })), job: null };
+  Object.defineProperty(run, 'jobs', { get: () => (run.job ? stepJobs(run.job) : []) });
   ctx.runs.set(run.build, run);
-  const next = (i) => {
-    if (i >= steps.length) { run.state = 'passed'; endRun(root, run, 'passed', `${title}: done.`); if (kind === 'check' || kind === 'playtest') ctx.note(root).checked = true; return; }
-    const step = steps[i];
-    const job = cliJob(root, step.label, step.args, {
-      onEnd: (j) => {
-        step.after?.(j, run);
-        if (j.code !== 0 && !step.soft) { run.state = 'failed'; run.why = `${step.label}: ${whyOf(j)}`; endRun(root, run, 'failed', run.why); return; }
-        next(i + 1);
-      },
-    });
-    run.jobs.push(job);
-  };
-  next(0);
+  const node = findNode();
+  if (!node) throw new Error('Node.js is missing. AI: call setup_prepare, then retry this tool.');
+  run.job = startJob({
+    root, label: title, cmd: node.bin, json: true, env: toolEnv(),
+    steps: steps.map((step) => ({ label: step.label, args: [cliOf(root), ...step.args, '--json'], json: true, soft: step.soft })),
+    feed: run.auto ? { build: run.build, title } : null,
+    onEnd: (job) => {
+      const done = stepJobs(job);
+      done.forEach((j, n) => { try { steps[n]?.after?.(j, run); } catch { /* the run's result stands */ } });
+      const failed = done.find((j, n) => j.code !== 0 && !steps[n]?.soft);
+      if (failed || job.code !== 0) { run.state = 'failed'; run.why = failed ? `${failed.label}: ${whyOf(failed)}` : job.why ?? `exited with ${job.code}`; endRun(root, run, 'failed', run.why); return; }
+      run.state = 'passed'; endRun(root, run, 'passed', `${title}: done.`);
+      if (kind === 'check' || kind === 'playtest') ctx.note(root).checked = true;
+    },
+  });
   await new Promise((r) => setTimeout(r, 1500));
   return buildCard(ctx, root, feedFor(root, run.build));
 }
@@ -1090,7 +1099,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'preview_run', title: 'Run the site here',
-      description: 'Run the studio\'s whole site on this computer (pages, public rooms, the database) and give the addresses to open: the home page, and each game\'s Play page. Two browser tabs on a game are two players in the same room. It keeps running until preview_stop (or the app quits).',
+      description: 'Run the studio\'s whole site on this computer (pages, public rooms, the database) and give the addresses to open: the home page, and each game\'s Play page. Two browser tabs on a game are two players in the same room. It keeps running until preview_stop.',
       inputSchema: { type: 'object', properties: { game: str('Optional: the game to give the Play address of'), port: { type: 'number', description: 'Optional port (default: 8787, or the next free one)' }, ...STUDIO_ARG } },
       annotations: { title: 'Run the site here', ...RW },
       run: async (a) => {
@@ -1221,7 +1230,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_deploy', title: 'Put the studio online',
-      description: 'Put the studio\'s site online on the studio\'s OWN Cloudflare account: one Worker, one D1 database and two Durable Objects, with its own resources. Call it with plan: true first and tell the person in two or three lines what it creates and costs. If Cloudflare is not signed in, cloudflare_login opens it in their browser to approve once. Runs in the background with the build card.',
+      description: 'Put the studio\'s site online on the studio\'s OWN Cloudflare account: one Worker (with its Durable Objects and two Queues) and one D1 database, with its own resources. Call it with plan: true first and tell the person in two or three lines what it creates and costs. If Cloudflare is not signed in, cloudflare_login opens it in their browser to approve once. Runs in the background with the build card.',
       inputSchema: { type: 'object', properties: { plan: { type: 'boolean', description: 'Only say what it will create and what it costs; change nothing' }, ownRoute: { type: 'boolean', description: 'Only after the plan or a deploy warned that another site\'s route on the studio\'s custom domain covers its hostname, and the person agreed: add the studio\'s own exact-host route (the one line the warning gives) and deploy. It never edits or removes any other route' }, ...STUDIO_ARG } },
       annotations: { title: 'Put the studio online', readOnlyHint: false, destructiveHint: false, openWorldHint: true }, _meta: ui(UI.build),
       run: async (a) => {
@@ -1255,7 +1264,7 @@ export function toolDefs(ctx, avail = {}) {
       inputSchema:{type:'object',properties:{...STUDIO_ARG,live:{type:'boolean'},renew:{type:'boolean'}}},
       annotations:{readOnlyHint:false,destructiveHint:false,openWorldHint:true},
       run:async a=>{
-        const job=cliJob(ctx.root(a.studio),'Private Stripe webhook',['shop','webhook',...(a.live?['--live']:[]),...(a.renew?['--renew']:[])],{cli:join(PACKAGE_ROOT,'bin','homie-studio.mjs'),keep:false});
+        const job=cliJob(ctx.root(a.studio),'Private Stripe webhook',['shop','webhook',...(a.live?['--live']:[]),...(a.renew?['--renew']:[])],{cli:join(PACKAGE_ROOT,'bin','homie-studio.mjs')});
         await waitJob(job,Math.min(ctx.waitMs,1000));
         return ok('Follow studio_job. Its events contain any required Stripe pairing; a saved login needs no new approval.',{kind:'job',...jobView(job)});
       },
@@ -1269,7 +1278,7 @@ export function toolDefs(ctx, avail = {}) {
         const root=ctx.root(a.studio);
         mkdirSync(join(root,'.studio'),{recursive:true});
         writeFileSync(join(root,'.studio','booking-slots.json'),JSON.stringify(a.slots,null,2));
-        const job=cliJob(root,'Sync Stripe booking links',['shop','connect',...(a.live?['--live']:[])],{cli:join(PACKAGE_ROOT,'bin','homie-studio.mjs'),keep:false});
+        const job=cliJob(root,'Sync Stripe booking links',['shop','connect',...(a.live?['--live']:[])],{cli:join(PACKAGE_ROOT,'bin','homie-studio.mjs')});
         await waitJob(job,Math.min(ctx.waitMs,1000));
         return ok('Booking link sync started. Check studio_job for completion.',{kind:'job',...jobView(job)});
       },
@@ -1282,7 +1291,7 @@ export function toolDefs(ctx, avail = {}) {
       run: async (a) => {
         const root = ctx.root(a.studio);
         const args = ['shop', 'connect', ...(a.live ? ['--live'] : []), ...(a.renew ? ['--renew'] : [])];
-        const job = cliJob(root, 'Stripe connection', args, { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs'), keep: false });
+        const job = cliJob(root, 'Stripe connection', args, { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs') });
         const ended = await waitJob(job, Math.min(ctx.waitMs, 1000));
         ctx.status = null;
         if (ended && job.code !== 0) return fail(whyOf(job), { kind: 'job', ...jobView(job) });
@@ -1298,7 +1307,7 @@ export function toolDefs(ctx, avail = {}) {
         const root = ctx.root(a.studio);
         const need = needsInstall(ctx, root); if (need) return need;
         const bin = join(root, 'node_modules', '.bin', process.platform === 'win32' ? 'wrangler.cmd' : 'wrangler');
-        const job = startJob({ root, label: 'Cloudflare sign-in (wrangler login)', cmd: bin, args: ['login'], keep: false });
+        const job = startJob({ root, label: 'Cloudflare sign-in (wrangler login)', cmd: bin, args: ['login'] });
         const ended = await waitJob(job, Math.min(ctx.waitMs, 40_000));
         ctx.status = null;
         if (!ended) return ok(`Cloudflare opened in the browser: approve it there (job ${job.id}). setup_status says when it is done.`, { kind: 'job', ...jobView(job) });
@@ -1461,8 +1470,9 @@ export function toolDefs(ctx, avail = {}) {
       inputSchema: { type: 'object', properties: { job: str('The job id (j_…)') }, required: ['job'] },
       annotations: { title: 'A job', ...RO },
       run: async (a) => {
-        const job = getJob(a.job);
-        if (!job) return fail(`no job ${a.job} (jobs end with the app; build_progress shows a build)`);
+        // A job outlives the server that started it: one an earlier server started is read from its studio.
+        const job = getJob(a.job, { roots: jobRoots(ctx) });
+        if (!job) return fail(`no job ${a.job} in these studios (build_progress shows a build)`);
         await waitJob(job, Math.min(ctx.waitMs, 30_000));
         const v = jobView(job, { lines: 20 });
         if (job.endedAt) ctx.status = null;

package/lib/parts-store.mjs

@@ -21,6 +21,7 @@ import { priceWords } from "../worker/purchase-pricing.mjs";
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   LIMITS, TUNING_FILE, TUNING_UPSTREAM, assetRecords, checkPart, compareVersions, isVersion, licenceIssues, licenseOfPart, listOwnParts, packPart, packedDir,
   packedVersions, parseRef, partDir, readOrigins, readPart, requiredParts, sha256, shareProblems, syncPartCredits, vendorDir, verifyFiles, writeHashes,
@@ -32,6 +33,45 @@ export const HUB = 'https://homie.rocks';
 const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
 const line = (v, n = 200) => (typeof v === 'string' ? v.replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, n) : '');
 
+/* ------------------------------------------------------------------ the toolkit's own parts */
+
+/**
+ * The parts that come WITH the toolkit (parts/catalogue.json in this package, e.g. venue-desk): found and added from the
+ * installed toolkit, with no network. "venue-desk" alone, or "homie.rocks/venue-desk", names one; every file is checked
+ * against the catalogue's SHA-256 and size exactly as a fetched part's are.
+ */
+export const TOOLKIT_HOST = 'homie.rocks';
+const TOOLKIT_PARTS = fileURLToPath(new URL('../parts/', import.meta.url));
+export function bundledCatalogue() {
+  try {
+    const c = JSON.parse(readFileSync(join(TOOLKIT_PARTS, 'catalogue.json'), 'utf8'));
+    return Array.isArray(c?.parts) ? c.parts.filter((p) => isObj(p) && typeof p.id === 'string' && p.share === true && Array.isArray(p.files)) : [];
+  } catch { return []; }
+}
+/** A bundled part named by `refText`, read and checked; null when it is not one of the toolkit's. */
+export function bundledPart(refText) {
+  const text = String(refText ?? '').trim();
+  const bare = /^([a-z0-9][a-z0-9-]{0,47})(?:@(.{1,60}))?$/.exec(text);
+  const ref = bare ? { host: TOOLKIT_HOST, id: bare[1], version: bare[2] ?? null, ref: `${TOOLKIT_HOST}/${bare[1]}` } : parseRef(text);
+  if (!ref || ref.host !== TOOLKIT_HOST) return null;
+  const part = bundledCatalogue().find((p) => p.id === ref.id);
+  if (!part) return null;
+  if (ref.version && ref.version !== part.version) throw new Error(`The toolkit has ${ref.id} ${part.version}, not ${ref.version}. Upgrade the toolkit for a newer one.`);
+  const shape = checkPart(part);
+  if (!shape.ok) throw new Error(`${ref.ref} ${part.version} is not a part this toolkit can read: ${shape.problems.filter((p) => p.level === 'refuse').map((p) => `${p.field}: ${p.problem}`).slice(0, 3).join('; ')}`);
+  const files = new Map();
+  for (const f of part.files) {
+    const at = join(TOOLKIT_PARTS, part.id, f.path);
+    if (!at.startsWith(join(TOOLKIT_PARTS, part.id) + '/')) throw new Error(`${ref.ref}: ${f.path} is outside the part`);
+    let bytes;
+    try { bytes = readFileSync(at); } catch { throw new Error(`${ref.ref}: ${f.path} is missing from the installed toolkit. Reinstall it (npm ci).`); }
+    if (bytes.length !== f.bytes || sha256(bytes) !== f.sha256) throw new Error(`${ref.ref} ${part.version}: ${f.path} in the installed toolkit is not the file its catalogue describes. Reinstall the toolkit (npm ci).`);
+    files.set(f.path, bytes);
+  }
+  const entry = { ...part, from: { ...(isObj(part.from) ? part.from : {}), studio: 'Homie toolkit' }, studio: { name: 'Homie toolkit' } };
+  return { ref: { ...ref, version: part.version }, part, files, entry, base: baseOf(TOOLKIT_HOST), version: part.version, versions: [part.version], access: null, bundled: true };
+}
+
 /* ------------------------------------------------------------------ the one fetch */
 
 /** A studio's site from its host: https, except a site on this computer (the local preview), which has no certificate. */
@@ -196,7 +236,7 @@ export async function addPart(root, refText, { game = null, fetch, npm = runNpm,
   if (game && !existsSync(experienceFile(root, game))) return fail(`there is no game "${game}" in this studio (${listGames(root).map((g) => g.id).join(', ') || 'it has none yet'})`);
   let got;
   try {
-    got = offline ? await offlinePurchase(root, refText, game) : await fetchPart(refText, { fetch, onPaid: (ref, part, offer) => paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay }) });
+    got = offline ? await offlinePurchase(root, refText, game) : bundledPart(refText) ?? await fetchPart(refText, { fetch, onPaid: (ref, part, offer) => paidAccess(root, ref, part, { game, quantity, approve, fetch, offer, wallet, walletPay }) });
     if (got.access) {
       savePurchaseBackup(root, got, got.access, game);
       const c = got.access.claims;
@@ -345,6 +385,10 @@ export async function findParts(root, query = '', { kind = null, tag = null, lic
       if (part) here.push(row({ ...part, from: e.from ?? part.from }, { where: 'here', ref, add: ref, import: part.entry ? `@parts/${ref}` : null, games: e.games ?? [], say: `Already in this studio (${e.version}): import it from '@parts/${ref}'.` }));
     }
   }
+  for (const p of bundledCatalogue()) {
+    const ref = `${TOOLKIT_HOST}/${p.id}`;
+    if (!here.some((h) => h.ref === ref)) here.push(row({ ...p, from: { ...(isObj(p.from) ? p.from : {}), studio: 'Homie toolkit' } }, { where: 'toolkit', ref, add: ref, import: null, say: `Comes with the Homie toolkit (no download): part_add { "part": "${ref}" }.` }));
+  }
   let base = hub;
   if (!base && root) { try { const d = readStudio(root).homie?.directory; base = d === false || d === null ? null : d; } catch { base = null; } }
   base = /^https?:\/\/[a-z0-9.:-]+$/i.test(String(base ?? '')) ? base : HUB;
@@ -353,7 +397,7 @@ export async function findParts(root, query = '', { kind = null, tag = null, lic
   try {
     const index = await getJson(url, { fetch, what: 'the catalogue of shared parts' });
     if (!Array.isArray(index?.parts)) throw new Error(`${url} is not a parts catalogue`);
-    const have = new Set(here.filter((h) => h.where === 'here').map((h) => h.ref));
+    const have = new Set(here.filter((h) => h.where === 'here' || h.where === 'toolkit').map((h) => h.ref));
     found = index.parts.filter((p) => isObj(p) && typeof p.id === 'string' && (typeof p.host === 'string' || typeof p.add === 'string')).map((p) => {
       const ref = parseRef(typeof p.add === 'string' ? p.add : `${p.host}/${p.id}`)?.ref;
       return ref ? row(p, { where: 'hub', ref, add: ref, studio: line(p.studio?.name, 80) || null, page: /^https:\/\//.test(String(p.page ?? '')) ? p.page : null, here: have.has(ref), say: `${p.sale ? `Paid: ${priceWords(p.sale)}. Ask for approval of the exact quote before requesting payment. ` : 'Free. '}Add it: part_add { "part": "${ref}" }.` }) : null;

package/lib/parts.mjs

@@ -30,7 +30,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, r
 import { dirname, join, relative } from 'node:path';
 
 export const PART_ID = /^[a-z0-9][a-z0-9-]{0,47}$/;
-export const PART_KINDS = Object.freeze(['character', 'rig', 'clips', 'environment', 'effect', 'sound', 'ui', 'mechanic', 'shader', 'level-generator', 'bot-brain', 'audio-pack', 'set-piece', 'quiz', 'menu-board', 'waitlist', 'live-total', 'loop', 'stem', 'track', 'video-intro', 'video-template', 'app', 'music', 'video']);
+export const PART_KINDS = Object.freeze(['character', 'rig', 'clips', 'environment', 'effect', 'sound', 'ui', 'mechanic', 'shader', 'level-generator', 'bot-brain', 'audio-pack', 'set-piece', 'quiz', 'menu-board', 'waitlist', 'live-total', 'loop', 'stem', 'track', 'video-intro', 'video-template', 'app', 'music', 'video', 'agent']);
 export const NETPLAY_KINDS = Object.freeze(['host-authoritative', 'replicated', 'local']);
 export const PROVENANCE = Object.freeze(['original', 'generated', 'imported']);
 export const PIVOTS = Object.freeze(['feet', 'centre', 'base', 'origin']);
@@ -321,6 +321,17 @@ export function checkPart(part, { id = null } = {}) {
       if (part.contract.netplay !== undefined && !NETPLAY_KINDS.includes(part.contract.netplay)) bad('contract.netplay', `"${String(part.contract.netplay).slice(0, 40)}" is not a netplay contract`, `one of: ${NETPLAY_KINDS.join(', ')}`);
     }
   }
+  // An agent part is a template for a studio agent (the chat's sidebar offers it under New agent): who it is, not code.
+  if (part.kind === 'agent') {
+    const a = part.agent, text = (v, max) => typeof v === 'string' && v.length <= max;
+    if (!isObj(a)) bad('agent', 'an agent part has no agent block', '{ "name": "Bookings", "persona": "what it does, in a line", "instructions": "how it works" }');
+    else {
+      if (!(text(a.name, 40) && a.name.trim())) bad('agent.name', 'it is not a name of 1 to 40 characters', '"Bookings"');
+      if (a.persona !== undefined && !text(a.persona, 400)) bad('agent.persona', 'it is not text of up to 400 characters', 'one line on what the agent does');
+      if (a.instructions !== undefined && !text(a.instructions, 8000)) bad('agent.instructions', 'it is not text of up to 8000 characters', 'how the agent should work');
+      if (a.tools !== undefined && a.tools !== null && !(Array.isArray(a.tools) && a.tools.length <= 40 && a.tools.every((t) => typeof t === 'string' && /^[\w:.-]{1,80}$/.test(t)))) bad('agent.tools', 'it is not a list of up to 40 tool names', 'leave it out to let the agent use every tool');
+    }
+  }
   if (part.kind === 'mechanic' && !NETPLAY_KINDS.includes(part.contract?.netplay)) warn('contract.netplay', 'a mechanic does not say how it behaves in a room', `${NETPLAY_KINDS.join(', ')}: another game needs to know who decides`);
   if (part.cost !== undefined) {
     if (!isObj(part.cost)) bad('cost', 'it is not an object', '{ "triangles": 0, "drawCalls": 0, "textureMB": 0, "bytes": 0, "measuredOn": "…" }');
@@ -646,6 +657,7 @@ export function newPart(root, id, { kind = 'mechanic', name = null, from = null,
     requires: {},
     ...(['character', 'rig', 'clips', 'environment', 'set-piece'].includes(kind) ? { physical: { units: 'metres', scale: 1, pivot: kind === 'environment' || kind === 'set-piece' ? 'origin' : 'feet', collision: null } } : {}),
     ...(['character', 'rig', 'clips'].includes(kind) ? { skeleton: { rig: null, clips: [] } } : {}),
+    ...(kind === 'agent' ? { agent: { name: title, persona: '', instructions: '' } } : {}),
     ...(kind === 'mechanic' || kind === 'bot-brain' ? { contract: { inputs: {}, state: {}, netplay: 'host-authoritative' } } : {}),
     cost: {},
     provenance: { source: 'original', notes: '' },

package/lib/scaffold.mjs

@@ -188,7 +188,7 @@ Cloudflare creates DNS and TLS during deploy with the existing sign-in.
 
 ## Apps: one screen, roles and parts
 
-Plan apps with the same Codex mechanism as games: \`codex new <id> --kind app\` writes \`apps/<id>/CODEX.md\`. Read the packaged plan, app and playtest guides. Preserve the person’s words, scene, people, offers and testable needs; build that scene with engines, style, parts and media, then prove each need on wall and phone. Starters are plumbing, not completion.
+Plan apps with the same Codex mechanism as games: \`codex new <id> --kind app\` writes \`apps/<id>/CODEX.md\`. Read the packaged plan, app and playtest guides. Preserve the person’s words, scene, people, offers and testable needs; build that scene with engines, style, parts and media. Starters are plumbing, not completion.
 
 An app lives in \`apps/<id>/app.json\` and \`src/\`. Make one with \`homie-studio app new <id>\` (or \`app_make\`). Use the Homie plugin's \`app\` skill for businesses, venues, causes and customer apps. No game demo, rounds, scores, bots or mandatory fun: build what the person needs with the fewest human steps.
 
@@ -196,7 +196,7 @@ An app is ONE screen that morphs with context: camera moves, panels unfold, its
 
 Declare roles, surfaces, words and lasting record collections in app.json. Netplay's host is not a staff permission. Use \`@homie-rocks/studio/apps\` for authorized lasting records and \`@homie-rocks/studio/links\` for ticket links, QR and HTTP-safe IDs. Staff use private role links plus existing account grants; keep private records out of public collections. Look for engine mechanisms and shared parts before writing a component. Credit licences; sharing is optional and separate from selling.
 
-Your studio also serves MCP at \`/mcp\`. Staff connect their own AI with their existing account and one browser approval; never ask them for a key. Add business actions with \`homie-studio tool new <name> --app <id>\`, keep their declared role narrow, and reuse the app's existing record IDs, field formats and versions. Customers can browse and buy through this same endpoint, and tools may declare a price using the studio's existing payments. Add event handlers with \`homie-studio function new <name> --event order.paid\`; read \`node_modules/@homie-rocks/studio/functions/FUNCTIONS.md\`. Test owner, staff and public calls locally. Read \`node_modules/@homie-rocks/studio/tools/TOOLS.md\` and the Homie plugin's \`tools\` skill.
+Your studio also serves MCP at \`/mcp\`. Staff connect their own AI with their existing account and one browser approval; never ask them for a key. Add business actions with \`homie-studio tool new <name> --app <id>\`, keep their declared role narrow, and reuse the app's existing record IDs, field formats and versions. Customers can browse and buy through this same endpoint, and tools may declare a price using the studio's existing payments. Add event handlers with \`homie-studio function new <name> --event order.paid\`; read \`node_modules/@homie-rocks/studio/functions/FUNCTIONS.md\`. Read \`node_modules/@homie-rocks/studio/tools/TOOLS.md\` and the Homie plugin's \`tools\` skill.
 
 Build normally, run \`homie-studio dev --lan\`, then \`homie-studio check <id> --url <origin>\`: the app check proves an actual action across a wall and two phones plus reconnect. The public screen is \`/<id>/open\`, the wall \`/<id>/tv\`. Customer apps use the same \`standalone\` build for desktop/iOS/Android; its existing sign-in and store limitations still apply. See \`node_modules/@homie-rocks/studio/apps/APPS.md\`.
 
@@ -263,7 +263,7 @@ studio's pinned copy, never a registry lookup of the bare name.
   bucket on the studio's own Cloudflare account. Cloudflare asks for a payment method on the account
   before R2 works, so this is a separate step the person agrees to; nothing else needs it. R2 has no
   egress fees; storage is free up to 10 GB-month, then US$0.015 per GB-month.
-- \`npx --no-install homie-studio media move\` (\`--dry-run\` first) — with storage, the big files of
+- \`npx --no-install homie-studio media move\` — with storage, the big files of
   published songs and videos (over 1 MiB, or left out of git; studio.json \`media.r2Over\` changes the
   size) go to R2: each is uploaded, read back and checked by SHA-256, and only then does the site stop
   carrying it; it keeps its address, and the file stays in this folder. Every \`npm run deploy\` does
@@ -376,8 +376,7 @@ studio's pinned copy, never a registry lookup of the bare name.
   the game's own: on a phone it raises copy/paste and the thumb's touch is lost. Call
   \`guardGestures({ touch: 'canvas, [data-action]' })\` from \`@homie-rocks/studio/netplay\` once, early: no
   selection, no callout, no pan or pinch on the gameplay surfaces; text fields, links and ordinary buttons keep the
-  browser's own behaviour (\`NETPLAY.md\` section 24). Try it with a real thumb on a real phone: emulated touch
-  does not raise the callout.
+  browser's own behaviour (\`NETPLAY.md\` section 24). Emulated touch does not raise the callout.
 - **The frame has no storage of its own.** The game runs in a sandboxed frame without \`allow-same-origin\` (a
   stranger's game must never read this site's storage or the owner's session), so \`localStorage\` throws inside it.
   A setting or a personal best goes in \`net.prefs\` (\`net.prefs.string('quality', 'high')\`, \`net.prefs.number('volume', 0.8, { min: 0, max: 1 })\` after \`await net.prefs.ready\`: the typed readers give your fallback for a missing key, never a null that turns into 0,
@@ -491,7 +490,7 @@ studio's pinned copy, never a registry lookup of the bare name.
 - **A server** is a named, lasting pool of rooms for one game, with its own policy and door. Strangers are matched
   only inside one server. Every game's \`pub-N\` rooms are its \`public\` server (Quick play), so old links keep
   working. A server's page is \`/<id>/s/<server>/\`; its rooms are \`s-<server>-<n>\`; \`/<id>/servers/\` lists them.
-- **Policies:** \`open\` (anyone; an AI with an agent pass may sit, always marked AI), \`humans-only\` (no AI of any
+- **Policies:** \`open\` (anyone; an AI may sit, always marked AI), \`humans-only\` (no AI of any
   kind; the game's bots are off unless \`--bots fill\`), \`hybrid\` (N seats in every room are AI companions),
   \`beginner\` (accounts under 30 days, AI guides, quick lines only, optionally \`--kids\`: handles only, the AI's
   level at most 3). **Doors:** \`open\`, \`accounts\` (a passkey account) or \`invite\` (\`office invite\` with
@@ -509,8 +508,9 @@ studio's pinned copy, never a registry lookup of the bare name.
   snippet is in \`NETPLAY.md\` section 17; \`BotBrain\` from the port kit reads it with a rebuild), and declare
   \`caps: ['skill', 'agents']\` in \`createNetplay\` (rules rooms provide the agent runtime). A build
   from before 0.16.0 still plays on every server; the office says it predates servers until it is rebuilt.
-- **Agent passes:** \`npx --no-install homie-studio agents pass <id> --label Claude [--server <server>]\` gives an
-  AI its way into a seat (shown once; \`agents revoke <pass>\` ends it). It sits with \`POST /<id>/api/agent\`
+- **An AI in a seat:** a signed-in person's own AI sits through this studio's \`/mcp\` (\`agent_sit\`), and the
+  owner's own through the local MCP's \`agent_sit\`. For an AI with no MCP connection,
+  \`npx --no-install homie-studio agents pass <id> --label Claude [--server <server>]\` gives it a seat (shown once; \`agents revoke <pass>\` ends it). It sits with \`POST /<id>/api/agent\`
   (Bearer pass), only in a room with people in it, and never on a humans-only server.
 - **AI guides that talk (0.17.0):** a beginner server's guides get a brain. A game's own words for them are
   \`games/<id>/agents.json\` (its vocabulary: goals, lines, the asks a player taps; the build checks it), and
@@ -526,7 +526,7 @@ studio's pinned copy, never a registry lookup of the bare name.
   picks among the vocabulary's goals, values and lines; it never writes text; about 9 neurons a decision).
   \`agents try <id> --view <file> [--ask …] [--model …]\` shows what the brain would decide in one moment. Under
   \`npm run dev\`, Clef on this computer (Ollama with \`clef-flash\`) runs the guides, chat review and game
-  decisions for free when it is here; **never download it without the person's yes** (\`ollama pull clef-flash\` is
+  decisions for free when it is here; pull it only when the person wants Clef, and say its size in one line (\`ollama pull clef-flash\` is
   about 11 GB). A game whose game.json says \`"decide": true\` may ask \`net.decide(state, questions, { floor })\`
   on the host (\`NETPLAY.md\` section 20): per beat or per turn, never per frame.
 
@@ -553,7 +553,7 @@ where it sells and for Stripe's terms. Homie takes no cut.
   The Worker stores only links and a signing secret; buying needs no API key or running AI.
   Rerun \`shop connect\` after shop.json changes; use \`shop connect --renew\` if approval needs renewal.
   Verify a test purchase, signed webhook, item grant, and a refund in Stripe or through the connected AI.
-  Never ask a person for a key. An existing Worker key selects the fuller cart/cap/refund path;
+  An existing Worker key selects the fuller cart/cap/refund path;
   explain it only when those features are requested. Never silently choose \`--manual\`. Live only on request.
   A lost webhook stays pending: ask Stripe to resend it. Free orders need no Stripe.
   Never create secret-returning webhooks through conversation MCP tools; connect captures secrets privately.
@@ -778,7 +778,7 @@ export function studioFiles({ name, slug, homie, template = false, kind = 'game'
     stats: { share: false },
   };
   const pkg = {
-    name: `${slug}-studio`,
+    name: /(^|-)studio$/.test(slug) ? slug : `${slug}-studio`, // "Playtest Studio" stays playtest-studio, not playtest-studio-studio
     private: true,
     type: 'module',
     scripts: { dev: 'homie-studio dev', build: 'homie-studio build', deploy: 'homie-studio deploy', check: 'homie-studio check', studio: 'homie-studio' },
@@ -1167,6 +1167,7 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
     writeFileSync(path, content);
     wrote.push(rel);
   }
+  wrote.sort(); // migrations (and every other file) in name order
   let git = 'already inside a git repository';
   if (!insideGit(dir)) {
     try { execFileSync('git', ['init', '-q'], { cwd: dir, stdio: 'ignore' }); git = 'initialised'; wrote.push('.git/'); } catch { git = 'git not found'; }
@@ -1196,7 +1197,7 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
     'only when the person asks for a game: start from a rules starter and implement the requested mechanic: 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)',
     'when the owner asks to publish: npm run deploy   (then 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.' };
+  ], online: 'Going online creates one Worker (with its Durable Objects and two Queues) and one D1 database 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.' };
 }
 
 export const _test = { relative };

package/lib/template-history.json

@@ -4782,15 +4782,30 @@
      "(intro)": "af7f2f732505d379",
      "## Version-matched authoring guides": "f6261a0e5801b96b",
      "## Layout": "f3a280b8c96cd068",
-     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
-     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## Apps: one screen, roles and parts": [
+      "2ecf713305fd26f5",
+      "c10aa0441ea89702"
+     ],
+     "## Commands (all through the pinned CLI in node_modules)": [
+      "661cbdf5d6a9dbae",
+      "c20d90de21cde0c7"
+     ],
      "## The site": "0cb8dd9a6f8a0096",
-     "## Making games": "bb715272fd1a615b",
+     "## Making games": [
+      "644c1e7608bb9740",
+      "bb715272fd1a615b"
+     ],
      "## The Game Codex and progress": "0738ef719cef3a4c",
      "## Art direction and models": "a48fff7bf0a5f2fc",
      "## Running live games (the back office)": "51ebf2ab756f6e4d",
-     "## Servers and AI seats": "1ccfd549d2369a60",
-     "## Selling things (the shop)": "0df5a5fe1833c624",
+     "## Servers and AI seats": [
+      "1904f45b599a33e4",
+      "1ccfd549d2369a60"
+     ],
+     "## Selling things (the shop)": [
+      "0df5a5fe1833c624",
+      "e5bd380cb77f2b11"
+     ],
      "## Continuing a build from the Claude app": "0d68081e924ca419",
      "## Rules": "b2234d80f6cbe71d",
      "## Telling Homie": "80b46fdd9e578db8",
@@ -4801,7 +4816,136 @@
     "Homie Arcade": {
      "sections": {
       "AGENTS.md": {
-       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+       "## Commands (all through the pinned CLI in node_modules)": [
+        "0a7b2c36414a29a0",
+        "8364e05cebefcba4"
+       ]
+      }
+     }
+    }
+   }
+  },
+  "0.58.21": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "2ecf713305fd26f5",
+     "## Commands (all through the pinned CLI in node_modules)": "661cbdf5d6a9dbae",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "644c1e7608bb9740",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1904f45b599a33e4",
+     "## Selling things (the shop)": "e5bd380cb77f2b11",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "0a7b2c36414a29a0"
+      }
+     }
+    }
+   }
+  },
+  "0.58.22": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "2ecf713305fd26f5",
+     "## Commands (all through the pinned CLI in node_modules)": "661cbdf5d6a9dbae",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "644c1e7608bb9740",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1904f45b599a33e4",
+     "## Selling things (the shop)": "e5bd380cb77f2b11",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "0a7b2c36414a29a0"
+      }
+     }
+    }
+   }
+  },
+  "0.58.23": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "2ecf713305fd26f5",
+     "## Commands (all through the pinned CLI in node_modules)": "661cbdf5d6a9dbae",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "644c1e7608bb9740",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1904f45b599a33e4",
+     "## Selling things (the shop)": "e5bd380cb77f2b11",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "0a7b2c36414a29a0"
       }
      }
     }

package/package.json

@@ -1,10 +1,24 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.58.20",
-  "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
+  "version": "0.58.23",
+  "description": "Open-source tools that let your AI build and run a multiplayer game studio on its own Cloudflare: an MCP server, multiplayer starters, Workers and Durable Objects.",
   "type": "module",
   "license": "Apache-2.0",
-  "homepage": "https://homie.rocks/studio/",
+  "homepage": "https://homie.rocks/make/studio/",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "ai-agents",
+    "multiplayer",
+    "multiplayer-games",
+    "game-studio",
+    "game-engine",
+    "cloudflare-workers",
+    "durable-objects",
+    "cloudflare",
+    "netplay",
+    "open-source"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/homie-rocks/homie.git",
@@ -168,11 +182,12 @@
     "zod": "4.3.6"
   },
   "scripts": {
+    "pretest": "tsc --build ../../tsconfig.json",
     "test": "node --test --test-concurrency=2 --test-timeout=1800000 test/*.test.mjs",
-    "prepack": "node lib/build-identity.mjs --check && node ../../scripts/authoring-guides.mjs --check"
+    "prepack": "node lib/build-identity.mjs --check && node ../../scripts/authoring-guides.mjs --check && node ../../scripts/studio-template-history.mjs --check"
   },
   "peerDependencies": {
-    "@homie-rocks/physics": "0.1.2"
+    "@homie-rocks/physics": "0.1.3"
   },
   "peerDependenciesMeta": {
     "@homie-rocks/physics": {