@homie-rocks/studio 0.51.3 → 0.51.5

package/guides/music/scripts/music.mjs

@@ -1,31 +1,11 @@
 #!/usr/bin/env node
-/**
- * music.mjs — songs and game scores for a Homie studio, made with ElevenLabs
- * Music through the creator's own account, mastered, looped on bar lines, and
- * published as a song page on the studio's site.
- *
- *   check                                   the provider road, the plan, credits left, the rights, ffmpeg, the studio
- *   quote --seconds <s> [--vocals]          the credit cost before anything is rendered
- *   budget <slug> --cap <credits>           the cap the person approved for this song (refuses anything past it)
- *   plan <slug> --spec <spec.json>          a composition plan with bar-exact sections (free, local)
- *   render <slug> [--dry-run] [--yes]       ONE paid render of the plan (or --prompt/--seconds); --dry-run sends nothing
- *   lyrics <slug> [--render <n>]            the transcription check: is every planned line actually sung?
- *   reconcile <slug>                        settle receipts the account had not reported yet (its balance can lag)
- *   master <slug> [--lufs -14] [--tp -1]    two-pass loudness to a target, measured after
- *   loop <slug> --bars <n> [--from-bar <k>] a seamless loop cut on bar lines (WAV + OGG), seam measured
- *   stems <slug> [--yes]                    stems from the provider (paid; priced by measurement)
- *   analyze <file>                          duration, loudness, tempo and beat grid of any audio file
- *   add <slug> --title "<t>" [--blurb] [--kind song|score|loop] [--for-game <id>] [--publish]
- *                                           the entry in music/manifest.json from what is in music/<slug>/
- *   publish <slug>                          media to R2 when the studio has it, rebuild and redeploy, check the page
- *
- * Everything prints a few lines; --json prints the result. Nothing prints a key.
- */
+/** music.mjs: local asset preparation only. Generation, schemas and pricing belong to the official provider MCP.
+ * Read ../SKILL.md for the current workflow. */
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { beatsOf, decodeMono, loudness, need, probe, run } from './lib/audio.mjs';
-import { composeDetailed, dryRun, quoteCredits, rightsFor, road, separateStems, subscription, transcribe } from './lib/eleven.mjs';
+
 import { SLUG, checkBudget, getEntry, readBudget, readJson, receipt, rel, requireStudio, setBudget, studioHasMediaPages, upsertEntry, writeJson } from './lib/studio.mjs';
 
 const argv = process.argv.slice(2);
@@ -55,12 +35,7 @@ function jobDir(root, slug) {
 /* ---------------------------------------------------------------- check / quote / budget */
 
 async function check() {
-  const r = road();
-  const out = { ok: true, command: 'check', road: r.road, cli: r.cli ?? null, ffmpeg: need('ffmpeg') && need('ffprobe') };
-  if (!r.road) { out.ok = false; out.why = r.why; }
-  else {
-    try { const s = await subscription(r); out.plan = s; out.rights = rightsFor(s.tier); } catch (error) { out.ok = false; out.why = error.message; }
-  }
+  const out = { ok: true, command: 'check', ffmpeg: need('ffmpeg') && need('ffprobe'), generation: 'Use the official ElevenLabs MCP in your AI client' };
   let root = null;
   try { root = requireStudio(); } catch (error) { out.studio = { ok: false, why: error.message }; }
   if (root) out.studio = { ok: true, root, pages: studioHasMediaPages(root) };
@@ -68,18 +43,6 @@ async function check() {
   return out;
 }
 
-async function quote() {
-  const seconds = Number(flags.get('seconds'));
-  if (!(seconds >= 3 && seconds <= 600)) throw new Error('--seconds must be 3..600 (ElevenLabs Music renders 3 s to 10 min)');
-  const q = quoteCredits(seconds, { vocals: flags.has('vocals') });
-  let plan = null;
-  try { plan = await subscription(); } catch { /* quote without the account */ }
-  const fits = plan ? q.total <= plan.remaining : null;
-  const cap = flags.has('budget') ? Number(flags.get('budget')) : null;
-  const longest = cap ? Math.floor(cap / (q.total / seconds)) : null;
-  return { ok: true, command: 'quote', seconds, credits: q, plan, fitsInPlan: fits, budget: cap, longestWithinBudget: longest };
-}
-
 function budget(root) {
   const slug = pos[1];
   const cap = Number(flags.get('cap'));
@@ -143,7 +106,7 @@ function plan(root) {
   if (specFile !== join(dir, 'spec.json')) writeJson(join(dir, 'spec.json'), spec);
   const p = buildPlan(spec);
   writeJson(join(dir, 'plan.json'), { title: spec.title ?? slug, bpm: p.bpm, key: spec.key ?? null, beatsPerBar: p.beatsPerBar, bars: p.bars, totalMs: p.totalMs, vocals: p.vocals, lyrics: p.lyrics, composition_plan: p.plan });
-  const q = quoteCredits(p.totalMs / 1000, { vocals: p.vocals });
+  const q = { status: 'unknown', next: 'Quote through the official ElevenLabs MCP before generation' };
   return { ok: true, command: 'plan', slug, seconds: p.totalMs / 1000, bars: p.bars, bpm: p.bpm, vocals: p.vocals, sections: p.plan.chunks.map((c) => ({ text: c.text.split('\n')[0], ms: c.duration_ms })), warnings: p.warnings, quote: q, file: rel(root, join(dir, 'plan.json')) };
 }
 
@@ -154,76 +117,9 @@ function plan(root) {
  * +445 a minute later). Wait up to ~40 s for it to move; null when it has not (the receipt then holds
  * the quote and is marked pending, and `reconcile` settles it later).
  */
-async function settle(r, beforeUsed) {
-  for (let i = 0; i < 10; i++) {
-    const s = await subscription(r).catch(() => null);
-    if (s && s.used > beforeUsed) return { delta: s.used - beforeUsed, after: s };
-    await new Promise((ok) => setTimeout(ok, Number(process.env.MUSIC_SETTLE_MS ?? 4000)));
-  }
-  return { delta: null, after: await subscription(r).catch(() => null) };
-}
 
-function nextRender(dir) {
-  const ns = readdirSync(join(dir, 'work')).map((f) => /^render-(\d+)\./.exec(f)?.[1]).filter(Boolean).map(Number);
-  return ns.length ? Math.max(...ns) + 1 : 1;
-}
 
-async function render(root) {
-  const slug = pos[1];
-  const dir = jobDir(root, slug);
-  const p = readJson(join(dir, 'plan.json'), null);
-  let body; let seconds; let vocals = false;
-  if (flags.has('prompt')) {
-    seconds = Number(flags.get('seconds'));
-    if (!(seconds >= 3 && seconds <= 600)) throw new Error('--seconds 3..600 with --prompt');
-    if (!flags.has('instrumental')) throw new Error('a prompt-only render is for instrumentals (--instrumental): words go through a composition plan (`plan`), because a prompt with lyrics has come back with nothing sung');
-    body = { prompt: String(flags.get('prompt')), music_length_ms: Math.round(seconds * 1000), force_instrumental: true, model_id: 'music_v2' };
-  } else {
-    if (!p) throw new Error(`no plan for ${slug}: run \`plan ${slug} --spec <spec.json>\` first (or --prompt ... --instrumental --seconds n)`);
-    seconds = p.totalMs / 1000; vocals = p.vocals;
-    body = { model_id: 'music_v2', composition_plan: p.composition_plan, with_timestamps: true };
-  }
-  const q = quoteCredits(seconds, { vocals });
-  if (flags.has('dry-run')) {
-    const d = dryRun(body, { outputFormat: OUTPUT_FORMAT });
-    return { ok: d.ok, command: 'render', dryRun: true, slug, seconds, quote: q, ...d };
-  }
-  const b = checkBudget(dir, q.music, { provider: 'elevenlabs', unit: 'credits' });
-  if (!flags.has('yes')) {
-    return { ok: false, command: 'render', slug, needs: 'approval', seconds, quote: q, budget: { cap: b.cap, spent: b.spent }, why: `This render costs about ${q.music} credits (${q.basis}). Tell the person that, and render with --yes once they say go.` };
-  }
-  const n = nextRender(dir);
-  const pending = join(dir, 'work', `render-${n}.pending`);
-  const stale = readdirSync(join(dir, 'work')).find((f) => f.endsWith('.pending'));
-  if (stale && !flags.has('again')) throw new Error(`work/${stale} says an earlier render was sent and never came back; it may have been billed. Check the account's history, then run again with --again if the person agrees`);
-  if (stale) rmSync(join(dir, 'work', stale));
-  const r = road();
-  const before = await subscription(r);
-  if (before.remaining < q.music) throw new Error(`the account has ${before.remaining} credits left and this needs about ${q.music}; nothing was sent (ElevenLabs does not go over on this plan: ${before.canGoOver ? 'it can' : 'it cannot'})`);
-  writeJson(pending, { at: new Date().toISOString(), seconds, quote: q.music });
-  say(`rendering ${seconds} s (about ${q.music} credits)…`);
-  const started = Date.now();
-  const res = await composeDetailed(body, { outputFormat: OUTPUT_FORMAT });
-  rmSync(pending, { force: true });
-  if (!res.audio?.length) throw new Error('the answer had no audio in it');
-  const audio = join(dir, 'work', `render-${n}.mp3`);
-  writeFileSync(audio, res.audio);
-  writeJson(join(dir, 'work', `render-${n}.json`), { songId: res.songId, composition_plan: res.json?.composition_plan ?? null, song_metadata: res.json?.song_metadata ?? null, words: res.json?.words_timestamps ?? null });
-  const { delta: measured, after } = await settle(r, before.used);
-  const facts = probe(audio);
-  const rights = rightsFor(before.tier);
-  // The budget counts the larger of the quote and the measurement until the account has reported the real cost.
-  const line = receipt(root, dir, {
-    provider: 'elevenlabs', model: 'music_v2', requestId: res.songId, cost: measured ?? q.music, unit: 'credits', pending: measured === null,
-    quoted: q.music, measured, balanceBefore: before.used, seconds: facts.duration, artifact: rel(root, audio), plan: before.tier, rights,
-  });
-  const out = { n, file: rel(root, audio), seconds: facts.duration, askedSeconds: seconds, songId: res.songId, words: res.json?.words_timestamps?.length ?? 0, creditsQuoted: q.music, creditsMeasured: measured, creditsLeft: after?.remaining ?? null, tier: before.tier, rights, ms: Date.now() - started, receiptAt: line.at };
-  writeJson(join(dir, 'render.json'), { ...out, at: new Date().toISOString() });
-  const note = measured === null
-    ? 'the account had not reported this render\'s cost yet: the quote is counted against the budget; run `reconcile` in a minute for the real number'
-    : Math.abs(measured - q.music) > q.music * 0.5 ? 'the measured cost is far from the quote: another job on the same account may have spent at the same time' : undefined;
-  return { ok: true, command: 'render', slug, ...out, note };
-}
+
 
 /* ---------------------------------------------------------------- lyrics check */
 
@@ -264,32 +160,6 @@ export function matchLyrics(lines, heardWords, { pass = 0.75 } = {}) {
   return rows;
 }
 
-async function lyricsCheck(root) {
-  const slug = pos[1];
-  const dir = jobDir(root, slug);
-  const p = readJson(join(dir, 'plan.json'), null);
-  if (!p?.vocals) throw new Error('this song has no sung lines in its plan');
-  const last = readJson(join(dir, 'render.json'), null);
-  const n = flags.has('render') ? Number(flags.get('render')) : last?.n;
-  const file = flags.get('file') ? resolve(String(flags.get('file'))) : join(dir, 'work', `render-${n}.mp3`);
-  if (!existsSync(file)) throw new Error(`no audio at ${rel(root, file)}`);
-  const seconds = probe(file).duration;
-  const cost = Math.ceil(seconds * 0.5);
-  const b = readBudget(dir);
-  if (b) checkBudget(dir, cost, { provider: 'elevenlabs', unit: 'credits' });
-  const r = road();
-  const before = await subscription(r).catch(() => null);
-  const t = await transcribe(file, { language: flags.get('language') ?? null });
-  const measured = before ? (await settle(r, before.used)).delta : null;
-  receipt(root, dir, { provider: 'elevenlabs', model: 'scribe_v2', requestId: t.transcription_id ?? null, cost: measured ?? cost, unit: 'credits', pending: measured === null, quoted: cost, measured, balanceBefore: before?.used ?? null, seconds, artifact: rel(root, file) });
-  const words = (t.words ?? []).filter((w) => (w.type ?? 'word') === 'word');
-  const lines = p.lyrics.flatMap((s) => s.lines);
-  const rows = matchLyrics(lines, words);
-  const out = { ok: rows.every((x) => x.ok), command: 'lyrics', slug, file: rel(root, file), heard: t.text ?? '', lines: rows, missing: rows.filter((x) => !x.ok).map((x) => x.line), creditsMeasured: measured };
-  writeJson(join(dir, `lyrics-check-${n ?? 'file'}.json`), out);
-  return out;
-}
-
 /* ---------------------------------------------------------------- master */
 
 function master(root) {
@@ -396,58 +266,13 @@ function loop(root) {
 
 /* ---------------------------------------------------------------- stems */
 
-async function stems(root) {
-  const slug = pos[1];
-  const dir = jobDir(root, slug);
-  const src = flags.get('in') ? resolve(String(flags.get('in'))) : join(dir, `${slug}-master.wav`);
-  if (!existsSync(src)) throw new Error('stems of what? master first, or --in <file>');
-  const est = Math.ceil(probe(src).duration * 10);
-  checkBudget(dir, est, { provider: 'elevenlabs', unit: 'credits' });
-  if (!flags.has('yes')) return { ok: false, command: 'stems', needs: 'approval', why: `Stem separation is paid and its price is not published per second; this job's budget allows it (a guess of ${est} credits is held against the cap). Ask the person, then run with --yes.` };
-  const r = road();
-  const before = await subscription(r);
-  const zip = join(dir, 'work', 'stems.zip');
-  await separateStems(src, zip);
-  const after = await subscription(r).catch(() => null);
-  const measured = after ? after.used - before.used : null;
-  receipt(root, dir, { provider: 'elevenlabs', model: 'stem-separation', cost: measured ?? est, unit: 'credits', estimated: measured === null, artifact: rel(root, zip) });
-  const outDir = join(dir, 'stems');
-  mkdirSync(outDir, { recursive: true });
-  const u = spawnSync('unzip', ['-o', '-q', zip, '-d', outDir]);
-  if (u.status !== 0) throw new Error('could not unzip the stems');
-  return { ok: true, command: 'stems', slug, files: readdirSync(outDir).map((f) => rel(root, join(outDir, f))), creditsMeasured: measured };
-}
-
 /* ---------------------------------------------------------------- reconcile */
 
 /**
  * Settle pending receipts: the account's usage now, minus its usage before this song's first pending call,
  * is what those calls cost (plus anything else the account did meanwhile, which is said, not hidden).
  */
-async function reconcile(root) {
-  const slug = pos[1];
-  const dir = jobDir(root, slug);
-  const b = readJson(join(dir, 'budget.json'), null);
-  if (!b) throw new Error('this song has no budget.json');
-  const pendingIdx = b.calls.map((c, i) => (c.pending ? i : -1)).filter((i) => i >= 0);
-  const now = await subscription();
-  if (!pendingIdx.length) return { ok: true, command: 'reconcile', slug, pending: 0, spent: b.spent, creditsLeft: now.remaining };
-  const first = b.calls[pendingIdx[0]];
-  if (first.balanceBefore == null) throw new Error('the pending call has no balance reading to settle from');
-  const settledBefore = b.calls.slice(pendingIdx[0]).filter((c) => !c.pending).reduce((a, c) => a + (c.cost || 0), 0);
-  const delta = now.used - first.balanceBefore - settledBefore;
-  const quoted = pendingIdx.reduce((a, i) => a + (b.calls[i].quoted ?? b.calls[i].cost), 0);
-  if (delta <= 0) return { ok: false, command: 'reconcile', slug, why: 'the account still shows no change since the render; try again in a minute' };
-  for (const i of pendingIdx) {
-    const c = b.calls[i];
-    const share = Math.round(delta * ((c.quoted ?? c.cost) / quoted));
-    c.measured = share; c.cost = share; c.pending = false; c.reconciledAt = new Date().toISOString();
-  }
-  b.spent = b.calls.reduce((a, c) => a + (c.cost || 0), 0);
-  writeJson(join(dir, 'budget.json'), b);
-  receipt(root, dir, { provider: 'elevenlabs', model: 'reconcile', cost: 0, unit: 'credits', note: `settled ${pendingIdx.length} pending call(s): ${delta} credits measured against ${quoted} quoted (anything else the account did in between is included)`, measuredTotal: delta });
-  return { ok: true, command: 'reconcile', slug, settled: pendingIdx.length, measured: delta, quoted, spent: b.spent, cap: b.cap, creditsLeft: now.remaining };
-}
+
 
 /* ---------------------------------------------------------------- analyze */
 
@@ -573,27 +398,16 @@ function print(r) {
   const L = [];
   switch (r.command) {
     case 'check':
-      L.push(`ElevenLabs: ${r.road ? `connected (${r.road === 'cli' ? `the elevenlabs CLI, ${r.cli}` : r.via === 'stripe-projects' ? 'the key Stripe Projects keeps for this studio' : r.source ?? 'ELEVENLABS_API_KEY'})` : 'not connected'}`);
       if (r.plan) L.push(`Plan: ${r.plan.tier} (${r.plan.status}); ${r.plan.remaining} credits left of ${r.plan.limit}; resets ${r.plan.resetAt ?? '?'}; ${r.plan.canGoOver ? 'CAN go over (usage-based billing)' : 'cannot go over'}`);
       if (r.rights) L.push(`Rights: ${r.rights.words}`);
       L.push(`ffmpeg: ${r.ffmpeg ? 'yes' : 'NO'}`, `Studio: ${r.studio?.ok ? r.studio.root : r.studio?.why}${r.studio?.pages && !r.studio.pages.ok ? ` (song pages: ${r.studio.pages.why})` : ''}`);
       break;
-    case 'quote':
-      L.push(`${r.seconds} s: about ${r.credits.total} credits (${r.credits.music} music${r.credits.lyricCheck ? ` + ${r.credits.lyricCheck} lyric check` : ''}); ${r.credits.basis}.`);
-      if (r.plan) L.push(`The account has ${r.plan.remaining} credits left (${r.plan.tier}).`);
-      if (r.budget) L.push(`Within a budget of ${r.budget} credits the longest render is about ${r.longestWithinBudget} s.`);
-      break;
+
     case 'plan':
-      L.push(`Plan: ${r.seconds} s, ${r.bars} bars at ${r.bpm} BPM${r.vocals ? ', with vocals' : ', instrumental'}; about ${r.quote.total} credits.`, ...r.sections.map((s) => `  ${s.text} ${s.ms} ms`), ...r.warnings.map((w) => `  warning: ${w}`), `Wrote ${r.file}`);
-      break;
-    case 'render':
-      if (r.dryRun) L.push(`Dry run (nothing sent): ${r.ok ? 'the request is valid' : r.why}; it would cost about ${r.quote.music} credits.`);
-      else if (r.needs) L.push(r.why);
-      else L.push(`Rendered ${r.file}: ${r.seconds.toFixed(2)} s (asked ${r.askedSeconds} s). Credits: quoted ${r.creditsQuoted}, measured ${r.creditsMeasured ?? 'unknown'}; ${r.creditsLeft ?? '?'} left. Plan ${r.tier}: ${r.rights.commercial ? 'commercial licence' : 'NO commercial licence'}.`, ...(r.note ? [r.note] : []));
-      break;
-    case 'lyrics':
-      L.push(`${r.ok ? 'Every planned line is sung.' : `NOT every line is sung: ${r.missing.length} missing.`}`, ...r.lines.map((x) => `  ${x.ok ? 'ok  ' : 'MISS'} ${Math.round(x.matched * 100)}%  "${x.line}"  heard: "${x.heard}"`));
+      L.push(`Plan: ${r.seconds} s, ${r.bars} bars at ${r.bpm} BPM${r.vocals ? ', with vocals' : ', instrumental'}; quote through the official ElevenLabs MCP.`, ...r.sections.map((s) => `  ${s.text} ${s.ms} ms`), ...r.warnings.map((w) => `  warning: ${w}`), `Wrote ${r.file}`);
       break;
+
+
     case 'master':
       L.push(`Mastered to ${r.master.lufs} LUFS, ${r.master.truePeak} dBTP (target ${r.target.lufs} / ${r.target.truePeak}); the mp3 reads ${r.mp3.lufs} LUFS, ${r.mp3.truePeak} dBTP. ${r.master.file}, ${r.mp3.file}`);
       break;
@@ -616,17 +430,12 @@ async function main() {
     return null;
   }
   if (cmd === 'check') return check();
-  if (cmd === 'quote') return quote();
   if (cmd === 'analyze') return analyze();
   const root = requireStudio();
   if (cmd === 'budget') return budget(root);
   if (cmd === 'plan') return plan(root);
-  if (cmd === 'render') return render(root);
-  if (cmd === 'lyrics') return lyricsCheck(root);
-  if (cmd === 'reconcile') return reconcile(root);
   if (cmd === 'master') return master(root);
   if (cmd === 'loop') return loop(root);
-  if (cmd === 'stems') return stems(root);
   if (cmd === 'add') return add(root);
   if (cmd === 'publish') return publishEntry(root, 'music', pos[1], { deploy: !flags.has('no-deploy') });
   return { ok: false, command: cmd, why: `unknown command "${cmd}" (music.mjs help)` };

package/guides/office/SKILL.md

@@ -156,3 +156,27 @@ 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.
+
+## Experimental MCP Events
+
+For an owner's AI that should hear a studio's declared events, read
+`node_modules/@homie-rocks/studio/docs/mcp-events.md`. Connect the client to
+`<site>/mcp/auth` through the person's existing studio approval, discover feeds
+with `events/list`, and use `events/poll`, an SSE `events/stream`, or
+`events/subscribe` with a client-generated `whsec_` secret and an exact
+owner-declared `mcp.events.<feed>.receivers` URL. Refresh before `refreshBefore`,
+persist cursors, verify Standard Webhooks signatures, deduplicate event IDs, and
+use `events/unsubscribe` to stop a webhook. The feeds keep their current roles;
+resources/subscribe and the cursor tool still work. This follows the experimental
+Triggers & Events working-group draft, with the Workers DNS-pinning limitation
+and receiver allowlist explained in that guide. Inspect Functions in the office
+and refresh's `deliveryStatus` for failed deliveries; never put secrets in logs.
+
+For production failures, the owner's AI can also use the person's existing
+Cloudflare connection to `https://mcp.cloudflare.com/mcp`, discover
+`cloudflare.alert.workers_observability_real_time_issue` with `events/list`, and
+subscribe with `events/subscribe` scoped to the studio's Worker. Enable Workers
+Issues and grant Notifications Write and Workers Observability Write. Cloudflare
+posts signed events to the client's webhook so new or recurring reliability
+problems reach the AI without polling; Homie hosts nothing for this. See
+[Cloudflare's announcement](https://developers.cloudflare.com/changelog/post/2026-10-13-cloudflare-mcp-events/).

package/guides/parts/SKILL.md

@@ -155,4 +155,4 @@ payer after the purchase, then record its hash with `shop refund <order> --manua
 
 For app, music and video parts, use `part_new` without `from`, choose any suitable kind label, put the licensed files in its folder, and supply the source as `{kind, id, studio}` in `from`. Preserve existing game manifests and imports. Hash and share through the usual tools. No new app build framework is implied.
 
-Selling defaults to the keyless shop: `shop connect` uses the official Stripe CLI approval, creates Payment Links and the webhook, and installs the signing key privately. One approval if needed, zero for an already connected profile. Machine MPP/SPT and MCP charges and the Stripe-recorded x402 path need the fuller Worker credential. Read the payment-path table in PARTS.md before setup. With browser access, operate Stripe's key page for the owner, let them complete only provider verification prompts, click Copy, and run `shop connect --from-clipboard`. Never ask the owner to find or paste a key when this alternative is available. The command reads and clears the clipboard privately. Do not print its contents. No real-account verification is claimed by the release's stand-in tests.
+Selling defaults to Stripe’s official plugin for shop catalog and links, with Homie’s private webhook installation. Read the shop skill. `shop connect` remains the CLI alternative for priced tool links. Never ask an owner for an API key. Machine payment paths that require runtime credentials are developer integrations, not an owner setup fallback.

package/guides/servers/SKILL.md

@@ -157,3 +157,27 @@ For local function and tool proof, run `dev` and use its localhost URL. The priv
 dev credential permits headless owner tool calls; production still uses OAuth.
 App need sessions are scoped to the declared role and fresh records. See the app
 and functions guides for tablet/kiosk proof and atomic function storage.
+
+## Experimental MCP Events
+
+For an owner's AI that should hear a studio's declared events, read
+`node_modules/@homie-rocks/studio/docs/mcp-events.md`. Connect the client to
+`<site>/mcp/auth` through the person's existing studio approval, discover feeds
+with `events/list`, and use `events/poll`, an SSE `events/stream`, or
+`events/subscribe` with a client-generated `whsec_` secret and an exact
+owner-declared `mcp.events.<feed>.receivers` URL. Refresh before `refreshBefore`,
+persist cursors, verify Standard Webhooks signatures, deduplicate event IDs, and
+use `events/unsubscribe` to stop a webhook. The feeds keep their current roles;
+resources/subscribe and the cursor tool still work. This follows the experimental
+Triggers & Events working-group draft, with the Workers DNS-pinning limitation
+and receiver allowlist explained in that guide. Inspect Functions in the office
+and refresh's `deliveryStatus` for failed deliveries; never put secrets in logs.
+
+For production failures, the owner's AI can also use the person's existing
+Cloudflare connection to `https://mcp.cloudflare.com/mcp`, discover
+`cloudflare.alert.workers_observability_real_time_issue` with `events/list`, and
+subscribe with `events/subscribe` scoped to the studio's Worker. Enable Workers
+Issues and grant Notifications Write and Workers Observability Write. Cloudflare
+posts signed events to the client's webhook so new or recurring reliability
+problems reach the AI without polling; Homie hosts nothing for this. See
+[Cloudflare's announcement](https://developers.cloudflare.com/changelog/post/2026-10-13-cloudflare-mcp-events/).

package/guides/shop/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: shop
 description: Sell things in a Homie studio's games with the studio's OWN Stripe - a supporter pack, cosmetics, a season pass, a one-time unlock, a tip, a round of several items to a table, a paid booking with slot capacity, monthly giving or a membership - in real money, with Stripe Checkout, Stripe Tax or Stripe Managed Payments, refunds from the office, and optional studio policies with an open default; set up with Stripe's own agent tools (Stripe's MCP server and skills) with one browser approval and Payment Links by default, no human-handled key and no API key in the Worker. Use when someone asks to sell something, add a shop or store, take payments or donations, take paid bookings, set up monthly giving or memberships, make money from a game, set up or connect Stripe, make the products in Stripe, asks "how are sales?", about tax or Managed Payments, to add a supporter badge, refund a player, or about chargebacks.
-compatibility: The studio's own current toolkit with stripe_login or shop connect --renew, Wrangler, and the official Stripe CLI. Stripe's own agent plugin (MCP and skills) is optional for catalog work and analytics.
+compatibility: Stripe's official OAuth MCP/plugin, Homie's stripe_shop_plan and stripe_webhook tools, and Wrangler. Stripe CLI is used privately for webhook setup and local forwarding.
 metadata:
   providers: stripe
 ---
@@ -16,7 +16,7 @@ Studio functions (`functions/FUNCTIONS.md`), with the event ID as the idempotenc
 
 # The shop
 
-Check that the toolkit exposes `stripe_login`, or that `homie-studio --help` lists `shop connect` with `--renew` and `--manual`. An older toolkit's default is the paste page: upgrade before using this flow; do not send the owner to that old default.
+Check that the toolkit exposes `stripe_shop_plan` and `stripe_webhook`; upgrade older toolkits first.
 The guide is `node_modules/@homie-rocks/studio/shop/SHOP.md`; the owner's plain words are `SELLING.md`.
 
 **The model, said plainly to the person.** The studio sells with **its own Stripe account**. The studio is the
@@ -28,87 +28,78 @@ entity field or a command into proof of a purchase: grants still come from the s
 verified server records. Room state is replicated to players; keep payment and private
 customer data out of it. Read the game skill's RULES.md before changing game outcomes.
 
-## Connect with Stripe's own browser approval
-
-Use `stripe_login` (MCP) or `npx --no-install homie-studio shop connect`. Test mode and a
-sandbox first. If the CLI is missing, run the one installation command the result gives:
-`npm install -g @stripe/cli@latest`. The toolkit opens Stripe's page and completes its official
-non-interactive login. Give the person the pairing code; they select their own account and approve.
-Use `studio_job` for the background result. Do not call a raw CLI config command: it may print secrets.
-
-The default is **keyless**: the toolkit uses the CLI's approved account to sync Products, Prices
-(including custom amounts for tips), Payment Links and the webhook. It captures the signing secret
-privately and installs it with the link configuration; it never exports the CLI credentials.
-The Worker redirects buyers to Stripe and grants purchases from signed events. No desktop agent,
-Homie service or API key is needed when someone pays. Run connect again after editing shop.json;
-it updates changed objects and archives removed ones. Existing connections need no new approval.
-
-Keyless also supports mixed fixed-price menus, capacity-limited booking links and fixed
-monthly gifts/memberships. Read SHOP.md's 0.51 examples before implementing these.
-Guests choose menu quantities on Stripe. Booking links show pending without holding
-an unpaid seat; Stripe's completion limit is the hard capacity. Use
-`stripe_bookings_sync` after publishing/changing slots (complete manifest), or update
-`.studio/booking-slots.json` and rerun connect. Sync creates the no-code portal login
-through the API; no Dashboard toggle is needed. Never ask for a key.
-
-Only when explicitly selected, an existing Worker key plus
-`STRIPE_CHECKOUT_MODE=sessions` enables exact app carts, exclusive expiring holds,
-spending reservations, provider reads and runtime refunds. A key alone never selects
-it. Default connect selects links and removes the runtime key.
-
-## Never
-
-- Never ask a person for a Stripe key, a webhook secret or a password in chat. Never display a CLI
-  config, credential response, environment value or raw login-completion output. The toolkit captures
-  these privately. Keys belong to the studio; no Homie account or service takes payments.
-- **Never make a webhook endpoint or an event destination through Stripe's MCP**: its signing secret
-  would enter the conversation. `shop connect` handles endpoint creation and secret storage privately.
-- Never silently select `--manual`. Only when the owner chooses the fallback, run
-  `shop connect --manual` (or `--manual --live`) and give the local page link. The page explains the
-  remaining Dashboard restricted-key step and creates the webhook automatically. This fallback
-  requires copying a key and does not meet the one-approval target; say so plainly.
-- Live mode only when the owner says go live. Account activation, tax, bank details and Stripe
-  approval links are the owner's. Never approve a Stripe confirmation link for them.
-- The studio chooses its settings. Omitted policies are open; choose a preset only when requested.
-
-## The owner's steps, for a creator with a fresh Stripe account
-
-With an existing Stripe account and deployed studio, there is **one Stripe approval** for the CLI;
-if that CLI profile is already connected, there are **zero new approvals**. An existing MCP-only
-consent is not a CLI login and is not exported or borrowed. Account creation/activation, an administrator
-enabling CLI access, and an initial Cloudflare sign-in are separate Stripe/hosting requirements.
-
-| The owner | You |
-|---|---|
-| Approves Stripe's browser page, selecting their studio account and sandbox. | Create/check shop.json; run stripe_login / shop connect; follow studio_job to completion. |
-| Nothing. | Sync all items and the webhook, install the signing secret and links privately, then verify a test purchase and grant. |
-| Requests a refund in Stripe or asks their connected AI. | Use the official Stripe connection, honor any confirmation link, verify the signed refund event removes the item. |
-| Says “go live” and completes Stripe activation if needed. | shop connect --live in the authorized account; verify only an authorized real purchase. |
-
-`shop connect --renew` restarts the approval flow when needed. CLI OAuth refresh is the CLI's job;
-there is no runtime API credential to expire. `shop catalog` remains the optional older catalog planner
-for keyed shops; keyless shops use connect for the complete catalog, links and webhook sync.
-
-## Optional Stripe agent tools
-
-For catalog work, analytics and advice, `stripe agent setup` installs Stripe's own agent plugin and
-skills; its OAuth MCP is `https://mcp.stripe.com`. This is optional and separate from Worker credentials.
-Check `get_stripe_account_info` before writes; confirm the account and mode match the studio.
-For CLI refunds or event resends, use the non-secret `profile` returned by connect with `stripe --project-name <profile>`; preserve its test/live context. Do not read credentials.
-The tools include `stripe_api_read`, `stripe_api_write`, API discovery and `stripe_analytics`.
-From **2026-10-31**, MCP rejects API keys without the Agent tag; OAuth remains supported. Agent keys
-can put refunds behind Stripe approval. A returned confirmation link belongs to the owner; wait
-for approval before retrying. Do not silently replace the payment runtime with MCP; a separate persistent MCP client would need its own production verification.
+## Default: Stripe's official plugin
+
+Use Stripe's official plugin, authenticated with its browser OAuth approval, for Products,
+Prices, Payment Links, menu links, per-slot booking links, monthly giving and the customer
+portal. Install with `stripe agent setup` if needed; the MCP URL is
+`https://mcp.stripe.com`. Current tools are `stripe_api_search`, `stripe_api_details`,
+`stripe_api_read` and `stripe_api_write`. Discover the operation and its schema before
+calling it; tool argument shapes can change. See https://docs.stripe.com/mcp.
+
+1. Create/check `shop.json`. Read the app's published slot records and supply the complete
+   slot manifest described below. Select the owner's account and sandbox in Stripe's plugin;
+   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`.
+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
+   links through Wrangler stdin. The CLI needs one separate browser approval if its
+   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
+   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
+   endpoint's delivery result and the app's verified records. Do not type a card into
+   a page for an automated proof; use Stripe's documented test PaymentMethods/fixtures.
+
+Never create a webhook through model-visible Stripe MCP: its response exposes the signing secret.
+
+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
+`stripe_login` / `shop connect` flow remains an alternative that syncs everything
+through Stripe CLI browser approval. `--renew` renews that approval; `--live` requires
+the owner's go-live request. Never read CLI config or print login-completion output.
+
+For local checkout, pass `url: "http://localhost:8787"` (or the private Wi-Fi address)
+and `mode: "test"` to the same plan/verify flow; the official plugin makes the links.
+Run `homie-studio shop listen --profile <sandbox-profile>` in a background terminal.
+Stripe CLI is required for forwarding; one browser approval is enough if needed.
+The command captures and saves the listener secret privately. Start/restart
+`homie-studio dev --lan` once it reports ready and keep the listener running.
+Never copy the listener's raw output into the conversation.
+
+For a faster local iteration, `homie-studio build --quick` skips generated rules play
+and the snapshot smoke-run, while retaining compilation, guards and type checks.
+Run a full build before release; quick output is not evidence that play checks passed.
 
 ## Do
 
 | The person says | Run | What happens |
 |---|---|---|
 | "Sell a supporter pack for $5" | `npx --no-install homie-studio shop init --supporter` (then `shop check`) | `shop.json` with a US$5 Supporter pack (a badge on their profile and beside their name in rooms, for a year; it changes nothing about play) and `SELLING.md`. Commit both. |
-| "Sell a skin / a season pass / the full game" | edit `shop.json` `items` (`kind`: `cosmetic`, `pass`, `unlock`; `price` in Stripe currency units; `gives`: the keys the game reads), `shop check`, then `shop connect` again | Kinds are studio labels, without a fixed list. `"advantage": true` follows the studio policy for beginner and kids servers. Homie sets no price ceiling. |
+| "Sell a skin / a season pass / the full game" | edit `shop.json` `items` (`kind`: `cosmetic`, `pass`, `unlock`; `price` in Stripe currency units; `gives`: the keys the game reads), `shop check`, then the official MCP plan/verify flow again | Kinds are studio labels, without a fixed list. `"advantage": true` follows the studio policy for beginner and kids servers. Homie sets no price ceiling. |
 | "Let people tip" | an item `{ "kind": "tip", "price": "choose", "min": 200, "max": 5000 }` | Pay what you want; amounts follow Stripe currency requirements, and max is optional and chosen by the studio. |
-| "Make the products in Stripe" | `shop connect` | Idempotent Product, Price, Payment Link and webhook sync from shop.json; no secret enters tool output. |
-| "Connect my Stripe" / "turn the shop on" | `stripe_login` or `shop connect` | Approve Stripe once if needed; the Worker receives links and the signing secret only. Follow the single next step returned. Live only when requested. |
+| "Make the products in Stripe" | `stripe_shop_plan` | Idempotent Product, Price, Payment Link and webhook sync from shop.json; no secret enters tool output. |
+| "Connect my Stripe" / "turn the shop on" | `stripe_shop_plan`, then `stripe_webhook` | Approve Stripe once if needed; the Worker receives links and the signing secret only. Follow the single next step returned. Live only when requested. |
 | "Is tax set up?" | `stripe_api_read` `GET /v1/tax/settings`, and `GET /v1/tax/registrations` | Seller "stripe": Stripe Tax needs `status: active` (the business address in Settings, Tax), or checkouts fail; with no registrations it collects no tax anywhere: say so, the accountant decides where to register. Seller "stripe-managed": Stripe files the tax; the connect page's test checkout said whether Managed Payments is on. Change nothing yourself. |
 | "Is the shop working?" | `npx --no-install homie-studio shop` | Open (test or live) or exactly what is missing, the last 30 days, the webhook address. |
 | "How are sales?" / "Show me the sales" | `shop` and `shop orders` first (the studio's own books); with Stripe's MCP, read-only: `stripe_analytics`, or `stripe_api_read` on `/v1/balance`, `/v1/payouts`, `/v1/checkout/sessions` | Counts, money and payouts in a few lines; never a buyer's name, email or card. Never a write to answer a question. The owner's `/_studio/office/shop` links every Stripe page and gives the accountant a CSV. |
@@ -158,7 +149,7 @@ Read SHOP.md for a round to table 7, `shop.book` and $20 monthly giving.
 Menus let guests choose several quantities on Stripe; signed invoices provide actual
 paid lines and the app reference. Slot Payment Links enforce completed-session
 capacity. Pending guests do not block others. The owner's AI syncs published slots
-with `stripe_bookings_sync`; the app shows Full from verified availability.
+with `stripe_shop_plan` and the complete slot manifest; the app shows Full from verified availability.
 Recurring Prices provide monthly preset gifts and memberships. Connect enables the
 no-code customer portal login through Stripe's API, without a Dashboard toggle.
 Paid invoice periods govern membership; failed renewal never extends it.