@homie-rocks/studio 0.51.4 → 0.51.6

package/CHANGELOG.md

@@ -17,6 +17,55 @@ 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.6] - 2026-10-14
+
+**Plugin 0.51.6**
+
+Keep each customer's exact basket through payment, and check that your studio meets its needs across screens, AI jobs and handover.
+
+### Added
+
+- **Check the whole service:** Owner needs can call studio MCP tools as customer, staff or owner, assert returned results and saved records, invoke declared scheduled functions locally, read event feeds and MCP Events, check webhook delivery, and verify handover files. Checks keep role permissions and test-record isolation. Headless-only plans run without Chrome; missing tools, permissions, effects and text explain why a need is not met.
+
+### Fixed
+
+- **Exact rounds and baskets:** Opt-in keyless saved baskets keep the phone's exact items and quantities. One custom-amount Payment Link carries the saved total; signed payments are checked against the saved basket and report full payment or a shortfall for staff. Short payments grant no automatic entitlements. The Worker needs no Stripe API key, and existing adjustable Stripe menus keep their behavior.
+- **Clear acceptance and evidence:** Passing assertions mark a need met even when captures are absent or fail. Capture diagnostics identify the surface, explain the failure and show how to collect evidence with `--shots`.
+- **Reliable changing controls:** Click, fill and select actions retry detached elements within a bounded wait. The app skill, packaged guides and Codex template explain how updating controls in place preserves a held press across delayed refreshes.
+
+### Upgrade notes
+
+- Saved baskets are opt-in through `shop.json.basket` and require Stripe with tax-inclusive menu prices. Automatic tax and Managed Payments are refused for basket mode. Staff can use the reported basket total, actual payment and settlement status to collect a shortfall.
+
+## [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.

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.
 
@@ -181,3 +181,18 @@ 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.
+
+## Every owner need is executable
+
+The Codex `needs` block supports existing UI steps plus named-role MCP calls,
+returned-result assertions, simulated schedule ticks, record/results reads,
+event feed/MCP Events/webhook checks and handover file contents. See the packaged
+[needs format and examples](../guides/app/NEEDS.md). Passing assertions are **met**;
+captures are additional evidence. Missing captures name their surface, reason and
+how to rerun with `--shots .checks`. Detached action elements are re-queried for a
+bounded ten seconds; ambiguous post-dispatch failures are not replayed.
+
+Keep buttons connected during delayed refreshes: create the button once and set
+`button.textContent = label` when data arrives. Never replace a held button with
+`innerHTML` or `replaceWith`; that can cancel navigation between pointer down and
+up. The needs guide has a short complete example and explains outcome assertions.

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

@@ -0,0 +1,160 @@
+# Check every owner need
+
+The JSON array in the app's `CODEX.md` fenced `needs` block is the acceptance
+source. Keep every owner statement, including AI jobs, reminders, results and
+handover. Each need has a unique `id`, `statement`, optional `role` and `steps`,
+and nonempty `assertions`. An unavailable capability stays as a need with an
+empty assertion list and a prose explanation; check reports it not met.
+
+Run `homie-studio check <app> --url http://localhost:8787 --shots .checks` with
+`homie-studio dev` running in the same studio. Headless-only needs require no
+Chrome. UI steps and headless steps can be combined in one need and run in order.
+Each need starts with its own saved results; records are shared across needs in
+the run. The default isolated record scope is shared by browsers, MCP calls and
+scheduled effects. `--no-isolate` explicitly uses existing records. Isolation is
+for app records, not a sandbox for external email/SMS/payment calls: use the
+service's test connection for those jobs.
+
+## Passing assertions and capture evidence
+
+Passing assertions mean **met**, with or without screenshots. A missing capture
+never changes that verdict. For every UI surface without a capture, the result
+names the surface, why it was unavailable (including the browser's error), and
+tells you to rerun with `--shots .checks`. Fix the reported disk/browser error
+first. Successful captures are listed in the saved needs report. Inspect them
+against the owner's scene: automation proves the assertions, not visual quality.
+Headless needs have no screenshots to collect.
+
+Click, fill and select actions re-query their selector for up to ten seconds when
+the browser reports a detached/stale element. A permanently unstable control
+reports its surface and selector. Other action failures are not replayed: a
+navigation error after dispatch does not prove that a purchase did not happen.
+
+## Customer and staff AI calls and returned results
+
+Headless actions require an explicit `role`, inherited from the need or overridden
+on a headless step/assertion. Use an app's declared role, or `owner` for owner-only
+operations. The dev-only signed identity enforces real MCP audiences and record
+capabilities; a customer is not silently promoted to owner. Production OAuth
+approval is unchanged. Missing dev credentials, tools or role permissions produce
+plain not-met reasons.
+
+```needs
+[
+  {"id":"ai-book","statement":"A customer's AI books in one call","role":"customer",
+   "steps":[{"mcp":{"tool":"book","arguments":{"name":"Ada"}},"save":"booking"}],
+   "assertions":[{"result":"booking","contains":{"ok":true}}]},
+  {"id":"open-roles","statement":"Staff AI can ask which roles are still open","role":"staff",
+   "steps":[{"mcp":{"tool":"open_roles"},"save":"open"}],
+   "assertions":[{"result":"open","path":"roles","contains":["cook"]}]}
+]
+```
+
+Use actual tool names, arguments and returned fields from this studio. `save`
+names the returned result; duplicate names fail. `result` reads it. `path` selects
+dot-separated object keys or array indexes, such as `records.0.data.name`.
+`equals` compares the full selected JSON value; `contains` matches a subset of
+object fields, each expected array entry against an actual entry, or a substring.
+`text` checks a string for one substring or every string in an array. Use `{"$result":"booking.id"}` anywhere in a subsequent step or assertion
+to refer to a saved value, without string interpolation. A missing
+result/path, wrong value or malformed assertion stays not met, naming the failed
+condition. Standard studio tool envelopes are unwrapped to their `data` value;
+other tools retain their structured content or MCP result.
+
+## Schedules, records and results
+
+A `schedule` step invokes a named declared scheduled function through the local
+MCP dispatcher, with a simulated timestamp in epoch milliseconds. It runs the
+handler headless and reports handler failures. This is a simulated tick, not
+proof that a deployed cron fired or an external message reached a person. Assert
+the actual resulting record or queue entry; do not just assert the trigger's ID.
+The handler still needs a declared role with the relevant record capabilities.
+
+```needs
+[
+  {"id":"remind","statement":"Daily reminders queue for booked guests","role":"owner",
+   "steps":[{"schedule":{"name":"reminders","at":1800000000000}}],
+   "assertions":[{"role":"staff","records":{"collection":"reminders"},
+                  "contains":{"records":[{"data":{"name":"Ada","state":"queued"}}]}}]},
+  {"id":"results","statement":"Staff can read the completed result","role":"staff",
+   "assertions":[{"records":{"collection":"results","id":"one"},
+                  "contains":{"data":{"status":"complete"}}}]}
+]
+```
+
+`records` uses the real `app_records` read tool, bound to this app, the named role
+and this check's isolation scope. Supply collection and optional ID as accepted by that tool. Use its actual response shape (a single record versus
+a list). Create fixtures with steps before asserting them; fresh runs start empty.
+
+## Owner AI events and webhook handoff
+
+Call `studio_events_read` to prove the feed contains the event, or use MCP Events
+`events/poll` with an explicit cursor to prove event retrieval. `events/list`
+checks discovery. `resources/read` also works and preserves its MCP `contents`
+array. These prove the studio exposes an event to the named role; they do not
+claim an external AI held a live connection or acted on it.
+
+```needs
+[
+  {"id":"owner-feed","statement":"The owner's AI can read new bookings","role":"owner",
+   "steps":[{"mcp":{"tool":"book","arguments":{"name":"Ada"}},"role":"customer"}],
+   "assertions":[{"mcp":{"tool":"studio_events_read","arguments":{"feed":"bookings"}},
+                  "contains":{"events":[{"type":"record.changed","data":{"data":{"name":"Ada"}}}]}}]},
+  {"id":"mcp-events","statement":"Owner AI retrieves booking events through MCP Events","role":"owner",
+   "assertions":[{"mcp":{"method":"events/poll","params":{"name":"bookings","cursor":"v1:bookings:0"}},
+                  "contains":{"events":[{"name":"bookings"}]}}]},
+  {"id":"webhook","statement":"The declared owner webhook accepts a signed test event","role":"owner",
+   "steps":[{"mcp":{"tool":"studio_events_webhook_test","arguments":{"feed":"bookings"}},"save":"delivery"}],
+   "assertions":[{"mcp":{"tool":"studio_events_webhook_status","arguments":{"feed":"bookings"}},
+                  "waitMs":5000,"contains":{"deliveries":[{"event":{"$result":"delivery.id"},"state":"complete"}]}}]}
+]
+```
+
+Declare the feed/audience and webhook first using the existing functions guide.
+The webhook test sends an explicitly synthetic event to the declared receiver;
+match the saved delivery ID to avoid mistaking an older delivery for this test.
+Use `studio_events_webhook_status` for subsequent attempts and errors.
+A status assertion proves the receiver's acknowledgement, not its downstream
+email/SMS or AI work. Read-only MCP/records assertions make one call by default. For asynchronous
+effects, set `waitMs` (0–10000) to re-read until the expected value appears.
+Tool/permission errors fail immediately. Saved results are immutable and are
+never retried. Never put a mutating tool in an assertion; use a step once and
+assert its saved result or durable effect. Unknown methods/tools and denied feeds
+fail explicitly. Secrets do not belong in the needs block.
+
+## Handover files
+
+```needs
+[
+  {"id":"handover","statement":"The owner has AI connection and reminder instructions",
+   "assertions":[{"file":"HANDOVER.md","text":["/mcp","Reminders run daily"]}]}
+]
+```
+
+`file` is relative to the studio root. The file must exist and be readable; `text`
+checks all requested contents. Without `text` it proves only existence/readability.
+Use this for handover instructions and exported text results; use `records` for
+live structured results. Missing files and missing text name the exact failure.
+
+## Keep controls connected during delayed refreshes
+
+Never replace a button under a press. A delayed fetch can finish between pointer
+down and pointer up; replacing the node cancels its click/navigation and loses
+focus. Create interactive nodes once, key repeated items by stable record IDs,
+and update text/attributes in place. Keep pending/disabled state deliberate.
+
+```js
+const choose = document.createElement('button');
+choose.textContent = 'Choose crew';
+choose.addEventListener('click', () => selectRole('crew'));
+controls.append(choose);
+async function refresh() {
+  const { open } = await loadRoles();
+  choose.textContent = `Choose crew (${open} places)`;
+  // Keep this same button connected; do not replace controls.innerHTML here.
+}
+```
+
+The runner can retry a detected stale handle before dispatch; it cannot infer
+that an app silently cancelled a press after dispatch. Both stable DOM updates
+and an assertion on the navigation's outcome are necessary.

package/guides/app/SKILL.md

@@ -100,7 +100,7 @@ The Codex's `needs` fenced block is a JSON array, one entry per need from the re
 
 Steps support `fill`, `select`, `click: true` and `reload: true`; surfaces are `wall`, `phone`, `phone-two`, `tablet`, `kiosk` and `staff` (a tablet viewport). Set a need’s `role` to the declared role to prove. Each assertion names its surface; only the named screens are required. Assertions use a visible selector with optional contained text, or an observed effect. An honestly unavailable capability remains in the block with no assertions and a plain explanation in the prose; check reports it not met. Do not delete, weaken or replace a need to get green. Static needs such as accurate prices may have no action steps. Use semantic attributes on real visible scene elements for testability, never hidden QA-only counters.
 
-Run build and the shared-action check, then the needs step runs on those real browsers. Save captures with `--shots .checks`. The result contains each statement, met/partly/not, the assertion result and captures of all named surfaces; `.studio/checks/<id>-needs.json` drives the Codex's Needs status. Redraw `codex <id>` after checking. Passing a selector assertion is evidence, not a visual judgement: read every capture and perform the full flows as owner and customer using the playtest skill. If the picture fails the words, it is not done even with green assertions.
+Run build and the shared-action check, then the needs step runs on those real browsers. Save captures with `--shots .checks`. The result contains each statement, met/partly/not, the assertion result and available captures of named surfaces; `.studio/checks/<id>-needs.json` drives the Codex's Needs status. Redraw `codex <id>` after checking. Passing a selector assertion is evidence, not a visual judgement: read every capture and perform the full flows as owner and customer using the playtest skill. If the picture fails the words, it is not done even with green assertions.
 
 For staff flows, sign in through the existing local owner link and prove the transition in real Chrome. Keep evidence in the Codex alongside the automated flows. Confirm unauthorized writes are refused and records remain after all screens close. Never call an untested privileged path passed. Before final handover, show the need table with evidence and explicit remaining gaps. If the starter or a board of boxes is still visible, return to the scene design and build it.
 
@@ -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
@@ -252,8 +252,8 @@ a notification or a person heard audio. Observations reset before each need.
 After reloads and rebuilt frames, check waits for online state, completed arrival,
 a hidden loading cover and two frames before assertions/captures. Timeout evidence
 names the surface and selector/effect it awaited. Dialogs are automatically accepted
-and reported. Read retries recover detached frames; dispatched actions are not
-silently repeated. `dev` rebuilds root HTML, CSS and JS as well as source and map
+and reported. Read retries recover detached frames. Click/fill/select retry detached elements by
+re-querying for up to ten seconds; other dispatched action failures are not replayed. `dev` rebuilds root HTML, CSS and JS as well as source and map
 changes. Unavailable sandbox Web Storage uses frame-local memory; use app records
 or `net.prefs` for persistence across reloads.
 
@@ -312,3 +312,19 @@ 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/).
+
+## Every need has a check
+
+Read [NEEDS.md](NEEDS.md) for the complete executable format and examples for UI,
+customer/staff MCP tools, owner event feeds and MCP Events, webhook delivery,
+simulated scheduled functions, records/results and handover files. Keep existing
+UI steps. Headless steps use an explicit named role and the local dev credential;
+assertions check actual returned values and effects. Missing capabilities stay
+not met with their reason. Passing assertions are met even without captures;
+missing evidence names each surface, its error and the `--shots .checks` remedy.
+
+Keep interactive DOM nodes connected across delayed refreshes. Update a button's
+text and attributes in place; never replace a button under a press. The short
+example in NEEDS.md preserves its click listener and focus. A stale-element retry
+helps a replaced handle before dispatch; it cannot recover a silently cancelled
+press. Assert the resulting navigation as well as the button's presence.