@homie-rocks/studio 0.51.6 → 0.51.8

package/CHANGELOG.md

@@ -17,6 +17,41 @@ 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.8] - 2026-10-15
+
+**Plugin 0.51.8**
+
+Run your studio across more screens with reliable shared records, clearer checks and a simpler owner connection.
+
+### Fixed
+
+- **Reliable screens and saved settings:** App screens share simultaneous record reads across tabs, queue bursts and back off after connection failures. Writes stay separate and refresh cached reads; reconnect notices use plain language. Records-only apps remember device preferences and saved references after reload while keeping their iframe sandbox.
+- **Room for your wall display:** TV join cards reserve a measured safe area for your app, stay within a bounded size and wrap long addresses. Hiding the card returns that space to your content.
+- **Checks that match what people can use:** Covered controls fail checks immediately with the blocking element identified, including overlays outside the app frame. You can also check text navigation with graphics disabled using `check --webgl-failure`; fallback notices stay in the page flow so controls remain reachable.
+- **Clean toolkit type checks:** Collision, terrain and tile-coordinate code now passes strict `build --types` checks when imported into your app or game.
+
+### Added
+
+- **Connect your owner's AI with your existing login:** `connector` uses your Wrangler sign-in to save a private MCP configuration limited to the chosen tools, studio origin and expiry. You can revoke access; the server stores only token hashes and command output contains no bearer secret.
+
+### Changed
+
+- **Safer bookings and usable text controls:** Authoring guides show server-owned capacity with atomic versioned writes, tested with six simultaneous requests and one successful reservation. They explain how to initialise text controls before graphics and keep the app usable when 3D is unavailable.
+- **Clear deploy guidance:** Wrangler remains the path for uploading your site's static assets. The guide explains why Cloudflare's official MCP request interface cannot perform the required upload authorization.
+
+## [0.51.7] - 2026-10-14
+
+**Plugin 0.51.7**
+
+Finish setting up your shop through Stripe's official plugin, and see what your studio's scheduled work is doing.
+
+### Fixed
+
+- **Finish shop setup with fewer calls:** Products, prices and payment links are set up together where possible, and setup remembers completed changes instead of repeatedly searching your Stripe account. Verified shop settings are saved and installed on deploy; checkout explains when private webhook setup is the remaining step.
+- **Clear, private webhook setup:** The guided flow explains when you need one separate Stripe CLI browser approval. The installer passes the signing secret privately to Wrangler. You do not need to supply an API key, and payments stay with Stripe.
+- **See your studio's work:** Owners and studio-wide staff can inspect function run history, errors and the next scheduled run through their authenticated studio connection. Record actions use your highest declared role by default and tell you which role was used.
+- **Reliable handover:** Deploy distinguishes claiming your studio from listing it in the directory. Screenshots used as evidence that owner needs are met are copied into the studio so they remain available with its Codex handover.
+
 ## [0.51.6] - 2026-10-14
 
 **Plugin 0.51.6**

package/apps/APPS.md

@@ -196,3 +196,29 @@ 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.
+
+
+## Selling and operational checks over MCP
+
+Use Stripe's official plugin and the shop skill's batched `stripe_shop_plan` flow.
+Retain write responses, verify, then deploy the compact public links. Until the
+private `stripe_webhook` step completes, checkout names that one remaining step.
+The AI starts the tool; the owner approves Stripe CLI once if needed. No secrets
+or API keys pass through chat. Deploy distinguishes **claimed, not listed** from
+an actual directory listing; publishing is a separate action.
+
+On the existing signed-in studio connector (`<site>/mcp/auth`), call
+`studio_function_runs` with optional `name`, `errors`, `before` for actual attempts,
+redacted errors and next due times. Owners and studio-wide `staff` grants can read
+this operational history; per-app staff grants do not expose other apps' runs.
+Do not start `functions runs --url` in a headless shell with no CLI OAuth session:
+that is a different client and would need its own initial browser approval.
+
+`app_records` without `role` selects the highest available declared role: signed-in
+roles first, then the largest permission set, with role name as a stable tie-break.
+Each response reports `role`; an explicit role stays explicit. Inspect `app_schema`
+and pass a role when deliberately testing the customer experience.
+
+`check --shots` may capture outside the studio, but persistent needs evidence copies
+those pictures into `.studio/checks` and stores studio-relative paths. Keep that
+folder with the Codex evidence. Deploy can render it without outside-path warnings.

package/bin/homie-studio.mjs

@@ -37,7 +37,9 @@
  *                                         AI guides, chat review and game decisions think with Clef on this computer
  *                                         when Ollama has clef-flash (free; dev never downloads it), else scripted;
  *                                         --remote-ai: the real Workers AI, billed)
- *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   homie-studio check <id> [--url <site>] [--shots <dir>] [--webgl-failure]
+ *   homie-studio connector --tools <name,...> --out <private-config.json> [--days 30]
+ *   homie-studio connector --revoke <id>
  *   homie-studio shoot <id> [--url <site> | --preview] [--frames 60] [--fps 30] [--device computer|phone]
  *                      [--out <dir>] [--hold <key code>] [--no-smoke] [--timeout 180]
  *                                         pictures of the game on a clock this command steps (one frame = 1/fps s
@@ -380,14 +382,14 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 const argv = process.argv.slice(2);
 const flags = new Map();
 // 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 BOOL_FLAGS = ['webgl-failure', '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) || k === 'profile' && argv[0] === 'shop')) flags.set(k, argv[++i]);
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && (!BOOL_FLAGS.includes(k) || k === 'revoke' && argv[0] === 'connector' || k === 'profile' && argv[0] === 'shop')) flags.set(k, argv[++i]);
     else flags.set(k, true);
   } else positional.push(a);
 }
@@ -407,6 +409,7 @@ function print(result) {
   if (/^(style|assets|cast|anim)( |$)/.test(String(result.command ?? ''))) { process.stdout.write(`${artLines(result).join('\n')}\n`); return; }
   if (/^collision /.test(String(result.command ?? '')) && result.lines) { process.stdout.write(`${result.lines.join('\n')}\n`); return; }
   switch (result.command) {
+    case 'connector': lines.push(JSON.stringify(result,null,2)); break;
     case 'new':
       lines.push(`${result.name} is a studio now: ${result.dir}`, '', 'Wrote:', ...result.wrote.map((f) => `  ${f}`), '', `Dependencies: ${result.installed}`, '', 'Next:', ...result.next.map((n) => `  ${n}`), '', result.online);
       break;
@@ -514,7 +517,7 @@ function print(result) {
         // (lib/deploy-state.mjs): the hash `build` printed and the one the live site's manifest answers with.
         ...result.games.map((g) => `  ${g.id}: ${g.open ?? g.play}${g.hash ? `  [${deployWords(g)}]` : ''}${g.wall ? `  wall: ${g.wall}` : ''}`), ...(result.removed?.length ? [`  no longer on the site: ${result.removed.join(', ')}`] : []), ...(result.notes ?? []).map((n) => `  Note: ${n}`), ...(result.songs ?? []).map((m) => `  song ${m.slug}: ${m.page}`), ...(result.videos ?? []).map((m) => `  video ${m.slug}: ${m.page}`),
         ...(result.media?.moved ?? []).map((m) => `  moved to R2 (checked by SHA-256): ${m.path}, still at ${m.url}`), ...(result.media?.failed ?? []).map((m) => `  not moved to R2: ${m.path}: ${m.why}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}, Durable Objects Table + Lobby${result.r2 ? `, R2 ${result.r2}` : ' (no storage: none needed; `homie-studio storage add` adds it for large media)'}.`,
-        result.claim ? 'The site claimed itself in the directory: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim. Listing is the studio’s choice: set homie.directory to true or a directory URL before deploying to request one.',
+        result.claim ? `The site is ${result.listing??'claimed, not listed'}: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish` : 'No directory claim. Listing is the studio’s choice: set homie.directory to true or a directory URL before deploying to request one.',
         ...(result.standalone?.length ? ['', ...result.standalone] : []));
       break;
     case 'deploy plan':
@@ -831,6 +834,7 @@ const OUTWARD_FLAGS = {
   'setup attach': ['homie', 'client'],
   handoff: ['homie', 'client'],
   'players owner': ['url', 'revoke'],
+  'connector': ['url','tools','out','days','revoke'],
   'stats key': ['url', 'hours'], 'stats link': ['url'], 'stats revoke': ['url'], 'stats share': [],
   'office link': ['url', 'to'], 'office key': ['url', 'hours'], 'office announce': ['url', 'game', 'room', 'seconds'],
   'office invite': ['url', 'label', 'uses', 'count', 'days', 'server'], 'office launch': ['url', 'max'],
@@ -914,6 +918,7 @@ async function main() {
   }
   if (cmd === 'events') return (await import('../lib/events-cli.mjs')).eventsCommand(root, sub, positional, flags, { log });
   if (cmd === 'function' || cmd === 'functions') return (await import('../lib/functions-cli.mjs')).functionCommand(root, sub, positional, flags, { log });
+  if (cmd === 'connector') return (await import('../lib/connector-token.mjs')).connectorToken(root,{url:flags.get('url'),tools:typeof flags.get('tools')==='string'?flags.get('tools').split(','):[],out:flags.get('out'),days:flags.has('days')?Number(flags.get('days')):30,revoke:flags.get('revoke')});
   if (cmd === 'tool') return (await import('../lib/tools-cli.mjs')).toolCommand(root, sub, positional, flags, { log });
   // A trailer is the plugin's video skill; this hands the words after the id over to it (lib/trailer.mjs).
   if (cmd === 'trailer') return trailerCommand(root, sub, argv.slice(argv.indexOf(sub) + 1), { skills: flags.get('skills') ?? null, slug: flags.get('slug') ?? null });
@@ -995,7 +1000,7 @@ async function main() {
       const results = [];
       for (const game of games) {
         const shots = flags.get('shots') ? resolve(flags.get('shots'), ...(games.length > 1 ? [game] : [])) : null;
-        const r = await tracked(root, 'checks', (report) => check({ root, url: site.url, game, shots, log, report, isolate:!flags.has('no-isolate') }), 'check');
+        const r = await tracked(root, 'checks', (report) => check({ webglFailure:flags.has('webgl-failure'), root, url: site.url, game, shots, log, report, isolate:!flags.has('no-isolate') }), 'check');
         results.push({ ...r, game, site: site.url, local: site.local });
         const receiptDir = join(root, '.studio', 'checks');
         mkdirSync(receiptDir, { recursive: true });

package/docs/toolkit-place-patterns.md

@@ -0,0 +1,62 @@
+# Building places: layout, authority and recovery
+
+## TV join safe area
+
+On `/<id>/tv`, the shell sets `body.homie-join-visible` while the join card is present. It publishes CSS pixel values on the document root in both the shell and the sandboxed app: `--homie-join-x`, `--homie-join-y`, `--homie-join-width`, `--homie-join-height`, and `--homie-join-inset-top/right/bottom/left`. The insets include the card's distance from its configured screen edge. Inactive edges are zero; no card means all values are zero and the body class is absent. Measurements update on resize and iframe navigation. The card is at most 480 × 280 CSS pixels; its address wraps within that box.
+
+Reserve an entire strip on either occupied axis, with a gap:
+
+```css
+.status { position: fixed; right: 20px;
+  bottom: calc(var(--homie-join-inset-bottom, 0px) + 20px); }
+.tee-sheet { position: fixed; left: 20px; bottom: 20px;
+  right: calc(var(--homie-join-inset-right, 0px) + 20px); }
+```
+
+For top/left join corners, use the corresponding top/left insets. Never position critical controls underneath the card merely because it ignores pointer events. Regression coverage measures actual rectangles at 1920×1080, 1280×720 and 3840×2160.
+
+## Authoritative capacity
+
+Bookings and inventory belong to server-side `defineTool` mutations, with strict schemas (`additionalProperties: false`) and atomic versioned writes. A client-writable generic ledger is not an inventory authority: six browsers can all read one remaining place and overwrite one another. Clients may display availability and request a reservation; they cannot supply remaining capacity, identity or a new inventory total.
+
+The executable [reservation example](../guides/app/examples/reserve.mjs) accepts only a slot ID. An owner-only action seeds `ctx.database.put('tee-0900', {remaining: 1, bookings: []}, {version: 0})`. `reserve` reads that row, derives the booking identity from `ctx.caller`, and writes with `{version: row.version}`. One SQLite statement checks the version and updates the entire row; a conflict is a failed reservation, never a success. Six simultaneous requests produce one winner and five conflicts. Do not expose this namespace through a generic client record mutation. Read availability through a separate read-only action. For retryable purchases add a server-owned idempotency key and settlement handling before charging.
+
+## Text first, graphics optional
+
+Bind navigation and text controls before creating a renderer. A failed WebGL context must not prevent those handlers from being installed:
+
+```ts
+renderTextControls();
+bindNavigation();
+try {
+  const renderer = new THREE.WebGLRenderer({canvas});
+  startScene(renderer);
+} catch {
+  canvas.hidden = true;
+  fallback.hidden = false; // a normal-flow status inside the scene section
+}
+```
+
+Keep the fallback inside the scene section, outside navigation; never use a fullscreen or fixed overlay. The shell's automatic fallback is a normal-flow status beside the canvas and does not intercept input. Author a Codex need that clicks navigation and asserts the resulting text; then run `homie-studio check <id> --webgl-failure --shots .checks/no-webgl`. This disables WebGL context creation before scripts run in every app frame and executes the same UI needs. A passing rendering check alone does not establish usable text controls.
+
+## Action diagnostics and types
+
+`check` tests whether the action target is covered before dispatch. An obstruction reports the surface, target selector and covering element immediately; remove the overlay or repair its layout before retrying. Navigation/detachment handling does not replay an ambiguous dispatched action.
+
+`build --types` checks imported toolkit sources too. Collision/terrain closure narrowing and tile-coordinate narrowing are fixed in the toolkit; fresh studios need no local suppressions or edits to `node_modules`.
+
+## Connect another studio without another approval page
+
+Use the new studio's directory and the owner's existing Wrangler login (the same Cloudflare account must have D1 access). One command writes a connector config, never its bearer to stdout:
+
+```sh
+homie-studio connector --tools studio_stats --out /private/path/studio-connector.json
+```
+
+Load that file directly into the AI client's connector configuration using its local configuration/import mechanism. Do not paste, print or include the file in chat or commit it. The file is created exclusively with mode 0600; existing files are never overwritten. Only the file path, token ID, scopes and expiry are reported. The config targets this studio's `/mcp/auth` endpoint. No browser approval is needed when Wrangler is already authenticated; this command does not deploy anything.
+
+Tokens are bound to this origin, limited to the exact named tools, expire after 30 days by default (`--days 1` through `--days 90`), and cannot read MCP resources or subscriptions. D1 stores only the token hash and its scope metadata. Revoke with `homie-studio connector --revoke <id>` from the same studio. Every dispatch rechecks expiry and revocation. A login to a different studio alone does not grant authority over this database.
+
+## Deployment
+
+Cloudflare's official MCP request interface cannot authorize new static-asset uploads with an upload JWT; deploy with Wrangler, Cloudflare's own CLI using browser OAuth.

package/functions/FUNCTIONS.md

@@ -87,8 +87,8 @@ homie-studio functions runs --before 101
 The command uses the studio's deployed address unless `--url` overrides it. It
 uses the existing owner OAuth connection (one initial browser approval; no office
 key). After approval, checks need no browser. An AI connected to `<site>/mcp` calls
-the owner-only `studio_function_runs` tool with optional `name`, `errors` and
-`before`. Anonymous callers and staff cannot read it.
+the owner/studio-staff `studio_function_runs` tool with optional `name`, `errors` and
+`before`. Anonymous callers and per-app staff cannot read it. A studio-wide `staff` grant can read it; revocation takes effect on the next call. Reuse the authenticated connector at `/mcp/auth`; a headless CLI with no saved OAuth session requires a separate initial browser approval.
 
 Results include function, event ID, trigger, started/finished UTC times, outcome,
 error message and attempt. Failed attempts survive successful retries; history

package/guides/app/SKILL.md

@@ -328,3 +328,37 @@ 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.
+
+
+## Selling and operational checks over MCP
+
+Use Stripe's official plugin and the shop skill's batched `stripe_shop_plan` flow.
+Retain write responses, verify, then deploy the compact public links. Until the
+private `stripe_webhook` step completes, checkout names that one remaining step.
+The AI starts the tool; the owner approves Stripe CLI once if needed. No secrets
+or API keys pass through chat. Deploy distinguishes **claimed, not listed** from
+an actual directory listing; publishing is a separate action.
+
+On the existing signed-in studio connector (`<site>/mcp/auth`), call
+`studio_function_runs` with optional `name`, `errors`, `before` for actual attempts,
+redacted errors and next due times. Owners and studio-wide `staff` grants can read
+this operational history; per-app staff grants do not expose other apps' runs.
+Do not start `functions runs --url` in a headless shell with no CLI OAuth session:
+that is a different client and would need its own initial browser approval.
+
+`app_records` without `role` selects the highest available declared role: signed-in
+roles first, then the largest permission set, with role name as a stable tie-break.
+Each response reports `role`; an explicit role stays explicit. Inspect `app_schema`
+and pass a role when deliberately testing the customer experience.
+
+`check --shots` may capture outside the studio, but persistent needs evidence copies
+those pictures into `.studio/checks` and stores studio-relative paths. Keep that
+folder with the Codex evidence. Deploy can render it without outside-path warnings.
+
+### Places: capacity, TV space and failed graphics
+
+Authoritative bookings/inventory are server-side `defineTool` actions with strict schemas and atomic versioned writes, never a client-writable generic ledger. Use [the capacity example](examples/reserve.mjs): seed one place through an owner action; six simultaneous reservation requests must yield exactly one winner. Derive identity from the caller; expose neither inventory totals nor the authoritative namespace as client mutations.
+
+Initialise text controls and navigation before 3D rendering. Catch renderer creation failures inside the scene section; keep fallback text in normal flow, never over navigation. Add a navigation need and run `homie-studio check <id> --webgl-failure --shots .checks/no-webgl` to prove the controls work without WebGL.
+
+On TV, reserve `--homie-join-inset-bottom/right` (or the configured corner's top/left) plus a gap; `body.homie-join-visible` and `--homie-join-x/y/width/height` describe the shell card in the app frame too. See `node_modules/@homie-rocks/studio/docs/toolkit-place-patterns.md` for layout and text-first examples, connector setup and diagnostics.

package/guides/app/examples/reserve.mjs

@@ -0,0 +1,13 @@
+import {defineTool} from '@homie-rocks/studio/tools';
+export default defineTool({
+ name:'reserve',description:'Reserve one place in a server-owned slot',audience:'signed-in',namespace:'capacity',
+ inputSchema:{type:'object',properties:{slot:{type:'string',pattern:'^tee-[0-9]{4}$'}},required:['slot'],additionalProperties:false},
+ async handler({slot},ctx){
+  const row=await ctx.database.getVersioned(slot);
+  if(!row)return {ok:false,reason:'Unknown slot'};
+  const value=row.value;
+  if(value.remaining<1)return {ok:false,reason:'Full'};
+  const result=await ctx.database.put(slot,{remaining:value.remaining-1,bookings:[...value.bookings,ctx.caller.id]},{version:row.version});
+  return result.ok?{ok:true}:{ok:false,reason:'Taken; refresh availability'};
+ }
+});

package/guides/functions/SKILL.md

@@ -28,3 +28,5 @@ isolated records. Assert actual sound/haptic/notification triggers where request
 Check waits through reload readiness and reports dialogs and named timeout conditions.
 Do not weaken a need to obtain a green result; inspect captures and complete the
 owner's workflow. Do not deploy merely to prove a local handler.
+
+For authoritative bookings/inventory use strict `defineTool` actions and `database.put(key, next, {version: row.version})`; a conflict is a failed reservation. Never make the inventory a client-writable generic ledger. The [capacity example](../app/examples/reserve.mjs) proves one winner from six simultaneous requests for one place; initialise capacity through an owner-only action.

package/guides/office/SKILL.md

@@ -118,7 +118,7 @@ build/deploy; the Worker dispatches due functions without an office browser.
 Build and redeploy after upgrading; custom crons are kept. Check the deploy plan's
 cron line. Do not add a default cron to a studio with no declared need.
 
-To inspect runs from the owner's AI, call the owner-only studio MCP tool
+To inspect runs from the owner's AI, call the owner or studio-staff MCP tool
 `studio_function_runs` (optional `name`, `errors`, `before`), or run
 `homie-studio functions runs [<name>] [--errors] [--url <studio-site>]`.
 Use the existing owner OAuth connection; never request an office key. Results
@@ -180,3 +180,29 @@ 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/).
+
+
+## Selling and operational checks over MCP
+
+Use Stripe's official plugin and the shop skill's batched `stripe_shop_plan` flow.
+Retain write responses, verify, then deploy the compact public links. Until the
+private `stripe_webhook` step completes, checkout names that one remaining step.
+The AI starts the tool; the owner approves Stripe CLI once if needed. No secrets
+or API keys pass through chat. Deploy distinguishes **claimed, not listed** from
+an actual directory listing; publishing is a separate action.
+
+On the existing signed-in studio connector (`<site>/mcp/auth`), call
+`studio_function_runs` with optional `name`, `errors`, `before` for actual attempts,
+redacted errors and next due times. Owners and studio-wide `staff` grants can read
+this operational history; per-app staff grants do not expose other apps' runs.
+Do not start `functions runs --url` in a headless shell with no CLI OAuth session:
+that is a different client and would need its own initial browser approval.
+
+`app_records` without `role` selects the highest available declared role: signed-in
+roles first, then the largest permission set, with role name as a stable tie-break.
+Each response reports `role`; an explicit role stays explicit. Inspect `app_schema`
+and pass a role when deliberately testing the customer experience.
+
+`check --shots` may capture outside the studio, but persistent needs evidence copies
+those pictures into `.studio/checks` and stores studio-relative paths. Keep that
+folder with the Codex evidence. Deploy can render it without outside-path warnings.

package/guides/servers/SKILL.md

@@ -130,7 +130,7 @@ build/deploy; the Worker dispatches due functions without an office browser.
 Build and redeploy after upgrading; custom crons are kept. Check the deploy plan's
 cron line. Do not add a default cron to a studio with no declared need.
 
-To inspect runs from the owner's AI, call the owner-only studio MCP tool
+To inspect runs from the owner's AI, call the owner or studio-staff MCP tool
 `studio_function_runs` (optional `name`, `errors`, `before`), or run
 `homie-studio functions runs [<name>] [--errors] [--url <studio-site>]`.
 Use the existing owner OAuth connection; never request an office key. Results
@@ -181,3 +181,29 @@ 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/).
+
+
+## Selling and operational checks over MCP
+
+Use Stripe's official plugin and the shop skill's batched `stripe_shop_plan` flow.
+Retain write responses, verify, then deploy the compact public links. Until the
+private `stripe_webhook` step completes, checkout names that one remaining step.
+The AI starts the tool; the owner approves Stripe CLI once if needed. No secrets
+or API keys pass through chat. Deploy distinguishes **claimed, not listed** from
+an actual directory listing; publishing is a separate action.
+
+On the existing signed-in studio connector (`<site>/mcp/auth`), call
+`studio_function_runs` with optional `name`, `errors`, `before` for actual attempts,
+redacted errors and next due times. Owners and studio-wide `staff` grants can read
+this operational history; per-app staff grants do not expose other apps' runs.
+Do not start `functions runs --url` in a headless shell with no CLI OAuth session:
+that is a different client and would need its own initial browser approval.
+
+`app_records` without `role` selects the highest available declared role: signed-in
+roles first, then the largest permission set, with role name as a stable tie-break.
+Each response reports `role`; an explicit role stays explicit. Inspect `app_schema`
+and pass a role when deliberately testing the customer experience.
+
+`check --shots` may capture outside the studio, but persistent needs evidence copies
+those pictures into `.studio/checks` and stores studio-relative paths. Keep that
+folder with the Codex evidence. Deploy can render it without outside-path warnings.

package/guides/shop/SKILL.md

@@ -42,20 +42,30 @@ calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
    read `/v1/account` to record its account ID. Live mode only after the owner requests it.
 2. Call Homie's `stripe_shop_plan` with `account`, `mode: "test"`, `slots` and
    `observations: []`. CLI equivalent: `homie-studio shop plan --have plan-input.json`.
-   That JSON file contains the same fields. A returned `next` is the exact operation:
-   method, API path, parameters, API version and (for creates) idempotency key. Updates set desired fields; read before retrying. Metadata
-   scopes objects to this studio and origin; prices and links have content revisions.
-3. Perform each `next` through Stripe's official MCP. For GET, append
-   `{ "path": "…", "params": {…}, "body": <Stripe response> }` to `observations`
-   and plan again. Follow every pagination request. After a write, discard observations
-   and read fresh. Replanning resolves real Stripe IDs; never invent IDs or substitute
-   a different price. Reuse the supplied idempotency key where the tool supports it;
-   otherwise read before retrying and match the stable product ID/revision metadata.
-4. When no writes remain, use fresh reads with `stripe_shop_plan` `verify: true`
-   (CLI `homie-studio shop verify --have plan-input.json`). It checks the catalog,
-   actual link fields and line items, menus, slot limits and portal settings against
-   shop.json and the slot manifest. A mismatch blocks verification. It saves only public
-   configuration to `.studio/stripe-mcp.json`; local test configuration goes to `.dev.vars`.
+   That JSON file contains the same fields. `operations` contains every independent
+   operation currently ready, with method, path, parameters and create idempotency key.
+   Execute the batch through Stripe's official plugin, then replan for dependent work.
+   `next` remains the first operation for older clients.
+3. Append `{ "method": "POST", "path": "…", "params": {…}, "body": <Stripe response> }`
+   for **writes as well as reads**. Keep this setup's observations across batches.
+   Product creation includes its default Price; link creation expands line items.
+   Product and Price Search use studio/origin metadata. Existing links are fetched by
+   IDs from the verified configuration; Stripe has no Payment Link metadata search.
+   Keep `.studio/stripe-mcp.json` when moving the studio to another computer. Without
+   it, repeat creates use their idempotency keys; outside Stripe's idempotency retention
+   window, recover the studio's existing link IDs before setup to avoid duplicates.
+   Follow search `next_page` cursors. Search is eventually consistent: write responses
+   are the immediate evidence. On an uncertain write, retry its exact idempotency key;
+   never discard successful responses or invent IDs. Start a new read set when checking
+   later external edits, changing accounts, or changing mode.
+4. Call `stripe_shop_plan` with `verify: true` using those observations (CLI
+   `homie-studio shop verify --have plan-input.json`). Verification checks real fields,
+   line items, menus, slot limits and portal settings. It saves compact public Worker
+   configuration and provenance to `.studio/stripe-mcp.json`, never API response history.
+   Deploy installs those links. Checkout then reports only `webhook-secret` missing;
+   it cannot open until signed payment events can confirm orders. Changing shop.json,
+   the slot manifest or origin requires verification again. Local test configuration
+   goes to `.dev.vars`.
 5. For a deployed HTTPS studio, run `stripe_webhook` (CLI `homie-studio shop webhook`).
    Follow `studio_job`. This uses Stripe CLI only for private webhook installation,
    checks the same account as the MCP, and installs the signing secret and verified
@@ -63,7 +73,7 @@ calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
    studio profile is not already connected. MCP approval cannot be reused or exported.
    Cloudflare authorization and an existing deployment are prerequisites.
 6. After installation, perform the returned `retire` operations through Stripe MCP to
-   archive replaced catalog objects, then verify fresh reads again. Test a sandbox
+   archive replaced catalog objects. Use fresh scoped reads for later drift checks. Test a sandbox
    purchase and its signed event, order grant, booking capacity or recurring invoice;
    a browser return is never proof. Stripe CLI `trigger` can send a test event, and
    `events resend <event> --webhook-endpoint <endpoint>` retries a delivery. Check the
@@ -72,6 +82,19 @@ calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
 
 Never create a webhook through model-visible Stripe MCP: its response exposes the signing secret.
 
+**Why the separate approval (checked 2026-10-14).** Stripe's
+[event destination API](https://docs.stripe.com/api/v2/core/event-destinations/create)
+also returns its signing secret only in the private create response when explicitly
+included. Thin events still require signature verification and authenticated retrieval
+of event details; they do not supply a secret handoff to Wrangler. The
+[official MCP](https://docs.stripe.com/mcp) documents no credential or secret transfer
+to a studio Worker. Therefore the AI starts `stripe_webhook`, the owner clicks
+Approve once in Stripe's CLI browser page if needed, and the tool completes endpoint
+creation and Wrangler secret installation privately. MCP approval and CLI approval
+are separate. No API key is requested, no secret enters chat, and Homie is never in
+the money path. A connected studio CLI profile needs no further approval.
+
+
 The owner never handles an API key or signing secret. No Homie backend handles payments.
 The Worker needs only public link configuration and the signing secret; buyers pay
 Stripe directly even when the AI and the owner's computer are offline. The old

package/guides/studio-setup/SKILL.md

@@ -409,3 +409,7 @@ and slug. It fills missing generated files and retries installation, preserving
 already there. A different studio or unrelated nonempty folder is still refused.
 New studios do not request a directory listing by default; set `homie.directory: true`
 or a directory URL only when the person chooses listing.
+
+Cloudflare's official MCP request interface cannot authorize new static-asset uploads with an upload JWT; deploy with Wrangler, Cloudflare's own CLI using browser OAuth.
+
+An owner's existing Wrangler login can connect another studio without a new browser approval: in that studio run `homie-studio connector --tools <exact-tool-names> --out <private-config.json>`, then load the file directly into the AI client's connector configuration. Never print the bearer or paste the file in chat. Revoke with `homie-studio connector --revoke <id>`. See the installed `docs/toolkit-place-patterns.md` for scope and expiry.

package/lib/app-needs.mjs

@@ -1,7 +1,7 @@
 import {actInApp,waitInApp} from './app-ready.mjs';
 /** Opt-in acceptance evidence, sourced from the person's Codex, not starter labels. */
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join, resolve, relative, isAbsolute } from 'node:path';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, copyFileSync, realpathSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute, basename } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { createHash } from 'node:crypto';
 
@@ -129,6 +129,12 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
 export function saveAppNeeds(root, id, plan, needs) {
   if (!root) return;
   const dir = join(root, '.studio', 'checks'); mkdirSync(dir, { recursive: true });
+  needs=needs.map(need=>({...need,captures:(need.captures??[]).map(file=>{
+    const source=realpathSync(resolve(root,file)),rel=relative(realpathSync(root),source);
+    if(!rel.startsWith('..')&&!isAbsolute(rel))return rel;
+    const target=join(dir,`${id}-${createHash('sha256').update(source).digest('hex').slice(0,12)}-${basename(source)}`);
+    copyFileSync(source,target);return relative(root,target);
+  })}));
   writeFileSync(join(dir, `${id}-needs.json`), JSON.stringify({ at: new Date().toISOString(), codexHash: plan.hash, needs }, null, 2));
 }
 

package/lib/app-ready.mjs

@@ -56,6 +56,28 @@ export async function actInApp(surface, selector, action, {ready=appReady,timeou
   for (;;) {
     try {
       await waitInApp(surface,selector,frame=>frame.waitForSelector(selector,{visible:true,timeout:Math.max(1,end-Date.now())}),{ready,timeout:Math.max(1,end-Date.now())});
+      const handle=await surface.frame.$?.(selector);
+      if(handle)try {
+        await handle.scrollIntoView();
+        const point=await handle.clickablePoint();
+        const ancestors=[];
+        for(let frame=surface.frame;frame.parentFrame();frame=frame.parentFrame())ancestors.unshift(await frame.frameElement());
+        const describeHit=(el,p)=>{
+          const hit=document.elementFromPoint(p.x,p.y);
+          return hit&&!el.contains(hit)?hit.tagName.toLowerCase()+(hit.id?'#'+hit.id:'')+[...hit.classList].map(c=>'.'+c).join(''):null;
+        };
+        let local={...point};
+        try {
+          for(const ancestor of ancestors){
+            const covered=await ancestor.evaluate(describeHit,local);
+            if(covered)throw new Error(`${surface.name}: ${selector} is covered at the click point by ${covered}`);
+            const offset=await ancestor.evaluate(el=>{const r=el.getBoundingClientRect();return {x:r.x+el.clientLeft,y:r.y+el.clientTop};});
+            local={x:local.x-offset.x,y:local.y-offset.y};
+          }
+          const covered=await handle.evaluate(describeHit,local);
+          if(covered)throw new Error(`${surface.name}: ${selector} is covered at the click point by ${covered}`);
+        }finally{await Promise.all(ancestors.map(h=>h.dispose()));}
+      }finally{await handle.dispose();}
       return await action(surface.frame);
     } catch(error) {
       if(!/node is detached|element.*(?:detach|stale)|stale.*element/i.test(error.message)) {
@@ -69,3 +91,12 @@ export async function actInApp(surface, selector, action, {ready=appReady,timeou
     }
   }
 }
+
+/** Install before navigation: every app iframe observes a real context creation failure. */
+export function forceWebglFailure() {
+ for(const proto of [globalThis.HTMLCanvasElement?.prototype,globalThis.OffscreenCanvas?.prototype]) {
+  if(!proto)continue;
+  const original=proto.getContext;
+  proto.getContext=function(kind,...args){return /^(webgl2?|experimental-webgl)$/.test(kind)?null:Reflect.apply(original,this,[kind,...args]);};
+ }
+}

package/lib/check.mjs

@@ -1,6 +1,6 @@
 import {needsHeadless} from './needs-headless.mjs';
 import {randomBytes} from 'node:crypto';
-import {actInApp,appReady,observeEffects,waitInApp,answerDialogs} from './app-ready.mjs';
+import {actInApp,appReady,observeEffects,forceWebglFailure,waitInApp,answerDialogs} from './app-ready.mjs';
 import {localCredential,localCookie} from './local-test.mjs';
 import { readAppNeeds, proveAppNeeds, saveAppNeeds } from './app-needs.mjs';
 /**
@@ -132,7 +132,7 @@ export function judgeRounds(browsers, missed = new Map()) {
   return null;
 }
 
-export async function check({ isolate = true, root = null, url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
+export async function check({ webglFailure = false, isolate = true, root = null, url, game, roundTimeoutMs = 150_000, rounds = 3, shots = null, userAgentTag = 'homie-studio-check', log = () => {}, report = null }) {
   if (!url || !game) throw new Error('usage: homie-studio check <game> --url <site url>');
   const base = String(url).replace(/\/+$/, '');
   const play = `${base}/${game}/play`;
@@ -152,14 +152,15 @@ export async function check({ isolate = true, root = null, url, game, roundTimeo
   if(appMeta && !appMeta.check?.action) {
     try {
       const plan=readAppNeeds(root,game);
-      if(plan && !plan.needs.some(n=>[...(n.steps??[]),...(n.assertions??[])].some(i=>i.surface)))return checkApp({isolate,root,url:base,game,meta:appMeta,shots,log,report});
+      if(plan && !plan.needs.some(n=>[...(n.steps??[]),...(n.assertions??[])].some(i=>i.surface)))return checkApp({webglFailure,isolate,root,url:base,game,meta:appMeta,shots,log,report});
     } catch(error) {return {ok:false,command:'check',kind:'app',why:error.message};}
   }
   const chrome = findChrome();
   if (!chrome) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
   try { puppeteer = (await import('puppeteer-core')).default; } catch { return { ok: false, command: 'check', why: 'puppeteer-core is not installed (it comes with @homie-rocks/studio; run npm install)' }; }
-  if (appMeta) return checkApp({ isolate, root, url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
+  if (appMeta) return checkApp({ webglFailure, isolate, root, url: base, game, meta: appMeta, shots, log, report, puppeteer, chrome });
+  if(webglFailure)return {ok:false,command:'check',why:'--webgl-failure requires an app with UI checks'};
   if (shots) mkdirSync(shots, { recursive: true });
   const profiles = [];
   const browsers = [];
@@ -354,7 +355,7 @@ export async function check({ isolate = true, root = null, url, game, roundTimeo
 }
 
 /** Apps prove a real action crossing surfaces and a reconnect, without inventing a round. */
-export async function checkApp({ isolate = true, root = null, url, game, meta, shots = null, log = () => {}, report = null, puppeteer, chrome }) {
+export async function checkApp({ webglFailure = false, isolate = true, root = null, url, game, meta, shots = null, log = () => {}, report = null, puppeteer, chrome }) {
   let plan;
   try { plan = readAppNeeds(root, game); } catch (error) { return { ok: false, command: 'check', kind: 'app', why: error.message }; }
   const secret=localCredential(root,url);
@@ -364,6 +365,7 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
   const proof = meta.check??{};
   const baseline=typeof proof.action==='string'&&typeof proof.observe==='string';
   if (!baseline && !plan) return { ok: false, command: 'check', kind: 'app', why: 'app.json check needs action and observe CSS selectors for a real shared action' };
+  if(webglFailure&&!baseline&&!plan?.needs.some(n=>[...(n.steps??[]),...(n.assertions??[])].some(i=>i.surface)))return {ok:false,command:'check',why:'--webgl-failure requires UI steps or assertions'};
   const captureWarnings=[];
   const profile = mkdtempSync(join(tmpdir(), 'homie-app-check-'));
   let browser;
@@ -382,6 +384,7 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
       const page=await context.newPage();
       answerDialogs(page,name,dialogs,report);
       await page.evaluateOnNewDocument(observeEffects);
+      if(webglFailure)await page.evaluateOnNewDocument(forceWebglFailure);
       const [width,height]=dimensions[name];
       await page.setViewport({width,height,isMobile:name!=='wall',hasTouch:name!=='wall'});
       const params=new URLSearchParams(proof.params??{});params.set('room',room);params.set('role',role);params.set('surface',name==='staff'?'tablet':name==='phone-two'?'phone':name);
@@ -423,7 +426,7 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
     const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report, ready:appReady, root, headless:needsHeadless({url,secret,app:game,meta,scope:isolate?room:null}) }) : null;
     if (plan) { saveAppNeeds(root, game, plan, needs); const { refreshCodexFile } = await import('./codex.mjs'); refreshCodexFile(root, game); }
     const ok = !needs || needs.every(n => n.status === 'met');
-    return { ok, ...(needs ? { needs, why: ok ? undefined : 'Some needs from the person’s Codex are not yet met; see needs and captures' } : {}), command: 'check', kind: 'app', isolatedRecords:isolate, captureWarnings, dialogs, room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: baseline };
+    return { ok, ...(needs ? { needs, why: ok ? undefined : 'Some needs from the person’s Codex are not yet met; see needs and captures' } : {}), command: 'check', kind: 'app', webglFailure, isolatedRecords:isolate, captureWarnings, dialogs, room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: baseline };
   } catch (error) { return { ok: false, command: 'check', kind: 'app', dialogs, why: error.message }; }
   finally { await browser?.close().catch(() => {}); rmSync(profile, { recursive: true, force: true }); }
 }