@homie-rocks/studio 0.51.3 → 0.51.5

package/guides/sound/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: sound
 description: Make a game's sound effects and synthesized music on the creator's own computer, free, with no provider or account — a set of effects (jump, coin, hit, explosion, win, lose, UI) rendered from presets, a short synthesized theme or score from chords and patterns with stems and seamless section loops, a mix of any audio files and expressions — measured for loudness, clipping, late starts and what a phone speaker loses, then wired into the game with a small player that starts on the first touch and switches music on bar lines. Use when someone asks for sound effects, SFX, game audio, a chiptune or synth theme, background music without a paid service, music that changes with the game, or says a game is silent.
+compatibility: Node 22 and ffmpeg for local synthesis; official ElevenLabs MCP for requested generated sound.
+metadata:
+  providers: elevenlabs
 ---
 
 # Sound for a studio's game
 
-Everything here runs on this computer with Node 22 and ffmpeg: nothing is sent anywhere and nothing
+Local synthesis runs on this computer with Node 22 and ffmpeg: nothing is sent anywhere and nothing
 costs money. Sung songs and produced music from a model are the `music` skill (ElevenLabs, paid);
 this skill is effects and synthesized music. They share the studio's `music/` folder and manifest, so
 a synthesized theme gets a song page just like a rendered one.
@@ -154,3 +157,69 @@ numbers, the warnings you fixed and any you did not, and that it cost nothing.
 - Never use a mp3 for an effect or a loop: encoders pad the start with silence (a late hit) and the
   ends (a gap at the loop). WAV or Ogg.
 - Never imitate a real song, artist or brand jingle.
+
+## Generated sound on request
+
+Use the official ElevenLabs MCP for requested generated effects. Discover its current
+sound capabilities and schema through the official plugin; never assume a tool exists.
+If the hosted connection lacks sound generation, say so; keep local synthesis available
+as Homie-owned, free functionality. Specify duration, loopability, envelope and material
+from the scene. Audition on phone speakers, remove clicks, and trigger it only on the
+intended game event after the browser audio unlock gesture.
+
+## Official generation workflow
+
+The owner's AI uses the provider's official plugin/MCP in its own client. Homie never
+asks for, stores, reads or prints provider credentials. Read the current provider
+skill and discover its available tools and input schemas; host prefixes vary.
+Connection instructions and verified sources: [official integrations](../studio-setup/references/OFFICIAL-MEDIA.md).
+If tools are missing, connect that official plugin once in the client's browser flow.
+Do not fall back to a Homie client, key file, environment key or CLI generation wrapper.
+
+Before spending, state the model, count/duration, estimated cost and remaining approved
+budget. Use the owner's existing authorization; ask only if the spend is outside it.
+Record the request ID as soon as accepted. Poll that same request; never resubmit to
+retry a slow job. Unknown cost is unknown, never zero. Provider billing is authoritative;
+Homie's local receipt cannot enforce spending in another client.
+
+## Place and prove the result
+
+Download the completed tool's output using the AI client's file/download facilities.
+Keep temporary signed URLs out of committed records. Keep the original in the studio's
+art/job folder; put the optimized delivered asset beside its game/app, or in music/ or
+videos/ for a published work. Record a receipt with these fields:
+
+```json
+{
+  "provider": "elevenlabs",
+  "tool": "actual discovered tool",
+  "model": "exact endpoint returned by the provider",
+  "requestId": "actual request ID",
+  "prompt": "the actual prompt, including style constraints",
+  "styleRevision": "revision from the studio's style",
+  "rights": {"source": "provider/model terms URL", "checkedAt": "YYYY-MM-DD", "commercial": false, "note": "record the actual plan and permitted use"},
+  "cost": {"status": "unknown"}
+}
+```
+
+For ElevenLabs use its actual discovered tool and model, and its flow/session or request
+identifier. A measured cost uses `{"status":"actual","amount":1,"unit":"credits"}`;
+a quote uses `estimate`. Never claim commercial rights from the fact that generation
+succeeded. Read the provider and model terms for the account's plan; record attribution,
+reference-image permissions and any restrictions. Mark test fixtures `"fixture": true`.
+
+Wire the delivered path into the scene or manifest, then run:
+
+```sh
+npx --no-install homie-studio media import --file <downloaded-file> --receipt <receipt.json> --out games/<id>/assets/<name> --used-by games/<id>/view.ts
+```
+
+This copies bytes, verifies a static reference, hashes the asset and records allowlisted
+provenance in `media/provenance.json`. Reimporting the same output is idempotent; it
+never generates or charges. Include each generation step's receipt for derived assets.
+Run the scene and look/listen: a file and static reference are not proof that it renders
+or plays. Report the placed path, usage evidence, rights and actual/estimated cost.
+
+The toolkit’s `lib/media-workflows.mjs` declares this skill’s verified tool references.
+Validate them against the host’s current tool inventory before execution; tool discovery
+is required for generation capabilities that have no stable documented name.

package/guides/sound/scripts/player/sound.js

@@ -0,0 +1,233 @@
+/*
+ * sound.js: a game's sound effects and music, from the files the Homie plugin's sound skill made
+ * (sound.json beside them lists what exists). Plain JavaScript, no dependencies.
+ *
+ *   import { createSound } from './sound.js';            // bundle games: from src/; static games: from sound/
+ *   const sound = createSound({ base: 'sound/' });        // where sound.json and the files are served, relative to the page
+ *   sound.play('jump');                                   // a random variant, a little pitch jitter, never more than 4 at once
+ *   sound.play('coin', { pitch: combo, volume: 0.8, pan: -0.3 });
+ *   sound.music('theme');                                 // the theme's first loop, from the first touch on
+ *   sound.section('chase');                               // the next loop, starting exactly on the next bar line
+ *   sound.duck(0.4, 0.5);                                 // music down to 40% for half a second (a big hit, a line of speech)
+ *   sound.volume({ sfx: 1, music: 0.6 }); sound.mute(true);
+ *
+ * Sound starts on the first touch, click or key, with no "tap for sound" screen: browsers keep audio
+ * suspended until a person has touched the page, so the first gesture resumes it (a held stick counts
+ * when the finger lifts). A sound asked for before that is dropped, not queued: a late hit is worse than none.
+ * window.__homieSound holds counters for a playtest (what played, when); it never controls anything.
+ *
+ * THE CAPTURE LOG (off unless a recorder asks). A recorder that renders the page frame by frame cannot
+ * record the speaker, so it asks for a log instead: before the page's scripts run it sets
+ *
+ *   window.__homieSoundCapture = { events: [] };
+ *
+ * and from then on every sound this player schedules is pushed onto `events` as it is scheduled, stamped
+ * with performance.now() (`t`, ms), enough to mix the same sound again offline from the same files:
+ *
+ *   { t, type: 'start', id, bus: 'sfx' | 'music', name, url, gain, rate, pan, loop, delay, fadeIn, bar? }
+ *   { t, type: 'stop', id, delay, fade, curve: 'cut' | 'linear' | 'target' }
+ *   { t, type: 'duck', to, seconds }                 music down to `to`, back after `seconds`
+ *   { t, type: 'levels', master, sfx, music, muted }
+ *   { t, type: 'drop', name, why }                   asked for and not played: 'locked', 'missing', 'loading', 'voices'
+ *
+ * `delay` is seconds after `t`; `url` is absolute; `rate` is the playback rate after pitch and jitter (the
+ * random choices are in the log, so the mix repeats them). With the log on, bar lines are counted on the page's
+ * clock (performance.now) instead of the audio clock, so a recorder's virtual clock moves them too.
+ * A game with its own audio code can push the same events itself; the video skill's `trailer` reads them.
+ * Without that global nothing is logged and nothing here costs anything.
+ */
+export function createSound({ base = 'sound/', manifest = 'sound.json', maxPerName = 4, maxVoices = 24 } = {}) {
+  const AC = window.AudioContext || window.webkitAudioContext;
+  const ctx = AC ? new AC({ latencyHint: 'interactive' }) : null;
+  const url = (f) => new URL(f, new URL(base, document.baseURI)).toString();
+  const buses = {};
+  const buffers = new Map();
+  const live = new Map();
+  const stats = { unlocked: false, unlockedAt: null, plays: [], missing: [], errors: [], music: null };
+  let meta = { sfx: {}, music: {} };
+  let muted = false;
+  const levels = { master: 1, sfx: 1, music: 0.7 };
+  let track = null;
+  // The capture log: only when a recorder put the global there before this ran (see the head of this file).
+  let cap = null;
+  try { const c = window.__homieSoundCapture; if (c && Array.isArray(c.events)) cap = c; } catch (e) { /* not ours to read */ }
+  let capId = 0;
+  const logEv = (e) => { if (cap) { e.t = performance.now(); cap.events.push(e); } return e; };
+  const fileOf = new Map(); // a variant's key -> the file that decoded (what the log names)
+
+  if (ctx) {
+    buses.master = ctx.createGain();
+    // A gentle safety limiter: many hits at once must not clip.
+    const comp = ctx.createDynamicsCompressor();
+    comp.threshold.value = -6; comp.knee.value = 6; comp.ratio.value = 8; comp.attack.value = 0.003; comp.release.value = 0.15;
+    buses.master.connect(comp).connect(ctx.destination);
+    buses.sfx = ctx.createGain(); buses.sfx.connect(buses.master);
+    buses.music = ctx.createGain(); buses.music.connect(buses.master);
+    buses.duck = ctx.createGain(); buses.duck.connect(buses.music);
+    applyLevels();
+    try { if (navigator.audioSession) navigator.audioSession.type = 'playback'; } catch (e) { /* not iOS */ }
+    const unlock = () => {
+      if (ctx.state !== 'running') ctx.resume().catch(() => {});
+      try { const b = ctx.createBuffer(1, 1, 22050); const s = ctx.createBufferSource(); s.buffer = b; s.connect(ctx.destination); s.start(0); } catch (e) { /* closed */ }
+      if (!stats.unlocked && ctx.state === 'running') { stats.unlocked = true; stats.unlockedAt = performance.now(); }
+      if (track && !track.started && ctx.state === 'running') startTrack();
+    };
+    for (const ev of ['pointerdown', 'pointerup', 'touchstart', 'touchend', 'keydown', 'click']) window.addEventListener(ev, unlock, { capture: true, passive: true });
+    ctx.addEventListener('statechange', () => { if (ctx.state === 'running') { stats.unlocked = true; stats.unlockedAt = stats.unlockedAt || performance.now(); if (track && !track.started) startTrack(); } });
+  }
+
+  const ready = fetch(url(manifest)).then((r) => { if (!r.ok) throw new Error(`${manifest}: HTTP ${r.status}`); return r.json(); }).then((m) => {
+    meta = { sfx: m.sfx || {}, music: m.music || {} };
+    const variants = Object.values(meta.sfx).flat();
+    const loops = Object.values(meta.music).flatMap((t) => Object.values(t.loops || {}));
+    return Promise.all([...variants, ...loops].map(loadFirst));
+  }).catch((e) => { stats.errors.push(String(e && e.message || e)); });
+
+  function load(file) {
+    if (!ctx || buffers.has(file)) return buffers.get(file);
+    const p = fetch(url(file)).then((r) => { if (!r.ok) throw new Error(`${file}: HTTP ${r.status}`); return r.arrayBuffer(); })
+      .then((b) => new Promise((ok, no) => ctx.decodeAudioData(b, ok, no)))
+      .then((buf) => { buffers.set(file, buf); return buf; })
+      .catch((e) => { stats.errors.push(String(e && e.message || e)); buffers.delete(file); return null; });
+    buffers.set(file, p);
+    return p;
+  }
+
+  // A list's own key, never a file's name: a list of ONE file ("jump.wav", or ["jump.wav"]) used to be kept under
+  // that file's name, so loading the file found the list's own unfinished promise and waited on itself for ever
+  // (`ready` never resolved, and music asked for before it never started).
+  const keyOf = (list) => `=${Array.isArray(list) ? list.join('|') : list}`;
+  /** A file listed as [ogg, wav]: the first this browser decodes wins (older Safari cannot decode Ogg). */
+  function loadFirst(list) {
+    const files = Array.isArray(list) ? list : [list];
+    const key = keyOf(list);
+    if (buffers.has(key)) return buffers.get(key);
+    const p = files.reduce((prev, f) => prev.then((buf) => buf || load(f).then((b) => (b instanceof AudioBuffer ? b : null))), Promise.resolve(null))
+      .then((buf) => { if (buf) { buffers.set(key, buf); fileOf.set(key, files.find((f) => buffers.get(f) === buf) ?? files[0]); } else buffers.delete(key); return buf; });
+    buffers.set(key, p);
+    return p;
+  }
+  const loopBuffer = (list) => buffers.get(keyOf(list));
+
+  function applyLevels() {
+    if (!ctx) return;
+    const t = ctx.currentTime;
+    buses.master.gain.setTargetAtTime(muted ? 0 : levels.master, t, 0.02);
+    buses.sfx.gain.setTargetAtTime(levels.sfx, t, 0.02);
+    buses.music.gain.setTargetAtTime(levels.music, t, 0.05);
+    logEv({ type: 'levels', master: levels.master, sfx: levels.sfx, music: levels.music, muted });
+  }
+
+  function play(name, { volume = 1, pitch = 0, pan = 0, jitter = 0.35 } = {}) {
+    stats.plays.push({ name, t: Math.round(performance.now()) });
+    if (stats.plays.length > 500) stats.plays.splice(0, 250);
+    if (!ctx || ctx.state !== 'running') { logEv({ type: 'drop', name, why: 'locked' }); return null; }
+    const variants = meta.sfx[name];
+    if (!variants || !variants.length) { if (!stats.missing.includes(name)) stats.missing.push(name); logEv({ type: 'drop', name, why: 'missing' }); return null; }
+    const variant = variants[Math.floor(Math.random() * variants.length)];
+    const buf = loopBuffer(variant);
+    if (!(buf instanceof AudioBuffer)) { logEv({ type: 'drop', name, why: 'loading' }); return null; }
+    const mine = live.get(name) || [];
+    while (mine.length >= maxPerName) { const old = mine.shift(); try { old.stop(); } catch (e) { /* ended */ } logEv({ type: 'stop', id: old.capId, delay: 0, fade: 0, curve: 'cut' }); }
+    let total = 0; for (const v of live.values()) total += v.length;
+    if (total >= maxVoices) { logEv({ type: 'drop', name, why: 'voices' }); return null; }
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    src.playbackRate.value = 2 ** ((pitch + (Math.random() * 2 - 1) * jitter) / 12);
+    if (cap) { src.capId = ++capId; logEv({ type: 'start', id: src.capId, bus: 'sfx', name, url: url(fileOf.get(keyOf(variant)) ?? (Array.isArray(variant) ? variant[0] : variant)), gain: volume, rate: src.playbackRate.value, pan: Math.max(-1, Math.min(1, pan || 0)), loop: false, delay: 0, fadeIn: 0 }); }
+    const g = ctx.createGain(); g.gain.value = volume;
+    let node = src.connect(g);
+    if (pan && ctx.createStereoPanner) { const p = ctx.createStereoPanner(); p.pan.value = Math.max(-1, Math.min(1, pan)); node = node.connect(p); }
+    node.connect(buses.sfx);
+    src.onended = () => { const i = mine.indexOf(src); if (i >= 0) mine.splice(i, 1); };
+    mine.push(src); live.set(name, mine);
+    src.start();
+    return src;
+  }
+
+  function startTrack() {
+    if (!track || !ctx || ctx.state !== 'running') return;
+    const buf = loopBuffer(track.loops[track.section]);
+    if (!(buf instanceof AudioBuffer)) { ready.then(() => { if (track && !track.started) startTrack(); }); return; }
+    track.started = true;
+    track.t0 = ctx.currentTime + 0.05;
+    track.c0 = performance.now() / 1000 + 0.05; // the same moment on the page's clock, for the capture log's bar lines
+    track.node = loopNode(buf, track.t0, track.fade, track.section);
+    stats.music = { name: track.name, section: track.section, since: Math.round(performance.now()) };
+  }
+
+  function loopNode(buf, at, fade, sectionName) {
+    const src = ctx.createBufferSource(); src.buffer = buf; src.loop = true;
+    if (cap) {
+      const list = track.loops[sectionName];
+      src.capId = ++capId;
+      logEv({ type: 'start', id: src.capId, bus: 'music', name: `${track.name}/${sectionName}`, url: url(fileOf.get(keyOf(list)) ?? (Array.isArray(list) ? list[0] : list)), gain: 1, rate: 1, pan: 0, loop: true, delay: Math.max(0, at - ctx.currentTime), fadeIn: Math.max(0.005, fade), bar: track.bar });
+    }
+    const g = ctx.createGain(); g.gain.setValueAtTime(0, at); g.gain.linearRampToValueAtTime(1, at + Math.max(0.005, fade));
+    src.connect(g).connect(buses.duck);
+    src.start(at);
+    return { src, g };
+  }
+
+  let loaded = false;
+  ready.then(() => { loaded = true; });
+  function music(name, opts = {}) {
+    // Called before sound.json has arrived (the usual case: at the top of the game): start it once it has.
+    if (!loaded) { ready.then(() => music(name, opts)); return; }
+    const { section = null, fade = 0.4 } = opts;
+    const t = meta.music[name];
+    if (!t) { stats.errors.push(`no music "${name}" in ${manifest}`); return; }
+    stopMusic({ fade: 0.2 });
+    const first = section || Object.keys(t.loops || {})[0];
+    track = { name, loops: t.loops, bar: t.barSeconds, section: first, started: false, fade };
+    startTrack();
+  }
+
+  /** Switch loops on the next bar line (every loop shares the tempo, so bar lines line up). */
+  function section(name, { fade = 0.03 } = {}) {
+    if (!track || !track.loops[name] || name === track.section) return;
+    track.section = name;
+    if (!track.started) return;
+    const buf = loopBuffer(track.loops[name]);
+    if (!(buf instanceof AudioBuffer)) return;
+    const now = ctx.currentTime;
+    let at = track.t0 + Math.ceil((now + 0.02 - track.t0) / track.bar) * track.bar;
+    if (cap) {
+      // With the capture log on, the next bar line is counted on the page's clock: a recorder's virtual clock is the
+      // one the film is on, and the audio clock runs at the wall's speed beside it.
+      const cnow = performance.now() / 1000;
+      const wait = track.c0 + Math.ceil((cnow + 0.02 - track.c0) / track.bar) * track.bar - cnow;
+      at = now + wait; track.c0 = cnow + wait;
+    }
+    const old = track.node;
+    old.g.gain.setValueAtTime(1, at - fade); old.g.gain.linearRampToValueAtTime(0, at);
+    try { old.src.stop(at + 0.05); } catch (e) { /* */ }
+    logEv({ type: 'stop', id: old.src.capId, delay: Math.max(0, at - fade - now), fade, curve: 'linear' });
+    track.node = loopNode(buf, at - fade, fade, name);
+    track.t0 = at;
+    stats.music = { name: track.name, section: name, since: Math.round(performance.now()) };
+  }
+
+  function stopMusic({ fade = 0.5 } = {}) {
+    if (!track) return;
+    if (track.node && ctx) { const t = ctx.currentTime; track.node.g.gain.setTargetAtTime(0, t, fade / 3); try { track.node.src.stop(t + fade + 0.1); } catch (e) { /* */ } logEv({ type: 'stop', id: track.node.src.capId, delay: 0, fade, curve: 'target' }); }
+    track = null; stats.music = null;
+  }
+
+  function duck(to = 0.4, seconds = 0.4) {
+    if (!ctx) return;
+    const t = ctx.currentTime; const g = buses.duck.gain;
+    g.cancelScheduledValues(t); g.setTargetAtTime(to, t, 0.015); g.setTargetAtTime(1, t + seconds, 0.12);
+    logEv({ type: 'duck', to, seconds });
+  }
+
+  const api = {
+    ready, play, music, section, stopMusic, duck,
+    volume(v) { Object.assign(levels, v || {}); applyLevels(); },
+    mute(on = true) { muted = !!on; applyLevels(); },
+    get context() { return ctx; },
+    state: () => ({ unlocked: stats.unlocked, running: ctx ? ctx.state === 'running' : false, loaded: new Set([...buffers.values()].filter((b) => b instanceof AudioBuffer)).size, music: stats.music, missing: stats.missing.slice(), errors: stats.errors.slice(0, 10) }),
+  };
+  try { window.__homieSound = { get stats() { return { ...api.state(), plays: stats.plays.slice(-100), unlockedAt: stats.unlockedAt }; } }; } catch (e) { /* frozen global */ }
+  return api;
+}

package/guides/studio-setup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: studio-setup
 description: "Set up a Homie studio (one repository with games/, apps/, music/, videos/ and posts/, and a site with public game rooms on the studio's own Cloudflare) with the AI handling setup and defaults: setup status first (accounts and tools, what each unlocks, the exact fix), choose editable defaults, plan the requested game or app, build it with progress the person can watch, playtest, put it online and list it in the homie.rocks directory. Use when someone asks to set up, create or start a studio or a game studio, asks what they need or whether they are set up, or says \"set up a game studio called X\" (with or without \"and make a multiplayer game\")."
-compatibility: Node 22. Reads, and offers only when a feature needs them, each provider's own tools (Wrangler (Cloudflare, pinned in the studio), the GitHub CLI, the ElevenLabs CLI, a fal key, Ollama for Clef on this computer, and as an option the stripe CLI's Stripe Projects). The plugin's providers.json lists them.
+compatibility: Node 22. Reads, and offers only when a feature needs them, each provider's own tools (Wrangler (Cloudflare, pinned in the studio), the GitHub CLI, official fal and ElevenLabs MCP connections, Cloudflare's official plugin, Stripe for the optional shop, and Ollama for Clef on this computer). The plugin's providers.json lists them.
 metadata:
   providers: cloudflare github elevenlabs fal stripe ollama
 ---
@@ -303,32 +303,16 @@ session: say nothing was sent and carry on. Never make help wait on it, never of
 a file, code or anyone's name in it, and a reply address only if they typed it. When they ask to tell Homie
 something themselves, draft it with `offered: false`.
 
-### Another way: Cloudflare (and ElevenLabs) through Stripe Projects
-
-`npx wrangler login` stays the way. Offer this only when the person has **no Cloudflare account** (and wants songs but
-has no ElevenLabs either), and would rather have both made for them in one go: Stripe Projects
-(docs.stripe.com/projects), Stripe's CLI plugin, makes or links provider accounts on the person's own Stripe sign-in
-and hands the credentials to the studio folder. It is a prototype in this version (`setup --via stripe-projects`).
-
-1. Say it in two lines: Stripe signs them in; Cloudflare makes a free account for their Stripe email (or, if they
-   have one, shows its own approval page once); on their own accounts; they accept Cloudflare's terms
-   (and ElevenLabs': whose free plan has **no commercial licence**, so songs made on it are not for sale).
-2. `npx --no-install homie-studio setup --via stripe-projects [--with elevenlabs] --dry-run`: what it would do.
-3. Run it without `--dry-run`. It stops at each step that is the person's and says which, as `needs`:
-   - `stripe-cli` / `projects-plugin`: run the command it names (the person approves the install);
-   - `projects-init`: run `stripe projects init --yes`; Stripe opens its sign-in in their browser. It must be **their
-     own** Stripe account (a new free one is fine). If the Stripe CLI on this computer is signed in to some other
-     account (a work or client one), stop and ask; never use it;
-   - `accept-terms`: ask the person; only after their yes, run it again with `--accept-tos`;
-   - `link-cloudflare`: run `stripe projects link cloudflare`; their browser shows Cloudflare's approval page;
-   - `paid`: stop. Nothing paid is ever added; this is theirs to decide in Stripe Projects, not yours.
-4. When it answers ok, `npm run deploy` as usual: Wrangler deploys with the Projects token.
-
-What it keeps where: the Cloudflare account id goes in `studio.json` (`cloudflare.auth: "stripe-projects"`); the token
-stays in Projects' vault and the git-ignored `.env` it syncs, and the toolkit hands it to Wrangler itself. Follow
-Projects' own rules: never print, read out or `cat` an env value (`stripe projects env --json` lists names only), never
-commit `.env`, `.env.*` or `.projects/vault/` (the command checks `.gitignore`), never hand-edit `.projects/`. If a
-later deploy says the token is not accepted: `stripe projects env --pull` in the studio folder, then deploy again.
+### Official provider connections
+
+Read [official integrations](references/OFFICIAL-MEDIA.md). The AI discovers the
+client's official fal, ElevenLabs and Cloudflare tools and verifies an authenticated
+read. Pass `integrations: {fal: "connected", elevenlabs: "unavailable", cloudflare:
+"unknown"}` to `setup_status` using actual session evidence. Omit unknown providers;
+never infer a connection from a local executable or credentials. The card shows the
+shortest browser connection flow for each. Optional media connections never block setup.
+Wrangler login remains the deployment connection. Do not provision provider credentials
+through Stripe Projects; its old Homie setup wrapper has been removed.
 
 The live address `deploy` prints is on `workers.dev`, which names the person's Cloudflare account;
 `deploy` keeps it in `.studio/local.json` (git-ignored). Never write it into a committed file. A custom

package/guides/studio-setup/references/OFFICIAL-MEDIA.md

@@ -0,0 +1,66 @@
+# Official integrations — checked 2026-10-14
+
+Homie owns studio direction, placement, provenance and checks. The AI client owns
+provider connections. Never copy credentials from an old Homie key file or a CLI login.
+
+| Provider | Official integration | What the person does |
+| --- | --- | --- |
+| fal | [fal plugin and model-generation MCP](https://fal.ai/docs/documentation/setting-up/mcp), `https://mcp.fal.ai/mcp-relay` | Install/connect in the AI client; sign in and approve once in the browser. OAuth, no API key. |
+| ElevenLabs | [elevenlabs/plugin](https://github.com/elevenlabs/plugin), [hosted MCP](https://elevenlabs.io/docs/eleven-agents/operate/hosted-mcp), `https://api.elevenlabs.io/v1/mcp` | Install/connect; sign in and approve workspace access once in the browser. OAuth, no API key. |
+| Cloudflare | [cloudflare/skills plugin](https://github.com/cloudflare/skills), [Code Mode MCP](https://github.com/cloudflare/mcp), `https://mcp.cloudflare.com/mcp` | Install/connect and approve account access in the browser. Wrangler deployment has its own browser login; MCP authorization does not sign Wrangler in. |
+
+For Codex CLI the AI can add a remote server (`codex mcp add <name> --url <URL>`)
+and start `codex mcp login <name>`; the person completes the browser page. For
+Claude Code add the HTTP server and authenticate from `/mcp`. In chat clients,
+choose the official connector in Settings/Connectors and Connect. Prefer an already
+installed official plugin. Cloudflare's Codex marketplace is `cloudflare/skills`
+and plugin `cloudflare@cloudflare`; ElevenLabs' marketplace is `elevenlabs/plugin`
+(install from `/plugins`). Start a new session if the client requires it.
+
+fal's docs explicitly distinguish the OAuth generation relay from its documentation
+server and key-based terminal clients. The generation relay exposes `search_models`,
+`recommend_model`, `get_model_schema`, `get_pricing`, `run_model`, `submit_job`,
+`check_job`, `get_job_result` and `upload_file`. Discover current schemas in-session.
+Do not install genmedia or make a local key for Homie.
+
+ElevenLabs' [October 12 announcement](https://elevenlabs.io/blog/introducing-voice-music-image-and-video-generation-in-the-elevenlabs-mcp)
+confirms hosted music and sound effects through the same OAuth connector. Workspace
+admins control tool access. Its [creative MCP skill](https://github.com/elevenlabs/plugin/blob/main/skills/mcp/creative-studio/SKILL.md)
+documents `creative_get_flow_node_types`, `creative_get_model_guide` and
+`creative_get_flow_run_status`. Discover the connected workspace's current generation
+schemas instead of inventing a music/sound submit tool name. The older
+[local MCP](https://github.com/elevenlabs/elevenlabs-mcp) is deprecated in favor of the
+hosted OAuth server; its key-based setup and tool names are not the remote contract.
+If a future official plugin requires a key, its own AI-client setup owns that flow;
+Homie never handles the value. In this proof session ElevenLabs tools were not exposed,
+so the owner still needs to choose ElevenLabs in Connectors, Connect, and approve the
+workspace in the browser. The previously signed-in CLI is not this MCP connection.
+
+Cloudflare's [server catalog](https://github.com/cloudflare/mcp-server-cloudflare)
+provides Observability (`https://observability.mcp.cloudflare.com/mcp`) for logs and
+analytics and Workers Bindings (`https://bindings.mcp.cloudflare.com/mcp`) for D1
+and other bindings. Prefer the main plugin's `search` then `execute` for current API
+operations, including Workers Issues events and D1 inspection, or discover typed tools
+on a product server. Scope reads to the studio's account and Worker. Each additional
+server may require its own consent; do not promise a single shared token. Use official
+MCP reads instead of adding Homie account/log/issue clients.
+
+[Wrangler login](https://developers.cloudflare.com/workers/wrangler/commands/general/#login)
+is Cloudflare's own OAuth browser flow. Keep `cloudflare_login` and pinned Wrangler
+for builds/deploys, D1 migrations and R2 upload. Homie does not read Projects env files.
+
+## Existing studios
+
+Update the toolkit and Homie plugin together; run `homie-studio upgrade --apply`.
+Use the matching toolkit guides if an installed plugin is older. Stop running copied
+Homie provider scripts. The removed generation commands have no compatibility path.
+Connect the official plugins in the AI client and report successful authenticated
+reads to `setup_status.integrations`. A local CLI installation or a key file is not
+connection evidence. Unknown stays unknown; optional connections never block local work.
+
+Remove old credential instructions from studio notes and copied skills. Homie upgrade
+replaces its exact retired credential-guidance section in AGENTS.md/CLAUDE.md/README.md;
+review custom instructions separately. Never open old credential files to migrate them.
+The owner can revoke retired credentials in provider settings and remove old files
+through their own credential manager. Existing outputs and receipts remain valid records;
+importing them is local and does not charge again. Stripe's shop integration is separate.

package/guides/style/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: style
 description: "A game's look as a set of decisions that fit together — render style, palette, shape language, proportions, materials, light, camera, fonts and effects; then the cast, its library family, scale and phone budgets — each picked automatically from the person's words with a one-line why, which the person can steer (\"warmer\", \"closer\"), lock, or explore on a style board of three directions drawn by the game engine itself (free; a painted mood image only on their own fal account). Locked and pinned decisions keep every asset coherent: change one and the blast radius lists exactly what went stale and what remaking it would cost, and nothing is remade without a yes. Use when someone talks about a game's look or style, \"make it look like…\", \"show me other looks\", \"keep that palette\", \"darker\", \"the art doesn't fit together\", or before making any models or art for a game."
-compatibility: Node 22 and Chrome. The style board is free; a painted mood image uses the creator's own fal account (FAL_KEY), through the models skill.
+compatibility: Node 22 and Chrome. The style board is free; a painted mood image uses the creator's own fal account through the official fal MCP.
 metadata:
   providers: fal
 ---
@@ -57,8 +57,8 @@ before you show them (file_read), and say in one line each what is different.
   with `style set` within them.
 - **Lock** when the person says so: `style lock <id> style.palette --words "<what they said>"`, or the whole
   style: `style lock <id> style --words "…"`.
-- **A painted mood image** per direction is optional and PAID (about US$0.035 each, the person's own fal
-  account, `models.mjs mood`): a picture the engine cannot draw is a target, never a promise, and the card says
+- **A painted mood image** per direction is optional and PAID (quoted through the official MCP, the person's own fal
+  account, the official fal MCP): a picture the engine cannot draw is a target, never a promise, and the card says
   so. Offer it only when the engine's swatches leave the person unsure.
 - **Golden images**: once the style is locked, two to six approved pictures (a chosen mood image, a concept they
   loved, their own art) become the references of every generated concept: `style golden <id> add <image>`.
@@ -103,3 +103,66 @@ would cost. Nothing is remade by itself: remaking is a new, priced job they appr
 - Never present a painted mood image as what the game looks like.
 - Never name a living artist in a style ("in the style of …"): describe the look in words.
 - Never "upgrade" a game whose procedural look is its strength to generated meshes without the owner's ask.
+
+## Painted style references
+
+Use the art skill and official fal MCP for optional painted mood images. Build the prompt
+from the derived style and approved references; record the style revision, cost and rights
+with each result. Keep boards in the codex and mark targets distinct from playable frames.
+
+## Official generation workflow
+
+The owner's AI uses the provider's official plugin/MCP in its own client. Homie never
+asks for, stores, reads or prints provider credentials. Read the current provider
+skill and discover its available tools and input schemas; host prefixes vary.
+Connection instructions and verified sources: [official integrations](../studio-setup/references/OFFICIAL-MEDIA.md).
+If tools are missing, connect that official plugin once in the client's browser flow.
+Do not fall back to a Homie client, key file, environment key or CLI generation wrapper.
+
+Before spending, state the model, count/duration, estimated cost and remaining approved
+budget. Use the owner's existing authorization; ask only if the spend is outside it.
+Record the request ID as soon as accepted. Poll that same request; never resubmit to
+retry a slow job. Unknown cost is unknown, never zero. Provider billing is authoritative;
+Homie's local receipt cannot enforce spending in another client.
+
+## Place and prove the result
+
+Download the completed tool's output using the AI client's file/download facilities.
+Keep temporary signed URLs out of committed records. Keep the original in the studio's
+art/job folder; put the optimized delivered asset beside its game/app, or in music/ or
+videos/ for a published work. Record a receipt with these fields:
+
+```json
+{
+  "provider": "fal",
+  "tool": "run_model",
+  "model": "exact endpoint returned by the provider",
+  "requestId": "actual request ID",
+  "prompt": "the actual prompt, including style constraints",
+  "styleRevision": "revision from the studio's style",
+  "rights": {"source": "provider/model terms URL", "checkedAt": "YYYY-MM-DD", "commercial": false, "note": "record the actual plan and permitted use"},
+  "cost": {"status": "unknown"}
+}
+```
+
+For ElevenLabs use its actual discovered tool and model, and its flow/session or request
+identifier. A measured cost uses `{"status":"actual","amount":1,"unit":"credits"}`;
+a quote uses `estimate`. Never claim commercial rights from the fact that generation
+succeeded. Read the provider and model terms for the account's plan; record attribution,
+reference-image permissions and any restrictions. Mark test fixtures `"fixture": true`.
+
+Wire the delivered path into the scene or manifest, then run:
+
+```sh
+npx --no-install homie-studio media import --file <downloaded-file> --receipt <receipt.json> --out games/<id>/assets/<name> --used-by games/<id>/view.ts
+```
+
+This copies bytes, verifies a static reference, hashes the asset and records allowlisted
+provenance in `media/provenance.json`. Reimporting the same output is idempotent; it
+never generates or charges. Include each generation step's receipt for derived assets.
+Run the scene and look/listen: a file and static reference are not proof that it renders
+or plays. Report the placed path, usage evidence, rights and actual/estimated cost.
+
+The toolkit’s `lib/media-workflows.mjs` declares this skill’s verified tool references.
+Validate them against the host’s current tool inventory before execution; tool discovery
+is required for generation capabilities that have no stable documented name.

package/guides/video/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: video
+description: "Capture and edit studio videos locally, and generate requested shots through the official fal MCP."
+compatibility: Node 22 and the official fal plugin in the AI client. Local media processing uses ffmpeg and Chrome where needed.
+metadata:
+  providers: fal
+---
+
+# Video from the studio
+
+Start with the actual running game/app. Plan a short sequence that shows its central
+action, one progression moment and a truthful call to action. Capture gameplay locally;
+do not pass generated footage off as gameplay. Derive generated shots from the locked
+style and approved reference frames, preserving composition and character continuity.
+
+For requested generated footage, use fal's `recommend_model`/`search_models`,
+`get_model_schema`, `get_pricing`, then `submit_job`, `check_job` and `get_job_result`.
+Specify count, duration, resolution and whether audio is needed. Inspect a first shot
+before chaining more. The provider plugin owns uploads and generation.
+
+Local `scripts/video.mjs` keeps capture/record/trailer, beat grids, slices, timing checks,
+editing and delivery. Read `references/RECORD.md` for page capture. Check contact sheets,
+then watch with audio at speed; verify sync, text legibility, transitions and both phone
+and landscape framing. Keep masters in `videos/<slug>/`, export compressed deliverables
+and register them in `videos/manifest.json`. Check that the site page plays the delivered
+file and credits its inputs. Deployment is a separate requested action.
+
+## Official generation workflow
+
+The owner's AI uses the provider's official plugin/MCP in its own client. Homie never
+asks for, stores, reads or prints provider credentials. Read the current provider
+skill and discover its available tools and input schemas; host prefixes vary.
+Connection instructions and verified sources: [official integrations](../studio-setup/references/OFFICIAL-MEDIA.md).
+If tools are missing, connect that official plugin once in the client's browser flow.
+Do not fall back to a Homie client, key file, environment key or CLI generation wrapper.
+
+Before spending, state the model, count/duration, estimated cost and remaining approved
+budget. Use the owner's existing authorization; ask only if the spend is outside it.
+Record the request ID as soon as accepted. Poll that same request; never resubmit to
+retry a slow job. Unknown cost is unknown, never zero. Provider billing is authoritative;
+Homie's local receipt cannot enforce spending in another client.
+
+## Place and prove the result
+
+Download the completed tool's output using the AI client's file/download facilities.
+Keep temporary signed URLs out of committed records. Keep the original in the studio's
+art/job folder; put the optimized delivered asset beside its game/app, or in music/ or
+videos/ for a published work. Record a receipt with these fields:
+
+```json
+{
+  "provider": "fal",
+  "tool": "run_model",
+  "model": "exact endpoint returned by the provider",
+  "requestId": "actual request ID",
+  "prompt": "the actual prompt, including style constraints",
+  "styleRevision": "revision from the studio's style",
+  "rights": {"source": "provider/model terms URL", "checkedAt": "YYYY-MM-DD", "commercial": false, "note": "record the actual plan and permitted use"},
+  "cost": {"status": "unknown"}
+}
+```
+
+For ElevenLabs use its actual discovered tool and model, and its flow/session or request
+identifier. A measured cost uses `{"status":"actual","amount":1,"unit":"credits"}`;
+a quote uses `estimate`. Never claim commercial rights from the fact that generation
+succeeded. Read the provider and model terms for the account's plan; record attribution,
+reference-image permissions and any restrictions. Mark test fixtures `"fixture": true`.
+
+Wire the delivered path into the scene or manifest, then run:
+
+```sh
+npx --no-install homie-studio media import --file <downloaded-file> --receipt <receipt.json> --out games/<id>/assets/<name> --used-by games/<id>/view.ts
+```
+
+This copies bytes, verifies a static reference, hashes the asset and records allowlisted
+provenance in `media/provenance.json`. Reimporting the same output is idempotent; it
+never generates or charges. Include each generation step's receipt for derived assets.
+Run the scene and look/listen: a file and static reference are not proof that it renders
+or plays. Report the placed path, usage evidence, rights and actual/estimated cost.
+
+The toolkit’s `lib/media-workflows.mjs` declares this skill’s verified tool references.
+Validate them against the host’s current tool inventory before execution; tool discovery
+is required for generation capabilities that have no stable documented name.