@homie-rocks/studio 0.51.4 → 0.51.5

package/CHANGELOG.md

@@ -17,6 +17,35 @@ 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.5] - 2026-10-14
+
+**Plugin 0.51.5**
+
+Connect your shop and media through official plugins, keep renewals and free bookings working, and see progress while you build.
+
+### Added
+
+- **Shop setup:** Stripe's official plugin can configure and verify products, prices, item and menu links, paid bookings, monthly giving and the customer portal. Homie plans only the changes your shop needs. No API keys are requested; webhook installation checks the Stripe account and passes the signing secret privately to Wrangler, never through the model. Local webhook forwarding keeps its secret private too.
+- **Build iteration:** Builds report progress, including during JSON output, and show a heartbeat while generated rules play. `build --quick` keeps type and guard checks while skipping play and snapshot smoke checks.
+- **Media placement:** `media import` places completed media, checks scene references and records file hashes, rights, provenance and explicit cost status. Video guidance and local processing tools now ship with the toolkit.
+
+### Changed
+
+- **Official media connections:** Art, models, music, sound, video and style use the official fal and ElevenLabs plugins in your AI client. Homie still handles art direction, local processing, placement and provenance. Its own provider generation clients, key-file readers and Stripe Projects credential bridge have been removed.
+- **Connection setup:** Setup reports official connections verified in the current session and explains browser sign-in. Cloudflare inspection uses its official MCP; deployment continues through Wrangler's browser login.
+
+### Fixed
+
+- **Recurring gifts and memberships:** Each renewal reaches your shop and notifies apps once, even when the studio also sells parts. Renewals keep the original purchase reference so apps can identify the cause or member. Subscription updates and cancellations reach the shop; parts payments retain their own route.
+- **Free volunteer shifts and services:** Free bookings in a mixed free/paid app work before Stripe is connected. They confirm locally and enforce capacity; paid checkout still requires a connection.
+
+### Upgrade notes
+
+- Update the toolkit and Homie plugin together, run upgrade, and connect the official provider plugins in your AI client. Existing media remains usable. Upgrade replaces retired credential instructions without reading or migrating old key files. Available ElevenLabs media capabilities depend on the connected server and are checked before generation.
+- Shop setup starts with `stripe_shop_plan` / `shop plan`, then `stripe_webhook` / `shop webhook`. Private webhook setup may need a separate Stripe CLI browser approval. `shop connect` remains the full CLI alternative; `shop listen` forwards local events privately.
+- Run a full build before release, even if you used `build --quick` while iterating.
+- Remove any temporary subscription-routing postinstall workaround for 0.51.3–0.51.4 after upgrading.
+
 ## [0.51.4] - 2026-10-14
 
 **Plugin 0.51.4** · Studio events through experimental MCP Events.

package/README.md

@@ -513,17 +513,7 @@ npx homie-studio shop                         # open (test or live) or what is m
 npx homie-studio shop refund ord_…            # an ASK: the owner taps once (or Refund in /_studio/office/shop)
 ```
 
-Connect with `stripe_login` or `shop connect`: the owner approves Stripe's official browser page, sandbox first.
-Where the CLI supplies a transferable legacy test key, the toolkit creates the webhook and installs both Worker
-secrets privately. It reports the 90-day expiry; `shop connect --renew` obtains approval again. Current CLI OAuth
-and live mode cannot export an independent Worker's key, so the result names that limitation. Only if the owner
-chooses the fallback does `shop connect --manual` open the old local key page (`--manual --live` for live mode).
-Never request a key in chat. Login is not a verified purchase; complete the test purchase, webhook and refund check.
-
-Stripe's optional agent tools (`stripe agent setup`) provide MCP and skills for catalog work (`shop catalog`),
-tax reads and sales questions. They are separate from the Worker's credentials. Never create a webhook through
-MCP because its response contains a secret. From 2026-10-31 Stripe MCP accepts only OAuth or Agent-tagged keys;
-that change does not affect the shop's ordinary restricted API key. [SHOP.md](shop/SHOP.md) describes the flow.
+Connect through Stripe’s official OAuth plugin: `stripe_shop_plan` gives exact catalog, menu, booking and recurring operations for Stripe MCP and verifies its fresh reads. `stripe_webhook` privately installs the signing secret using one separate Stripe CLI browser approval if needed. No owner handles a key. `shop connect` remains the CLI alternative. [SHOP.md](shop/SHOP.md) describes the flow.
 
 In a game: `createShop()` from `@homie-rocks/studio/shop` (`has`, `entitlements`, `on('change')`, `open`, `used`, `add`, `checkout`, `buy`); a
 supporter's badge rides on their seat (`peer.badge`). Stripe Checkout (hosted), optional Stripe Tax, or Stripe Managed
@@ -1185,26 +1175,17 @@ no Wrangler, no rooms, the game alone and offline with its bots) and shoots that
 there (it needs rooms: use `dev` and `--url`). The result names the build the frames are of, by the hash `build`
 printed and the hashed bundle the page loaded.
 
-## Another way to Cloudflare: Stripe Projects (a prototype, 0.24.3)
+## Official media and hosting connections
 
-`npx wrangler login` stays the way. For a creator with no Cloudflare account (and no ElevenLabs), Stripe Projects
-(Stripe's CLI plugin, docs.stripe.com/projects) can make or link both on the person's own Stripe sign-in, on free
-plans, and hand the credentials to the studio folder:
+Connect fal and ElevenLabs through their official plugins in your AI client and approve
+one browser sign-in per provider. Homie never handles their credentials. Cloudflare's
+plugin provides account inspection; deployment keeps pinned Wrangler's own browser login.
+See [connection and upgrade guidance](guides/studio-setup/references/OFFICIAL-MEDIA.md).
 
-```sh
-npx homie-studio setup --via stripe-projects [--with elevenlabs] --dry-run   # what it would do; changes nothing
-npx homie-studio setup --via stripe-projects [--with elevenlabs] --accept-tos  # after the person accepted the providers' terms
-```
-
-It stops with a `needs` step at each thing that is the person's (the Stripe CLI and its Projects plugin, Stripe's
-sign-in, the providers' terms, Cloudflare's own approval page for an existing account); it never adds a paid plan or
-a payment method. The Cloudflare account id goes in studio.json with `"auth": "stripe-projects"`; the token stays in
-Projects' vault and the git-ignored `.env` it syncs, and every Wrangler run in the studio takes it from there
-(`deploy`, `dev`, secrets, the office). It checks read-only what the token can do (Wrangler signed in, D1, Workers AI;
-R2 is optional) and that `.gitignore` keeps `.env`, `.env.*`, `.projects/vault/` and `.projects/cache/` out of git.
-With `--with elevenlabs` the music skill finds the ElevenLabs key there too (ElevenLabs' free plan has no commercial
-licence). Unverified until a real run: the exact JSON of the Projects commands, and the Cloudflare token's permission
-groups, which the checks measure instead of assuming.
+`homie-studio media import --file <download> --receipt <receipt.json> --out <studio-path>
+--used-by <scene-file>` places a completed asset and records its hash, rights, style and
+cost status in `media/provenance.json`. It makes no provider calls. The scene file must
+reference the delivered path; also verify the asset in the running scene.
 
 ## No payment method needed
 

package/apps/APPS.md

@@ -114,7 +114,7 @@ information in a separate private collection. Public roles must not have write
 capabilities for slots or bookings. Staff movement is a versioned record update
 containing only `slot`; confirmation and release follow verified Checkout state.
 The default keyless connection uses one Payment Link per published slot. Call
-`stripe_bookings_sync` after publishing/changing slots. Pending checkout does not
+`stripe_shop_plan` with the complete slot manifest after publishing/changing slots. Pending checkout does not
 block others; payment secures the seat. Use record.booking.full/available/synced
 for slot display. Read SHOP.md for the complete manifest and limitations.
 

package/bin/homie-studio.mjs

@@ -17,9 +17,9 @@
  *   homie-studio app role <id> <role> [--player <account>] [--revoke] [--url <site>]
  *   homie-studio game new <id> [--from gem-rush] [--name "<Game Name>"]
  *   homie-studio games
- *   homie-studio build [<id>] [--maps] [--types] [--long-check]   (--maps: also keep each bundle's source map and
+ *   homie-studio build [<id>] [--maps] [--types] [--long-check] [--quick]   (--maps: also keep each bundle's source map and
  *                                          module sizes in .studio/maps/<id>/, never in site/dist: what `perf` reads a
- *                                          CPU profile through; --types: check the games' TypeScript first, with the
+ *                                          CPU profile through; --quick: skip rules play and smoke checks; --types: check the games' TypeScript first, with the
  *                                          studio's own `typescript`; a type error stops the build; --long-check: play
  *                                          each rules game eight times as long before it is written (a rules game is
  *                                          always type-checked and played; this is more of the same play, for a
@@ -183,10 +183,11 @@
  *   homie-studio shop                     is the studio's shop selling (its own Stripe), and if not, what is missing
  *   homie-studio shop init [--supporter|--giving] [--currency <code>] [--price 500] [--managed]   shop.json and SELLING.md
  *   homie-studio shop check               shop.json against studio settings and provider requirements
- *   homie-studio shop connect [--live] [--renew] [--manual]   sync Payment Links and webhook through Stripe browser approval; --manual chooses the local page for the studio's
- *                                         restricted Stripe key; with it this makes the webhook (0.24.3), and the key
- *                                         and the webhook's secret go straight to the Worker secrets, never a chat or a
- *                                         file (test keys only unless --live)
+ *   homie-studio shop listen --profile <sandbox> [--port 8787]   private local webhook forwarding
+ *   homie-studio shop plan --have <file>    exact next operation for Stripe's official MCP (public reads only)
+ *   homie-studio shop verify --have <file>  verify fresh MCP reads and save the public link configuration
+ *   homie-studio shop webhook [--live] [--renew]   privately install webhook using one Stripe CLI browser approval
+ *   homie-studio shop connect [--live] [--renew]   alternative: full sync through Stripe CLI approval
  *   homie-studio shop catalog [--have <file>|-] [--mode test|live]   the items as Products in the studio's Stripe,
  *                                         made by the AI through Stripe's own MCP: the read first, then (with what it
  *                                         answered) the exact writes; in sync, shop.json "catalog" records the mode
@@ -226,14 +227,9 @@
  *   homie-studio setup attach <hs_…> [--client claude|codex|grok]
  *                                          (this repository is the studio the chat's setup card is making: say so, once,
  *                                          learn its live address, and give a template copy its real name)
- *   homie-studio setup --via stripe-projects [--with elevenlabs] [--accept-tos] [--dry-run]
- *                                         (a prototype, 0.24.3: Cloudflare, and ElevenLabs with --with, made or linked
- *                                          through Stripe Projects on their free plans; the person accepts the providers'
- *                                          terms (then --accept-tos) and signs in on Stripe's and the provider's own
- *                                          pages; the account id goes into studio.json, the token stays in Projects'
- *                                          vault and its git-ignored .env, and Wrangler runs with it here. The usual
- *                                          way, npx wrangler login, stays the default. lib/projects.mjs)
  *   homie-studio domain <hostname>                  AI configures DNS/TLS for the next deploy
+ *   homie-studio media import --file <download> --receipt <receipt.json> --out <studio-path> --used-by <scene-file>
+ *                                          Place completed official MCP output with provenance (no provider calls)
  *   homie-studio setup prepare                     AI installs a private Node/npm if missing
  *   homie-studio setup status [--connector yes|no] [--client claude|codex|grok]   (also: homie-studio doctor)
  *                                         what this computer and the person's accounts have for a studio: Node, the Homie
@@ -325,6 +321,7 @@
  *
  * Every command prints a few lines for a person; --json prints the result.
  */
+import { importMedia } from '../lib/media-import.mjs';
 // FIRST, before any other file of the toolkit is evaluated: a Node.js that is too old ends here, with the reason.
 import '../lib/node-version.mjs';
 import { spawn, spawnSync } from 'node:child_process';
@@ -362,8 +359,6 @@ import { agentsBrain, agentsBrainKey, agentsPass, agentsPasses, agentsRevoke, ag
 import { AgentSeat } from '../lib/agent-seat.mjs';
 import { shopCheck, shopConnect, shopDisconnect, shopInit, shopLines, shopOrders, shopRefund, shopStatus } from '../lib/shop.mjs';
 import { catalogLines, catalogPlan } from '../lib/shop-catalog.mjs';
-import { projectsLines, setupViaProjects } from '../lib/projects.mjs';
-import { projectsCloudflareEnv } from '../lib/projects-env.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
 import { formatStatus, setupStatus } from '../lib/doctor.mjs';
 import { codexTarget, newCodex, writeCodexPage } from '../lib/codex.mjs';
@@ -384,22 +379,23 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['public', 'lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'giving', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
+// build --quick keeps compilation and type checks, skips rules generated play/smoke checks.
+const BOOL_FLAGS = ['quick', 'public', 'lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'giving', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a.startsWith('--')) {
     const [k, v] = a.slice(2).split(/=(.*)/s, 2);
     if (v !== undefined) flags.set(k, v);
-    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && !BOOL_FLAGS.includes(k)) flags.set(k, argv[++i]);
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && (!BOOL_FLAGS.includes(k) || k === 'profile' && argv[0] === 'shop')) flags.set(k, argv[++i]);
     else flags.set(k, true);
   } else positional.push(a);
 }
 const asJson = flags.has('json');
-const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
+const log = asJson && positional[0] !== 'build' ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
-  if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
+  if (asJson || /^shop (plan|verify)$/.test(result.command ?? '')) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
   // A standalone plan or build says every target, built or not, and what a standalone copy does not have.
   if (/^standalone( |$)/.test(String(result.command ?? ''))) { process.stdout.write(`${standaloneLines(result).join('\n')}\n`); return; }
   // A check that found problems still prints them (its rows say what to fix), never a bare "failed".
@@ -635,9 +631,6 @@ function print(result) {
     case 'shop catalog':
       lines.push(...catalogLines(result));
       break;
-    case 'setup':
-      lines.push(...projectsLines(result));
-      break;
     case 'chat rules':
     case 'chat budget':
     case 'lounge rules':
@@ -846,6 +839,8 @@ 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 listen': ['profile','port'],
+  'shop webhook': ['live','renew','profile'],
   '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'],
@@ -936,12 +931,7 @@ async function main() {
   if (cmd === 'progress') return progressCommand(root, sub);
   if (cmd === 'domain') return studioDomain(root, sub);
   if (cmd === 'setup' && sub === 'attach') return setupAttach(root, positional[2], { homie: flags.get('homie'), client: flags.get('client') });
-  if (cmd === 'setup' && flags.has('via')) {
-    if (flags.get('via') !== 'stripe-projects') return { ok: false, command: 'setup', why: '--via stripe-projects is the one other way this version knows (the default is npx wrangler login)' };
-    const extra = String(flags.get('with') ?? '').split(',').map((x) => x.trim()).filter(Boolean);
-    if (extra.some((x) => x !== 'elevenlabs')) return { ok: false, command: 'setup', why: '--with takes elevenlabs (Cloudflare is always set up)' };
-    return setupViaProjects(root, { withElevenlabs: extra.includes('elevenlabs'), acceptTos: flags.has('accept-tos'), dryRun: flags.has('dry-run'), log });
-  }
+  if (cmd === 'media' && sub === 'import') return importMedia(root, { file: flags.get('file'), receipt: flags.get('receipt'), out: flags.get('out'), usedBy: flags.get('used-by') });
   if (cmd === 'handoff') return handoff(root, sub, { homie: flags.get('homie'), client: flags.get('client') });
   if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
   if (cmd === 'port' && sub === 'check') {
@@ -963,7 +953,7 @@ async function main() {
   // go, so an old note, an old card or an agent's memory of the toolkit does not end at "unknown command".
   if (cmd === 'game' && sub === 'remix') return { ok: false, command: 'game remix', why: 'remix was retired: a game is no longer handed over whole, and no studio serves one. Games build on each other through parts, the pieces of a game its studio chose to share: find one with `homie-studio parts find <words>` and bring it in with `homie-studio parts add` (in chat: parts_find, part_add; parts/PARTS.md)' };
   if (cmd === 'games') return { ok: true, command: 'games', games: listGames(root).map(({ dir, ...g }) => ({ ...g, dir: relative(root, dir) })) };
-  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log, maps: flags.has('maps'), types: flags.has('types'), longCheck: flags.has('long-check') }), 'build');
+  if (cmd === 'build') return tracked(root, 'build', () => build(root, { only: positional[1] ?? null, log, maps: flags.has('maps'), types: flags.has('types'), longCheck: flags.has('long-check'), quick: flags.has('quick') }), 'build');
   if (cmd === 'preview') return preview(root, positional[1] ?? (listGames(root).length === 1 ? listGames(root)[0].id : null));
   if (cmd === 'perf' && sub === 'sizes') return perfSizes(root, positional[2] ?? listGames(root)[0]?.id);
   if (cmd === 'lab') return labCommand(root, sub);
@@ -1114,7 +1104,15 @@ async function main() {
     const url = flags.get('url');
     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==='listen')return (await import('../lib/shop-listen.mjs')).shopListen(root,{profile:flags.get('profile'),port:flags.get('port')??8787,log});
     if (sub === 'check') return shopCheck(root);
+    if (sub === 'plan' || sub === 'verify') {
+      const {shopMcpPlan,saveMcpVerification}=await import('../lib/shop-mcp.mjs');
+      const file=flags.get('have');
+      const input=file?JSON.parse(readFileSync(file==='-'?0:file,'utf8')):{};
+      return (sub==='verify'?saveMcpVerification:shopMcpPlan)(root,input);
+    }
+    if (sub === 'webhook') return shopConnect(root,{webhookOnly:true,live:flags.has('live'),renew:flags.has('renew'),profile:flags.get('profile'),log:line=>process.stderr.write(`${line}\n`)});
     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')});
@@ -1362,7 +1360,7 @@ function mediaPut(root, file, as) {
   const key = as ?? (/^(music|videos)\//.test(rel) && !rel.includes('..') ? rel : `${folder}/${basename(file)}`);
   const bin = wranglerBin(root);
   return new Promise((done) => {
-    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: workerDir(root), env: { ...process.env, ...projectsCloudflareEnv(root), CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
+    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: workerDir(root), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
     p.on('close', (code) => {
       if (code !== 0) return done({ ok: false, command: 'media put', why: 'wrangler r2 object put failed' });
       // The manifest is committed: it names the file by its path on the site, never the workers.dev address.

package/guides/app/SKILL.md

@@ -183,7 +183,7 @@ Scaffold businesses with `new <folder> --kind business`; causes with `--kind cau
 
 For giving, set the studio currency and run `shop init --giving --currency CAD` (use the organisation’s currency). It creates one-time/monthly suggested gifts. The owner supplies `giving.receiptText` in shop.json; Homie supplies no legal or tax text. Before Stripe is connected, local /shop/ previews items and prices with checkout disabled. Run the connection step yourself; the owner approves their Stripe account in the browser.
 
-Use `shop.book` and the booking collection declaration in SHOP.md. Default keyless booking links show pending while paying; an unpaid guest does not block others. Stripe limits completed sessions to capacity. The owner’s AI syncs published/changed slots with `stripe_bookings_sync`. Say “Pay to secure your seat.” Exclusive unpaid holds require the explicitly selected optional keyed connection.
+Use `shop.book` and the booking collection declaration in SHOP.md. Default keyless booking links show pending while paying; an unpaid guest does not block others. Stripe limits completed sessions to capacity. The owner’s AI syncs published/changed slots with `stripe_shop_plan` and the complete slot manifest. Say “Pay to secure your seat.” Exclusive unpaid holds require the explicitly selected optional keyed connection.
 
 
 ## Tell my AI when a booking comes in

package/guides/art/SKILL.md

@@ -1,154 +1,82 @@
 ---
 name: art
-description: Make a studio's game look like something at build time — a cover from a real frame of the game (free), painted covers, backdrops, textures and character plates from image models through the creator's OWN fal account under a hard budget with a receipt for every call, checked (does the texture tile, is the file small enough for a phone, does the cover promise only what the game contains) and loaded by the game — plus the art-direction method (a style sheet and paintovers of real frames as the target the game's own rendering is changed to reach). Use when someone asks for cover art, key art, a thumbnail, a hero image, backgrounds, textures, sprites, or says the game looks rough, flat or unfinished.
-compatibility: Node 22, ffmpeg and Chrome. Generated images use the creator's own fal account (FAL_KEY); fal's own MCP server (https://mcp.fal.ai/mcp-relay) finds models and reads prices.
+description: "Make game and app art using the official fal MCP, studio art direction, local capture and asset checks."
+compatibility: Node 22 and the official fal plugin in the AI client. Local media processing uses ffmpeg and Chrome where needed.
 metadata:
   providers: fal
 ---
 
-# Art for a studio's game
-
-**Build time, never a frame of play.** Everything here happens once, before anybody plays, and costs
-nothing at runtime: never call an image model from a game's loop or from anything a person waits on.
-If you want one there, you want a baked asset instead.
-
-One script: `scripts/art.mjs` in this skill's folder (Claude Code:
-`node "${CLAUDE_PLUGIN_ROOT}/skills/art/scripts/art.mjs" <command>`), from inside the studio. Node 22,
-ffmpeg and Chrome; `--json` on every command. Art jobs live in `art/<slug>/` (the images, the
-`budget.json`, the `.request` and `.json` receipts beside each generated file); every paid call is
-also a line in `art/receipts.jsonl`.
-
-```sh
-node <art.mjs> check      # ffmpeg, Chrome, the studio; the fal key checked for free (only generated images need it)
-```
-
-## 1. The cover, first, always
-
-The cover is what a stranger sees before pressing anything: the studio's game page, the directory
-card, a link preview. Start from the game itself:
-
-```sh
-npm run dev                                                       # background task
-node <art.mjs> frame <game> --url http://127.0.0.1:8787           # real game frames, the most detailed picked
-node <art.mjs> cover <game> --from art/frames/frame-04.png [--focus 0.6,0.4]
-```
-
-`frame` uses the play view for server rules so the camera's seat keeps the room
-running, and the big screen for older games. It hides the platform's furniture
-(join QR, status chip, result cards) and keeps the frame with the most visible detail.
-For `--view tv` in a rules game, keep a real player in that same room: a TV alone
-does not keep a server match running. A paused-room message means use `--view play`
-or open a player, not change hosting mode.
-`cover` crops it to 16:9 around the focus, writes `cover.jpg` (1600x900, under 400 KB) into the game
-and names it in `game.json` (`"cover": "cover.jpg"`): the site and the directory use it until the game's
-landing has a still of its own (`hero/wide.jpg`), which then is its picture everywhere.
-
-**Open the cover and look.** A cover is a picture of the GAME: no QR code, no share panel, no debug
-text, not the waiting screen (a picture of nothing happening). Dark or featureless frames get a
-warning: a black card on a page reads as a black box.
-
-**A painted cover** from that frame, when the person wants one (paid, below): write the prompt from
-the game you just played, never from its title. Describe what is on screen: the palette, the time of
-day, what the player is doing, the shapes. A cover that promises something the game does not contain
-is the one failure here that matters: a person presses Play expecting that picture and meets
-something else. Use the real frame as the image reference (`"@file:art/frames/frame-04.png"` in the
-input) so the painting keeps the game's layout.
-
-## 2. Paid images: price, budget, one call at a time
-
-Use an already connected fal account for paid generation; never ask the person to find or set a key.
-The local paid script discovers an existing fal key using the lookup below. If none is available, continue
-with local assets or captured footage and explain that this paid-script connection is not ready.
-Do not make account configuration a prerequisite for a live studio. **fal's own MCP server** is how you find a
-model and read its input schema and price (`search_models`, `recommend_model`, `get_model_schema`,
-`get_pricing`): use it rather than memory, because endpoints retire and reprice. Not connected? Offer
-it, and the person signs in on fal's own page (no key): in Claude Code `claude mcp add --transport http
---scope user fal https://mcp.fal.ai/mcp-relay`, then `/mcp`; in Codex `codex mcp add fal --url
-https://mcp.fal.ai/mcp-relay`, then `codex mcp login fal`. **Paid calls go through `art.mjs gen`,
-never the MCP's `run_model` or `submit_job`**: `gen` prices, caps, receipts and resumes; the MCP's run
-does none of that (the Homie mod in Claude Code, and Homie's hooks in Codex, hold one as a call whose cost cannot be read first).
-
-```sh
-node <art.mjs> price --model fal-ai/flux/dev --input art/cover/input.json    # free: fal's unit price x this input
-node <art.mjs> budget cover --cap <dollars the person agreed to>
-node <art.mjs> gen cover --model fal-ai/flux/dev --input art/cover/input.json --out cover-painted.jpg --dry-run
-node <art.mjs> gen cover --model fal-ai/flux/dev --input art/cover/input.json --out cover-painted.jpg --yes
+# Art for this studio
+
+Read the game's or app's style, codex and existing scene before writing a prompt.
+Use its palette, shape language, materials, lighting and camera. Keep approved references
+and the style revision. Covers must describe what the playable experience really offers.
+A frame from the running game is free and often the best cover.
+
+For generated art use fal's `recommend_model` or `search_models`, `get_model_schema`
+and `get_pricing`, then `run_model`. Continue a pending request with `check_job` and
+`get_job_result`. Use `upload_file` only as documented by the official plugin for references.
+Set an explicit image count. Inspect the first result before any dependent generation.
+
+Local `scripts/art.mjs` keeps `check`, `frame`, `cover`, `tile`, `fit` and `sheet`.
+Use `cover <game> --from <image>` for a 1600×900 cover and game.json reference;
+`fit <image> --out <file>` for phone-sized delivery. Check tile seams with a repeated
+2×2 preview, transparency against light and dark, readability at phone size, and
+compression after fitting. Do not replace an engine effect with a large image by default.
+
+## 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"}
+}
 ```
 
-- Tell the person the price and ask for a cap before the first call. `gen` refuses with no budget,
-  refuses past the cap, and asks again without `--yes`.
-- The receipt is written the moment fal accepts the job. Running the same `gen` again resumes it from
-  `<out>.request`: it never pays twice. A cut-off call is resumed, not re-sent.
-- **Never run paid generation in a loop** to "try until it is good". Look at what came back, change
-  the prompt, run it once more. Spend the riskiest image first.
-- No real people, no real brands, no copyrighted characters, no "in the style of" a living artist, in
-  prompts or references.
-- **Every prompt starts from the game's derived style prompt** (`homie-studio style prompt <id>`: medium,
-  shape, palette hexes, light, framing; computed from the decisions, never edited by hand) and uses the golden
-  images as references on a multi-reference model. A picture made under an older palette is listed stale when
-  the palette changes (the `style` skill's blast radius).
-- What the provider's terms say about the pictures, with read dates: `references/RIGHTS.md`. Read the live page
-  again before anything commercial is published.
-- 3D models (props, characters) are the `models` skill's; mood images for the style board are too
-  (`models.mjs mood`).
+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`.
 
-## 3. Backdrops, textures, plates
-
-A procedural gradient sky is the tell that a game was generated; a painted one costs one image at build
-time and loads like any other asset. Good candidates: a skybox or far matte, a ground or wall texture,
-a character plate, a title card. Bad: anything the game generates procedurally for a reason.
+Wire the delivered path into the scene or manifest, then run:
 
 ```sh
-node <art.mjs> tile art/floor/floor.png                                      # does it tile? seam numbers and a 2x2 preview
-node <art.mjs> fit art/floor/floor.png --out games/<id>/public/art/floor.jpg --width 1024 --max-kb 250
-node <art.mjs> sheet art/floor                                               # everything in a job, labelled, to look at
+npx --no-install homie-studio media import --file <downloaded-file> --receipt <receipt.json> --out games/<id>/assets/<name> --used-by games/<id>/view.ts
 ```
 
-- **Models are bad at tiling.** Ask for a texture, then check it: a seam over 2 shows as a grid of
-  lines in the game. Mirror-blend the edges or make it tile yourself before it ships.
-- **Size is a feature.** A phone downloads every byte before the first round. Fit backdrops to the
-  size they are drawn at, JPEG (or WebP where ffmpeg has it) for pictures, PNG only for hard-edged
-  sprites with transparency. Then play it again: the `playtest` skill's first row times the load; an
-  asset that doubled the load time made the game worse.
-- Put art where the game's own build puts assets (`games/<id>/public/` for a bundled game, the
-  game's folder for a static one) and load it with a relative path.
-
-## 4. Art direction: paintovers, then change the game
-
-Images do not fix a game that looks unfinished; the best-loved browser games often ship no texture
-files at all. What makes a frame look finished is light, contrast between the subject and the ground,
-detail at more than one scale, and a clear horizon or depth. The method:
-
-1. **The style bible is the game's decisions** (the `style` skill): render style, palette with its jobs,
-   light, shape language, camera, fonts, drawn in the codex's Art direction tab. An older studio's
-   `art/STYLE.md` retires into it: carry what it says into `style set` / `style steer`, then keep only the
-   decisions. Paint with the LOCKED palette and light.
-2. **Paintovers**: real frames of the game (`frame`), painted over by an image model with the derived style
-   prompt (`npx --no-install homie-studio style prompt <id>`) and the frame as the reference, plus the golden
-   images (`style golden`) where there are any. These are the TARGET, never shipped as the game.
-3. **Change the game's own rendering** (lights, materials, fog, the floor, the camera) until frames of
-   the running game match the paintover; compare them side by side.
-4. **Judge blind**: frames of the old build, the new one and a reference game the person admires,
-   shuffled under random labels, scored by a fresh reviewer before the labels are revealed (the
-   `playtest` skill's review). A reference is a bar, not a template.
-
-## Tell the person
-
-What was made and where it is used, the file sizes, what it cost (from the receipts) against the cap,
-what is a real frame and what is generated, and the pictures themselves.
-
-## Never
-
-- Never ship generated art as a screenshot of gameplay, or a cover that shows what the game does not have.
-- Never spend without a budget, past it, or without a receipt; never print or store a key.
-- Never replace art a person made without asking.
-
-### Existing provider credentials
+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 tools read `FAL_KEY` or `ELEVENLABS_API_KEY` first, then the plain single-line
-key in `~/.homie/keys/fal-key` or `~/.homie/keys/elevenlabs-key`. They also accept
-`~/.homie/workspace/fal-key` and `~/.homie/workspace/elevenlabs-key` from earlier
-installs. Checks name the source, never the key. Keep these files private (mode
-0600); never copy them into a studio. ElevenLabs also accepts its CLI browser
-sign-in and the existing Stripe Projects connection. Run the tool’s `check`
-before declaring a provider disconnected.
+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.