@homie-rocks/studio 0.51.4 → 0.51.6

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.

package/guides/art/scripts/art.mjs

@@ -1,33 +1,13 @@
 #!/usr/bin/env node
-/**
- * art.mjs: a game's cover, painted backdrops and textures, made at build time and never while
- * anyone plays. Real frames come from the running game for free; generated images come from fal
- * through the creator's own account, priced first, capped by a budget, receipted the moment fal
- * accepts them.
- *
- *   check                                   ffmpeg, Chrome, the studio, the fal key (a free check)
- *   frame <game> --url <site> [--view tv|play] [--seconds 12] [--slug <art job>]
- *                                           real frames of the game playing, the busiest one picked
- *   cover <game> --from <image> [--focus x,y]
- *                                           the game's cover: 16:9, 1600x900 JPEG, into the game, named in game.json
- *   budget <slug> --cap <usd>               what the person agreed to spend on this art job
- *   price --model <fal model> --input <input.json>
- *   gen <slug> --model <fal model> --input <input.json> --out <file> [--dry-run | --yes]
- *                                           one paid image (or a few), inside the cap, resumable, receipted
- *   tile <image>                            does a texture tile without a seam? numbers and a 2x2 preview
- *   fit <image> --out <file> [--width 1024] [--max-kb 300]
- *                                           a texture or backdrop at a size a phone can download
- *   sheet <folder>                          a labelled contact sheet of every image in a folder
- *
- * Every command takes --json. Run it from inside the studio (the folder with studio.json).
- */
+/** art.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 { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { experienceDir, experienceJson, isServerRules, SLUG, checkBudget, findStudio, readBudget, readJson, setBudget, writeJson } from '../../music/scripts/lib/studio.mjs';
 import { GPU_FLAGS, chromePath, htmlToPng, loadPuppeteer } from '../../video/scripts/lib/browser.mjs';
-import { checkKey, falKey, priceOf, run as falRun } from '../../video/scripts/lib/fal.mjs';
+
 import { decode, stats } from '../../playtest/scripts/lib/pixels.mjs';
 
 const argv = process.argv.slice(2);
@@ -61,29 +41,15 @@ function gameDir(root, game) {
 }
 
 /** A receipt line: the job's budget (running total), art/receipts.jsonl, and HOMIE_SPEND_LEDGER when set. */
-function receipt(root, dir, line) {
-  const at = new Date().toISOString();
-  const b = readBudget(dir);
-  if (b) {
-    b.spent = +(b.spent + (Number(line.cost) || 0)).toFixed(6);
-    b.calls.push({ at, provider: line.provider, model: line.model, cost: line.cost, unit: line.unit, requestId: line.requestId ?? null, artifact: line.artifact ?? null });
-    writeJson(join(dir, 'budget.json'), b);
-  }
-  mkdirSync(join(root, 'art'), { recursive: true });
-  appendFileSync(join(root, 'art', 'receipts.jsonl'), `${JSON.stringify({ schema: 'homie.media-receipt/1', at, ...line })}\n`);
-  const ledger = process.env.HOMIE_SPEND_LEDGER;
-  if (ledger) {
-    try { appendFileSync(ledger, `${JSON.stringify({ schema: 'homie.brand-spend/1', at, provider: line.provider, model: line.model, jobId: line.requestId ?? null, units: line.units ?? null, unit: line.unitName ?? line.unit, usd: line.cost, credits: null, unpriced: null, brand: process.env.HOMIE_SPEND_BRAND ?? null, attribution: process.env.HOMIE_SPEND_ATTRIBUTION ?? null, artifact: line.artifact ?? null })}\n`); } catch (e) { process.stderr.write(`could not write the ledger: ${e.message}\n`); }
-  }
-}
+
 
 /* ---------------------------------------------------------------- check */
 
 async function check() {
   const ff = spawnSync('ffmpeg', ['-version']).status === 0;
   const root = findStudio();
-  const key = falKey() ? await checkKey() : { ok: false, why: 'FAL_KEY is not set (only generated images need it; frames, covers, tiles and fitting are free)' };
-  return { ok: ff, command: 'check', ffmpeg: ff, chrome: chromePath(), puppeteer: Boolean(loadPuppeteer(root)), studio: root, fal: key.ok ? `the key works (checked free; from ${key.source})` : key.why };
+  return { ok: ff, command: 'check', ffmpeg: ff, chrome: chromePath(), puppeteer: Boolean(loadPuppeteer(root)), studio: root, generation: 'Use the official fal MCP in your AI client' };
+
 }
 
 /* ---------------------------------------------------------------- frame */
@@ -175,43 +141,6 @@ function budget(root) {
   return { ok: true, command: 'budget', slug: pos[1], cap: b.cap, spent: b.spent };
 }
 
-function inputOf(file) {
-  const j = readJson(resolve(String(file ?? '')), null);
-  if (!j) throw new Error('--input <file.json>: the model\'s input (its schema is on the model\'s fal page, or the fal MCP get_model_schema)');
-  return j;
-}
-
-async function price() {
-  const model = String(flags.get('model') ?? '');
-  if (!model) throw new Error('--model <fal model id, e.g. fal-ai/flux/dev>');
-  const p = await priceOf(model, inputOf(flags.get('input')));
-  return { ok: true, command: 'price', ...p };
-}
-
-async function gen(root) {
-  const slug = pos[1];
-  const dir = artDir(root, slug);
-  const model = String(flags.get('model') ?? '');
-  if (!model) throw new Error('--model <fal model id>');
-  if (!flags.get('out')) throw new Error('--out <file in this art job, e.g. cover-painted.png>');
-  const input = inputOf(flags.get('input'));
-  const out = resolve(dir, String(flags.get('out')));
-  if (!out.startsWith(`${dir}/`)) throw new Error('--out must stay inside the art job\'s folder');
-  if (existsSync(out)) return { ok: true, command: 'gen', slug, already: rel(root, out) };
-  const p = await priceOf(model, input);
-  if (flags.has('dry-run')) return { ok: true, command: 'gen', dryRun: true, slug, price: p };
-  const resuming = existsSync(`${out}.request`);
-  if (!resuming) {
-    const b = checkBudget(dir, p.usd, { provider: 'fal', unit: 'usd' });
-    if (!flags.has('yes')) return { ok: false, command: 'gen', needs: 'approval', slug, price: p, budget: { cap: b.cap, spent: b.spent }, why: `This call costs about US$${p.usd.toFixed(3)} (${p.basis}); US$${b.spent.toFixed(2)} of US$${b.cap.toFixed(2)} spent so far. Run it with --yes once that is fine.` };
-  }
-  const r = await falRun(model, input, {
-    out, base: dir, uploads: join(dir, 'uploads.json'), price: p, log: (m) => { if (!JSON_OUT) process.stderr.write(`${m}\n`); },
-    onAccepted: async (q) => { receipt(root, dir, { provider: 'fal', model, requestId: q.request_id, cost: p.usd, unit: 'usd', units: p.units, unitName: p.unit, basis: p.basis, artifact: rel(root, out) }); },
-  });
-  return { ok: true, command: 'gen', slug, files: r.files.map((f) => rel(root, f)), requestId: r.requestId, usd: p.usd, spent: readJson(join(dir, 'budget.json'), {}).spent, next: 'look at it before anything else; a second call only with a changed prompt, never a loop' };
-}
-
 /* ---------------------------------------------------------------- tile / fit / sheet */
 
 function tile() {
@@ -281,14 +210,12 @@ async function main() {
     return { ok: true, command: 'help', usage: head.replace(/^#!.*\n\/\*\*?/, '').replace(/^ \* ?/gm, '').trim() };
   }
   if (cmd === 'check') return check();
-  if (cmd === 'price') return price();
   if (cmd === 'tile') return tile();
   if (cmd === 'fit') return fit();
   const root = studioRoot();
   if (cmd === 'frame') return frame(root);
   if (cmd === 'cover') return cover(root);
   if (cmd === 'budget') return budget(root);
-  if (cmd === 'gen') return gen(root);
   if (cmd === 'sheet') return sheet(root);
   return { ok: false, command: cmd, why: `unknown command "${cmd}" (art.mjs help)` };
 }