@homie-rocks/studio 0.20.0 → 0.22.0

package/lib/scaffold.mjs

@@ -106,6 +106,7 @@ directory lists its games; homie.rocks does not host them.
 | --- | --- |
 | \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`; and, when it has them, \`tunables.json\` (the numbers that shape how it feels: the Game Lab's sliders, kept values written back) and \`lab.json\` (the Game Lab's takes). |
 | \`music/\`, \`videos/\` | Songs, scores, loops; trailers, music videos, cutscenes. \`manifest.json\` lists each one (\`node_modules/@homie-rocks/studio/media/MEDIA.md\`); a published entry gets a page at \`/music/<slug>/\` or \`/videos/<slug>/\`. Without storage the site serves each file itself (up to 25 MiB). Once the studio has storage (see below), its big media (over 1 MiB, or left out of git) lives in its own R2: every deploy uploads it, checks it by SHA-256 and serves it from R2 at the same address. Large files never go into git. The Homie plugin's \`music\` and \`video\` skills make them. |
+| \`games/<id>/assets/\` | Every model and texture a game ships, with where it came from and its licence (\`manifest.json\`), and \`RIGHTS.md\` in plain words; \`games/<id>/codex/decisions.json\` (private, like the codex) is its look as decisions, and \`style.json\` the palette, fonts, light and camera the game draws with. \`art/<slug>/\` holds art jobs (concepts, receipts; \`raw/\` is git-ignored). |
 | \`posts/\` | The studio's news and drops: one markdown file each (\`posts/2026-09-30-we-are-live.md\`: \`title:\`, \`date:\`, \`summary:\`, and \`game:\` / \`song:\` / \`video:\` to link one). They are the site's Posts, with Atom and JSON feeds. |
 | \`site/\` | The studio's site: its look (\`theme.json\`), and anything of its own that wins over the generated pages (\`site/README.md\`); the Worker (\`src/worker.mjs\`) and its D1 migrations. |
 | \`wrangler.jsonc\` | The Worker's Cloudflare config (the Worker, D1, the Table and Lobby Durable Objects, and \`previews\` for branch Previews), at the root, where Cloudflare's Workers Builds reads it. A studio made before 0.10.0 keeps it in \`site/\` and deploys from a computer; every command finds either. |
@@ -264,6 +265,26 @@ studio's pinned copy, never a registry lookup of the bare name.
   Cloudflare, Chrome, ffmpeg, GitHub, ElevenLabs, fal), what each unlocks, and the exact fix. Optional ones never
   block anything.
 
+## Art direction and models
+
+- **A game's look is a set of decisions** (\`games/<id>/codex/decisions.json\`, drawn in the codex's Art direction
+  tab): render style, palette, shape, proportions, materials, light, camera, fonts, effects; the cast, its library
+  family, scale and phone budgets. \`npx --no-install homie-studio style init <id> --prompt "<the person's words>"\`
+  picks every one automatically with a why. The person can steer one ("warmer"), lock one, or explore three
+  directions drawn by the game engine itself (\`style board <id>\`, free). The first asset built on a decision pins
+  it; a locked one changes only with the person's yes after \`style blast\` shows what goes stale and what remaking
+  it would cost. Nothing is ever remade by itself. The Homie plugin's \`style\` skill has the rest.
+- **Models come free first**: the engine, then Homie's CC0 starter library (\`assets find "<words>"\`, then
+  \`assets add <id> <item>\`, copied in, never hot-linked), then the person's own files (\`assets add <id> --file …
+  --license …\`), then generated props on the person's own fal account under a budget with receipts (the plugin's
+  \`models\` skill). Every model is checked (no external URIs, no oversized files), made phone-sized and recorded
+  with its licence; \`RIGHTS.md\` and the credits page follow. \`assets check <id>\` holds a game to the phone
+  budgets; \`assets lineup <id>\` shows everything at true scale. A three.js game loads models through
+  \`@homie-rocks/studio/assets\` (\`createModels\`); \`game new <id> --from gem-rush-3d\` starts one.
+- **Licences**: a public game ships only assets whose licence allows it (CC0, CC BY with credit, the studio's own,
+  generated); \`publish\` refuses an asset with no licence record. A remix gets each redistributable model,
+  checked by SHA-256, and a grey placeholder for the rest.
+
 ## Running live games (the back office)
 
 - The owner runs the studio's live games from \`/_studio/office\` (\`npx --no-install homie-studio office link\` gives
@@ -279,7 +300,7 @@ studio's pinned copy, never a registry lookup of the bare name.
 - The owner is recognised in their own games: signed in, their play page has a small Owner button (tap a player:
   Mute, Kick; Announce). Nobody else's page has it.
 - **From the AI:** \`npx --no-install homie-studio office\` lists who is playing now; \`office announce "<text>"\` and
-  \`office invite <id>\` happen at once; \`office kick\`, \`office close\` and \`office launch\` only ASK, and print a
+  \`office invite <id>\` happen at once; \`office kick\`, \`office mute\`, \`office close\` and \`office launch\` only ASK, and print a
   one-time link that opens the ask in the owner's own browser, where one tap does it. An ask is not done until the
   owner tapped. \`office key\` gives a key for the Homie MCP's owner tools (\`studio_office\`, \`room_announce\`,
   \`room_kick\`, \`room_close\`, \`game_launch_state\`), which ask the same way; never paste a key anywhere else.
@@ -337,6 +358,11 @@ chat's card follows the work from then on) and, for a studio still being set up,
   studio.json as \`cloudflare.domain\`.
 - A game's room size is its netplay manifest's \`maxPlayers\` (game.json \`netplay\`, or netplay.json), up to 32.
 - Nothing in this studio needs \`~/.homie\` or a Homie box.
+- Optional in studio.json: \`"protect"\` (globs of files the owner wants to look at before any change, such as
+  \`"games/*/game.json"\`) and \`"budget"\` (\`{ "usd": <n>, "credits": <n> }\`: the most the studio's media jobs spend
+  in all). In Claude Code, the Homie plugin's mod holds an edit to a protected file, a deploy, and a paid call past
+  the budget until the person says Proceed, and takes keys out of command output. When it refuses a call, say what
+  you meant to do and why; do not retry it unless the person asks.
 
 ## Beta
 
@@ -480,6 +506,11 @@ music/**/*.flac
 videos/**/*.mp4
 videos/**/*.mov
 videos/**/*.webm
+# 3D: raw provider output, high-poly sources and Blender files stay on this computer (or the studio's R2): never shipped, never committed. The phone-sized model in games/<id>/public/models/ is committed.
+art/**/raw/
+*.blend
+*.blend1
+*.fbx
 `;
 
 /** Every file a new studio gets, relative to its folder. */

package/lib/site.mjs

@@ -417,7 +417,12 @@ export function landingOf(g, out, { videos = [], songs = [], log = () => {} } =
 
   const words = L.players && typeof L.players === 'object' ? { one: str(L.players.one, 24), many: str(L.players.many, 24) } : null;
   // The landing's own colours (landing.theme): only colours, and the ink on its own accent worked out like the studio's.
-  const theme = L.theme && typeof L.theme === 'object' ? Object.fromEntries(['accent', 'glow', 'bg', 'fg'].filter((k) => COLOR.test(String(L.theme[k] ?? ''))).map((k) => [k, L.theme[k]])) : null;
+  // Else the game's own palette (games/<id>/style.json, its art-direction decisions): one look from the game to its page.
+  const style = !L.theme ? readJson(join(g.dir, 'style.json'))?.palette : null;
+  // Its accents only: the page keeps the studio's light or dark scheme, so its text always reads.
+  const fromStyle = style && typeof style === 'object' ? { accent: style.accent, glow: style.accent2 } : null;
+  const raw = L.theme && typeof L.theme === 'object' ? L.theme : fromStyle;
+  const theme = raw ? Object.fromEntries(['accent', 'glow', 'bg', 'fg'].filter((k) => COLOR.test(String(raw[k] ?? ''))).map((k) => [k, raw[k]])) : null;
   if (theme?.accent) { const l = luminance(theme.accent); if (l !== null) theme.accentInk = l > 0.4 ? '#0b0b10' : '#ffffff'; }
   // landing.scheme: "light" for a white or cream game (its hero is tinted light and its words dark), "dark" for a
   // dark game in a light studio. Anything else follows the studio's look.

package/lib/studio.mjs

@@ -3,7 +3,7 @@
  * current directory, and its games.
  */
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { httpsPage, licenseOf, pageOfSource, remixAllowed, remixCredit, remixRow } from '../worker/license.mjs';
 
@@ -115,17 +115,24 @@ function renameTakeSaves(dir, from, id) {
   if (next !== text) writeFileSync(file, next);
 }
 
-/** `homie-studio game new <id> --from <starter> --name "<Name>"`: a starter copied in as this studio's own game. */
-export function newGame(root, id, { from = 'gem-rush', name } = {}) {
+/**
+ * `homie-studio game new <id> --from <starter> --name "<Name>"`: a starter copied in as this studio's own game. A starter
+ * whose game.json says `"assets": "library"` gets its models from the starter library here (fetchStarterModels).
+ */
+export async function newGame(root, id, { from = 'gem-rush', name } = {}) {
   if (!GAME_ID.test(String(id ?? '')) || RESERVED_IDS.has(id)) throw new Error(`a game id is lowercase letters, digits and hyphens, up to 40, and not one of ${[...RESERVED_IDS].join(', ')} (got ${JSON.stringify(id)})`);
   const src = join(PACKAGE_ROOT, 'starters', from);
   if (!existsSync(join(src, 'game.json'))) throw new Error(`no starter "${from}"; starters: ${starters().map((s) => s.id).join(', ')}`);
   const dest = join(root, 'games', id);
   if (existsSync(join(dest, 'game.json'))) throw new Error(`games/${id} already exists; pick another id or change that game`);
-  // A planned game (its folder holds the Game Codex, maybe art, and no game.json yet): the starter goes in around
-  // what is there, and nothing of the plan is overwritten.
-  if (existsSync(dest) && readdirSync(dest).some((f) => existsSync(join(src, f)))) throw new Error(`games/${id} holds files of its own that a starter would overwrite; pick another id`);
-  cpSync(src, dest, { recursive: true });
+  // A planned game (its folder holds the Game Codex, maybe its art direction and models, and no game.json yet): the
+  // starter goes in around what is there, and nothing of the plan is overwritten. Its style.json (from its own
+  // decisions) and credits.json stay; the starter's models join its assets/manifest.json beside the game's own.
+  const ADOPT = ['style.json', 'credits.json', 'assets'];
+  const planned = existsSync(dest) ? readdirSync(dest).filter((f) => existsSync(join(src, f))) : [];
+  const clash = planned.filter((f) => !ADOPT.includes(f));
+  if (clash.length) throw new Error(`games/${id} holds files of its own that a starter would overwrite (${clash.join(', ')}); pick another id`);
+  cpSync(src, dest, { recursive: true, filter: (from) => !planned.some((f) => from === join(src, f) || from.startsWith(join(src, f) + sep)) });
   const meta = JSON.parse(readFileSync(join(dest, 'game.json'), 'utf8'));
   meta.id = id;
   if (name) meta.name = String(name).slice(0, 60);
@@ -136,7 +143,113 @@ export function newGame(root, id, { from = 'gem-rush', name } = {}) {
   renameTakeSaves(dest, from, id);
   const html = join(dest, 'index.html');
   if (name && existsSync(html)) writeFileSync(html, readFileSync(html, 'utf8').replace(/<title>[^<]*<\/title>/, `<title>${String(name).replace(/[<&]/g, '')}</title>`));
-  return { ok: true, command: 'game new', id, from, dir: dest, files: readdirSync(dest, { recursive: true }).map(String) };
+  const merged = planned.includes('assets') && existsSync(join(src, 'assets', 'manifest.json')) ? await adoptStarterAssets(root, id, src) : null;
+  const needs = addNeeds(root, meta.needs);
+  const models = meta.assets === 'library' ? await fetchStarterModels(dest, merged) : null;
+  // A starter with models carries their rights: assets/RIGHTS.md and the credits, written again for this game.
+  if (existsSync(join(dest, 'assets', 'manifest.json'))) {
+    const { readManifest, syncCredits, writeRights } = await import('./asset-manifest.mjs');
+    const manifest = readManifest(root, id);
+    writeRights(root, id, manifest);
+    syncCredits(root, id, manifest);
+  }
+  return { ok: true, command: 'game new', id, from, dir: dest, files: readdirSync(dest, { recursive: true }).map(String), ...needs, ...(models ? { models } : {}) };
+}
+
+/**
+ * A planned game that already has models: the starter's entries join its assets/manifest.json (an id the game
+ * already uses keeps the game's own). The game's code draws them under the game's current decisions (it reads
+ * style.json), so each adopted entry is recorded as made under those revisions, not the starter's. Returns the
+ * adopted ids (the only ones fetched).
+ */
+async function adoptStarterAssets(root, id, src) {
+  const { readManifest, writeManifest } = await import('./asset-manifest.mjs');
+  const { readDecisions, revisionsFor, setDecision } = await import('./decisions.mjs');
+  const mine = readManifest(root, id);
+  const theirs = JSON.parse(readFileSync(join(src, 'assets', 'manifest.json'), 'utf8'));
+  // The starter is dressed from one library family: an automatic pick follows it (one family a game); one the person
+  // chose stays, and the lineup flags the starter's models until they are swapped.
+  const family = (theirs.assets ?? []).map((a) => String(a.from?.pack ?? '').split('-')[0]).find(Boolean);
+  const before = readDecisions(root, id)?.decisions?.['cast.family'];
+  if (family && before && before.value !== family && before.state === 'auto') {
+    setDecision(root, id, 'cast.family', family, { by: 'ai', why: `the starter's models are ${family}; one family a game, so every piece fits` });
+  }
+  const doc = readDecisions(root, id);
+  const adopted = [];
+  for (const a of theirs.assets ?? []) {
+    if (mine.assets.some((x) => x.id === a.id)) continue;
+    if (doc && a.made?.under) a.made.under = revisionsFor(doc, Object.keys(a.made.under));
+    mine.assets.push(a);
+    adopted.push(a.id);
+  }
+  writeManifest(root, id, mine);
+  return adopted;
+}
+
+/**
+ * A STARTER'S MODELS COME FROM THE STARTER LIBRARY: the repository keeps no binaries, so such a starter ships only its
+ * assets/manifest.json, each model a library item (`from.item`) and the file it goes to. Each is fetched from the
+ * library (HOMIE_LIBRARY: a folder or an address; homie.rocks by default), checked by the index's SHA-256 and the GLB
+ * safety rules (lib/library.mjs fetchItemFile), and written there; the manifest keeps the SHA-256 of what was written.
+ * When the library cannot be reached the models stay out, `why` says so, and the game draws its stand-ins until they
+ * come (`homie-studio assets add <game> <item> --as <asset>`). Returns { fetched, missing: [{ asset, item, why }], from }.
+ */
+async function fetchStarterModels(dest, only = null) {
+  const file = join(dest, 'assets', 'manifest.json');
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+  const wanted = (manifest.assets ?? []).filter((a) => (!only || only.includes(a.id)) && a.route === 'library' && a.from?.item && (a.files ?? []).some((f) => f.role === 'model' && /^public\/models\/[a-z0-9][a-z0-9-]{0,47}\.glb$/.test(String(f.path))));
+  if (!wanted.length) return null;
+  const { fetchItemFile, libraryBase, loadIndex } = await import('./library.mjs');
+  const lib = libraryBase();
+  let index;
+  try { index = (await loadIndex({ lib })).index; } catch (error) {
+    return { fetched: 0, missing: wanted.map((a) => ({ asset: a.id, item: a.from.item, why: 'no library' })), why: error.message, from: lib.base };
+  }
+  const missing = [];
+  let fetched = 0;
+  for (const a of wanted) {
+    const item = index.items.find((x) => x.id === a.from.item);
+    const f = a.files.find((x) => x.role === 'model');
+    if (!item) { missing.push({ asset: a.id, item: a.from.item, why: `the library has no ${a.from.item}` }); continue; }
+    try {
+      const { bytes, sha256 } = await fetchItemFile(lib, item);
+      mkdirSync(dirname(join(dest, f.path)), { recursive: true });
+      writeFileSync(join(dest, f.path), bytes);
+      Object.assign(f, { bytes: bytes.byteLength, sha256 });
+      a.from.sha256 = sha256;
+      fetched += 1;
+    } catch (error) { missing.push({ asset: a.id, item: a.from.item, why: error.message }); }
+  }
+  writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+  return { fetched, missing, from: lib.base };
+}
+
+/**
+ * WHAT A STARTER NEEDS FROM NPM. A starter's game.json may say `"needs": { "three": "0.185.1" }`: libraries its code
+ * imports that a studio does not have yet. Each one the studio's package.json lacks (in dependencies or
+ * devDependencies) goes into devDependencies at that exact version, so the game bundles one copy of it (a second
+ * three.js beside the one @homie-rocks/studio/assets imports would be two engines). A version the studio already
+ * pins is left as it is and named in `needsHeld`. `needs` stays in the game's game.json: it is what the game was
+ * written against. Returns { needs, needsAdded, needsHeld, installNeeded }.
+ */
+export function addNeeds(root, needs) {
+  const want = needs && typeof needs === 'object' && !Array.isArray(needs) ? Object.entries(needs).filter(([n, v]) => /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]{0,213}$/.test(n) && /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(String(v))) : [];
+  if (!want.length) return {};
+  const file = join(root, 'package.json');
+  const pkg = JSON.parse(readFileSync(file, 'utf8'));
+  const added = []; const held = [];
+  for (const [n, v] of want) {
+    const have = pkg.dependencies?.[n] ?? pkg.devDependencies?.[n];
+    if (have) { if (have !== v) held.push({ name: n, want: v, have }); continue; }
+    pkg.devDependencies = { ...(pkg.devDependencies ?? {}), [n]: String(v) };
+    added.push({ name: n, version: String(v) });
+  }
+  if (added.length) {
+    pkg.devDependencies = Object.fromEntries(Object.entries(pkg.devDependencies).sort(([a], [b]) => a.localeCompare(b)));
+    writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+  return { needs: Object.fromEntries(want), needsAdded: added, needsHeld: held, installNeeded: added.length > 0 };
 }
 
 /**
@@ -188,5 +301,19 @@ export async function remixGame(root, source, id, { name } = {}) {
   const main = join(dest, meta.entry ?? 'src/main.ts');
   if (existsSync(main) && from) writeFileSync(main, readFileSync(main, 'utf8').replace(new RegExp(`game: '${from}'`, 'g'), `game: '${id}'`));
   if (from) renameTakeSaves(dest, from, id);
-  return { ok: true, command: 'game remix', id, from: String(url), credit: meta.remixOf.credit, page: meta.remixOf.page, license, files: wrote };
+  // Its models and pictures (0.22.0): fetched from the original site and checked by SHA-256 where their licence lets a
+  // remix carry them; a grey placeholder of the same size where it does not (lib/remix-assets.mjs).
+  let assets = null;
+  if (existsSync(join(dest, 'assets', 'manifest.json'))) {
+    const { fetchRemixAssets } = await import('./remix-assets.mjs');
+    assets = await fetchRemixAssets(root, id, url, { credit: { studio: credit.studio ?? null, game: credit.game ?? meta.name ?? from } });
+  }
+  // What its code imports beyond the toolkit (a 3D game: three.js). A remix source is someone else's text, so only the
+  // libraries the toolkit's own starters use are added; anything else is named for the person to decide.
+  const asked = meta.needs && typeof meta.needs === 'object' && !Array.isArray(meta.needs) ? meta.needs : {};
+  const refusedNeeds = Object.keys(asked).filter((n) => !REMIX_NEEDS.has(n));
+  const needs = addNeeds(root, Object.fromEntries(Object.entries(asked).filter(([n]) => REMIX_NEEDS.has(n))));
+  return { ok: true, command: 'game remix', id, from: String(url), credit: meta.remixOf.credit, page: meta.remixOf.page, license, files: wrote, ...(assets ? { assets } : {}), ...needs, ...(refusedNeeds.length ? { needsNotAdded: refusedNeeds } : {}) };
 }
+/** The libraries a remix may add to a studio's package.json by itself (the ones the toolkit's starters use). */
+const REMIX_NEEDS = new Set(['three']);

package/lib/style-board.mjs

@@ -0,0 +1,227 @@
+/**
+ * THE STYLE BOARD AND THE LINEUP: pictures the engine draws for free (lib/render3d.mjs).
+ *
+ *   styleBoard(root, id)      three coherent directions (lib/decisions.mjs directionsFor), each drawn as the game would
+ *                             draw it: its palette, light, camera, material model, fonts and proportions, with the
+ *                             starter library family's own pieces re-tinted into its palette. Saved as
+ *                             games/<id>/codex/board/<a|b|c>-swatch.jpg (private, under 300 KB each), the board in
+ *                             decisions.json. A painted mood image per direction is optional and paid: the art skill
+ *                             makes it on the creator's own fal account and `style mood` records it, labelled a target.
+ *   assetsLineup(root, id)    every made asset at true scale on a 1 m grid under the game's light (front and
+ *                             three-quarter), silhouettes black on white at 64 px tall, and flags: over budget, palette
+ *                             drift (CIEDE2000 from the locked palette), an unreadable silhouette, another library family,
+ *                             stale. .studio/art/<id>/lineup-*.jpg and lineup.json.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+import { readManifest } from './asset-manifest.mjs';
+import { assetsCheck } from './asset-check.mjs';
+import { mix, nearest } from './colour.mjs';
+import { directionsFor, initDecisions, labelOf, lightColours, readDecisions, staleAssets, styleTokens, writeDecisions, addLatestLine } from './decisions.mjs';
+import { PALETTE_KEYS } from './style-presets.mjs';
+import { loadIndex, searchLibrary, fetchItemFile, libraryBase } from './library.mjs';
+import { modelIn, saveDataUrl, withRenderer, dataUrlBytes } from './render3d.mjs';
+
+const BOARD_DIR = join('codex', 'board');
+const PICTURE_MAX = 300 * 1024;
+
+/** A direction's (or a game's) style values as the render page's tokens. */
+export function tokensOf(values) {
+  const ui = values['style.ui'] ?? {};
+  return {
+    palette: values['style.palette'], light: values['style.light'], camera: values['style.camera'], render: values['style.render'],
+    materials: values['style.materials'], fonts: { display: ui.display, body: ui.body }, shape: values['style.shape'], proportions: values['style.proportions'],
+  };
+}
+
+/** Up to `n` library pieces of a family that suit the game's words, as model inputs (empty when no library is reachable). */
+async function libraryPieces(family, query, n, log) {
+  try {
+    const { index, lib } = await loadIndex({ lib: libraryBase() });
+    const picks = [];
+    const seen = new Set();
+    for (const q of [query, 'tree', 'rock', 'bush plant', 'crate barrel']) {
+      for (const hit of searchLibrary(index, q, { family, limit: 6 })) {
+        if (picks.length >= n) break;
+        const it = hit.item;
+        if (seen.has(it.id) || it.kind === 'texture' || it.kind === 'sky' || it.rigged) continue;
+        seen.add(it.id);
+        try { const { bytes } = await fetchItemFile(lib, it); picks.push(modelIn(it.id, bytes, { label: it.name })); } catch (error) { log(`library ${it.id}: ${error.message}`); }
+      }
+    }
+    return picks;
+  } catch (error) { log(`no library pieces: ${error.message}`); return []; }
+}
+
+/** Save a data: URL picture under `max` bytes (re-encoding JPEG quality down if it is over). */
+async function savePicture(url, file, max = PICTURE_MAX) {
+  let bytes = saveDataUrl(url, file);
+  if (bytes <= max) return bytes;
+  try {
+    const sharp = (await import('sharp')).default;
+    for (const q of [78, 68, 58]) {
+      const out = await sharp(dataUrlBytes(url).bytes).jpeg({ quality: q, mozjpeg: true }).toBuffer();
+      writeFileSync(file, out);
+      bytes = out.byteLength;
+      if (bytes <= max) break;
+    }
+  } catch { /* kept as it is */ }
+  return bytes;
+}
+
+export async function styleBoard(root, id, { prompt = '', log = () => {}, library = true } = {}) {
+  let doc = readDecisions(root, id);
+  if (!doc) { initDecisions(root, id, { prompt, path: 'hands-on' }); doc = readDecisions(root, id); }
+  const { directions } = directionsFor(root, id, { prompt: prompt || doc.prompt });
+  let game = {};
+  try { game = JSON.parse(readFileSync(join(root, 'games', id, 'game.json'), 'utf8')); } catch { game = {}; }
+  const title = game.name ?? id.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+  const words = [prompt, doc.prompt, (doc.decisions['cast.list']?.value ?? []).map((c) => c.id).join(' ')].join(' ');
+  const dir = join(root, 'games', id, BOARD_DIR);
+  mkdirSync(dir, { recursive: true });
+  const pieces = {};
+  if (library) for (const d of directions) if (!pieces[d.family]) pieces[d.family] = await libraryPieces(d.family, words, 4, log);
+  const out = [];
+  const renderer = await withRenderer(async (r) => {
+    for (const d of directions) {
+      const url = await r.swatch(tokensOf(d.values), pieces[d.family] ?? [], { title });
+      const file = join(dir, `${d.id}-swatch.jpg`);
+      const bytes = await savePicture(url, file);
+      out.push({ ...d, swatch: relative(join(root, 'games', id), file), bytes, library: (pieces[d.family] ?? []).map((m) => m.id) });
+    }
+    return r.renderer;
+  }, { log });
+  const prev = doc.board?.directions ?? [];
+  doc = readDecisions(root, id);
+  // A pick survives a redraw only while its letter still names the same direction.
+  const was = prev.find((p) => p.id === doc.board?.chosen);
+  const still = was && out.some((d) => d.id === was.id && d.label === was.label);
+  doc.board = {
+    at: new Date().toISOString(), renderer, chosen: still ? was.id : null,
+    directions: out.map((d) => ({ id: d.id, label: d.label, family: d.family, values: d.values, swatch: d.swatch.split('\\').join('/'), library: d.library, mood: prev.find((p) => p.id === d.id && p.label === d.label)?.mood ?? null })),
+  };
+  writeDecisions(root, id, doc);
+  return { ok: true, command: 'style board', id, title, renderer, directions: boardView(root, id, doc) };
+}
+
+/** The board as cards and the CLI show it: per direction its rows (decision, label), swatch path and mood. */
+export function boardView(root, id, doc = readDecisions(root, id)) {
+  return (doc?.board?.directions ?? []).map((d) => ({
+    id: d.id, label: d.label, family: d.family, swatch: d.swatch, mood: d.mood,
+    chosen: doc.board.chosen === d.id,
+    colours: PALETTE_KEYS.map((k) => d.values['style.palette']?.[k]).filter(Boolean),
+    fonts: { display: d.values['style.ui']?.display, body: d.values['style.ui']?.body },
+    rows: Object.entries(d.values).map(([k, v]) => ({ decision: k, label: labelOf(k, v), same: JSON.stringify(doc.decisions[k]?.value) === JSON.stringify(v), state: doc.decisions[k]?.state ?? null })),
+  }));
+}
+
+/** `style mood <id> <dir> --image <file>`: a painted mood image for one direction (made and paid for by the art skill). */
+export async function recordMood(root, id, dirId, image, { usd = null, receipt = null, model = null } = {}) {
+  const doc = readDecisions(root, id);
+  const d = doc?.board?.directions?.find((x) => x.id === dirId);
+  if (!d) throw new Error(`no direction "${dirId}" on the style board (style board ${id} draws it first)`);
+  if (!existsSync(image)) throw new Error(`no picture at ${image}`);
+  const file = join(root, 'games', id, BOARD_DIR, `${dirId}-mood.jpg`);
+  const sharp = (await import('sharp')).default;
+  let q = 82;
+  let out = await sharp(readFileSync(image)).resize(960, 540, { fit: 'cover' }).jpeg({ quality: q, mozjpeg: true }).toBuffer();
+  while (out.byteLength > PICTURE_MAX && q > 50) { q -= 10; out = await sharp(readFileSync(image)).resize(960, 540, { fit: 'cover' }).jpeg({ quality: q, mozjpeg: true }).toBuffer(); }
+  writeFileSync(file, out);
+  d.mood = { path: relative(join(root, 'games', id), file).split('\\').join('/'), usd: usd === null ? null : Number(usd), receipt, model, label: 'target (painted, not what the game draws)', at: new Date().toISOString() };
+  writeDecisions(root, id, doc);
+  return { ok: true, command: 'style mood', id, direction: dirId, mood: d.mood };
+}
+
+/** `style golden <id> add <image>`: one of two to six golden images (references for every concept call). */
+export async function addGolden(root, id, image, { from = null } = {}) {
+  const doc = readDecisions(root, id);
+  if (!doc) throw new Error(`games/${id} has no decisions yet`);
+  if (!existsSync(image)) throw new Error(`no picture at ${image}`);
+  doc.golden = doc.golden ?? [];
+  if (doc.golden.length >= 6) throw new Error('six golden images already: remove one first (style golden <id> remove <n>)');
+  const n = doc.golden.reduce((m, g) => Math.max(m, Number(/(\d+)\.jpg$/.exec(g.path)?.[1] ?? 0)), 0) + 1;
+  const dir = join(root, 'games', id, BOARD_DIR, 'golden');
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${n}.jpg`);
+  try {
+    const sharp = (await import('sharp')).default;
+    writeFileSync(file, await sharp(readFileSync(image)).resize(1024, 1024, { fit: 'inside' }).jpeg({ quality: 84, mozjpeg: true }).toBuffer());
+  } catch { if (/\.jpe?g$/i.test(extname(image))) copyFileSync(image, file); else throw new Error('sharp could not read that picture'); }
+  doc.golden.push({ path: relative(join(root, 'games', id), file).split('\\').join('/'), from: from ?? relative(root, image), approvedBy: 'person', at: new Date().toISOString() });
+  writeDecisions(root, id, doc);
+  addLatestLine(root, id, `Added golden image ${n} (from ${from ?? relative(root, image)}): every concept is made with it as a reference.`);
+  return { ok: true, command: 'style golden', id, golden: doc.golden };
+}
+
+/* ------------------------------------------------------------------ the lineup */
+
+const DRIFT = 18; // mean CIEDE2000 (area-weighted) from the palette above which an asset is flagged
+
+export async function assetsLineup(root, id, { log = () => {} } = {}) {
+  const manifest = readManifest(root, id);
+  const doc = readDecisions(root, id);
+  const tokens = styleTokens(doc) ?? { palette: { bg: '#20242c', ink: '#f2f2f2', accent: '#ffcf5a', accent2: '#7dffb0', danger: '#ff5d5d', good: '#5fdc8b', gold: '#f2c14e', ramp: [] } };
+  const models = [];
+  for (const a of manifest.assets) {
+    const f = (a.files ?? []).find((x) => x.role === 'model');
+    if (!f) continue;
+    const abs = join(root, 'games', id, f.path);
+    if (!existsSync(abs)) continue;
+    // `inGame`: what the game's code does to it at runtime (drawn at another height, repainted from style.json): the
+    // lineup draws it the same way (the repaint as the board's re-tint, the nearest the game's own swap can be shown).
+    const scale = a.inGame?.heightM && a.measured?.heightM ? a.inGame.heightM / a.measured.heightM : null;
+    models.push({ a, input: modelIn(a.id, readFileSync(abs), { label: a.card ? String(a.card).split('/').pop() : a.id, ...(scale ? { scale } : {}), ...(a.inGame?.tint ? { tint: lightColours({ sky: a.inGame.tint, ground: a.inGame.tint }, tokens.palette).sky } : a.inGame?.repaint ? { retint: true } : Number(a.inGame?.pull) > 0 ? { pull: Number(a.inGame.pull) } : {}) }), abs });
+  }
+  if (!models.length) return { ok: false, command: 'assets lineup', id, why: `games/${id} has no recorded models yet (assets add, or the models skill)` };
+  const dir = join(root, '.studio', 'art', id);
+  mkdirSync(dir, { recursive: true });
+  const shot = await withRenderer(async (r) => ({ renderer: r.renderer, ...(await r.lineup(models.map((m) => m.input), tokens)) }), { log });
+  const images = { front: join(dir, 'lineup-front.jpg'), quarter: join(dir, 'lineup-quarter.jpg'), silhouettes: join(dir, 'lineup-silhouettes.png') };
+  saveDataUrl(shot.front, images.front); saveDataUrl(shot.quarter, images.quarter); saveDataUrl(shot.silhouettes, images.silhouettes);
+  const palette = [...PALETTE_KEYS.map((k) => tokens.palette[k]), ...(tokens.palette.ramp ?? [])].filter(Boolean);
+  const family = doc?.decisions?.['cast.family']?.value ?? null;
+  const check = await assetsCheck(root, id, { validate: false, write: true }).catch(() => null);
+  const stale = doc ? staleAssets(doc, manifest) : [];
+  const { albedoOf } = await import('./optimise.mjs');
+  const rows = [];
+  for (const m of models) {
+    const flags = [];
+    let drift = null;
+    try {
+      const colours = await albedoOf(m.abs);
+      // A model the game pulls toward the palette (inGame.pull) is scored on the colours it is drawn in.
+      const pull = Math.max(0, Math.min(1, Number(m.a.inGame?.pull) || 0));
+      const drawn = colours.map((c) => (pull ? { ...c, hex: mix(c.hex, nearest(c.hex, palette).hex, pull) } : c));
+      const scored = drawn.map((c) => { const n = nearest(c.hex, palette); return { hex: c.hex, share: c.share, palette: n.hex, delta: +n.delta.toFixed(1) }; });
+      const mean = scored.reduce((n, c) => n + c.delta * c.share, 0) / Math.max(0.0001, scored.reduce((n, c) => n + c.share, 0));
+      drift = { mean: +mean.toFixed(1), colours: scored };
+      if (m.a.inGame?.repaint) drift.repaint = m.a.inGame.repaint;
+      else if (mean > DRIFT) flags.push(`palette drift: its colours sit ${drift.mean} from the palette (over ${DRIFT}); a re-tint (free) or a remake`);
+    } catch (error) { log(`${m.a.id}: colours not read (${error.message})`); }
+    const row = shot.rows.find((x) => x.id === m.a.id);
+    if (row && ['character', 'creature'].includes(m.a.kind) && (row.silhouette.widthPx < 6 || row.silhouette.fill > 0.92)) flags.push(`silhouette: ${row.silhouette.widthPx < 6 ? 'too thin to read at 64 px' : 'a blob at 64 px (no limbs, ears or tail break the outline)'}`);
+    const c = check?.rows?.find((x) => x.id === m.a.id);
+    if (c && !c.ok) flags.push(`over budget: ${c.problems[0]}`);
+    if (family && m.a.route === 'library' && m.a.from?.pack && !String(m.a.from.pack).startsWith(family)) flags.push(`another library family (${m.a.from.pack}; the game's is ${family}): mixing families shows`);
+    if (stale.some((s) => s.id === m.a.id)) flags.push('stale: made under an older decision');
+    rows.push({ id: m.a.id, label: m.input.label, kind: m.a.kind, route: m.a.route, size: row?.size ?? null, silhouette: row?.silhouette ?? null, drift, flags });
+  }
+  const result = { ok: true, command: 'assets lineup', id, renderer: shot.renderer, images: Object.fromEntries(Object.entries(images).map(([k, v]) => [k, relative(root, v)])), rows, palette: palette.slice(0, 7), family, at: new Date().toISOString(), flagged: rows.filter((r) => r.flags.length).length };
+  writeFileSync(join(dir, 'lineup.json'), `${JSON.stringify(result, null, 2)}\n`);
+  return result;
+}
+
+/** `assets review <id> --score n --outliers a,b`: a fresh reviewer's "one game?" score, and the assets it named. */
+export function recordReview(root, id, { score, outliers = [], note = null, by = 'reviewer' } = {}) {
+  const s = Number(score);
+  if (!(s >= 1 && s <= 10)) throw new Error('--score 1 to 10 ("does it look like one game?")');
+  const dir = join(root, '.studio', 'art', id);
+  mkdirSync(dir, { recursive: true });
+  const manifest = readManifest(root, id);
+  const needs = new Set(outliers.filter(Boolean));
+  if (s < 7) for (const a of manifest.assets) if (a.route !== 'procedural') needs.add(a.id);
+  const review = { score: s, outliers: [...needs], note, by, at: new Date().toISOString(), verdict: s >= 7 && !outliers.length ? 'one game' : 'needs review' };
+  writeFileSync(join(dir, 'review.json'), `${JSON.stringify(review, null, 2)}\n`);
+  return { ok: true, command: 'assets review', id, review };
+}
+