@homie-rocks/studio 0.49.0 → 0.50.1

package/lib/app-needs.mjs

@@ -0,0 +1,63 @@
+/** Opt-in acceptance evidence, sourced from the person's Codex, not starter labels. */
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+export function readAppNeeds(root, id) {
+  if (!root) return null;
+  const file = join(root, 'apps', id, 'CODEX.md');
+  if (!existsSync(file)) return null;
+  const source = readFileSync(file, 'utf8');
+  const block = /^```needs\s*\n([\s\S]*?)^```/m.exec(source);
+  if (!block) return null; // An existing prose Codex has not opted into executable needs.
+  const needs = JSON.parse(block[1]);
+  if (!Array.isArray(needs) || !needs.length) throw new Error('App Codex has no demonstrable needs yet');
+  const ids = new Set();
+  for (const n of needs) {
+    if (!n || !/^[a-zA-Z0-9_-]+$/.test(n.id ?? '') || ids.has(n.id) || typeof n.statement !== 'string' || !n.statement.trim()) throw new Error('Each Codex need requires a unique id and a statement from the request');
+    ids.add(n.id);
+  }
+  return { needs, hash: createHash('sha256').update(source).digest('hex') };
+}
+
+/** Run real UI actions. A failed or absent flow stays visible; continue collecting other needs. */
+export async function proveAppNeeds({ plan, surfaces, shots, report }) {
+  const results = [];
+  const surface = name => { const s = surfaces.find(s => s.name === name); if (!s) throw new Error(`unknown surface ${name}`); return s; };
+  for (const need of plan.needs) {
+    const result = { id: need.id, statement: need.statement, status: 'not', captures: [] };
+    try {
+      if (!Array.isArray(need.assertions) || !['wall', 'phone'].every(name => need.assertions.some(a => a.surface === name))) throw new Error('needs wall and phone assertions');
+      for (const step of need.steps ?? []) {
+        const { frame, page } = surface(step.surface);
+        if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await page.waitForFunction(() => window.__shell?.link?.state === 'online'); surface(step.surface).frame = page.frames().find(f => /\/__game\//.test(f.url())); continue; }
+        await frame.waitForSelector(step.selector, { visible: true });
+        if (step.click) await frame.click(step.selector);
+        else if (step.fill !== undefined) { await frame.$eval(step.selector, el => { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }); await frame.type(step.selector, String(step.fill)); }
+        else if (step.select !== undefined) await frame.select(step.selector, String(step.select));
+        else throw new Error('step needs click, fill, select or reload');
+      }
+      for (const assertion of need.assertions) {
+        const { frame } = surface(assertion.surface);
+        await frame.waitForSelector(assertion.selector, { visible: true, timeout: 10000 });
+        if (assertion.text !== undefined) await frame.waitForFunction((selector, text) => document.querySelector(selector)?.textContent.includes(text), { timeout: 10000 }, assertion.selector, String(assertion.text));
+      }
+      result.status = shots ? 'met' : 'partly';
+      result.why = shots ? 'UI assertions passed; inspect captures against the pictured scene' : 'Assertions passed but no captures saved';
+    } catch (error) { result.why = error.message; }
+    if (shots) for (const name of ['wall', 'phone']) {
+      const file = join(shots, `${need.id}-${name}.jpg`);
+      try { await surface(name).page.screenshot({ path: file, type: 'jpeg', quality: 85 }); result.captures.push(file); }
+      catch (error) { result.status = 'partly'; result.why += `; capture failed: ${error.message}`; }
+    }
+    report?.check?.(`need-${need.id}`, result.status === 'met' ? 'pass' : 'fail', { label: need.statement, note: result.why });
+    results.push(result);
+  }
+  return results;
+}
+
+export function saveAppNeeds(root, id, plan, needs) {
+  if (!root) return;
+  const dir = join(root, '.studio', 'checks'); mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${id}-needs.json`), JSON.stringify({ at: new Date().toISOString(), codexHash: plan.hash, needs }, null, 2));
+}

package/lib/check.mjs

@@ -1,3 +1,4 @@
+import { readAppNeeds, proveAppNeeds, saveAppNeeds } from './app-needs.mjs';
 /**
  * `homie-studio check [<game>] [--url <site> | --live]` — the promise, measured (where it runs and on which games
  * when nobody says: lib/check-site.mjs; never the live site unless asked): two fresh
@@ -127,7 +128,7 @@ export function judgeRounds(browsers, missed = new Map()) {
   return null;
 }
 
-export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
+export async function check({ root = null, url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
   if (!url || !game) throw new Error('usage: homie-studio check <game> --url <site url>');
   const base = String(url).replace(/\/+$/, '');
   const play = `${base}/${game}/play`;
@@ -148,7 +149,7 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
   if (!chrome) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
-  if (appMeta) return checkApp({ url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
+  if (appMeta) return checkApp({ root, url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
   if (shots) mkdirSync(shots, { recursive: true });
   const profiles = [];
   const browsers = [];
@@ -343,7 +344,9 @@ export async function check({ url, game, roundTimeoutMs = 150_000, rounds = 3, s
 }
 
 /** Apps prove a real action crossing surfaces and a reconnect, without inventing a round. */
-export async function checkApp({ url, game, meta, shots = null, log = () => {}, report = null, puppeteer, chrome }) {
+export async function checkApp({ root = null, url, game, meta, shots = null, log = () => {}, report = null, puppeteer, chrome }) {
+  let plan;
+  try { plan = readAppNeeds(root, game); } catch (error) { return { ok: false, command: 'check', kind: 'app', why: error.message }; }
   const proof = meta.check;
   if (!proof || typeof proof.action !== 'string' || typeof proof.observe !== 'string') return { ok: false, command: 'check', kind: 'app', why: 'app.json check needs action and observe CSS selectors for a real shared action' };
   if (shots) mkdirSync(shots, { recursive: true });
@@ -390,7 +393,10 @@ export async function checkApp({ url, game, meta, shots = null, log = () => {},
       if (shots) await s.page.screenshot({ path: join(shots, `${s.name}.jpg`), type: 'jpeg', quality: 85 });
     }
     report?.check?.('app-action', 'pass', { note: 'action reached wall and both phones; reconnect retained it' });
-    return { ok: true, command: 'check', kind: 'app', room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: true };
+    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report }) : null;
+    if (plan) { saveAppNeeds(root, game, plan, needs); const { refreshCodexFile } = await import('./codex.mjs'); refreshCodexFile(root, game); }
+    const ok = !needs || needs.every(n => n.status === 'met');
+    return { ok, ...(needs ? { needs, why: ok ? undefined : 'Some needs from the person’s Codex are not yet met; see needs and captures' } : {}), command: 'check', kind: 'app', room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: true };
   } catch (error) { return { ok: false, command: 'check', kind: 'app', why: error.message }; }
   finally { await browser?.close().catch(() => {}); rmSync(profile, { recursive: true, force: true }); }
 }

package/lib/codex.mjs

@@ -68,6 +68,15 @@ export const SECTIONS = [
   { key: 'questions', title: 'Open questions', match: /^(open questions|questions|undecided|to decide)\b/i },
 ];
 
+export const APP_SECTIONS = [
+  { key: 'dream', title: 'Their words', match: /^their words|^dream/i },
+  { key: 'scene', title: 'Scene', match: /^scene/i },
+  { key: 'people', title: 'People and surfaces', match: /^people/i },
+  { key: 'offers', title: 'Offers', match: /^offers/i },
+  { key: 'needs', title: 'Needs', match: /^needs/i },
+  ...SECTIONS.filter(s => ['art','sound','milestones','questions'].includes(s.key)),
+];
+
 /* ------------------------------------------------------------------ parsing */
 
 /** A small YAML subset: `key: value`, quoted or bare, and one level of nested `key:` blocks or `{ a: b, c: d }`. */
@@ -130,7 +139,7 @@ export function parseCodex(source) {
     while (seen.has(id)) id = `${id}-2`;
     seen.add(id);
     s.id = id;
-    s.key = SECTIONS.find((k) => k.match.test(s.title))?.key ?? (/^latest|^decisions|^changelog|^news/i.test(s.title) ? 'latest' : null);
+    s.key = [...SECTIONS, ...APP_SECTIONS].find((k) => k.match.test(s.title))?.key ?? (/^latest|^decisions|^changelog|^news/i.test(s.title) ? 'latest' : null);
   }
   return { meta, title, pitch: pitch.join('\n').trim(), sections };
 }
@@ -139,7 +148,7 @@ export function parseCodex(source) {
 export function codexGaps(parsed) {
   const has = (key) => parsed.sections.some((s) => s.key === key && s.body.join('\n').replace(/<!--[\s\S]*?-->/g, '').trim());
   const questions = parsed.sections.filter((s) => s.key === 'questions').flatMap((s) => s.body.filter((l) => /^\s*([-*+]|\d+[.)])\s+\S/.test(l)));
-  return { missing: SECTIONS.filter((s) => s.key !== 'questions' && !has(s.key)).map((s) => s.title), openQuestions: questions.length };
+  return { missing: (parsed.meta.kind === 'app' ? APP_SECTIONS : SECTIONS).filter((s) => s.key !== 'questions' && !has(s.key)).map((s) => s.title), openQuestions: questions.length };
 }
 
 /* ------------------------------------------------------------------ files from the studio */
@@ -303,6 +312,16 @@ ${stats.length ? `<dl class="stats">${stats.map(([k, v]) => `<dt>${esc(k)}</dt><
 }
 
 function sectionHtml(section, emb, ctx) {
+  if (section.key === 'needs') {
+    const source = section.body.join('\n');
+    const block = /^```needs\s*\n([\s\S]*?)^```/m.exec(source);
+    if (block) {
+      try {
+        const needs = JSON.parse(block[1]);
+        if (Array.isArray(needs)) return `<section class="tab" id="${esc(section.id)}" data-key="needs"><h2>${esc(section.title)}</h2>${renderMarkdown(source.replace(block[0], '')).html}<div class="cards">${needs.map(n => `<article class="card"><h3>${esc(n.id)}</h3><p>${esc(n.statement)}</p><p class="meta">${Array.isArray(n.assertions) && n.assertions.length ? 'To demonstrate on the wall and phone' : 'Not yet demonstrable'}</p></article>`).join('')}</div></section>`;
+      } catch { /* Keep malformed source visible for correction. */ }
+    }
+  }
   const intro = [];
   const cards = [];
   let current = null;
@@ -510,13 +529,13 @@ function lookOf(root, game, meta, emb) {
  * sit in games/<id>/ before its game.json does: then the "game" is that planned folder. `create`: a codex is being
  * started for an id with no folder yet.
  */
-function codexGame(root, id, { create = false } = {}) {
+function codexGame(root, id, { create = false, kind = null } = {}) {
   const game = listGames(root).find((g) => g.id === id);
   if (game) return game;
   if (!GAME_ID.test(String(id ?? ''))) return null;
-  const dir = join(experienceDir(root, id));
+  const dir = kind === 'app' ? join(root, 'apps', id) : experienceDir(root, id);
   if (existsSync(join(dir, 'game.json'))) return null;
-  return existsSync(join(dir, CODEX_FILE)) || create ? { id, dir, name: null, planned: true } : null;
+  return existsSync(join(dir, CODEX_FILE)) || create ? { id, dir, kind: dir === join(root, 'apps', id) ? 'app' : 'game', name: null, planned: true } : null;
 }
 
 /**
@@ -529,9 +548,10 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
   const game = codexGame(root, id);
   if (!game) throw new Error(`no game "${id}" in games/, and no codex planning it`);
   const file = join(game.dir, CODEX_FILE);
-  if (!existsSync(file)) throw new Error(`games/${id}/${CODEX_FILE} does not exist yet: npx --no-install homie-studio codex new ${id}`);
-  if (statSync(file).size > LIMITS.source) throw new Error(`games/${id}/${CODEX_FILE} is over ${LIMITS.source / 1024} KB`);
+  if (!existsSync(file)) throw new Error(`${relative(root, file)} does not exist yet: npx --no-install homie-studio codex new ${id}`);
+  if (statSync(file).size > LIMITS.source) throw new Error(`${relative(root, file)} is over ${LIMITS.source / 1024} KB`);
   const parsed = parseCodex(readFileSync(file, 'utf8'));
+  if (game.kind === 'app') parsed.meta.kind = 'app';
   const { meta } = parsed;
   let studio = {};
   try { studio = readStudio(root); } catch { studio = {}; }
@@ -555,7 +575,17 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
   tabs.splice(sections[0]?.key === 'latest' ? 1 : 0, 0, statusTab);
   const cover = typeof meta.cover === 'string' ? emb.image(meta.cover) : null;
   const pitch = parsed.pitch ? renderMarkdown(parsed.pitch).html : (game.blurb ? `<p>${esc(game.blurb)}</p>` : '');
-  const body = sections.map((x) => sectionHtml(x, emb, ctx)).join('\n');
+  const needReportFile = join(root, '.studio', 'checks', `${id}-needs.json`);
+  let needStatus = '';
+  if (game.kind === 'app' && existsSync(needReportFile)) {
+    try {
+      const r = JSON.parse(readFileSync(needReportFile, 'utf8'));
+      const stale = r.codexHash !== createHash('sha256').update(readFileSync(file, 'utf8')).digest('hex');
+      tabs.push('<a href="#needs-status">Needs status</a>');
+      needStatus = `<section class="tab" id="needs-status"><h2>Needs status</h2><p>${stale ? 'Plan changed: this evidence is stale; check again. ' : ''}Checked ${esc(r.at)}. Screen assertions are evidence; review the captures against Their words.</p>${r.needs.map(n => `<article><h3>${esc(n.statement)}</h3><p><strong>${stale ? 'not yet rechecked' : esc(n.status)}</strong> — ${esc(n.why ?? '')}</p>${(n.captures ?? []).map(p => figure(emb, n.statement, relative(root, resolve(root, p)), p)).join('')}</article>`).join('')}</section>`;
+    } catch { /* The next check repairs an incomplete receipt. */ }
+  }
+  const body = needStatus + sections.map((x) => sectionHtml(x, emb, ctx)).join('\n');
   const status = statusHtml(s, ctx);
   const start = s?.state === 'running' ? 'build-status' : (sections[0]?.id ?? 'build-status');
   const tagline = typeof meta.tagline === 'string' ? meta.tagline : '';
@@ -567,13 +597,13 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="robots" content="noindex, nofollow">
-<title>${esc(title)} · Game Codex</title>
+<title>${esc(title)} · ${game.kind === 'app' ? 'App' : 'Game'} Codex</title>
 ${look.links.map((href) => `<link rel="stylesheet" href="${esc(href)}">`).join('\n')}
 <style>${look.faces.join('')}${css(look.palette, look.fonts, ctx.pixel)}</style>
 </head>
 <body data-mode="${esc(mode)}" data-start="${esc(start)}"${ctx.pixel ? ' class="pixel"' : ''}>
 <header class="hero">${cover ? `<div class="bgimg" style="background-image:url(${cover})"></div>` : ''}<div class="wrap">
-<p class="kicker">Game Codex · ${esc(studio.name ?? '')}</p>
+<p class="kicker">${game.kind === 'app' ? 'App' : 'Game'} Codex · ${esc(studio.name ?? '')}</p>
 <h1>${esc(title)}</h1>
 ${tagline ? `<p class="tagline">${esc(tagline)}</p>` : ''}
 ${pitch ? `<div class="pitch">${pitch}</div>` : ''}
@@ -583,12 +613,12 @@ ${pitch ? `<div class="pitch">${pitch}</div>` : ''}
 ${body}
 ${status}
 </main>
-<footer>Game Codex for ${esc(title)}: the plan your AI keeps true as decisions change. Source: games/${esc(id)}/${CODEX_FILE}. Drawn ${esc(now.toISOString().slice(0, 16).replace('T', ' '))} UTC. Made with Homie.</footer>
+<footer>${game.kind === 'app' ? 'App' : 'Game'} Codex for ${esc(title)}: the plan your AI keeps true as decisions change. Source: ${esc(relative(root, file))}. Drawn ${esc(now.toISOString().slice(0, 16).replace('T', ' '))} UTC. Made with Homie.</footer>
 <script>${CODEX_SCRIPT}</script>
 </body>
 </html>
 `;
-  return { html, title, sections: sections.map((x) => ({ id: x.id, title: x.title, key: x.key })), missing: gaps.missing, openQuestions: gaps.openQuestions, warnings: emb.warnings, build: s ? { state: s.state, percent: s.percent } : null };
+  return { html, kind: game.kind ?? 'game', title, sections: sections.map((x) => ({ id: x.id, title: x.title, key: x.key })), missing: gaps.missing, openQuestions: gaps.openQuestions, warnings: emb.warnings, build: s ? { state: s.state, percent: s.percent } : null };
 }
 
 /** `homie-studio codex <id>`: the page on this computer (or the artifact copy). */
@@ -598,7 +628,7 @@ export function writeCodexPage(root, id, { mode = 'file' } = {}) {
   mkdirSync(dir, { recursive: true });
   const file = join(dir, mode === 'artifact' ? `${id}.artifact.html` : `${id}.html`);
   writeFileSync(file, r.html);
-  return { ok: true, command: 'codex', id, mode, file: relative(root, file), path: file, bytes: Buffer.byteLength(r.html), title: r.title, sections: r.sections, missing: r.missing, openQuestions: r.openQuestions, warnings: r.warnings, build: r.build };
+  return { ok: true, command: 'codex', kind: r.kind, id, mode, file: relative(root, file), path: file, bytes: Buffer.byteLength(r.html), title: r.title, sections: r.sections, missing: r.missing, openQuestions: r.openQuestions, warnings: r.warnings, build: r.build };
 }
 
 /** Called whenever a progress feed changes: the local page redraws itself (only when it exists already). */
@@ -632,21 +662,21 @@ export function buildCodexPages(root, dist, ids, { log = () => {} } = {}) {
 /* ------------------------------------------------------------------ a new codex */
 
 /** `homie-studio codex new <id>`: CODEX.md with every section, its look taken from the game and the studio. */
-export function newCodex(root, id, { name = null } = {}) {
+export function newCodex(root, id, { name = null, kind = null } = {}) {
   // A game is planned before it is made: with no game of this id, the codex starts its folder (games/<id>/CODEX.md),
   // and `game new <id>` later makes the game around it.
-  const game = codexGame(root, id, { create: true });
+  const game = codexGame(root, id, { create: true, kind });
   if (!game) return { ok: false, command: 'codex new', why: `"${id}" is not a game id (lowercase letters, digits and hyphens, up to 40)` };
   if (game.planned) { game.name = name ? String(name).slice(0, 60) : id.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' '); mkdirSync(game.dir, { recursive: true }); }
   const file = join(game.dir, CODEX_FILE);
-  if (existsSync(file)) return { ok: false, command: 'codex new', why: `games/${id}/${CODEX_FILE} exists already: change it, never replace it` };
+  if (existsSync(file)) return { ok: false, command: 'codex new', why: `${relative(root, file)} exists already: change it, never replace it` };
   const theme = readTheme(root);
   const land = game.landing?.theme ?? {};
   const q = (v) => JSON.stringify(String(v));
   const cover = ['hero/wide.jpg', 'cover.jpg', 'cover.png', 'public/cover.jpg', 'public/cover.png'].find((p) => existsSync(join(game.dir, p)));
   const today = new Date().toISOString().slice(0, 10);
   const players = game.players ? `${game.players.min ?? 1} to ${game.players.max ?? 8}` : '1 to 8';
-  const text = `---
+  let text = `---
 tagline: ${q(game.blurb ?? '')}
 ${cover ? `cover: ${cover}\n` : ''}palette:
   bg: ${q(theme.bg ?? '#0b0c12')}
@@ -721,9 +751,56 @@ ${game.planned ? `- [ ] The plan (this codex)
 ## Open questions
 
 -
+`;
+  if (game.kind === 'app') text = `---
+kind: app
+tagline: ""
+try: "Open the wall and phone. Follow a real request through the scene."
+---
+# ${game.name ?? id}
+
+## Their words
+<!-- Quote the owner's request. Preserve their dream, not your implementation summary. -->
+
+## Scene
+<!-- Walking in: what is on the wall, what moves/fills/arrives/lights up, how it feels. -->
+
+## People and surfaces
+<!-- Each person, what they must do, and what wall, phone, staff and kiosk show them. -->
+
+## Offers
+<!-- What is sold or given, price and currency, once/monthly, and what payment fulfils. -->
+
+## Needs
+<!-- Each statement is observable on a real screen. Fill this executable needs block.
+Each need: id, statement, steps (surface wall/phone/phone-two; click/fill/select and selector/value),
+assertions (surface, selector, optional text). Include wall and phone assertions and real flow steps.
+A missing flow is reported not met. Do not replace an unmet need with an easier one. -->
+\`\`\`needs
+[]
+\`\`\`
+
+## Art direction
+<!-- Run style init with the owner's words. Composition, materials, typography and motion. -->
+
+## Music and sound
+<!-- Useful cues, silent wall by default, local synthesis or connected providers. -->
+
+## Built from
+<!-- Engine packages, parts_find results and provenance, original work and media routes. -->
+
+## Milestones
+- [ ] Their dream captured
+- [ ] Their scene and workflows running
+- [ ] Every need demonstrated on wall and phone and visually reviewed
+
+## Latest
+- ${today}: Planned from the person's request. Starter plumbing is not completion.
+
+## Open questions
 `;
   writeFileSync(file, text);
-  return { ok: true, command: 'codex new', id, file: relative(root, file), planned: Boolean(game.planned), next: [`fill it from the request and sensible defaults (interview only when asked), then: npx --no-install homie-studio codex ${id}`, ...(game.planned ? [`after recording those defaults: npx --no-install homie-studio game new ${id} --from gem-rush --name "<Name>" makes the game around it (the codex stays)`] : [])] };
+  return { ok: true, command: 'codex new', id, file: relative(root, file), planned: Boolean(game.planned), next: [`fill it from the request and sensible defaults (interview only when asked), then: npx --no-install homie-studio codex ${id}`, ...(game.planned ? [`after recording those defaults: npx --no-install homie-studio ${game.kind === 'app' ? 'app' : 'game'} new ${id} --from ${game.kind === 'app' ? 'welcome' : 'gem-rush'} --name "<Name>" makes the game around it (the codex stays)`] : [])] };
 }
 
 /** A sign-in link that opens one game's codex on the live site (the stats page's one-time sign-in, then the codex). */

package/lib/decisions.mjs

@@ -16,7 +16,7 @@
  * games/<id>/style.json (public, tiny) carries the palette and fonts a game, its landing and its title cards draw with.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { relative, dirname, join } from 'node:path';
 import { HEX, deltaHex, hexToRgb, luminance, mix, nudge } from './colour.mjs';
 import { CAMERAS, FAMILIES, FONT_SETS, GENRES, LIGHTS, MOODS, PALETTES, PALETTE_KEYS, RENDERS, SHAPES } from './style-presets.mjs';
 import { readTheme } from './site.mjs';
@@ -39,7 +39,8 @@ export function contextOf(root, id, { prompt = '' } = {}) {
   let codex = '';
   try { codex = readFileSync(join(dir, 'CODEX.md'), 'utf8').replace(/<!--[\s\S]*?-->/g, ''); } catch { codex = ''; }
   let game = {};
-  try { game = JSON.parse(readFileSync(join(dir, 'game.json'), 'utf8')); } catch { game = {}; }
+  try { game = JSON.parse(readFileSync(experienceFile(root, id), 'utf8')); } catch { game = {}; }
+  const kind = existsSync(join(dir, 'app.json')) || /^kind: app$/m.test(codex) ? 'app' : 'game';
   const fm = /^---\n([\s\S]*?)\n---/.exec(codex)?.[1] ?? '';
   const pal = {};
   for (const k of [...PALETTE_KEYS, 'panel']) { const m = new RegExp(`^\\s+${k}:\\s*"?(#[0-9a-fA-F]{3,6})"?`, 'm').exec(fm); if (m) pal[k] = m[1]; }
@@ -50,9 +51,9 @@ export function contextOf(root, id, { prompt = '' } = {}) {
   for (const [key, re] of [['characters', '(?:characters|cast|heroes|creatures|enemies)'], ['items', '(?:items|props|pickups|collectibles)'], ['places', '(?:world|places|setting|zones?|levels?)']]) {
     for (const m of section(re).matchAll(/^###\s+(.+?)\s*$/gm)) cards.push({ section: key, title: clean(m[1], 60) });
   }
-  const words = [prompt, game.name, game.blurb, section('(?:concept|the game|pitch|overview)'), section('(?:art|look|style|visual)'), section('(?:world|setting)')].filter(Boolean).join(' \n ');
+  const words = [prompt, game.name, game.blurb, section('(?:concept|the game|pitch|overview)'), section('(?:art|look|style|visual)'), section('(?:world|setting)'), ...(kind === 'app' ? [section('(?:their words|dream)'), section('scene'), section('people')] : [])].filter(Boolean).join(' \n ');
   const score = (re) => (words.match(new RegExp(re.source, 'gi')) ?? []).length;
-  const genre = Object.entries(GENRES).map(([g, v]) => [g, score(v.words)]).filter(([, n]) => n).sort((a, b) => b[1] - a[1])[0]?.[0] ?? 'party';
+  const genre = kind === 'app' ? 'app' : Object.entries(GENRES).map(([g, v]) => [g, score(v.words)]).filter(([, n]) => n).sort((a, b) => b[1] - a[1])[0]?.[0] ?? 'party';
   const mood = Object.fromEntries(Object.entries(MOODS).map(([m, re]) => [m, score(re)]));
   let theme = {};
   try { theme = readTheme(root); } catch { theme = {}; }
@@ -76,7 +77,7 @@ export function contextOf(root, id, { prompt = '' } = {}) {
     const hs = assets.filter((a) => a.kind === 'character' && Number(a.measured?.heightM) > 0).map((a) => Number(a.measured.heightM)).sort((a, b) => a - b);
     if (hs.length) castHeightM = Math.round(hs[Math.floor(hs.length / 2)] * 100) / 100;
   } catch { clipVerbs = []; }
-  return { id, prompt: clean(prompt, 600), words, score, genre, mood, codexPalette: pal, codexFonts: fonts, theme, cards, players: Number(game.players?.max ?? game.netplay?.maxPlayers ?? 8) || 8, name: game.name ?? id, codexArt: clean(section('(?:art|look|style|visual)'), 400), drawn, clipVerbs, castHeightM };
+  return { id, kind, prompt: clean(prompt, 600), words, score, genre, mood, codexPalette: pal, codexFonts: fonts, theme, cards, players: Number(game.players?.max ?? game.netplay?.maxPlayers ?? 8) || 8, name: game.name ?? id, codexArt: clean(section('(?:art|look|style|visual)'), 400), drawn, clipVerbs, castHeightM };
 }
 
 /** The best match in a preset table by word score: [key, score] or null. */
@@ -356,7 +357,7 @@ function change(rec, patch, { by = 'ai', words = null, reason = null } = {}) {
 export function initDecisions(root, id, { prompt = '', path = null, budget = null } = {}) {
   gameDirOf(root, id);
   const ctx = contextOf(root, id, { prompt });
-  const doc = readDecisions(root, id) ?? { v: 1, scope: 'game', game: id, path: path ?? 'automatic', budget: null, prompt: '', decisions: {}, board: null, golden: [] };
+  const doc = readDecisions(root, id) ?? { v: 1, scope: ctx.kind, game: id, path: path ?? 'automatic', budget: null, prompt: '', decisions: {}, board: null, golden: [] };
   if (path) doc.path = path === 'hands-on' ? 'hands-on' : 'automatic';
   if (budget !== null && budget !== undefined) doc.budget = { usd: Math.max(0, Number(budget) || 0), provider: 'fal', approvedBy: 'the person, in chat', at: now() };
   if (prompt) doc.prompt = clean(prompt, 600);
@@ -367,6 +368,7 @@ export function initDecisions(root, id, { prompt = '', path = null, budget = nul
   const kept = [];
   const made = [];
   for (const [did] of CATALOGUE) {
+    if (ctx.kind === 'app' && !did.startsWith('style.')) continue;
     const def = CAT.get(did);
     const rec = doc.decisions[did];
     // Kept: anything the person steered or locked, anything pinned, and what a starter's style.json already draws.
@@ -380,7 +382,7 @@ export function initDecisions(root, id, { prompt = '', path = null, budget = nul
     made.push(did);
   }
   writeDecisions(root, id, doc);
-  return { ok: true, command: 'style init', id, picked: made, kept, genre: ctx.genre, summary: oneLine(doc), file: `games/${id}/${DECISIONS_FILE}` };
+  return { ok: true, command: 'style init', id, picked: made, kept, kind: ctx.kind, genre: ctx.genre, summary: oneLine(doc), file: relative(root, fileOf(root, id)) };
 }
 
 /** The one line the automatic path says: "Look: flat low-poly, autumn grove palette, high three-quarter camera". */

package/lib/functions-build.mjs

@@ -1,10 +1,19 @@
 import {existsSync,readdirSync,mkdirSync,writeFileSync,readFileSync} from 'node:fs';
 import {join} from 'node:path';
+import {readStudio} from './studio.mjs';
 import {pathToFileURL} from 'node:url';
 import {createRequire} from 'node:module';
 const require=createRequire(import.meta.url);
 export function functionFiles(root) { const dir=join(root,'functions');return existsSync(dir)?readdirSync(dir).filter(f=>/^[a-z][a-z0-9-]*\.ts$/.test(f)).sort().map(f=>join(dir,f)):[]; }
 export async function buildFunctions(root,esbuild) {
+  const feeds=readStudio(root).mcp?.events??{};
+  if(!feeds||typeof feeds!=='object'||Array.isArray(feeds))throw new Error('mcp.events must be a map of named event feeds');
+  for(const [name,feed] of Object.entries(feeds)) {
+    if(!/^[a-z][a-z0-9-]*$/.test(name)||!feed||typeof feed.event!=='string'||!feed.event.trim())throw new Error('Event feed needs a name and event type');
+    if(feed.event==='record.changed'&&(!/^[a-z][a-z0-9-]*$/.test(feed.app??'')||!/^[a-z][a-z0-9-]*$/.test(feed.collection??'')))throw new Error('Record event feed needs app and collection');
+    if(feed.audience!==undefined&&feed.audience!=='owner'&&!(feed.audience&&typeof feed.audience==='object'&&feed.audience.app===feed.app&&typeof feed.audience.role==='string'))throw new Error('Event feed audience must be owner or an app role');
+    if(feed.event!=='record.changed'&&feed.audience&&feed.audience!=='owner')throw new Error('Non-record event feeds require owner audience');
+  }
   const files=functionFiles(root),dir=join(root,'site/src/functions');mkdirSync(dir,{recursive:true});
   if(files.length) {
     const ts=require('typescript'),options={target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.ESNext,moduleResolution:ts.ModuleResolutionKind.Bundler,strict:true,noEmit:true,skipLibCheck:true};
@@ -31,6 +40,7 @@ export async function buildFunctions(root,esbuild) {
 export function functionDeploymentSQL(root) {
   const file=join(root,'site/src/functions/declarations.json');
   const definitions=existsSync(file)?JSON.parse(readFileSync(file,'utf8')):[];
+  for(const [name,feed] of Object.entries(readStudio(root).mcp?.events??{}))definitions.push({name:'@events/'+name,event:feed.event});
   const literal=value=>"'"+String(value).replaceAll("'","''")+"'";
   return [...definitions.map(fn=>`INSERT INTO function_subscriptions(name,type,cursor,started) VALUES(${literal(fn.name)},${literal(fn.event)},(SELECT COALESCE(MAX(seq),0) FROM studio_events),unixepoch()*1000) ON CONFLICT(name) DO UPDATE SET type=excluded.type,cursor=excluded.cursor,started=excluded.started WHERE type!=excluded.type;`),`DELETE FROM function_subscriptions WHERE name NOT IN (${definitions.map(fn=>literal(fn.name)).join(',')||"''"});`,"INSERT INTO meta(key,value) VALUES('function-registry-deployed','1') ON CONFLICT(key) DO UPDATE SET value='1';"].join(' ');
 }

package/lib/handoff.mjs

@@ -43,7 +43,7 @@ export function stepsFor(h, { games = [], client = 'chat', studioKind = 'game' }
   const q = (s) => JSON.stringify(String(s));
   const app = h.what === 'app' || ['business', 'cause', 'app'].includes(studioKind);
   const work = app && ['setup', 'make'].includes(h.kind) ? [
-    'Follow the new-studio checklist and app skill from the request through building and checks without waiting unless the person asks.',
+    'Follow the app and shared plan skills: capture their words, scene, people, offers and demonstrable needs in apps/<id>/CODEX.md. Starter plumbing is not the deliverable. Build their scene and prove each need on wall and phone; continue without an engineering interview.',
     has ? `apps/${id} is here already: change it as the brief says.` : `npx --no-install homie-studio app new ${id ?? '<id>'} --from ${ID.test(String(h.from ?? '')) ? h.from : 'welcome'}`,
     'Use apps/<id>/app.json for the organisation’s words, roles and records; site/pages/ for public pages; shop init --giving --currency <currency> for gifts.',
   ] : {

package/lib/mcp-tools.mjs

@@ -845,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} (${!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}\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;
       },
@@ -922,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 });
       },
     },
     {
@@ -979,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/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';
@@ -68,7 +68,7 @@ export function slugify(name) {
  * No `database_id` until one is known: Wrangler (4.45.0+) and the Deploy to Cloudflare flow create the database
  * the binding names and keep it linked.
  */
-export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', main = null, ai = false, routes = null, paidParts = false, partsRateLimit = null, triggers = null }) {
+export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layout = 'root', main = null, ai = false, routes = null, paidParts = false, partsRateLimit = null, triggers = null, eventFeeds = null }) {
   const at = layout === 'site' ? { schema: '../node_modules', main: 'src/runtime/worker.js', dist: './dist', migrations: 'migrations' }
     : { schema: 'node_modules', main: 'site/src/runtime/worker.js', dist: './site/dist', migrations: 'site/migrations' };
   const rooms = [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }, { name: 'GATE', class_name: 'Gate' }, { name: 'CONCENTRATOR', class_name: 'Concentrator' }];
@@ -100,7 +100,7 @@ export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null, layou
     // Workers AI, only when a server's AI guides think with it (agents_brain workers-ai; deploy adds it, 0.17.0).
     // Never in Previews: they do not inherit it, so a Preview's guides answer from the game's script.
     ...(ai ? { ai: { binding: 'AI' } } : {}),
-    vars: { STUDIO_NAME: name },
+    vars: { STUDIO_NAME: name, ...(eventFeeds&&Object.keys(eventFeeds).length?{STUDIO_EVENT_FEEDS:JSON.stringify(eventFeeds)}:{}) },
     observability: { enabled: true },
     previews: { vars: { STUDIO_NAME: name, HOMIE_PREVIEW: '1' }, durable_objects: { bindings: rooms } },
   };
@@ -117,7 +117,7 @@ export function agentsMd({ name, slug, kind = 'game' }) {
 
 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\` first. Proceed from the owner's request through building and checking; ask for an interview only when requested or when essential information is missing.
+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.
@@ -173,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.
@@ -822,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': '',
@@ -993,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;
@@ -1014,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). */
@@ -1079,9 +1087,9 @@ export function newStudio(folder, { name, homie, slug: askedSlug, install = true
   const q = JSON.stringify(realpathSync(dir));
   return { ok: true, command: 'new', dir: realpathSync(dir), name, slug, wrote, git, installed, studio: STUDIO_VERSION, next: kind !== 'game' ? [
     `cd ${q}`,
-    'Read the app guide. Proceed from the request through build and checks without waiting unless the person asks for an interview.',
+    '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>"',
-    'npm install && npm run build; npm run dev (use the printed address)',
+    '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.',
   ] : [