@homie-rocks/studio 0.48.4 → 0.50.0

package/guides/art/scripts/art.mjs

@@ -0,0 +1,308 @@
+#!/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).
+ */
+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);
+const flags = new Map();
+const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith('--')) { const k = a.slice(2); const v = argv[i + 1]; if (v === undefined || v.startsWith('--')) flags.set(k, true); else { flags.set(k, v); i++; } } else pos.push(a);
+}
+const JSON_OUT = flags.has('json');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const rel = (root, f) => relative(root, f).split('\\').join('/');
+const ffmpeg = (args) => { const r = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }); if (r.status !== 0) throw new Error(`ffmpeg: ${String(r.stderr).trim().split('\n').pop()}`); return r; };
+const size = (file) => { const r = spawnSync('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height', '-of', 'csv=p=0', file], { encoding: 'utf8' }); const [w, h] = String(r.stdout).trim().split(',').map(Number); return { w, h }; };
+
+function studioRoot() {
+  const root = findStudio();
+  if (!root) throw new Error('not inside a Homie studio (no studio.json here or above). The studio-setup skill makes one.');
+  return root;
+}
+function artDir(root, slug) {
+  if (!SLUG.test(String(slug ?? ''))) throw new Error('name the art job with a slug: lowercase letters, digits and hyphens (e.g. "cover" or "skyline")');
+  const d = join(root, 'art', slug);
+  mkdirSync(d, { recursive: true });
+  return d;
+}
+function gameDir(root, game) {
+  const d = experienceDir(root, String(game ?? ''));
+  if (!game || !existsSync(experienceJson(d))) throw new Error('a game in this studio: games/<id>/game.json');
+  return d;
+}
+
+/** 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 };
+}
+
+/* ---------------------------------------------------------------- frame */
+
+async function frame(root) {
+  const game = pos[1];
+  const source = gameDir(root, game);
+  const url = String(flags.get('url') ?? '').replace(/\/+$/, '');
+  if (!/^https?:\/\//.test(url)) throw new Error('--url <the studio site: http://127.0.0.1:8787 from npm run dev, or the live site>');
+  const serverRules = isServerRules(source);
+  const view = flags.has('view') ? (flags.get('view') === 'play' ? 'play' : 'tv') : serverRules ? 'play' : 'tv';
+  const seconds = Math.max(4, Math.min(60, Number(flags.get('seconds') ?? 12)));
+  const dir = artDir(root, String(flags.get('slug') ?? 'frames'));
+  const puppeteer = loadPuppeteer(root); const exe = chromePath();
+  if (!puppeteer || !exe) throw new Error(!exe ? 'no Chrome found (set CHROME_PATH)' : 'puppeteer-core is missing (npm install in the studio)');
+  const browser = await puppeteer.launch({ executablePath: exe, headless: true, timeout: 150_000, args: [...GPU_FLAGS, '--mute-audio', '--window-size=1920,1080', '--hide-scrollbars', '--force-color-profile=srgb', '--no-first-run'] });
+  const shots = [];
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: 1920, height: 1080, deviceScaleFactor: 1 });
+    await page.setUserAgent(`${await browser.userAgent()} homie-art`);
+    await page.goto(`${url}/${game}/${view}`, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+    // The platform's own furniture never goes into art: the join card, the QR, the status chip, result cards.
+    await page.addStyleTag({ content: '.join,.chip,.card,[data-join],[data-chip],[data-results],[data-screen],[data-room-ui],[data-toast]{display:none!important}' }).catch(() => {});
+    await page.waitForSelector('iframe', { timeout: 30000 });
+    const gameFrame = page.frames().find(f => /\/__game\//.test(f.url()));
+    if (!gameFrame) throw new Error('the game frame never loaded');
+    if (serverRules) await gameFrame.waitForFunction(() => Boolean(window.__homieNet), { timeout: 30000 });
+    const before = await gameFrame.evaluate(() => window.__homieNet?.probe?.tick?.() ?? null);
+    await sleep(4000);
+    if (serverRules && view === 'tv') {
+      const after = await gameFrame.evaluate(() => window.__homieNet?.probe?.tick?.() ?? null);
+      if (!(after > before)) throw new Error('The server room is paused: a TV is not a participant. Use --view play, or keep a player in this same room, then capture again.');
+    }
+    for (let t = 0; t < seconds; t += 2) {
+      const png = await page.screenshot({ type: 'png', captureBeyondViewport: false });
+      const st = stats(decode(png, 480));
+      const f = join(dir, `frame-${String(shots.length + 1).padStart(2, '0')}.png`);
+      writeFileSync(f, png);
+      shots.push({ file: rel(root, f), ...st });
+      await sleep(2000);
+    }
+  } finally { await browser.close().catch(() => {}); }
+  const usable = shots.filter((s) => !s.black && !s.flat);
+  const best = (usable.length ? usable : shots).slice().sort((a, b) => b.edges - a.edges)[0];
+  return { ok: Boolean(usable.length), command: 'frame', view, frames: shots.map((s) => `${s.file}: detail ${(s.edges * 100).toFixed(1)}%, brightness ${s.mean}`), best: best?.file, why: usable.length ? undefined : 'every frame was black or one colour: is the game drawing?', next: `look at ${best?.file}; a cover from it: art.mjs cover ${game} --from ${best?.file}` };
+}
+
+/* ---------------------------------------------------------------- cover */
+
+function cover(root) {
+  const game = pos[1];
+  const gdir = gameDir(root, game);
+  const from = resolve(String(flags.get('from') ?? ''));
+  if (!existsSync(from)) throw new Error('--from <image>: a frame from `frame`, a painted image from `gen`, or the person\'s own art');
+  const g = readJson(experienceJson(gdir), {});
+  const pub = g.build?.mode === 'static' ? gdir : join(gdir, 'public');
+  mkdirSync(pub, { recursive: true });
+  const { w, h } = size(from);
+  if (!w || !h) throw new Error(`could not read ${from} as an image`);
+  // Crop to 16:9 around the focus (fractions; the middle by default), then 1600x900.
+  const [fx, fy] = String(flags.get('focus') ?? '0.5,0.5').split(',').map(Number);
+  const cw = Math.min(w, Math.round(h * 16 / 9)); const ch = Math.min(h, Math.round(w * 9 / 16));
+  const x = Math.max(0, Math.min(w - cw, Math.round(fx * w - cw / 2))); const y = Math.max(0, Math.min(h - ch, Math.round(fy * h - ch / 2)));
+  const out = join(pub, 'cover.jpg');
+  let q = 3;
+  for (;;) {
+    ffmpeg(['-i', from, '-vf', `crop=${cw}:${ch}:${x}:${y},scale=1600:900:flags=lanczos`, '-q:v', String(q), out]);
+    if (statSync(out).size <= 400 * 1024 || q >= 10) break;
+    q += 1;
+  }
+  g.cover = 'cover.jpg';
+  writeFileSync(experienceJson(gdir), `${JSON.stringify(g, null, 2)}\n`);
+  const st = stats(decode(out, 480));
+  const warn = [];
+  if (w < 1200) warn.push(`the source is ${w} px wide: upscaled covers look soft; capture or generate at 1600 px or more`);
+  if (st.mean < 35) warn.push(`dark (brightness ${st.mean} of 255): a card on a page reads as a black box`);
+  if (st.edges < 0.03) warn.push('little visible detail: a cover sells the game; a busier moment or a painted version reads better');
+  return { ok: true, command: 'cover', game, cover: rel(root, out), kb: Math.round(statSync(out).size / 1024), from: `${w}x${h}`, crop: `${cw}x${ch} at ${x},${y}`, gameJson: 'cover: "cover.jpg"', warnings: warn, look: 'open it: no QR code, no share panel, no debug text, not a waiting screen, and nothing the game does not contain' };
+}
+
+/* ---------------------------------------------------------------- money */
+
+function budget(root) {
+  const dir = artDir(root, pos[1]);
+  const cap = Number(flags.get('cap'));
+  if (!(cap > 0 && cap <= 1000)) throw new Error('--cap <US dollars the person agreed to>');
+  const b = setBudget(dir, { provider: 'fal', unit: 'usd', cap });
+  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() {
+  const file = resolve(String(pos[1] ?? ''));
+  if (!existsSync(file)) throw new Error('usage: tile <image>');
+  const img = decode(file, 512);
+  const { w, h, rgb } = img;
+  const px = (x, y, c) => rgb[(y * w + x) * 3 + c];
+  const colDiff = (a, b) => { let s = 0; for (let y = 0; y < h; y++) for (let c = 0; c < 3; c++) s += Math.abs(px(a, y, c) - px(b, y, c)); return s / (h * 3); };
+  const rowDiff = (a, b) => { let s = 0; for (let x = 0; x < w; x++) for (let c = 0; c < 3; c++) s += Math.abs(px(x, a, c) - px(x, b, c)); return s / (w * 3); };
+  // The wrap (last column against the first) against the texture's own neighbour steps inside it.
+  let inX = 0; let nX = 0; for (let x = 1; x < w; x += 7) { inX += colDiff(x - 1, x); nX++; }
+  let inY = 0; let nY = 0; for (let y = 1; y < h; y += 7) { inY += rowDiff(y - 1, y); nY++; }
+  const seamX = +(colDiff(w - 1, 0) / Math.max(0.5, inX / nX)).toFixed(2);
+  const seamY = +(rowDiff(h - 1, 0) / Math.max(0.5, inY / nY)).toFixed(2);
+  const preview = file.replace(/(\.[a-z0-9]+)$/i, '-tiled.png');
+  ffmpeg(['-i', file, '-filter_complex', '[0]scale=512:-2,split=4[a][b][c][d];[a][b]hstack[t];[c][d]hstack[u];[t][u]vstack', preview]);
+  const ok = seamX <= 2 && seamY <= 2;
+  return { ok: true, command: 'tile', file, seamX, seamY, tiles: ok, why: ok ? 'the edges meet like the inside does (2 or less)' : `a visible seam ${seamX > 2 ? 'left to right' : ''}${seamX > 2 && seamY > 2 ? ' and ' : ''}${seamY > 2 ? 'top to bottom' : ''}: image models are bad at tiling; mirror-blend the edges or ask for a texture and make it tile yourself`, preview };
+}
+
+function fit() {
+  const file = resolve(String(pos[1] ?? ''));
+  if (!existsSync(file)) throw new Error('usage: fit <image> --out <file.jpg|.webp|.png> [--width 1024] [--max-kb 300]');
+  let out = resolve(String(flags.get('out') ?? file.replace(/(\.[a-z0-9]+)$/i, '-fit.jpg')));
+  const encoders = spawnSync('ffmpeg', ['-hide_banner', '-encoders'], { encoding: 'utf8' }).stdout ?? '';
+  let note;
+  if (extname(out).toLowerCase() === '.webp' && !/libwebp/.test(encoders)) { out = out.replace(/\.webp$/i, '.jpg'); note = 'this ffmpeg has no WebP encoder, so it wrote a JPEG (brew install ffmpeg with libwebp, or keep JPEG: every browser reads it)'; }
+  const width = Math.max(16, Math.min(8192, Number(flags.get('width') ?? 1024)));
+  const maxKb = Number(flags.get('max-kb') ?? 300);
+  const ext = extname(out).toLowerCase();
+  mkdirSync(dirname(out), { recursive: true });
+  let q = ext === '.webp' ? 82 : 3;
+  for (let pass = 0; pass < 8; pass++) {
+    const enc = ext === '.webp' ? ['-c:v', 'libwebp', '-quality', String(q)] : ext === '.png' ? ['-compression_level', '9'] : ['-q:v', String(q)];
+    ffmpeg(['-i', file, '-vf', `scale=${width}:-2:flags=lanczos`, ...enc, out]);
+    if (statSync(out).size <= maxKb * 1024 || ext === '.png') break;
+    q = ext === '.webp' ? q - 10 : q + 2;
+  }
+  const kb = Math.round(statSync(out).size / 1024);
+  const { w, h } = size(out);
+  return { ok: kb <= maxKb || ext !== '.png', command: 'fit', out, size: `${w}x${h}`, kb, note, ...(kb > maxKb ? { why: `still ${kb} KB: a smaller width, or JPEG/WebP instead of PNG` } : {}), next: 'load it in the game, play it, and check the load time did not grow (the playtest\'s first row)' };
+}
+
+async function sheet(root) {
+  const dir = resolve(String(pos[1] ?? ''));
+  if (!existsSync(dir)) throw new Error('usage: sheet <folder of images>');
+  const files = readdirSync(dir).filter((f) => /\.(png|jpe?g|webp)$/i.test(f) && !f.startsWith('sheet')).sort();
+  if (!files.length) throw new Error('no images in that folder');
+  const cells = files.map((f) => {
+    const small = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-i', join(dir, f), '-vf', 'scale=480:-2', '-f', 'image2', '-c:v', 'mjpeg', '-q:v', '4', '-'], { maxBuffer: 32 * 1024 * 1024 }).stdout;
+    return `<figure><img src="data:image/jpeg;base64,${Buffer.from(small).toString('base64')}"><figcaption>${f.replace(/</g, '&lt;')}</figcaption></figure>`;
+  });
+  const cols = Math.min(4, files.length); const rowsN = Math.ceil(files.length / cols);
+  const html = `<!doctype html><meta charset="utf-8"><style>body{margin:0;background:#111;color:#ddd;font:14px system-ui,sans-serif}main{display:grid;grid-template-columns:repeat(${cols},480px);gap:12px;padding:12px}figure{margin:0}img{width:480px;height:270px;object-fit:contain;background:#000;display:block}figcaption{padding-top:4px}</style><main>${cells.join('')}</main>`;
+  const out = join(dir, 'sheet.png');
+  await htmlToPng(root, html, out, { width: cols * 492 + 12, height: rowsN * 306 + 12 });
+  return { ok: true, command: 'sheet', images: files.length, sheet: out };
+}
+
+/* ---------------------------------------------------------------- main */
+
+async function main() {
+  const cmd = pos[0];
+  if (!cmd || cmd === 'help' || flags.has('help')) {
+    const head = readFileSync(fileURLToPath(import.meta.url), 'utf8').split('*/')[0];
+    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)` };
+}
+
+const print = (o) => {
+  if (JSON_OUT) { process.stdout.write(`${JSON.stringify(o, null, 2)}\n`); return; }
+  if (o.ok === false && o.why) { process.stdout.write(`art: ${o.why}\n`); return; }
+  for (const [k, v] of Object.entries(o)) if (k !== 'ok' && k !== 'command' && v !== undefined) process.stdout.write(`${k}: ${Array.isArray(v) ? `\n  ${v.join('\n  ')}` : typeof v === 'object' ? JSON.stringify(v) : v}\n`);
+};
+
+try {
+  const r = await main();
+  if (r) { print(r); if (r.ok === false) process.exitCode = 1; }
+} catch (error) {
+  print({ ok: false, why: error instanceof Error ? error.message : String(error) });
+  process.exitCode = 1;
+}

package/guides/models/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: models
+description: Give a game real 3D models that fit together and run on a phone — free CC0 models from Homie's starter library (Kenney, KayKit, Poly Haven, ambientCG) copied in with their licence, the person's own files checked and made phone-sized, and generated props (a concept image in the game's locked style, then Tripo P1 image-to-3D) and generated rigged characters (an A-pose concept, then Meshy 7.1 with its auto-rig, the library's clips retargeted onto it) on the person's OWN fal account under a hard budget with a receipt per call — every asset recorded with its provenance and licence (RIGHTS.md, the credits page), checked against phone budgets, shown in a lineup at true scale, and loaded through one safe loader. Use when someone wants 3D models, props, characters, scenery or "free assets" for a game, asks where a model came from or whether it may be used, or says the models look like they are from different games.
+compatibility: Node 22. Generated props use Tripo's models, and generated characters Meshy's, on the creator's own fal account (a local FAL_KEY for this skill's script, or a job run through a signed-in fal connector and brought in with `models.mjs import`). fal's own MCP server (https://mcp.fal.ai/mcp-relay) reads schemas and prices.
+metadata:
+  providers: fal tripo
+---
+
+# Models for a game: free first, everything licensed, one look
+
+Read the `style` skill first: a game's models are made under its decisions (render style, palette, scale,
+budgets). Routes, cheapest coherent one first:
+
+1. **The engine** (free): procedural geometry, tinted from the palette. The house's best looks are procedural;
+   never replace one with generated meshes without the owner's ask.
+2. **The starter library** (free, CC0): `assets find`, then `assets add`.
+3. **The person's own files**: `assets add --file … --license …` (ask whose it is).
+4. **Generated** (paid, their own fal account, under a budget): a concept, then a mesh: props, and rigged characters
+   (below). A character's rig, clips and feel are the `animate` skill's.
+
+Commands run from inside the studio: `npx --no-install homie-studio assets …` (free) and this skill's script for
+the paid route: `node "${CLAUDE_PLUGIN_ROOT}/skills/models/scripts/models.mjs" <command>` (in an app with Homie's
+tools: `assets_find`, `asset_add`, `asset_make`, `asset_check`, `asset_lineup`, `asset_rights`).
+
+## The starter library (free)
+
+```sh
+npx --no-install homie-studio assets find "fox"                    # CC0 items, phone-sized, with triangles and size
+npx --no-install homie-studio assets find "pine tree" --family kenney
+npx --no-install homie-studio assets add <id> kenney-cube-pets/animal-fox --height 0.7 --card "Characters/Fox"
+```
+
+One library family per game (`cast.family`): mixing Kenney with KayKit shows. An added item is COPIED into
+`games/<id>/public/models/` (never loaded from homie.rocks at runtime), recorded in `assets/manifest.json` with its
+pack, origin and SHA-256, and its pack is credited on the landing's credits page (kindly: CC0 needs no credit).
+`HOMIE_LIBRARY` points at another copy of the library (a folder or an address).
+
+## The person's own files
+
+```sh
+npx --no-install homie-studio assets add <id> --file /path/to/lantern.glb --license own --as lantern --height 0.6
+```
+
+Ask whose it is and under what licence: `own`, `cc0`, `cc-by-4.0` (with `--attribution "<who, where>"`),
+`eula:<store>`, `market:<listing>`, `other` (with `--notes`). The file is refused before anything reads it when it
+loads anything from an address (an external URI), declares a buffer over the import cap, or is over 64 MB; a
+.gltf may bring its .bin and pictures from its own folder only. Then it is made phone-sized (its tier's
+triangles and picture size, the pivot at the bottom centre, its height in metres, meshopt geometry, WebP
+pictures); the raw file stays in `art/<slug>/raw/` (git-ignored; the studio's R2 with `media move` once it has
+storage), never shipped and never committed. FBX, OBJ and .blend: export a .glb first (Blender: File > Export >
+glTF 2.0, binary).
+
+## Generated props (paid): price, budget, look, then the mesh
+
+```sh
+node <models.mjs> check                                  # the LOCAL fal key (a free check) and the registry
+node <models.mjs> quote <id> --count 3                   # concept + mesh, priced live (about US$0.54 a prop)
+node <models.mjs> budget <id> --cap 3                    # the cap the person agreed to, for this game's models
+node <models.mjs> prop <id> lantern --card "Items/Ember Lantern" --what "an iron lantern with a warm ember inside" --height 0.6 --dry-run
+node <models.mjs> prop <id> lantern --card "Items/Ember Lantern" --what "…" --height 0.6 --yes     # the concept only
+#   LOOK at art/lantern/concept.*: the thing, whole, in the game's style, on a plain background?
+node <models.mjs> prop <id> lantern --mesh --yes          # Tripo P1, textured, face_limit 1500; then optimised and recorded
+npx --no-install homie-studio assets lineup <id>         # true scale, silhouettes, palette drift
+```
+
+- Tell the person the price first and agree a cap; `prop` refuses with no budget, refuses past the cap, and asks
+  again without `--yes`. The receipt is written the moment fal accepts the job (`art/receipts.jsonl`, the
+  game's `art/<id>-models/budget.json`); running the same step again resumes it and never pays twice.
+- The concept starts from the derived style prompt (`homie-studio style prompt <id>`) with the golden images as
+  references, on a plain background with even light (baked light is the top quality problem of image-to-3D).
+- **Two sign-ins, one set of books.** `FAL_KEY` in the shell is what this script pays with. A fal connector (fal's
+  MCP server signed in from the app) is a separate sign-in the script cannot see: `check` reports the local key only,
+  and "no local FAL_KEY" does not mean the connector is signed out. With a key, generate here. With only a connector,
+  generate there (ask the price first and hold it to the same cap), save the job's receipt as JSON the moment it is
+  accepted (`{ "requestId", "endpoint", "cost" }`) and bring the finished file in:
+  `node <models.mjs> import <id> lantern --receipt art/lantern/mesh-job.json --file <the .glb> [--concept <image> --concept-receipt <job.json>] [--kind character] [--height 0.6]`.
+  It is refused with no budget or past the cap, writes one receipt line a request id (never twice), keeps the raw file
+  in `art/<asset>/raw/` and records the asset with every step, exactly as a job made here. Never copy a key out of
+  the connector, and never bring a connector's file in with a bare `assets add`: the spend and the provenance would
+  be missing.
+- **Never a loop.** Look at the concept before the mesh, and at the model in the lineup before the next one. A
+  bad concept: change the words and `--concept-again` once. Spend the riskiest prop first.
+- `references/models.json` is the dated registry of endpoints, prices and schemas. Endpoints retire and reprice
+  monthly: `node <models.mjs> registry` reads every price again for free; update the registry (`--write`) when one
+  moved, and never hard-code an endpoint anywhere else. fal's own MCP server (`get_model_schema`, `get_pricing`,
+  `search_models` for a newer Tripo version; the `art` skill says how to connect it) reads the same facts. A paid
+  run goes through `models.mjs` when there is a local key; a run made through the connector instead is only finished
+  when `models.mjs import` has recorded it (above).
+- Tripo's models run **on fal** here (`tripo3d/...` endpoints): one account, prices read live, the receipts above.
+  Tripo's own CLI and MCP server (`tripo-cli`, `tripo mcp`) bill a separate Tripo account in Tripo credits, outside
+  this skill's budget and receipts, and a free Tripo plan makes its outputs public under CC BY 4.0
+  (`references/RIGHTS.md`): keep a game's models on the fal route. The Homie mod (Claude Code) and Homie's hooks (Codex)
+  hold a `tripo` generating command or a Tripo MCP tool as a call whose cost cannot be read first.
+- A painted mood image for the style board: `node <models.mjs> mood <id> b --yes` (about US$0.035; a target).
+
+## Generated characters (paid): an A-pose concept, then a rigged mesh
+
+Library characters first (`assets find "knight" --kind character`: KayKit's adventurers and skeletons, Kenney's mini
+and blocky characters, all CC0 and animated). For one the library cannot cover:
+
+```sh
+node <models.mjs> character <id> ranger --card "Players/Ranger" --what "a forest ranger: green hooded cloak, leather tunic, a bow on the back" --height 1.45 --like kaykit-adventurers/rogue --dry-run
+node <models.mjs> character <id> ranger --card "Players/Ranger" --what "…" --height 1.45 --like kaykit-adventurers/rogue --yes   # the concept only
+#   LOOK at art/ranger/concept.*: one character, whole, in an A-pose, in the game's style, on a plain background?
+node <models.mjs> character <id> ranger --mesh --yes     # Meshy 7.1 + auto-rig, about US$1.40; then free: optimised, rig mapped, clips retargeted
+npx --no-install homie-studio anim preview <id> --asset ranger   # LOOK at the preview sheet
+```
+
+`--like` takes a library character's own thumbnail as the style reference (so a generated hero stands beside the
+library's in one look); golden images, when the game has them, come first. The concept is a full body in an A-pose,
+front view, plain background (what auto-rigging needs). Humanoids with clear limbs only. The quote reads fal's pricing
+API and the model page's add-ons (textures, rigging) and takes the higher. The raw rigged file stays in
+`art/<asset>/raw/`; the shipped character is phone-sized with its skeleton mapped to the standard and the library's
+CC0 clips (idle, run, jump, attack, hit, die, ...) retargeted onto it, recorded with both receipts.
+
+## Check, lineup, rights
+
+```sh
+npx --no-install homie-studio assets check <id>    # phone budgets, the glTF-Validator, licences, staleness, big files
+npx --no-install homie-studio assets use <id> <asset> unused   # a file the game no longer draws (or cast, prop, environment)
+npx --no-install homie-studio assets add <id> --file <model.glb> --license own --lo 0.2   # also <asset>_lo.glb: the same prop at a fifth of its triangles, for the far band (LodProps)
+npx --no-install homie-studio assets lineup <id>   # pictures in .studio/art/<id>/; look at them
+npx --no-install homie-studio assets rights <id>   # games/<id>/assets/RIGHTS.md and the credits
+npx --no-install homie-studio assets redo <id> <asset>   # made again from its kept raw file, free
+```
+
+`assets redo` runs only the free steps again (today's budgets and render style, from `art/<slug>/raw/`). A model
+drawn black in the game is metal with nothing to reflect: every style but `pbr` makes models non-metal, and a redo
+applies it to one made before. A palette or shape change needs a new concept and mesh (paid), not a redo.
+
+Phone budgets (per asset): a prop 1,500 triangles and 512 px pictures, a hero 8,000 and 1,024 px, one material;
+the scene: about 100 draw calls, 150,000 triangles, 48 MB of picture memory, 5 MB of shipped payload. `assets check`
+holds the game to them, and what it adds up is an **inventory estimate**: the recorded files' own numbers times their
+`placements`. It never ran the game, so procedural geometry, repeated instances, effects and shadow passes are not in
+it, and "shipped payload" is every built file gzipped, not what a browser fetched before the first round. Say
+"inventory estimate" when you report it; the `playtest` and `perf` skills measure the running game and are the real
+gate on a phone.
+
+- A game that needs heavier models says so once, in game.json: `"assets": { "budgets": { "triangles": 4000, "bytes": 600000 } }`
+  (the loader's warnings and the check both read it; hard caps still hold).
+- Standalone textures and skies are measured too (size, hash, decode, mipmapped memory once a picture). Record every
+  picture the game loads as a texture (`kind: "texture"` or `"sky"`, with its licence and SHA-256): the check lists
+  shipped pictures that have no record and leaves them out of the sum.
+- A model's normal and roughness maps count unless the manifest declares the game draws base colour only
+  (`"inGame": { "maps": "base" }` on a record or at the top of the manifest). Declare it only when the game really
+  calls `stylize()` with a non-PBR material model on those models; never to make a number pass.
+- The lineup is three pictures: the inventory (everything recorded), the cast (what is in play) and the environment.
+  Mark a file the game no longer draws `unused`, and give a reviewer the cast and environment lineups, not the folder.
+
+After the lineup, have a FRESH reviewer (the `playtest` skill's blind review: a new agent that never saw your
+reasoning) look at the style board, the golden images and the lineup pictures and score "does every model look
+like one game?" from 1 to 10, naming outliers; record it: `assets review <id> --score <n> --outliers a,b`.
+Under 7, or any outlier, those assets need another look.
+
+## Loading them in the game
+
+Every model loads through `@homie-rocks/studio/assets`:
+
+```ts
+import { createModels } from '@homie-rocks/studio/assets';
+const models = createModels();
+const fox = await models.instance('./models/fox.glb').catch(() => models.placeholder({ x: 0.5, y: 0.7, z: 0.8 }));
+```
+
+It refuses an unsafe or oversized file (an external URI, a buffer over the cap, an extension three.js cannot
+read) before parsing it, decodes meshopt geometry, clones skinned models properly, and warns in development
+when a model is over its budget. Draw each loaded model the way the decisions say, once, before copying it:
+`stylize((await models.load(url)).scene, style)` with the game's `style.json` (its material model and ink outline,
+as the style board drew them). The `gem-rush-3d` starter shows the whole pattern.
+
+## Licences, plainly
+
+- `references/RIGHTS.md` keeps what the providers' terms say, with read dates. Read the live pages again before
+  anything commercial is published (`registry` re-reads prices; terms you read by hand).
+- The assets whose licence lets the file itself be handed on are CC0, CC BY with credit, the studio's own, and
+  generated ones: only those may be in a part the studio shares. With anything else the game may serve the file
+  to its players, and the studio's repository must stay private while it holds the raw file. `publish` refuses a game with an asset that
+  has no licence record.
+- Never fetch from Poly Pizza or ShareTextures by script, never use Quaternius, Mixamo, Synty, Fab, Unity Asset
+  Store or TurboSquid files in a public game's repository, never use a model or dataset under non-commercial
+  terms.
+
+## Never
+
+- Never spend without a budget, past it, or without a receipt; never run paid generation in a loop; never print
+  or store a key.
+- Never ship a raw provider file, never commit one, never ship an asset with no licence record.
+- Never replace a model the person made without asking.
+
+### Existing provider credentials
+
+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.

package/guides/models/references/RIGHTS.md

@@ -0,0 +1,46 @@
+# Rights for models and generated art
+
+What the providers' own terms say about the files this skill makes or brings in, with the date each page was
+read. Terms change: before anything commercial is published, read the live page again, and update the date here
+and in `@homie-rocks/studio`'s `lib/asset-manifest.mjs` (`PROVIDER_TERMS`), which writes every game's RIGHTS.md.
+
+## Generated on the person's own account
+
+- **fal** (https://fal.ai/terms, read 2026-10-02, "Last Updated: September 8, 2026"): "Customer owns and retains
+  all right, title, and interest in and to the Customer Input." There is no matching clause assigning the
+  Output to the customer; fal "does not represent, warrant, or covenant that any Output Content will be original,
+  will not infringe rights of any third party … or otherwise entitle Company to any intellectual property rights
+  in any Output Content". Third-party model outputs may not be used to train models that compete with them. The
+  endpoints in `models.json` carry fal's "Commercial use" label.
+- **Tripo** through fal (developer terms, https://developers.tripo3d.ai/en/terms, read 2026-10-02, last updated
+  2025-07-11): "you may use Outputs for lawful commercial or non-commercial purposes". Calls through fal are paid
+  calls. Tripo's FREE plan makes outputs public under CC BY 4.0 (credit Tripo); this skill never uses a free plan.
+- **Copyright in purely AI-made files** may be thin, so a licence on them may not bind whoever copies those
+  files. RIGHTS.md says so plainly and never claims more than the terms above.
+
+## The starter library (CC0 only)
+
+- **Kenney** (https://kenney.nl/support; each pack's License.txt): "Creative Commons Zero, CC0": personal,
+  educational and commercial use; credit "is not a requirement".
+- **KayKit** (each repository's licence file): CC0 1.0, no attribution required (a request not to resell
+  unmodified copies is a request, not a term; Homie never sells them).
+- **Poly Haven** (https://polyhaven.com/license): CC0; redistribution allowed; no credit needed for downloaded or
+  mirrored files (only the live API inside a product needs a visible credit, and Homie never proxies it).
+- **ambientCG** (https://docs.ambientcg.com/license/): CC0 1.0; "You can include the raw files in your project,
+  for example a video game".
+
+Never in the library or a public game's repository: Quaternius (its site licence of 2026-08-28 forbids
+redistribution as an asset pack or template; reference only until written permission), Mixamo, Synty, Fab,
+Unity Asset Store, TurboSquid (forbids three.js `.glb` outright), Sketchfab Standard, three.js example models,
+anything trained on or made from non-commercial data (AMASS, SMPL, GVHMR, the Bandai Namco dataset).
+
+## What may be handed on
+
+A game serves its files to its players and to nobody else. A file leaves a studio only inside a part the studio
+chose to share (the `parts` skill), and only when its licence lets the file itself be handed on.
+
+| Licence | In a shared part |
+| --- | --- |
+| CC0, CC BY (credit kept), the studio's own, generated | yes |
+| Quaternius (QAL) | no |
+| Mixamo, a store EULA, a bought listing, "other" | no |