@koda-sl/baker-cli 0.98.0-dev.62be5b016 → 0.98.1

package/dist/cli.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import {
-  AssetRef,
   ELEVENLABS_MAX_MUSIC_LENGTH_MS,
   IMAGE_GENERATE_MODELS,
   MODEL_REGISTRY,
@@ -8,10 +7,9 @@ import {
   ValidationError,
   createEngineFromEnv,
   defaultRegistry,
-  extForMime,
   generateCatalog,
   validateCanvasDeep
-} from "./chunk-IKMDQQ4M.js";
+} from "./chunk-3JVYU72O.js";
 
 // src/cli.ts
 import { defineCommand as defineCommand149, runMain } from "citty";
@@ -149,9 +147,9 @@ async function handleResponse(response) {
     throw new ApiError("INTERNAL_ERROR", "Failed to parse API response as JSON");
   }
 }
-async function apiGet(path8, params) {
+async function apiGet(path11, params) {
   const env = getEnv();
-  const url = new URL(path8, env.BAKER_API_URL);
+  const url = new URL(path11, env.BAKER_API_URL);
   if (params) {
     const clean = sanitizeParams(params);
     for (const [key, value] of Object.entries(clean)) {
@@ -176,12 +174,12 @@ async function apiGet(path8, params) {
   }
   return handleResponse(response);
 }
-async function apiPost(path8, body, opts) {
+async function apiPost(path11, body, opts) {
   const env = getEnv();
   const timeoutMs = opts?.timeoutMs ?? 6e4;
   let response;
   try {
-    response = await fetchWithRateLimitRetry(new URL(path8, env.BAKER_API_URL).toString(), {
+    response = await fetchWithRateLimitRetry(new URL(path11, env.BAKER_API_URL).toString(), {
       method: "POST",
       headers: {
         Authorization: `Bearer ${env.BAKER_API_KEY}`,
@@ -1329,31 +1327,31 @@ function cachePath(category, key) {
   return join(dir, `${hashKey(key)}.json`);
 }
 function cacheGet(category, key) {
-  const path8 = cachePath(category, key);
-  if (!existsSync(path8)) {
+  const path11 = cachePath(category, key);
+  if (!existsSync(path11)) {
     return null;
   }
   try {
-    const raw = readFileSync(path8, "utf-8");
+    const raw = readFileSync(path11, "utf-8");
     const entry = JSON.parse(raw);
     if (entry.expiresAt < Date.now()) {
-      rmSync(path8, { force: true });
+      rmSync(path11, { force: true });
       return null;
     }
     return entry;
   } catch {
-    rmSync(path8, { force: true });
+    rmSync(path11, { force: true });
     return null;
   }
 }
 function cacheSet(category, key, data, ttlMs, fields) {
-  const path8 = cachePath(category, key);
+  const path11 = cachePath(category, key);
   const entry = {
     expiresAt: Date.now() + ttlMs,
     data,
     fields
   };
-  writeFileSync(path8, JSON.stringify(entry), "utf-8");
+  writeFileSync(path11, JSON.stringify(entry), "utf-8");
 }
 var HOUR = 60 * 60 * 1e3;
 var MINUTE = 60 * 1e3;
@@ -8063,232 +8061,14 @@ var catalogCommand = defineCommand78({
   }
 });
 
-// src/commands/canvas/gallery.ts
-import { readdir, readFile } from "fs/promises";
-import path from "path";
-import { defineCommand as defineCommand79 } from "citty";
-
-// src/engine/gallery/descriptor.ts
-var KNOWN_RATIOS = [
-  ["9:16", 9 / 16],
-  ["4:5", 4 / 5],
-  ["1:1", 1],
-  ["1.91:1", 1.91],
-  ["16:9", 16 / 9],
-  ["4:1", 4]
-];
-var RATIO_TOLERANCE = 0.06;
-function aspectLabel(width, height) {
-  if (!width || !height) {
-    return "other";
-  }
-  const ratio = width / height;
-  let best = "other";
-  let bestErr = Number.POSITIVE_INFINITY;
-  for (const [label, value] of KNOWN_RATIOS) {
-    const err = Math.abs(ratio - value) / value;
-    if (err < bestErr) {
-      bestErr = err;
-      best = label;
-    }
-  }
-  return bestErr <= RATIO_TOLERANCE ? best : `${width}x${height}`;
-}
-function visualRef(value) {
-  const parsed = AssetRef.safeParse(value);
-  if (!parsed.success) {
-    return null;
-  }
-  if (parsed.data.kind !== "image" && parsed.data.kind !== "video") {
-    return null;
-  }
-  return parsed.data;
-}
-function deliverableFor(ref, stem, resolveLocal) {
-  const width = "width" in ref ? ref.width : void 0;
-  const height = "height" in ref ? ref.height : void 0;
-  return {
-    kind: ref.kind,
-    format: aspectLabel(width, height),
-    // Remote-node outputs already carry a public R2 url; local composites are
-    // resolved against the mounted run dir's public base.
-    url: ref.url ?? resolveLocal(`${stem}.${extForMime(ref.mime)}`),
-    width,
-    height,
-    label: stem
-  };
-}
-function deliverablesFromOutput(output, resolveLocal) {
-  if (Array.isArray(output)) {
-    const out = [];
-    output.forEach((entry, i) => {
-      const ref2 = visualRef(entry);
-      if (ref2) {
-        out.push(deliverableFor(ref2, `_final__${i}`, resolveLocal));
-      }
-    });
-    return out;
-  }
-  const ref = visualRef(output);
-  return ref ? [deliverableFor(ref, "_final", resolveLocal)] : [];
-}
-function buildGeneration(runId, manifest, resolveLocal) {
-  const m = manifest ?? {};
-  const credits = typeof m.stats?.total_credits === "number" ? m.stats.total_credits : 0;
-  return {
-    runId,
-    createdAt: typeof m.completed_at === "number" ? m.completed_at : 0,
-    credits,
-    deliverables: deliverablesFromOutput(m.output, resolveLocal)
-  };
-}
-function buildGalleryDescriptor(input) {
-  const generations = [...input.generations].sort((a, b) => b.createdAt - a.createdAt);
-  return {
-    slug: input.slug,
-    title: input.definition.title,
-    platform: input.definition.platform,
-    status: input.definition.status,
-    reference: input.definition.reference,
-    selectedRun: input.definition.selectedRun,
-    generations
-  };
-}
-function titleFromSlug(slug) {
-  return slug.split(/[-_/]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
-}
-function stripQuotes(raw) {
-  const trimmed = raw.trim();
-  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
-    return trimmed.slice(1, -1);
-  }
-  return trimmed;
-}
-function parseInlineList(raw) {
-  return raw.slice(1, -1).split(",").map((item) => stripQuotes(item)).filter(Boolean);
-}
-function parseFrontmatter(markdown) {
-  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  const block = match?.[1];
-  if (!block) {
-    return {};
-  }
-  const out = {};
-  let listKey = null;
-  for (const line of block.split(/\r?\n/)) {
-    const item = line.match(/^\s+-\s+(.*)$/)?.[1];
-    if (listKey && item !== void 0) {
-      out[listKey].push(stripQuotes(item));
-      continue;
-    }
-    const kv = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
-    if (!kv?.[1]) {
-      continue;
-    }
-    listKey = null;
-    const key = kv[1];
-    const value = (kv[2] ?? "").trim();
-    if (value === "") {
-      out[key] = [];
-      listKey = key;
-    } else if (value.startsWith("[") && value.endsWith("]")) {
-      out[key] = parseInlineList(value);
-    } else {
-      out[key] = stripQuotes(value);
-    }
-  }
-  return out;
-}
-function asString(value) {
-  if (typeof value === "string" && value.length > 0) {
-    return value;
-  }
-  return void 0;
-}
-function asList(value) {
-  if (Array.isArray(value)) {
-    return value;
-  }
-  return typeof value === "string" && value.length > 0 ? [value] : [];
-}
-function parseCreativeDefinition(markdown, slug) {
-  const fm = parseFrontmatter(markdown);
-  return {
-    title: asString(fm.title) ?? titleFromSlug(slug),
-    platform: asList(fm.platform),
-    formats: asList(fm.formats),
-    status: asString(fm.status) ?? "draft",
-    reference: asString(fm.reference),
-    selectedRun: asString(fm.selected_run)
-  };
-}
-
-// src/commands/canvas/gallery.ts
-async function readJson(file) {
-  try {
-    return JSON.parse(await readFile(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
-async function listRunDirs(runsDir) {
-  try {
-    const entries = await readdir(runsDir, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
-  } catch {
-    return [];
-  }
-}
-var galleryCommand = defineCommand79({
-  meta: {
-    name: "gallery",
-    description: "Read a creative's _definition.md + every persisted run manifest and emit the gallery descriptor (JSON) the dashboard renders."
-  },
-  args: {
-    dir: { type: "positional", required: true, description: "Creative folder, e.g. src/creatives/<slug>" },
-    "workspace-dir": { type: "string", description: "R2-mounted workspace root (default ./.creatives-workspace)" },
-    "public-url": { type: "string", description: "R2 public base (default $R2_PUBLIC_URL)" },
-    "company-id": { type: "string", description: "Company id for the R2 prefix (default $BAKER_COMPANY_ID)" }
-  },
-  async run({ args }) {
-    const creativeDir = path.resolve(String(args.dir));
-    const slug = path.basename(creativeDir);
-    const workspaceDir = path.resolve(String(args["workspace-dir"] ?? ".creatives-workspace"));
-    const runsDir = path.join(workspaceDir, slug, "runs");
-    const runtimeEnv = process.env;
-    const publicUrl = (args["public-url"] ?? runtimeEnv.R2_PUBLIC_URL ?? "").replace(/\/+$/, "");
-    const companyId = String(args["company-id"] ?? runtimeEnv.BAKER_COMPANY_ID ?? "");
-    const definitionPath = path.join(creativeDir, "_definition.md");
-    let definitionMd = "";
-    try {
-      definitionMd = await readFile(definitionPath, "utf8");
-    } catch {
-    }
-    const definition = parseCreativeDefinition(definitionMd, slug);
-    const generations = [];
-    for (const runId of await listRunDirs(runsDir)) {
-      const manifest = await readJson(path.join(runsDir, runId, "manifest.json"));
-      if (!manifest) {
-        continue;
-      }
-      const runDir = path.join(runsDir, runId);
-      const resolveLocal = (filename) => publicUrl && companyId ? `${publicUrl}/creatives/${companyId}/${slug}/runs/${runId}/${filename}` : path.join(runDir, filename);
-      generations.push(buildGeneration(runId, manifest, resolveLocal));
-    }
-    const descriptor = buildGalleryDescriptor({ slug, definition, generations });
-    process.stdout.write(`${JSON.stringify({ ok: true, descriptor }, null, 2)}
-`);
-  }
-});
-
 // src/commands/canvas/inspect.ts
 import { execFile } from "child_process";
-import { readdir as readdir2, readFile as readFile2, stat } from "fs/promises";
-import path2 from "path";
+import { readdir, readFile, stat } from "fs/promises";
+import path from "path";
 import { promisify } from "util";
-import { defineCommand as defineCommand80 } from "citty";
+import { defineCommand as defineCommand79 } from "citty";
 var execFileAsync = promisify(execFile);
-var inspectCommand = defineCommand80({
+var inspectCommand = defineCommand79({
   meta: {
     name: "inspect",
     description: "Dump a one-page summary of a canvas run: per-node duration + cache status, list of output files in the run dir, and optionally three thumbnail frames per video output. Pass either a run_id (resolved against --outputs-dir) or an absolute run directory."
@@ -8302,7 +8082,7 @@ var inspectCommand = defineCommand80({
     }
   },
   async run({ args }) {
-    const outputsDir = path2.resolve(String(args["outputs-dir"] ?? "canvas"));
+    const outputsDir = path.resolve(String(args["outputs-dir"] ?? "canvas"));
     const runArg = String(args.run);
     const runDir = await resolveRunDir(runArg, outputsDir);
     const manifest = await loadManifest(runDir);
@@ -8314,7 +8094,7 @@ var inspectCommand = defineCommand80({
     }
     const summary = {
       ok: true,
-      run_id: manifest.run_id ?? path2.basename(runDir),
+      run_id: manifest.run_id ?? path.basename(runDir),
       run_dir: runDir,
       stats: manifest.stats ?? null,
       output: manifest.output ?? null,
@@ -8327,20 +8107,20 @@ var inspectCommand = defineCommand80({
   }
 });
 async function resolveRunDir(run, outputsDir) {
-  if (path2.isAbsolute(run)) {
+  if (path.isAbsolute(run)) {
     const s2 = await stat(run).catch(() => null);
     if (s2?.isDirectory()) return run;
     throw new Error(`inspect: ${run} is not a directory`);
   }
-  const candidate = path2.join(outputsDir, run);
+  const candidate = path.join(outputsDir, run);
   const s = await stat(candidate).catch(() => null);
   if (s?.isDirectory()) return candidate;
   throw new Error(`inspect: no run directory at ${candidate}`);
 }
 async function loadManifest(runDir) {
-  const manifestPath = path2.join(runDir, "manifest.json");
+  const manifestPath = path.join(runDir, "manifest.json");
   try {
-    const raw = await readFile2(manifestPath, "utf-8");
+    const raw = await readFile(manifestPath, "utf-8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -8348,9 +8128,9 @@ async function loadManifest(runDir) {
 }
 async function listRunFiles(runDir) {
   const out = [];
-  const names = await readdir2(runDir);
+  const names = await readdir(runDir);
   for (const name of names) {
-    const abs = path2.join(runDir, name);
+    const abs = path.join(runDir, name);
     const s = await stat(abs).catch(() => null);
     if (!s?.isFile()) continue;
     out.push({ name, path: abs, size: s.size });
@@ -8395,9 +8175,9 @@ async function probeDuration(filePath) {
 }
 
 // src/commands/canvas/run.ts
-import { readFile as readFile3 } from "fs/promises";
-import path3 from "path";
-import { defineCommand as defineCommand81 } from "citty";
+import { readFile as readFile2 } from "fs/promises";
+import path4 from "path";
+import { defineCommand as defineCommand80 } from "citty";
 
 // src/commands/canvas/placeholders.ts
 function unsuppliedPlaceholderAssets(canvas) {
@@ -8415,19 +8195,74 @@ function unsuppliedPlaceholderAssets(canvas) {
   return out;
 }
 
+// src/commands/canvas/resolve-paths.ts
+import path2 from "path";
+function resolveRelativeCanvasPaths(canvas, baseDir) {
+  if (!canvas || typeof canvas !== "object") return canvas;
+  const c = canvas;
+  if (!Array.isArray(c.nodes)) return canvas;
+  return { ...canvas, nodes: c.nodes.map((n) => resolveNode(n, baseDir)) };
+}
+function resolveNode(node, baseDir) {
+  if (!node || typeof node !== "object") return node;
+  const n = node;
+  const params = n.params;
+  if (!params || typeof params !== "object") return node;
+  if (n.type === "ingest" && params.source === "path" && isResolvableRelative(params.path)) {
+    return { ...node, params: { ...params, path: path2.resolve(baseDir, params.path) } };
+  }
+  if (n.type === "hyperframe_render" && isResolvableRelative(params.composition)) {
+    return { ...node, params: { ...params, composition: path2.resolve(baseDir, params.composition) } };
+  }
+  return node;
+}
+function isResolvableRelative(value) {
+  return typeof value === "string" && value.length > 0 && !value.includes("[TODO") && !path2.isAbsolute(value);
+}
+
+// src/commands/canvas/run-retention.ts
+import { rm } from "fs/promises";
+import path3 from "path";
+function runDirsToPrune(entries, keep, currentRunId) {
+  const runs = entries.filter((e) => /^r_[0-9A-Za-z]+$/.test(e) && e !== currentRunId).sort();
+  if (keep <= 0) return runs;
+  return runs.slice(0, Math.max(0, runs.length - keep));
+}
+async function pruneOldRuns(outputsDir, keep, currentRunId, log) {
+  const { readdir: readdir3 } = await import("fs/promises");
+  let entries;
+  try {
+    entries = await readdir3(outputsDir);
+  } catch {
+    return;
+  }
+  const toPrune = runDirsToPrune(entries, keep, currentRunId);
+  if (toPrune.length === 0) return;
+  for (const dir of toPrune) {
+    await rm(path3.join(outputsDir, dir), { recursive: true, force: true }).catch(
+      (e) => log(`[prune   ] could not remove ${dir}: ${e.message}`)
+    );
+  }
+  log(`[prune   ] removed ${toPrune.length} old run dir(s), kept the ${keep} newest`);
+}
+
 // src/commands/canvas/run.ts
-var runCommand = defineCommand81({
+var runCommand = defineCommand80({
   meta: { name: "run", description: "Validate and execute a canvas JSON file." },
   args: {
     file: { type: "positional", required: true, description: "Path to canvas JSON" },
     "cache-dir": { type: "string", description: "Cache root (default ./canvas/.cache)" },
     "outputs-dir": { type: "string", description: "Per-run outputs root (default ./canvas)" },
     "run-id": { type: "string", description: "Override run id" },
-    "cache-policy": { type: "string", description: "read_write | bypass | read_only" }
+    "cache-policy": { type: "string", description: "read_write | bypass | read_only" },
+    "keep-runs": {
+      type: "string",
+      description: "After the run, prune old r_* run dirs, keeping the N newest (off by default)"
+    }
   },
   async run({ args }) {
-    const filePath = path3.resolve(String(args.file));
-    const raw = await readFile3(filePath, "utf8");
+    const filePath = path4.resolve(String(args.file));
+    const raw = await readFile2(filePath, "utf8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -8437,6 +8272,7 @@ var runCommand = defineCommand81({
 `);
       process.exit(2);
     }
+    parsed = resolveRelativeCanvasPaths(parsed, path4.dirname(filePath));
     const pending = unsuppliedPlaceholderAssets(parsed);
     if (pending.length > 0) {
       process.stderr.write(
@@ -8468,6 +8304,12 @@ var runCommand = defineCommand81({
         run_id: args["run-id"] ? String(args["run-id"]) : void 0,
         cache_policy: policy
       });
+      const keepRuns = args["keep-runs"] !== void 0 ? Number(args["keep-runs"]) : void 0;
+      if (keepRuns !== void 0 && Number.isFinite(keepRuns)) {
+        const outputsDir = args["outputs-dir"] ? path4.resolve(String(args["outputs-dir"])) : path4.resolve("canvas");
+        await pruneOldRuns(outputsDir, keepRuns, result.run_id, (line) => process.stdout.write(`${line}
+`));
+      }
       process.stdout.write(
         `${JSON.stringify(
           {
@@ -8499,9 +8341,9 @@ var runCommand = defineCommand81({
 });
 
 // src/commands/canvas/scaffold-static-ad.ts
-import { readFile as readFile4, writeFile } from "fs/promises";
-import path4 from "path";
-import { defineCommand as defineCommand82 } from "citty";
+import { readFile as readFile3, writeFile } from "fs/promises";
+import path5 from "path";
+import { defineCommand as defineCommand81 } from "citty";
 
 // src/engine/scaffold/staticAd.ts
 import { z as z2 } from "zod";
@@ -8714,7 +8556,7 @@ var SELECT_SYSTEM = 'You identify the MAIN, identity-critical visual elements of
 var SELECT_PROMPT = 'AD BLUEPRINT (from image_describe):\n{{blueprint}}\n\nFrom this blueprint, list ONLY the elements that are prominent, important, and identity-bearing \u2014 the ones a reproduction must ground in a real asset:\n- the brand logo/wordmark (from brands_logos with function_in_image = advertiser_brand) -> type "logo"\n- trust/rating/certification/app-store/review badges (brands_logos with function_in_image = trust_badge | review_platform | certification_or_seal | app_store_badge | payment_method) -> type "badge"\n- a showcased/hero product or package (a foreground entry in subjects that the ad is selling) -> type "product"\n- a foreground person whose identity matters (from people) -> type "person"\n- a foreground animal/character with a specific expression (from subjects) -> type "animal"\n\nDROP background extras, decorative props, generic scenery, and anything small or incidental. Keep at most ~6. If there are none, return an empty list.\n\nFor each kept element return: { "type": one of logo|product|person|animal|badge, "label": a short UPPER_SNAKE_CASE name (e.g. LOGO, PRODUCT, HERO_DOG, TRUSTPILOT), "description": a concrete reusable description to source/shoot the real asset (include the exact expression for a living subject), "expression": the facial expression for a living subject or null, "reason": why it is identity-critical, "locator": the blueprint entry this element came from as { "collection": one of "subjects" | "people" | "brands_logos", "index": its 0-based position in that array } (people -> people; logos/badges -> brands_logos; products/animals/objects -> subjects). Output ONLY the JSON object.';
 async function loadAssetText(ref, label) {
   const r = ref;
-  if (typeof r?.path === "string") return readFile4(r.path, "utf8");
+  if (typeof r?.path === "string") return readFile3(r.path, "utf8");
   if (typeof r?.url === "string") {
     const res = await fetch(r.url);
     if (!res.ok) throw new Error(`failed to fetch ${label} (${res.status})`);
@@ -8820,7 +8662,7 @@ async function runVisionPasses(canvas) {
     return fail("read_outputs", e instanceof Error ? e.message : String(e));
   }
 }
-var scaffoldStaticAdCommand = defineCommand82({
+var scaffoldStaticAdCommand = defineCommand81({
   meta: {
     name: "scaffold-static-ad",
     description: "Turn a source/inspiration image into a runnable static-ad canvas. Runs billed passes \u2014 image_describe (the blueprint, baked to prompt.json as the editable 'prompt'), an AI selection of the image's MAIN identity elements, and a structured global-layout pass (the column/row grid with per-region bounds and text sizes) \u2014 then scaffolds a canvas that wires one [TODO] ingest slot per element (logo/product/subject/badge + brand font) into image_generate. Edit prompt.json and drop the real assets, then `baker canvas run` it."
@@ -8837,10 +8679,10 @@ var scaffoldStaticAdCommand = defineCommand82({
     "skip-font": { type: "boolean", description: "Skip the brand-font \u2192 type-specimen slot" }
   },
   async run({ args }) {
-    const imagePath = path4.resolve(String(args.file));
-    const outPath = args.out ? path4.resolve(String(args.out)) : path4.join(path4.dirname(imagePath), "static-ad.canvas.json");
-    const outDir = path4.dirname(outPath);
-    const blueprintPath = path4.join(outDir, "prompt.json");
+    const imagePath = path5.resolve(String(args.file));
+    const outPath = args.out ? path5.resolve(String(args.out)) : path5.join(path5.dirname(imagePath), "static-ad.canvas.json");
+    const outDir = path5.dirname(outPath);
+    const blueprintPath = path5.join(outDir, "prompt.json");
     const { describeModel, selectModel, layoutModel, genModel } = resolveModels(args);
     const describeCanvas = buildDescribeCanvas(
       imagePath,
@@ -8897,7 +8739,7 @@ var scaffoldStaticAdCommand = defineCommand82({
             run_estimated_credits: validation.estimatedCredits
           },
           checklist: {
-            edit_prompt: `Edit ${path4.basename(blueprintPath)} \u2014 it is the blueprint generated from your image; rewrite it into the ad you want (palette, copy, claims, subjects). It feeds the generator directly.`,
+            edit_prompt: `Edit ${path5.basename(blueprintPath)} \u2014 it is the blueprint generated from your image; rewrite it into the ad you want (palette, copy, claims, subjects). It feeds the generator directly.`,
             assets_to_supply: report.elements,
             font_slot: report.includes_font ? "Drop a brand font at the [TODO] brandfont path, or delete the brandfont + type_ref nodes to skip it." : "skipped (--skip-font)",
             note: "Replace every [TODO] ingest path with a real file, then `baker canvas validate` and `baker canvas run`. Running generates a billed image \u2014 it is not free."
@@ -8913,12 +8755,12 @@ var scaffoldStaticAdCommand = defineCommand82({
 
 // src/commands/canvas/scaffold-video.ts
 import { cp, mkdir, readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
-import path6 from "path";
-import { defineCommand as defineCommand83 } from "citty";
+import path8 from "path";
+import { defineCommand as defineCommand82 } from "citty";
 
 // src/engine/nodes/local/lib/sceneDetect.ts
 import { execFile as execFile2 } from "child_process";
-import { mkdtemp, readdir as readdir3, readFile as readFile5, rm } from "fs/promises";
+import { mkdtemp, readdir as readdir2, readFile as readFile4, rm as rm2 } from "fs/promises";
 import { tmpdir } from "os";
 import { join as join2 } from "path";
 import { promisify as promisify2 } from "util";
@@ -8982,11 +8824,11 @@ async function runSceneDetectOnce(filePath, threshold, minSceneLenS, timeoutMs)
       ],
       { encoding: "utf-8", maxBuffer: 32 * 1024 * 1024, timeout: timeoutMs }
     );
-    const csvName = (await readdir3(outDir)).find((f) => f.toLowerCase().endsWith(".csv"));
+    const csvName = (await readdir2(outDir)).find((f) => f.toLowerCase().endsWith(".csv"));
     if (!csvName) return [];
-    return parsePySceneDetectCsvCuts(await readFile5(join2(outDir, csvName), "utf-8"));
+    return parsePySceneDetectCsvCuts(await readFile4(join2(outDir, csvName), "utf-8"));
   } finally {
-    await rm(outDir, { recursive: true, force: true });
+    await rm2(outDir, { recursive: true, force: true });
   }
 }
 async function detectSceneCutsPySceneDetect(filePath, opts = {}) {
@@ -9242,6 +9084,13 @@ function stillHoldArgs(durationS, dims) {
     `scale=${dims.w}:${dims.h}:force_original_aspect_ratio=increase,crop=${dims.w}:${dims.h},setsar=1,format=yuv420p`,
     "-c:v",
     "libx264",
+    // Near-visually-lossless re-encode. libx264 DEFAULTS (crf 23, preset medium)
+    // roughly halve the source bitrate and add banding on smooth surfaces; the
+    // spine concats these by stream-copy, so any loss here ships to the final cut.
+    "-crf",
+    "18",
+    "-preset",
+    "slow",
     "-pix_fmt",
     "yuv420p",
     "{{out.video}}"
@@ -9257,6 +9106,13 @@ function trimArgs(durationS, offsetS = 0) {
     "-an",
     "-c:v",
     "libx264",
+    // Preserve the seedance source quality through the trim. libx264 DEFAULTS
+    // (crf 23) halve the bitrate (measured 9.57→4.40 Mbps) and band on motion;
+    // the spine stream-copies the result, so the loss is permanent without this.
+    "-crf",
+    "18",
+    "-preset",
+    "slow",
     "-pix_fmt",
     "yuv420p",
     "{{out.video}}"
@@ -9323,6 +9179,13 @@ var Scene = z3.object({
   // The scene's role in the ad's persuasion arc (DECON-supplied); drives the
   // script re-craft checklist. Inferred from position when absent.
   narrative_role: z3.string().optional(),
+  // DECON-supplied on the HOOK scene: the engineered physical/emotional state that
+  // makes the first frame stop the scroll (sweaty/breathless/urgent …). Injected
+  // into the hook's start-frame description so the generator renders that state,
+  // not a calm influencer (CCA-11).
+  hook_mechanic: z3.object({ mechanic: z3.string().optional(), why_it_stops_scroll: z3.string().optional() }).loose().optional(),
+  // DECON-supplied per-scene location (so a gym hook isn't flattened to "home").
+  scene_setting: z3.string().optional(),
   // How this scene cuts to the next (DECON-supplied). A recognized non-cut type
   // (fade/whip/zoom/dissolve/swipe) is reproduced as an ffmpeg xfade at the
   // boundary; cut/match_cut/none/other stay hard cuts. The last scene's value is
@@ -9370,10 +9233,21 @@ var VideoBlueprint = z3.object({
       mode: z3.string().optional(),
       voice_description: z3.string().optional(),
       persona: z3.string().optional()
-    }).loose().optional()
+    }).loose().optional(),
+    // Visual palette — read only to colour a clean brand-card/CTA plate (the
+    // first hex is the dominant brand colour); never to drive frame generation.
+    style: z3.object({ palette: z3.array(z3.object({ hex: z3.string().optional() }).loose()).optional() }).loose().optional()
   }).loose().optional(),
   scenes: z3.array(Scene).min(1)
 }).loose();
+function injectHookPhysicality(blueprint) {
+  for (const scene of blueprint.scenes) {
+    const why = scene.hook_mechanic?.why_it_stops_scroll?.trim();
+    const prompt = scene.start_frame_prompt?.trim();
+    if (!why || !prompt || prompt.includes(why)) continue;
+    scene.start_frame_prompt = `${prompt} The subject's physical state IS the scroll-stopper \u2014 render it explicitly, not a calm pose: ${why}.`;
+  }
+}
 var AppearsItem = z3.union([z3.number(), z3.object({ scene: z3.number(), edge: z3.string().optional() }).loose()]);
 var RecurringElement = z3.object({
   // person | animal | product | logo | badge | other
@@ -9399,7 +9273,8 @@ function sanitizeId2(raw, fallback) {
   return /^[a-z]/.test(id) ? id : `${fallback}_${id}`.replace(/_+$/g, "") || fallback;
 }
 function labelFor2(el, used) {
-  const base = (el.label ?? el.type ?? "ELEMENT").toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "ELEMENT";
+  const raw = el.type?.toLowerCase() === "logo" ? "BRAND_LOGO" : el.label ?? el.type ?? "ELEMENT";
+  const base = raw.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "ELEMENT";
   let label = base;
   let n = 2;
   while (used.has(label)) label = `${base}_${n++}`;
@@ -9566,6 +9441,8 @@ function buildElementSheets(slots, nodes) {
     if (slot.sameAs) continue;
     if (slot.presence.size < 1) continue;
     const sheetId = `${slot.id}_sheet`;
+    const slotType = slot.type.toLowerCase();
+    const isCast = slotType === "person" || slotType === "animal";
     nodes.push({
       id: sheetId,
       type: "image_reference_sheet",
@@ -9578,7 +9455,14 @@ function buildElementSheets(slots, nodes) {
         // 4K: the sheet packs up to 8 cells (angles + tight face/detail close-ups), and
         // it's the ONE reference every frame grounds on — per-cell sharpness here
         // propagates to every clip, so it's worth the highest tier on this single asset.
-        image_size: "4K"
+        image_size: "4K",
+        // The sheet is the look that propagates to EVERY grounded frame, so a glossy
+        // studio turnaround makes the whole UGC ad read as "produced" (the #1 AI tell).
+        // Force a flat, real, front-camera look on the cast sheet so the actor stays
+        // authentic, not an airbrushed influencer (CCA-02).
+        ...isCast ? {
+          style: "authentic UGC look: flat, even, natural front-camera lighting \u2014 no studio key/rim light, no seamless backdrop, no shallow depth of field; real skin texture and pores, no airbrushing or beauty retouch; true-to-life everyday styling"
+        } : {}
       }
     });
     slot.ref = `$ref:${sheetId}.sheet`;
@@ -9686,8 +9570,7 @@ function buildFrameRef(edge, url, framePrompt, present, ctx, nodes) {
     const t = s.type.toLowerCase();
     return t === "person" || t === "animal";
   });
-  const castIdentityLocked = castSlots.every((s) => s.sheetBacked);
-  const useOriginalAnchor = Boolean(url) && (castSlots.length === 0 || castIdentityLocked);
+  const useOriginalAnchor = Boolean(url) && castSlots.length === 0;
   const hasOriginal = useOriginalAnchor;
   const originalRef = useOriginalAnchor && url ? ingestFrameRef(url, edge, ctx, nodes) : void 0;
   const reference = [...present.map((s) => s.ref), ...originalRef ? [originalRef] : []];
@@ -9898,6 +9781,39 @@ function isUiOnlyComposite(regions) {
   const ui = regions.filter(regionIsUiSurface).length;
   return ui >= 1 && regions.length - ui <= 1;
 }
+function sceneIsFullScreenUi(scene, present) {
+  if (scene.narrative_role?.trim() === "cta") return false;
+  const hasCast = present.some((s) => {
+    const t = s.type.toLowerCase();
+    return t === "person" || t === "animal";
+  });
+  if (hasCast) return false;
+  const hay = `${scene.summary ?? ""} ${scene.start_frame_prompt ?? ""} ${scene.end_frame_prompt ?? ""} ${scene.action_detail ?? ""}`;
+  return UI_SURFACE_RE.test(hay);
+}
+function screenStillArgs(durationS, dims) {
+  return [
+    "-loop",
+    "1",
+    "-i",
+    "{{in.frame}}",
+    "-t",
+    durationS.toFixed(3),
+    "-r",
+    "30",
+    "-vf",
+    `scale=${dims.w}:${dims.h}:force_original_aspect_ratio=decrease,pad=${dims.w}:${dims.h}:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1,format=yuv420p`,
+    "-c:v",
+    "libx264",
+    "-crf",
+    "18",
+    "-preset",
+    "slow",
+    "-pix_fmt",
+    "yuv420p",
+    "{{out.video}}"
+  ];
+}
 function layeredComposition(scene) {
   const comp = scene.composition;
   const layout = (comp?.layout ?? "").toLowerCase();
@@ -10068,6 +9984,77 @@ function emitFlashHold(i, scene, slots, ctx, lengths, out, ar, nodes, clips) {
   });
   clips.push({ ref: `$ref:s${i}_clip.video`, scene_s: lengths.dur, out });
 }
+function emitScreenScene(i, scene, lengths, out, ar, nodes, clips) {
+  const label = commentSafe((scene.summary || scene.start_frame_prompt || "the app screen").slice(0, 120));
+  const refId = `s${i}_screen_ref`;
+  nodes.push({
+    id: refId,
+    type: "ingest",
+    params: {
+      source: "path",
+      path: `[TODO: supply the REAL screen for "${label}" \u2014 NEVER AI-generate a UI. Capture a clean, text-free screenshot with \`baker images screenshot https://<brand-domain>/<path>\` (image-library skill); spoken/overlay text rides the overlay layer, not the screenshot]`,
+      expect: "image"
+    }
+  });
+  nodes.push({
+    id: `s${i}_clip`,
+    type: "ffmpeg",
+    inputs: { frame: `$ref:${refId}.asset` },
+    params: {
+      args: screenStillArgs(lengths.trimTarget, canvasDims(ar)),
+      outputs: { video: { kind: "video", ext: "mp4" } }
+    }
+  });
+  clips.push({ ref: `$ref:s${i}_clip.video`, scene_s: lengths.dur, out });
+}
+var BRAND_CARD_RE = /\b(?:solid|plain|flat|brand|logo|wordmark|end[- ]?card|cta card|title card|colou?r background|background colou?r)\b/i;
+function sceneIsBrandCard(scene, present, isCta) {
+  if (!isCta) return false;
+  const hasCast = present.some((s) => {
+    const t = s.type.toLowerCase();
+    return t === "person" || t === "animal";
+  });
+  if (hasCast) return false;
+  const hay = `${scene.summary ?? ""} ${scene.start_frame_prompt ?? ""} ${scene.end_frame_prompt ?? ""}`;
+  return BRAND_CARD_RE.test(hay);
+}
+var HEX6_RE = /^#?[0-9a-fA-F]{6}$/;
+function brandPlateColor(blueprint) {
+  const palette = blueprint.global?.style?.palette;
+  const hex = palette?.map((p) => p?.hex).find((h) => typeof h === "string" && HEX6_RE.test(h));
+  return hex ? `0x${hex.replace(/^#/, "").toUpperCase()}` : "0x000000";
+}
+function colorPlateArgs(durationS, dims, color) {
+  return [
+    "-f",
+    "lavfi",
+    "-i",
+    `color=c=${color}:s=${dims.w}x${dims.h}:r=30`,
+    "-t",
+    durationS.toFixed(3),
+    "-c:v",
+    "libx264",
+    "-crf",
+    "18",
+    "-preset",
+    "slow",
+    "-pix_fmt",
+    "yuv420p",
+    "{{out.video}}"
+  ];
+}
+function emitBrandCardScene(i, lengths, out, ar, color, nodes, clips) {
+  nodes.push({
+    id: `s${i}_clip`,
+    type: "ffmpeg",
+    inputs: {},
+    params: {
+      args: colorPlateArgs(lengths.trimTarget, canvasDims(ar), color),
+      outputs: { video: { kind: "video", ext: "mp4" } }
+    }
+  });
+  clips.push({ ref: `$ref:s${i}_clip.video`, scene_s: lengths.dur, out });
+}
 function musicArcDigest(blueprint) {
   const roles = blueprint.scenes.map((s) => s.narrative_role).filter((r) => Boolean(r));
   const arc = roles.length > 0 ? roles.join(" \u2192 ") : "";
@@ -10187,7 +10174,7 @@ function makePresenterPresent(slots, canonical, opts = {}) {
   const solePerson = !opts.strict && personSlots.length === 1 ? personSlots[0].presence : null;
   return (speaker, sceneIndex) => {
     const presence = bySpeaker.get(speaker) ?? solePerson;
-    if (!presence) return opts.strict ? false : true;
+    if (!presence) return !opts.strict;
     return presence.has(sceneIndex);
   };
 }
@@ -10552,6 +10539,15 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
     shootMode: mode,
     ingestCache: env.ingestCache
   };
+  if (!env.reuse && sceneIsFullScreenUi(scene, present)) {
+    emitScreenScene(i, scene, lengths, lengths.out, env.ar, nodes, out.clips);
+    return void 0;
+  }
+  const isCta = scene.narrative_role?.trim() === "cta" || isLast;
+  if (!env.reuse && sceneIsBrandCard(scene, present, isCta)) {
+    emitBrandCardScene(i, lengths, lengths.out, env.ar, brandPlateColor(env.blueprint), nodes, out.clips);
+    return void 0;
+  }
   if (!ambientBroll && lengths.dur <= FLASH_HOLD_MAX_S) {
     emitFlashHold(i, scene, env.slots, ctx, lengths, lengths.out, env.ar, nodes, out.clips);
     return void 0;
@@ -10817,7 +10813,7 @@ function overlayElement(ov, at, dur) {
   const normAnim = normalizeAnim(ov.animation);
   const anim = normAnim ? ` data-anim="${normAnim}"` : "";
   const detail = ov.animation_detail ? ` data-anim-detail="${escapeHtml(ov.animation_detail)}"` : "";
-  return `<div class="ov ${positionClass(ov.position)}" data-start="${at}" data-dur="${dur}"${role}${anim}${detail}>${escapeHtml(ov.text.trim())}</div>`;
+  return `<div class="ov clip ${positionClass(ov.position)}" data-start="${at}" data-dur="${dur}"${role}${anim}${detail}>${escapeHtml(ov.text.trim())}</div>`;
 }
 var RICH_OVERLAY_RE = /notif|tweet|\bx post\b|post\b|comment|message|chat|bubble|card|review|rating|stat|counter|toast|popup/;
 function sourceHint(fe) {
@@ -10847,7 +10843,7 @@ function floatingStub(fe, sceneStart) {
   const slug = (fe.kind ?? "element").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "element";
   return [
     `<!-- ${kind}: ${label} @ ${at}s for ${dur}s (${positionClass(fe.position)}). Source a real asset: ${hint} \u2014 drop it in this dir and uncomment:`,
-    `<img class="ov ${positionClass(fe.position)}" src="your-${slug}.png" data-start="${at}" data-dur="${dur}" alt="" /> -->`
+    `<img class="ov clip ${positionClass(fe.position)}" src="your-${slug}.png" data-start="${at}" data-dur="${dur}" alt="" /> -->`
   ].join("\n");
 }
 function uiPipStub(scene) {
@@ -10867,7 +10863,7 @@ function uiPipStub(scene) {
     "     \u2014 OR hand-build a brand-accurate HTML screen; then frame it in a phone mockup:",
     "       npx hyperframes add phone-scroll   (writes compositions/phone-scroll.html)",
     "     drop the screenshot as screenshot.png in this dir and nest it as a PIP clip:",
-    `     <div data-composition-src="compositions/phone-scroll.html" data-start="${at}" data-duration="${dur}" data-track-index="2" data-width="1080" data-height="1920"></div> -->`
+    `     <div class="clip" data-composition-src="compositions/phone-scroll.html" data-start="${at}" data-duration="${dur}" data-track-index="2" data-width="1080" data-height="1920"></div> -->`
   ].join("\n");
 }
 function buildOverlayHtml(input) {
@@ -10963,6 +10959,7 @@ function buildSpine(clips, nodes) {
 }
 function scaffoldVideoCanvas(input, elementsInput, opts) {
   const blueprint = VideoBlueprint.parse(input);
+  injectHookPhysicality(blueprint);
   const elements = RecurringElements.parse(elementsInput);
   const nodes = [];
   nodes.push({
@@ -11374,18 +11371,44 @@ function videoReport(input, elementsInput) {
 
 // src/commands/canvas/composition-path.ts
 import { existsSync as existsSync3 } from "fs";
-import path5 from "path";
+import path6 from "path";
 function resolveShippedCanvasDir(name, startDir, exists = existsSync3, maxDepth = 8) {
-  const rel = path5.join("canvas", name);
+  const rel = path6.join("canvas", name);
   let dir = startDir;
   for (let i = 0; i < maxDepth; i++) {
-    const candidate = path5.join(dir, rel);
-    if (exists(path5.join(candidate, "meta.json"))) return candidate;
-    const parent = path5.dirname(dir);
+    const candidate = path6.join(dir, rel);
+    if (exists(path6.join(candidate, "meta.json"))) return candidate;
+    const parent = path6.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return path5.resolve(startDir, "../../../", rel);
+  return path6.resolve(startDir, "../../../", rel);
+}
+
+// src/commands/canvas/gitignore.ts
+import { appendFile, readFile as readFile5 } from "fs/promises";
+import path7 from "path";
+function missingGitignoreEntries(existing, entries) {
+  const present = new Set(
+    existing.split("\n").map((l) => l.trim().replace(/\/+$/, "")).filter((l) => l.length > 0 && !l.startsWith("#"))
+  );
+  return entries.filter((e) => !present.has(e.trim().replace(/\/+$/, "")));
+}
+async function ensureGitignore(dir, entries) {
+  const file = path7.join(dir, ".gitignore");
+  let existing;
+  try {
+    existing = await readFile5(file, "utf8");
+  } catch {
+    return;
+  }
+  const missing = missingGitignoreEntries(existing, entries);
+  if (missing.length === 0) return;
+  const prefix = existing.endsWith("\n") || existing.length === 0 ? "" : "\n";
+  await appendFile(file, `${prefix}
+# Baker canvas (engine cache + scaffold working files)
+${missing.join("\n")}
+`);
 }
 
 // src/commands/canvas/scaffold-video.ts
@@ -11433,7 +11456,7 @@ async function loadTranscriptBestEffort(ref) {
 async function stageCaptions(outDir, transcript) {
   const text = transcript?.trim();
   if (!text || text === "[]") return {};
-  const compositionPath = path6.join(outDir, "tiktok-captions-composition");
+  const compositionPath = path8.join(outDir, "tiktok-captions-composition");
   await cp(SHIPPED_CAPTIONS_DIR, compositionPath, { recursive: true });
   return { compositionPath };
 }
@@ -11565,7 +11588,7 @@ async function runAnalysisPasses(deconstructCanvas, selectModel) {
     return fail2("deconstruct", e instanceof Error ? e.message : String(e));
   }
 }
-var scaffoldVideoCommand = defineCommand83({
+var scaffoldVideoCommand = defineCommand82({
   meta: {
     name: "scaffold-video",
     description: "Turn a reference video into a runnable reproduction canvas in one command. Runs billed passes \u2014 video_deconstruct (the full scene-by-scene blueprint + transcript, baked to prompt.json as the editable 'prompt') and an AI selection of the video's RECURRING identity elements (person/animal/product/logo) \u2014 then scaffolds a pipeline where every scene boundary is a static-ad-grade frame (the blueprint as target_blueprint, a reference legend, the real frame as anchor) and each recurring element gets ONE shared [TODO] ingest slot wired into every frame it appears in. The clips feed Seedance an ultra-detailed motion brief (action, camera, dialogue, transcript). Edit prompt.json, drop the real source images, then `baker canvas run`."
@@ -11595,11 +11618,11 @@ var scaffoldVideoCommand = defineCommand83({
     }
   },
   async run({ args }) {
-    const videoPath = path6.resolve(String(args.file));
-    const base = path6.basename(videoPath, path6.extname(videoPath));
-    const outPath = args.out ? path6.resolve(String(args.out)) : path6.join(path6.dirname(videoPath), `${base}.video.canvas.json`);
-    const outDir = path6.dirname(outPath);
-    const blueprintPath = path6.join(outDir, "prompt.json");
+    const videoPath = path8.resolve(String(args.file));
+    const base = path8.basename(videoPath, path8.extname(videoPath));
+    const outPath = args.out ? path8.resolve(String(args.out)) : path8.join(path8.dirname(videoPath), `${base}.video.canvas.json`);
+    const outDir = path8.dirname(outPath);
+    const blueprintPath = path8.join(outDir, "prompt.json");
     const frames = args.frames === "reuse" ? "reuse" : "generate";
     const maxScenes = args["max-scenes"] ? Number(args["max-scenes"]) : void 0;
     if (Number.isFinite(maxScenes)) {
@@ -11622,9 +11645,9 @@ var scaffoldVideoCommand = defineCommand83({
     const annotated = annotateBlueprintWithElements(blueprint, elements);
     await writeFile2(blueprintPath, `${JSON.stringify(annotated, null, 2)}
 `, "utf8");
-    const compositionDest = path6.join(outDir, "video-overlay-composition");
+    const compositionDest = path8.join(outDir, "video-overlay-composition");
     await cp(SHIPPED_COMPOSITION_DIR, compositionDest, { recursive: true });
-    const indexPath = path6.join(compositionDest, "index.html");
+    const indexPath = path8.join(compositionDest, "index.html");
     const overlayHtml = buildOverlayHtml(blueprint);
     const indexHtml = await readFile6(indexPath, "utf8");
     const injected = indexHtml.replace("<!--OVERLAYS-->", () => overlayHtml);
@@ -11639,9 +11662,9 @@ var scaffoldVideoCommand = defineCommand83({
     const opts = {
       imageModel,
       videoModel,
-      overlayCompositionPath: compositionDest,
-      captionsCompositionPath: captions.compositionPath,
-      blueprintPath,
+      overlayCompositionPath: path8.relative(outDir, compositionDest),
+      captionsCompositionPath: captions.compositionPath ? path8.relative(outDir, captions.compositionPath) : void 0,
+      blueprintPath: path8.relative(outDir, blueprintPath),
       frames,
       ambient: Boolean(args.ambient),
       ...args.resolution ? { resolution: String(args.resolution) } : {}
@@ -11654,7 +11677,7 @@ var scaffoldVideoCommand = defineCommand83({
     } catch (e) {
       return fail2("scaffold", e instanceof Error ? e.message : String(e));
     }
-    const validation = await validateCanvasDeep(canvas, defaultRegistry());
+    const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(canvas, outDir), defaultRegistry());
     if (!validation.ok) {
       process.stderr.write(
         `${JSON.stringify({ ok: false, error: { code: "validation", issues: validation.issues } }, null, 2)}
@@ -11664,6 +11687,7 @@ var scaffoldVideoCommand = defineCommand83({
     }
     await writeFile2(outPath, `${JSON.stringify(canvas, null, 2)}
 `, "utf8");
+    await ensureGitignore(process.cwd(), ["canvas/", ".context/"]);
     process.stdout.write(
       `${JSON.stringify(
         {
@@ -11681,7 +11705,7 @@ var scaffoldVideoCommand = defineCommand83({
             run_estimated_credits: validation.estimatedCredits
           },
           checklist: {
-            edit_prompt: `Edit ${path6.basename(blueprintPath)} \u2014 the blueprint deconstructed from your video; rewrite it into the ad you want (cast, palette, copy, claims). Every scene frame reads it via target_blueprint.`,
+            edit_prompt: `Edit ${path8.basename(blueprintPath)} \u2014 the blueprint deconstructed from your video; rewrite it into the ad you want (cast, palette, copy, claims). Every scene frame reads it via target_blueprint.`,
             recurring_elements_to_supply: report.elements,
             voices_to_confirm: report.dialogue.map((d) => ({
               scene: d.scene,
@@ -11706,9 +11730,84 @@ var scaffoldVideoCommand = defineCommand83({
   }
 });
 
+// src/commands/canvas/set-prompt.ts
+import { readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
+import path9 from "path";
+import { defineCommand as defineCommand83 } from "citty";
+function setNodePrompt(canvas, nodeId, text) {
+  const nodes = canvas?.nodes;
+  if (!Array.isArray(nodes)) throw new Error("canvas has no nodes array");
+  const idx = nodes.findIndex((n) => n?.id === nodeId);
+  if (idx < 0) {
+    const ids = nodes.map((n) => n?.id).filter((id) => typeof id === "string");
+    throw new Error(`node "${nodeId}" not found. Known nodes: ${ids.join(", ")}`);
+  }
+  const node = nodes[idx];
+  const newNode = { ...node, params: { ...node.params ?? {}, prompt: text } };
+  const newNodes = [...nodes];
+  newNodes[idx] = newNode;
+  return { ...canvas, nodes: newNodes };
+}
+var setPromptCommand = defineCommand83({
+  meta: {
+    name: "set-prompt",
+    description: "Safely set a node's params.prompt (a frame description, motion prompt, etc.) without hand-editing the JSON. Prefer --text-file for multi-line/accented copy \u2014 it preserves UTF-8 exactly, unlike shell-quoted jq."
+  },
+  args: {
+    file: { type: "positional", required: true, description: "Path to canvas JSON" },
+    node: { type: "positional", required: true, description: "Node id to edit (e.g. s0_start)" },
+    text: { type: "string", description: "New prompt text (inline)" },
+    "text-file": { type: "string", description: "Read the new prompt from a UTF-8 file (preserves accents/newlines)" }
+  },
+  async run({ args }) {
+    const filePath = path9.resolve(String(args.file));
+    let canvas;
+    try {
+      canvas = JSON.parse(await readFile7(filePath, "utf8"));
+    } catch (e) {
+      process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "parse", message: String(e) } }, null, 2)}
+`);
+      process.exit(2);
+    }
+    let text;
+    if (args["text-file"]) text = await readFile7(path9.resolve(String(args["text-file"])), "utf8");
+    else if (args.text !== void 0) text = String(args.text);
+    else {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, error: { code: "no_text", message: "pass --text or --text-file" } }, null, 2)}
+`
+      );
+      process.exit(2);
+      return;
+    }
+    let updated;
+    try {
+      updated = setNodePrompt(canvas, String(args.node), text);
+    } catch (e) {
+      process.stderr.write(
+        `${JSON.stringify({ ok: false, error: { code: "node_not_found", message: String(e.message) } }, null, 2)}
+`
+      );
+      process.exit(2);
+      return;
+    }
+    const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(updated, path9.dirname(filePath)), defaultRegistry());
+    if (!validation.ok) {
+      process.stderr.write(`${JSON.stringify({ ok: false, error: { code: "validation", issues: validation.issues } }, null, 2)}
+`);
+      process.exit(2);
+      return;
+    }
+    await writeFile3(filePath, `${JSON.stringify(updated, null, 2)}
+`, "utf8");
+    process.stdout.write(`${JSON.stringify({ ok: true, node: String(args.node), bytes: text.length }, null, 2)}
+`);
+  }
+});
+
 // src/commands/canvas/validate.ts
-import { readFile as readFile7 } from "fs/promises";
-import path7 from "path";
+import { readFile as readFile8 } from "fs/promises";
+import path10 from "path";
 import { defineCommand as defineCommand84 } from "citty";
 var validateCommand = defineCommand84({
   meta: {
@@ -11717,8 +11816,8 @@ var validateCommand = defineCommand84({
   },
   args: { file: { type: "positional", required: true, description: "Path to canvas JSON" } },
   async run({ args }) {
-    const filePath = path7.resolve(String(args.file));
-    const raw = await readFile7(filePath, "utf8");
+    const filePath = path10.resolve(String(args.file));
+    const raw = await readFile8(filePath, "utf8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -11728,6 +11827,7 @@ var validateCommand = defineCommand84({
 `);
       process.exit(2);
     }
+    parsed = resolveRelativeCanvasPaths(parsed, path10.dirname(filePath));
     const result = await validateCanvasDeep(parsed, defaultRegistry());
     if (!result.ok) {
       process.stderr.write(`${JSON.stringify({ ok: false, issues: result.issues }, null, 2)}
@@ -11764,7 +11864,6 @@ Subcommands:
   baker canvas run <file.json>        \u2014 execute the canvas, write outputs to ./canvas/<run_id>/
   baker canvas catalog                \u2014 print the agent-facing node + composition catalog (JSON Schema)
   baker canvas inspect <run_id>       \u2014 one-page summary of a completed run
-  baker canvas gallery <dir>          \u2014 read a creative folder's _definition.md + run manifests into the dashboard gallery descriptor (JSON)
   baker canvas scaffold-video <video>                \u2014 turn a reference video into a runnable reproduction canvas (deconstruct + recurring-element detection)
   baker canvas scaffold-static-ad <image>            \u2014 turn a source image into a runnable static-ad canvas (describe + element detection)`
   },
@@ -11773,9 +11872,9 @@ Subcommands:
     validate: validateCommand,
     catalog: catalogCommand,
     inspect: inspectCommand,
-    gallery: galleryCommand,
     "scaffold-video": scaffoldVideoCommand,
-    "scaffold-static-ad": scaffoldStaticAdCommand
+    "scaffold-static-ad": scaffoldStaticAdCommand,
+    "set-prompt": setPromptCommand
   }
 });
 
@@ -12609,7 +12708,7 @@ function cropSprite(input, region) {
 
 // src/lib/image/io.ts
 import { randomBytes } from "crypto";
-import { glob as fsGlob, readFile as readFile8, rename, stat as stat2, writeFile as writeFile3 } from "fs/promises";
+import { glob as fsGlob, readFile as readFile9, rename, stat as stat2, writeFile as writeFile4 } from "fs/promises";
 import { dirname, extname, join as join3, resolve as resolve4 } from "path";
 var REMOTE_RE = /^https?:\/\//i;
 var GLOB_RE = /[*?[\]{}]/;
@@ -12645,11 +12744,11 @@ async function readImageBuffer(pathOrUrl) {
     }
     return Buffer.from(await response.arrayBuffer());
   }
-  return readFile8(pathOrUrl);
+  return readFile9(pathOrUrl);
 }
-async function isDirectory(path8) {
+async function isDirectory(path11) {
   try {
-    const s = await stat2(path8);
+    const s = await stat2(path11);
     return s.isDirectory();
   } catch {
     return false;
@@ -12668,7 +12767,7 @@ async function atomicWrite(targetPath, data) {
   const absolute = resolve4(targetPath);
   const dir = dirname(absolute);
   const tmp = join3(dir, `.baker-image-${randomBytes(8).toString("hex")}.tmp`);
-  await writeFile3(tmp, data);
+  await writeFile4(tmp, data);
   await rename(tmp, absolute);
 }
 
@@ -13009,7 +13108,7 @@ var findCommand = defineCommand98({
 });
 
 // src/commands/images/generate.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { defineCommand as defineCommand99 } from "citty";
 import sharp2 from "sharp";
 var GENERATE_TIMEOUT_MS = 18e4;
@@ -13092,7 +13191,7 @@ async function resolveReferences(spec) {
     }
     let raw;
     try {
-      raw = await readFile9(entry);
+      raw = await readFile10(entry);
     } catch {
       throw new ApiError("VALIDATION_ERROR", `Reference file not found: ${entry}`);
     }
@@ -14858,7 +14957,7 @@ function makeTagsCommand(command, label, endpoint) {
 var tagsCommand2 = makeTagsCommand("images", "image", "/api/images/tags");
 
 // src/commands/images/upload.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { extname as extname2 } from "path";
 import { defineCommand as defineCommand114 } from "citty";
 var MIME_MAP = {
@@ -14998,7 +15097,7 @@ async function uploadLocal(target, args) {
     });
     return;
   }
-  const fileBuffer = await readFile10(target);
+  const fileBuffer = await readFile11(target);
   const base64 = fileBuffer.toString("base64");
   const body = { base64, contentType };
   if (args.source) body.source = args.source;
@@ -16975,7 +17074,7 @@ var searchCommand3 = defineCommand143({
 var tagsCommand4 = makeTagsCommand("videos", "video", "/api/videos/tags");
 
 // src/commands/videos/upload.ts
-import { readFile as readFile11, stat as stat3 } from "fs/promises";
+import { readFile as readFile12, stat as stat3 } from "fs/promises";
 import { extname as extname3 } from "path";
 import { defineCommand as defineCommand144 } from "citty";
 var MIME_MAP2 = {
@@ -17040,7 +17139,7 @@ var uploadCommand2 = defineCommand144({
         return;
       }
       const { uploadUrl, videoId } = await apiPost("/api/videos/upload", {});
-      const fileBuffer = await readFile11(filePath);
+      const fileBuffer = await readFile12(filePath);
       const uploadResponse = await fetch(uploadUrl, {
         method: "PUT",
         headers: { "Content-Type": contentType },