@homie-rocks/studio 0.51.2 → 0.51.4

package/CHANGELOG.md

@@ -17,6 +17,47 @@ 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.4] - 2026-10-14
+
+**Plugin 0.51.4** · Studio events through experimental MCP Events.
+
+Your studio’s declared events reach supporting AI clients through experimental MCP polling, SSE streams and signed webhooks.
+
+### Added
+
+- Every declared studio feed speaks the Triggers & Events draft: role-filtered `events/list`, cursor/replay polling, SSE push with heartbeat and resume, and authenticated webhook subscribe/refresh/unsubscribe with negotiated TTLs and client-supplied Standard Webhooks secrets.
+- Extension and configured webhooks share the durable delivery engine. Owners can see retries and errors; rotation dual-signs for five minutes. Existing resource subscriptions and cursor tools keep working.
+- Servers, app and office guides explain subscription setup and Cloudflare's own Workers Issues events through the person's existing Cloudflare connection.
+
+### Upgrade notes
+
+- Experimental wire format tracks the working-group draft as inspected on 2026-10-14. Declare exact trusted HTTPS callback URLs in each feed's `receivers` array for extension webhooks. Workers fetch cannot pin DNS with original TLS SNI, so arbitrary callbacks are refused; the guide documents this draft limitation. Poll and push need no callback setup.
+
+## [0.51.3] - 2026-10-14
+
+**Plugin 0.51.3**
+
+Business and cause apps use their own words, count every paid monthly gift, and test real Stripe checkout locally.
+
+### Added
+
+- Local real Stripe test checkout: `shop connect --local --profile <sandbox> --url <Wi-Fi address>` syncs test Payment Links without Cloudflare or a public webhook. Stripe CLI forwards signed events to `dev`; phones return to the same Wi-Fi thank-you page.
+- App acceptance needs can name a checkout popup, interact with it, and continue asserting the original phone.
+
+### Fixed
+
+- Monthly subscription invoices create deduplicated paid orders and app events with the original reference, so every gift reaches fulfilment.
+- Business/cause menus name their own pages and apps. App shells use app names, website buttons have independent wording, thank-you pages name the organisation, and default phone sharing stays above bottom tabs.
+- Gathering is a task check-in starter with its own records and no giving or quiz workflow. App style defaults use illustration and AI refinements retain AI attribution.
+- `dev` loads root `.dev.vars`. App collections no longer stop accepting records at 1,000.
+- Requests and scheduled runs remove referral metadata recreated by an old Worker during a rolling deployment.
+- The installed app reference documents the supported local payment/checker path and distinguishes local MCP tools from hosted connector tools.
+
+### Upgrade notes
+
+- Restart local dev after updating `.dev.vars`. Local Stripe links are test-only; live connection and deployment are unchanged.
+- Existing app `screen.share` choices and authored site headers remain in control. Subscription renewals now emit `order.paid` as well as lifecycle events; fulfilment listening to both should deduplicate by payment identity.
+
 ## [0.51.2] - 2026-10-14
 
 **Plugin 0.51.2** · Deploying and listing do what the studio chose, under one address.

package/app-starters/gathering/app.json

@@ -39,14 +39,8 @@
     "many": "people",
     "action": "Check in",
     "total": "Check-ins",
-    "choice": "Choose an option",
-    "monthly": "Gift frequency",
-    "once": "One time",
-    "month": "Monthly",
-    "give": "Give securely on Stripe",
-    "goal": "Intention goal \u00b7 not payments received",
+    "choice": "Choose a task",
     "prompt": "Choose what works for you.",
-    "finished": "All three answers are in. Thank you!",
     "complete": "Mark complete",
     "done": "Complete",
     "pending": "Checked in",
@@ -68,14 +62,6 @@
             "type": "string",
             "required": true,
             "maxLength": 60
-          },
-          "amount": {
-            "type": "number",
-            "required": true
-          },
-          "monthly": {
-            "type": "boolean",
-            "required": true
           }
         }
       }
@@ -129,34 +115,6 @@
       "Packing",
       "Deliveries"
     ],
-    "color": "#184b43",
-    "currency": "CAD",
-    "goal": 2500,
-    "questions": [
-      {
-        "text": "Which planet is called the red planet?",
-        "choices": [
-          "Venus",
-          "Mars",
-          "Jupiter"
-        ]
-      },
-      {
-        "text": "How many sides does a hexagon have?",
-        "choices": [
-          "5",
-          "6",
-          "8"
-        ]
-      },
-      {
-        "text": "Which is a mammal?",
-        "choices": [
-          "Dolphin",
-          "Trout",
-          "Octopus"
-        ]
-      }
-    ]
+    "color": "#184b43"
   }
 }

package/app-starters/gathering/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}}
-</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>
+</style><main><header><span id="connection"></span><h1></h1><p id="intro"></p><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><button data-action></button></div><p id="status" role="status"></p></section></main><script type="module" src="./assets/main.js"></script></html>

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

@@ -3,7 +3,7 @@ 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 };
+type Entry = { choice: string; status: string };
 const room = openRoom<typeof rules>();
 const net = room.net;
 const role = net.params.role ?? 'customer';
@@ -11,41 +11,29 @@ const words: Record<string, string> = app.words;
 const config = app.starter;
 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;
+let rows: AppRecord<Entry>[] = [], busy = false, ready = false;
 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;
+ const list = 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;
+ $('#prompt').textContent = words.prompt;
 }
 choices();
 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 : ''}`;
+  li.textContent = `${row.data.choice} · ${row.data.status}`;
   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);
@@ -61,9 +49,8 @@ action.onclick = async () => {
  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());
+  await records.create({ choice, status: words.pending }, 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(); }

package/apps/APPS.md

@@ -18,7 +18,7 @@ await queue.remove(rows[0]);
 queue.dispose();
 ```
 
-The shell handles requests only from its own frame and uses its own role, link and account, never authority claimed by the message. The Worker checks every request. Roles declare `signIn: boolean` and `can: ["read:queue", "create:queue", "update:queue", "delete:queue"]`. Collections declare fields with `type` (string/number/boolean), optional `required`, `maxLength`, `enum`, and `initial` (the only value allowed on create). Unknown fields are refused. Records are at most 8 KB, collection reads at most 1,000 records, request bodies at most 12 KB. A full collection refuses creates. This is a small operational helper, not an unbounded ledger.
+The shell handles requests only from its own frame and uses its own role, link and account, never authority claimed by the message. The Worker checks every request. Roles declare `signIn: boolean` and `can: ["read:queue", "create:queue", "update:queue", "delete:queue"]`. Collections declare fields with `type` (string/number/boolean), optional `required`, `maxLength`, `enum`, and `initial` (the only value allowed on create). Unknown fields are refused. Records are at most 8 KB and request bodies at most 12 KB. Homie imposes no collection count limit; the studio’s database capacity applies.
 
 Generate a fresh ID for every new record; never reuse a deleted ID. Updates and deletes compare `version` atomically. Conflicts return 409; reload and resolve them. A successful write is committed before acknowledgement. Records are scoped by app and collection, not by room. Deleting a room does not delete records. With `records.persist: false`, use netplay keyed state for transient data instead. Database failures are visible and never replaced with fabricated local success.
 
@@ -127,3 +127,57 @@ 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.
+
+## Real Stripe test checkout on this computer
+
+Use the installed toolkit's app guide and this reference for its exact version.
+The local toolkit MCP exposes `parts_find`; the hosted directory connector may not.
+With a shell, `homie-studio parts find "giving"` is the supported equivalent. Read a
+part's contract: a pledge-only example is not payment fulfilment. The giving starter
+uses the shop bridge; `shop.catalog()` is available in this version. Field names
+start with a lowercase letter and continue with lowercase letters, digits or `_`.
+
+No public HTTPS address or Cloudflare account is needed for local Stripe test
+payments. Use the owner's existing Stripe CLI sandbox profile; log in only when
+that profile is unavailable or expired. Never create an imitation checkout.
+
+1. Create the app and `shop init --giving --currency CAD` (choose the actual currency).
+2. Choose the computer's Wi-Fi address and a fixed dev port. Run
+   `homie-studio shop connect --local --profile <sandbox-profile> --url http://192.168.1.8:8787`.
+   This syncs real test Products, Prices and Payment Links through Stripe CLI and
+   saves local bindings in the project's `.dev.vars`; it does not deploy or create
+   a public webhook. Local products use a separate identity from deployed products.
+3. Run `stripe --project-name <sandbox-profile> listen --all-snapshot --forward-to http://localhost:8787/api/shop/hook`.
+   Put its signing secret in root `.dev.vars` as `STRIPE_WEBHOOK_SECRET=whsec_…`.
+   Keep that listener running. Never commit the secrets file or print its contents.
+4. Run `homie-studio dev --lan --port 8787`. Dev loads root `.dev.vars` beside its
+   generated Wrangler configuration. Restart after changing bindings. If dev reports
+   another port, update the listener and repeat local shop connection with that port.
+5. Open **the same Wi-Fi address** on desktop and phones. Checkout returns there,
+   so its guest cookie and thank-you page work on both. Localhost is only suitable
+   when every browser is on this computer. Use Stripe's test card; verify the signed
+   webhook, paid order and app record before reporting success.
+
+The first Checkout emits `order.paid`. Later paid subscription-cycle invoices each
+create a distinct paid order and emit `order.paid` with the original app and reference.
+Invoice retries do not count again; the initial invoice does not duplicate Checkout.
+Keep fulfilment idempotent by order/event ID. Subscription lifecycle events remain
+available separately. Failed invoices never create paid gifts.
+
+`check` uses isolated records on localhost by default; `--no-isolate` opts into the
+existing records. Stripe webhooks use the ordinary local database, so for a real
+payment acceptance run use a disposable studio and `check --no-isolate`. Test money
+must not be mistaken for live giving. Named staff/tablet/kiosk surfaces and roles
+are supported; only the surfaces named by each need are asserted.
+
+For a Give button opening a new tab, name its popup in the click step:
+
+```json
+{"surface":"phone","selector":"[data-give]","click":true,"popup":"checkout"}
+```
+
+Later steps and assertions can use `"surface":"checkout"` for the provider page.
+The phone remains its own surface; assert its confirmed gift after checkout. The
+checker brings each page forward before reading or capturing it. Use the real
+provider's controls, never a test-only app action. App sharing defaults to the top
+right, clear of bottom tabs; `screen.share` remains an author-controlled override.

package/bin/homie-studio.mjs

@@ -846,7 +846,7 @@ const OUTWARD_FLAGS = {
   'chat remove': ['url', 'all'], 'chat budget': ['url'],
   'servers close': ['url', 'reopen'], 'servers level': ['url'], 'servers member': ['url', 'role', 'remove'],
   'parts reissue': ['claim-hash', 'receipt-verified', 'buyer'], 'parts retire': [], 'parts keys': [], 'parts refund': ['game'],
-  'shop connect': ['url', 'managed', 'live', 'manual', 'renew', 'from-clipboard'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note', 'manual-transaction'],
+  'shop connect': ['local', 'profile', 'url', 'managed', 'live', 'manual', 'renew', 'from-clipboard'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note', 'manual-transaction'],
   'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
   'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
   'events webhook': ['url','after'],
@@ -1115,6 +1115,10 @@ async function main() {
     if (!sub) return shopStatus(root, { url });
     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 === 'check') return shopCheck(root);
+    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 === 'disconnect') return shopDisconnect(root);
     if (sub === 'catalog') {

package/docs/mcp-events.md

@@ -0,0 +1,68 @@
+# Experimental MCP Events
+
+Studio MCP implements the [Triggers & Events working group's design sketch](https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/13e0a59749cde947374aaa8e3a65f0b424468d5a/docs/design-sketch-proposal.md) as inspected on 2026-10-14. This is an experimental draft, not an adopted MCP standard. Method names, envelopes, schemas, metadata keys and provisional error codes live in `worker/mcp-events-wire.mjs` so draft changes have one wire-format boundary. The studio's existing `resources/subscribe`, event resources and cursor-read tool continue to work.
+
+Declare feeds in `studio.json` under `mcp.events`. Each map key is the extension's event `name`. For example:
+
+```json
+{
+  "mcp": {
+    "events": {
+      "bookings": {
+        "event": "record.changed",
+        "app": "cafe",
+        "collection": "bookings",
+        "audience": { "app": "cafe", "role": "staff" },
+        "receivers": ["https://your-ai-receiver.example/hooks/studio"]
+      }
+    }
+  }
+}
+```
+
+`receivers` is an owner-controlled list of exact HTTPS callback URLs, without credentials or fragments. Include only endpoints whose operators have agreed to receive events. A feed's existing configured `webhook.url` is also accepted. Rebuild and deploy the declaration through the studio's usual authorized workflow. Poll and push need no receiver declaration. `maxSubscriptions`, when explicitly declared on a feed, limits its active extension webhooks; otherwise there is no subscription quota. Event arguments are currently `{}`: the declared feed already supplies the app, collection and audience filter.
+
+## An owner's AI connects and subscribes
+
+1. Use an MCP Events-capable client and connect to `<studio-site>/mcp/auth`. Approve with the person's existing studio account in the browser. Staff approve their own account. Do not request an office key. Initialization advertises `capabilities.events.listChanged: true`.
+2. Call `events/list`. It returns only feeds the current account can read, with `delivery: ["poll", "push", "webhook"]`, input and payload schemas. Re-list when the general MCP GET channel receives `notifications/events/list_changed`.
+3. Choose a delivery mode. These are protocol requests made by the client/SDK, not model-visible tool calls:
+   - **Poll:** call `events/poll` with `{ "name": "bookings", "arguments": {}, "cursor": null }`. The first call returns no history and a cursor at now. Persist each returned cursor and pass it on the next poll. Drain `hasMore: true` immediately; otherwise wait `nextPollMs`. Optional `maxEvents` caps a page (server maximum 100); `maxAgeMs` bounds replay.
+   - **Push:** POST `events/stream` with a JSON-RPC request ID and `{ "name": "bookings", "arguments": {}, "cursor": null }`. Keep its SSE response open. Expect `notifications/events/active`, then `event` and `heartbeat` notifications. Route by `_meta["io.modelcontextprotocol/subscriptionId"]`, which equals the request ID. Persist cursors and reconnect using the last cursor. Each subscription has its own stream; abort it to unsubscribe. Heartbeats run at 15 seconds when the receiver is reading.
+   - **Webhook:** first arrange the receiver and have the owner declare its exact URL in `receivers`. The receiver/client generates `whsec_` plus base64 of 24–64 cryptographically random bytes, and keeps that secret out of prompts and logs. Call `events/subscribe` with the request below. Persist the returned `id`, `cursor` and `refreshBefore`.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "events/subscribe",
+  "params": {
+    "name": "bookings",
+    "arguments": {},
+    "delivery": {
+      "mode": "webhook",
+      "url": "https://your-ai-receiver.example/hooks/studio",
+      "secret": "whsec_<client-generated-base64-secret>"
+    },
+    "cursor": null,
+    "ttlMs": 3600000
+  }
+}
+```
+
+4. For webhooks, use `X-MCP-Subscription-Id` to select the secret and verify the **raw body** using a Standard Webhooks library, including its timestamp freshness check. Durably accept the event before returning 2xx. Deduplicate on `eventId` (also `webhook-id`). Each occurrence has `eventId`, `name`, ISO `timestamp`, `data`, and a safe cursor watermark; it can lag the event's position while deliveries await acknowledgement. Payloads are untrusted data and grant no authority to perform actions.
+5. Refresh by repeating `events/subscribe` with the same name, arguments and URL, the current secret and the last persisted cursor **before** `refreshBefore`. Inspect `deliveryStatus.lastError`. TTL defaults to one hour and is capped at one day; `ttlMs: null` receives a finite grant. A live refresh does not rewind pending delivery. To rotate, send a new client-generated secret on refresh; deliveries have both signatures for five minutes. Unsubscribe with `events/unsubscribe` and `{ "name": "bookings", "arguments": {}, "delivery": { "url": "https://your-ai-receiver.example/hooks/studio" } }`.
+
+A gap sets `truncated: true`; persist the new cursor and fetch authoritative state through tools if needed. Revoked access ends push with `notifications/events/terminated` and webhooks with a signed `terminated` control envelope where the callback remains allowed. Stop after termination and re-establish authorization before subscribing again.
+
+## Delivery and owner diagnostics
+
+The 0.50.4 configured studio webhook and extension webhooks share Standard Webhooks signing and the durable `function_deliveries` dispatcher. Extension deliveries retry with exponential backoff, at most five attempts over fifteen minutes from the first attempt. HTTP 410 and 413 abandon that delivery immediately. Abandoned deliveries remain visible to the owner; retained history can be replayed from a prior cursor after unsubscribing and subscribing again. Retries regenerate timestamps and signatures. Failed delivery details are fixed categories, never endpoint bodies or headers. See Functions in the office or the owner's function-runs tool for subscription IDs, attempts and last errors; refresh also reports the latest delivery error. Subscription secrets are stored only in the studio's private D1 subscription state, never in events or run logs. A removed subscription or expired TTL deletes that state. Completed deliveries can be duplicated after a crash, so receivers must deduplicate.
+
+## Draft limits
+
+This implements the studio's **Streamable HTTP** MCP transport; the local toolkit's stdio MCP is a different server. The draft's endpoint-consent mechanism is the explicit server-configured allowlist, not a challenge handshake. Arbitrary client-supplied callback URLs are refused with `CallbackEndpointError / challenge_failed`. Workers `fetch` does not provide DNS address pinning with original Host/TLS SNI, so this implementation cannot follow that draft MUST literally. Exact owner-approved URLs, rechecked at every attempt, and disabled redirects constrain the destination; this is not a claim of draft-complete DNS-rebinding protection. Only approve trusted receiver operators. No no-expiry grants or asymmetric server signatures are offered. Durable queue positions survive Worker restarts, extending the sketch's ephemeral in-flight bookkeeping while preserving client-owned replay cursors. A webhook's conservative safe watermark may lag the event being delivered by one event.
+
+## Production failures from Cloudflare
+
+An owner's AI can also subscribe through the person's **existing Cloudflare connection** to Cloudflare's own API MCP at `https://mcp.cloudflare.com/mcp`: discover `cloudflare.alert.workers_observability_real_time_issue` with `events/list`, then use `events/subscribe` with that descriptor's arguments scoped to the studio's Worker and the client's webhook. Enable Workers Issues on that Worker and grant **Notifications Write** and **Workers Observability Write**. Cloudflare posts signed events for new or recurring production issues, so reliability problems reach the AI without polling. Homie hosts nothing for this connection. See [Cloudflare's 2026-10-13 announcement](https://developers.cloudflare.com/changelog/post/2026-10-13-cloudflare-mcp-events/).

package/guides/app/SKILL.md

@@ -6,6 +6,12 @@ compatibility: Node 22 and Chrome; the studio's pinned toolkit and Wrangler.
 
 # Make an app
 
+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
+checkout, CLI webhook forwarding, root `.dev.vars`, Wi-Fi return pages and named
+checkout popups. Use an existing approved sandbox profile; no deploy is needed.
+
 An app is **one screen, its roles, and its parts**. The screen transforms with the person and the work: a camera moves, a ticket unfolds, controls appear in context. Do not build page-to-page navigation, a sidebar of links, or a conventional admin website inside it. A studio's public website can still have pages around the app.
 
 Read the person's brief and existing `apps/<id>/` first. Choose sensible engineering defaults from the brief; never ask the person how to implement shared state. A business or cause needs no game demo, mandatory entertainment, invented customers, scores or rounds. Never impose a shop, directory listing, sign-in for public visitors, or paid media. Make the fewest human steps possible; run commands yourself.
@@ -38,7 +44,7 @@ Before writing scene components:
 
 1. Run `style init <id> --prompt "<the person's own scene words>"`. Record the direction in the Codex: composition, camera, materials, colour, typography and motion. Use the same style machinery as games, not the starter's default theme.
 2. Inspect the installed `@homie-rocks/*` packages for mechanisms. `geom`, `props`, `render`, `camera`, `postfx` and `fx` can make the place; `input`, `ui`, `ui-world`, `device`, `audio` and `loop` make it usable. Read the package exports and examples rather than guessing imports. Install every dependency reported by the starter or parts before building.
-3. Search `parts_find` for each meaningful piece; shell equivalent: `homie-studio parts find "<piece>"`. Read its contract, source studio and licence. Add fitting pieces with `part_add` / `parts add`; write the missing parts yourself. The example studios share real app pieces: search for venue, workshop, giving, arrivals, scene, queue and sound, not just game characters. If local example studios are available, read their shared `parts/` and manifests without modifying the source studios. A failed catalogue request is not proof that nothing exists.
+3. Search the local toolkit MCP `parts_find` for each meaningful piece (the hosted connector may not expose it); shell equivalent: `homie-studio parts find "<piece>"`. Read its contract, source studio and licence. Add fitting pieces with `part_add` / `parts add`; write the missing parts yourself. The example studios share real app pieces: search for venue, workshop, giving, arrivals, scene, queue and sound, not just game characters. If local example studios are available, read their shared `parts/` and manifests without modifying the source studios. A failed catalogue request is not proof that nothing exists.
 4. Use the art/models/sound/music skills with connected providers and an authorized budget. Generate distinctive assets when useful. If no provider is connected, continue with original geometry, locally drawn SVG, CC0 assets and local synthesized sound. Report the means honestly. Provider absence never justifies replacing the scene with a board.
 5. Record packages, parts with attribution, original work and media routes under **Built from**. Keep costs and provenance visible.
 
@@ -124,7 +130,7 @@ Without Stripe, keep real services and prices visible and say payment is not con
 - `apps/<id>/app.json` describes roles (`signIn`, `can`), surfaces (`phone`, `wall`, `kiosk`, `tablet`), wording, record collections, parts and the real UI action used by check. The app's entry and assets live beside it, just like a game.
 - Before inventing each component, inspect engine packages for the mechanism and `parts_find` for the piece. A queue, quiz, menu board, live total, music loop or video intro can be a part. Record its licence and credit. Sharing happens only when requested; selling parts is not part of this workflow.
 - Use the same engine packages as a game: `@homie-rocks/geom` and `props` for original scenery; `render`, `camera`, `postfx`, `fx` for light, composition and motion; `input`, `ui`, `ui-world`, `audio`, `device`, `loop` for interaction and feel. An app can be fully 3D and wild. Legibility and the actual task come first.
-- Use the `style`, `art`, `models`, `animate`, `sound`, `music`, `video` and `perf` skills where they help. It should look like a game studio made it: a coherent world with a useful HUD, not generic cards and navigation. Media cost and licensing decisions remain the person's.
+- Use the `style`, `art`, `models`, `animate`, `sound`, `music`, `video` and `perf` skills where they help. Give the organisation a coherent scene with readable controls and purposeful motion. Media cost and licensing decisions remain the person's.
 - Keep native buttons at least 44 px, keyboard focus visible, text as text, motion reducible, and the wall QR clear of useful information. Pointer gesture guards belong on the canvas, not native click buttons.
 
 ## Roles and records
@@ -282,3 +288,27 @@ Upgrade compares copied app presets with recorded toolkit versions. Unchanged
 preset files and default values take the new version; custom scene files, names and
 edited labels remain the studio’s. An app wall uses its join label rather than game
 instructions. Rebuild after upgrade and inspect both the wall and giving page.
+
+## Experimental MCP Events
+
+For an owner's AI that should hear a studio's declared events, read
+`node_modules/@homie-rocks/studio/docs/mcp-events.md`. Connect the client to
+`<site>/mcp/auth` through the person's existing studio approval, discover feeds
+with `events/list`, and use `events/poll`, an SSE `events/stream`, or
+`events/subscribe` with a client-generated `whsec_` secret and an exact
+owner-declared `mcp.events.<feed>.receivers` URL. Refresh before `refreshBefore`,
+persist cursors, verify Standard Webhooks signatures, deduplicate event IDs, and
+use `events/unsubscribe` to stop a webhook. The feeds keep their current roles;
+resources/subscribe and the cursor tool still work. This follows the experimental
+Triggers & Events working-group draft, with the Workers DNS-pinning limitation
+and receiver allowlist explained in that guide. Inspect Functions in the office
+and refresh's `deliveryStatus` for failed deliveries; never put secrets in logs.
+
+For production failures, the owner's AI can also use the person's existing
+Cloudflare connection to `https://mcp.cloudflare.com/mcp`, discover
+`cloudflare.alert.workers_observability_real_time_issue` with `events/list`, and
+subscribe with `events/subscribe` scoped to the studio's Worker. Enable Workers
+Issues and grant Notifications Write and Workers Observability Write. Cloudflare
+posts signed events to the client's webhook so new or recurring reliability
+problems reach the AI without polling; Homie hosts nothing for this. See
+[Cloudflare's announcement](https://developers.cloudflare.com/changelog/post/2026-10-13-cloudflare-mcp-events/).

package/guides/office/SKILL.md

@@ -156,3 +156,27 @@ in and continues there. A plain link-preview GET spends nothing; the loaded page
 submits the same-origin sign-in form. Keep the link private.
 Local office and role commands reuse the running dev server’s D1 configuration even
 after deploy records the production database id.
+
+## Experimental MCP Events
+
+For an owner's AI that should hear a studio's declared events, read
+`node_modules/@homie-rocks/studio/docs/mcp-events.md`. Connect the client to
+`<site>/mcp/auth` through the person's existing studio approval, discover feeds
+with `events/list`, and use `events/poll`, an SSE `events/stream`, or
+`events/subscribe` with a client-generated `whsec_` secret and an exact
+owner-declared `mcp.events.<feed>.receivers` URL. Refresh before `refreshBefore`,
+persist cursors, verify Standard Webhooks signatures, deduplicate event IDs, and
+use `events/unsubscribe` to stop a webhook. The feeds keep their current roles;
+resources/subscribe and the cursor tool still work. This follows the experimental
+Triggers & Events working-group draft, with the Workers DNS-pinning limitation
+and receiver allowlist explained in that guide. Inspect Functions in the office
+and refresh's `deliveryStatus` for failed deliveries; never put secrets in logs.
+
+For production failures, the owner's AI can also use the person's existing
+Cloudflare connection to `https://mcp.cloudflare.com/mcp`, discover
+`cloudflare.alert.workers_observability_real_time_issue` with `events/list`, and
+subscribe with `events/subscribe` scoped to the studio's Worker. Enable Workers
+Issues and grant Notifications Write and Workers Observability Write. Cloudflare
+posts signed events to the client's webhook so new or recurring reliability
+problems reach the AI without polling; Homie hosts nothing for this. See
+[Cloudflare's announcement](https://developers.cloudflare.com/changelog/post/2026-10-13-cloudflare-mcp-events/).

package/guides/servers/SKILL.md

@@ -157,3 +157,27 @@ For local function and tool proof, run `dev` and use its localhost URL. The priv
 dev credential permits headless owner tool calls; production still uses OAuth.
 App need sessions are scoped to the declared role and fresh records. See the app
 and functions guides for tablet/kiosk proof and atomic function storage.
+
+## Experimental MCP Events
+
+For an owner's AI that should hear a studio's declared events, read
+`node_modules/@homie-rocks/studio/docs/mcp-events.md`. Connect the client to
+`<site>/mcp/auth` through the person's existing studio approval, discover feeds
+with `events/list`, and use `events/poll`, an SSE `events/stream`, or
+`events/subscribe` with a client-generated `whsec_` secret and an exact
+owner-declared `mcp.events.<feed>.receivers` URL. Refresh before `refreshBefore`,
+persist cursors, verify Standard Webhooks signatures, deduplicate event IDs, and
+use `events/unsubscribe` to stop a webhook. The feeds keep their current roles;
+resources/subscribe and the cursor tool still work. This follows the experimental
+Triggers & Events working-group draft, with the Workers DNS-pinning limitation
+and receiver allowlist explained in that guide. Inspect Functions in the office
+and refresh's `deliveryStatus` for failed deliveries; never put secrets in logs.
+
+For production failures, the owner's AI can also use the person's existing
+Cloudflare connection to `https://mcp.cloudflare.com/mcp`, discover
+`cloudflare.alert.workers_observability_real_time_issue` with `events/list`, and
+subscribe with `events/subscribe` scoped to the studio's Worker. Enable Workers
+Issues and grant Notifications Write and Workers Observability Write. Cloudflare
+posts signed events to the client's webhook so new or recurring reliability
+problems reach the AI without polling; Homie hosts nothing for this. See
+[Cloudflare's announcement](https://developers.cloudflare.com/changelog/post/2026-10-13-cloudflare-mcp-events/).

package/guides/shop/SKILL.md

@@ -173,3 +173,11 @@ CLI fixture/API tokens; never enter card digits into a page. The local listener
 for development; production sends signed events directly to the studio's webhook.
 The optional keyed fixture remains available for testing explicitly selected session
 checkout. Label offline fixtures simulations.
+
+## Local Stripe test payments
+
+Use `shop connect --local --profile <sandbox-profile> --url http://<Wi-Fi-IP>:8787`
+and Stripe CLI `listen --all-snapshot --forward-to http://localhost:8787/api/shop/hook`. The full
+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.

package/lib/app-needs.mjs

@@ -24,6 +24,8 @@ export function readAppNeeds(root, id) {
 /** 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 () => {} }) {
   const results = [];
+  const appBarrier=ready;
+  ready=async s=>{await s.page.bringToFront?.();if(s.external){s.frame=s.page.mainFrame();return;}await appBarrier(s);};
   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; };
   for (const need of plan.needs) {
@@ -33,7 +35,8 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
     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 assertions on its named surfaces');
-      for (const name of names) { const s = surface(name); if (need.role && s.role !== need.role) throw new Error(`${name} requires role ${need.role}, got ${s.role ?? 'unspecified'}`); }
+      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 step of need.steps ?? []) {
         const target=surface(step.surface);
@@ -43,7 +46,19 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
         if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await ready(surface(step.surface)); continue; }
         await waitInApp(target,step.selector,f=>f.waitForSelector(step.selector, { visible: true, timeout:10000 }),{ready});
         const frame=target.frame;
-        if (step.click) await frame.click(step.selector);
+        if (step.click && step.popup) {
+          let listener,timer;
+          const opened=new Promise((resolve,reject)=>{
+            listener=popup=>resolve(popup);page.once('popup',listener);
+            timer=setTimeout(()=>reject(new Error('payment popup did not open')),10000);
+          });
+          try {
+            const [popup]=await Promise.all([opened,frame.click(step.selector)]);
+            surfaces.push({name:step.popup,page:popup,frame:popup.mainFrame(),external:true,role:target.role});
+            await page.bringToFront();
+          } finally {clearTimeout(timer);page.off('popup',listener);}
+        }
+        else if (step.click) {await frame.click(step.selector);await page.bringToFront?.();}
         else if (step.fill !== undefined) { await frame.$eval(step.selector, el => { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }); await frame.type(step.selector, String(step.fill)); }
         else if (step.select !== undefined) await frame.select(step.selector, String(step.select));
         else throw new Error('step needs click, fill, select or reload');

package/lib/app-ready.mjs

@@ -1,5 +1,6 @@
 /** One arrival barrier for baseline proof, needs reloads and rebuilt frames. */
 export async function appReady(surface, {timeout=60000}={}) {
+  await surface.page.bringToFront?.();
   const end=Date.now()+timeout;
   let error;
   do {

package/lib/art-cli.mjs

@@ -151,13 +151,13 @@ export async function styleCommand(root, sub, positional, flags, { log = () => {
   } else if (verb === 'set') {
     if (!args[1] || args[2] === undefined) return { ok: false, command: 'style set', why: `usage: homie-studio style set <id> <decision> <value> (decisions: ${CATALOGUE_IDS.slice(0, 10).join(', ')}, …)` };
     r = setDecision(root, id, args[1], args.slice(2).join(' '), { by: flags.get('by') === 'person' ? 'person' : 'ai', why: flags.get('why') ?? null, words: flags.get('words') ?? null, unlock: flags.has('unlock'), reason: flags.get('reason') ?? null, confirm: flags.has('confirm'), manifest: manifest() });
-  } else if (verb === 'steer') r = steerDecision(root, id, args[1], args.slice(2).join(' ') || String(flags.get('words') ?? ''), { manifest: manifest() });
+  } else if (verb === 'steer') r = steerDecision(root, id, args[1], args.slice(2).join(' ') || String(flags.get('words') ?? ''), { manifest: manifest(), by: flags.get('by') === 'person' ? 'person' : 'ai' });
   else if (verb === 'lock') r = lockDecision(root, id, args[1] ?? 'style', { by: 'person', words: flags.get('words') ?? null });
   else if (verb === 'unlock') r = unlockDecision(root, id, args[1], { reason: flags.get('reason') ?? null, by: 'person' });
   else if (verb === 'board') { const { styleBoard } = await import('./style-board.mjs'); r = await styleBoard(root, id, { prompt: String(flags.get('prompt') ?? ''), log, library: !flags.has('no-library') }); }
   else if (verb === 'pick') {
     const mixes = Object.fromEntries(list(flags.get('mix')).map((x) => x.split('=')).filter(([k, v]) => k && v));
-    r = pickDirection(root, id, args[1] && !args[1].includes('=') ? args[1] : null, { mixes, manifest: manifest() });
+    r = pickDirection(root, id, args[1] && !args[1].includes('=') ? args[1] : null, { mixes, manifest: manifest(), by: flags.get('by') === 'person' ? 'person' : 'ai' });
   } else if (verb === 'mood') { const { recordMood } = await import('./style-board.mjs'); r = await recordMood(root, id, args[1], resolve(String(flags.get('image') ?? '')), { usd: flags.get('usd') ?? null, receipt: flags.get('receipt') ?? null, model: flags.get('model') ?? null }); }
   else if (verb === 'golden') {
     if (args[1] === 'add') { const { addGolden } = await import('./style-board.mjs'); r = await addGolden(root, id, resolve(String(args[2] ?? flags.get('image') ?? '')), { from: flags.get('from') ?? null }); }

package/lib/art-tools.mjs

@@ -223,11 +223,11 @@ export function artToolDefs(ctx, h) {
         const by = a.by === 'person' ? 'person' : 'ai';
         let r; let action;
         try {
-          if (a.pick || a.mix) { action = 'pick'; r = pickDirection(root, game, a.pick ? String(a.pick).toLowerCase() : null, { mixes: a.mix && typeof a.mix === 'object' ? a.mix : {}, manifest }); }
+          if (a.pick || a.mix) { action = 'pick'; r = pickDirection(root, game, a.pick ? String(a.pick).toLowerCase() : null, { mixes: a.mix && typeof a.mix === 'object' ? a.mix : {}, manifest, by }); }
           else if (!a.decision) return fail('name the decision (decision: "style.palette"), or pick a direction (pick: "b")');
           else if (a.lock) { action = 'lock'; r = lockDecision(root, game, a.lock === true ? a.decision : String(a.lock), { by: 'person', words: a.words ?? (by === 'person' ? 'tapped Lock' : null) }); }
           else if (a.unlock && a.value === undefined && a.steer === undefined) { action = 'unlock'; r = unlockDecision(root, game, a.decision, { reason: a.reason ?? null, by: 'person' }); }
-          else if (a.steer) { action = 'steer'; r = steerDecision(root, game, a.decision, String(a.steer), { manifest }); }
+          else if (a.steer) { action = 'steer'; r = steerDecision(root, game, a.decision, String(a.steer), { manifest, by }); }
           else if (a.value !== undefined) { action = 'set'; r = setDecision(root, game, a.decision, a.value, { by, why: null, words: a.words ?? null, unlock: a.unlock === true, reason: a.reason ?? null, confirm: a.confirm === true, manifest }); }
           else return fail('say what to do: value, steer, lock, unlock, pick or mix');
         } catch (error) { return fail(error.message); }

package/lib/check.mjs

@@ -387,6 +387,7 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
     for(const name of ['wall','phone','phone-two'])await openSurface(name);
     const textOf = (f) => f.$eval(proof.observe, (e) => e.textContent);
     const actor = surfaces[1];
+    await appReady(actor);
     await waitInApp(actor,proof.action,f=>f.waitForFunction((selector) => { const el = document.querySelector(selector); return el && !el.disabled && !el.hidden; }, {}, proof.action));
     before = await waitInApp(actor,proof.observe,textOf);
     await actor.frame.click(proof.action);
@@ -406,6 +407,7 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
     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 [...(need.steps??[]),...(need.assertions??[])]) {
+      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);
     }