@homie-rocks/studio 0.51.4 → 0.51.6

package/lib/app-needs.mjs

@@ -1,7 +1,8 @@
-import {waitInApp} from './app-ready.mjs';
+import {actInApp,waitInApp} from './app-ready.mjs';
 /** 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 { join, resolve, relative, isAbsolute } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { createHash } from 'node:crypto';
 
 export function readAppNeeds(root, id) {
@@ -22,30 +23,38 @@ export function readAppNeeds(root, id) {
 }
 
 /** Run real UI actions. A failed or absent flow stays visible; continue collecting other needs. */
-export async function proveAppNeeds({ plan, surfaces, shots, report, ready = async () => {} }) {
+export async function proveAppNeeds({ plan, surfaces, shots, report, ready = async () => {}, root, headless }) {
   const results = [];
   const appBarrier=ready;
-  ready=async s=>{await s.page.bringToFront?.();if(s.external){s.frame=s.page.mainFrame();return;}await appBarrier(s);};
+  ready=async (s,options)=>{await s.page.bringToFront?.();if(s.external){s.frame=s.page.mainFrame();return;}await appBarrier(s,options);};
   let activeRole;
   const surface = name => { const s = surfaces.find(s => s.name === name && (!activeRole || s.role === activeRole)) ?? surfaces.find(s => s.name === name); if (!s) throw new Error(`unknown surface ${name}`); return s; };
   for (const need of plan.needs) {
     activeRole = need.role;
-    const names = [...new Set([...(need.steps ?? []), ...(need.assertions ?? [])].map(s => s.surface))];
+    const names = [...new Set([...(need.steps ?? []), ...(need.assertions ?? [])].map(s => s.surface).filter(Boolean))];
+    const saved = new Map();
+    const run = async item => { if (!headless) throw new Error('headless MCP proof requires local dev and its test credential'); return headless(item,item.role ?? need.role); };
     let waiting = 'validating assertions';
     const result = { id: need.id, statement: need.statement, status: 'not', captures: [] };
     try {
-      if (!Array.isArray(need.assertions) || !need.assertions.length) throw new Error('need requires assertions on its named surfaces');
+      if (!Array.isArray(need.assertions) || !need.assertions.length) throw new Error('need requires at least one assertion (UI, result, records or file)');
       const popupNames=new Set((need.steps??[]).map(s=>s.popup).filter(Boolean));
       for (const name of names) { if(popupNames.has(name))continue; const s = surface(name); if (need.role && s.role !== need.role) throw new Error(`${name} requires role ${need.role}, got ${s.role ?? 'unspecified'}`); }
       for (const name of new Set(need.assertions.filter(a => a.effect).map(a => a.surface))) await surface(name).frame.evaluate(() => { window.__homieNeedsEffects = []; });
-      for (const step of need.steps ?? []) {
+      for (const rawStep of need.steps ?? []) {
+        const step=resolveNeedResults(rawStep,saved);
+        if (step.mcp || step.schedule) {
+          waiting = step.mcp ? `MCP ${step.mcp.tool ?? step.mcp.method} as ${step.role ?? need.role ?? 'unspecified'}` : `schedule ${step.schedule.name}`;
+          const value = await run(step);
+          if (step.save) { if(saved.has(step.save))throw new Error(`duplicate saved result ${step.save}`); saved.set(step.save,value); }
+          continue;
+        }
         const target=surface(step.surface);
         if(!step.reload)await ready(target);
         const { page } = target;
         waiting = `${step.surface}: ${step.reload ? 'reload and arrival readiness' : step.selector}`;
         if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await ready(surface(step.surface)); continue; }
-        await waitInApp(target,step.selector,f=>f.waitForSelector(step.selector, { visible: true, timeout:10000 }),{ready});
-        const frame=target.frame;
+        const act = fn => actInApp(target,step.selector,fn,{ready});
         if (step.click && step.popup) {
           let listener,timer;
           const opened=new Promise((resolve,reject)=>{
@@ -53,17 +62,42 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
             timer=setTimeout(()=>reject(new Error('payment popup did not open')),10000);
           });
           try {
-            const [popup]=await Promise.all([opened,frame.click(step.selector)]);
+            const [popup]=await Promise.all([opened,act(frame=>frame.click(step.selector))]);
             surfaces.push({name:step.popup,page:popup,frame:popup.mainFrame(),external:true,role:target.role});
             await page.bringToFront();
           } finally {clearTimeout(timer);page.off('popup',listener);}
         }
-        else if (step.click) {await frame.click(step.selector);await page.bringToFront?.();}
-        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 if (step.click) {await act(frame=>frame.click(step.selector));await page.bringToFront?.();}
+        else if (step.fill !== undefined) { await act(async frame=>{ 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 act(frame=>frame.select(step.selector, String(step.select)));
         else throw new Error('step needs click, fill, select or reload');
       }
-      for (const assertion of need.assertions) {
+      for (const rawAssertion of need.assertions) {
+        const assertion=resolveNeedResults(rawAssertion,saved);
+        if (assertion.result || assertion.records || assertion.file || assertion.mcp) {
+          waiting = assertion.file ? `file ${assertion.file}` : assertion.result ? `result ${assertion.result}${assertion.path ? '.'+assertion.path : ''}` : assertion.records ? `records ${assertion.records.collection}` : `MCP ${assertion.mcp.tool ?? assertion.mcp.method}`;
+          let value;
+          if (assertion.file) {
+            if (!root) throw new Error('file proof requires the studio root');
+            const file=resolve(root,assertion.file), rel=relative(resolve(root),file);
+            if(rel.startsWith('..') || isAbsolute(rel))throw new Error('handover file must be inside the studio');
+            value=readFileSync(file,'utf8');
+          } else if (assertion.result) {
+            if(!saved.has(assertion.result))throw new Error(`no saved result ${assertion.result}; add save to its step`);
+            value=saved.get(assertion.result);
+          } else {
+            const waitMs=assertion.waitMs??0;
+            if(!Number.isInteger(waitMs)||waitMs<0||waitMs>10000)throw new Error('waitMs must be an integer from 0 to 10000');
+            const end=Date.now()+waitMs;
+            for(;;) {
+              value=await run(assertion);
+              try {assertNeedValue(value,assertion);break;}
+              catch(error){if(Date.now()>=end)throw error;await new Promise(resolve=>setTimeout(resolve,100));}
+            }
+          }
+          assertNeedValue(value,assertion);
+          continue;
+        }
         waiting = `${assertion.surface}: ${assertion.effect ? assertion.effect + ' ' + (assertion.name ?? '') : assertion.selector + (assertion.text === undefined ? '' : ' containing ' + JSON.stringify(assertion.text))}`;
         const target=surface(assertion.surface);
         await ready(target);
@@ -77,13 +111,14 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
         if (assertion.text !== undefined) await frame.waitForFunction((selector, text) => document.querySelector(selector)?.textContent.includes(text), { timeout: 10000 }, assertion.selector, String(assertion.text));
         },{ready});
       }
-      result.status = shots ? 'met' : 'partly';
-      result.why = shots ? 'UI assertions passed; inspect captures against the pictured scene' : 'Assertions passed but no captures saved';
+      result.status = 'met';
+      result.why = 'Assertions passed';
     } catch (error) { result.why = `Waiting for ${waiting}: ${error.message}`; }
+    if (!shots) for (const name of names) result.why += `; ${name} capture not requested: rerun check with --shots .checks and inspect the scene`;
     if (shots) for (const name of names) {
       const file = join(shots, `${need.id}-${name}.jpg`);
-      try { await ready(surface(name)); await surface(name).page.screenshot({ path: file, type: 'jpeg', quality: 85 }); result.captures.push(file); }
-      catch (error) { if (result.status === 'met') result.status = 'partly'; result.why += `; capture failed: ${error.message}`; }
+      try { mkdirSync(shots,{recursive:true}); await ready(surface(name)); await surface(name).page.screenshot({ path: file, type: 'jpeg', quality: 85 }); result.captures.push(file); }
+      catch (error) { result.why += `; ${name} capture failed: ${error.message}. Resolve this capture error and rerun check with --shots .checks`;  }
     }
     report?.check?.(`need-${need.id}`, result.status === 'met' ? 'pass' : 'fail', { label: need.statement, note: result.why });
     results.push(result);
@@ -96,3 +131,36 @@ export function saveAppNeeds(root, id, plan, needs) {
   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));
 }
+
+/** Partial structured matching: object keys must match; each expected array entry must occur. */
+export function containsValue(actual, expected) {
+  if (typeof expected === 'string') return typeof actual === 'string' && actual.includes(expected);
+  if (Array.isArray(expected)) return Array.isArray(actual) && expected.every(e=>actual.some(a=>containsValue(a,e)));
+  if (expected && typeof expected === 'object') return actual !== null && typeof actual === 'object' && Object.entries(expected).every(([k,v])=>Object.hasOwn(actual,k)&&containsValue(actual[k],v));
+  return isDeepStrictEqual(actual,expected);
+}
+export function assertNeedValue(value, assertion) {
+  if(assertion.path) for(const key of assertion.path.split('.')) value=value!=null&&Object.hasOwn(Object(value),key)?value[key]:undefined;
+  if(value === undefined)throw new Error('value does not exist');
+  if(Object.hasOwn(assertion,'equals')&&!isDeepStrictEqual(value,assertion.equals))throw new Error(`expected equals ${JSON.stringify(assertion.equals)}; got ${JSON.stringify(value)}`);
+  if(Object.hasOwn(assertion,'contains')&&!containsValue(value,assertion.contains))throw new Error(`expected contains ${JSON.stringify(assertion.contains)}; got ${JSON.stringify(value)}`);
+  if(assertion.text!==undefined)for(const text of [].concat(assertion.text))if(typeof value!=='string'||!value.includes(String(text)))throw new Error(`expected text ${JSON.stringify(text)}`);
+  if(!assertion.file&&!Object.hasOwn(assertion,'equals')&&!Object.hasOwn(assertion,'contains')&&assertion.text===undefined)throw new Error('result/records assertion requires equals, contains or text');
+}
+
+/** Explicit result references never evaluate code or interpolate arbitrary strings. */
+export function resolveNeedResults(value,saved) {
+  if(Array.isArray(value))return value.map(v=>resolveNeedResults(v,saved));
+  if(value && typeof value==='object') {
+    if(Object.keys(value).length===1 && typeof value.$result==='string') {
+      const [name,...path]=value.$result.split('.');
+      if(!saved.has(name))throw new Error(`no saved result ${name}`);
+      let result=saved.get(name);
+      for(const key of path)result=result!=null&&Object.hasOwn(Object(result),key)?result[key]:undefined;
+      if(result===undefined)throw new Error(`saved result path ${value.$result} does not exist`);
+      return result;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key,v])=>[key,resolveNeedResults(v,saved)]));
+  }
+  return value;
+}

package/lib/app-ready.mjs

@@ -48,3 +48,24 @@ export function answerDialogs(page,surface,dialogs,report) {
   await dialog.accept().catch(()=>{});
  });
 }
+
+/** Retry only errors identifying a detached element, never an ambiguous navigation after dispatch. */
+export async function actInApp(surface, selector, action, {ready=appReady,timeout=10000}={}) {
+  const end=Date.now()+timeout;
+  let stale;
+  for (;;) {
+    try {
+      await waitInApp(surface,selector,frame=>frame.waitForSelector(selector,{visible:true,timeout:Math.max(1,end-Date.now())}),{ready,timeout:Math.max(1,end-Date.now())});
+      return await action(surface.frame);
+    } catch(error) {
+      if(!/node is detached|element.*(?:detach|stale)|stale.*element/i.test(error.message)) {
+        if(stale && Date.now()>=end)throw new Error(`${surface.name}: stale element ${selector} never settled within ${timeout}ms: ${error.message}`);
+        throw error;
+      }
+      stale=error;
+      if(Date.now()>=end)throw new Error(`${surface.name}: stale element ${selector} never settled within ${timeout}ms: ${error.message}`);
+      await new Promise(resolve=>setTimeout(resolve,Math.min(50,Math.max(1,end-Date.now()))));
+      await ready(surface,{timeout:Math.max(1,end-Date.now())});
+    }
+  }
+}

package/lib/build.mjs

@@ -384,7 +384,7 @@ function pointAtBundle(html, bundle) {
  * game is served (/games/<id>/ on the site, /<id>/__game/ in its frame, the lab). A game with no dynamic import is
  * one file, as before. `hashed` (the site's build) names the bundle by its content too: see the top of this file.
  */
-export async function buildGameFiles(esbuild, root, g, out, { maps = false, sourcemap = null, cache = {}, log = () => {}, hashed = false, lab = false, longCheck = false } = {}) {
+export async function buildGameFiles(esbuild, root, g, out, { maps = false, sourcemap = null, cache = {}, log = () => {}, hashed = false, lab = false, longCheck = false, quick = false } = {}) {
   rmSync(out, { recursive: true, force: true });
   mkdirSync(join(out, 'assets'), { recursive: true });
   const mode = g.build?.mode ?? 'bundle';
@@ -411,7 +411,7 @@ export async function buildGameFiles(esbuild, root, g, out, { maps = false, sour
     }
   }
   const { prepareRules, viewPlugin } = ruled ? await rulesBuild() : {};
-  const rules = ruled ? await prepareRules(esbuild, root, g, { log, longCheck }) : null;
+  const rules = ruled ? await prepareRules(esbuild, root, g, { log, longCheck, quick }) : null;
   const bundle = async (entryRel) => {
     const entry = join(g.dir, entryRel);
     if (!existsSync(entry)) throw new Error(`${label}: entry ${entryRel} not found`);
@@ -509,7 +509,8 @@ export function orderGames(games, order, log = () => {}) {
   return [...games].sort((a, b) => (at.get(a.id) ?? Infinity) - (at.get(b.id) ?? Infinity) || a.id.localeCompare(b.id));
 }
 
-export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false, types = false, beforePublish = async () => {}, longCheck = false } = {}) {
+export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false, types = false, beforePublish = async () => {}, longCheck = false, quick = false } = {}) {
+  log(`Building studio${quick?' (quick: rules play checks skipped)':''}…`);
   const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
   if (Object.hasOwn(studio, 'referrals')) log('studio.json referrals: ignored; Homie has no referral system.');
@@ -535,13 +536,13 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   // from the site as it is.
   const dist = openStage(root, { from: only ? live : null });
   try {
-    return await buildInto(dist, { esbuild, studio, shop, live, games, before, typed, root, only, log, deploy, maps, beforePublish, longCheck });
+    return await buildInto(dist, { esbuild, studio, shop, live, games, before, typed, root, only, log, deploy, maps, beforePublish, longCheck, quick });
   } finally {
     rmSync(dist, { recursive: true, force: true });
   }
 }
 
-async function buildInto(dist, { esbuild, studio, shop, live, games, before, typed, root, only, log, deploy, maps, beforePublish, longCheck }) {
+async function buildInto(dist, { esbuild, studio, shop, live, games, before, typed, root, only, log, deploy, maps, beforePublish, longCheck, quick }) {
   const built = [];
   const retired = [];
   const cache = {};
@@ -549,8 +550,9 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   const browserHosted = [];
   for (const g of games) {
     const out = join(dist, 'games', g.id);
+    log(`Building ${g.id}…`);
     const started = Date.now();
-    const { mode, warnings, bundle, chunks, rules } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log, hashed: true, longCheck });
+    const { mode, warnings, bundle, chunks, rules } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log, hashed: true, longCheck, quick });
     if (rules) ruled.push({ id: g.id, ...rules }); else browserHosted.push(g.id);
     // The guides' vocabulary (NETPLAY.md section 18): checked here, so a room never meets a line it cannot say.
     vocabFor(g, out);
@@ -571,14 +573,14 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     if (seats.asked > SEAT_MAX && !rules) log(`games/${g.id} asks for ${seats.asked} players; browser-hosted netplay rooms retain their ${SEAT_MAX}-player limit, so this build uses ${SEAT_MAX} seats. For larger rooms, rewrite as rules plus view: node_modules/@homie-rocks/studio/guides/game/REWRITE.md`);
     built.push({
       id: g.id, name: g.name, mode, bytes, ms: Date.now() - started, warnings, seats: seats.max,
-      ...(rules ? { capacityTrial: rules.check.capacityTrial } : {}),
+      ...(rules ? { capacityTrial: rules.check.capacityTrial, rulesChecksSkipped: rules.check.skipped === true } : {}),
       ...(bundle ? { bundle } : {}), ...(chunks.length ? { chunks: chunks.length, chunkBytes: later } : {}),
     });
     log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB${chunks.length ? ` + ${chunks.length} additional ${chunks.length === 1 ? 'chunk' : 'chunks'}, ${Math.max(1, Math.round(later / 1024))} KB` : ''})`);
     if (rules && (rules.settings.offline || rules.settings.host === 'browser')) log(`${g.id}: this ${g.kind === 'app' ? 'app' : 'game'}'s rules and tunables are sent to players' devices so it can be played offline`);
-    if (rules) log(`  ${g.id}: its rules run ${rules.settings.host === 'browser' ? "in a player's browser" : 'on the server'} (checked and guarded, ${Math.max(1, Math.round(rules.code.length / 1024))} KB, build ${rules.build}; ${rules.check.ticks} ticks played, the room rebuilt from its save ${rules.check.restores} times: the busiest tick used ${rules.tickUnits} of ${rules.settings.budget.tick} budget units, ${rules.units} of them in one handler; the largest save was ${rules.check.largestSaveBytes} bytes)`);
+    if (rules && !quick) log(`  ${g.id}: its rules run ${rules.settings.host === 'browser' ? "in a player's browser" : 'on the server'} (checked and guarded, ${Math.max(1, Math.round(rules.code.length / 1024))} KB, build ${rules.build}; ${rules.check.ticks} ticks played, the room rebuilt from its save ${rules.check.restores} times: the busiest tick used ${rules.tickUnits} of ${rules.settings.budget.tick} budget units, ${rules.units} of them in one handler; the largest save was ${rules.check.largestSaveBytes} bytes)`);
     if (rules && rules.settings.host === 'server' && (rules.snapshotBytes > rules.snapshotCap || rules.checkpointBytes > rules.checkpointCap)) log(`  ${g.id}: this state fits server and offline play but exceeds browser hosting limits.`);
-    if (rules) log(`  ${g.id}: smoke-run largest snapshot ${rules.snapshotBytes} B / ${rules.snapshotCap} B browser cap; checkpoint ${rules.checkpointBytes} B / ${rules.checkpointCap} B browser cap (measured, not an upper bound)`);
+    if (rules && !quick) log(`  ${g.id}: smoke-run largest snapshot ${rules.snapshotBytes} B / ${rules.snapshotCap} B browser cap; checkpoint ${rules.checkpointBytes} B / ${rules.checkpointCap} B browser cap (measured, not an upper bound)`);
   }
   // A game written before rules (its own code is the host) builds and runs exactly as it did. Said in one line.
   if (browserHosted.length) log(`hosted by a player's browser, as before (no room object; nothing to do): ${browserHosted.join(', ')}`);
@@ -752,6 +754,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   // site, never before: a game that did not build has left both as they were.
   await beforePublish();
   const hosted = (await rulesBuild()).writeRules(root, ruled, all.filter((g) => rulesOf.get(g.id)?.host === 'server').map((g) => g.id));
+  log('Building site Worker…');
   await (await import('./worker-build.mjs')).buildWorker(root, esbuild);
   // All of it is there: now, and only now, it becomes site/dist (lib/stage.mjs).
   const swapped = swapIn(dist, live);

package/lib/check.mjs

@@ -1,5 +1,6 @@
+import {needsHeadless} from './needs-headless.mjs';
 import {randomBytes} from 'node:crypto';
-import {appReady,observeEffects,waitInApp,answerDialogs} from './app-ready.mjs';
+import {actInApp,appReady,observeEffects,waitInApp,answerDialogs} from './app-ready.mjs';
 import {localCredential,localCookie} from './local-test.mjs';
 import { readAppNeeds, proveAppNeeds, saveAppNeeds } from './app-needs.mjs';
 /**
@@ -148,6 +149,12 @@ export async function check({ isolate = true, root = null, url, game, roundTimeo
     if (meta?.rulesError) return { ok: false, command: 'check', why: meta.rulesError };
     if (meta?.kind === 'app') appMeta = meta;
   } catch { /* browser preflight below still names failures */ }
+  if(appMeta && !appMeta.check?.action) {
+    try {
+      const plan=readAppNeeds(root,game);
+      if(plan && !plan.needs.some(n=>[...(n.steps??[]),...(n.assertions??[])].some(i=>i.surface)))return checkApp({isolate,root,url:base,game,meta:appMeta,shots,log,report});
+    } catch(error) {return {ok:false,command:'check',kind:'app',why:error.message};}
+  }
   const chrome = findChrome();
   if (!chrome) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
@@ -357,13 +364,13 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
   const proof = meta.check??{};
   const baseline=typeof proof.action==='string'&&typeof proof.observe==='string';
   if (!baseline && !plan) 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 });
+  const captureWarnings=[];
   const profile = mkdtempSync(join(tmpdir(), 'homie-app-check-'));
   let browser;
   const surfaces = [];
   const room = `check-${randomBytes(10).toString('hex')}`;
   try {
-    browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, args: chromeArgs() });
+    if(baseline || plan?.needs.some(n=>[...(n.steps??[]),...(n.assertions??[])].some(i=>i.surface))) browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, args: chromeArgs() });
     const openSurface = async (name, role) => {
       const dimensions={wall:[1280,720],phone:[390,844],'phone-two':[390,844],tablet:[1024,768],staff:[1024,768],kiosk:[1080,1920]};
       if(!dimensions[name])throw new Error(`Unknown needs surface ${name}`);
@@ -390,7 +397,7 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
     await appReady(actor);
     await waitInApp(actor,proof.action,f=>f.waitForFunction((selector) => { const el = document.querySelector(selector); return el && !el.disabled && !el.hidden; }, {}, proof.action));
     before = await waitInApp(actor,proof.observe,textOf);
-    await actor.frame.click(proof.action);
+    await actInApp(actor,proof.action,f=>f.click(proof.action));
     await waitInApp(actor,proof.observe+' changes after action',f=>f.waitForFunction((selector, was) => document.querySelector(selector)?.textContent !== was, {}, proof.observe, before));
     after = await waitInApp(actor,proof.observe,textOf);
     for (const s of surfaces) await waitInApp(s,proof.observe+' equals '+after,f=>f.waitForFunction((selector, wanted) => document.querySelector(selector)?.textContent === wanted, {}, proof.observe, after));
@@ -402,19 +409,21 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
     if (rooms.some((r) => r !== room)) throw new Error('surfaces did not retain the same room');
     for (const s of surfaces) {
       await appReady(s);
-      if (shots) await s.page.screenshot({ path: join(shots, `${s.name}.jpg`), type: 'jpeg', quality: 85 });
+      if (shots) try {mkdirSync(shots,{recursive:true});await s.page.screenshot({ path: join(shots, `${s.name}.jpg`), type: 'jpeg', quality: 85 });}
+      catch(error){const warning=`${s.name} capture failed: ${error.message}. Resolve this capture error and rerun check with --shots .checks`;captureWarnings.push(warning);log(warning);}
     }
     report?.check?.('app-action', 'pass', { note: 'action reached wall and both phones; reconnect retained it' });
     }
     for(const need of plan?.needs??[])for(const item of [...(need.steps??[]),...(need.assertions??[])]) {
+      if(!item.surface)continue;
       if(plan.needs.some(n=>(n.steps??[]).some(s=>s.popup===item.surface)))continue;
       const role=item.role??need.role??meta.surfaces?.[item.surface]??(item.surface==='staff'?'staff':undefined);
       if(!surfaces.some(s=>s.name===item.surface&&s.role===role))await openSurface(item.surface,role);
     }
-    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report, ready:appReady }) : null;
+    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report, ready:appReady, root, headless:needsHeadless({url,secret,app:game,meta,scope:isolate?room:null}) }) : 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', isolatedRecords:isolate, dialogs, room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: baseline };
+    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', isolatedRecords:isolate, captureWarnings, dialogs, room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: baseline };
   } catch (error) { return { ok: false, command: 'check', kind: 'app', dialogs, why: error.message }; }
   finally { await browser?.close().catch(() => {}); rmSync(profile, { recursive: true, force: true }); }
 }

package/lib/cloudflare.mjs

@@ -48,7 +48,6 @@ import { repoOf } from './repo.mjs';
 import { keptRoutes, readConfig, readZoneRoutes, routesOf, shadowedDomain, wideRouteRefusal, zoneFinding } from './routes.mjs';
 import { ensureLocalIgnored, ensureMigrations, migrationWord } from './scaffold.mjs';
 import { LOCAL_STATE, configPath, domainOrigin, isRulesGame, isWorkersDev, layoutOf, listExperiences as listGames, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
-import { projectsCloudflareEnv } from './projects-env.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
 
@@ -62,11 +61,7 @@ export function wranglerBin(root) {
   return existsSync(local) ? local : null;
 }
 
-/**
- * Wrangler from the studio's own node_modules, run in site/ with the given environment. A studio whose Cloudflare came
- * through Stripe Projects (studio.json `cloudflare.auth: "stripe-projects"`, 0.24.3) runs it with the token and account
- * Projects synced to its git-ignored output file; every other studio with Wrangler's own sign-in.
- */
+/** Wrangler from the studio's own node_modules, using Cloudflare's own sign-in. */
 export function runner(root, env) {
   const bin = wranglerBin(root);
   if (!bin) throw new Error('Wrangler is not installed in this studio yet: run `npm install` in the studio folder first');
@@ -74,7 +69,7 @@ export function runner(root, env) {
     const dev = join(workerDir(root), '.wrangler', 'homie-dev.wrangler.json');
     if (args.includes('--local') && !args.includes('--config') && existsSync(dev)) args = [...args, '--config', dev, '--persist-to', join(workerDir(root), '.wrangler', 'state')];
     const res = spawnSync(bin, args, {
-      cwd, env: { ...process.env, ...projectsCloudflareEnv(root), ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' }, encoding: 'utf8',
+      cwd, env: { ...process.env, ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' }, encoding: 'utf8',
       input, maxBuffer: 64 * 1024 * 1024, timeout: 10 * 60_000,
     });
     const out = `${res.stdout ?? ''}${res.stderr ?? ''}`.replace(ANSI, '');
@@ -152,7 +147,7 @@ export async function zoneCheck(root, { studio = readStudio(root), config = read
   try {
     const w = bin ? runner(root, accountId ? { CLOUDFLARE_ACCOUNT_ID: accountId } : {}) : null;
     headers = await cloudflareAuth({
-      env: { ...process.env, ...projectsCloudflareEnv(root) }, bin, cwd: root,
+      env: { ...process.env }, bin, cwd: root,
       exec: async (_bin, args) => { const r = w(args, { cwd: root }); return { code: r.code, stdout: r.stdout }; },
     });
   } catch { headers = null; }
@@ -398,7 +393,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   const started = Date.now();
   let dep = w(['deploy', ...(workerEntry(root) ? [workerEntry(root)] : []), ...repoVar(root)]);
   if (dep.code !== 0 && explainCloudflare(dep.out, accountId)?.needs === 'workers-dev-subdomain') {
-    const headers = await cloudflareAuth({ env: { ...process.env, ...projectsCloudflareEnv(root) }, bin: wranglerBin(root), cwd: root,
+    const headers = await cloudflareAuth({ env: { ...process.env }, bin: wranglerBin(root), cwd: root,
       exec: async (_bin, args) => { const r = w(args, { cwd: root }); return { code: r.code, stdout: r.stdout }; } });
     const address = await registerWorkersAddress({ accountId, slug: studio.slug, headers, ...(fetchFn ? { fetchFn } : {}) });
     if (!address.ok) return { ok: false, command: 'deploy', needs: 'workers-dev-subdomain', why: address.next };
@@ -408,7 +403,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
   if (dep.code !== 0) return refuse(`wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}`, dep.out);
   if (paidReleases(root).length) {
     const bin = wranglerBin(root);
-    const uploadOptions = { cwd: workerDir(root), env: { ...process.env, ...projectsCloudflareEnv(root), CLOUDFLARE_ACCOUNT_ID: accountId, WRANGLER_SEND_METRICS: 'false', CI: '1' } };
+    const uploadOptions = { cwd: workerDir(root), env: { ...process.env, CLOUDFLARE_ACCOUNT_ID: accountId, WRANGLER_SEND_METRICS: 'false', CI: '1' } };
     await uploadPaidParts(root, { bucket: purchaseBucket, log, put: (key, file) => wranglerRun(bin, ['r2', 'object', 'put', key, '--file', file, '--remote'], uploadOptions), hash: (key) => hashRemote(bin, key, uploadOptions) });
   }
   remember(`worker:${cf.worker}`);
@@ -772,7 +767,7 @@ export async function mediaMove(root, { paths = null, dryRun = false, verify = f
   const bin = wranglerBin(root);
   if (!bin) return { ok: false, ...base, why: 'Wrangler is not installed in this studio yet: run `npm install` in the studio folder first' };
   const account = accountId || process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || null;
-  const opts = { cwd: workerDir(root), env: { ...process.env, ...projectsCloudflareEnv(root), ...(account ? { CLOUDFLARE_ACCOUNT_ID: account } : {}), WRANGLER_SEND_METRICS: 'false', CI: '1' } };
+  const opts = { cwd: workerDir(root), env: { ...process.env, ...(account ? { CLOUDFLARE_ACCOUNT_ID: account } : {}), WRANGLER_SEND_METRICS: 'false', CI: '1' } };
   const moved = [];
   const failed = [];
   const verified = [];

package/lib/codex.mjs

@@ -318,7 +318,7 @@ function sectionHtml(section, emb, ctx) {
     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>`;
+        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 with check' : 'Not yet demonstrable'}</p></article>`).join('')}</div></section>`;
       } catch { /* Keep malformed source visible for correction. */ }
     }
   }
@@ -582,7 +582,7 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
       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>`;
+      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)}. Assertions are evidence; review available 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');
@@ -772,9 +772,11 @@ try: "Open the wall and phone. Follow a real request through the scene."
 <!-- 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.
+<!-- Each owner statement belongs in this executable needs block.
+Each need: id, statement, optional role, steps and assertions. UI: surface/selector with
+click/fill/select/reload; headless: mcp tool/arguments + save, or schedule name/at.
+Assert UI selectors, saved result/path/equals/contains, records, or file/text.
+See node_modules/@homie-rocks/studio/guides/app/NEEDS.md for complete examples.
 A missing flow is reported not met. Do not replace an unmet need with an easier one. -->
 \`\`\`needs
 []

package/lib/dev.mjs

@@ -32,7 +32,6 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpat
 import { connect } from 'node:net';
 import { dirname, join, sep } from 'node:path';
 import { detectLocalAi, localAiVars } from './local-ai.mjs';
-import { projectsCloudflareEnv } from './projects-env.mjs';
 import { routesOf } from './routes.mjs';
 import { ensureMigrations, migrationWord } from './scaffold.mjs';
 import { isRulesGame, listExperiences as listGames, workerDir } from './studio.mjs';
@@ -343,7 +342,7 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
   if (!b.catalogue.length && !b.songs.length && !b.videos.length) log('No game yet: the home page says "First game coming soon" until the first one is made.');
   const bin = wranglerBin(root);
   if (!bin) return { ok: false, command: 'dev', why: 'run npm install in the studio first' };
-  const env = { ...process.env, ...projectsCloudflareEnv(root), WRANGLER_SEND_METRICS: 'false', CI: '1', ...(process.stdout.isTTY && !process.env.NO_COLOR ? { FORCE_COLOR: process.env.FORCE_COLOR ?? '1' } : {}) };
+  const env = { ...process.env, WRANGLER_SEND_METRICS: 'false', CI: '1', ...(process.stdout.isTTY && !process.env.NO_COLOR ? { FORCE_COLOR: process.env.FORCE_COLOR ?? '1' } : {}) };
   for (const added of ensureMigrations(root)) log(`added ${added} (${migrationWord(added)})`);
   await new Promise((done) => {
     const m = spawn(bin, ['d1', 'migrations', 'apply', 'DB', '--local'], { cwd: workerDir(root), env, stdio: ['ignore', 'ignore', 'inherit'] });

package/lib/doctor.mjs

@@ -1,4 +1,4 @@
-import { providerKey } from './provider-key.mjs';
+import { officialConnections } from './official-media.mjs';
 /**
  * `homie-studio setup status` (also `homie-studio doctor`): what this computer and this person's accounts have for
  * a studio, as one checklist, before anything is made. For each thing: green, missing, or "do this now", what it
@@ -35,8 +35,7 @@ import { providerKey } from './provider-key.mjs';
  *   status line        optional    (Claude Code only) the build's progress under the prompt
  *
  * It is safe at any time, inside a studio or before one exists: it only reads (local files, `--version` of a few
- * tools, `wrangler whoami`, `gh auth status`, `elevenlabs auth status`, one GET to the directory and, when a fal key
- * is set, fal's free pricing API; when a server's AI guides use Workers AI, one read of the live database and one
+ * tools, `wrangler whoami`, `gh auth status`, one GET to the directory and explicit AI-host connection evidence; when a server's AI guides use Workers AI, one read of the live database and one
  * one-word call to the model; in Codex or Grok, the `[mcp_servers.homie]` table of that app's config.toml, of which
  * it keeps only whether it is an address or a command, and the hooks' mark in this user's cache), never changes
  * anything, and never prints a key, a token, a command line or an account's name or id.
@@ -53,7 +52,6 @@ import { whyFailed } from './net.mjs';
 import { isOurs } from './statusline.mjs';
 import { findStudio, listExperiences as listGames, readLocal, readStudio } from './studio.mjs';
 import { standaloneRows } from './standalone.mjs';
-import { projectsCloudflareEnv, projectsElevenLabs } from './projects-env.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 
 /** A command's result, never throwing: code 127 when the program is not installed, 124 when it ran out of time. */
@@ -175,7 +173,7 @@ const ago = (ms) => (ms < 90_000 ? `${Math.max(1, Math.round(ms / 1000))} s` : m
  * replaceable for tests.
  */
 export async function setupStatus({
-  cwd = process.cwd(), env = process.env, platform = process.platform, connector = null, homie = null, client = null,
+  cwd = process.cwd(), env = process.env, platform = process.platform, connector = null, integrations = {}, homie = null, client = null,
   exec = defaultExec, fetchFn = globalThis.fetch, chrome = findChrome, node = process.versions.node, nowMs = Date.now(),
 } = {}) {
   const root = findStudio(cwd);
@@ -198,18 +196,12 @@ export async function setupStatus({
 
   // The Homie connector (the AI says; the network is checked here), Cloudflare, GitHub and the providers, at once.
   const said = connector === true || connector === 'yes' ? 'yes' : connector === false || connector === 'no' ? 'no' : null;
-  const [net, who, gh, eleven, fal] = await Promise.all([
+  const [net, who, gh] = await Promise.all([
     reach(`${directory}/mcp`, fetchFn),
     (async () => {
-      if (env.CLOUDFLARE_API_TOKEN) return { signedIn: true, how: 'an API token in the environment' };
       const bin = root ? join(root, 'node_modules', '.bin', win ? 'wrangler.cmd' : 'wrangler') : null;
       if (!bin || !existsSync(bin)) return { signedIn: null };
-      // Through Stripe Projects (studio.json "auth": "stripe-projects"): Wrangler with the token Projects synced.
-      const projects = projectsCloudflareEnv(root);
-      const r = await exec(bin, ['whoami', '--json'], { cwd: root, timeout: 25_000, env: { ...env, ...projects, WRANGLER_SEND_METRICS: 'false', CI: '1' } });
-      if (projects.CLOUDFLARE_API_TOKEN && r.code === 0) {
-        try { if (JSON.parse(r.stdout.slice(Math.max(0, r.stdout.indexOf('{')))).loggedIn) return { signedIn: true, how: 'through Stripe Projects (its token, in the studio\'s git-ignored .env; never shown)', accounts: 1, accountIds: [projects.CLOUDFLARE_ACCOUNT_ID].filter(Boolean) }; } catch { /* read below */ }
-      }
+      const r = await exec(bin, ['whoami', '--json'], { cwd: root, timeout: 25_000, env: { ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' } });
       if (r.code === 124) return { signedIn: null, why: 'Wrangler did not answer in time' };
       // The accounts' ids stay in this process (the Workers AI row calls the studio's own account); never printed.
       try { const d = JSON.parse(r.stdout.slice(Math.max(0, r.stdout.indexOf('{')))); return { signedIn: Boolean(d.loggedIn), accounts: Array.isArray(d.accounts) ? d.accounts.length : null, accountIds: Array.isArray(d.accounts) ? d.accounts.map((a) => a?.id).filter(Boolean) : [] }; } catch { return { signedIn: false }; }
@@ -224,26 +216,6 @@ export async function setupStatus({
       if (v.code !== 0) return { git: git.code === 0, gh: false, signedIn: false, onGitHub };
       return { git: git.code === 0, gh: true, signedIn: (await exec('gh', ['auth', 'status'], { timeout: 10_000 })).code === 0, onGitHub };
     })(),
-    (async () => {
-      const cliBin = env.ELEVENLABS_CLI || 'elevenlabs';
-      const v = await exec(cliBin, ['--version']);
-      let signedIn = false;
-      if (v.code === 0) {
-        const s = await exec(cliBin, ['auth', 'status', '--format', 'json'], { timeout: 10_000 });
-        try { signedIn = Boolean(JSON.parse(s.stdout)?.schemes?.some((x) => x.logged_in)); } catch { signedIn = false; }
-      }
-      const credential = providerKey('elevenlabs', env);
-      return { cli: v.code === 0, signedIn, key: Boolean(credential.key), source: credential.source, projects: root ? projectsElevenLabs(root) : false };
-    })(),
-    (async () => {
-      const { key, source } = providerKey('fal', env);
-      if (!key) return { key: false };
-      const base = String(env.FAL_API_URL || 'https://api.fal.ai').replace(/\/+$/, '');
-      try {
-        const res = await fetchFn(`${base}/v1/models/pricing?endpoint_id=fal-ai/flux/dev`, { headers: { Authorization: `Key ${key}` }, signal: AbortSignal.timeout(6000) });
-        return { key: true, source, valid: res.ok ? true : res.status === 401 || res.status === 403 ? false : null };
-      } catch { return { key: true, source, valid: null }; }
-    })(),
   ]);
 
   // The Homie connector. A session with a shell makes, deploys and lists a studio without it, so it never blocks.
@@ -385,23 +357,7 @@ export async function setupStatus({
       : { who: 'person', open: 'https://github.com/signup', say: `Make a free GitHub account; your AI installs the GitHub CLI${mac ? ' (brew install gh)' : ''} when you want the backup.` },
   });
 
-  // ElevenLabs.
-  rows.push({
-    id: 'elevenlabs', label: 'ElevenLabs', need: 'optional', state: eleven.signedIn || eleven.key || eleven.projects ? 'ok' : 'optional',
-    detail: eleven.signedIn ? 'the elevenlabs CLI is signed in' : eleven.key ? `key from ${eleven.source}` : eleven.projects ? 'through Stripe Projects (its key, in the studio\'s git-ignored .env; never shown)' : eleven.cli ? 'the elevenlabs CLI is here, not signed in' : 'not connected',
-    unlocks: 'songs and game scores (the music skill), billed to your own ElevenLabs plan; every render is quoted first',
-    fix: eleven.signedIn || eleven.key || eleven.projects ? null : eleven.cli
-      ? { who: 'ai', run: 'elevenlabs auth login', say: 'ElevenLabs opens in your browser; sign in once. No key is pasted anywhere.' }
-      : { who: mac ? 'ai' : 'person', run: mac ? 'brew install elevenlabs/tap/elevenlabs && elevenlabs auth login' : undefined, open: 'https://elevenlabs.io/sign-up', say: 'Make an ElevenLabs account when you want songs; your AI installs their CLI and you sign in once in the browser.' },
-  });
-
-  // fal.
-  rows.push({
-    id: 'fal', label: 'fal', need: 'optional', state: fal.key ? (fal.valid === false ? 'act' : 'ok') : 'optional',
-    detail: !fal.key ? 'no fal key in the environment or Homie key files' : `key from ${fal.source}; ${fal.valid === true ? 'fal accepts it' : fal.valid === false ? 'fal refused it (wrong or revoked)' : 'fal did not answer just now'}`,
-    unlocks: 'painted art and backdrops (the art skill) and generated video clips (the video skill), on your own fal account under a budget; covers from a real frame and captured trailers are free',
-    fix: fal.key && fal.valid !== false ? null : { who: 'ai', say: 'Use local art and captured footage. Paid fal scripts need an already connected account; never ask the person to find or set a key. Offer the provider browser connection only when generated media is requested.', open: 'https://fal.ai/dashboard' },
-  });
+  rows.push(...officialConnections(integrations));
 
   // Stripe, only in a studio that sells. Installing agent tooling is not proof of Worker credentials.
   // shop connect runs browser pairing and reports the remaining steps; this read-only status never reads keys.
@@ -411,11 +367,11 @@ export async function setupStatus({
     const mcp = stripeAgentConfigured({ root, env });
     rows.push({
       id: 'stripe', label: 'Stripe', need: 'for selling', state: 'act',
-      detail: [version ? `Stripe CLI ${version} is installed` : 'Stripe CLI is not installed', mcp ? `optional MCP is set up for ${mcp}` : 'optional MCP is not set up', 'CLI access is not proof that Worker credentials or a purchase work'].join('; '),
-      unlocks: 'Connect the studio’s own Stripe with browser approval; shop connect syncs Payment Links and the webhook without a Worker API key. Verify a test purchase before calling the shop ready.',
+      detail: [version ? `Stripe CLI ${version} is installed` : 'Stripe CLI is not installed', mcp ? `official MCP is set up for ${mcp}` : 'official MCP is not set up', 'Provider sign-in is not proof that the shop and signed events work'].join('; '),
+      unlocks: 'Use Stripe’s official plugin for shop planning and verification, then install the private webhook. Verify a test purchase before calling the shop ready.',
       fix: {
-        who: 'ai', run: version ? 'npx --no-install homie-studio shop connect' : 'npm install -g @stripe/cli@latest',
-        say: 'Use stripe_login or shop connect. Never ask for a key in chat. Sync Products, Prices, Payment Links and the webhook through the approved CLI. The Worker needs only the signing secret; repeat connect after edits.',
+        who: 'ai', run: mcp ? 'npx --no-install homie-studio shop plan' : version ? 'stripe agent setup' : 'npm install -g @stripe/cli@latest',
+        say: 'Use stripe_shop_plan with Stripe’s official MCP for catalog and links, then stripe_webhook for private signing-secret installation. Never ask for a key. Repeat plan and verify after edits.',
         open: 'https://dashboard.stripe.com/register',
       },
     });