@homie-rocks/studio 0.51.4 → 0.51.6

package/lib/mcp-tools.mjs

@@ -1,4 +1,3 @@
-import { providerKey } from './provider-key.mjs';
 /**
  * THE LOCAL MCP SERVER'S TOOLS (`homie-studio mcp`, lib/mcp.mjs): the studio toolkit as MCP tools, so the Claude
  * desktop app (through the Homie extension), Claude Code or any MCP client builds games in the SAME chat that shows
@@ -200,14 +199,14 @@ function needsInstall(ctx, root) {
 
 /* ------------------------------------------------------------------ the setup card */
 
-async function statusOf(ctx, root, { fresh = false } = {}) {
+async function statusOf(ctx, root, { fresh = false, integrations = {} } = {}) {
   const key = root ?? '';
-  if (!fresh && ctx.status && ctx.status.key === key && Date.now() - ctx.status.at < 20_000) return ctx.status.value;
+  if (!fresh && !Object.keys(integrations).length && ctx.status && ctx.status.key === key && Date.now() - ctx.status.at < 20_000) return ctx.status.value;
   const node = findNode({ fresh });
   // Claude Code's own status line is not this host's: its row stays out (CLAUDECODE says the server runs inside it).
   const env = toolEnv();
   delete env.CLAUDECODE;
-  const value = await setupStatus({ cwd: root ?? ctx.studiosDir ?? homedir(), connector: 'yes', node: node?.version ?? '0', env });
+  const value = await setupStatus({ cwd: root ?? ctx.studiosDir ?? homedir(), connector: 'yes', integrations, node: node?.version ?? '0', env });
   const row = value.rows.find((r) => r.id === 'node');
   if (row) {
     if (!node) { row.detail = 'not found on this computer (22 or newer is needed)'; row.state = 'missing'; }
@@ -240,8 +239,8 @@ function checklist(ctx, root) {
   return steps.map((label, n) => ({ n, label, state: done[n] ? 'done' : n === now ? 'now' : 'todo' }));
 }
 
-async function setupCard(ctx, root, { fresh = false, made = null, install = null, wanted = null } = {}) {
-  const status = await statusOf(ctx, root, { fresh });
+async function setupCard(ctx, root, { fresh = false, made = null, install = null, wanted = null, integrations = {} } = {}) {
+  const status = await statusOf(ctx, root, { fresh, integrations });
   const studios = ctx.studios().map(({ root: r, ...s }) => s);
   const current = root ? ctx.describe(root) : null;
   const running = root ? runningJobs(root).find((j) => j.label.startsWith('npm install')) : null;
@@ -814,13 +813,13 @@ export function toolDefs(ctx, avail = {}) {
     {
       name: 'setup_status', title: 'Setup status',
       description: 'Step 0 of a new studio, and any time the person asks what they need or whether they are set up: what this computer and their accounts have (Node, Cloudflare signed in and email verified, Chrome for the checks, ffmpeg, and the optional GitHub, ElevenLabs and fal), what each unlocks, and the exact fix; the studios in the studios folder; and the new-studio checklist with where they are on it. For a studio that is not made yet, pass its name as studio: the checklist is then the new studio\'s, never another studio\'s that happens to be in the folder. Read-only, a few seconds. Optional rows never block anything.',
-      inputSchema: { type: 'object', properties: { studio: str('Optional: which studio (its folder name or name), or the name of a new studio that is not made yet; else the one in use'), fresh: { type: 'boolean', description: 'Check again now instead of the last 20 s' } } },
+      inputSchema: { type: 'object', properties: { studio: str('Optional: which studio (its folder name or name), or the name of a new studio that is not made yet; else the one in use'), fresh: { type: 'boolean', description: 'Check again now instead of the last 20 s' }, integrations: { type: 'object', description: 'Session evidence from official MCP tools: connected only after a successful authenticated call; unavailable when absent, otherwise unknown. Never credentials.', properties: Object.fromEntries(['fal','elevenlabs','cloudflare'].map(id => [id, { type: 'string', enum: ['connected','unavailable','unknown'] }])) } } },
       annotations: { title: 'Setup status', ...RO }, _meta: ui(UI.setup),
       run: async (a) => {
         // A name with no studio of it yet is the studio about to be made: its own checklist, from step 1.
         const named = String(a.studio ?? '').trim().slice(0, 60);
-        if (named && !ctx.knows(named)) return setupCard(ctx, null, { fresh: a.fresh === true, wanted: named });
-        return setupCard(ctx, ctx.root(a.studio, { need: false }), { fresh: a.fresh === true });
+        if (named && !ctx.knows(named)) return setupCard(ctx, null, { fresh: a.fresh === true, integrations: a.integrations, wanted: named });
+        return setupCard(ctx, ctx.root(a.studio, { need: false }), { fresh: a.fresh === true, integrations: a.integrations });
       },
     },
     {
@@ -1031,13 +1030,13 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'build', title: 'Build the site',
-      description: 'Bundle every game or app and the site into site/dist. Rules builds always run strict types, the guard and deterministic generated play, including save/restore and prediction checks. Read full diagnostics and repair the named handler; info lines do not fail. Never bypass checks or switch to browser hosting to escape a failure. A running preview shows the new build on reload.',
-      inputSchema: { type: 'object', properties: { game: str('Optional: only this game'), ...STUDIO_ARG } },
+      description: 'Bundle every game or app and the site into site/dist. Rules builds run strict types, the guard and deterministic generated play. quick:true skips generated play and snapshot smoke checks for local iteration; full build before release. Read full diagnostics and repair the named handler; info lines do not fail. Never bypass checks or switch to browser hosting to escape a failure. A running preview shows the new build on reload.',
+      inputSchema: { type: 'object', properties: { game: str('Optional: only this game'), quick:{type:'boolean'}, ...STUDIO_ARG } },
       annotations: { title: 'Build', ...RW },
       run: async (a) => {
         const root = ctx.root(a.studio);
         const need = needsInstall(ctx, root); if (need) return need;
-        const r = await cli(ctx, root, 'build', ['build', ...(a.game ? [String(a.game)] : [])]);
+        const r = await cli(ctx, root, 'build', ['build', ...(a.game ? [String(a.game)] : []), ...(a.quick?['--quick']:[])]);
         if (!r.ended) return stillRunning(r.job, 'The build');
         if (r.job.code !== 0) return fail(`The build failed: ${whyOf(r.job)}`);
         const g = r.result?.games ?? [];
@@ -1177,9 +1176,31 @@ export function toolDefs(ctx, avail = {}) {
         return startRun(ctx, root, { kind: 'deploy', game: null, title: `${studio.name}: online`, steps: [{ label: 'deploy', args: ['deploy', ...(a.ownRoute === true ? ['--own-route'] : [])] }] });
       },
     },
+    {
+      name: 'stripe_shop_plan', title: 'Plan or verify the Stripe shop',
+      description: 'Default setup with Stripe official MCP. Supply public API observations as {path,params,body}, account ID, mode, and complete booking slots. Returns the exact next read/write with metadata and idempotency. Execute via Stripe stripe_api_search/details/read/write, clear observations after writes, repeat until verified. verify:true saves the public config for stripe_webhook. Never pass webhook creation responses or secrets.',
+      inputSchema: {type:'object',properties:{...STUDIO_ARG,account:{type:'string'},mode:{enum:['test','live']},url:{type:'string'},slots:{type:'array',items:{type:'object'}},observations:{type:'array',items:{type:'object'}},verify:{type:'boolean'}}},
+      annotations:{readOnlyHint:false,destructiveHint:false,openWorldHint:false},
+      run:async a=>{
+        const {shopMcpPlan,saveMcpVerification}=await import('./shop-mcp.mjs');
+        const result=await (a.verify?saveMcpVerification:shopMcpPlan)(ctx.root(a.studio),a);
+        return ok(JSON.stringify(result),result);
+      },
+    },
+    {
+      name:'stripe_webhook',title:'Install Stripe webhook privately',
+      description:'After stripe_shop_plan verify:true, create/install only the webhook and verified public links. Uses a separate official CLI browser approval if needed; never shows secrets. Follow studio_job. Never create a webhook through model-visible Stripe MCP.',
+      inputSchema:{type:'object',properties:{...STUDIO_ARG,live:{type:'boolean'},renew:{type:'boolean'}}},
+      annotations:{readOnlyHint:false,destructiveHint:false,openWorldHint:true},
+      run:async a=>{
+        const job=cliJob(ctx.root(a.studio),'Private Stripe webhook',['shop','webhook',...(a.live?['--live']:[]),...(a.renew?['--renew']:[])],{cli:join(PACKAGE_ROOT,'bin','homie-studio.mjs'),keep:false});
+        await waitJob(job,Math.min(ctx.waitMs,1000));
+        return ok('Follow studio_job; approve Stripe in the browser if requested.',{kind:'job',...jobView(job)});
+      },
+    },
     {
       name:'stripe_bookings_sync', title:'Sync published booking slots to Stripe',
-      description:'Owner AI: after reading published slot records, supply the complete slot manifest. Creates/updates Stripe Payment Links with completed-session capacity limits through the approved CLI profile. Before moving a booking, sync target active:false to deactivate and expire open sessions. After the versioned staff move, sync current confirmed counts for affected slots to restore the remaining budget. Removed slots deactivate and expire open sessions. No Worker API key. Follow studio_job. Never increase capacity merely to reopen a full slot.',
+      description:'CLI alternative to stripe_shop_plan with Stripe official MCP: after reading published slot records, supply the complete slot manifest. Creates/updates Stripe Payment Links with completed-session capacity limits through the approved CLI profile. Before moving a booking, sync target active:false to deactivate and expire open sessions. After the versioned staff move, sync current confirmed counts for affected slots to restore the remaining budget. Removed slots deactivate and expire open sessions. No Worker API key. Follow studio_job. Never increase capacity merely to reopen a full slot.',
       inputSchema:{type:'object',properties:{...STUDIO_ARG,slots:{type:'array',items:{type:'object',properties:{app:{type:'string'},collection:{type:'string'},slots:{type:'string'},slot:{type:'string'},item:{type:'string'},capacity:{type:'integer',minimum:0},confirmed:{type:'integer',minimum:0},active:{type:'boolean'}},required:['app','collection','slots','slot','item','capacity'],additionalProperties:false}},live:{type:'boolean'}},required:['slots']},
       annotations:{readOnlyHint:false,destructiveHint:false,openWorldHint:true},
       run:async a=>{
@@ -1193,12 +1214,12 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'stripe_login', title: 'Connect the studio to Stripe',
-      description: 'Connect and sync shop.json through Stripe’s official CLI with one browser approval if needed. Creates Products, Prices, Payment Links and the webhook; installs only links and signing secret, no API key in the Worker. Repeat after edits. Follow studio_job. An existing key supports fuller checkout; manual only if explicitly chosen for those features. live only when the owner says go live.',
-      inputSchema: { type: 'object', properties: { ...STUDIO_ARG, live: { type: 'boolean' }, renew: { type: 'boolean' }, manual: { type: 'boolean' } } },
+      description: 'Connect and sync shop.json through Stripe’s official CLI with one browser approval if needed. Creates Products, Prices, Payment Links and the webhook; installs only links and signing secret, no API key in the Worker. Repeat after edits. Follow studio_job. Alternative to the default Stripe official MCP plan and private stripe_webhook flow. live only when the owner says go live.',
+      inputSchema: { type: 'object', properties: { ...STUDIO_ARG, live: { type: 'boolean' }, renew: { type: 'boolean' } } },
       annotations: { title: 'Connect Stripe', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       run: async (a) => {
         const root = ctx.root(a.studio);
-        const args = ['shop', 'connect', ...(a.live ? ['--live'] : []), ...(a.renew ? ['--renew'] : []), ...(a.manual ? ['--manual'] : [])];
+        const args = ['shop', 'connect', ...(a.live ? ['--live'] : []), ...(a.renew ? ['--renew'] : [])];
         const job = cliJob(root, 'Stripe connection', args, { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs'), keep: false });
         const ended = await waitJob(job, Math.min(ctx.waitMs, 1000));
         ctx.status = null;
@@ -1496,13 +1517,13 @@ export function toolDefs(ctx, avail = {}) {
       },
     });
   }
-  // The media skills' own scripts, where their provider (or the free tool they need) is set up on this computer.
-  for (const [name, title, needs] of [['music', 'Music (ElevenLabs)', 'elevenlabs'], ['sound', 'Sound effects and a theme (free)', 'ffmpeg'], ['art', 'Art: covers, frames, painted art', 'ffmpeg'], ['video', 'Video: trailers and clips', 'ffmpeg'], ['models', 'Models: generated 3D props (paid, on your fal account)', 'node']]) {
+  // Local media processing; provider tools are discovered by the AI host.
+  for (const [name, title, needs] of [['music', 'Music preparation', 'ffmpeg'], ['sound', 'Sound effects and a theme (free)', 'ffmpeg'], ['art', 'Art: covers, frames, painted art', 'ffmpeg'], ['video', 'Video: trailers and clips', 'ffmpeg'], ['models', 'Models: import completed 3D assets', 'node']]) {
     const script = ctx.skillsDir ? join(ctx.skillsDir, name, 'scripts', `${name}.mjs`) : null;
     if (!script || !existsSync(script) || !avail[needs]) continue;
     tools.push({
       name, title,
-      description: `The ${name} guide's own script, in the studio, by its words (studio_guide { "topic": "${name}" } says which, in what order, and what costs money): e.g. ["check"]${name === 'music' ? ', ["quote","--seconds","30"]' : name === 'sound' ? ', ["sfx","pickup"]' : ''}. Paid steps are quoted first and capped by the budget the person agreed to. Long renders hand back a job.`,
+      description: `Local ${name} preparation only; read studio_guide for the workflow. Generation, pricing and provider connections use the official provider MCP in the AI client.`,
       inputSchema: { type: 'object', properties: { args: { type: 'array', items: { type: 'string' }, description: 'The script\'s words' }, ...STUDIO_ARG }, required: ['args'] },
       annotations: { title, readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       run: async (a) => {
@@ -1523,9 +1544,9 @@ export function toolDefs(ctx, avail = {}) {
   return tools;
 }
 
-/** What the media tools need, cheaply (no network): ffmpeg on the PATH, ElevenLabs' CLI or key. */
+/** Local processing availability only; provider connections belong to the AI host. */
 export function availability(env = process.env) {
-  return { node: true, ffmpeg: Boolean(which(process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')), elevenlabs: Boolean(providerKey('elevenlabs', env).key || which(process.platform === 'win32' ? 'elevenlabs.exe' : 'elevenlabs')) };
+  return { node: true, ffmpeg: Boolean(which(process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')) };
 }
 
 /** The codex page small enough to hand a card (a tool result over ~150,000 characters is not shown). */

package/lib/mcp.mjs

@@ -37,7 +37,7 @@ Carry the person's request through to a working result without a lesson or an in
 Run setup_status (for a studio that is not made yet, pass its name as studio), studio_scaffold (NO game until one is requested), then build the requested thing and check it. A demo and a small-change lesson are optional only when requested. Look for existing engine mechanisms and parts_find before building systems. Use few, large edits: one file_edit carries every change to a file in its edits list. game_plan records your decisions; it does not require an interview. Install missing prerequisites yourself with setup_prepare; follow studio_job without asking the person to retry. Optional providers never block.
 New games and apps needing transient shared live state use rules plus view with room.host server. Read studio_guide topic game and its file RULES.md before writing rules: declared entity/shared state and events, guarded deterministic move for immediate local prediction, and a browser view for input and rendering. Read file REWRITE.md when an owner asks to move an old game's rules to the server; no automatic converter exists; existing netplay games keep building and running with their original 32-seat limit; larger rooms require a rewrite. Repair the full build diagnostics and prove the requested behavior in two browsers. Set players.max to the chosen room size, including hundreds; public connections use Gates. Choose room.view radiusM, precisionM, nearM and farHz explicitly and measure at the requested size. Private per-seat state is not delivered. Apps use authorized app records for lasting/private business data; room hosting is not staff permission.
 Show progress briefly and give the preview link as soon as it works. Only when going live was requested, studio_deploy with plan: true says what it creates and costs; cloudflare_login asks for browser approval once; then studio_deploy. Publish to the directory only when requested (offer once after going live). Honour an existing request to deploy or list; do not ask again except for a host's mandatory approval.
-For a shop, stripe_login (shop connect) syncs Products, Prices, Payment Links and the webhook through one Stripe browser approval. No human-handled key. Follow studio_job and the result's single next step; rerun after shop.json changes. Test purchase, webhook, grant and refund with stand-ins before going live. Live payments only when requested.
+For a shop, default to stripe_shop_plan with Stripe official MCP for catalog and links, then stripe_webhook for private webhook installation. stripe_login (shop connect) is the CLI alternative. No human-handled key. Follow studio_job and the result's single next step; rerun after shop.json changes. Test purchase, webhook, grant and refund with stand-ins before going live. Live payments only when requested.
 For a custom domain already on Cloudflare, studio_domain prepares the exact hostname route using the existing sign-in; studio_deploy applies it and Cloudflare creates DNS and TLS. Never ask for zone or account ids. Keep workers.dev until a domain is requested.
 
 If studio_scaffold finds an earlier folder of the studio's name that is not a studio, ask the person whether to fold its premise in (studio_fold), and remove it only with a second yes.

package/lib/media-import.mjs

@@ -0,0 +1,41 @@
+/** Place already downloaded official MCP outputs. No provider networking, credentials or generation. */
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+function inside(root, name) {
+  const path = resolve(root, name), rel = relative(root, path);
+  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) throw new Error('asset paths must stay inside the studio');
+  let ancestor = path;
+  while (!existsSync(ancestor)) ancestor = dirname(ancestor);
+  const actual = relative(realpathSync(root), realpathSync(ancestor));
+  if (isAbsolute(actual) || actual === '..' || actual.startsWith(`..${sep}`)) throw new Error('symlink leaves studio');
+  return path;
+}
+export function importMedia(root, { file, receipt, out, usedBy }) {
+  if (!existsSync(resolve(root, 'studio.json'))) throw new Error('not a studio');
+  const r = typeof receipt === 'string' ? JSON.parse(readFileSync(receipt, 'utf8')) : receipt;
+  for (const key of ['provider','tool','model','requestId','prompt','styleRevision','rights','cost']) if (r?.[key] === undefined) throw new Error(`receipt needs ${key}`);
+  if (!['fal','elevenlabs'].includes(r.provider) || !r.requestId || !r.tool || !r.model || !r.prompt) throw new Error('incomplete official MCP provenance');
+  if (!r.rights?.source || !r.rights?.checkedAt || typeof r.rights?.commercial !== 'boolean') throw new Error('record rights source, date and commercial permission');
+  if (!['estimate','actual','unknown'].includes(r.cost?.status) || (r.cost.status !== 'unknown' && !(Number.isFinite(r.cost.amount) && r.cost.amount >= 0 && r.cost.unit))) throw new Error('cost must be actual, estimate or explicitly unknown');
+  const target = inside(root, out), use = inside(root, usedBy);
+  const bytes = readFileSync(file);
+  if (!bytes.length) throw new Error('empty asset');
+  const hash = createHash('sha256').update(bytes).digest('hex');
+  const registry = inside(root, 'media/provenance.json');
+  const records = existsSync(registry) ? JSON.parse(readFileSync(registry,'utf8')) : [];
+  const previous = records.find(x => x.provider === r.provider && x.requestId === r.requestId && x.output === out);
+  if (previous && previous.sha256 !== hash) throw new Error('same output identity has different bytes');
+  if (existsSync(target) && createHash('sha256').update(readFileSync(target)).digest('hex') !== hash) throw new Error('destination already contains a different asset');
+  // Store only allowlisted provenance; raw tool responses may contain temporary signed URLs.
+  const record = { provider:r.provider, tool:r.tool, model:r.model, requestId:r.requestId, prompt:r.prompt, styleRevision:r.styleRevision,
+    rights:{ source:r.rights.source, checkedAt:r.rights.checkedAt, commercial:r.rights.commercial, note:r.rights.note ?? null },
+    cost:{ status:r.cost.status, amount:r.cost.amount ?? null, unit:r.cost.unit ?? null }, fixture:r.fixture === true,
+    output:out, usedBy, sha256:hash, bytes:bytes.length };
+  // Static reference evidence is not a runtime claim. Skills must also inspect the running scene.
+  const reference = relative(dirname(use), target).split(sep).join('/');
+  if (!readFileSync(use,'utf8').includes(reference)) throw new Error(`consumer does not reference ${reference}`);
+  mkdirSync(dirname(target),{recursive:true}); copyFileSync(file,target);
+  if (!previous) { records.push(record); mkdirSync(dirname(registry),{recursive:true}); writeFileSync(registry,JSON.stringify(records,null,2)+'\n'); }
+  return { ok:true, command:'media import', artifact:out, provenance:'media/provenance.json', sha256:hash, already:Boolean(previous), usage:'static reference verified; inspect the running scene' };
+}

package/lib/media-workflows.mjs

@@ -0,0 +1,13 @@
+/** Declarative tool references for Homie's media skills; host namespaces are resolved by the AI. */
+export const MEDIA_WORKFLOWS = Object.freeze({
+ art: { provider:'fal', tools:['recommend_model','get_model_schema','get_pricing','run_model','check_job','get_job_result','upload_file'] },
+ models: { provider:'fal', tools:['recommend_model','get_model_schema','get_pricing','run_model','submit_job','check_job','get_job_result'] },
+ video: { provider:'fal', tools:['recommend_model','get_model_schema','get_pricing','submit_job','check_job','get_job_result'] },
+ style: { provider:'fal', tools:['recommend_model','get_model_schema','get_pricing','run_model','check_job','get_job_result'] },
+ music: { provider:'elevenlabs', tools:['creative_get_flow_node_types','creative_get_model_guide','creative_get_flow_run_status'], generation:'discover from connected workspace schema' },
+ sound: { provider:'elevenlabs', tools:['creative_get_flow_node_types','creative_get_model_guide','creative_get_flow_run_status'], generation:'discover from connected workspace schema' },
+});
+export function validateMediaTools(workflow, tools) {
+ const available=new Set(tools.map(t=>t.name));
+ return {ready:workflow.tools.every(t=>available.has(t)), missing:workflow.tools.filter(t=>!available.has(t))};
+}

package/lib/needs-headless.mjs

@@ -0,0 +1,34 @@
+import {localCookie} from './local-test.mjs';
+
+/** Each action has an explicit local identity, using the real MCP transport and permissions. */
+export function needsHeadless({url,secret,app,meta,scope}) {
+  return async (item,role) => {
+    if(!secret)throw new Error('Headless role proof requires homie-studio dev in this studio and its localhost URL');
+    if(!role || (role!=='owner'&&!Object.hasOwn(meta.roles??{},role)))throw new Error(`Name a declared role (or owner) for headless proof; got ${role??'none'}`);
+    const {Client,StreamableHTTPClientTransport}=await import('mcp-studio-client');
+    const client=new Client({name:'Homie needs check',version:'1.0.0'});
+    const transport=new StreamableHTTPClientTransport(new URL('/mcp',url),{requestInit:{headers:{authorization:`Bearer ${secret}`,cookie:`homie_test=${localCookie(secret,{app,role,scope})}`}}});
+    try {
+      await client.connect(transport);
+      let call=item.mcp;
+      if(item.records)call={tool:'app_records',arguments:{...item.records,app,role,operation:'read'}};
+      if(item.schedule)call={tool:'studio_schedule_fire',arguments:item.schedule};
+      if(call?.method) {
+        if(call.method==='resources/read')return await client.readResource(call.params);
+        // The extension's JSON-RPC result is intentionally preserved for path assertions.
+        if(['events/list','events/poll'].includes(call.method)) {
+          const {z}=await import('zod');
+          return await client.request({method:call.method,params:call.params??{}},z.object({}).passthrough(),{timeout:10000});
+        }
+        throw new Error(`Unsupported MCP proof method ${call.method}; use tools, resources/read, events/list or events/poll`);
+      }
+      if(!call?.tool)throw new Error('MCP step requires tool and optional arguments');
+      const result=await client.callTool({name:call.tool,arguments:call.arguments??{}},undefined,{timeout:item.schedule?15000:10000});
+      if(result.isError)throw new Error(result.content?.filter(c=>c.type==='text').map(c=>c.text).join('; ')||'MCP tool failed');
+      if(result.structuredContent!==undefined)return result.structuredContent;
+      const content=result.content?.filter(c=>c.type==='text');
+      if(content?.length===1) {try {const parsed=JSON.parse(content[0].text);return parsed.kind==='untrusted-tool-data'?parsed.data:parsed;}catch{}}
+      return result;
+    } finally {await client.close();}
+  };
+}

package/lib/official-media.mjs

@@ -0,0 +1,15 @@
+/** Provider connections belong to the AI host. Never inspect credentials or host configuration. */
+export const INTEGRATIONS = Object.freeze({
+  fal: { label: 'fal', url: 'https://mcp.fal.ai/mcp-relay', connectUrl: 'https://fal.ai/docs/documentation/setting-up/mcp', unlocks: 'Images, 3D and generated video', connect: 'Install the official fal plugin in your AI client, or add this remote MCP URL, then approve its browser sign-in once.' },
+  elevenlabs: { label: 'ElevenLabs', url: 'https://api.elevenlabs.io/v1/mcp', connectUrl: 'https://elevenlabs.io/mcp', unlocks: 'Music, speech and sound where exposed by the connected MCP', connect: 'Install elevenlabs/plugin in your AI client, or add this remote MCP URL, then approve its browser sign-in once. Discover the workspace tools before promising a media capability.' },
+  cloudflare: { label: 'Cloudflare MCP', url: 'https://mcp.cloudflare.com/mcp', connectUrl: 'https://github.com/cloudflare/skills', unlocks: 'Inspect Workers Issues, logs and D1 through official tools', connect: 'Connect the official Cloudflare plugin or this MCP URL and approve account access in the browser. Deploys separately use Wrangler login (cloudflare_login).' },
+});
+export function officialConnections(evidence = {}) {
+  return Object.entries(INTEGRATIONS).map(([provider, p]) => {
+    const connected = evidence[provider] === 'connected';
+    return { id: provider === 'cloudflare' ? 'cloudflare-mcp' : provider, label: p.label, need: 'optional', state: connected ? 'ok' : 'optional',
+      connection: connected ? 'connected' : evidence[provider] === 'unavailable' ? 'unavailable' : 'unknown',
+      detail: connected ? 'Official MCP connected (authenticated call reported by this AI session)' : evidence[provider] === 'unavailable' ? 'Official MCP unavailable in this AI session' : 'Connection unknown: the AI host must discover tools and verify an authenticated read',
+      unlocks: p.unlocks, fix: connected ? null : { who: 'person', open: p.connectUrl, say: `${p.connect} MCP URL: ${p.url}` } };
+  });
+}

package/lib/rules-build.mjs

@@ -141,7 +141,8 @@ export function smokeRun(H, compiled, id, { timer = () => { const t = process.cp
  * Returns { code, tune, map, settings, seats, stateHash, schema, publicTune, build, files, rounds, units, tickUnits, check }.
  * `longCheck`: eight times the generated play (`homie-studio build --long-check`).
  */
-export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck = false } = {}) {
+export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck = false, quick = false } = {}) {
+  log(`${g.id}: checking rules and types${quick ? ' (quick rebuild; play checks skipped)' : ''}`);
   const guarded = await guardRules(esbuild, root, g.dir);
   if (!guarded.ok) throw new Error(`${g.kind === 'app' ? 'apps' : 'games'}/${g.id}: its rules were refused.\n${guarded.problems.slice(0, 20).map((p) => `  ${problemLine(p)}`).join('\n')}${guarded.problems.length > 20 ? `\n  … and ${guarded.problems.length - 20} more` : ''}`);
   const tune = readJson(join(g.dir, 'tunables.json')) ?? {};
@@ -157,8 +158,14 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
   const bundle = await loadRules(esbuild, root, g.id, guarded.code, { bundleOnly: true, physics: Boolean(map.physics) });
   const data = { id: g.id, tune, map, room: g.room, seats, vocab: readJson(join(g.dir, 'agents.json')), sites: guarded.sites };
   // The declarations first, for the type check: a wrong program is named by the compiler before anything is played.
-  await typecheckRules(root, g, await runRulesWorker(bundle, data, { declarationsOnly: true }), tune, { log });
-  const checked = await runRulesWorker(bundle, data, { allowance: longCheck ? LONG_ALLOWANCE : ALLOWANCE });
+  const declarations=await runRulesWorker(bundle,data,{declarationsOnly:true});
+  await typecheckRules(root,g,declarations,tune,{log});
+  log(`${g.id}: ${quick?'skipping generated play':'running generated rules play; use build --quick for an iteration without play checks'}`);
+  const heartbeat=setInterval(()=>log(`${g.id}: rules play still running (${Math.round((Date.now()-started)/1000)}s)`),15000);
+  const started=Date.now();
+  let checked;
+  try { checked=quick?{...declarations,information:[],plays:[],ticks:0,roundsPlayed:0,restores:0,units:0,maxUnits:0,maxTickUnits:0,largestSaveBytes:0}:await runRulesWorker(bundle,data,{allowance:longCheck?LONG_ALLOWANCE:ALLOWANCE}); }
+  finally {clearInterval(heartbeat);}
   for (const p of checked.problems) log(`warning: ${g.kind === 'app' ? 'apps' : 'games'}/${g.id}/${g.kind === 'app' ? 'app' : 'game'}.json: ${p}`);
   for (const line of checked.information) log(`info: ${line}`);
   const { settings, schema, publicTune, rounds, stateHash } = checked;
@@ -168,7 +175,8 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
   const { def, R, H, initializePhysics } = await loadRules(esbuild, root, g.id, guarded.code, {physics: Boolean(map.physics)});
   if (initializePhysics) await initializePhysics(readFileSync(new URL(import.meta.resolve('@homie-rocks/physics/vendor/rapier.wasm'))));
   const compiled = R.compileRules(def, { tune, map: R.compileMap(map, map.name), settings, seats });
-  const stats = smokeRun(H, compiled, g.id, { timer: () => 0, vocab: data.vocab });
+  log(`${g.id}: ${quick?'skipping':'running'} rules snapshot smoke check`);
+  const stats = quick ? {snapshotBytes:null,checkpointBytes:null,frameBytes:{},frameRates:{}} : smokeRun(H, compiled, g.id, { timer: () => 0, vocab: data.vocab });
   const snapshotCap = capOf('snap', seats); const checkpointCap = capOf('ckpt', seats);
   const exceeded = RULES_FRAMES.flatMap(t => {
     const bytes = stats.frameBytes[t] ?? 0; const cap = capOf(t, seats);
@@ -187,7 +195,7 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
     build: createHash('sha256').update(guarded.code).update(JSON.stringify(built)).digest('hex'),
     snapshotCap, checkpointCap, snapshotBytes: stats.snapshotBytes, checkpointBytes: stats.checkpointBytes,
     units: checked.maxUnits, tickUnits: checked.maxTickUnits,
-    check: { information: checked.information, capacityTrial: trial, plays: checked.plays, ticks: checked.ticks, rounds: checked.roundsPlayed, restores: checked.restores, units: checked.units, largestSaveBytes: checked.largestSaveBytes },
+    check: { skipped: quick, information: checked.information, capacityTrial: trial, plays: checked.plays, ticks: checked.ticks, rounds: checked.roundsPlayed, restores: checked.restores, units: checked.units, largestSaveBytes: checked.largestSaveBytes },
   };
 }
 

package/lib/scaffold.mjs

@@ -535,7 +535,7 @@ where it sells and for Stripe's terms. Homie takes no cut.
   player refund window covers items; a tip is never taken back by the player.
 - Flood settings are configurable: buyer attempts 6/minute, address attempts 600/minute,
   new guest buyers 600/hour. Stripe constraints, integer arithmetic, ownership and signatures protect payments.
-- \`shop check\` validates settings; \`stripe_login\` / \`shop connect\` starts Stripe browser approval.
+- \`shop check\` validates settings; \`stripe_shop_plan\` plans and verifies Stripe official MCP operations; \`stripe_webhook\` installs the signing secret privately.
   Never ask a person for a key. Follow the result's next step: deploy first if needed, then rerun connect.
   The default syncs Products, Prices, Payment Links and the webhook through the approved Stripe CLI.
   The Worker stores only links and a signing secret; buying needs no API key or running AI.
@@ -719,7 +719,7 @@ site/.wrangler/
 .wrangler/
 .dev.vars
 .env
-# Stripe Projects (setup --via stripe-projects): credentials stay in its vault and the .env files it syncs, never in git.
+# Provider-owned credential stores and local environment files never belong in git.
 .env.*
 .projects/vault/
 .projects/cache/

package/lib/shop-links.mjs

@@ -6,7 +6,8 @@ import { LINKS_STRIPE_VERSION, linkSettings, paymentLinkURL } from '../worker/sh
 import { HOOK_EVENTS, SHOP_HOOK_EVENTS } from './shop.mjs';
 const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 const same = (a, b) => Object.keys(a ?? {}).length === Object.keys(b).length && Object.entries(b).every(([k, v]) => a?.[k] === v);
-export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, receipt, saveReceipt, bookingSlots = [], local = false }) {
+export const matchesFields = (actual, expected) => Array.isArray(expected) ? Array.isArray(actual) && actual.length === expected.length && expected.every((v,i)=>matchesFields(actual[i],v)) : expected && typeof expected === 'object' ? Object.entries(expected).every(([k,v]) => matchesFields(actual?.[k],v)) : actual === expected;
+export async function reconcilePaymentLinks({ api, shop, slug, site, mode, bookingSlots = [], verifyObjects = false }) {
   const list = async (path, params = {}) => {
     const all = []; let cursor;
     do {
@@ -19,15 +20,16 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     } while (cursor);
     return all;
   };
-  if(local && mode!=='test')throw new Error('Local checkout requires Stripe test mode');
-  const secrets = local ? {code:0,stdout:'[]'} : await w(['secret', 'list']);
-  if (secrets.code !== 0) return { ok: false, needs: 'cloudflare', why: 'Connect Cloudflare and deploy the studio, then run shop connect again.' };
-  const names = JSON.parse(secrets.stdout ?? secrets.out);
-  const has = (name) => names.some((s) => s.name === name);
   const products = await list('/v1/products');
   const prices = await list('/v1/prices');
   const links = await list('/v1/payment_links');
   const own = (o) => o.metadata?.homie === 'shop-links-v1' && o.metadata?.studio === slug && o.metadata?.origin === site;
+  const verifyLink = async (link, params) => {
+    if (!verifyObjects) return;
+    const actual=await api('GET',`/v1/payment_links/${link.id}`,{expand:['line_items']});
+    const normalized={...actual,line_items:actual.line_items?.data?.map(line=>({...line,price:line.price?.id??line.price}))};
+    if(actual.id!==link.id || actual.active!==link.active || actual.url!==link.url || actual.line_items?.has_more===true || !matchesFields(actual.metadata,link.metadata) || !paymentLinkURL(actual.url) || !matchesFields(normalized,params)) throw new Error(`Stripe Payment Link ${link.id} differs from its planned fields. Restore its configuration through Stripe MCP before verifying.`);
+  };
   const config = { v: 1, mode, settings: linkSettings(shop), items: [] };
   const customText=shop.giving?.receiptText ? {custom_text:{submit:{message:shop.giving.receiptText}}} : {};
   const catalogPrices = new Map();
@@ -36,7 +38,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const id = await productIdOf(slug, item.id);
     keepProducts.add(id);
     const metadata = { homie: 'shop-links-v1', studio: slug, origin: site };
-    const fields = { name: item.name, ...(item.blurb ? {description:item.blurb} : {}), tax_code: item.taxCode ?? defaultTaxCode(item), metadata, active: true };
+    const fields = { name: item.name, description:item.blurb??'', tax_code: item.taxCode ?? defaultTaxCode(item), metadata, active: true };
     let product = products.find((p) => p.id === id);
     if (!product) product = await api('POST', '/v1/products', { id, ...fields }, `product-${hash(id)}`);
     else if (!same(product.metadata, metadata) || product.name !== fields.name || (product.description ?? '') !== (fields.description ?? '') || (product.tax_code?.id ?? product.tax_code) !== fields.tax_code || !product.active) await api('POST', `/v1/products/${id}`, fields);
@@ -48,6 +50,8 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const revision = hash(priceFields);
     let price = prices.find((p) => own(p) && p.product === id && p.metadata?.revision === revision);
     if (!price) price = await api('POST', '/v1/prices', { ...priceFields, metadata: { ...metadata, revision } }, `price-${hash({ priceFields, metadata })}`);
+    if (verifyObjects && ((price.recurring?.interval_count??1)!==1 || Boolean(price.recurring)!==Boolean(item.interval) || Boolean(price.custom_unit_amount)!==(item.price==='choose'))) throw new Error(`Stripe Price ${price.id} has a different payment type from shop.json`);
+    if (verifyObjects && !matchesFields({...price, product:price.product?.id??price.product, ...(price.custom_unit_amount?{custom_unit_amount:{...price.custom_unit_amount,enabled:true}}:{})},priceFields)) throw new Error(`Stripe Price ${price.id} differs from shop.json; restore or archive it through Stripe MCP before planning again.`);
     if (!price.active) await api('POST', `/v1/prices/${price.id}`, { active: true });
     keepPrices.add(price.id);
     catalogPrices.set(item.id, price.id);
@@ -61,6 +65,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const linkRevision = hash({ params, item, policy: shop.policy });
     let link = links.find((p) => own(p) && p.metadata?.revision === linkRevision);
     if (!link) link = await api('POST', '/v1/payment_links', { ...params, metadata: { ...metadata, revision: linkRevision } }, `link-${linkRevision}`);
+    await verifyLink(link,params);
     if (!link.active) await api('POST', `/v1/payment_links/${link.id}`, { active: true });
     if (!paymentLinkURL(link.url) || !/^plink_\w+$/.test(link.id)) throw new Error('Invalid Payment Link');
     keepLinks.add(link.id);
@@ -73,7 +78,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
   const menuItems = shop.items.filter(i => typeof i.price === 'number' && i.price > 0 && !i.interval);
   const metadata = { homie: 'shop-links-v1', studio: slug, origin: site };
   const groups=Map.groupBy(menuItems,i=>i.game??'');
-  for(const group of groups.values()) for (let offset = 0; offset < group.length; offset += 10) {
+  for(const group of (shop.basket ? [] : groups.values())) for (let offset = 0; offset < group.length; offset += 10) {
     const items = group.slice(offset, offset + 10);
     if (items.length < 2) continue;
     const params = { ...customText, line_items: items.map(i => ({price:catalogPrices.get(i.id),quantity:1,adjustable_quantity:{enabled:true,minimum:0,maximum:shop.policy.repeatPurchases?999999:1}})),
@@ -83,13 +88,40 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const revision=hash(params);
     let link=links.find(p=>own(p)&&p.metadata?.revision===revision);
     if(!link)link=await api('POST','/v1/payment_links',{...params,metadata:{...metadata,revision}},`menu-${revision}`);
+    await verifyLink(link,params);
     if(!link.active)await api('POST',`/v1/payment_links/${link.id}`,{active:true});
     keepLinks.add(link.id);
     config.menus.push({id:link.id,url:link.url,revision,items:items.map(i=>({item:i.id,price:catalogPrices.get(i.id)}))});
   }
+  // One aggregate payment represents a frozen local basket, including one-item baskets.
+  // Runtime uses prefilled_amount, never a shared Price mutation: concurrent
+  // guests must receive their own saved totals.
+  if(shop.basket) for(const [game,items] of groups) {
+    const id=await productIdOf(slug,`basket-${game||'shop'}`);
+    keepProducts.add(id);
+    const fields={name:shop.basket.name,description:shop.basket.description,metadata,active:true};
+    const product=products.find(p=>p.id===id);
+    if(!product)await api('POST','/v1/products',{id,...fields},`product-${hash(id)}`);
+    else if(product.name!==fields.name || product.description!==fields.description || !product.active)await api('POST',`/v1/products/${id}`,fields);
+    const priceFields={product:id,currency:shop.currency,custom_unit_amount:{enabled:true},tax_behavior:'inclusive'};
+    const priceRevision=hash(priceFields);
+    let price=prices.find(p=>own(p)&&p.product===id&&p.metadata?.revision===priceRevision);
+    if(!price)price=await api('POST','/v1/prices',{...priceFields,metadata:{...metadata,revision:priceRevision}},`price-${hash({priceFields,metadata})}`);
+    if(!price.active)await api('POST',`/v1/prices/${price.id}`,{active:true});
+    keepPrices.add(price.id);
+    const params={line_items:[{price:price.id,quantity:1}],automatic_tax:{enabled:false},payment_intent_data:{metadata},
+      after_completion:{type:'redirect',redirect:{url:`${site}/shop/thanks?session_id={CHECKOUT_SESSION_ID}`}}};
+    const revision=hash(params);
+    let link=links.find(p=>own(p)&&p.metadata?.revision===revision);
+    if(!link)link=await api('POST','/v1/payment_links',{...params,metadata:{...metadata,revision}},`basket-${revision}`);
+    if(!link.active)await api('POST',`/v1/payment_links/${link.id}`,{active:true});
+    if(!paymentLinkURL(link.url))throw new Error('Invalid basket Payment Link');
+    keepLinks.add(link.id);
+    config.menus.push({id:link.id,url:link.url,revision,price:price.id,basket:true,items:items.map(i=>({item:i.id,price:catalogPrices.get(i.id)}))});
+  }
   config.slots=[];
   const pause=async link=>{
-    await api('POST',`/v1/payment_links/${link.id}`,{active:false});
+    if(link.active) await api('POST',`/v1/payment_links/${link.id}`,{active:false});
     for(const session of await list('/v1/checkout/sessions',{payment_link:link.id,status:'open'})) {
       await api('POST',`/v1/checkout/sessions/${session.id}/expire`);
     }
@@ -107,11 +139,13 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     let link=links.find(p=>own(p)&&p.metadata?.slot===identity);
     if(!link && (!slot.capacity||slot.active===false))continue;
     if(link?.metadata?.price && link.metadata.price!==catalogPrices.get(item.id))throw new Error('Slot service price changed. Deactivate the old slot and publish a new slot ID after reviewing existing bookings.');
-    if(slot.confirmed!==undefined && link?.active && slot.active!==false)throw new Error('Pause affected slot links before recounting confirmed seats; wait for signed payments, move/refund, then sync the fresh counts.');
+    const seatsRevision=hash({slot,capacity:slot.capacity,confirmed:slot.confirmed});
+    const counted=slot.confirmed!==undefined && link?.metadata?.seats_revision===seatsRevision;
+    if(slot.confirmed!==undefined && !counted && link?.active && slot.active!==false)throw new Error('Pause affected slot links before recounting confirmed seats; wait for signed payments, move/refund, then sync the fresh counts.');
     const count=link?.restrictions?.completed_sessions?.count??0;
     // Initial publication uses capacity exactly. After a reviewed move/refund the
     // AI supplies current confirmed seats; keep the existing Stripe lifetime count.
-    const limit=slot.confirmed===undefined ? slot.capacity : count+slot.capacity-slot.confirmed;
+    const limit=counted ? Number(link.metadata.seats_limit) : slot.confirmed===undefined ? slot.capacity : count+slot.capacity-slot.confirmed;
     const active=slot.active!==false && limit>count;
     const params={...customText,line_items:[{price:catalogPrices.get(item.id),quantity:1}],payment_method_types:['card'],
       restrictions:{completed_sessions:{limit:Math.max(1,limit)}},after_completion:{type:'redirect',redirect:{url:`${site}/shop/thanks?session_id={CHECKOUT_SESSION_ID}`}}};
@@ -119,9 +153,10 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     else {
       // Pause first whenever publishing a changed budget, so old sessions cannot
       // spend a previous capacity after staff moves or removes a slot.
-      if(!active || link.restrictions?.completed_sessions?.limit!==limit)await pause(link);
-      link=await api('POST',`/v1/payment_links/${link.id}`,{restrictions:params.restrictions,active});
+      if(!active || link.restrictions?.completed_sessions?.limit!==Math.max(1,limit))await pause(link);
+      if (link.active !== active || link.restrictions?.completed_sessions?.limit !== Math.max(1,limit) || slot.confirmed!==undefined && !counted) link=await api('POST',`/v1/payment_links/${link.id}`,{restrictions:params.restrictions,active,...(slot.confirmed!==undefined?{metadata:{seats_revision:seatsRevision,seats_limit:String(limit)}}:{})});
     }
+    await verifyLink(link,params);
     keepLinks.add(link.id);
     config.slots.push({...slot,id:link.id,url:link.url,price:catalogPrices.get(item.id),revision:identity,active:link.active,count:link.restrictions?.completed_sessions?.count??0,limit,paused:slot.active===false});
   }
@@ -132,11 +167,40 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
     const portals=await list('/v1/billing_portal/configurations');
     let portal=portals.find(p=>own(p));
     const params={features:{subscription_cancel:{enabled:true},payment_method_update:{enabled:true},invoice_history:{enabled:true}},login_page:{enabled:true},business_profile:{headline:'Manage your membership or giving'},default_return_url:`${site}/shop/`,metadata};
-    portal=await api('POST',portal?`/v1/billing_portal/configurations/${portal.id}`:'/v1/billing_portal/configurations',params);
+    if (!portal || !matchesFields(portal, params)) portal=await api('POST',portal?`/v1/billing_portal/configurations/${portal.id}`:'/v1/billing_portal/configurations',params, portal?undefined:`portal-${hash({slug,site,params})}`);
     config.portal=portal.login_page?.url;
   }
-  if(local)return {ok:true,command:'shop connect',local:true,mode,config};
-  const purchases = root ? await (await import('./purchase-links.mjs')).syncPurchaseLinks({ root, api, slug, site, mode, list, till: shop.purchasesTill ?? shop.till }) : null;
+  const retire = [
+    ...links.filter(p=>own(p)&&p.active&&!keepLinks.has(p.id)).map(p=>({method:'POST',path:`/v1/payment_links/${p.id}`,params:{active:false}})),
+    ...prices.filter(p=>own(p)&&p.active&&!keepPrices.has(p.id)).map(p=>({method:'POST',path:`/v1/prices/${p.id}`,params:{active:false}})),
+    ...products.filter(p=>own(p)&&p.active&&!keepProducts.has(p.id)).map(p=>({method:'POST',path:`/v1/products/${p.id}`,params:{active:false}})),
+  ];
+  return {config, retire};
+}
+
+export async function syncPaymentLinks(options) {
+  const {root, api, shop, slug, site, mode, w, receipt, saveReceipt, local = false} = options;
+  if (local && mode !== 'test') throw new Error('Local checkout requires Stripe test mode');
+  const {config, retire} = options.catalog ?? await reconcilePaymentLinks(options);
+  if (local) return {ok:true, command:'shop connect', local:true, mode, config};
+  const list = async (path,params={}) => {
+    const all=[]; let cursor;
+    do {
+      const page=await api('GET',path,{...params,limit:100,...(cursor?{starting_after:cursor}:{})});
+      if (!Array.isArray(page.data)) throw new Error('Incomplete Stripe list');
+      all.push(...page.data);
+      const next=page.has_more?page.data.at(-1)?.id:null;
+      if(page.has_more && (!next || next===cursor))throw new Error('Incomplete Stripe pagination');
+      cursor=next;
+    }while(cursor);
+    return all;
+  };
+  const secrets=await w(['secret','list']);
+  if(secrets.code!==0)return {ok:false,needs:'cloudflare',why:'Connect Cloudflare before installing the shop.'};
+  const names=JSON.parse(secrets.stdout??secrets.out);
+  const has=name=>names.some(s=>s.name===name);
+
+  const purchases = root && !options.catalog ? await (await import('./purchase-links.mjs')).syncPurchaseLinks({ root, api, slug, site, mode, list, till: shop.purchasesTill ?? shop.till }) : null;
   const purchaseSecrets = {};
   if (purchases?.config.offers.length && !has('PURCHASE_SIGNING_KEYS')) {
     const { generateKeyPair, exportJWK } = await import('jose');
@@ -166,9 +230,7 @@ export async function syncPaymentLinks({ root, api, shop, slug, site, mode, w, r
   }
   await purchases?.retire();
   // Retire only after the replacement configuration and signing secret are installed.
-  for (const link of links.filter((p) => own(p) && p.active && !keepLinks.has(p.id))) await api('POST', `/v1/payment_links/${link.id}`, { active: false });
-  for (const price of prices.filter((p) => own(p) && p.active && !keepPrices.has(p.id))) await api('POST', `/v1/prices/${price.id}`, { active: false });
-  for (const product of products.filter((p) => own(p) && p.active && !keepProducts.has(p.id))) await api('POST', `/v1/products/${product.id}`, { active: false });
+  if (!options.catalog) for (const op of retire) await api(op.method, op.path, op.params);
   for (const e of endpoints.filter((e) => e.id !== endpoint.id && e.url === url && e.metadata?.homie === 'shop-v1' && e.status !== 'disabled')) await api('POST', `/v1/webhook_endpoints/${e.id}`, { disabled: true });
   return { ok: true, command: 'shop connect', mode, keyless: true, saved: !unchanged, alreadyConnected: Boolean(unchanged), webhook: { id: endpoint.id, url }, verifiedPurchase: false,
     message: 'Your shop uses Stripe Payment Links. No Stripe API key is stored in the Worker.',

package/lib/shop-listen.mjs

@@ -0,0 +1,43 @@
+/** Private local Stripe forwarding. Only the allowlisted readiness line reaches the model. */
+import {spawn} from 'node:child_process';
+import {readFileSync,writeFileSync,existsSync,chmodSync} from 'node:fs';
+import {join} from 'node:path';
+import {stripeProcess,completionArgs} from './stripe-connect.mjs';
+export function saveLocalStripe(root,values) {
+  const file=join(root,'.dev.vars');
+  let text=existsSync(file)?readFileSync(file,'utf8'):'';
+  for(const [key,value] of Object.entries(values)) {
+    text=text.replace(new RegExp(`^${key}=.*\\n?`,'gm'),'');
+    text+=`\n${key}=${value}\n`;
+  }
+  writeFileSync(file,text,{mode:0o600});
+  chmodSync(file,0o600);
+}
+export async function shopListen(root,{profile,port=8787,log=()=>{},exec=stripeProcess,spawnProcess=spawn}={}) {
+  if(!profile || !Number.isInteger(Number(port)) || Number(port)<1 || Number(port)>65535)throw new Error('Supply a sandbox profile and local port');
+  const cli=args=>exec(['--project-name',profile,...args],{cwd:root});
+  const probe=await cli(['get','/v1/products','-d','limit=1']);
+  if(probe.code!==0) {
+    const start=await cli(['login','--non-interactive']);
+    let login;try{login=JSON.parse(start.stdout);}catch{}
+    const complete=completionArgs(login?.next_step);
+    const u=login?.browser_url;
+    if(!complete || !/^https:\/\/(dashboard|access)\.stripe\.com\//.test(u??''))throw new Error('Update Stripe CLI and retry local browser approval');
+    log(`Approve Stripe sandbox access: ${u}`);
+    if((await cli(complete)).code!==0)throw new Error('Stripe browser approval did not finish');
+  }
+  const env={...process.env};for(const key of Object.keys(env))if(key.startsWith('STRIPE_'))delete env[key];
+  return new Promise((resolve,reject)=>{
+    const child=spawnProcess('stripe',['--project-name',profile,'listen','--all-snapshot','--forward-to',`http://localhost:${port}/api/shop/hook`],{cwd:root,env,stdio:['ignore','pipe','pipe']});
+    let buffer='',ready=false;
+    const capture=data=>{
+      buffer=(buffer+data.toString()).slice(-8192);
+      const secret=/whsec_[A-Za-z0-9+/=_-]+(?=[\s\x1b])/.exec(buffer)?.[0];
+      if(secret && !ready){saveLocalStripe(root,{STRIPE_WEBHOOK_SECRET:secret});ready=true;buffer='';log('Stripe sandbox forwarding ready. Signing secret saved privately; start/restart homie-studio dev.');}
+    };
+    child.stdout.on('data',capture);child.stderr.on('data',capture);
+    child.on('error',()=>reject(new Error('Install Stripe CLI before local forwarding')));
+    const stop=()=>child.kill();process.once('SIGTERM',stop);process.once('SIGINT',stop);
+    child.on('close',code=>{process.removeListener('SIGTERM',stop);process.removeListener('SIGINT',stop);resolve({ok:ready&&code===0,command:'shop listen',ready});});
+  });
+}

package/lib/shop-local.mjs

@@ -27,5 +27,5 @@ export async function shopConnectLocal(root,{url,profile,exec=stripeProcess}={})
  vars=vars.replace(/^STRIPE_(?:SHOP_LINKS|CHECKOUT_MODE)=.*\n?/gm,'');
  vars+=`\nSTRIPE_CHECKOUT_MODE=links\nSTRIPE_SHOP_LINKS=base64:${Buffer.from(JSON.stringify(r.config)).toString('base64')}\n`;
  writeFileSync(file,vars,{mode:0o600});
- return {ok:true,command:'shop connect',local:true,mode:'test',url:origin.origin,message:'Test Payment Links saved to root .dev.vars.',next:[`stripe --project-name ${profile} listen --all-snapshot --forward-to http://localhost:${origin.port||80}/api/shop/hook`,'Put the listener signing secret in root .dev.vars as STRIPE_WEBHOOK_SECRET, then start/restart homie-studio dev --lan. Keep the listener running.','Open the same Wi-Fi address on phones; complete Stripe test checkout and verify the paid order and app event.']};
+ return {ok:true,command:'shop connect',local:true,mode:'test',url:origin.origin,message:'Test Payment Links saved to root .dev.vars.',next:[`homie-studio shop listen --profile '${profile}' --port ${origin.port||80}`,'The listener saves the signing secret privately. Start/restart homie-studio dev --lan after it reports ready.','Open the same Wi-Fi address on phones and verify the paid order and app event.']};
 }