@homie-rocks/studio 0.50.6 → 0.51.0

package/CHANGELOG.md

@@ -17,6 +17,68 @@ 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.51.0] - 2026-10-14
+
+**Plugin 0.51.0** · Take the money through your own Stripe, keyless by default.
+
+One Stripe approval enables mixed menus, paid capacity bookings and monthly giving through the owner’s own account.
+
+### Added
+
+- Mixed-item Stripe menus with adjustable quantities, signed paid invoice lines
+  and app references such as table 7 on `order.paid`.
+- Booking collections with pending/confirmed/released records and versioned staff
+  moves. Each published slot has its own Stripe Payment Link with a completed-session
+  capacity limit; the owner's AI syncs slots with `stripe_bookings_sync`.
+- Recurring Payment Links for monthly giving and memberships, paid invoice periods,
+  subscription lifecycle events and an API-configured no-code customer portal login.
+- Real sandbox acceptance for menus, two guests with the last-seat link open,
+  full-link deactivation, monthly payment, portal, and clock-driven renewal/failure.
+
+### Changed
+
+- The one-approval CLI connection remains keyless. Homie has no platform credential,
+  backend or cut in the payment path. A key alone never selects session checkout;
+  `STRIPE_CHECKOUT_MODE=sessions` explicitly opts into the fuller connection.
+- Keyless unpaid bookings are pending, not exclusive holds. Payment secures the seat.
+  The optional keyed path retains exclusive expiring holds and exact app-built carts.
+- The giving starter opens real Checkout for suggested one-time/monthly gifts and
+  disables payment before connection. It never counts intentions as gifts.
+
+### Fixed
+
+- Records-only app shells include the shop bridge without needing a multiplayer room.
+- Signed menu invoices and Checkout events tolerate either arrival order, and paid
+  membership access never extends on a failed renewal or revives after cancellation.
+
+### Upgrade notes
+
+Existing studios keep their pinned version until they opt in. Apply booking and
+subscription migrations when adding those capabilities. Run connect after changing
+shop items; the owner's AI syncs published slot manifests after schedule changes.
+Stripe's Payment Link and invoice snapshot limits split large catalogues into menus;
+custom amounts and monthly presets use separate links. No studio catalogue cap is added.
+
+## [0.50.7] - 2026-10-14
+
+**Plugin 0.50.7** · Prove your needs on every screen, with fixes from studio testers.
+
+Your app checks can show that your staff, tablet, kiosk, phone and wall workflows meet the needs you wrote down. Local checks use fresh records, and everyday studio work is more reliable.
+
+### Fixed
+
+- App checks use the screens and staff roles named in your needs, verify sound, vibration and notification requests, and wait for the app to be ready after a reload. If a check cannot finish, it tells you which screen and condition it was waiting for.
+- Your AI can test local functions and tools without opening a browser, including the first event and its app or booking references. Staff access across your studio works alongside access granted to individual apps.
+- Functions can safely update shared records, append entries and increment counters when several requests arrive together. Your AI can read event feeds through tools, discover feed changes, and clear history through a point you choose.
+- Local previews refresh when you edit your app's HTML, CSS or JavaScript. Records-only apps open without game rules or a room, and embedded apps can keep temporary browser storage when persistent storage is unavailable. Checks handle confirmation dialogs and rebuilt app frames; local staff links use localhost.
+- Invalid records explain which field or ID needs fixing. Tool failures keep their useful explanation while hiding credentials. On narrow screens without 3D support, the fallback message leaves the headline readable; command help points to your app's files.
+- Shop and giving previews keep your items and amounts visible before payments are connected, with checkout disabled. A new studio can preview an empty shop.
+
+### Upgrade notes
+
+- Upgrade, build and redeploy your studio to apply migration `0024_tool_data_versions.sql`, which lets functions detect conflicting record updates. This release adds no studio quota or automatic history deletion.
+- Local app checks use isolated records and private local staff sessions by default. Use `check --no-isolate` when you deliberately want to check existing records. Production sign-in stays the same.
+
 ## [0.50.6] - 2026-10-14
 
 **Plugin 0.50.6** · Scheduled functions run, and your AI can see every run.

package/app-starters/giving/README.md

@@ -1,5 +1,28 @@
 # Together we can
 
-Edit app.json words and starter settings. Phone: /<id>/open; wall: /<id>/tv. A site/pages/<id>/index.html replaces only the landing. Records are public; use references, never private contact details. Staff updates require an account grant.
+This starter opens real Checkout for one-time or monthly gifts from your studio's
+shop. Run `shop init --giving --currency CAD`, then connect the organisation's
+Stripe. The default gift options include $20 monthly. Existing studios and apps
+are unchanged; generate this starter to opt in.
 
-Giving totals are public intentions, not received money. The gift link opens the studio shop. Use `shop init --giving --currency CAD` and connect the organisation’s Stripe account. Monthly renewals are managed in Stripe.
+The phone reads the actual shop's donation options and availability. Without
+Stripe, the options are a disabled preview (`screen.shopPreview: true`). A chosen-amount item (`price: 'choose'`)
+shows an amount field using the item's minimum and maximum. See `shop/SHOP.md`
+for the keyless Payment Links setup and “give $20 monthly” example.
+
+Checkout opening never increments a total or creates an intention record. Stripe's
+verified payment supplies `order.paid` and `subscription.started`; subsequent
+invoices supply `subscription.renewed` or `subscription.failed`. Connect these
+events to your own public progress display if desired. The starter deliberately
+shows no collected total until you implement that verified projection.
+
+The Manage my gifts link opens the studio shop, where the giver can open their
+own Stripe customer portal. Connect creates the no-code portal login through Stripe's API; no Dashboard toggle is needed.
+Set `giving.receiptText` in shop.json for your organisation's receipt wording.
+Edit app.json name, blurb and colour for your cause. Phone: /<id>/open; wall:
+/<id>/tv. Capture and check both surfaces before sharing.
+
+Add the cause’s actual needs to its CODEX.md before running `check`. This starter
+has no pretend shared-record action for the checker to click. For a disconnected
+preview, assert `[data-action]:disabled` on the phone; verify paid flows with the
+Checkout harness and signed events once the keyless connection is available.

package/app-starters/giving/app.json

@@ -1,29 +1,20 @@
 {
   "id": "giving",
   "name": "Together we can",
-  "blurb": "Support our goal with a one-time or monthly gift. Intentions below are not payments.",
+  "blurb": "Support our work with a one-time or monthly gift, paid securely through Stripe.",
   "entry": "src/view.ts",
   "roles": {
     "customer": {
       "signIn": false,
-      "can": [
-        "read:entries",
-        "create:entries"
-      ]
+      "can": []
     },
     "wall": {
       "signIn": false,
-      "can": [
-        "read:entries"
-      ]
+      "can": []
     },
     "staff": {
       "signIn": true,
-      "can": [
-        "read:entries",
-        "update:entries",
-        "delete:entries"
-      ]
+      "can": []
     }
   },
   "surfaces": {
@@ -37,14 +28,14 @@
     "join": "Scan to join",
     "one": "person",
     "many": "people",
-    "action": "Record my intention",
-    "total": "Giving intentions",
+    "action": "Give on Stripe",
+    "total": "Your gift",
     "choice": "Choose an option",
     "monthly": "Gift frequency",
     "once": "One time",
     "month": "Monthly",
     "give": "Give securely on Stripe",
-    "goal": "Intention goal \u00b7 not payments received",
+    "goal": "Our goal",
     "prompt": "Choose what works for you.",
     "finished": "All three answers are in. Thank you!",
     "complete": "Mark complete",
@@ -54,33 +45,6 @@
     "live": "Together \u00b7 live",
     "reconnecting": "Reconnecting\u2026"
   },
-  "records": {
-    "persist": true,
-    "collections": {
-      "entries": {
-        "fields": {
-          "choice": {
-            "type": "string",
-            "required": true,
-            "maxLength": 100
-          },
-          "status": {
-            "type": "string",
-            "required": true,
-            "maxLength": 60
-          },
-          "amount": {
-            "type": "number",
-            "required": true
-          },
-          "monthly": {
-            "type": "boolean",
-            "required": true
-          }
-        }
-      }
-    }
-  },
   "parts": [],
   "netplay": {
     "v": 1,
@@ -100,7 +64,8 @@
   "watch": "overview",
   "screen": {
     "join": "bottom-right",
-    "share": "top-right"
+    "share": "top-right",
+    "shopPreview": true
   },
   "needs": {
     "three": "0.185.1",
@@ -108,12 +73,9 @@
     "@homie-rocks/geom": "0.1.1",
     "@types/three": "0.185.1"
   },
-  "check": {
-    "action": "[data-action]",
-    "observe": "[data-count]"
-  },
+  "check": {},
   "landing": {
-    "pitch": "Support our goal with a one-time or monthly gift. Intentions below are not payments."
+    "pitch": "Support our work with a one-time or monthly gift, paid securely through Stripe."
   },
   "room": {
     "host": "server"
@@ -126,6 +88,7 @@
     "kind": "giving",
     "choices": [
       "10",
+      "20",
       "25",
       "50"
     ],
@@ -158,5 +121,9 @@
         ]
       }
     ]
+  },
+  "records": {
+    "persist": false,
+    "collections": {}
   }
 }

package/app-starters/giving/index.html

@@ -1,3 +1,3 @@
 <!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Live together</title><style>
-*{box-sizing:border-box}body{margin:0;background:var(--tone,#183b55);color:#fff7df;font-family:system-ui,sans-serif}main{min-height:100svh;padding:clamp(24px,5vw,64px);display:grid;grid-template-columns:1.1fr 1fr;gap:40px;align-items:center}h1{font-size:clamp(44px,6vw,88px);line-height:1;letter-spacing:-.05em;margin:20px 0}p{line-height:1.6;max-width:40em}#connection{font-size:12px;text-transform:uppercase;letter-spacing:.18em}.panel{background:#fff7df;color:#20352e;border-radius:28px;padding:28px;box-shadow:0 30px 80px #0003}#count{font-size:80px;font-weight:800;line-height:1}ul{padding:0;list-style:none}li{padding:12px 0;border-bottom:1px solid #20352e22}button,select,a{font:inherit;min-height:48px;border-radius:12px}button,select{padding:10px 16px;width:100%;margin-top:8px}button{background:var(--tone);color:#fff7df;border:0;cursor:pointer}button:disabled{opacity:.5}a{display:inline-flex;align-items:center;color:inherit}label{display:block;margin-top:14px}select{background:white;color:#20352e;border:1px solid #20352e66}progress{width:100%;height:22px;accent-color:var(--tone)}#status{min-height:24px}#amount{font-size:40px;font-weight:700}button:focus-visible,select:focus-visible,a:focus-visible{outline:3px solid #df9325;outline-offset:4px}.wall #controls{display:none}#giving-link[hidden],[hidden]{display:none!important}@media(max-width:650px){main{display:block;padding:72px 22px 24px}h1{font-size:46px}.panel{margin-top:24px;padding:22px}#count{font-size:58px}li{font-size:14px}}@media(max-height:520px) and (min-width:651px){main{padding:65px 25px 20px;gap:22px}h1{font-size:38px}.panel{padding:18px}}
+*{box-sizing:border-box}body{margin:0;background:var(--tone,#183b55);color:#fff7df;font-family:system-ui,sans-serif}main{min-height:100svh;padding:clamp(24px,5vw,64px);display:grid;grid-template-columns:1.1fr 1fr;gap:40px;align-items:center}h1{font-size:clamp(44px,6vw,88px);line-height:1;letter-spacing:-.05em;margin:20px 0}p{line-height:1.6;max-width:40em}#connection{font-size:12px;text-transform:uppercase;letter-spacing:.18em}.panel{background:#fff7df;color:#20352e;border-radius:28px;padding:28px;box-shadow:0 30px 80px #0003}#count{font-size:80px;font-weight:800;line-height:1}ul{padding:0;list-style:none}li{padding:12px 0;border-bottom:1px solid #20352e22}button,select,input,a{font:inherit;min-height:48px;border-radius:12px}button,select,input{padding:10px 16px;width:100%;margin-top:8px}button{background:var(--tone);color:#fff7df;border:0;cursor:pointer}button:disabled{opacity:.5}a{display:inline-flex;align-items:center;color:inherit}label{display:block;margin-top:14px}select,input{background:white;color:#20352e;border:1px solid #20352e66}progress{width:100%;height:22px;accent-color:var(--tone)}#status{min-height:24px}#amount{font-size:40px;font-weight:700}button:focus-visible,select:focus-visible,a:focus-visible{outline:3px solid #df9325;outline-offset:4px}.wall #controls{display:none}#giving-link[hidden],[hidden]{display:none!important}@media(max-width:650px){main{display:block;padding:72px 22px 24px}h1{font-size:46px}.panel{margin-top:24px;padding:22px}#count{font-size:clamp(28px,9vw,46px)}li{font-size:14px}}@media(max-height:520px) and (min-width:651px){main{padding:65px 25px 20px;gap:22px}h1{font-size:38px}.panel{padding:18px}}
 </style><main><header><span id="connection"></span><h1></h1><p id="intro"></p><div id="goal"><p id="goal-label"></p><div><span id="amount"></span> / <span id="target"></span></div><progress></progress></div><ul id="entries" aria-live="polite"></ul></header><section class="panel"><div id="label"></div><div id="count" data-count>0</div><div id="controls"><p id="prompt"></p><label><span id="choice-label"></span><select id="choice"></select></label><label id="frequency"><span id="frequency-label"></span><select id="monthly"><option id="once" value="once"></option><option id="month" value="month"></option></select></label><button data-action></button><a id="giving-link" href="/shop/" target="_blank" rel="noopener"></a></div><p id="status" role="status"></p></section></main><script type="module" src="./assets/main.js"></script></html>

package/app-starters/giving/src/rules.ts

@@ -15,7 +15,7 @@ export default defineRules({
   },
   room: {
     rounds: { seconds: 0, breakSeconds: 0 }, bots: { keep: 0 },
-    join() { return { kind: 'participant', at: { x: 0, y: 0 } }; },
+    join() { return { kind: 'participant', at: { x: 0, y: 0, z: 0 } }; },
     on: { refresh(world) { world.shared.revision += 1; world.emit('refresh', { x: 0, y: 0 }, {}); } },
   },
 });

package/app-starters/giving/src/view.ts

@@ -1,74 +1,72 @@
 import app from '../app.json';
 import { openRoom } from '@homie-rocks/studio/rules/view';
 import type rules from './rules';
-import { createAppRecords, type AppRecord } from '@homie-rocks/studio/apps';
-import { randomId } from '@homie-rocks/studio/links';
-type Entry = { choice: string; status: string; amount: number; monthly: boolean };
+import { createShop, type ShopCatalog } from '@homie-rocks/studio/shop';
 const room = openRoom<typeof rules>();
-const net = room.net;
-const role = net.params.role ?? 'customer';
-const words: Record<string, string> = app.words;
-const config = app.starter;
+const shop = createShop();
 const $ = <T extends HTMLElement = HTMLElement>(s: string) => document.querySelector<T>(s)!;
-const records = createAppRecords<Entry>({ collection: 'entries' });
-let rows: AppRecord<Entry>[] = [], busy = false, ready = false, question = 0;
 const action = $<HTMLButtonElement>('[data-action]');
-document.body.className = role;
-document.body.style.setProperty('--tone', config.color);
-$('h1').textContent = app.name; $('#intro').textContent = app.blurb;
-$('#label').textContent = words.total; action.textContent = words.action;
-$('#choice-label').textContent = words.choice;
-$('#frequency-label').textContent = words.monthly;
-$('#once').textContent = words.once; $('#month').textContent = words.month;
-$('#giving-link').textContent = words.give;
-$('#giving-link').hidden = config.kind !== 'giving';
-$('#frequency').hidden = config.kind !== 'giving';
-$('#goal').hidden = config.kind !== 'giving';
-$('#controls').hidden = role === 'wall';
-const select = $<HTMLSelectElement>('#choice');
-function choices() {
- select.replaceChildren();
- const list = config.kind === 'quiz' ? config.questions[question]?.choices ?? [] : config.choices;
- for (const value of list) { const option = document.createElement('option'); option.value = value; option.textContent = value; select.append(option); }
- $('#prompt').textContent = config.kind === 'quiz' ? config.questions[question]?.text ?? words.finished : words.prompt;
- action.hidden = config.kind === 'quiz' && question >= config.questions.length;
-}
-choices();
+const choice = $<HTMLSelectElement>('#choice');
+const frequency = $<HTMLSelectElement>('#monthly');
+let catalog: ShopCatalog | undefined, busy = false;
+const wall = room.net.params.role === 'wall';
+document.body.className = room.net.params.role ?? 'customer';
+document.body.style.setProperty('--tone', app.starter.color);
+$('h1').textContent = app.name;
+$('#intro').textContent = app.blurb;
+$('#label').textContent = wall ? 'Give with us' : 'Your gift';
+$('#choice-label').textContent = 'Choose a gift';
+$('#frequency-label').textContent = 'Gift frequency';
+$('#once').textContent = 'One time'; $('#month').textContent = 'Monthly';
+$('#giving-link').textContent = 'Manage my gifts';
+$('#goal').hidden = true;
+$('#entries').hidden = true;
+$('#prompt').textContent = 'Choose what works for you. Payments go directly to our Stripe account.';
+const amountLabel = document.createElement('label'); amountLabel.textContent = 'Your amount';
+const amount = document.createElement('input'); amount.type = 'number'; amount.inputMode = 'decimal'; amountLabel.append(amount);
+choice.parentElement!.after(amountLabel);
+function selected() { return catalog?.items.find(i => i.id === choice.value); }
 function paint() {
- $('[data-count]').textContent = String(rows.length);
- const amount = rows.reduce((n, r) => n + r.data.amount, 0);
- $('#amount').textContent = new Intl.NumberFormat(undefined, { style: 'currency', currency: config.currency }).format(amount);
- $('#target').textContent = new Intl.NumberFormat(undefined, { style: 'currency', currency: config.currency }).format(config.goal);
- $<HTMLProgressElement>('progress').max = config.goal; $<HTMLProgressElement>('progress').value = amount;
- $('#goal-label').textContent = words.goal;
- action.disabled = busy || !ready;
- $('#entries').replaceChildren();
- for (const row of rows.slice(-6).reverse()) {
-  const li = document.createElement('li');
-  li.textContent = `${row.data.choice} · ${row.data.status}${row.data.monthly ? ' · ' + words.month : ''}`;
-  if (role === 'staff' && row.data.status !== words.done) {
-   const button = document.createElement('button'); button.textContent = words.complete;
-   button.onclick = () => { void records.update(row, { ...row.data, status: words.done }).then(refresh).catch(e => { $('#status').textContent = e.message; }); }; li.append(button);
-  }
-  $('#entries').append(li);
+ const item = selected();
+ amountLabel.hidden = item?.price !== 'choose';
+ action.disabled = busy || !catalog?.open || !item || item.way === 'closed';
+ action.textContent = frequency.value === 'month' ? 'Give monthly on Stripe' : 'Give on Stripe';
+ $('[data-count]').textContent = wall ? 'Thank you' : item?.shown ?? 'Preview';
+ if (item?.price === 'choose') {
+  const scale = catalog!.currencyScale;
+  amount.min = String((item.min ?? 0) / scale);
+  amount.max = item.max == null ? '' : String(item.max / scale);
+  amount.step = String(1 / scale);
  }
 }
-async function refresh() {
- try { rows = await records.list(); ready = true; paint(); net.playable(); }
- catch (error) { $('#status').textContent = (error as Error).message; }
+function options() {
+ choice.replaceChildren();
+ for (const item of catalog?.items ?? []) {
+  if (item.kind !== 'donation' || Boolean(item.interval) !== (frequency.value === 'month')) continue;
+  const option = document.createElement('option'); option.value = item.id; option.textContent = `${item.name} · ${item.shown}`; choice.append(option);
+ }
+ paint();
 }
+choice.onchange = paint; frequency.onchange = options;
 action.onclick = async () => {
+ const item = selected(); if (!item || !catalog?.open) return;
+ const value = item.price === 'choose' ? Math.round(Number(amount.value) * catalog.currencyScale) : undefined;
+ if (item.price === 'choose' && (!amount.value || !Number.isSafeInteger(value) || value! < (item.min ?? 0) || item.max != null && value! > item.max)) {
+  $('#status').textContent = 'Enter an amount within the displayed range.'; return;
+ }
  busy = true; paint();
  try {
-  const choice = select.value;
-  await records.create({ choice: config.kind === 'quiz' ? `${question + 1}. ${choice}` : choice, status: words.pending, amount: config.kind === 'giving' ? Number(choice) : 0, monthly: $<HTMLSelectElement>('#monthly').value === 'month' }, randomId());
-  $('#status').textContent = words.thanks;
-  if (config.kind === 'quiz') { question++; choices(); }
-  room.command('refresh', {}); await refresh();
- } catch (error) { $('#status').textContent = (error as Error).message; }
- finally { busy = false; paint(); }
+  // Opening Checkout is not a payment. Only Stripe's verified webhook records a gift.
+  const opened = await shop.buy(item.id, 1, value);
+  $('#status').textContent = opened ? 'Finish your gift on Stripe. Your receipt confirms payment.' : 'Open the shop to sign in or complete the steps for this gift.';
+  if (!opened) shop.open(item.id);
+ } finally { busy = false; paint(); }
 };
-room.on('refresh', () => { void refresh(); });
-net.on('link', () => { void refresh(); });
-setInterval(() => { $('#connection').textContent = net.link === 'online' ? words.live : words.reconnecting; void refresh(); }, 2000);
+async function refresh() {
+ catalog = await shop.catalog(); options();
+ $('#status').textContent = wall ? 'Join on your phone to choose a one-time or monthly gift.' : catalog.open ? 'Monthly gifts renew until you cancel through Stripe. Manage your gifts using the link below.' : 'Preview — giving is unavailable until the organisation connects Stripe.';
+ $('#connection').textContent = room.net.link === 'online' ? 'Together · live' : 'Connecting…';
+ room.net.playable();
+}
+shop.on('closed', () => { void refresh(); });
 void refresh();

package/apps/APPS.md

@@ -43,13 +43,13 @@ The QR encoder is the existing wall encoder, publicly exported with types. Links
 
 ## Parts, check and stores
 
-Parts import exactly as games do (`@parts/<id>` or `@parts/<host>/<id>`), with the same provenance and credit checks. `check.action` and `check.observe` name real UI selectors: the checker clicks on a phone, waits for changed text on wall and both phones, then reloads the actor and checks again. `check.params` optionally supplies public URL parameters (for example `{ "ticket": "404" }`) to all three surfaces so the action can address an existing sample record. The checker always chooses its own room. No round hooks are required. This performs the declared action and writes real records: use a local/test studio or a workflow explicitly safe to exercise.
+Parts import exactly as games do (`@parts/<id>` or `@parts/<host>/<id>`), with the same provenance and credit checks. `check.action` and `check.observe` name real UI selectors: the checker clicks on a phone, waits for changed text on wall and both phones, then reloads the actor and checks again. `check.params` optionally supplies public URL parameters (for example `{ "ticket": "404" }`) to all three surfaces so the action can address an existing sample record. The checker always chooses its own room. No round hooks are required. `check` uses fresh isolated records by default; run dev and check its localhost URL. `--no-isolate` explicitly uses existing records. A Codex-only needs plan can omit this baseline action.
 
 `homie-studio standalone plan/build <app-id>` reuses Electron/Capacitor and the same built bundle. Public customer record calls use the existing standalone origin allowlist; credentials are never shared across origins. Native staff sign-in, private collections, offline record writes, native billing and automatic store upload are not implemented. Existing game standalone behavior is unchanged. A store build still needs its normal local SDK, signing and store review.
 
 ## Shop button on the screen
 
-An open shop with items for this game or app shows **Shop** above its play/open screen. The shell reserves 52 pixels plus the safe area above the content, so the button never covers its controls. In `game.json` or `app.json`, set `"screen": { "shop": false }` to hide this button (merge with any existing screen settings). The room panel and your own shop buttons still work. Closed shops, kids policies and an empty selection show no button.
+An open shop with items for this game or app shows **Shop** above its play/open screen. The shell reserves 52 pixels plus the safe area above the content, so the button never covers its controls. In `game.json` or `app.json`, set `"screen": { "shop": false }` to disable the experience’s shop (merge with any existing screen settings). Keep it true or omitted when your app uses its own `createShop` buttons; false also refuses their checkout bridge requests. Closed shops, kids policies and an empty selection show no button.
 
 ```ts
 import { createShop } from '@homie-rocks/studio/shop';
@@ -59,3 +59,71 @@ itemButton.onclick = () => shop.open('supporter');
 ```
 
 These calls open the same shop in games and apps. Inside a player card, purchases leave for the studio's shop; ordinary play/open pages start Stripe checkout. The studio's TV and kids policies still apply.
+
+
+
+`check` uses fresh isolated records by default and prints that choice. Run `dev`,
+then check its **localhost** URL with the studio root available. All screens in a
+run share its isolated records; later runs start empty. `--no-isolate` explicitly
+uses existing records (including when checking a live URL). Do not assume existing
+bookings are fixtures: create the needed records through the flow. The baseline
+`app.json check` action is optional when the Codex contains executable needs.
+
+`dev` creates a private local test credential. The checker signs each screen into
+the role the need names without a passkey ceremony, and still enforces that role’s
+record capabilities. This credential only works on loopback with the dev-only
+Worker binding; production account sign-in is unchanged. Use `app role <id> staff
+--player <account> --studio` for a studio-wide grant; omit `--studio` for one app.
+Staff links printed locally use localhost. A grant can be revoked at either scope.
+
+Example: `{"id":"fit","statement":"My crew fits boards from a tablet","role":"staff",
+"steps":[{"surface":"tablet","selector":"[data-fit]","click":true}],
+"assertions":[{"surface":"tablet","selector":"[data-state]","text":"Fitted"},
+{"surface":"tablet","effect":"sound","name":"audio"}]}`.
+
+Nonvisual assertions observe actual platform calls: `sound` (`audio` for Web Audio
+source starts, including the audio package, or `media` for media play), `haptic`
+(`vibrate`), and `notification` (the notification title). Omit `name` to accept any
+request of that type. An app-specific adapter may emit `homie-effect` with
+`{effect,name}` at its real trigger. These prove requests, not that an OS delivered
+a notification or a person heard audio. Observations reset before each need.
+
+After reloads and rebuilt frames, check waits for online state, completed arrival,
+a hidden loading cover and two frames before assertions/captures. Timeout evidence
+names the surface and selector/effect it awaited. Dialogs are automatically accepted
+and reported. Read retries recover detached frames; dispatched actions are not
+silently repeated. `dev` rebuilds root HTML, CSS and JS as well as source and map
+changes. Unavailable sandbox Web Storage uses frame-local memory; use app records
+or `net.prefs` for persistence across reloads.
+
+Record fields start with a lowercase letter and use lowercase letters, digits and
+underscore. Record IDs use 1–64 letters, digits, underscores or hyphens. `app_schema`
+and the `app_records` tool schema explain the contract; validation errors name it.
+
+Live and local unconnected shop/giving pages display the declared items and amounts
+with disabled payment controls. They say they are not taking payments yet. A fresh
+`/shop/` has an empty preview; an authored shop page still takes precedence.
+
+## Booking capacity
+
+See `shop/SHOP.md` for “book a tune and hold the slot”. A collection opts in with
+`booking: {slots: 'slots', item: 'full-tune'}`. Slots are ordinary staff-managed
+records with integer `capacity`. Bookings are server-managed records created by
+`shop.book`; their public data is only slot, quantity and state. Keep personal
+information in a separate private collection. Public roles must not have write
+capabilities for slots or bookings. Staff movement is a versioned record update
+containing only `slot`; confirmation and release follow verified Checkout state.
+The default keyless connection uses one Payment Link per published slot. Call
+`stripe_bookings_sync` after publishing/changing slots. Pending checkout does not
+block others; payment secures the seat. Use record.booking.full/available/synced
+for slot display. Read SHOP.md for the complete manifest and limitations.
+
+The giving starter now reads the actual shop donation options with `shop.catalog()`.
+`shop init --giving --currency CAD` includes $20 monthly; `app new giving --from giving`
+opens Checkout for the selected amount and frequency. A disconnected shop displays
+a disabled preview. No intention record or unverified collected total is created.
+Use the Manage my gifts link for the buyer-owned Stripe portal in the shop.
+
+Records-only apps support the same shop bridge as room apps. In the sandboxed
+view, use `createShop({target: parent})` to send checkout and booking requests to
+the authenticated outer shell; a room simulation is not required for payments.

package/apps/apps.ts

@@ -1,6 +1,6 @@
 /** Lasting records through the same sandbox bridge used by saves and the shop. */
 import { randomId } from '../links/links.mjs';
-export interface AppRecord<T> { id: string; data: T; version: number; updatedAt: number }
+export interface AppRecord<T> { id: string; data: T; version: number; updatedAt: number; booking?: {full: boolean; available: number; synced: boolean} }
 export function createAppRecords<T extends Record<string, unknown>>({ collection }: { collection: string }) {
   if (!/^[a-z][a-z0-9-]{0,39}$/.test(collection)) throw new Error('invalid collection');
   const pending = new Map<string, { resolve: (v: any) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();

package/bin/homie-studio.mjs

@@ -246,7 +246,7 @@
  *                                         when another MCP server named homie has taken the connector's name there.
  *
  *   homie-studio codex new <id> [--kind app|game] [--name "<Name>"]
- *                                         games/<id>/CODEX.md: the Game Codex, every section, in the game's colours (a game
+ *                                         apps/<id>/CODEX.md for apps; games/<id>/CODEX.md for games: the Codex, every section, in the game's colours (a game
  *                                          is planned before it is made: with no game <id> yet, it starts its folder)
  *   homie-studio codex <id> [--artifact] [--open]
  *                                         the codex as a page in the game's own look (.studio/codex/<id>.html; it redraws
@@ -788,7 +788,11 @@ function print(result) {
         `Written: ${result.file}`);
       break;
     case 'check':
-      if (result.kind === 'app') { lines.push(`PASS: app ${result.game ?? ''}: wall and two phones shared an action; reconnect ${result.reconnect ? 'passed' : 'failed'}.`, `  ${result.before} → ${result.after}`); break; }
+      if (result.kind === 'app') {
+        if (result.needs?.length) lines.push(`PASS: app ${result.game ?? ''}: ${result.needs.length} Codex needs checked on ${(result.surfaces ?? []).join(', ')}.`);
+        if (result.reconnect) lines.push(`PASS: app ${result.game ?? ''}: wall and two phones shared an action; reconnect passed.`, `  ${result.before} → ${result.after}`);
+        break;
+      }
       if (result.results) { for (const r of result.results) lines.push(`${r.game}: PASS at ${r.site}: room ${r.room}, round ${r.round?.n} (${r.round?.humans} humans, ${r.round?.bots} bots), connection ${r.uninterrupted === true ? 'uninterrupted' : r.uninterrupted === false ? 'INTERRUPTED' : 'unknown'}`); break; }
       if (result.site) lines.push(`Checked ${result.local ? 'this studio\'s own build' : 'the site'} at ${result.site}.`);
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
@@ -951,7 +955,7 @@ async function main() {
     const { withKey } = await import('../lib/office.mjs');
     const id = positional[2]; const role = positional[3];
     if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(id ?? '') || !/^[a-z][a-z0-9-]{0,39}$/.test(role ?? '')) throw new Error('app role <id> <role> [--player <account>] [--revoke] [--url <site>]');
-    return withKey(root, flags.get('url'), (call) => call(`/${id}/api/app/roles`, { role, ...(flags.get('player') ? { player: flags.get('player') } : {}), revoke: flags.has('revoke') }));
+    return withKey(root, flags.get('url'), (call) => call(`/${id}/api/app/roles`, { role, studio:flags.has('studio'), ...(flags.get('player') ? { player: flags.get('player') } : {}), revoke: flags.has('revoke') }));
   }
   if (cmd === 'app' && sub === 'new') return newApp(root, positional[2], { name: flags.get('name'), from: flags.get('from') ?? 'welcome' });
   if (cmd === 'game' && sub === 'new') return newGame(root, positional[2], { from: flags.get('from') ?? 'gem-rush', name: flags.get('name') });
@@ -1001,7 +1005,7 @@ async function main() {
       const results = [];
       for (const game of games) {
         const shots = flags.get('shots') ? resolve(flags.get('shots'), ...(games.length > 1 ? [game] : [])) : null;
-        const r = await tracked(root, 'checks', (report) => check({ root, url: site.url, game, shots, log, report }), 'check');
+        const r = await tracked(root, 'checks', (report) => check({ root, url: site.url, game, shots, log, report, isolate:!flags.has('no-isolate') }), 'check');
         results.push({ ...r, game, site: site.url, local: site.local });
         const receiptDir = join(root, '.studio', 'checks');
         mkdirSync(receiptDir, { recursive: true });

package/functions/FUNCTIONS.md

@@ -8,8 +8,9 @@ homie-studio dev
 homie-studio function fire order.paid --id local-order-1 --input '{"order":"example"}'
 ```
 
-The fire command connects to the local studio through the existing browser OAuth
-approval. It is an owner tool and refuses remote hosts. It records an event in the
+The fire command uses the private credential created by `dev`, without browser
+approval. Local `tool call` uses the same headless connection. It is an owner tool
+and refuses remote hosts; production connections still require OAuth. It records an event in the
 same durable dispatcher as real events; firing the same ID again is a duplicate.
 
 ```ts
@@ -346,3 +347,39 @@ local webhook declaration. Build, commit and deploy the removal to retire the
 subscription and pending retries; in-flight requests cannot be recalled. Adding
 again creates a new registration and key, so old pending deliveries cannot be sent
 to a replacement receiver. The feed's MCP subscriptions remain available.
+
+
+## Concurrent storage and logs
+
+`context.database` is scoped to the function (tools can explicitly share a
+namespace). `get(key)` returns its JSON value; `getVersioned(key)` returns
+`{value,version}` or null. `put(key,value,{version})` compares and sets in one SQL
+statement, returning `{ok:true,version}` or `{ok:false,conflict:true}`. Version 0
+means create only. Omitting the version preserves unconditional replacement.
+
+```ts
+let row = await context.database.getVersioned('total');
+while (!(await context.database.put('total', Number(row?.value ?? 0) + 1,
+  { version: row?.version ?? 0 })).ok) {
+  row = await context.database.getVersioned('total');
+}
+// Prefer a single atomic statement for these operations:
+await context.database.increment('total', 1);
+await context.database.append('selected-items', event.data);
+const page = await context.database.list({prefix:'booking:', after:'', limit:100});
+// page.items: {key,value,version}[], page.next: next cursor or null.
+```
+
+These operations prevent lost writes between Workers; they do not make an
+at-least-once event exactly once. Use event IDs for deduplication. Atomic append is
+for application arrays, not an ever-growing operational log. Declare a studio event
+feed for logs and read pages using `studio_events_read` or resources. The owner can
+clear retained event/delivery history through an explicit sequence with
+`studio_events_clear`; no retention limit is imposed by default.
+
+A booking payment can be tested with:
+`homie-studio function fire order.paid --id fitting-paid-1 --input
+'{"order":"local-order","app":"boards","reference":"booking-1"}'`.
+Create any records the handler reads first. First fire registers subscriptions
+before writing the event, so the first event is delivered too. No Stripe checkout
+or browser approval is needed for this explicitly synthetic local event.