@homie-rocks/studio 0.51.5 → 0.51.7

package/CHANGELOG.md

@@ -17,6 +17,39 @@ 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.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**
+
+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**

package/apps/APPS.md

@@ -181,3 +181,44 @@ 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.
+
+
+## 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

@@ -514,7 +514,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':

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/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.
 
@@ -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,45 @@ 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.
+
+
+## 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/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