@homie-rocks/studio 0.51.1 → 0.51.3

package/CHANGELOG.md

@@ -17,6 +17,51 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.51.3] - 2026-10-14
+
+**Plugin 0.51.3**
+
+Business and cause apps use their own words, count every paid monthly gift, and test real Stripe checkout locally.
+
+### Added
+
+- Local real Stripe test checkout: `shop connect --local --profile <sandbox> --url <Wi-Fi address>` syncs test Payment Links without Cloudflare or a public webhook. Stripe CLI forwards signed events to `dev`; phones return to the same Wi-Fi thank-you page.
+- App acceptance needs can name a checkout popup, interact with it, and continue asserting the original phone.
+
+### Fixed
+
+- Monthly subscription invoices create deduplicated paid orders and app events with the original reference, so every gift reaches fulfilment.
+- Business/cause menus name their own pages and apps. App shells use app names, website buttons have independent wording, thank-you pages name the organisation, and default phone sharing stays above bottom tabs.
+- Gathering is a task check-in starter with its own records and no giving or quiz workflow. App style defaults use illustration and AI refinements retain AI attribution.
+- `dev` loads root `.dev.vars`. App collections no longer stop accepting records at 1,000.
+- Requests and scheduled runs remove referral metadata recreated by an old Worker during a rolling deployment.
+- The installed app reference documents the supported local payment/checker path and distinguishes local MCP tools from hosted connector tools.
+
+### Upgrade notes
+
+- Restart local dev after updating `.dev.vars`. Local Stripe links are test-only; live connection and deployment are unchanged.
+- Existing app `screen.share` choices and authored site headers remain in control. Subscription renewals now emit `order.paid` as well as lifecycle events; fulfilment listening to both should deduplicate by payment identity.
+
+## [0.51.2] - 2026-10-14
+
+**Plugin 0.51.2** · Deploying and listing do what the studio chose, under one address.
+
+Your studio follows your listing choice, shares one public address, and keeps its apps and tools working after deploy and upgrade.
+
+### Fixed
+
+- Your studio only joins the directory when you choose to list it. Existing claims remain honoured, and you can publish a listing after an unlisted deploy.
+- Your custom domain is the shared address for pages and app links. Visitors arriving at the workers.dev address reach that domain, while app APIs, multiplayer connections and AI tools keep working.
+- Deploy shows your app, game and wall links without guessing your bill. Local database tools keep working after deploy, interrupted setup can resume, and office sign-in takes you straight to the page you requested.
+- Upgrades refresh untouched app presets and defaults while preserving your edits, including giving choices. App walls use the app's own join wording.
+- Decorative app hero frames let visitors scroll the page; apps can share and download files while keeping their sandbox protection.
+- Signed-in AI connectors can discover how to connect through `/mcp/auth`; public tools remain available through `/mcp`.
+
+### Upgrade notes
+
+- Ask Homie to upgrade your studio, install dependencies and rebuild. Existing directory claims remain honoured. To list a new studio, choose `homie.directory: true` or a directory URL before deploy.
+- Use `/mcp/auth` for staff AI connectors and `/mcp` for public connectors.
+
 ## [0.51.1] - 2026-10-14
 
 **Plugin 0.51.1** · A player's own runner never jumps across the screen.

package/README.md

@@ -110,10 +110,21 @@ is put in a studio unless the person asks for one), and its Home has a
 In the session that works in the repository, `homie-studio setup attach <hs_…> [--client claude|codex|grok]` then gives the studio
 the name chosen in the chat and removes the band.
 
-**The site claims itself in the directory.** The homie.rocks directory lists a studio only when its site serves
-the claim the directory handed out for that address. From 0.10.0 the site asks for it the first time its
-`/.well-known/homie-studio.json` is read (by `studio_publish`, or by `deploy` reading it once) and keeps it in
-its D1; nothing is stored by hand. studio.json `homie.directory: false` keeps a studio out.
+**Listing is the studio’s choice.** Set `homie.directory: true` for homie.rocks or a
+chosen directory URL before deploying. Omitted, null or false makes no new claim;
+existing stored claims remain honoured. An explicit `publish` also records the choice
+and stores the directory claim without requiring a second deploy. The manifest and
+publish use the custom domain when configured. Workers.dev browser pages redirect to
+it; discovery and tool routes remain accessible on both addresses.
+
+Deploy prints `/<id>/open` for apps, `/<id>/play` for games and `/<id>/tv` for walls.
+It reports no unmeasured Cloudflare plan. Local tools retain their dev database binding
+after the first deploy. Rerunning an interrupted `new` fills missing files without
+overwriting the matching studio’s edits. Office links sign in directly and retain
+`--to` destinations, including app and connection pages.
+
+For signed-in staff AI connectors use `/mcp/auth`; it returns a 401 OAuth discovery
+challenge without a token. `/mcp` continues to serve public tools anonymously.
 
 ## The site: the hub's shape, and a landing for every game
 

package/app-starters/gathering/app.json

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

package/app-starters/gathering/index.html

@@ -1,3 +1,3 @@
 <!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Live together</title><style>
 *{box-sizing:border-box}body{margin:0;background:var(--tone,#183b55);color:#fff7df;font-family:system-ui,sans-serif}main{min-height:100svh;padding:clamp(24px,5vw,64px);display:grid;grid-template-columns:1.1fr 1fr;gap:40px;align-items:center}h1{font-size:clamp(44px,6vw,88px);line-height:1;letter-spacing:-.05em;margin:20px 0}p{line-height:1.6;max-width:40em}#connection{font-size:12px;text-transform:uppercase;letter-spacing:.18em}.panel{background:#fff7df;color:#20352e;border-radius:28px;padding:28px;box-shadow:0 30px 80px #0003}#count{font-size:80px;font-weight:800;line-height:1}ul{padding:0;list-style:none}li{padding:12px 0;border-bottom:1px solid #20352e22}button,select,a{font:inherit;min-height:48px;border-radius:12px}button,select{padding:10px 16px;width:100%;margin-top:8px}button{background:var(--tone);color:#fff7df;border:0;cursor:pointer}button:disabled{opacity:.5}a{display:inline-flex;align-items:center;color:inherit}label{display:block;margin-top:14px}select{background:white;color:#20352e;border:1px solid #20352e66}progress{width:100%;height:22px;accent-color:var(--tone)}#status{min-height:24px}#amount{font-size:40px;font-weight:700}button:focus-visible,select:focus-visible,a:focus-visible{outline:3px solid #df9325;outline-offset:4px}.wall #controls{display:none}#giving-link[hidden],[hidden]{display:none!important}@media(max-width:650px){main{display:block;padding:72px 22px 24px}h1{font-size:46px}.panel{margin-top:24px;padding:22px}#count{font-size:58px}li{font-size:14px}}@media(max-height:520px) and (min-width:651px){main{padding:65px 25px 20px;gap:22px}h1{font-size:38px}.panel{padding:18px}}
-</style><main><header><span id="connection"></span><h1></h1><p id="intro"></p><div id="goal"><p id="goal-label"></p><div><span id="amount"></span> / <span id="target"></span></div><progress></progress></div><ul id="entries" aria-live="polite"></ul></header><section class="panel"><div id="label"></div><div id="count" data-count>0</div><div id="controls"><p id="prompt"></p><label><span id="choice-label"></span><select id="choice"></select></label><label id="frequency"><span id="frequency-label"></span><select id="monthly"><option id="once" value="once"></option><option id="month" value="month"></option></select></label><button data-action></button><a id="giving-link" href="/shop/" target="_blank" rel="noopener"></a></div><p id="status" role="status"></p></section></main><script type="module" src="./assets/main.js"></script></html>
+</style><main><header><span id="connection"></span><h1></h1><p id="intro"></p><ul id="entries" aria-live="polite"></ul></header><section class="panel"><div id="label"></div><div id="count" data-count>0</div><div id="controls"><p id="prompt"></p><label><span id="choice-label"></span><select id="choice"></select></label><button data-action></button></div><p id="status" role="status"></p></section></main><script type="module" src="./assets/main.js"></script></html>

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

@@ -3,7 +3,7 @@ import { openRoom } from '@homie-rocks/studio/rules/view';
 import type rules from './rules';
 import { createAppRecords, type AppRecord } from '@homie-rocks/studio/apps';
 import { randomId } from '@homie-rocks/studio/links';
-type Entry = { choice: string; status: string; amount: number; monthly: boolean };
+type Entry = { choice: string; status: string };
 const room = openRoom<typeof rules>();
 const net = room.net;
 const role = net.params.role ?? 'customer';
@@ -11,41 +11,29 @@ const words: Record<string, string> = app.words;
 const config = app.starter;
 const $ = <T extends HTMLElement = HTMLElement>(s: string) => document.querySelector<T>(s)!;
 const records = createAppRecords<Entry>({ collection: 'entries' });
-let rows: AppRecord<Entry>[] = [], busy = false, ready = false, question = 0;
+let rows: AppRecord<Entry>[] = [], busy = false, ready = false;
 const action = $<HTMLButtonElement>('[data-action]');
 document.body.className = role;
 document.body.style.setProperty('--tone', config.color);
 $('h1').textContent = app.name; $('#intro').textContent = app.blurb;
 $('#label').textContent = words.total; action.textContent = words.action;
 $('#choice-label').textContent = words.choice;
-$('#frequency-label').textContent = words.monthly;
-$('#once').textContent = words.once; $('#month').textContent = words.month;
-$('#giving-link').textContent = words.give;
-$('#giving-link').hidden = config.kind !== 'giving';
-$('#frequency').hidden = config.kind !== 'giving';
-$('#goal').hidden = config.kind !== 'giving';
 $('#controls').hidden = role === 'wall';
 const select = $<HTMLSelectElement>('#choice');
 function choices() {
  select.replaceChildren();
- const list = config.kind === 'quiz' ? config.questions[question]?.choices ?? [] : config.choices;
+ const list = config.choices;
  for (const value of list) { const option = document.createElement('option'); option.value = value; option.textContent = value; select.append(option); }
- $('#prompt').textContent = config.kind === 'quiz' ? config.questions[question]?.text ?? words.finished : words.prompt;
- action.hidden = config.kind === 'quiz' && question >= config.questions.length;
+ $('#prompt').textContent = words.prompt;
 }
 choices();
 function paint() {
  $('[data-count]').textContent = String(rows.length);
- const amount = rows.reduce((n, r) => n + r.data.amount, 0);
- $('#amount').textContent = new Intl.NumberFormat(undefined, { style: 'currency', currency: config.currency }).format(amount);
- $('#target').textContent = new Intl.NumberFormat(undefined, { style: 'currency', currency: config.currency }).format(config.goal);
- $<HTMLProgressElement>('progress').max = config.goal; $<HTMLProgressElement>('progress').value = amount;
- $('#goal-label').textContent = words.goal;
  action.disabled = busy || !ready;
  $('#entries').replaceChildren();
  for (const row of rows.slice(-6).reverse()) {
   const li = document.createElement('li');
-  li.textContent = `${row.data.choice} · ${row.data.status}${row.data.monthly ? ' · ' + words.month : ''}`;
+  li.textContent = `${row.data.choice} · ${row.data.status}`;
   if (role === 'staff' && row.data.status !== words.done) {
    const button = document.createElement('button'); button.textContent = words.complete;
    button.onclick = () => { void records.update(row, { ...row.data, status: words.done }).then(refresh).catch(e => { $('#status').textContent = e.message; }); }; li.append(button);
@@ -61,9 +49,8 @@ action.onclick = async () => {
  busy = true; paint();
  try {
   const choice = select.value;
-  await records.create({ choice: config.kind === 'quiz' ? `${question + 1}. ${choice}` : choice, status: words.pending, amount: config.kind === 'giving' ? Number(choice) : 0, monthly: $<HTMLSelectElement>('#monthly').value === 'month' }, randomId());
+  await records.create({ choice, status: words.pending }, randomId());
   $('#status').textContent = words.thanks;
-  if (config.kind === 'quiz') { question++; choices(); }
   room.command('refresh', {}); await refresh();
  } catch (error) { $('#status').textContent = (error as Error).message; }
  finally { busy = false; paint(); }

package/apps/APPS.md

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

package/bin/homie-studio.mjs

@@ -507,25 +507,25 @@ function print(result) {
       lines.push(JSON.stringify(result.result, null, 2));
       break;
     case 'deploy':
-      if (result.mcp) lines.push(`Connect your AI: ${result.mcp} (approve in your studio's browser page; no key)`);
+      if (result.mcp) lines.push(`Connect your AI: ${result.mcp}/auth (approve in your studio's browser page; no key)`);
       if (result.ci) {
-        lines.push(`Live: ${result.url ?? '(Wrangler printed no address)'}${result.commit ? ` (commit ${result.commit.slice(0, 7)}${result.branch ? ` on ${result.branch}` : ''})` : ''}`, ...result.steps.map((x) => `  ${x.what}`), ...result.games.map((g) => `  ${g.id}: ${g.play}${g.hash ? `  [${deployWords(g)}]` : ''}`));
+        lines.push(`Live: ${result.url ?? '(Wrangler printed no address)'}${result.commit ? ` (commit ${result.commit.slice(0, 7)}${result.branch ? ` on ${result.branch}` : ''})` : ''}`, ...result.steps.map((x) => `  ${x.what}`), ...result.games.map((g) => `  ${g.id}: ${g.open ?? g.play}${g.hash ? `  [${deployWords(g)}]` : ''}${g.wall ? `  wall: ${g.wall}` : ''}`));
         break;
       }
       lines.push(`Live: ${result.url}`, ...(result.workersDev && result.workersDev !== result.url ? [`  also at ${result.workersDev}`] : []),
         ...(result.local ? [`  (the workers.dev address names your Cloudflare account, so it is kept in ${result.local} on this computer, never in studio.json)`] : []),
         // Which games this deploy changed since the last deploy from here, and each one's build hash
         // (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.play}${g.hash ? `  [${deployWords(g)}]` : ''}`), ...(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)'}. All on the free Workers plan${result.r2 ? ' plus R2' : ''}.`,
-        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 yet (the site claims itself when the directory first reads it; publish does).',
+        ...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.standalone?.length ? ['', ...result.standalone] : []));
       break;
     case 'deploy plan':
       lines.push(`What \`npm run deploy\` does for ${result.studio}, on the Cloudflare account the person approves:`, '',
         ...result.cloudflare.map((r) => `  ${r.kind}${r.name ? ` ${r.name}` : ''}: ${r.what} [${r.state}${r.plan ? `; ${r.plan}` : ''}]`), '',
-        `Cost: ${result.cost}`, `Sign-in: ${result.login}`, `Address: ${result.address}`,
-        `The directory (${result.directory.site}) stores: ${result.directory.stores}`, result.never,
+        ...(result.cost ? [`Cost: ${result.cost}`] : []), `Sign-in: ${result.login}`, `Address: ${result.address}`,
+        result.directory.choice, ...(result.directory.site ? [`The directory (${result.directory.site}) stores: ${result.directory.stores}`] : []), result.never,
         ...(result.zone?.warning ? ['', `Warning: ${result.zone.warning}`] : result.zone?.why ? ['', result.zone.why] : []),
         ...(result.parts && partsPlanLines(result.parts).length ? ['', ...partsPlanLines(result.parts)] : []),
         ...(result.standalone?.length ? ['', ...result.standalone] : []));
@@ -846,7 +846,7 @@ const OUTWARD_FLAGS = {
   'chat remove': ['url', 'all'], 'chat budget': ['url'],
   'servers close': ['url', 'reopen'], 'servers level': ['url'], 'servers member': ['url', 'role', 'remove'],
   'parts reissue': ['claim-hash', 'receipt-verified', 'buyer'], 'parts retire': [], 'parts keys': [], 'parts refund': ['game'],
-  'shop connect': ['url', 'managed', 'live', 'manual', 'renew', 'from-clipboard'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note', 'manual-transaction'],
+  'shop connect': ['local', 'profile', 'url', 'managed', 'live', 'manual', 'renew', 'from-clipboard'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note', 'manual-transaction'],
   'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
   'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
   'events webhook': ['url','after'],
@@ -1115,6 +1115,10 @@ async function main() {
     if (!sub) return shopStatus(root, { url });
     if (sub === 'init') return shopInit(root, { supporter: flags.has('supporter'), giving: flags.has('giving'), currency: flags.get('currency') ?? null, price: flags.get('price') ?? 500, managed: flags.has('managed') });
     if (sub === 'check') return shopCheck(root);
+    if (sub === 'connect' && flags.has('local')) {
+      if(flags.has('live'))throw new Error('Local checkout requires test mode');
+      return (await import('../lib/shop-local.mjs')).shopConnectLocal(root,{url:flags.get('url'),profile:flags.get('profile')});
+    }
     if (sub === 'connect') return shopConnect(root, { managed: flags.has('managed') ? true : null, live: flags.has('live'), manual: flags.has('manual'), fromClipboard: flags.has('from-clipboard'), renew: flags.has('renew'), log: (line) => process.stderr.write(`${line}\n`) });
     if (sub === 'disconnect') return shopDisconnect(root);
     if (sub === 'catalog') {

package/guides/app/SKILL.md

@@ -6,6 +6,12 @@ compatibility: Node 22 and Chrome; the studio's pinned toolkit and Wrangler.
 
 # Make an app
 
+For the installed version’s payment, records and local-check contracts, start with
+`node_modules/@homie-rocks/studio/apps/APPS.md`. Its “Real Stripe test checkout on
+this computer” section is the supported offline-hosting path: real Stripe test
+checkout, CLI webhook forwarding, root `.dev.vars`, Wi-Fi return pages and named
+checkout popups. Use an existing approved sandbox profile; no deploy is needed.
+
 An app is **one screen, its roles, and its parts**. The screen transforms with the person and the work: a camera moves, a ticket unfolds, controls appear in context. Do not build page-to-page navigation, a sidebar of links, or a conventional admin website inside it. A studio's public website can still have pages around the app.
 
 Read the person's brief and existing `apps/<id>/` first. Choose sensible engineering defaults from the brief; never ask the person how to implement shared state. A business or cause needs no game demo, mandatory entertainment, invented customers, scores or rounds. Never impose a shop, directory listing, sign-in for public visitors, or paid media. Make the fewest human steps possible; run commands yourself.
@@ -38,7 +44,7 @@ Before writing scene components:
 
 1. Run `style init <id> --prompt "<the person's own scene words>"`. Record the direction in the Codex: composition, camera, materials, colour, typography and motion. Use the same style machinery as games, not the starter's default theme.
 2. Inspect the installed `@homie-rocks/*` packages for mechanisms. `geom`, `props`, `render`, `camera`, `postfx` and `fx` can make the place; `input`, `ui`, `ui-world`, `device`, `audio` and `loop` make it usable. Read the package exports and examples rather than guessing imports. Install every dependency reported by the starter or parts before building.
-3. Search `parts_find` for each meaningful piece; shell equivalent: `homie-studio parts find "<piece>"`. Read its contract, source studio and licence. Add fitting pieces with `part_add` / `parts add`; write the missing parts yourself. The example studios share real app pieces: search for venue, workshop, giving, arrivals, scene, queue and sound, not just game characters. If local example studios are available, read their shared `parts/` and manifests without modifying the source studios. A failed catalogue request is not proof that nothing exists.
+3. Search the local toolkit MCP `parts_find` for each meaningful piece (the hosted connector may not expose it); shell equivalent: `homie-studio parts find "<piece>"`. Read its contract, source studio and licence. Add fitting pieces with `part_add` / `parts add`; write the missing parts yourself. The example studios share real app pieces: search for venue, workshop, giving, arrivals, scene, queue and sound, not just game characters. If local example studios are available, read their shared `parts/` and manifests without modifying the source studios. A failed catalogue request is not proof that nothing exists.
 4. Use the art/models/sound/music skills with connected providers and an authorized budget. Generate distinctive assets when useful. If no provider is connected, continue with original geometry, locally drawn SVG, CC0 assets and local synthesized sound. Report the means honestly. Provider absence never justifies replacing the scene with a board.
 5. Record packages, parts with attribution, original work and media routes under **Built from**. Keep costs and provenance visible.
 
@@ -124,7 +130,7 @@ Without Stripe, keep real services and prices visible and say payment is not con
 - `apps/<id>/app.json` describes roles (`signIn`, `can`), surfaces (`phone`, `wall`, `kiosk`, `tablet`), wording, record collections, parts and the real UI action used by check. The app's entry and assets live beside it, just like a game.
 - Before inventing each component, inspect engine packages for the mechanism and `parts_find` for the piece. A queue, quiz, menu board, live total, music loop or video intro can be a part. Record its licence and credit. Sharing happens only when requested; selling parts is not part of this workflow.
 - Use the same engine packages as a game: `@homie-rocks/geom` and `props` for original scenery; `render`, `camera`, `postfx`, `fx` for light, composition and motion; `input`, `ui`, `ui-world`, `audio`, `device`, `loop` for interaction and feel. An app can be fully 3D and wild. Legibility and the actual task come first.
-- Use the `style`, `art`, `models`, `animate`, `sound`, `music`, `video` and `perf` skills where they help. It should look like a game studio made it: a coherent world with a useful HUD, not generic cards and navigation. Media cost and licensing decisions remain the person's.
+- Use the `style`, `art`, `models`, `animate`, `sound`, `music`, `video` and `perf` skills where they help. Give the organisation a coherent scene with readable controls and purposeful motion. Media cost and licensing decisions remain the person's.
 - Keep native buttons at least 44 px, keyboard focus visible, text as text, motion reducible, and the wall QR clear of useful information. Pointer gesture guards belong on the canvas, not native click buttons.
 
 ## Roles and records
@@ -268,3 +274,17 @@ Use the Manage my gifts link for the buyer-owned Stripe portal in the shop.
 For a records-only booking app, use `createShop({target: parent})` inside its
 sandboxed view. The shell includes the authenticated shop bridge; do not add a
 room simulation merely to make a payment button work.
+
+## Frames and upgrades (0.51.1)
+
+App frames permit Web Share and downloads, while keeping their opaque-origin
+sandbox. Share still requires the guest’s click and browser support; offer a download
+or copy link too. Both the iframe permissions and the served frame’s CSP matter.
+Use `.hero-media` for a decorative iframe in a site hero: it lets scroll gestures
+reach the page. An intentionally interactive hero frame opts in with `data-interactive`.
+App shells allow normal touch scrolling and selection.
+
+Upgrade compares copied app presets with recorded toolkit versions. Unchanged
+preset files and default values take the new version; custom scene files, names and
+edited labels remain the studio’s. An app wall uses its join label rather than game
+instructions. Rebuild after upgrade and inspect both the wall and giving page.

package/guides/office/SKILL.md

@@ -147,3 +147,12 @@ Before Stripe is connected, both live and local shop/giving pages show items and
 amounts with checkout disabled and clear not-taking-payment wording. A fresh studio
 has an empty `/shop/` preview. `dev` watches authoring HTML/CSS/JS; check reports
 accepted dialogs and precise waits, and reacquires frames during rebuilds.
+
+## Direct sign-in links (0.51.1)
+
+`office link --to /<app>/open` and `--to /_studio/office/connections` retain the
+same-site destination, including its query string. Opening the link signs the browser
+in and continues there. A plain link-preview GET spends nothing; the loaded page
+submits the same-origin sign-in form. Keep the link private.
+Local office and role commands reuse the running dev server’s D1 configuration even
+after deploy records the production database id.

package/guides/shop/SKILL.md

@@ -173,3 +173,11 @@ CLI fixture/API tokens; never enter card digits into a page. The local listener
 for development; production sends signed events directly to the studio's webhook.
 The optional keyed fixture remains available for testing explicitly selected session
 checkout. Label offline fixtures simulations.
+
+## Local Stripe test payments
+
+Use `shop connect --local --profile <sandbox-profile> --url http://<Wi-Fi-IP>:8787`
+and Stripe CLI `listen --all-snapshot --forward-to http://localhost:8787/api/shop/hook`. The full
+recipe is in the installed toolkit’s `apps/APPS.md`, “Real Stripe test checkout on
+this computer”. It uses root `.dev.vars`, needs no public HTTPS or Cloudflare, and
+keeps the existing approved Stripe CLI session. Do not write a stand-in checkout.

package/guides/studio-setup/SKILL.md

@@ -338,7 +338,7 @@ existing Cloudflare sign-in to create DNS and TLS. Never ask the person for a zo
 or wildcard route already on that domain belongs to another site there, and the deploy's warning gives the
 one line to add instead (the `publish` skill has the rest).
 
-**The directory, only when asked.** Going online never lists a studio: listing in the homie.rocks directory
+**The directory, only when asked.** A deploy never opts a studio in by itself: listing in the homie.rocks directory
 is its own step, it is public, and it is the person's to ask for. When they asked to be listed (in their first
 message or now), or say yes when you offer it once the site is live, call the Homie MCP tool `studio_publish`
 with the live site address (without the connector, `npx --no-install homie-studio publish`). It lists the
@@ -417,3 +417,11 @@ there (checked by SHA-256, at the same addresses); `homie-studio media move --dr
 Every studio serves its own MCP at `<site>/mcp`. Use the `tools` skill for studio-defined business actions, signed integrations and staff AI access. Reuse office and app-record built-ins first. After an authorized deploy, hand over the MCP address and `<site>/_studio/office/connections`: the person approves with the studio account they already have, with no key to copy. Staff connect their own account and retain only their app grants. Client connector setup is separate from the studio approval. Never deploy merely to set up a local tool test.
 
 For a business or cause, use `studio_scaffold {name, kind:"business"}` or `homie-studio new <folder> --kind cause`. Continue directly with the app skill and the appropriate `app new --from` starter; no game demo or planning interview unless requested.
+
+## Resuming setup (0.51.1)
+
+If `homie-studio new` was interrupted, rerun it in the same folder with the same name
+and slug. It fills missing generated files and retries installation, preserving files
+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.

package/lib/app-needs.mjs

@@ -24,6 +24,8 @@ export function readAppNeeds(root, id) {
 /** Run real UI actions. A failed or absent flow stays visible; continue collecting other needs. */
 export async function proveAppNeeds({ plan, surfaces, shots, report, ready = async () => {} }) {
   const results = [];
+  const appBarrier=ready;
+  ready=async s=>{await s.page.bringToFront?.();if(s.external){s.frame=s.page.mainFrame();return;}await appBarrier(s);};
   let activeRole;
   const surface = name => { const s = surfaces.find(s => s.name === name && (!activeRole || s.role === activeRole)) ?? surfaces.find(s => s.name === name); if (!s) throw new Error(`unknown surface ${name}`); return s; };
   for (const need of plan.needs) {
@@ -33,7 +35,8 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
     const result = { id: need.id, statement: need.statement, status: 'not', captures: [] };
     try {
       if (!Array.isArray(need.assertions) || !need.assertions.length) throw new Error('need requires assertions on its named surfaces');
-      for (const name of names) { const s = surface(name); if (need.role && s.role !== need.role) throw new Error(`${name} requires role ${need.role}, got ${s.role ?? 'unspecified'}`); }
+      const popupNames=new Set((need.steps??[]).map(s=>s.popup).filter(Boolean));
+      for (const name of names) { if(popupNames.has(name))continue; const s = surface(name); if (need.role && s.role !== need.role) throw new Error(`${name} requires role ${need.role}, got ${s.role ?? 'unspecified'}`); }
       for (const name of new Set(need.assertions.filter(a => a.effect).map(a => a.surface))) await surface(name).frame.evaluate(() => { window.__homieNeedsEffects = []; });
       for (const step of need.steps ?? []) {
         const target=surface(step.surface);
@@ -43,7 +46,19 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
         if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await ready(surface(step.surface)); continue; }
         await waitInApp(target,step.selector,f=>f.waitForSelector(step.selector, { visible: true, timeout:10000 }),{ready});
         const frame=target.frame;
-        if (step.click) await frame.click(step.selector);
+        if (step.click && step.popup) {
+          let listener,timer;
+          const opened=new Promise((resolve,reject)=>{
+            listener=popup=>resolve(popup);page.once('popup',listener);
+            timer=setTimeout(()=>reject(new Error('payment popup did not open')),10000);
+          });
+          try {
+            const [popup]=await Promise.all([opened,frame.click(step.selector)]);
+            surfaces.push({name:step.popup,page:popup,frame:popup.mainFrame(),external:true,role:target.role});
+            await page.bringToFront();
+          } finally {clearTimeout(timer);page.off('popup',listener);}
+        }
+        else if (step.click) {await frame.click(step.selector);await page.bringToFront?.();}
         else if (step.fill !== undefined) { await frame.$eval(step.selector, el => { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }); await frame.type(step.selector, String(step.fill)); }
         else if (step.select !== undefined) await frame.select(step.selector, String(step.select));
         else throw new Error('step needs click, fill, select or reload');