@homie-rocks/studio 0.51.8 → 0.53.0

package/CHANGELOG.md

@@ -17,6 +17,65 @@ 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**
+
+Run your place with trusted actions across screens and AI, live business records, shared booking capacity and stronger proofs that it works for your customers.
+
+### Added
+
+- **One trusted action from any screen or AI:** App screens call the same studio tools as MCP through `createAppTools`, with strict input schemas, server role checks and versioned writes.
+- **Screens that stay in step:** Live record subscriptions and presence use the existing Lobby without polling or a dummy game room. Supported app context supplies your public address and a local proof clock; isolated proofs stay separate.
+- **Business events with useful history:** Record changes include the previous value. Trusted functions publish schema-checked business feeds with durable receipts that prevent duplicate events.
+- **Bookings that share one capacity:** App holds and Stripe session checkout use the same capacity row, including group quantities, ownership, version checks and scheduled release. Confirmations distinguish unpaid reservations from verified payments.
+- **Proofs for difficult situations:** Needs can force disabled clicks to check server refusals, race actions from separate browsers, restart local development and reload without WebGL.
+- **Time at your place:** IANA time zones support local scheduling and explicitly reject nonexistent or ambiguous wall times around clock changes.
+
+### Fixed
+
+- **Shops that survive upgrades:** Matching 0.51.6 Stripe plugin verifications remain valid; real shop, slot or site changes explain what needs verification. Unfinished setup still builds and deploys with checkout closed and a clear next step.
+- **Room for your whole catalogue:** Verified public links ship as a JSON asset instead of a size-limited Worker text binding, including catalogues with more than 100 links. Missing assets keep checkout closed.
+- **Faster Stripe setup and replanning:** Saved public observations avoid repeated discovery. Explicit refresh paginates expanded Payment Link lists, refreshes changed links and preserves verification freshness. Private webhook setup installs Stripe's official npm CLI automatically when missing, then continues to browser approval.
+
+### Changed
+
+- **Guides grounded in six real builds:** App and game guides include place patterns, security alternatives and small examples that compile against the toolkit.
+- **Cleaner upgrades:** Recognized polling workarounds and exact obsolete capability notes are retired; custom business logic remains available for review.
+
+### Upgrade notes
+
+- Apply migrations `0027_app_live.sql`, `0028_business_events.sql` and `0029_booking_holds.sql` in order.
+- Replace refresh timers with record subscriptions, and private origin, peer and clock reads with `createAppContext`.
+- Shared local booking holds require Stripe session checkout. Keyless Payment Links cannot claim those holds and are explicitly refused.
+
 ## [0.51.8] - 2026-10-15
 
 **Plugin 0.51.8**

package/apps/APPS.md

@@ -222,3 +222,120 @@ and pass a role when deliberately testing the customer experience.
 `check --shots` may capture outside the studio, but persistent needs evidence copies
 those pictures into `.studio/checks` and stores studio-relative paths. Keep that
 folder with the Codex evidence. Deploy can render it without outside-path warnings.
+
+## Screens and AI share tools
+
+Import `createAppTools` from `@homie-rocks/studio/apps`, then call
+`await tools.call('place_book', {slot, request})`. It runs the studio's `defineTool`
+handler, with its strict input schema, audience checks, rate policy and versioned
+`context.database`. The shell supplies identity; message fields cannot grant a
+role. Only studio-defined tools are exposed. Priced tools still use MCP's payment
+approval flow. Dispose the client on unmount. Use a stable request ID across
+retries; a lost response does not mean the write failed. Keep rules in a shared
+`domain.ts`, but only the server handler commits them.
+
+## Live records and frame context
+
+`records.subscribe(() => void refresh())` returns an unsubscribe function. It
+notifies on connection/reconnection and when the collection changes; `refresh`
+calls `records.list()` to obtain currently authorized data. Do an initial read as
+well. Coalesce overlapping refreshes in a busy screen. This uses the existing
+Lobby, without a rules file or a dummy map. Notifications contain collection names,
+not records or private IDs. A 15-second server heartbeat repairs missed wakes;
+screens do not poll. Closing the page closes its stream. Apply `0027_app_live.sql`
+on upgrade before starting the new Worker.
+
+`createAppContext()` provides `ready`, `current`, `subscribe`, `now()` and `dispose`.
+After `await context.ready`, `current` has `app`, `origin`, public `url`, and
+`presence` (connected screens in this app/room and isolated proof scope, including
+the current screen). Presence is screens, not unique people or paid customers.
+The public address excludes role grants and booking credentials. Do not inspect
+`HOMIE_NET` or cast room internals to read peers.
+
+For a signed local proof session, the shell supports
+`window.homieApp.setTestClock(epochMilliseconds)` and `null` to restore wall time;
+frame code reads `context.now()`. Production shells refuse the setter. This is a
+view clock, never authority for capacity, payment or server deadlines. Scheduled
+needs supply their own explicit `scheduledTime`.
+
+See `guides/app/PLACES.md` for the six-build recipe and small typed examples.
+
+## One capacity budget for holds and Stripe
+
+A collection with `booking: {slots:'slots', item:'ticket'}` uses the same
+`shop_bookings` row from hold through payment. A trusted tool can call:
+
+```ts
+const held = await context.bookings.hold({
+  app: 'place', collection: 'bookings', slot: 'morning', quantity: 2,
+  id: input.request, expiresAt: Date.now() + 60_000 // choose the hold window on the server
+});
+```
+
+Require a signed-in caller, or pass a private, random 32–128 hex-character `token`
+for a guest. Keep the request ID stable on retries; a retry returns the original expiry and never extends it. The returned `id` is
+scoped by app/collection/proof; it is public identification, never authorization.
+Only the owner (or holder of that private token) can `get`, `confirm` or `release`.
+Confirm/release take `{id, version, token?}`. Another owner's ID is not permission.
+The entire group quantity reserves atomically or fails; there is no partial group.
+Slot reads report availability including held and confirmed quantities.
+
+Use `shop.book('ticket', {collection:'bookings', slot:'morning', hold:held.id,
+token}, 2)` to pay for that same row. Session checkout claims it once, in the order
+transaction. A second checkout cannot take it; verified payment updates it.
+`confirmed` means a capacity commitment; only `paid:true` means payment was
+verified. Do not label a confirmation as a paid receipt.
+
+A scheduled owner function calls
+`context.bookings.releaseExpired({app:'place',collection:'bookings',now:event.data.scheduledTime})`.
+Only unconfirmed local holds expire this way. After checkout claims a hold,
+Stripe's verified payment/expiry/refund owns its lifecycle; a local timer cannot
+release a possibly paid seat. Keyless Payment Links cannot safely claim local
+holds: configure session checkout, or keep using their existing pending-to-paid
+path. The toolkit refuses to mix active keyless links with new local holds.
+Apply `0029_booking_holds.sql`; public projections never include actors or tokens.
+
+## Adversarial needs
+
+Actions inside `concurrent` start together on separate browser contexts:
+
+```json
+{"concurrent":[{"surface":"phone","selector":"#book","click":true},{"surface":"phone-two","selector":"#book","click":true}]}
+```
+
+Assert exactly one saved booking afterwards. `{"surface":"staff","selector":"#close","forceClick":true}`
+temporarily bypasses the disabled attribute, clicks, and restores it: assert the
+server refusal and unchanged data. It is not a permission grant.
+`{"surface":"phone","capabilities":{"webgl":false}}` installs a WebGL blocker
+before reloading that surface, leaving ordinary controls functional. Set `true`
+to restore WebGL on another reload. `{"surface":"phone","clock":1792800000000}`
+sets the supported local frame clock.
+
+`{"restart":true}` asks the authenticated local dev controller to restart its own
+Wrangler child, keeps disk state and proof sessions, and waits for readiness.
+It never kills a PID discovered by port. Start the current toolkit's dev server;
+remote URLs and old servers without this controller refuse or time out. Put
+restart/capability steps outside concurrent groups, then assert saved state.
+
+## Place time and upgrades
+
+```ts
+import {placeTime} from '@homie-rocks/studio/links';
+const startsAt = placeTime('2027-03-20', '09:30', 'America/Vancouver');
+```
+
+Store the occurrence's local date/time and IANA zone in place config; derive epoch
+milliseconds with the runtime's zone database. Never append `-07:00`. Invalid dates
+and spring gaps are refused; repeated autumn times require explicit
+`{disambiguation:'earlier'}` or `'later'`. Generate future occurrence dates from the
+calendar rule, not a constant “next Saturday”. Update runtime zone data with the
+runtime itself.
+
+`upgrade --diff` includes recognized obsolete capability notes and standalone
+2–3-second named refresh timers over `createAppRecords` clients. `upgrade --apply`
+replaces those timers with subscriptions and corrects exact stale notes without
+marking old needs passed. Timer conversion uses the studio’s installed TypeScript
+compiler; run `npm install` in the studio first if it is missing. Review the diff and rerun the affected needs. Custom
+combined timer/jobs, hand-written routes and business-event mirrors need a semantic
+migration to the APIs above; they are not automatically deleted. The owner's
+words, historical evidence and unresolved integration work remain intact.

package/apps/apps.ts

@@ -4,7 +4,9 @@ export interface AppRecord<T> { id: string; data: T; version: number; updatedAt:
 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> }>();
+  const listeners = new Set<() => void>();
   const receive = (e: MessageEvent) => {
+    if(e.source === parent && e.data?.type === 'homie-app-changed' && e.data.collections?.includes(collection)) { for(const listener of listeners) listener(); return; }
     if (e.source !== parent || e.data?.type !== 'homie-app-result') return;
     const p = pending.get(e.data.id); if (!p) return;
     pending.delete(e.data.id); clearTimeout(p.timer);
@@ -18,11 +20,76 @@ export function createAppRecords<T extends Record<string, unknown>>({ collection
     parent.postMessage({ type: 'homie-app', id, collection, method, record, data, version }, '*');
   });
   return {
+    subscribe(listener: () => void) { listeners.add(listener); parent.postMessage({type:'homie-app-subscribe',collections:[collection]}, '*'); return () => {listeners.delete(listener);}; },
     async list(): Promise<AppRecord<T>[]> { return (await ask('GET')).records; },
     async get(id: string): Promise<AppRecord<T> | null> { return (await ask('GET', id)).records[0] ?? null; },
     create: (data: T, id = randomId()) => ask('POST', id, data),
     update: (record: AppRecord<T>, data: T) => ask('PUT', record.id, data, record.version),
     remove: (record: AppRecord<T>) => ask('DELETE', record.id, undefined, record.version),
-    dispose() { removeEventListener('message', receive); for (const p of pending.values()) { clearTimeout(p.timer); p.reject(new Error('disposed')); } pending.clear(); },
+    dispose() { listeners.clear(); removeEventListener('message', receive); for (const p of pending.values()) { clearTimeout(p.timer); p.reject(new Error('disposed')); } pending.clear(); },
   };
 }
+
+/** Call the same trusted studio definition used by MCP. The shell supplies identity. */
+export function createAppTools() {
+  const pending = new Map<string, {resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout>}>();
+  const receive = (e: MessageEvent) => {
+    if (e.source !== parent || e.data?.type !== 'homie-app-result') return;
+    const p = pending.get(e.data.id); if (!p) return;
+    pending.delete(e.data.id); clearTimeout(p.timer);
+    if (e.data.result?.ok) p.resolve(e.data.result.data); else p.reject(new Error(e.data.result?.error ?? 'tool failed'));
+  };
+  addEventListener('message', receive);
+  return {
+    call<T = unknown>(name: string, input: Record<string, unknown> = {}): Promise<T> {
+      return new Promise((resolve, reject) => {
+        const id = randomId();
+        const timer = setTimeout(() => { pending.delete(id); reject(new Error('app shell did not answer')); }, 15000);
+        pending.set(id, {resolve: value => resolve(value as T), reject, timer});
+        parent.postMessage({type:'homie-app-tool', id, name, input}, '*');
+      });
+    },
+    dispose() { removeEventListener('message', receive); for (const p of pending.values()) { clearTimeout(p.timer); p.reject(new Error('disposed')); } pending.clear(); }
+  };
+}
+
+export interface AppContext { app: string; origin: string; url: string; presence: number; now: number | null }
+/** Public self address and live presence supplied by the authenticated shell. */
+export function createAppContext() {
+  let value: AppContext | null = null;
+  const listeners = new Set<(context: AppContext) => void>();
+  let resolve!: (context: AppContext) => void;
+  const ready = new Promise<AppContext>(r => {resolve = r;});
+  const receive = (e: MessageEvent) => {
+    if(e.source !== parent || e.data?.type !== 'homie-app-context') return;
+    value = Object.freeze(e.data.context) as AppContext;
+    resolve(value); for(const listener of listeners) listener(value);
+  };
+  addEventListener('message', receive);
+  parent.postMessage({type:'homie-app-context'}, '*');
+  parent.postMessage({type:'homie-app-subscribe',collections:[]}, '*');
+  return {
+    ready,
+    get current() {return value;},
+    now: () => value?.now ?? Date.now(),
+    subscribe(listener: (context: AppContext) => void) {listeners.add(listener); if(value)listener(value); return () => {listeners.delete(listener);};},
+    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/docs/toolkit-place-patterns.md

@@ -1,5 +1,11 @@
 # Building places: layout, authority and recovery
 
+Start with [the six-build place recipe](../guides/app/PLACES.md) and
+[the app contracts](../apps/APPS.md) for screen-to-tool calls, live records,
+shared booking holds, named events, IANA time and adversarial needs. The small
+CAS example below teaches authority; paid inventory uses `context.bookings` so
+checkout and app capacity remain one system.
+
 ## TV join safe area
 
 On `/<id>/tv`, the shell sets `body.homie-join-visible` while the join card is present. It publishes CSS pixel values on the document root in both the shell and the sandboxed app: `--homie-join-x`, `--homie-join-y`, `--homie-join-width`, `--homie-join-height`, and `--homie-join-inset-top/right/bottom/left`. The insets include the card's distance from its configured screen edge. Inactive edges are zero; no card means all values are zero and the body class is absent. Measurements update on resize and iframe navigation. The card is at most 480 × 280 CSS pixels; its address wraps within that box.

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.
 
@@ -383,3 +397,30 @@ A booking payment can be tested with:
 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.
+
+## Previous records and named business events
+
+`record.changed` data includes `previous`: `null` for insert, the old data for
+update/delete. `data` remains the new value for update and the deleted value for
+delete. Both are captured by the same database transaction as the write. Import
+`RecordChanged<T>` and `ScheduledEvent` from `@homie-rocks/studio/functions`;
+scheduled time is `event.data.scheduledTime` (epoch milliseconds), not `event.at`.
+
+Declare a feed in `studio.json` and its allowed payload:
+
+```json
+{"mcp":{"events":{"arrivals":{"event":"place.arrived","audience":"owner","schema":{"type":"object","properties":{"booking":{"type":"string"}},"required":["booking"],"additionalProperties":false}}}}}
+```
+
+A function declares `publish: ['arrivals']`, then calls
+`await context.events.publish({feed:'arrivals', id:event.id, data:{booking:'...'}})`.
+Use the source event ID, or a stable business request ID; repeats with the same
+payload are no-ops, and changed payloads under the same ID are refused. Publication
+and its deduplication receipt commit atomically. Receipts survive feed pruning.
+Do not mirror every record or build a sleep-and-retry log. Keep contact details
+out of operational events. Owner AIs use the existing feed cursor, MCP subscription
+or declared webhook; functions never send email/SMS themselves.
+
+Apply `0028_business_events.sql` on upgrade. Local proof publications carry their
+scope and do not appear in production feed reads. Event feeds retain their declared
+type; give different business feeds distinct types when their content differs.

package/functions/functions.ts

@@ -8,6 +8,10 @@ export interface StudioFunction<Data = unknown> {
   /** Permit an explicit owner replay command to consume retained history. */
   replay?: boolean;
   events?: StudioTool['events'];
+  publish?: string[];
   handler(event: StudioEvent<Data>, context: ToolContext): unknown | Promise<unknown>;
 }
 export function defineFunction<Data = unknown>(definition: StudioFunction<Data>): StudioFunction<Data> { return definition; }
+
+export interface RecordChanged<T = Record<string, unknown>> { app: string; collection: string; record: string; version: number; operation: "insert" | "update" | "delete"; data: T; previous: T | null }
+export interface ScheduledEvent { function: string; cron: string; scheduledTime: number }

package/guides/app/PLACES.md

@@ -0,0 +1,146 @@
+# Build a place people recognize
+
+Use this with APPS.md and TOOLS.md. Six place builds exposed the same rule:
+make the owner's dream visible, with one trusted operation behind every action.
+
+1. **Start with their paragraph.** Quote the owner's actual words in CODEX.md,
+   including sensory details and operating rules. Write one executable need per
+   clause. Describe Scene as data: “held = white ball; confirmed = gold; mine =
+   gold ring; empty capacity = empty pegs.” List phone, wall, signed-in staff,
+   customer AI and owner AI with their addresses and actions. Record what is
+   simulated, evidence viewports and who reviewed it. Local review is not independent.
+2. **Make records visible.** Give each meaningful record an object, each state a
+   material, and the visitor's object a clear marker. Arrivals pop and chime;
+   outcomes become bags, cups or flags. Empty capacity can be negative space.
+3. **Spend geometry where it reads.** Use one layout curve for paths, trees and
+   objects. Add a gradient sky shader and sun, fog matching the horizon, terrain
+   vertex colours by zone, and seeded low-poly local vegetation. Animate water
+   and a flag in vertex shaders; avoid recomputing a large mesh's normals every
+   frame. Ease role-specific cameras with `1 - Math.exp(-dt * 4)`. Cap pixel
+   ratio on phones, pause hidden frames, respect reduced motion. Generate a
+   filtered noise ambient bed after the first sound opt-in; its gain follows the
+   scene. Compose a share card from the live scene and actual outcome.
+4. **One set of rules.** Put validation and transitions in `domain.ts`; the view
+   may preview them, but a `defineTool` handler decides and saves. Screens call
+   `createAppTools().call`, AIs call the same definition over MCP. Use strict
+   schemas, bounded inputs, versioned writes with revalidation on conflict, and
+   a caller-generated request ID. A repeated ID with different data is refused.
+   Do not rebuild the operation with browser record writes or a custom route.
+5. **Plan the AI's whole visit.** Provide `place_info` (“Call this first”: rules,
+   availability, prices, notice), `place_book` (all choices in one call, bounded
+   enums from config, a private management credential and a `next` sentence),
+   and `place_booking` (owner-authorized lookup/change/cancel). Never expose
+   management credentials in public records. Owner tools read an outbox, mark
+   messages sent, consume event feeds, and repeat next month by a calendar rule.
+   Homie composes; the owner's AI sends through its own connector. A repeat
+   invites past visitors; it never silently enrols them.
+6. **Operate from one config.** Put the place's IANA zone, schedule rule, capacity,
+   prices, add-ons and notice in one config. Derive UI, tools and `shop.json` from
+   it during build. Do not maintain a second price list. Model holds → confirm →
+   scheduled release, with fixed spot IDs and version checks on reuse. Group
+   allocation must be atomic, never a loop that reports partial success. Use the
+   toolkit's booking capacity for paid inventory. HANDOVER.md says what runs
+   where, the monthly rhythm, how to connect an AI, what to do when the owner
+   leaves, and which integrations are still unproven.
+
+## Small working boundaries
+
+The examples use the installed toolkit's exports. Declare `reserve` in `tools/`;
+this small example reserves one whole slot for a signed-in account. Keep the
+public collection a projection without account IDs or secrets. A production
+paid slot uses the shop booking system, not a second ledger.
+
+```ts
+import { defineTool } from '@homie-rocks/studio/tools';
+export default defineTool<{ slot: string; request: string }>({
+  name: 'reserve', description: 'Reserve one slot; repeat the same request safely.',
+  audience: 'signed-in',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['slot', 'request'],
+    properties: {
+      slot: { type: 'string', enum: ['morning', 'afternoon'] },
+      request: { type: 'string', pattern: '^[a-f0-9]{32}$' }
+    }
+  },
+  async handler(input, ctx) {
+    const owner = ctx.caller.id;
+    const key = 'slot:' + input.slot;
+    const old = await ctx.database.getVersioned(key);
+    if (old) {
+      const saved = old.value as { owner: string; request: string };
+      if (saved.owner === owner && saved.request === input.request) return { booked: true };
+      return { booked: false, next: 'That slot is full. No place has been taken.' };
+    }
+    const result = await ctx.database.put(key, { owner, request: input.request }, { version: 0 });
+    return { booked: result.ok, next: result.ok ? 'Your place is reserved.' : 'That slot filled. Choose another.' };
+  }
+});
+```
+
+```ts
+import { createAppTools, createAppContext, createAppRecords } from '@homie-rocks/studio/apps';
+const tools = createAppTools();
+const context = createAppContext();
+const self = await context.ready; // self.url is public; it contains no private access link
+const records = createAppRecords<{ status: string }>({ collection: 'spots' });
+const refresh = async () => {
+  const rows = await records.list();
+  document.querySelector('output')!.textContent = `${rows.length} places · ${self.url}`;
+};
+const stop = records.subscribe(() => { void refresh(); });
+await refresh();
+// In the visitor's click handler, preserve request across network retries:
+const request = crypto.randomUUID().replaceAll('-', '');
+await tools.call('reserve', { slot: 'morning', request });
+// On unmount: stop(); records.dispose(); context.dispose(); tools.dispose();
+```
+
+Build the controls first: an area menu is the primary navigation, and tapping a
+3D object selects the same area. Catch renderer creation failure and context loss;
+keep every booking/control usable without WebGL. Refusals are human sentences
+that say what happened. Prove refusals by bypassing disabled controls, race two
+browsers for the last seat, reload and restart, and run with WebGL unavailable.
+Document the exact commands and results; an empty assertion list is not proof.
+
+## Do not teach the mistakes
+
+- No booking codes in public collections or anonymous edits of arbitrary bookings.
+  Bind tickets to their account/seat, or verify a secret only the booker holds.
+- No public staff console. Use a signed-in role and check it on the server.
+  Label an intentionally public simulator in both UI and Codex.
+- Never interpolate visitor text into `innerHTML`: a stored XSS reached a staff
+  tablet in the study. Use `textContent` for names, contacts, notices and outbox text.
+- Never issue an “official receipt” for an unpaid donation. Record a pledge as a
+  pledge; count a paid gift only after a verified, deduplicated `order.paid` event,
+  with the gift's ID as its reference.
+- No fixed UTC offsets or one hard-coded event date. Use IANA zones and recurring
+  calendar rules; carry the same occurrence into site copy and all screens.
+- No sleep-and-retry event arrays or staff-device cron jobs. Use durable functions,
+  version checks, declared feeds and the server scheduler.
+- No live-only assets. Commit every asset the site serves, with its provenance,
+  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

@@ -6,6 +6,9 @@ compatibility: Node 22 and Chrome; the studio's pinned toolkit and Wrangler.
 
 # Make an app
 
+For place-based builds, read [the six-build patterns](../app/PLACES.md): owner words to needs, records as objects, a local scene and ambience, one trusted operation for screens and AI, graceful graphics, and adversarial proof. Apply the same authority and honest-evidence rules to game economies and tickets.
+
+
 For the installed version’s payment, records and local-check contracts, start with
 `node_modules/@homie-rocks/studio/apps/APPS.md`. Its “Real Stripe test checkout on
 this computer” section is the supported offline-hosting path: real Stripe test

package/guides/game/SKILL.md

@@ -25,6 +25,9 @@ cover, doors and platforms, use declared entity `collider` state and movement's
 
 # Make a game
 
+For place-based builds, read [the six-build patterns](../app/PLACES.md): owner words to needs, records as objects, a local scene and ambience, one trusted operation for screens and AI, graceful graphics, and adversarial proof. Apply the same authority and honest-evidence rules to game economies and tickets.
+
+
 You are in a Homie studio when the folder (or one above it) has `studio.json`. If there
 is none, use the `studio-setup` skill first.