@homie-rocks/studio 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -17,6 +17,33 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.53.0] - 2026-10-15
+
+**Plugin 0.53.0**
+
+Take bookings against real resources, keep private apps usable, collect deposits reliably and turn tested examples into your own place.
+
+### Added
+
+- **Bookings that fit your place:** Reserve shared resources alongside booking capacity, allocate packages, and use seasonal calendars in your place's time zone. Shared phone controls let customers choose booking options and resources; common booking argument aliases work across tools.
+- **Keep upcoming slots ready to sell:** Declared `booking.slots_need_payment_links` events let your studio respond when rolling slot inventory needs payment links.
+- **Apps customers can install:** Public apps can offer a direct install page with a web manifest and optional service worker. Add your own icons and offline behavior; installation support depends on the browser.
+- **A quicker start from an example:** Fork editable source with new studio and app identities and fresh deployment settings. A single concept flag marks previews with a TEST / CONCEPT banner and keeps them out of the directory and search indexing.
+- **Turn-based games without unnecessary physics:** Participants can have private roles and timed phases without needing physics bodies. Private fields remain visible only to their owning player.
+- **Simpler Stripe setup:** `shop observe` accepts incremental public responses from Stripe's official plugin and returns the next setup plan without a hand-built observations file. New Stripe sign-ins show pairing instructions in the job's progress before approval completes.
+
+### Fixed
+
+- **Deposits tied to the right booking:** Supporter and deposit links keep quantity at one. Variable deposits retain the app reference and require the saved subtotal before fulfillment; booking and AI checkout also preserve the reference in the saved order.
+- **Private apps that load safely:** Authorized private app frames can load their modules through expiring asset links while anonymous modules and records stay closed. Missing record IDs explain exactly where to supply the ID.
+- **Checks that reflect each screen's role:** Wall and phone permissions remain separate, each need starts in a fresh room after the baseline, and saving check evidence no longer restarts development. Brief Cloudflare startup failures retry with a visible notice.
+- **Smoother shop upgrades:** Existing billing portals are discovered when older verifications lack their IDs. Webhook setup fills missing account IDs after checking link ownership with the saved Stripe login; reused logins no longer show unnecessary pairing instructions.
+
+### Upgrade notes
+
+- Apply `0030_booking_resources.sql` after the existing booking migrations to use resource-aware bookings.
+- Concept mode labels a preview; it does not isolate payment credentials or data. Installed public app surfaces run as same-origin studio code; private app shells keep their sandbox.
+
 ## [0.52.0] - 2026-10-15
 
 **Plugin 0.52.0**

package/apps/apps.ts

@@ -76,3 +76,20 @@ export function createAppContext() {
     dispose() {removeEventListener('message',receive);listeners.clear();}
   };
 }
+
+/** Native accessible choices; submit value() to the same booking tool used by an AI. */
+export function createBookingChoices({container,options=[],resources=[]}:{container:HTMLElement;options?:Array<{id:string;name:string}>;resources?:Array<{id:string;name:string}>}) {
+  const fields=new Map<string,HTMLSelectElement>();
+  const group=document.createElement('fieldset');
+  const legend=document.createElement('legend');legend.textContent='Choose an option';group.append(legend);
+  for(const [name,choices] of [['option',options],['resource',resources]] as const) {
+    if(!choices.length)continue;
+    const label=document.createElement('label');label.textContent=name==='option'?'Option':'Resource';
+    const select=document.createElement('select');select.name=name;
+    const empty=document.createElement('option');empty.value='';empty.textContent=name==='option'?'Choose an option':'Any available resource';select.append(empty);
+    for(const choice of choices){const option=document.createElement('option');option.value=choice.id;option.textContent=choice.name;select.append(option);}
+    label.append(select);group.append(label);fields.set(name,select);
+  }
+  container.append(group);
+  return {value:():{option?:string;resource?:string}=>Object.fromEntries([...fields].filter(([,select])=>select.value).map(([name,select])=>[name,select.value])),dispose:()=>group.remove()};
+}

package/bin/homie-studio.mjs

@@ -911,6 +911,7 @@ async function main() {
   }
   // The starter library and the optimiser work anywhere; the rest of style and assets inside a studio (lib/art-cli.mjs).
   if (cmd === 'assets' && ['find', 'optimise', 'optimize'].includes(sub)) return assetsCommand(null, sub, positional, flags, { log });
+  if(cmd==='fork')return (await import('../lib/fork.mjs')).forkStudio(positional[1],positional[2],{name:flags.get('name'),slug:flags.get('slug'),ids:flags.get('ids')?JSON.parse(flags.get('ids')):{}});
   const root = requireStudio();
   // Keep guidance visible to AI callers using --json as well as human output.
   if (['build', 'check', 'upgrade'].includes(cmd)) {
@@ -1111,18 +1112,23 @@ async function main() {
     if (sub === 'init') return shopInit(root, { supporter: flags.has('supporter'), giving: flags.has('giving'), currency: flags.get('currency') ?? null, price: flags.get('price') ?? 500, managed: flags.has('managed') });
     if(sub==='listen')return (await import('../lib/shop-listen.mjs')).shopListen(root,{profile:flags.get('profile'),port:flags.get('port')??8787,log});
     if (sub === 'check') return shopCheck(root);
+    if(sub==='observe') {
+      const {recordShopObservations}=await import('../lib/shop-mcp.mjs');
+      const input=JSON.parse(readFileSync(0,'utf8'));
+      return recordShopObservations(root,Array.isArray(input)?{observations:input}:input);
+    }
     if (sub === 'plan' || sub === 'verify') {
       const {shopMcpPlan,saveMcpVerification}=await import('../lib/shop-mcp.mjs');
       const file=flags.get('have');
       const input=file?JSON.parse(readFileSync(file==='-'?0:file,'utf8')):{};
       return (sub==='verify'?saveMcpVerification:shopMcpPlan)(root,input);
     }
-    if (sub === 'webhook') return shopConnect(root,{webhookOnly:true,live:flags.has('live'),renew:flags.has('renew'),profile:flags.get('profile'),log:line=>process.stderr.write(`${line}\n`)});
+    if (sub === 'webhook') return shopConnect(root,{onEvent:event=>process.stderr.write('HOMIE_EVENT '+JSON.stringify(event)+'\n'),webhookOnly:true,live:flags.has('live'),renew:flags.has('renew'),profile:flags.get('profile'),log:line=>process.stderr.write(`${line}\n`)});
     if (sub === 'connect' && flags.has('local')) {
       if(flags.has('live'))throw new Error('Local checkout requires test mode');
       return (await import('../lib/shop-local.mjs')).shopConnectLocal(root,{url:flags.get('url'),profile:flags.get('profile')});
     }
-    if (sub === 'connect') return shopConnect(root, { managed: flags.has('managed') ? true : null, live: flags.has('live'), manual: flags.has('manual'), fromClipboard: flags.has('from-clipboard'), renew: flags.has('renew'), log: (line) => process.stderr.write(`${line}\n`) });
+    if (sub === 'connect') return shopConnect(root, { onEvent:event=>process.stderr.write('HOMIE_EVENT '+JSON.stringify(event)+'\n'), managed: flags.has('managed') ? true : null, live: flags.has('live'), manual: flags.has('manual'), fromClipboard: flags.has('from-clipboard'), renew: flags.has('renew'), log: (line) => process.stderr.write(`${line}\n`) });
     if (sub === 'disconnect') return shopDisconnect(root);
     if (sub === 'catalog') {
       const from = flags.get('have');

package/docs/shop-migration.md

@@ -0,0 +1,9 @@
+# Keyless shop setup and migration
+
+Use `stripe_shop_plan` with Stripe's official plugin to perform the returned operations. Supply each new response as `{method,path,params,body}` in `observations`; earlier responses are saved automatically. Product and price discovery uses metadata searches. Payment Links use Stripe's paginated list API with expanded line items, then match studio, origin and revision metadata locally (Stripe has no Payment Link search endpoint). No creation is planned before discovery completes.
+
+For CLI workflows, pipe an array of these responses, or `{observations:[...]}`, into `homie-studio shop observe`. It saves the responses and returns the next dependency batch. `shop plan` resumes without `--have`. Never include credentials or webhook creation responses.
+
+Old verifications without a billing portal ID discover and reuse the existing portal before planning creation. Old verifications without an account ID adopt the official CLI's signed-in account only after reading and matching their saved Payment Links. A known different account is still refused. Verification freshness and configuration checks still apply.
+
+`stripe_webhook` returns a job. Read `studio_job`: while browser approval is pending, `events` contains `{type:"stripe.pairing",code,url}`. Show that code and URL to the owner. A saved valid Stripe login emits no pairing event and needs no new approval. Secrets never enter the event.

package/docs/toolkit-batch.md

@@ -0,0 +1,49 @@
+# App references, private frames and checks
+
+`shop.book(item, {collection, slot}, quantity, {reference})` accepts your app's booking reference. `studio_checkout` over MCP accepts `reference` alongside `lines`, `game` and optional `booking: {collection,slot}`. The saved order and `order.paid` event retain this value. It identifies your record; it is not proof of payment. Confirm the signed payment before fulfilling it.
+
+HTTP record creation puts the ID in `/<app>/api/app/records/<collection>/<id>` and fields in `{data:{...}}`. The `app_records` MCP tool and `ctx.records` put `id` at the top level of their arguments, alongside `app` and `collection`. A missing HTTP ID now returns the exact URL format. IDs use 1–64 letters, digits, underscores or hyphens.
+
+Private apps authorize the owner page first, then give its sandboxed frame a signed asset path valid for five minutes. Relative modules and chunks retain that path, without the owner's cookie. Asset capabilities cannot read records, call tools or authorize room sockets. Reload the owner page for a new path after expiry. Responses are private and uncached; unsigned private modules and records stay closed.
+
+`check` gives the baseline action and every Codex need separate browser contexts and fresh rooms. Isolated record namespaces follow those rooms. `check --url https://studio.example` uses the saved owner MCP connection to mint 15-minute app-role sessions. These sessions cannot grant global owner access or access another app, and their record writes stay in the test namespace. Test slots never emit production payment-link work. With `--no-isolate`, records are explicitly shared. A need's `role` applies to its primary surface (`surface`, the first action’s surface, or the phone/matching role in observation-only needs); other surfaces retain their declared roles. Use an individual step's `role` for an explicit override. `--shots <directory>` captures passing and failing UI needs.
+
+`dev` ignores changes to the authoring `CODEX.md` when detecting runtime edits, so saving needs evidence does not interrupt an active check. It reports when its requested port is busy and gives the actual URL. `check` without `--url` follows the running studio's registered dev URL. MCP connections retry a brief Cloudflare 1042 startup response up to three times and report each retry. Other errors return normally. Records-only apps do not inherit game-player cost estimates.
+
+For turn-based games, a `player:true` entity can omit `body` and movement code. Declare its hidden role with `f.text(32, {visibility:'owner'})`; use `visibility:'server'` for secrets no client should receive. Keep hidden roles out of public shared fields and effects. The server projects snapshots for the receiving seat, including spectators. Use `room.start` and `room.on` with `world.after(ticks, event, data)` for phase deadlines; timers belong to the room and require no physics body. The normal server host remains required for secrecy.
+
+Set one studio flag, `"concept":true`, and build for a concept preview. The site returns no directory manifest, disallows indexing and displays a fixed TEST / CONCEPT banner on HTML surfaces. Remove the flag and rebuild to leave concept mode. This labels a test site; it does not sandbox payment credentials or data.
+
+A public records-only app can opt into a direct install surface:
+
+```json
+{"web":{"manifest":{"name":"Guest app","short_name":"Guest","icons":[]},"serviceWorker":"sw.js"}}
+```
+
+Place the service worker in the app's public files. `/app-id/install` serves the compiled app directly, with a manifest and optional service-worker registration. Records and app-tool helpers use the direct bridge. Add suitable icons and implement the offline behaviour in your service worker. The installed surface runs as same-origin studio code; signed-in/private app shells retain their sandbox. The manifest scope is the app's address, and installation support depends on the browser.
+
+Fork editable example source in one command:
+
+```sh
+homie-studio fork /path/to/example /path/to/new-place --name 'New Place' --slug new-place
+```
+
+The command renames the studio, app/game IDs, record/slot IDs declared in JSON or JavaScript/TypeScript objects and matching source references. Use `--ids '{"old-id":"new-id"}'` for explicit overrides or long names. It excludes local state, credentials, dependencies, generated output and deployment identities, then generates a fresh Worker configuration. It refuses an existing destination and leaves the example unchanged. Install dependencies and run the returned check before publishing.
+
+Supporter and deposit Payment Links have quantity fixed at one. For a variable deposit, declare `kind:"deposit", price:"choose"`, then call `shop.buy(id, 1, amount, {reference})`. Amounts use currency minor units. The link prefills the saved amount and carries the order ID, which maps back to the app reference. A signed payment with a different subtotal does not fulfill the order. Compute and validate the amount in the app's trusted booking operation and compare the payment event to its saved booking amount before confirmation; a buyer-supplied reference alone grants no authority.
+
+Declare a function or AI event feed for `booking.slots_need_payment_links`. For example, in `studio.json`:
+
+```json
+{"mcp":{"events":{"slot-links":{"event":"booking.slots_need_payment_links","audience":"owner"}}}}
+```
+
+ Creating or updating a booking's slot record without a matching capacity link inserts the event in the same database transaction. Its `slots` array contains `app`, booking `collection`, slot collection `slots`, `slot`, `item` and `capacity`. The owner's AI reads the full published slot inventory, calls `stripe_shop_plan`, performs its operations through Stripe's official plugin, records responses, verifies, then builds the updated public configuration. Never create webhooks through model-visible plugin calls. Unsubscribed events are not retained. Free items require no payment link.
+
+Resource-aware bookings declare `booking: {slots:"slots", item:"ticket", resources:"resources"}`. Resource records hold `capacity`, optional `skills` arrays and `attributes` objects. Slots hold ISO `start`/`end`, candidate `resources`, and optional required `skills`/`attributes`. `ctx.bookings.hold` accepts `resource` (preferred resource), `option` and `addons`. An option can contain `components`, each naming candidate `resources`, optional `skills`/`attributes`, `units`, `offsetMinutes` and `durationMinutes`. Every component consumes capacity; overlapping allocations are checked atomically by the database. Release frees them. Editing an allocated resource or moving an allocated booking is refused: release and allocate the replacement deliberately. Resource checkout requires the allocated hold ID, so a raw checkout cannot bypass capacity. Paid exclusive holds still require session checkout; keyless inventory cannot share an exclusive unpaid hold.
+
+Set the app's IANA `timeZone`, then use `ctx.bookings.calendar({app,startDate,endDate,time,days,capacity})` for an inclusive season of multi-day slots. `durationMinutes` handles shorter slots; `weekdays` uses Sunday=0 through Saturday=6. Persist the returned records through `ctx.records`. DST gaps and ambiguous wall times are refused; supply an explicit offset timestamp for such exceptional slots.
+
+The public `studio_book` MCP tool uses the same hold operation. It accepts `time` as `slot`, `preferredResource`/`preferred_resource` as `resource`, and `addons`, `addOns` or `add-ons` as either an array of IDs or an object of quantities. Conflicting aliases are refused. Supply a stable request `id`, `expiresAt` within 15 minutes (or the booking declaration’s `holdMinutes`, up to one day), and a private random hex `token` for anonymous bookings. Keep that token private for later management.
+
+The phone helper `createBookingChoices({container,options,resources})` from `@homie-rocks/studio/apps` renders accessible native selects. Submit its `value()` (`{option,resource}`) to the app's trusted booking tool. The phone and customer AI therefore use the same option/resource IDs and capacity rules. Call `dispose()` when the surface closes.

package/functions/FUNCTIONS.md

@@ -26,7 +26,21 @@ export default defineFunction<{ order: string }>({
 ```
 
 Build discovers and type-checks `functions/*.ts`. Handlers have the studio tool
-context and run with the studio's authority. They can change records, send a
+context and run with the studio's authority. Handlers can call `ctx.records` (or
+`context.records` when the parameter is named `context`) to read, create, update
+and delete declared app records. Supply `app`, `collection`, and `id` at the top
+level; put the record fields inside `data`. Updates and deletes also require
+the current `version`. These calls use the same validation and permissions as
+the app record API.
+
+```ts
+await context.records({
+  app: 'calendar', collection: 'notes', id: event.id,
+  operation: 'create', data: { message: 'Ready' },
+});
+```
+
+Handlers They can change records, send a
 room event through declared capabilities, call an external service, or implement
 another business workflow. Treat event data as data, not instructions.
 

package/guides/app/PLACES.md

@@ -121,3 +121,26 @@ Document the exact commands and results; an empty assertion list is not proof.
   and verify a clean checkout can build it. Declare only packages actually used.
 - No invented reviews, impact figures or verification. Label estimates and test
   payments honestly; remove stale workaround claims when upgrading.
+
+## Booking toolkit and customer-AI arguments
+
+Use declared booking slots and resources instead of duplicating capacity logic.
+`studio_book` accepts `slot` or `time`, `resource`, `preferredResource` or
+`preferred_resource`, and `addons`, `addOns` or `add-ons` as an array of IDs or an
+object of quantities. Contradictory aliases are refused. Use the same option and
+resource IDs in `createBookingChoices` on the phone. A booking may allocate
+multiple resource components, with skills, attributes and capacity checked by
+the server. Use the app's IANA `timeZone` and `ctx.bookings.calendar` for dated or
+multi-day seasons. Public holds need a stable ID, bounded expiry and a private
+management token for anonymous customers.
+
+Pass the app's booking reference to `shop.book` or MCP `studio_checkout`. For
+variable deposits use an amount-based link and validate the paid amount against
+the saved booking. Declare `booking.slots_need_payment_links` so the owner's AI
+can prepare links for newly rolled dates through Stripe's official plugin.
+Use `shop observe` to record plugin responses, then verify and build.
+
+The toolkit's `docs/toolkit-batch.md` documents resource declarations, install
+surfaces, private frames, concept previews, example forks and isolated live-site
+checks. Record IDs belong at the top level of `ctx.records`/`app_records`
+arguments, alongside `app` and `collection`.

package/lib/app-needs.mjs

@@ -22,15 +22,23 @@ export function readAppNeeds(root, id) {
   return { needs, hash: createHash('sha256').update(source).digest('hex') };
 }
 
+/** An action names its actor; an observation-only need prefers its phone or a matching role. */
+export function primaryNeedSurface(need,roleFor=()=>undefined) {
+ const action=needSteps(need.steps).find(s=>s.surface)?.surface;
+ const assertions=(need.assertions??[]).filter(s=>s.surface);
+ return need.surface??action??assertions.find(s=>['phone','phone-two'].includes(s.surface))?.surface??assertions.find(s=>!need.role||roleFor(s.surface)===need.role)?.surface;
+}
+
 /** 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 () => {}, root, headless, restart }) {
   const results = [];
   const appBarrier=ready;
   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; };
+  let activeRole, primarySurface;
+  const surface = (name, explicitRole) => { const role=explicitRole??(name===primarySurface?activeRole:undefined); const s=surfaces.find(s=>s.name===name&&(!role||s.role===role)); if(!s)throw new Error(role?`${name} requires role ${role}`:`unknown surface ${name}`);return s; };
   for (const need of plan.needs) {
     activeRole = need.role;
+    primarySurface = primaryNeedSurface(need,name=>surfaces.find(s=>s.name===name)?.role);
     const names = [...new Set([...needSteps(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); };
@@ -39,8 +47,8 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
     try {
       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 item of [...needSteps(need.steps),...need.assertions])if(item.surface&&!popupNames.has(item.surface))surface(item.surface,item.role);
+      for(const target of new Set(need.assertions.filter(a=>a.effect).map(a=>surface(a.surface,a.role))))await target.frame.evaluate(()=>{window.__homieNeedsEffects=[];});
       const perform = async rawStep => {
         const step=resolveNeedResults(rawStep,saved);
         if(step.concurrent){
@@ -57,7 +65,7 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
           if (step.save) { if(saved.has(step.save))throw new Error(`duplicate saved result ${step.save}`); saved.set(step.save,value); }
           return;
         }
-        const target=surface(step.surface);
+        const target=surface(step.surface,step.role);
         if(!step.reload)await ready(target);
         const { page } = target;
         if(step.capabilities){
@@ -68,7 +76,7 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
         if(Object.hasOwn(step,'clock')){await page.evaluate(value=>window.homieApp.setTestClock(value),step.clock);return;}
 
         waiting = `${step.surface}: ${step.reload ? 'reload and arrival readiness' : step.selector}`;
-        if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await ready(surface(step.surface)); return; }
+        if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await ready(surface(step.surface,step.role)); return; }
         const act = fn => actInApp(target,step.selector,fn,{ready});
         if (step.click && step.popup) {
           let listener,timer;
@@ -118,7 +126,7 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
           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);
+        const target=surface(assertion.surface,assertion.role);
         await ready(target);
         await waitInApp(target,waiting,async frame=>{
         if (assertion.effect) {
@@ -134,9 +142,10 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
       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 { mkdirSync(shots,{recursive:true}); await ready(surface(name)); await surface(name).page.screenshot({ path: file, type: 'jpeg', quality: 85 }); result.captures.push(file); }
+    if (shots) for (const target of surfaces.filter(s=>names.includes(s.name))) {
+      const name=target.name, suffix=surfaces.filter(s=>s.name===name).length>1?'-'+target.role:'';
+      const file = join(shots, `${need.id}-${name}${suffix}.jpg`);
+      try { mkdirSync(shots,{recursive:true}); await ready(target); await target.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 });

package/lib/app-ready.mjs

@@ -9,7 +9,7 @@ export async function appReady(surface, {timeout=60000}={}) {
         const cover=document.querySelector('[data-arrive]');
         return window.__shell?.link?.state==='online' && window.__shell?.arrival?.phase==='done' && (!cover || (getComputedStyle(cover).opacity==='0' && getComputedStyle(cover).visibility==='hidden'));
       },{timeout:Math.max(1,end-Date.now())});
-      const frame=surface.page.frames().find(f=>/\/__game\//.test(f.url()));
+      const frame=surface.page.frames().find(f=>/\/(?:__game|__assets)\//.test(f.url()));
       if(!frame)throw new Error('app frame missing');
       await frame.evaluate(()=>new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve))));
       surface.frame=frame;return;

package/lib/build.mjs

@@ -635,7 +635,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
     const bundle = bundleOf(dir);
     builds[g.id] = { hash: gameDigest(dir), ...(bundle ? { bundle } : {}) };
     return {
-      ...(g.kind === 'app' ? { kind: 'app', roles: g.roles, surfaces: g.surfaces, words: g.words, records: g.records, parts: g.parts ?? [], check: g.check } : {}),
+      ...(g.kind === 'app' ? { kind: 'app', ...(g.web?{web:g.web}:{}), ...(g.timeZone?{timeZone:g.timeZone}:{}), roles: g.roles, surfaces: g.surfaces, words: g.words, records: g.records, parts: g.parts ?? [], check: g.check } : {}),
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
       ...(ui ? { ui } : {}),
       // A rules game's round is its rules' own (`room.rounds`), and its movement a per-kind choice there: game.json's
@@ -698,6 +698,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   const lounge = loungeConfig(studio, rows, { audience: audienceOf(studio) });
   const catalogue = {
     studio: {
+      ...(studio.concept===true?{concept:true}:{}),
       name: studio.name, slug: studio.slug, version: STUDIO_VERSION, ...(studio.kind ? { kind: studio.kind } : {}),
       ...(typeof studio.tagline === 'string' && studio.tagline.trim() ? { tagline: studio.tagline.trim().slice(0, 140) } : {}),
       theme,
@@ -716,7 +717,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
       ...(studio.rooms?.share === false ? { rooms: { share: false } } : {}),
       // The directory the live site claims itself in (0.10.0); studio.json `homie.directory: false` keeps it out.
       // HOMIE_DIRECTORY (a build variable) points one build at another directory, such as a staging one.
-      directory: directoryUrl(process.env.HOMIE_DIRECTORY ?? studio.homie?.directory),
+      directory: studio.concept===true?false:directoryUrl(process.env.HOMIE_DIRECTORY ?? studio.homie?.directory),
       canonical: domainOrigin(studio.cloudflare?.domain) ?? domainOrigin(studio.cloudflare?.url),
       // A copy of the public template that nobody has named yet shows the name typed in Cloudflare's form.
       ...(studio.template === true ? { template: true } : {}),

package/lib/check.mjs

@@ -2,7 +2,7 @@ import {needsHeadless} from './needs-headless.mjs';
 import {randomBytes} from 'node:crypto';
 import {actInApp,appReady,observeEffects,forceWebglFailure,waitInApp,answerDialogs} from './app-ready.mjs';
 import {localCredential,localCookie} from './local-test.mjs';
-import { readAppNeeds, proveAppNeeds, saveAppNeeds, needSteps } from './app-needs.mjs';
+import { readAppNeeds, proveAppNeeds, saveAppNeeds, needSteps, primaryNeedSurface } from './app-needs.mjs';
 /**
  * `homie-studio check [<game>] [--url <site> | --live]` — the promise, measured (where it runs and on which games
  * when nobody says: lib/check-site.mjs; never the live site unless asked): two fresh
@@ -359,7 +359,7 @@ export async function checkApp({ webglFailure = false, isolate = true, root = nu
   let plan;
   try { plan = readAppNeeds(root, game); } catch (error) { return { ok: false, command: 'check', kind: 'app', why: error.message }; }
   const secret=localCredential(root,url);
-  if(isolate && !secret)return {ok:false,command:'check',why:'Fresh isolated records are on by default. Run dev in this studio and check its localhost URL, or explicitly use --no-isolate.'};
+
   log(isolate ? 'Fresh isolated records: on (this check only).' : 'Fresh isolated records: off; using existing records.');
   const dialogs=[];
   const proof = meta.check??{};
@@ -368,19 +368,34 @@ export async function checkApp({ webglFailure = false, isolate = true, root = nu
   if(webglFailure&&!baseline&&!plan?.needs.some(n=>[...needSteps(n.steps),...(n.assertions??[])].some(i=>i.surface)))return {ok:false,command:'check',why:'--webgl-failure requires UI steps or assertions'};
   const captureWarnings=[];
   const profile = mkdtempSync(join(tmpdir(), 'homie-app-check-'));
-  let browser;
+  let browser, ownerClient;
   const surfaces = [];
-  const room = `check-${randomBytes(10).toString('hex')}`;
+  let room = `check-${randomBytes(10).toString('hex')}`;
   try {
+    const remoteCookies=new Map();
+    const sessionFor=async role=>{
+      if(secret)return {name:'homie_test',value:localCookie(secret,{app:game,role,scope:isolate?room:null})};
+      if(!isolate)return null;
+      ownerClient??=await (await import('./tools-cli.mjs')).connectToolClient(root,url,{log});
+      const key=room+':'+role;
+      if(!remoteCookies.has(key)) {
+        const result=await ownerClient.callTool({name:'studio_check_session',arguments:{app:game,role,scope:room}});
+        if(result.isError)throw new Error(result.content?.[0]?.text??'Cannot create isolated check session');
+        const parsed=result.structuredContent??JSON.parse(result.content.find(c=>c.type==='text').text),data=parsed.data??parsed;
+        if(!data.token)throw new Error('Studio did not return its test-session token');
+        remoteCookies.set(key,{name:'homie_check',value:data.token});
+      }
+      return remoteCookies.get(key);
+    };
     if(baseline || plan?.needs.some(n=>[...needSteps(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}`);
       role ??= meta.surfaces?.[name==='phone-two'?'phone':name] ?? (name==='staff'?'staff':undefined);
       if(!meta.roles?.[role])throw new Error(`${name}: unknown role ${role}`);
-      if(meta.roles[role].signIn && !secret)throw new Error(`${name}: local staff proof needs dev's test session`);
+      if(meta.roles[role].signIn && !secret && !isolate)throw new Error(`${name}: local staff proof needs dev's test session`);
       const context=await browser.createBrowserContext();
-      if(secret)await context.setCookie({name:'homie_test',value:localCookie(secret,{app:game,role,scope:isolate?room:null}),url,httpOnly:true,sameSite:'Strict'});
+      const cookie=await sessionFor(role);if(cookie)await context.setCookie({...cookie,url,httpOnly:true,sameSite:'Strict',secure:new URL(url).protocol==='https:'});
       const page=await context.newPage();
       answerDialogs(page,name,dialogs,report);
       await page.evaluateOnNewDocument(observeEffects);
@@ -417,16 +432,25 @@ export async function checkApp({ webglFailure = false, isolate = true, root = nu
     }
     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 [...needSteps(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?[]:null;
+    for(const need of plan?.needs??[]) {
+      // Baseline and every need get separate contexts, rooms and record namespaces.
+      for(const context of new Set(surfaces.map(surface=>surface.page.browserContext())))await context.close();
+      surfaces.length=0;
+      room=`check-${randomBytes(10).toString('hex')}`;
+      const declaredRole=name=>meta.surfaces?.[name==='phone-two'?'phone':name]??(name==='staff'?'staff':undefined);
+      const primary=primaryNeedSurface(need,declaredRole);
+      log(`Need ${need.id}: fresh room ${room}; records ${isolate?'isolated':'shared (--no-isolate)'}.`);
+      for(const item of [...needSteps(need.steps),...(need.assertions??[])]) {
+        if(!item.surface || (need.steps??[]).some(s=>s.popup===item.surface))continue;
+        const role=item.role??(item.surface===primary?need.role:undefined)??declaredRole(item.surface);
+        if(!surfaces.some(s=>s.name===item.surface&&s.role===role))await openSurface(item.surface,role);
+      }
+      needs.push(...await proveAppNeeds({plan:{...plan,needs:[need]},surfaces,shots,report,ready:appReady,root,restart:()=>import('./dev-restart.mjs').then(m=>m.requestDevRestart(root,url)),headless:needsHeadless({url,secret,app:game,meta,scope:isolate?room:null,sessionFor})}));
     }
-    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report, ready:appReady, root, restart:()=>import('./dev-restart.mjs').then(m=>m.requestDevRestart(root,url)), 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', webglFailure, 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 }); }
+  finally { await ownerClient?.close().catch(()=>{}); await browser?.close().catch(() => {}); rmSync(profile, { recursive: true, force: true }); }
 }

package/lib/dev.mjs

@@ -300,6 +300,7 @@ export function rulesStamp(g) {
   const walk=dir=>{for(const entry of readdirSync(dir,{withFileTypes:true})) {
     if(['node_modules','.git','.wrangler','.studio','.port','.cache','.parcel-cache','.vite','.DS_Store','coverage','dist','codex'].includes(entry.name))continue;
     const file=join(dir,entry.name);
+    if(file===join(g.dir,'CODEX.md'))continue; // check writes authoring evidence, never runtime inputs
     if(entry.isDirectory())walk(file);
     else if(entry.isFile()){const st=statSync(file);rows.push(`${file}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`);}
   }};

package/lib/fork.mjs

@@ -0,0 +1,47 @@
+import {existsSync,mkdirSync,readdirSync,readFileSync,writeFileSync,copyFileSync,rmSync} from 'node:fs';
+import {resolve,join,dirname,extname,relative} from 'node:path';
+import {refreshWorkerConfig} from './worker-config.mjs';
+/** Copy editable source, never account state, installed code or a deployment. */
+export async function forkStudio(source,target,{name,slug,ids={}}={}) {
+ source=resolve(source);target=resolve(target);
+ if(existsSync(target))throw new Error('Fork target already exists');
+ if(!/^[a-z][a-z0-9-]{0,39}$/.test(slug??'')||typeof name!=='string'||!name.trim())throw new Error('Supply name and a lowercase slug (1–40 letters, digits and hyphens)');
+ if(!relative(source,target).startsWith('..'))throw new Error('Fork target must be outside the example');
+ const studio=JSON.parse(readFileSync(join(source,'studio.json'),'utf8'));
+ const excluded=new Set(['node_modules','.git','.studio','dist','.wrangler','.DS_Store','wrangler.json','wrangler.jsonc','wrangler.toml','wrangler.custom.json','package-lock.json']);
+ const files=[];
+ function walk(dir){for(const entry of readdirSync(join(source,dir),{withFileTypes:true})) {
+  if(excluded.has(entry.name)||entry.name.startsWith('.')&&entry.name!=='.gitignore'||entry.name.startsWith('.dev.vars')||entry.name.endsWith('.sqlite')||entry.name.endsWith('.db')||entry.name.endsWith('.pem')||entry.name.endsWith('.key')||entry.isSymbolicLink())continue;
+  const path=join(dir,entry.name);if(entry.isDirectory())walk(path);else if(entry.isFile())files.push(path);
+ }}walk('');
+ const mapping=new Map([[studio.slug,slug],[studio.name,name]]);
+ const collect=value=>{if(!value||typeof value!=='object')return;if(typeof value.id==='string'&&/^[a-z][a-z0-9-]*$/.test(value.id))mapping.set(value.id,ids[value.id]??`${slug}-${value.id}`);for(const child of Object.values(value))collect(child);};
+ for(const file of files.filter(p=>p.endsWith('.json')&&!['studio.json','package.json'].includes(p)))try{collect(JSON.parse(readFileSync(join(source,file),'utf8')));}catch{}
+ const ts=(await import('typescript')).default;
+ for(const file of files.filter(p=>/\.(?:[cm]?js|tsx?)$/.test(p))) {
+  const tree=ts.createSourceFile(file,readFileSync(join(source,file),'utf8'),ts.ScriptTarget.Latest,true);
+  const visit=node=>{
+   if(ts.isPropertyAssignment(node)&&(ts.isIdentifier(node.name)||ts.isStringLiteral(node.name))&&node.name.text==='id'&&ts.isStringLiteral(node.initializer))collect({id:node.initializer.text});
+   ts.forEachChild(node,visit);
+  };visit(tree);
+ }
+ for(const [old,next] of Object.entries(ids))mapping.set(old,next);
+ for(const [old,next] of mapping)if(typeof next!=='string'||!next.length)throw new Error(`Invalid replacement for ${old}`);
+ for(const [old,next] of mapping)if(old!==studio.name&&(!/^[a-z][a-z0-9-]{0,39}$/.test(next)))throw new Error(`Renamed id ${next} exceeds 40 characters; supply ids.${old}`);
+ const escape=s=>s.replace(/[.*+?^${}()|[\]\\]/g,'\\$&');
+ const pattern=new RegExp(`(?<![A-Za-z0-9_-])(?:${[...mapping.keys()].filter(Boolean).sort((a,b)=>b.length-a.length).map(escape).join('|')})(?![A-Za-z0-9_-])`,'g');
+ const rewrite=s=>s.replace(pattern,value=>mapping.get(value));
+ mkdirSync(target);
+ try {
+  for(const file of files) {
+   const to=join(target,...file.split('/').map(part=>mapping.get(part)??part));mkdirSync(dirname(to),{recursive:true});
+   if(['.json','.ts','.js','.mjs','.html','.css','.md','.sql','.txt','.svg','.yaml','.yml'].includes(extname(file)))writeFileSync(to,rewrite(readFileSync(join(source,file),'utf8')));else copyFileSync(join(source,file),to);
+  }
+  const fresh=JSON.parse(readFileSync(join(target,'studio.json'),'utf8'));fresh.name=name;fresh.slug=slug;delete fresh.github;delete fresh.template;
+  fresh.cloudflare={worker:slug,d1:slug+'-db',created:[]};fresh.homie={...fresh.homie,directory:false};
+  writeFileSync(join(target,'studio.json'),JSON.stringify(fresh,null,2)+'\n');
+  const pkg=JSON.parse(readFileSync(join(target,'package.json'),'utf8'));pkg.name=slug;delete pkg.repository;writeFileSync(join(target,'package.json'),JSON.stringify(pkg,null,2)+'\n');
+  refreshWorkerConfig(target);
+  return {ok:true,command:'fork',root:target,renamed:Object.fromEntries(mapping),next:['npm install','homie-studio check']};
+ }catch(error){rmSync(target,{recursive:true,force:true});throw error;}
+}

package/lib/jobs.mjs

@@ -158,6 +158,7 @@ export function jobView(job, { lines = 12 } = {}) {
     startedAt: job.startedAt, endedAt: job.endedAt,
     seconds: Math.round(((job.endedAt ? Date.parse(job.endedAt) : Date.now()) - Date.parse(job.startedAt)) / 1000),
     tail: text.slice(-lines), log: job.log, result: job.result,
+    events: job.err.split('\n').filter(line=>line.startsWith('HOMIE_EVENT ')).flatMap(line=>{try{return [JSON.parse(line.slice(12))];}catch{return [];}}),
   };
 }
 

package/lib/mcp-tools.mjs

@@ -1195,7 +1195,7 @@ export function toolDefs(ctx, avail = {}) {
       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)});
+        return ok('Follow studio_job. Its events contain any required Stripe pairing; a saved login needs no new approval.',{kind:'job',...jobView(job)});
       },
     },
     {

package/lib/needs-headless.mjs

@@ -1,13 +1,14 @@
 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}) {
+export function needsHeadless({url,secret,app,meta,scope,sessionFor}) {
   return async (item,role) => {
-    if(!secret)throw new Error('Headless role proof requires homie-studio dev in this studio and its localhost URL');
+    if(!secret&&!sessionFor)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})}`}}});
+    const cookie=sessionFor?await sessionFor(role):{name:'homie_test',value:localCookie(secret,{app,role,scope})};
+    const transport=new StreamableHTTPClientTransport(new URL('/mcp',url),{requestInit:{headers:{...(secret?{authorization:`Bearer ${secret}`} : {}),...(cookie?{cookie:`${cookie.name}=${cookie.value}`}:{})}}});
     try {
       await client.connect(transport);
       let call=item.mcp;

package/lib/scaffold.mjs

@@ -1,3 +1,4 @@
+import {BOOKING_RESOURCES_MIGRATION,BOOKING_RESOURCES_MIGRATION_FILE} from '../worker/booking-resources.mjs';
 import {BOOKING_HOLDS_MIGRATION,BOOKING_HOLDS_MIGRATION_FILE} from '../worker/booking-holds.mjs';
 import {BUSINESS_EVENTS_MIGRATION,BUSINESS_EVENTS_MIGRATION_FILE} from '../worker/business-events.mjs';
 import {APP_LIVE_MIGRATION,APP_LIVE_MIGRATION_FILE} from '../worker/app-streams.mjs';
@@ -827,6 +828,7 @@ export { default, Table, Lobby, Gate, Concentrator } from '@homie-rocks/studio/w
     [`site/migrations/${SHOP_REMOVE_REFERRALS_FILE}`]: SHOP_REMOVE_REFERRALS,
     [`site/migrations/${APPS_MIGRATION_FILE}`]: APPS_MIGRATION,
     [`site/migrations/${BUSINESS_EVENTS_MIGRATION_FILE}`]: BUSINESS_EVENTS_MIGRATION,
+    [`site/migrations/${BOOKING_RESOURCES_MIGRATION_FILE}`]: BOOKING_RESOURCES_MIGRATION,
     [`site/migrations/${BOOKING_HOLDS_MIGRATION_FILE}`]: BOOKING_HOLDS_MIGRATION,
     [`site/migrations/${APP_LIVE_MIGRATION_FILE}`]: APP_LIVE_MIGRATION,
     [`site/migrations/${TOOL_DATABASE_MIGRATION_FILE}`]: TOOL_DATABASE_MIGRATION,
@@ -1069,8 +1071,13 @@ function ensureBookingHolds(root) {
   if(existsSync(file))return null;
   mkdirSync(dirname(file),{recursive:true});writeFileSync(file,BOOKING_HOLDS_MIGRATION);return `site/migrations/${BOOKING_HOLDS_MIGRATION_FILE}`;
 }
+function ensureBookingResources(root) {
+  const file=join(root,'site','migrations',BOOKING_RESOURCES_MIGRATION_FILE);
+  if(existsSync(file))return null;
+  mkdirSync(dirname(file),{recursive:true});writeFileSync(file,BOOKING_RESOURCES_MIGRATION);return `site/migrations/${BOOKING_RESOURCES_MIGRATION_FILE}`;
+}
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root), ensureFunctionReference(root), ensureShopRemoveReferrals(root), ensureFunctionRuns(root), ensureToolDatabase(root), ensureBookings(root), ensureSubscriptions(root), ensureAppLive(root), ensureBusinessEvents(root), ensureBookingHolds(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(root), ensureChatMigration(root), ensureShopMigration(root), ensureLoungeMigration(root), ensureShopReservations(root), ensureShopLines(root), ensureAppsMigration(root), ensurePartsMigration(root), ensurePartsStateMigration(root), ensureMcpMigration(root), ensureFunctionsMigration(root), ensureFunctionCursors(root), ensureFunctionMeta(root), ensureFunctionReference(root), ensureShopRemoveReferrals(root), ensureFunctionRuns(root), ensureToolDatabase(root), ensureBookings(root), ensureSubscriptions(root), ensureAppLive(root), ensureBusinessEvents(root), ensureBookingHolds(root),ensureBookingResources(root)].filter(Boolean);
 }
 
 /** What a migration file the template added is for, in a few words (deploy and dev say it). */

package/lib/shop-links.mjs

@@ -85,7 +85,7 @@ export async function reconcilePaymentLinks({ api, shop, slug, site, mode, booki
     catalogPrices.set(item.id, price.id);
     if ((product.default_price?.id ?? product.default_price) !== price.id) await api('POST', `/v1/products/${id}`, { default_price: price.id });
     if (item.price === 0) return; // Free orders never leave the studio.
-    const params = { ...customText, line_items: [{ price: price.id, quantity: 1, ...(item.price !== 'choose' ? { adjustable_quantity: { enabled: shop.policy.repeatPurchases, minimum: 1, maximum: 999999 } } : {}) }],
+    const params = { ...customText, line_items: [{ price: price.id, quantity: 1, ...(item.price !== 'choose' && !['supporter','deposit'].includes(item.kind) ? { adjustable_quantity: { enabled: shop.policy.repeatPurchases, minimum: 1, maximum: 999999 } } : {}) }],
       after_completion: { type: 'redirect', redirect: { url: `${site}/shop/thanks?session_id={CHECKOUT_SESSION_ID}` } },
       ...(shop.till === 'stripe-managed' ? { managed_payments: { enabled: true } } : { automatic_tax: { enabled: shop.automaticTax } }),
       ...(item.interval ? { subscription_data: { metadata } } : { payment_intent_data: { metadata } }),
@@ -103,7 +103,7 @@ export async function reconcilePaymentLinks({ api, shop, slug, site, mode, booki
   // Stripe allows 20 Payment Link lines; invoice snapshots include only the first
   // 10. Split catalogues so keyless fulfillment needs no authenticated pagination.
   config.menus = [];
-  const menuItems = shop.items.filter(i => typeof i.price === 'number' && i.price > 0 && !i.interval);
+  const menuItems = shop.items.filter(i => !['supporter','deposit'].includes(i.kind) && typeof i.price === 'number' && i.price > 0 && !i.interval);
   const metadata = { homie: 'shop-links-v1', studio: slug, origin: site };
   const tasks=[];
   const groups=Map.groupBy(menuItems,i=>i.game??'');
@@ -198,7 +198,7 @@ export async function reconcilePaymentLinks({ api, shop, slug, site, mode, booki
     });
   }
   if(shop.items.some(i=>i.interval)) tasks.push(async()=>{
-    const portals=scoped?(knownPortal?[await api('GET',`/v1/billing_portal/configurations/${knownPortal}`,{})]:[]):await list('/v1/billing_portal/configurations');
+    const portals=knownPortal?[await api('GET',`/v1/billing_portal/configurations/${knownPortal}`,{})]: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};
     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})}`);

package/lib/shop-mcp.mjs

@@ -151,3 +151,9 @@ export function publicMcpSetup(root) {
   }
   return false;
 }
+
+/** Record a batch from the official plugin and return the next dependency batch. */
+export async function recordShopObservations(root, options = {}) {
+  if(!Array.isArray(options.observations) || !options.observations.length)throw new Error('Supply observations: [{method,path,params,body}] from Stripe’s official plugin.');
+  return shopMcpPlan(root, options);
+}