@homie-rocks/studio 0.48.4 → 0.50.0

package/lib/mcp-tools.mjs

@@ -339,7 +339,7 @@ async function studioCard(ctx, root) {
     const cover = budget > 0 ? coverData(g.dir) : null;
     if (cover) budget -= cover.length;
     const isLive = live && onLine.has(g.id);
-    return { id: g.id, name: String(g.name ?? g.id).slice(0, 60), blurb: String(g.blurb ?? '').slice(0, 160), cover, live: Boolean(isLive), play: { dev: dev ? `${dev.url}/${g.id}/play` : null, live: isLive ? `${live}/${g.id}/play` : null }, page: isLive ? `${live}/${g.id}/` : null };
+    return { id: g.id, name: String(g.name ?? g.id).slice(0, 60), blurb: String(g.blurb ?? '').slice(0, 160), cover, live: Boolean(isLive), play: { dev: dev ? `${dev.url}/${g.id}/${g.kind === 'app' ? 'open' : 'play'}` : null, live: isLive ? `${live}/${g.id}/${g.kind === 'app' ? 'open' : 'play'}` : null }, page: isLive ? `${live}/${g.id}/` : null };
   });
   const posts = (() => { try { return readdirSync(join(root, 'posts')).filter((f) => /\.md$/.test(f) && f !== 'README.md' && !/^[_.]/.test(f)).length; } catch { return 0; } })();
   let rooms = [];
@@ -350,7 +350,8 @@ async function studioCard(ctx, root) {
       rooms = (Array.isArray(body?.rooms) ? body.rooms : []).slice(0, 8).map((r) => ({ game: String(r.game ?? '').slice(0, 40), room: String(r.room ?? '').slice(0, 20), players: Number(r.players) || 0 }));
     } catch { rooms = []; }
   }
-  const demo = games.length ? null : await demoGames({ timeoutMs: 4000 }).then((d) => ({ name: d.pick.name, play: d.pick.play, studio: d.studio.name })).catch(() => null);
+  const appStudio = ['business', 'cause', 'app'].includes(studio.kind);
+  const demo = games.length || appStudio ? null : await demoGames({ timeoutMs: 4000 }).then((d) => ({ name: d.pick.name, play: d.pick.play, studio: d.studio.name })).catch(() => null);
   const data = {
     kind: 'studio', folder: basename(root), root, name: studio.name, tagline: studio.tagline ?? null,
     games, songs: published(root, 'music'), videos: published(root, 'videos'), posts,
@@ -360,7 +361,7 @@ async function studioCard(ctx, root) {
   if (behind) data.behind = { ...behind, whatsNew: behind.whatsNew ? { ...behind.whatsNew, versions: behind.whatsNew.versions.slice(0, 6).map(({ version, summary, upgrade }) => ({ version, summary, upgrade: upgrade.slice(0, 2) })) } : null };
   const text = [
     `${studio.name} (${root})`,
-    games.length ? `Games: ${games.map((g) => `${g.name} (${g.id}${live ? (g.live ? ', live' : ', not deployed yet') : ''})`).join(', ')}` : 'No game yet: its home page says "First game coming soon".',
+    games.length ? `${appStudio ? 'Apps' : 'Apps and games'}: ${games.map((g) => `${g.name} (${g.id}${live ? (g.live ? ', live' : ', not deployed yet') : ''})`).join(', ')}` : appStudio ? 'No app yet: app new creates your first live app.' : 'No game yet: its home page says "First game coming soon".',
     dev ? `Running here: ${dev.url}/` : 'Not running here (preview_run starts it).',
     live ? `Live: ${live}/` : 'Not online yet (studio_deploy).',
     ...(rooms.length ? [`Live rooms: ${rooms.map((r) => `${r.game} ${r.room} (${r.players})`).join(', ')}`] : []),
@@ -814,8 +815,8 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_scaffold', title: 'Make a studio',
-      description: 'Step 1: make a new game studio ON THIS COMPUTER, in the studios folder: one folder with AGENTS.md, games/, music/, videos/, posts/ and a site that later goes online on the studio\'s own Cloudflare (their account). It has NO game: its home page says "First game coming soon". Then installs its pinned toolkit (npm install, in the background). Never put a game in it the person did not ask for.',
-      inputSchema: { type: 'object', properties: { name: str('The studio\'s name, e.g. "Night Owls"'), folder: str('Optional: the folder name inside the studios folder (default: from the name)') } },
+      description: 'Make a studio for a business, cause, app or game ON THIS COMPUTER, in the studios folder: one folder with AGENTS.md, games/, music/, videos/, posts/ and a site that later goes online on the studio\'s own Cloudflare (their account). Choose kind business or cause for an app-first setup. Proceed through setup, build and checks without waiting unless asked. Then installs its pinned toolkit (npm install, in the background). Never put a game in it the person did not ask for.',
+      inputSchema: { type: 'object', properties: { name: str('The studio\'s name, e.g. "Night Owls"'), kind: { type: 'string', enum: ['game', 'business', 'cause', 'app'], description: 'Use business or cause for customer apps' }, folder: str('Optional: the folder name inside the studios folder (default: from the name)') } },
       annotations: { title: 'Make a studio', ...RW }, _meta: ui(UI.setup),
       run: async (a) => {
         const name = String(a.name ?? '').trim().slice(0, 60) || 'My Studio';
@@ -833,7 +834,7 @@ export function toolDefs(ctx, avail = {}) {
         let at = dir;
         if (existsSync(at) && readdirSync(at).some((f) => !['.DS_Store', '.git'].includes(f)) && !existsSync(join(at, 'studio.json'))) at = `${dir}-studio`;
         let made;
-        try { made = newStudio(at, { name, install: false, ...(ctx.directory ? { homie: ctx.directory } : {}) }); } catch (error) { return fail(error.message); }
+        try { made = newStudio(at, { name, kind: a.kind ?? 'game', install: false, ...(ctx.directory ? { homie: ctx.directory } : {}) }); } catch (error) { return fail(error.message); }
         ctx.current = made.dir;
         ctx.note(made.dir).earlier = earlier.map((e) => e.path);
         let install = null;
@@ -844,7 +845,7 @@ export function toolDefs(ctx, avail = {}) {
         }
         const r = await setupCard(ctx, made.dir, { install, made: { dir: made.dir, wrote: made.wrote } });
         const fold = earlier.length ? `\n\nAn earlier folder for this name is on this computer, and it is not a studio: ${earlier.map((e) => `${e.path} (${e.files.join(', ') || 'empty'})`).join('; ')}. ASK the person: fold its premise into ${name}? With their yes, studio_fold { "from": "<that folder>" } copies its notes into the studio (notes/earlier/) and shows them to you, so the plan can use them. Then, only with another yes, studio_fold { "from": "<that folder>", "remove": true } moves the old folder to the Trash.` : '';
-        r.content[0].text = `Made ${name} at ${made.dir} (no game yet: its home page says "First game coming soon").\nWrote: ${made.wrote.join(', ')}\n${!install ? '' : install.endedAt ? (install.code === 0 ? 'Its toolkit is installed.' : `npm install failed: ${whyOf(install)}`) : `Its toolkit is installing (job ${install.id}).`}${fold}\n\n${r.content[0].text}`;
+        r.content[0].text = `Made ${name} at ${made.dir} (${!a.kind || a.kind === 'game' ? 'its home page says "First game coming soon"' : 'ready for the requested app'}).\nWrote: ${made.wrote.join(', ')}\n${!install ? '' : install.endedAt ? (install.code === 0 ? 'Its toolkit is installed.' : `npm install failed: ${whyOf(install)}`) : `Its toolkit is installing (job ${install.id}).`}${fold}${a.kind && a.kind !== 'game' ? '\n\n' + made.next.join('\n') : ''}\n\n${r.content[0].text}`;
         if (r.structuredContent) r.structuredContent.earlier = earlier;
         return r;
       },
@@ -908,12 +909,12 @@ export function toolDefs(ctx, avail = {}) {
     {
       name: 'app_make', title: 'Make an app',
       description: 'Make one morphing screen with customer, staff and wall roles, lasting records and a shared 3D scene. Uses the same engines, netplay, parts and standalone builds as games. No rounds required.',
-      inputSchema: { type: 'object', properties: { id: str('App id: lowercase, digits, hyphens'), name: str('Display name'), ...STUDIO_ARG }, required: ['id', 'name'] },
+      inputSchema: { type: 'object', properties: { id: str('App id: lowercase, digits, hyphens'), name: str('Display name'), from: { type: 'string', enum: ['welcome', 'gathering', 'giving', 'quiz', 'jobs'] }, ...STUDIO_ARG }, required: ['id', 'name'] },
       annotations: { title: 'Make an app', ...RW },
       run: async (a) => {
         if (!GAME_ID.test(String(a.id ?? ''))) return fail('invalid app id');
         const root = ctx.root(a.studio);
-        const r = await cli(ctx, root, `app new ${a.id}`, ['app', 'new', a.id, '--name', String(a.name ?? a.id).slice(0, 60)]);
+        const r = await cli(ctx, root, `app new ${a.id}`, ['app', 'new', a.id, '--from', a.from ?? 'welcome', '--name', String(a.name ?? a.id).slice(0, 60)]);
         if (!r.ended) return stillRunning(r.job, 'Making the app');
         if (r.job.code !== 0) return fail(`Not made: ${whyOf(r.job)}`);
         let install = '';
@@ -921,7 +922,7 @@ export function toolDefs(ctx, avail = {}) {
           if (ctx.install) { const job = runningJobs(root).find((j) => j.label.startsWith('npm install')) ?? installJob(root); install = ` Dependencies are installing (job ${job.id}); wait for studio_job.`; }
           else install = ' Run studio_install for its engine dependencies.';
         }
-        return ok(`apps/${a.id} is ready.${install} Build, dev --lan, then check. Follow the app skill: one screen, roles and parts.`, { kind: 'app', ...r.result });
+        return ok(`apps/${a.id} plumbing is ready.${install} Read the app and plan guides. Capture the person’s dream in apps/${a.id}/CODEX.md, design their scene with engines, style from their words, parts_find and media. Build it; fix failures without flattening. Check and playtest each Codex need with wall and phone evidence.`, { kind: 'app', ...r.result });
       },
     },
     {
@@ -978,25 +979,26 @@ export function toolDefs(ctx, avail = {}) {
       },
     },
     {
-      name: 'game_plan', title: 'Plan a game (its Game Codex)',
+      name: 'game_plan', title: 'Plan a game or app (its Codex)',
       description: 'Step 4: start the game\'s Game Codex (games/<id>/CODEX.md, every section) and record sensible defaults from the request for genre, style, devices, rooms, art, sound and scope. Never route engineering or design questions to the person. A game is planned before it is made: with no game <id> yet, this starts its folder with only the codex. Fill CODEX.md from their request and your defaults in one call (file_write of the whole file, or one file_edit with an edits list), then game_codex shows it. While planning, run `parts find` (the parts_find tool) for each system the game needs, so the plan starts from pieces of existing games and the @homie-rocks/* packages rather than from nothing; the codex\'s Built from section records what was found.',
-      inputSchema: { type: 'object', properties: { id: str('The game\'s id (lowercase, digits, hyphens)'), name: str('Its name, when the game is not made yet'), interview: { type: 'boolean', description: 'Only when the person explicitly requests a planning conversation' }, ...STUDIO_ARG }, required: ['id'] },
+      inputSchema: { type: 'object', properties: { id: str('The game\'s id (lowercase, digits, hyphens)'), name: str('Its name, when the game is not made yet'), kind: { type: 'string', enum: ['game', 'app'], description: 'App plans use apps/<id>/CODEX.md with the person’s scene, people, offers and needs' }, interview: { type: 'boolean', description: 'Only when the person explicitly requests a planning conversation' }, ...STUDIO_ARG }, required: ['id'] },
       annotations: { title: 'Plan a game', ...RW },
       run: async (a) => {
         const root = ctx.root(a.studio);
-        const file = join(root, 'games', String(a.id), 'CODEX.md');
+        const folder = a.kind === 'app' || existsSync(join(root, 'apps', String(a.id))) ? 'apps' : 'games';
+        const file = join(root, folder, String(a.id), 'CODEX.md');
         let made = null;
         if (!existsSync(file)) {
-          made = newCodex(root, String(a.id), { name: a.name ?? null });
+          made = newCodex(root, String(a.id), { name: a.name ?? null, kind: folder === 'apps' ? 'app' : 'game' });
           if (!made.ok) return fail(made.why);
         }
         const guide = a.interview === true && ctx.skillsDir && existsSync(join(ctx.skillsDir, 'plan', 'references', 'INTERVIEW.md')) ? readFileSync(join(ctx.skillsDir, 'plan', 'references', 'INTERVIEW.md'), 'utf8') : null;
         return ok([
-          made ? `Wrote games/${a.id}/CODEX.md (every section${made.planned ? '; the game is planned here before it is made' : ''}).` : `games/${a.id}/CODEX.md is there already: change it, never replace it.`,
-          'From the request and sensible defaults, fill CODEX.md in one call, then show it with game_codex and continue building. New games are rules plus view with room.host server; read the game guide and RULES.md. Choose phone and computer controls, a small first version, local sound and CC0 art. Infer persistent progress from the premise. No interview unless the person explicitly asks to plan together; no engineering or design questions.',
+          made ? `Wrote ${folder}/${a.id}/CODEX.md (every section${made.planned ? '; the game is planned here before it is made' : ''}).` : `${folder}/${a.id}/CODEX.md is there already: change it, never replace it.`,
+          folder === 'apps' ? 'Fill Their words, Scene, People and surfaces, Offers and executable Needs from the person’s request. Use the app guide; starter plumbing is not their scene. Show with game_codex, build and prove every need on wall and phone.' : 'From the request and sensible defaults, fill CODEX.md in one call, then show it with game_codex and continue building. New games are rules plus view with room.host server; read the game guide and RULES.md. Choose phone and computer controls, a small first version, local sound and CC0 art. Infer persistent progress from the premise. No interview unless the person explicitly asks to plan together; no engineering or design questions.',
           '', PARTS_FIRST,
           ...(guide ? ['', 'Optional reference for a person who explicitly requests an interview:', guide] : []),
-        ].join('\n'), { kind: 'plan', id: a.id, file: `games/${a.id}/CODEX.md`, created: Boolean(made) });
+        ].join('\n'), { kind: 'plan', id: a.id, file: `${folder}/${a.id}/CODEX.md`, created: Boolean(made) });
       },
     },
     {

package/lib/mcp.mjs

@@ -144,7 +144,7 @@ function promptText(name, args = {}) {
 export async function serveMcp({ studios = null, skills = null, cwd = process.cwd(), input = process.stdin, output = process.stdout, waitMs, directory = null, install = true, desktop = inDesktopApp(), log = (line) => process.stderr.write(`[homie-studio mcp] ${line}\n`) } = {}) {
   // A GUI app starts this with a short PATH: everything it runs sees the usual places Node, npm and ffmpeg live.
   process.env.PATH = toolPath();
-  const skillsDir = skills ?? [join(PACKAGE_ROOT, '..', '..', 'plugins', 'homie', 'skills'), join(PACKAGE_ROOT, '..', 'skills')].find((d) => existsSync(join(d, 'studio-setup', 'SKILL.md'))) ?? null;
+  const skillsDir = skills ?? [join(PACKAGE_ROOT, '..', '..', 'plugins', 'homie', 'skills'), join(PACKAGE_ROOT, '..', 'skills'), join(PACKAGE_ROOT, 'guides')].find((d) => existsSync(join(d, 'studio-setup', 'SKILL.md'))) ?? null;
   const ctx = new StudioContext({ studiosDir: studios, cwd, skillsDir, waitMs: waitMs ?? Number(process.env.HOMIE_MCP_WAIT_MS || 40_000), directory, install, desktop });
   let avail = availability();
   let names = '';

package/lib/parts.mjs

@@ -559,15 +559,15 @@ function liftPlan(root, game, paths) {
   const files = [];
   const walk = (rel) => {
     const abs = join(gdir, rel);
-    if (!existsSync(abs)) throw new Error(`games/${game}/${rel} is not there`);
+    if (!existsSync(abs)) throw new Error(`${relative(root, experienceDir(root, game))}/${rel} is not there`);
     if (statSync(abs).isDirectory()) { for (const e of readdirSync(abs, { withFileTypes: true })) if (!e.name.startsWith('.') && e.name !== 'node_modules') walk(`${rel}/${e.name}`); } else files.push(rel);
   };
   for (const raw of paths) {
     const rel = posix(String(raw)).replace(/^\.\//, '').replace(/^(?:games|apps)\/[^/]+\//, '').replace(/\/+$/, '');
-    if (!rel || rel.split('/').includes('..') || rel.startsWith('/')) throw new Error(`"${raw}" is not a path inside games/${game}`);
+    if (!rel || rel.split('/').includes('..') || rel.startsWith('/')) throw new Error(`"${raw}" is not a path inside ${relative(root, experienceDir(root, game))}`);
     walk(rel);
   }
-  if (!files.length) throw new Error(`name the files of games/${game} that become the part (src/creature.ts, or a folder)`);
+  if (!files.length) throw new Error(`name the files of ${relative(root, experienceDir(root, game))} that become the part (src/creature.ts, or a folder)`);
   // A part is a piece of a game, never the whole game: its entry, its page and its game.json stay the game's.
   let entry = 'src/main.ts';
   try { entry = JSON.parse(readFileSync(experienceFile(root, game), 'utf8')).entry ?? entry; } catch { /* the default entry */ }
@@ -607,7 +607,7 @@ export function newPart(root, id, { kind = 'mechanic', name = null, from = null,
     if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(String(from)) || !existsSync(experienceFile(root, from))) return { ok: false, command: 'parts new', why: `there is no game "${from}" in this studio to lift a part out of` };
     let plan;
     try { plan = liftPlan(root, from, paths); } catch (error) { return { ok: false, command: 'parts new', why: error.message }; }
-    if (plan.outside.length) return { ok: false, command: 'parts new', why: `These files still reach into the rest of games/${from}: ${plan.outside.slice(0, 6).join('; ')}. A part has to stand without the game: lift those files too, or pass what they provide in as an argument first. Nothing was moved.`, outside: plan.outside };
+    if (plan.outside.length) return { ok: false, command: 'parts new', why: `These files still reach into the rest of ${relative(root, experienceDir(root, from))}: ${plan.outside.slice(0, 6).join('; ')}. A part has to stand without the game: lift those files too, or pass what they provide in as an argument first. Nothing was moved.`, outside: plan.outside };
     mkdirSync(dir, { recursive: true });
     lifted = { moved: [], copied: [] };
     for (const f of plan.files) {
@@ -654,7 +654,7 @@ export function newPart(root, id, { kind = 'mechanic', name = null, from = null,
   return {
     ok: true, command: 'parts new', id, dir: `${PARTS_DIR}/${id}`, kind, entry, files: part.files.map((f) => f.path), ...(lifted ? { from, lifted } : {}),
     next: [
-      ...(lifted ? [`games/${from} imports it now (each lifted module's old path re-exports the part's); build the game to see it unchanged.`] : []),
+      ...(lifted ? [`${relative(root, experienceDir(root, from))} imports it now (each lifted module's old path re-exports the part's); build the app or game to see it unchanged.`] : []),
       `Write a one-sentence "summary" in parts/${id}/part.json, and what it needs from a game under "contract".`,
       `Another game of this studio uses it with: import … from '@parts/${id}'`,
       'It is private. Sharing it needs a licence (an SPDX identifier such as CC-BY-4.0) and is live after the studio\'s next deploy.',
@@ -739,7 +739,7 @@ export function syncPartCredits(root, game, origins) {
   if (!existsSync(join(experienceDir(root, game)))) return null;
   const text = `${JSON.stringify({ ...credits, parts: [...keep, ...mine] }, null, 2)}\n`;
   if (!existsSync(file) || readFileSync(file, 'utf8') !== text) writeFileSync(file, text);
-  return `games/${game}/credits.json`;
+  return `${relative(root, experienceDir(root, game))}/credits.json`;
 }
 
 /* ------------------------------------------------------------------ where brought-in parts came from */

package/lib/scaffold.mjs

@@ -1,4 +1,4 @@
-import { FUNCTIONS_META_MIGRATION, FUNCTIONS_META_MIGRATION_FILE, FUNCTIONS_MIGRATION, FUNCTIONS_MIGRATION_FILE, FUNCTIONS_CURSOR_MIGRATION, FUNCTIONS_CURSOR_MIGRATION_FILE } from '../worker/functions-schema.mjs';
+import { FUNCTIONS_REFERENCE_MIGRATION, FUNCTIONS_REFERENCE_MIGRATION_FILE, FUNCTIONS_META_MIGRATION, FUNCTIONS_META_MIGRATION_FILE, FUNCTIONS_MIGRATION, FUNCTIONS_MIGRATION_FILE, FUNCTIONS_CURSOR_MIGRATION, FUNCTIONS_CURSOR_MIGRATION_FILE } from '../worker/functions-schema.mjs';
 import { MCP_MIGRATION, MCP_MIGRATION_FILE } from '../worker/mcp-store.mjs';
 import { APPS_MIGRATION, APPS_MIGRATION_FILE } from '../worker/app-records.mjs';
 import { PURCHASE_MIGRATION, PURCHASE_MIGRATION_FILE, PURCHASE_STATE, PURCHASE_STATE_FILE } from '../worker/purchase-schema.mjs';
@@ -40,7 +40,7 @@ import { rulesIndex } from './studio.mjs';
 
 export const COMPAT_DATE = '2026-06-01';
 /** 4.135.0 or later: Worker Previews (`wrangler preview`, a Durable Object namespace per Preview). */
-export const WRANGLER_VERSION = '4.145.0';
+export const WRANGLER_VERSION = '4.150.0';
 /**
  * The TypeScript a new studio asks for, so `build --types` (and an editor) has a compiler: the studio's own
  * devDependency, never one of the toolkit's (a studio that never checks types pays nothing for it at runtime).
@@ -112,11 +112,28 @@ ${JSON.stringify(config, null, 2)}
 `;
 }
 
-export function agentsMd({ name, slug }) {
+export function agentsMd({ name, slug, kind = 'game' }) {
+  if (kind !== 'game') return `# ${name}
+
+This is **${name}** (\`${slug}\`), a ${kind === 'cause' ? 'cause' : 'business'} studio. Its apps, pages and shop run on its own Cloudflare account.
+
+Read \`node_modules/@homie-rocks/studio/guides/app/SKILL.md\` and the shared \`guides/plan/SKILL.md\` first. Capture the owner’s exact dream, scene, people, offers and demonstrable needs in \`apps/<id>/CODEX.md\` (\`codex new <id> --kind app\`). A starter is plumbing, never the deliverable. Build their scene with the engine packages, style from their words, parts_find and appropriate art/models/sound/music. Fix build failures without flattening the scene. End with every Codex need shown on wall and phone and judged through the playtest guide. Proceed from the owner's request through building and checking; ask for an interview only when requested or when essential information is missing.
+
+- \`apps/<id>/app.json\` defines the app's words, roles, records and surfaces; \`src/view.ts\` draws it.
+- \`site/pages/<path>/index.html\` adds a page and a header link. A page at an app's id replaces its landing, while \`/<id>/open\` and \`/<id>/tv\` remain the phone and wall entrances.
+- \`shop.json\` defines products, services or gifts. Local dev previews items before Stripe is connected.
+- \`studio.json\` names the organisation and its currency. \`site/theme.json\` sets its colours and fonts.
+
+Start with \`homie-studio app new <id> --from welcome|gathering|giving|quiz|jobs\`, then \`npm install\`, \`npm run build\`, \`npm run dev\`. Use the printed address; a busy port is skipped. Run \`homie-studio check <id> --url <address> --shots .checks\` and inspect the wall and phone captures.
+
+For gifts, use \`homie-studio shop init --giving --currency <currency>\`. The organisation supplies its own receipt/tax wording. The giving wall records intentions, not paid gifts. Service requests are not confirmed reservations.
+
+Keep credentials, private staff links and personal records out of source control. Use the studio's own roles and records APIs. Publish only when the owner requests it. Existing authored files belong to the owner; do not overwrite them during upgrades.
+`;
   return `# ${name}
 
 This folder is a studio: **${name}** (\`${slug}\`). It is one repository.
-Its games, music, videos and posts live here; its website and public game rooms
+${kind === 'game' ? 'Its games, music, videos and posts live here;' : 'Its apps and public pages live here. Read node_modules/@homie-rocks/studio/guides/app/SKILL.md first;'} its website and public game rooms
 run on the studio's **own Cloudflare account** (one Worker, one D1 database and
 the Table/Lobby Durable Objects, on the studio's Cloudflare account), built
 from \`@homie-rocks/studio\`, pinned in \`package.json\`. The homie.rocks
@@ -156,6 +173,8 @@ 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.
+
 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.
 
 An app is ONE screen that morphs with context: camera moves, panels unfold, its roles see and do different things, and parts plug into the scene. No page-to-page navigation or menus of links inside it. Use all the same engine packages and media skills as games (camera, geom, props, render, postfx, fx, audio, input, ui-world; style, art, models, animate, music, sound, video). It can be fully 3D and wild while remaining useful and legible.
@@ -679,7 +698,7 @@ anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site
 | \`theme.json\` | The look: \`bg\`, \`fg\`, \`accent\`, \`glow\` colours, \`display\` and \`text\` fonts (\`fonts\` loads a file from \`public/\`), \`radius\`, \`mark\` (a logo). Or \`palette\`: neon, dock, gold, acid, ember, orchid, tide, candy. |
 | \`theme.css\` | Extra CSS on every page (restyle anything, the "Made with Homie" footer included). |
 | \`partials/<name>.html\` | A piece of every page: \`head\`, \`header\`, \`footer\`, \`home\` (a band on Home), \`game\` (a band on every game's landing), \`game-<id>\` (on one game's), \`post\`. |
-| \`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 -->\`, and \`<!-- homie:schema -->\` in its \`<head>\` (the page's structured data for search engines). A Home of your own (\`pages/index.html\`) takes the generated hero with \`<!-- homie:home-hero -->\` (the featured game) or \`<!-- homie:home-hero <id> -->\` (that game); a game's own hero files are served at \`/games/<id>/_landing/<file>\` (\`wide.jpg\`, \`tall.jpg\`, \`wide.mp4\`, \`tall.mp4\`) if a page of yours needs one by address (\`/api/games\` says each exactly, in \`landing.hero\`). |
+| \`pages/<path>/index.html\` | A whole page at \`/<path>/\`, instead of the generated one (\`pages/<id>/index.html\` replaces an app or game landing; the app still opens at \`/<id>/open\` and its wall at \`/<id>/tv\`) or beside them (\`pages/about/index.html\`). It may borrow \`<!-- homie:style -->\`, \`<!-- homie:header -->\`, \`<!-- homie:footer -->\`, \`<!-- homie:script -->\`, and \`<!-- homie:schema -->\` in its \`<head>\` (the page's structured data for search engines). A Home of your own (\`pages/index.html\`) takes the generated hero with \`<!-- homie:home-hero -->\` (the featured game) or \`<!-- homie:home-hero <id> -->\` (that game); a game's own hero files are served at \`/games/<id>/_landing/<file>\` (\`wide.jpg\`, \`tall.jpg\`, \`wide.mp4\`, \`tall.mp4\`) if a page of yours needs one by address (\`/api/games\` says each exactly, in \`landing.hero\`). |
 | \`public/\` | Files served as they are, at the same path (\`public/fonts/x.woff2\` is \`/fonts/x.woff2\`). A \`robots.txt\`, \`sitemap.xml\` or \`llms.txt\` here replaces the one the site makes. |
 
 \`src/worker.mjs\` and \`migrations/\` are the Worker (its config is \`wrangler.jsonc\`, at the studio's root); \`dist/\` is the build (not committed).
@@ -726,10 +745,11 @@ art/**/raw/
 `;
 
 /** Every file a new studio gets, relative to its folder. */
-export function studioFiles({ name, slug, homie, template = false }) {
+export function studioFiles({ name, slug, homie, template = false, kind = 'game' }) {
   const worker = slug;
   const studio = {
     name, slug,
+    ...(kind !== 'game' ? { kind } : {}),
     // 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 } : {}),
@@ -759,7 +779,7 @@ export function studioFiles({ name, slug, homie, template = false }) {
     },
   };
   const files = {
-    'AGENTS.md': agentsMd({ name, slug }),
+    'AGENTS.md': agentsMd({ name, slug, kind }),
     'CLAUDE.md': claudeMd(),
     'README.md': template ? templateReadme() : readme({ name }),
     'HANDOFF.md': HANDOFF_MD,
@@ -775,6 +795,7 @@ export function studioFiles({ name, slug, homie, template = false }) {
     'posts/README.md': POSTS_README,
     'site/theme.json': themeFile(slug),
     'site/README.md': SITE_README,
+    'site/pages/.gitkeep': '',
     'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1, and R2 once storage is added.
 // The code is @homie-rocks/studio's, pinned in package.json, so an update never changes a published game by surprise.
 import { hostRules, useTools } from '@homie-rocks/studio/worker';
@@ -803,6 +824,7 @@ export { default, Table, Lobby, Gate, Concentrator } from '@homie-rocks/studio/w
     [`site/migrations/${FUNCTIONS_MIGRATION_FILE}`]: FUNCTIONS_MIGRATION,
     [`site/migrations/${FUNCTIONS_CURSOR_MIGRATION_FILE}`]: FUNCTIONS_CURSOR_MIGRATION,
     [`site/migrations/${FUNCTIONS_META_MIGRATION_FILE}`]: FUNCTIONS_META_MIGRATION,
+    [`site/migrations/${FUNCTIONS_REFERENCE_MIGRATION_FILE}`]: FUNCTIONS_REFERENCE_MIGRATION,
     [`site/migrations/${LOUNGE_MIGRATION_FILE}`]: LOUNGE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
@@ -974,6 +996,11 @@ function ensurePartsStateMigration(root) {
   return `site/migrations/${PURCHASE_STATE_FILE}`;
 }
 
+function ensureFunctionReference(root) {
+  const file=join(root,'site','migrations',FUNCTIONS_REFERENCE_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,FUNCTIONS_REFERENCE_MIGRATION);return `site/migrations/${FUNCTIONS_REFERENCE_MIGRATION_FILE}`;
+}
 function ensureFunctionMeta(root) {
   const file=join(root,'site','migrations',FUNCTIONS_META_MIGRATION_FILE);
   if(existsSync(file))return null;
@@ -995,7 +1022,7 @@ function ensureMcpMigration(root) {
   mkdirSync(dirname(file),{recursive:true});writeFileSync(file,MCP_MIGRATION);return `site/migrations/${MCP_MIGRATION_FILE}`;
 }
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopStatements(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root), ensureFunctionReference(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */
@@ -1019,7 +1046,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, template = false } = {}) {
+export function newStudio(folder, { name, homie, slug: askedSlug, install = true, template = false, kind = 'game' } = {}) {
   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()));
@@ -1034,7 +1061,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', template });
+  const files = studioFiles({ name: String(name).trim(), slug, homie: homie || 'https://homie.rocks', template, kind });
   mkdirSync(dir, { recursive: true });
   const wrote = [];
   for (const [rel, content] of Object.entries(files)) {
@@ -1058,7 +1085,14 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
     } catch (error) { installed = `npm install failed (${String(error.stderr ?? error.message).trim().split('\n').slice(-2).join(' ')}): run it in the studio folder`; }
   }
   const q = JSON.stringify(realpathSync(dir));
-  return { ok: true, command: 'new', dir: realpathSync(dir), name, slug, wrote, git, installed, studio: STUDIO_VERSION, next: [
+  return { ok: true, command: 'new', dir: realpathSync(dir), name, slug, wrote, git, installed, studio: STUDIO_VERSION, next: kind !== 'game' ? [
+    `cd ${q}`,
+    'Read the app and shared plan guides. Create apps/<id>/CODEX.md with codex new <id> --kind app; capture their words, scene, people, offers and testable needs. Proceed without an engineering interview.',
+    'npx --no-install homie-studio app new <id> --from welcome --name "<Name>"',
+    'Starter = plumbing only. Install dependencies, style init from their words, parts find, design and build their living scene; repair failures without flattening it. npm run build; npm run dev (use the printed address)',
+    'npx --no-install homie-studio check <id> --url <printed address> --shots .checks',
+    'The phone opens /<id>/open; the wall /<id>/tv. Publish when requested.',
+  ] : [
     `cd ${q}${install ? '' : ' && npm install'}`,
     'read the game skill and RULES.md; choose sensible defaults and make the requested game as server rules plus view',
     'optional live example, without copying a game here: npx --no-install homie-studio demo',

package/lib/shop-links.mjs

@@ -39,7 +39,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     else if (!same(product.metadata, metadata) || product.name !== fields.name || (product.description ?? '') !== fields.description || (product.tax_code?.id ?? product.tax_code) !== fields.tax_code || !product.active) await api('POST', `/v1/products/${id}`, fields);
     // Omit an unset minimum: Stripe applies its settlement-currency floor itself.
     // https://docs.stripe.com/api/prices/create#create_price-custom_unit_amount-minimum
-    const priceFields = { product: id, currency: shop.currency, tax_behavior: 'exclusive', ...(item.price === 'choose'
+    const priceFields = { product: id, currency: shop.currency, ...(item.interval ? { recurring: { interval: item.interval } } : {}), tax_behavior: 'exclusive', ...(item.price === 'choose'
       ? { custom_unit_amount: { enabled: true, ...(item.min > 0 ? { minimum: item.min } : {}), ...(item.max !== null ? { maximum: item.max } : {}) } }
       : { unit_amount: item.price }) };
     const revision = hash(priceFields);
@@ -52,7 +52,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const params = { line_items: [{ price: price.id, quantity: 1, ...(item.price !== 'choose' ? { adjustable_quantity: { enabled: shop.policy.repeatPurchases, minimum: 1, maximum: 999999 } } : {}) }],
       after_completion: { type: 'redirect', redirect: { url: `${site}/shop/thanks?session_id={CHECKOUT_SESSION_ID}` } },
       ...(shop.till === 'stripe-managed' ? { managed_payments: { enabled: true } } : { automatic_tax: { enabled: shop.automaticTax } }),
-      payment_intent_data: { metadata },
+      ...(item.interval ? { subscription_data: { metadata } } : { payment_intent_data: { metadata } }),
     };
     const linkRevision = hash({ params, item, policy: shop.policy });
     let link = links.find((p) => own(p) && p.metadata?.revision === linkRevision);

package/lib/shop.mjs

@@ -107,13 +107,15 @@ export function supporterItem({ price = 500, days = 365, name = 'Supporter' } =
   return { id: 'supporter', kind: 'supporter', name, price, days, gives: ['badge:supporter'], badge: 'Supporter', blurb: 'A Supporter badge on your account and beside your name in rooms, for a year. It changes nothing about how any game plays.' };
 }
 
-export function shopInit(root, { supporter = false, currency = 'usd', price = 500, managed = false } = {}) {
+export function shopInit(root, { supporter = false, giving = false, currency = null, price = 500, managed = false } = {}) {
   const file = join(root, SHOP_FILE);
   if (existsSync(file)) return { ok: false, command: 'shop init', why: 'shop.json is here already: change it, then homie-studio shop check' };
   const studio = readStudio(root);
+  if (giving && !currency && !studio.currency) return { ok: false, command: 'shop init', why: 'Set studio.json currency or give --currency for gifts.' };
   const shop = {
-    till: managed ? 'stripe-managed' : 'stripe', currency: String(currency).toLowerCase(),
-    items: supporter ? [supporterItem({ price: Number(price) })] : [],
+    ...(giving ? { giving: { receiptText: '' } } : {}),
+    till: managed ? 'stripe-managed' : 'stripe', currency: String(currency ?? studio.currency ?? 'usd').toLowerCase(),
+    items: giving ? [1000, 2500, 5000].flatMap(amount => [false, true].map(monthly => ({ id: `gift-${amount}${monthly ? '-monthly' : ''}`, kind: 'donation', name: monthly ? 'Monthly gift' : 'One-time gift', price: amount, ...(monthly ? { interval: 'month' } : {}), gives: [], blurb: monthly ? 'Give this amount each month. Manage your gift through Stripe.' : 'A gift to support our work.' }))) : supporter ? [supporterItem({ price: Number(price) })] : [],
   };
   const r = checkShop(shop, { games: listGames(root).map((g) => g.id) });
   if (!r.ok) return { ok: false, command: 'shop init', why: r.errors.map((e) => e.message).join('; ') };

package/lib/studio.mjs

@@ -90,7 +90,7 @@ export function listExperiences(root) {
   for (const row of rows) { if (ids.has(row.id)) throw new Error(`app/game id collision: ${row.id}`); ids.add(row.id); }
   return rows;
 }
-export const experienceDir = (root, id) => join(root, existsSync(join(root, 'apps', id, 'app.json')) ? 'apps' : 'games', id);
+export const experienceDir = (root, id) => join(root, (existsSync(join(root, 'apps', id, 'app.json')) || existsSync(join(root, 'apps', id, 'CODEX.md'))) ? 'apps' : 'games', id);
 export const experienceFile = (root, id) => join(experienceDir(root, id), existsSync(join(root, 'apps', id, 'app.json')) ? 'app.json' : 'game.json');
 function listKind(root, kind) {
   const dir = join(root, `${kind}s`);
@@ -300,16 +300,17 @@ export function addNeeds(root, needs) {
 }
 
 
-export async function newApp(root, id, { name } = {}) {
+export async function newApp(root, id, { name, from = 'welcome' } = {}) {
   if (!GAME_ID.test(String(id ?? '')) || RESERVED_IDS.has(id)) throw new Error('invalid app id');
-  if (listExperiences(root).some((g) => g.id === id) || existsSync(join(root, 'apps', id))) throw new Error(`app/game ${id} already exists`);
+  if (listExperiences(root).some((g) => g.id === id) || (existsSync(join(root, 'apps', id)) && readdirSync(join(root, 'apps', id)).some(f => !['CODEX.md', 'codex', 'style.json'].includes(f)))) throw new Error(`app/game ${id} already exists`);
   const dest = join(root, 'apps', id);
-  cpSync(join(PACKAGE_ROOT, 'app-starters', 'welcome'), dest, { recursive: true });
+  if (!['welcome', 'giving', 'gathering', 'quiz', 'jobs'].includes(from)) throw new Error('app starter: welcome, giving, gathering, quiz or jobs');
+  cpSync(join(PACKAGE_ROOT, 'app-starters', from), dest, { recursive: true });
   const file = join(dest, 'app.json');
   const meta = JSON.parse(readFileSync(file, 'utf8'));
-  meta.id = id; meta.name = String(name ?? 'Welcome together').slice(0, 60);
+  meta.id = id; meta.name = String(name ?? meta.name).slice(0, 60);
   writeFileSync(file, `${JSON.stringify(meta, null, 2)}\n`);
   const main = join(dest, meta.entry ?? 'src/main.ts');
   writeFileSync(main, readFileSync(main, 'utf8').replaceAll("game: 'welcome'", `game: '${id}'`));
-  return { ok: true, command: 'app new', id, dir: dest, files: readdirSync(dest, { recursive: true }).map(String), ...addNeeds(root, meta.needs) };
+  return { ok: true, command: 'app new', id, from, dir: dest, files: readdirSync(dest, { recursive: true }).map(String), ...addNeeds(root, meta.needs), next: ['This starter is plumbing: roles, records, room and a check. It is not the deliverable.', 'Read guides/plan/SKILL.md and guides/app/SKILL.md in the installed toolkit. Capture the person’s scene, people, offers and demonstrable needs in apps/' + id + '/CODEX.md. Build that scene with engines, style and shared parts; repair build failures without flattening it.', 'Install reported dependencies, build, and prove every Codex need on wall and phone before calling it done.'] };
 }

package/lib/template-history.json

@@ -3111,6 +3111,90 @@
      }
     }
    }
+  },
+  "0.49.0": {
+   "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)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "8596f2b25edda3e2",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "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)": "9e020d69dd6a954e",
+     "## 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)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
+  },
+  "0.50.0": {
+   "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)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "5222e08ca55e326e",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "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)": "9e020d69dd6a954e",
+     "## 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)": "611b437f5b3303f0"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.48.4",
+  "version": "0.50.0",
   "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.",
   "type": "module",
   "license": "Apache-2.0",
@@ -141,11 +141,11 @@
     "@gltf-transform/extensions": "4.5.1",
     "@gltf-transform/functions": "4.5.1",
     "@jridgewell/trace-mapping": "0.3.31",
-    "@modelcontextprotocol/sdk": "1.30.0",
-    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "@x402/core": "2.28.0",
     "@x402/evm": "2.28.0",
-    "agents": "0.28.0",
+    "agents": "0.28.1",
     "esbuild": "0.28.1",
     "gltf-validator": "2.0.0-dev.3.10",
     "jose": "6.2.12",

package/shop/SHOP.md

@@ -215,3 +215,7 @@ itemButton.onclick = () => shop.open('supporter');
 ```
 
 These calls open the same shop in games and apps. Inside a player card, purchases leave for the studio's shop; ordinary play/open pages start Stripe checkout. The studio's TV and kids policies still apply.
+
+## App payment references
+
+Create the booking/ticket/gift intention first. `shop.buy('full-tune', 1, undefined, { reference: booking.id })` or `shop.checkout({ reference: booking.id })` sends the app's own reference through checkout. Existing boolean returns are unchanged: checkout opened is not paid. The verified durable `order.paid` event carries `data.order`, `data.reference` (null if omitted) and `data.app`. Reopened Payment Links retain the reference. A reference is buyer-supplied correlation, not authorization: verify the record, app, amount and currency, deduplicate by event/order ID, then fulfil it. Keep personal data out of references. Before Stripe is connected, local prices and unpaid requests can be demonstrated; actual payment and recurring collection remain unverified. Test events must be labelled simulations.

package/shop/shop.ts

@@ -61,8 +61,8 @@ export interface Shop {
   add(item: string, quantity?: number, amount?: number): void;
   cart(): CartLine[];
   clear(): void;
-  checkout(): Promise<boolean>;
-  buy(item: string, quantity?: number, amount?: number): Promise<boolean>;
+  checkout(options?: { reference?: string }): Promise<boolean>;
+  buy(item: string, quantity?: number, amount?: number, options?: { reference?: string }): Promise<boolean>;
   /** Mark an item used; the studio's refundUsedItems policy decides whether self-service refunds still apply. */
   used(key: string): Promise<boolean>;
   on(ev: 'change', fn: (owns: string[]) => void): () => void;
@@ -129,8 +129,8 @@ export function createShop(opts: ShopOptions = {}): Shop {
     add: (item, quantity = 1, amount) => { cart.push({ item, quantity, ...(amount === undefined ? {} : { amount }) }); },
     cart: () => cart.map((line) => ({ ...line })),
     clear: () => { cart = []; },
-    checkout: async () => { const ok = Boolean((await send({ op: 'checkout', lines: cart })).ok); if (ok) cart = []; return ok; },
-    buy: async (item, quantity = 1, amount) => Boolean((await send({ op: 'checkout', lines: [{ item, quantity, ...(amount === undefined ? {} : { amount }) }] })).ok),
+    checkout: async (options = {}) => { const ok = Boolean((await send({ op: 'checkout', lines: cart, reference: options.reference })).ok); if (ok) cart = []; return ok; },
+    buy: async (item, quantity = 1, amount, options = {}) => Boolean((await send({ op: 'checkout', reference: options.reference, lines: [{ item, quantity, ...(amount === undefined ? {} : { amount }) }] })).ok),
     close: () => { void send({ op: 'close' }); },
     used: async (key) => (KEY.test(String(key)) && owns.includes(String(key)) ? Boolean((await send({ op: 'used', key })).ok) : false),
     on: ((ev: ShopEvent, fn: (x: unknown) => void) => {

package/worker/app-format.mjs

@@ -21,7 +21,7 @@ export function appProblems(meta) {
     for (const [field, spec] of Object.entries(c.fields)) if (!key.test(field) || !object(spec) || !['string', 'number', 'boolean'].includes(spec.type) || (spec.enum && (!Array.isArray(spec.enum) || !spec.enum.length))) bad.push(`collection ${id}.${field}: invalid field`);
   }
   for (const r of Object.values(roles)) for (const cap of Array.isArray(r?.can) ? r.can : []) if (!Object.hasOwn(meta.records?.collections ?? {}, String(cap).split(':')[1])) bad.push(`unknown collection in ${cap}`);
-  for (const [k, v] of Object.entries(meta.words ?? {})) if (!Object.hasOwn(APP_WORDS, k) || typeof v !== 'string' || !v.trim() || v.length > 60) bad.push(`words.${k}: use a short label`);
+  for (const [k, v] of Object.entries(meta.words ?? {})) if (!/^[a-z][a-zA-Z0-9-]*$/.test(k) || typeof v !== 'string' || v.length > 500) bad.push(`words.${k}: use a short label`);
   return bad;
 }
 export const appWords = (g) => g?.kind === 'app' ? { ...APP_WORDS, ...g.words } : { open: 'Play', join: 'Scan to play', one: 'player', many: 'players' };

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.48.4","sha256":"5a637b57c0a41bb68ece5691250f4f8e7f646d489608a0a2721f571053602b2f"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.50.0","sha256":"817f88f291b3f1dc92e51bb54784034debeabc202a269a2466a1efc2ef07d292"});

package/worker/functions-schema.mjs

@@ -69,3 +69,18 @@ ELSE 0 END BEGIN
  SELECT 'refund:' || json_extract(NEW.value,'$.id'),'payment.refunded',
  json_object('refund',json_extract(NEW.value,'$.id'),'payment',json_extract(NEW.value,'$.payment_intent'),'amount',json_extract(NEW.value,'$.amount'),'currency',json_extract(NEW.value,'$.currency')),json_extract(NEW.value,'$.at')*1000;
 END;`).join('\n');
+
+/** Application correlation is saved before payment; only the paid transition emits it. */
+export const FUNCTIONS_REFERENCE_MIGRATION_FILE = '0021_app_payment_reference.sql';
+export const FUNCTIONS_REFERENCE_MIGRATION = `
+DROP TRIGGER IF EXISTS shop_orders_function_paid;
+CREATE TRIGGER shop_orders_function_paid AFTER UPDATE ON shop_orders
+WHEN EXISTS (SELECT 1 FROM function_subscriptions WHERE type='order.paid')
+ AND OLD.paid_at IS NULL AND NEW.paid_at IS NOT NULL
+ AND NOT EXISTS (SELECT 1 FROM purchase_orders WHERE id=NEW.id) BEGIN
+ INSERT OR IGNORE INTO studio_events(id,type,data,at)
+ VALUES('shop_orders:' || NEW.id || ':paid','order.paid',
+ json_object('order',NEW.id,'source','shop_orders','amount',NEW.amount,'currency',NEW.currency,'mode',NEW.mode,
+ 'app',NEW.game,'reference',(SELECT value FROM meta WHERE key='shop-reference:' || NEW.id)),NEW.paid_at);
+END;
+`;