@homie-rocks/studio 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -17,6 +17,63 @@ 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.54.0] - 2026-10-15
+
+**Plugin 0.54.0**
+
+Studios answer faster, private apps stay private and usable, shops catch every payment, and the toolkit's CI costs a quarter of what it did.
+
+### Changed
+
+- Reduce pull-request CI work through shared studio fixtures, focused compatibility coverage, and nightly release checks.
+
+### Fixed
+
+- **Long-running app screens:** renew role handoffs on records, live and tools responses, reconnect idle live streams before expiry, and set handoffs on records-only pages. Revoked sessions, grants and rotated links still stop access. Remove the shared role secret from the phone address bar and subsequent API URLs.
+- **Tool catalogue:** load and notify once per Worker isolate and database binding, then refresh after studio mutations; static requests no longer repeatedly load tool modules and serialize schemas.
+- **Test assets:** require a valid test session for the same app, role and scope whenever a test-kind asset ticket is used.
+
+- **Request path:** remove referral cleanup and function registration from startup; clean retired referral keys in migration 0031. Reuse the deployment catalogue, reuse stable-binding metadata caches guarded by a trigger-maintained revision, avoid repeat tool-catalogue notifications, and dispatch background work after actual writes. Public static assets require no D1 reads; private app assets retain live authorization.
+- **Payment Links:** menu items support `maxQuantity` (default 99), slot links accept groups within published remaining capacity, and confirmation uses the paid seat quantity atomically. Payments that cannot be fulfilled remain visible as review orders with a durable staff event and customer notice. Full connect saves public JSON link assets, retaining replaced links until deployment.
+- **Stripe setup:** observe deterministic product IDs before creating missing search results; keep public checkout mode out of secret uploads and report Wrangler's redacted error text.
+- **Payment review:** single-item links enforce quantity caps at Stripe and fulfillment; old menu snapshots retain their published maximum. Signed payments with missing/unknown references or a currency mismatch remain visible for staff review without granting entitlements.
+- **Background delivery:** include nested background work, preserve D1 sessions and raw-write tracking, and refresh connected AIs’ tool lists on the first ordinary request after deployment.
+- **App checks:** needs without assertions are pending placeholders, rather than failed checks. They remain unproven: check reports not done with a pending label while preserving a nonfailing exit for placeholders.
+- **App navigation:** Big screen uses a five-minute HttpOnly same-origin role session instead of copying the shared access secret; app context URLs include only a validated public room ID.
+- **App subscriptions and privacy:** tool-data revisions and app wakes are scoped to the namespaces each app uses. Private asset capabilities support invite passes, signed-in sessions and tool/test identities, conceal session hashes with encryption plus HMAC, and recheck revocation and grants in one statement.
+- **Prediction:** synchronous `room.me` readers share a presentation even when CPU work crosses a simulation tick; the next microtask refreshes it. Fixes the 60 Hz browser prediction smoke flake without relaxing thresholds.
+
+### Upgrade notes
+
+- Apply migrations 0031–0033 with the normal studio deploy. Rebuild/deploy after full `shop connect` to publish its public link configuration. Review group availability and resync slot manifests after confirmations, moves or refunds; a Payment Link is not an exclusive unpaid hold.
+
+## [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');
@@ -1388,7 +1394,7 @@ try {
   // A shared progress feed sends its last word before the command exits.
   await flushProgress();
   if (result && result.command !== 'help') print(result);
-  if (result?.ok === false) process.exitCode = 1;
+  if (result?.ok === false) process.exitCode = result.command==='check' && result.pending===true && result.exitCode===0 ? 0 : 1;
   // Chrome's pipes can outlive browser.close(); a finished check must not hang its caller.
   if (['check', 'port check', 'look', 'perf', 'shoot', 'lab check'].includes(result?.command)) process.exit(process.exitCode ?? 0);
 } catch (error) {

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/guides/app/SKILL.md

@@ -101,9 +101,9 @@ The Codex's `needs` fenced block is a JSON array, one entry per need from the re
 ]
 ```
 
-Steps support `fill`, `select`, `click: true` and `reload: true`; surfaces are `wall`, `phone`, `phone-two`, `tablet`, `kiosk` and `staff` (a tablet viewport). Set a need’s `role` to the declared role to prove. Each assertion names its surface; only the named screens are required. Assertions use a visible selector with optional contained text, or an observed effect. An honestly unavailable capability remains in the block with no assertions and a plain explanation in the prose; check reports it not met. Do not delete, weaken or replace a need to get green. Static needs such as accurate prices may have no action steps. Use semantic attributes on real visible scene elements for testability, never hidden QA-only counters.
+Steps support `fill`, `select`, `click: true` and `reload: true`; surfaces are `wall`, `phone`, `phone-two`, `tablet`, `kiosk` and `staff` (a tablet viewport). Set a need’s `role` to the declared role to prove. Each assertion names its surface; only the named screens are required. Assertions use a visible selector with optional contained text, or an observed effect. An honestly unavailable capability remains in the block with no assertions and a plain explanation in the prose; check reports it pending (a placeholder, not a failure or proof). Do not delete, weaken or replace a need to get green. Static needs such as accurate prices may have no action steps. Use semantic attributes on real visible scene elements for testability, never hidden QA-only counters.
 
-Run build and the shared-action check, then the needs step runs on those real browsers. Save captures with `--shots .checks`. The result contains each statement, met/partly/not, the assertion result and available captures of named surfaces; `.studio/checks/<id>-needs.json` drives the Codex's Needs status. Redraw `codex <id>` after checking. Passing a selector assertion is evidence, not a visual judgement: read every capture and perform the full flows as owner and customer using the playtest skill. If the picture fails the words, it is not done even with green assertions.
+Run build and the shared-action check, then the needs step runs on those real browsers. Save captures with `--shots .checks`. The result contains each statement, met/partly/not/pending, the assertion result and available captures of named surfaces; `.studio/checks/<id>-needs.json` drives the Codex's Needs status. Redraw `codex <id>` after checking. Passing a selector assertion is evidence, not a visual judgement: read every capture and perform the full flows as owner and customer using the playtest skill. If the picture fails the words, it is not done even with green assertions.
 
 For staff flows, sign in through the existing local owner link and prove the transition in real Chrome. Keep evidence in the Codex alongside the automated flows. Confirm unauthorized writes are refused and records remain after all screens close. Never call an untested privileged path passed. Before final handover, show the need table with evidence and explicit remaining gaps. If the starter or a board of boxes is still visible, return to the scene design and build it.
 

package/guides/shop/SKILL.md

@@ -210,3 +210,9 @@ and Stripe CLI `listen --all-snapshot --forward-to http://localhost:8787/api/sho
 recipe is in the installed toolkit’s `apps/APPS.md`, “Real Stripe test checkout on
 this computer”. It uses root `.dev.vars`, needs no public HTTPS or Cloudflare, and
 keeps the existing approved Stripe CLI session. Do not write a stand-in checkout.
+
+### Batch setup and reconciliation
+
+Set each menu item's `maxQuantity` in `shop.json` when the studio has an order limit; the default is 99. Slot links support group quantities up to published remaining seats. Supply reviewed `confirmed` seat totals when resyncing: Stripe counts sessions, not people. The database confirms the entire paid group atomically. If a payment differs from the saved deposit/basket or a group no longer fits, inspect the `review` order and `payment.review` event, arrange fulfillment or refund, and show the customer the saved notice. Never discard a paid event.
+
+Full `shop connect` and plugin verification both save public JSON assets; rebuild/deploy those assets before retiring replaced links. Checkout mode is a public Worker variable, not a secret. If a product search misses an existing deterministic ID, perform the planner's GET for that ID before creating it. Preserve Wrangler's diagnostic when setup fails.

package/lib/app-needs.mjs

@@ -22,25 +22,40 @@ 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); };
     let waiting = 'validating assertions';
     const result = { id: need.id, statement: need.statement, status: 'not', captures: [] };
     try {
-      if (!Array.isArray(need.assertions) || !need.assertions.length) throw new Error('need requires at least one assertion (UI, result, records or file)');
+      if (need.assertions === undefined || Array.isArray(need.assertions) && !need.assertions.length) {
+        result.status = 'pending';
+        result.why = 'Placeholder: add assertions to prove this need';
+        report?.check?.(`need-${need.id}`, 'skip', { label: need.statement, note: result.why });
+        results.push(result);
+        continue;
+      }
+      if (!Array.isArray(need.assertions)) throw new Error('assertions must be an array');
       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 +72,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 +83,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 +133,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 +149,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
@@ -689,7 +689,7 @@ async function buildInto(dist, { esbuild, studio, shop, live, games, before, typ
   mkdirSync(join(dist, '_site'), { recursive: true });
   if(publicMcpSetup(root)) {
     const verified=verifiedMcpConfig(root);
-    writeFileSync(join(dist,'_site','stripe-shop-links.json'),JSON.stringify({config:verified?.result.config??null,next:verified?null:'Ask your AI to finish stripe_shop_plan with verify:true.'}));
+    writeFileSync(join(dist,'_site','stripe-shop-links.json'),JSON.stringify({config:verified?.result.config??null,purchases:existsSync(join(root,'.studio','stripe-purchase-links.json'))?JSON.parse(readFileSync(join(root,'.studio','stripe-purchase-links.json'),'utf8')):null,next:verified?null:'Ask your AI to finish stripe_shop_plan with verify:true.'}));
   }
   writeFileSync(join(dist, '_site', 'posts.json'), `${JSON.stringify({ v: 1, posts })}\n`);
   const studioExtras = schemaExtras(s.schema, { where: 'studio.json site', types: 'Organization', log });
@@ -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,33 @@ 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 };
+    const outcome = appNeedsOutcome(needs);
+    return { ...outcome, ...(needs ? { needs } : {}), 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 }); }
+}
+
+/** Pending is unfinished proof, not a failure of the baseline checks. */
+export function appNeedsOutcome(needs) {
+ const failed=needs?.some(n=>!['met','pending'].includes(n.status));
+ if(failed)return {ok:false,exitCode:1,why:'Some needs from the person’s Codex are not yet met; see needs and captures'};
+ if(needs?.some(n=>n.status==='pending'))return {ok:false,pending:true,exitCode:0,why:'Pending needs are not yet proved.'};
+ return {ok:true,exitCode:0};
 }

package/lib/dev.mjs

@@ -200,6 +200,7 @@ export function devConfig(root, remoteAi) {
   // Always retain the exact local binding configuration for CLI commands after a deploy.
   const abs = (p) => (p && !p.startsWith('/') ? join(base, p) : p);
   delete json.$schema;
+  json.vars={...json.vars,HOMIE_DEV:'1'};
   json.main = entry ?? abs(json.main);
   if (json.assets?.directory) json.assets.directory = abs(json.assets.directory);
   json.d1_databases = (json.d1_databases ?? []).map((d) => ({ ...d, ...(d.migrations_dir ? { migrations_dir: abs(d.migrations_dir) } : {}) }));
@@ -300,6 +301,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}`);}
   }};
@@ -350,6 +352,12 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
     m.on('close', done);
     m.on('error', done);
   });
+  const {functionDeploymentSQL}=await import('./functions-build.mjs');
+  const registerFunctions=()=>new Promise(resolve=>{
+    const child=spawn(bin,['d1','execute','DB','--local','--command',functionDeploymentSQL(root)],{cwd:workerDir(root),env,stdio:['ignore','ignore','inherit']});
+    child.on('close',code=>resolve(code===0));child.on('error',()=>resolve(false));
+  });
+  if(!await registerFunctions())return {ok:false,command:'dev',why:'Local function registration failed; fix the D1 error above before serving requests.'};
   const origin = `http://127.0.0.1:${port}`;
   const printedOrigin = `http://localhost:${port}`;
   log(`Local site: ${printedOrigin}/  (each game: ${printedOrigin}/<id>/play — open it in two browsers)`);
@@ -479,7 +487,7 @@ export async function dev(root, { lan = false, port: askedPort = 8787, remoteAi
     if (rebuilding || ending) return;
     const stamp = toolsStamp(); if (stamp === lastTools) return;
     lastTools = stamp; rebuilding = true;
-    try { log('Studio tools changed: type-checking and rebuilding…'); await build(root, { log }); }
+    try { log('Studio tools changed: type-checking and rebuilding…'); await build(root, { log }); if(!await registerFunctions())throw new Error('Local function registration failed'); }
     catch (error) { log(`Studio tools did not build: ${error.message}`); }
     finally { rebuilding = false; }
   };