@homie-rocks/studio 0.51.3 → 0.51.5

package/CHANGELOG.md

@@ -17,6 +17,51 @@ 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.5] - 2026-10-14
+
+**Plugin 0.51.5**
+
+Connect your shop and media through official plugins, keep renewals and free bookings working, and see progress while you build.
+
+### Added
+
+- **Shop setup:** Stripe's official plugin can configure and verify products, prices, item and menu links, paid bookings, monthly giving and the customer portal. Homie plans only the changes your shop needs. No API keys are requested; webhook installation checks the Stripe account and passes the signing secret privately to Wrangler, never through the model. Local webhook forwarding keeps its secret private too.
+- **Build iteration:** Builds report progress, including during JSON output, and show a heartbeat while generated rules play. `build --quick` keeps type and guard checks while skipping play and snapshot smoke checks.
+- **Media placement:** `media import` places completed media, checks scene references and records file hashes, rights, provenance and explicit cost status. Video guidance and local processing tools now ship with the toolkit.
+
+### Changed
+
+- **Official media connections:** Art, models, music, sound, video and style use the official fal and ElevenLabs plugins in your AI client. Homie still handles art direction, local processing, placement and provenance. Its own provider generation clients, key-file readers and Stripe Projects credential bridge have been removed.
+- **Connection setup:** Setup reports official connections verified in the current session and explains browser sign-in. Cloudflare inspection uses its official MCP; deployment continues through Wrangler's browser login.
+
+### Fixed
+
+- **Recurring gifts and memberships:** Each renewal reaches your shop and notifies apps once, even when the studio also sells parts. Renewals keep the original purchase reference so apps can identify the cause or member. Subscription updates and cancellations reach the shop; parts payments retain their own route.
+- **Free volunteer shifts and services:** Free bookings in a mixed free/paid app work before Stripe is connected. They confirm locally and enforce capacity; paid checkout still requires a connection.
+
+### Upgrade notes
+
+- Update the toolkit and Homie plugin together, run upgrade, and connect the official provider plugins in your AI client. Existing media remains usable. Upgrade replaces retired credential instructions without reading or migrating old key files. Available ElevenLabs media capabilities depend on the connected server and are checked before generation.
+- Shop setup starts with `stripe_shop_plan` / `shop plan`, then `stripe_webhook` / `shop webhook`. Private webhook setup may need a separate Stripe CLI browser approval. `shop connect` remains the full CLI alternative; `shop listen` forwards local events privately.
+- Run a full build before release, even if you used `build --quick` while iterating.
+- Remove any temporary subscription-routing postinstall workaround for 0.51.3–0.51.4 after upgrading.
+
+## [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**

package/README.md

@@ -513,17 +513,7 @@ npx homie-studio shop                         # open (test or live) or what is m
 npx homie-studio shop refund ord_…            # an ASK: the owner taps once (or Refund in /_studio/office/shop)
 ```
 
-Connect with `stripe_login` or `shop connect`: the owner approves Stripe's official browser page, sandbox first.
-Where the CLI supplies a transferable legacy test key, the toolkit creates the webhook and installs both Worker
-secrets privately. It reports the 90-day expiry; `shop connect --renew` obtains approval again. Current CLI OAuth
-and live mode cannot export an independent Worker's key, so the result names that limitation. Only if the owner
-chooses the fallback does `shop connect --manual` open the old local key page (`--manual --live` for live mode).
-Never request a key in chat. Login is not a verified purchase; complete the test purchase, webhook and refund check.
-
-Stripe's optional agent tools (`stripe agent setup`) provide MCP and skills for catalog work (`shop catalog`),
-tax reads and sales questions. They are separate from the Worker's credentials. Never create a webhook through
-MCP because its response contains a secret. From 2026-10-31 Stripe MCP accepts only OAuth or Agent-tagged keys;
-that change does not affect the shop's ordinary restricted API key. [SHOP.md](shop/SHOP.md) describes the flow.
+Connect through Stripe’s official OAuth plugin: `stripe_shop_plan` gives exact catalog, menu, booking and recurring operations for Stripe MCP and verifies its fresh reads. `stripe_webhook` privately installs the signing secret using one separate Stripe CLI browser approval if needed. No owner handles a key. `shop connect` remains the CLI alternative. [SHOP.md](shop/SHOP.md) describes the flow.
 
 In a game: `createShop()` from `@homie-rocks/studio/shop` (`has`, `entitlements`, `on('change')`, `open`, `used`, `add`, `checkout`, `buy`); a
 supporter's badge rides on their seat (`peer.badge`). Stripe Checkout (hosted), optional Stripe Tax, or Stripe Managed
@@ -1185,26 +1175,17 @@ no Wrangler, no rooms, the game alone and offline with its bots) and shoots that
 there (it needs rooms: use `dev` and `--url`). The result names the build the frames are of, by the hash `build`
 printed and the hashed bundle the page loaded.
 
-## Another way to Cloudflare: Stripe Projects (a prototype, 0.24.3)
+## Official media and hosting connections
 
-`npx wrangler login` stays the way. For a creator with no Cloudflare account (and no ElevenLabs), Stripe Projects
-(Stripe's CLI plugin, docs.stripe.com/projects) can make or link both on the person's own Stripe sign-in, on free
-plans, and hand the credentials to the studio folder:
+Connect fal and ElevenLabs through their official plugins in your AI client and approve
+one browser sign-in per provider. Homie never handles their credentials. Cloudflare's
+plugin provides account inspection; deployment keeps pinned Wrangler's own browser login.
+See [connection and upgrade guidance](guides/studio-setup/references/OFFICIAL-MEDIA.md).
 
-```sh
-npx homie-studio setup --via stripe-projects [--with elevenlabs] --dry-run   # what it would do; changes nothing
-npx homie-studio setup --via stripe-projects [--with elevenlabs] --accept-tos  # after the person accepted the providers' terms
-```
-
-It stops with a `needs` step at each thing that is the person's (the Stripe CLI and its Projects plugin, Stripe's
-sign-in, the providers' terms, Cloudflare's own approval page for an existing account); it never adds a paid plan or
-a payment method. The Cloudflare account id goes in studio.json with `"auth": "stripe-projects"`; the token stays in
-Projects' vault and the git-ignored `.env` it syncs, and every Wrangler run in the studio takes it from there
-(`deploy`, `dev`, secrets, the office). It checks read-only what the token can do (Wrangler signed in, D1, Workers AI;
-R2 is optional) and that `.gitignore` keeps `.env`, `.env.*`, `.projects/vault/` and `.projects/cache/` out of git.
-With `--with elevenlabs` the music skill finds the ElevenLabs key there too (ElevenLabs' free plan has no commercial
-licence). Unverified until a real run: the exact JSON of the Projects commands, and the Cloudflare token's permission
-groups, which the checks measure instead of assuming.
+`homie-studio media import --file <download> --receipt <receipt.json> --out <studio-path>
+--used-by <scene-file>` places a completed asset and records its hash, rights, style and
+cost status in `media/provenance.json`. It makes no provider calls. The scene file must
+reference the delivered path; also verify the asset in the running scene.
 
 ## No payment method needed
 

package/apps/APPS.md

@@ -114,7 +114,7 @@ information in a separate private collection. Public roles must not have write
 capabilities for slots or bookings. Staff movement is a versioned record update
 containing only `slot`; confirmation and release follow verified Checkout state.
 The default keyless connection uses one Payment Link per published slot. Call
-`stripe_bookings_sync` after publishing/changing slots. Pending checkout does not
+`stripe_shop_plan` with the complete slot manifest after publishing/changing slots. Pending checkout does not
 block others; payment secures the seat. Use record.booking.full/available/synced
 for slot display. Read SHOP.md for the complete manifest and limitations.
 

package/bin/homie-studio.mjs

@@ -17,9 +17,9 @@
  *   homie-studio app role <id> <role> [--player <account>] [--revoke] [--url <site>]
  *   homie-studio game new <id> [--from gem-rush] [--name "<Game Name>"]
  *   homie-studio games
- *   homie-studio build [<id>] [--maps] [--types] [--long-check]   (--maps: also keep each bundle's source map and
+ *   homie-studio build [<id>] [--maps] [--types] [--long-check] [--quick]   (--maps: also keep each bundle's source map and
  *                                          module sizes in .studio/maps/<id>/, never in site/dist: what `perf` reads a
- *                                          CPU profile through; --types: check the games' TypeScript first, with the
+ *                                          CPU profile through; --quick: skip rules play and smoke checks; --types: check the games' TypeScript first, with the
  *                                          studio's own `typescript`; a type error stops the build; --long-check: play
  *                                          each rules game eight times as long before it is written (a rules game is
  *                                          always type-checked and played; this is more of the same play, for a
@@ -183,10 +183,11 @@
  *   homie-studio shop                     is the studio's shop selling (its own Stripe), and if not, what is missing
  *   homie-studio shop init [--supporter|--giving] [--currency <code>] [--price 500] [--managed]   shop.json and SELLING.md
  *   homie-studio shop check               shop.json against studio settings and provider requirements
- *   homie-studio shop connect [--live] [--renew] [--manual]   sync Payment Links and webhook through Stripe browser approval; --manual chooses the local page for the studio's
- *                                         restricted Stripe key; with it this makes the webhook (0.24.3), and the key
- *                                         and the webhook's secret go straight to the Worker secrets, never a chat or a
- *                                         file (test keys only unless --live)
+ *   homie-studio shop listen --profile <sandbox> [--port 8787]   private local webhook forwarding
+ *   homie-studio shop plan --have <file>    exact next operation for Stripe's official MCP (public reads only)
+ *   homie-studio shop verify --have <file>  verify fresh MCP reads and save the public link configuration
+ *   homie-studio shop webhook [--live] [--renew]   privately install webhook using one Stripe CLI browser approval
+ *   homie-studio shop connect [--live] [--renew]   alternative: full sync through Stripe CLI approval
  *   homie-studio shop catalog [--have <file>|-] [--mode test|live]   the items as Products in the studio's Stripe,
  *                                         made by the AI through Stripe's own MCP: the read first, then (with what it
  *                                         answered) the exact writes; in sync, shop.json "catalog" records the mode
@@ -226,14 +227,9 @@
  *   homie-studio setup attach <hs_…> [--client claude|codex|grok]
  *                                          (this repository is the studio the chat's setup card is making: say so, once,
  *                                          learn its live address, and give a template copy its real name)
- *   homie-studio setup --via stripe-projects [--with elevenlabs] [--accept-tos] [--dry-run]
- *                                         (a prototype, 0.24.3: Cloudflare, and ElevenLabs with --with, made or linked
- *                                          through Stripe Projects on their free plans; the person accepts the providers'
- *                                          terms (then --accept-tos) and signs in on Stripe's and the provider's own
- *                                          pages; the account id goes into studio.json, the token stays in Projects'
- *                                          vault and its git-ignored .env, and Wrangler runs with it here. The usual
- *                                          way, npx wrangler login, stays the default. lib/projects.mjs)
  *   homie-studio domain <hostname>                  AI configures DNS/TLS for the next deploy
+ *   homie-studio media import --file <download> --receipt <receipt.json> --out <studio-path> --used-by <scene-file>
+ *                                          Place completed official MCP output with provenance (no provider calls)
  *   homie-studio setup prepare                     AI installs a private Node/npm if missing
  *   homie-studio setup status [--connector yes|no] [--client claude|codex|grok]   (also: homie-studio doctor)
  *                                         what this computer and the person's accounts have for a studio: Node, the Homie
@@ -325,6 +321,7 @@
  *
  * Every command prints a few lines for a person; --json prints the result.
  */
+import { importMedia } from '../lib/media-import.mjs';
 // FIRST, before any other file of the toolkit is evaluated: a Node.js that is too old ends here, with the reason.
 import '../lib/node-version.mjs';
 import { spawn, spawnSync } from 'node:child_process';
@@ -362,8 +359,6 @@ import { agentsBrain, agentsBrainKey, agentsPass, agentsPasses, agentsRevoke, ag
 import { AgentSeat } from '../lib/agent-seat.mjs';
 import { shopCheck, shopConnect, shopDisconnect, shopInit, shopLines, shopOrders, shopRefund, shopStatus } from '../lib/shop.mjs';
 import { catalogLines, catalogPlan } from '../lib/shop-catalog.mjs';
-import { projectsLines, setupViaProjects } from '../lib/projects.mjs';
-import { projectsCloudflareEnv } from '../lib/projects-env.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
 import { formatStatus, setupStatus } from '../lib/doctor.mjs';
 import { codexTarget, newCodex, writeCodexPage } from '../lib/codex.mjs';
@@ -384,22 +379,23 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['public', 'lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'giving', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
+// build --quick keeps compilation and type checks, skips rules generated play/smoke checks.
+const BOOL_FLAGS = ['quick', 'public', 'lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'giving', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a.startsWith('--')) {
     const [k, v] = a.slice(2).split(/=(.*)/s, 2);
     if (v !== undefined) flags.set(k, v);
-    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && !BOOL_FLAGS.includes(k)) flags.set(k, argv[++i]);
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && (!BOOL_FLAGS.includes(k) || k === 'profile' && argv[0] === 'shop')) flags.set(k, argv[++i]);
     else flags.set(k, true);
   } else positional.push(a);
 }
 const asJson = flags.has('json');
-const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
+const log = asJson && positional[0] !== 'build' ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
-  if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
+  if (asJson || /^shop (plan|verify)$/.test(result.command ?? '')) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
   // A standalone plan or build says every target, built or not, and what a standalone copy does not have.
   if (/^standalone( |$)/.test(String(result.command ?? ''))) { process.stdout.write(`${standaloneLines(result).join('\n')}\n`); return; }
   // A check that found problems still prints them (its rows say what to fix), never a bare "failed".
@@ -635,9 +631,6 @@ function print(result) {
     case 'shop catalog':
       lines.push(...catalogLines(result));
       break;
-    case 'setup':
-      lines.push(...projectsLines(result));
-      break;
     case 'chat rules':
     case 'chat budget':
     case 'lounge rules':
@@ -846,6 +839,8 @@ 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 listen': ['profile','port'],
+  'shop webhook': ['live','renew','profile'],
   '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'],
@@ -936,12 +931,7 @@ async function main() {
   if (cmd === 'progress') return progressCommand(root, sub);
   if (cmd === 'domain') return studioDomain(root, sub);
   if (cmd === 'setup' && sub === 'attach') return setupAttach(root, positional[2], { homie: flags.get('homie'), client: flags.get('client') });
-  if (cmd === 'setup' && flags.has('via')) {
-    if (flags.get('via') !== 'stripe-projects') return { ok: false, command: 'setup', why: '--via stripe-projects is the one other way this version knows (the default is npx wrangler login)' };
-    const extra = String(flags.get('with') ?? '').split(',').map((x) => x.trim()).filter(Boolean);
-    if (extra.some((x) => x !== 'elevenlabs')) return { ok: false, command: 'setup', why: '--with takes elevenlabs (Cloudflare is always set up)' };
-    return setupViaProjects(root, { withElevenlabs: extra.includes('elevenlabs'), acceptTos: flags.has('accept-tos'), dryRun: flags.has('dry-run'), log });
-  }
+  if (cmd === 'media' && sub === 'import') return importMedia(root, { file: flags.get('file'), receipt: flags.get('receipt'), out: flags.get('out'), usedBy: flags.get('used-by') });
   if (cmd === 'handoff') return handoff(root, sub, { homie: flags.get('homie'), client: flags.get('client') });
   if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
   if (cmd === 'port' && sub === 'check') {
@@ -963,7 +953,7 @@ async function main() {
   // go, so an old note, an old card or an agent's memory of the toolkit does not end at "unknown command".
   if (cmd === 'game' && sub === 'remix') return { ok: false, command: 'game remix', why: 'remix was retired: a game is no longer handed over whole, and no studio serves one. Games build on each other through parts, the pieces of a game its studio chose to share: find one with `homie-studio parts find <words>` and bring it in with `homie-studio parts add` (in chat: parts_find, part_add; parts/PARTS.md)' };
   if (cmd === 'games') return { ok: true, command: 'games', games: listGames(root).map(({ dir, ...g }) => ({ ...g, dir: relative(root, dir) })) };
-  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log, maps: flags.has('maps'), types: flags.has('types'), longCheck: flags.has('long-check') }), 'build');
+  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log, maps: flags.has('maps'), types: flags.has('types'), longCheck: flags.has('long-check'), quick: flags.has('quick') }), 'build');
   if (cmd === 'preview') return preview(root, positional[1] ?? (listGames(root).length === 1 ? listGames(root)[0].id : null));
   if (cmd === 'perf' && sub === 'sizes') return perfSizes(root, positional[2] ?? listGames(root)[0]?.id);
   if (cmd === 'lab') return labCommand(root, sub);
@@ -1114,7 +1104,15 @@ async function main() {
     const url = flags.get('url');
     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==='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 === '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 === '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')});
@@ -1362,7 +1360,7 @@ function mediaPut(root, file, as) {
   const key = as ?? (/^(music|videos)\//.test(rel) && !rel.includes('..') ? rel : `${folder}/${basename(file)}`);
   const bin = wranglerBin(root);
   return new Promise((done) => {
-    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: workerDir(root), env: { ...process.env, ...projectsCloudflareEnv(root), CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
+    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: workerDir(root), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
     p.on('close', (code) => {
       if (code !== 0) return done({ ok: false, command: 'media put', why: 'wrangler r2 object put failed' });
       // The manifest is committed: it names the file by its path on the site, never the workers.dev address.

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

@@ -183,7 +183,7 @@ Scaffold businesses with `new <folder> --kind business`; causes with `--kind cau
 
 For giving, set the studio currency and run `shop init --giving --currency CAD` (use the organisation’s currency). It creates one-time/monthly suggested gifts. The owner supplies `giving.receiptText` in shop.json; Homie supplies no legal or tax text. Before Stripe is connected, local /shop/ previews items and prices with checkout disabled. Run the connection step yourself; the owner approves their Stripe account in the browser.
 
-Use `shop.book` and the booking collection declaration in SHOP.md. Default keyless booking links show pending while paying; an unpaid guest does not block others. Stripe limits completed sessions to capacity. The owner’s AI syncs published/changed slots with `stripe_bookings_sync`. Say “Pay to secure your seat.” Exclusive unpaid holds require the explicitly selected optional keyed connection.
+Use `shop.book` and the booking collection declaration in SHOP.md. Default keyless booking links show pending while paying; an unpaid guest does not block others. Stripe limits completed sessions to capacity. The owner’s AI syncs published/changed slots with `stripe_shop_plan` and the complete slot manifest. Say “Pay to secure your seat.” Exclusive unpaid holds require the explicitly selected optional keyed connection.
 
 
 ## Tell my AI when a booking comes in
@@ -288,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/).