pixelkiln 0.35.0 → 0.37.0

package/dist/cli.js

@@ -1,5 +1,71 @@
 #!/usr/bin/env node
 
+// src/errors.ts
+var EXIT_CODES = {
+  usage: 2,
+  project: 3,
+  provider: 4,
+  "refused-overwrite": 5,
+  budget: 6,
+  capability: 7
+};
+var PixelKilnError = class extends Error {
+  code;
+  hint;
+  constructor(message6, code, opts = {}) {
+    super(message6, opts.cause === void 0 ? void 0 : { cause: opts.cause });
+    this.name = "PixelKilnError";
+    this.code = code;
+    if (opts.hint) this.hint = opts.hint;
+  }
+};
+var UsageError = class extends PixelKilnError {
+  constructor(message6, opts) {
+    super(message6, "usage", opts);
+    this.name = "UsageError";
+  }
+};
+var ProjectError = class extends PixelKilnError {
+  constructor(message6, opts) {
+    super(message6, "project", opts);
+    this.name = "ProjectError";
+  }
+};
+var ProviderError = class extends PixelKilnError {
+  /** Registry id of the provider that failed. */
+  provider;
+  /** HTTP status when the failure was a response, otherwise undefined. */
+  status;
+  constructor(provider, message6, opts = {}) {
+    super(message6, "provider", opts);
+    this.name = "ProviderError";
+    this.provider = provider;
+    if (opts.status !== void 0) this.status = opts.status;
+  }
+};
+var OverwriteRefusedError = class extends PixelKilnError {
+  /** The file(s) left untouched. */
+  files;
+  constructor(message6, files, opts) {
+    super(message6, "refused-overwrite", opts);
+    this.name = "OverwriteRefusedError";
+    this.files = files;
+  }
+};
+var BudgetError = class extends PixelKilnError {
+  constructor(message6, opts) {
+    super(message6, "budget", opts);
+    this.name = "BudgetError";
+  }
+};
+function errorCode(err) {
+  return err instanceof PixelKilnError ? err.code : void 0;
+}
+function exitCodeFor(err) {
+  const code = errorCode(err);
+  return code ? EXIT_CODES[code] : 1;
+}
+
 // src/cli/main.ts
 import { existsSync as existsSync31 } from "fs";
 import { readFile as readFile27 } from "fs/promises";
@@ -103,7 +169,7 @@ var TOOLS = ["editor"];
 function parseArgs(argv) {
   const [command = "help"] = argv;
   if (!COMMANDS.includes(command)) {
-    throw new Error(`Unknown command "${command}". Run \`pixelkiln help\` for the list.`);
+    throw new UsageError(`Unknown command "${command}". Run \`pixelkiln help\` for the list.`);
   }
   let rest = argv.slice(1);
   let subcommand;
@@ -111,10 +177,10 @@ function parseArgs(argv) {
   if (command === "quality") {
     subcommand = rest[0];
     if (subcommand === void 0 || subcommand.startsWith("-")) {
-      throw new Error(`quality needs a subcommand: ${QUALITY_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`quality needs a subcommand: ${QUALITY_SUBCOMMANDS.join(", ")}`);
     }
     if (!QUALITY_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(
+      throw new UsageError(
         `Unknown quality subcommand "${subcommand}". Known: ${QUALITY_SUBCOMMANDS.join(", ")}`
       );
     }
@@ -122,10 +188,10 @@ function parseArgs(argv) {
   } else if (command === "recipe") {
     subcommand = rest[0];
     if (subcommand === void 0 || subcommand.startsWith("-")) {
-      throw new Error(`recipe needs a subcommand: ${RECIPE_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`recipe needs a subcommand: ${RECIPE_SUBCOMMANDS.join(", ")}`);
     }
     if (!RECIPE_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(
+      throw new UsageError(
         `Unknown recipe subcommand "${subcommand}". Known: ${RECIPE_SUBCOMMANDS.join(", ")}`
       );
     }
@@ -133,17 +199,17 @@ function parseArgs(argv) {
     if (subcommand !== "list") {
       target = rest[0];
       if (target === void 0 || target.startsWith("-")) {
-        throw new Error(`recipe ${subcommand} needs a recipe id, selector, or path.`);
+        throw new UsageError(`recipe ${subcommand} needs a recipe id, selector, or path.`);
       }
       rest = rest.slice(1);
     }
   } else if (command === "workspace") {
     subcommand = rest[0];
     if (subcommand === void 0 || subcommand.startsWith("-")) {
-      throw new Error(`workspace needs a subcommand: ${WORKSPACE_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`workspace needs a subcommand: ${WORKSPACE_SUBCOMMANDS.join(", ")}`);
     }
     if (!WORKSPACE_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(
+      throw new UsageError(
         `Unknown workspace subcommand "${subcommand}". Known: ${WORKSPACE_SUBCOMMANDS.join(", ")}`
       );
     }
@@ -151,7 +217,7 @@ function parseArgs(argv) {
     if (subcommand === "add" || subcommand === "remove") {
       target = rest[0];
       if (target === void 0 || target.startsWith("-")) {
-        throw new Error(
+        throw new UsageError(
           subcommand === "add" ? "workspace add needs a manifest path." : "workspace remove needs a project id or manifest path."
         );
       }
@@ -160,29 +226,29 @@ function parseArgs(argv) {
   } else if (command === "edit") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "start" : rest[0];
     if (!EDIT_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(`Unknown edit subcommand "${subcommand}". Known: ${EDIT_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`Unknown edit subcommand "${subcommand}". Known: ${EDIT_SUBCOMMANDS.join(", ")}`);
     }
     if (rest[0] === subcommand) rest = rest.slice(1);
   } else if (command === "tools") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "status" : rest[0];
     if (!TOOLS_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(`Unknown tools subcommand "${subcommand}". Known: ${TOOLS_SUBCOMMANDS.join(", ")}`);
+      throw new UsageError(`Unknown tools subcommand "${subcommand}". Known: ${TOOLS_SUBCOMMANDS.join(", ")}`);
     }
     if (rest[0] === subcommand) rest = rest.slice(1);
     target = rest[0]?.startsWith("-") ? void 0 : rest[0];
     if (subcommand === "install" && target === void 0) {
-      throw new Error(`tools install needs a tool name: ${TOOLS.join(", ")}`);
+      throw new UsageError(`tools install needs a tool name: ${TOOLS.join(", ")}`);
     }
     if (target !== void 0) {
       if (!TOOLS.includes(target)) {
-        throw new Error(`Unknown tool "${target}". Known: ${TOOLS.join(", ")}`);
+        throw new UsageError(`Unknown tool "${target}". Known: ${TOOLS.join(", ")}`);
       }
       rest = rest.slice(1);
     }
   } else if (command === "refine") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "run" : rest[0];
     if (!REFINE_SUBCOMMANDS.includes(subcommand)) {
-      throw new Error(
+      throw new UsageError(
         `Unknown refine subcommand "${subcommand}". Known: ${REFINE_SUBCOMMANDS.join(", ")}`
       );
     }
@@ -191,19 +257,19 @@ function parseArgs(argv) {
   for (let i = 0; i < rest.length; i++) {
     const token = rest[i];
     if (!token.startsWith("-")) {
-      throw new Error(`Unexpected argument "${token}". Options must be passed with a named flag.`);
+      throw new UsageError(`Unexpected argument "${token}". Options must be passed with a named flag.`);
     }
     if (BOOL_FLAGS.includes(token)) continue;
     if (VALUE_FLAGS.includes(token)) {
       const value = rest[i + 1];
       const looksLikeFlag = value !== void 0 && value.startsWith("-") && !Number.isFinite(Number(value));
       if (value === void 0 || looksLikeFlag) {
-        throw new Error(`${token} needs a value.`);
+        throw new UsageError(`${token} needs a value.`);
       }
       i++;
       continue;
     }
-    throw new Error(
+    throw new UsageError(
       `Unknown flag "${token}". Known flags: ${[...VALUE_FLAGS, ...BOOL_FLAGS].join(", ")}`
     );
   }
@@ -227,7 +293,7 @@ function parseArgs(argv) {
   if (rawColumns !== void 0) {
     columns = Number(rawColumns);
     if (!Number.isInteger(columns) || columns < 1 || columns > 1024) {
-      throw new Error(`--columns must be a whole number between 1 and 1024, got "${rawColumns}"`);
+      throw new UsageError(`--columns must be a whole number between 1 and 1024, got "${rawColumns}"`);
     }
   }
   const rawPort = get("--port");
@@ -235,7 +301,7 @@ function parseArgs(argv) {
   if (rawPort !== void 0) {
     port = Number(rawPort);
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
-      throw new Error(`--port must be a whole number between 1 and 65535, got "${rawPort}"`);
+      throw new UsageError(`--port must be a whole number between 1 and 65535, got "${rawPort}"`);
     }
   }
   let budget;
@@ -248,30 +314,30 @@ function parseArgs(argv) {
       const rawAmount = rawBudget.slice(separator + 1).trim();
       const amount2 = Number(rawAmount);
       if (!providerId || /[=\s]/.test(providerId) || !Number.isFinite(amount2) || amount2 < 0) {
-        throw new Error(
+        throw new UsageError(
           `--budget must be a non-negative number or provider=number, got "${rawBudget}".`
         );
       }
       if (Object.hasOwn(providerBudgets, providerId)) {
-        throw new Error(`--budget repeats provider "${providerId}".`);
+        throw new UsageError(`--budget repeats provider "${providerId}".`);
       }
       providerBudgets[providerId] = amount2;
       continue;
     }
     const amount = Number(rawBudget);
     if (!Number.isFinite(amount) || amount < 0) {
-      throw new Error(`--budget must be a non-negative number, got "${rawBudget}".`);
+      throw new UsageError(`--budget must be a non-negative number, got "${rawBudget}".`);
     }
-    if (budget !== void 0) throw new Error("Only one unkeyed --budget may be passed.");
+    if (budget !== void 0) throw new UsageError("Only one unkeyed --budget may be passed.");
     budget = amount;
   }
   if (budget !== void 0 && Object.keys(providerBudgets).length) {
-    throw new Error("Do not mix an unkeyed --budget with provider-keyed budgets.");
+    throw new UsageError("Do not mix an unkeyed --budget with provider-keyed budgets.");
   }
   const manifest = get("--manifest") ?? "pixelkiln.manifest.json";
   const rawFormat = get("--format");
   if (rawFormat && rawFormat !== "generic" && rawFormat !== "tiled" && rawFormat !== "godot") {
-    throw new Error(`--format must be generic, tiled, or godot, got "${rawFormat}"`);
+    throw new UsageError(`--format must be generic, tiled, or godot, got "${rawFormat}"`);
   }
   const numberOption = (flag, opts) => {
     const raw = get(flag);
@@ -279,13 +345,13 @@ function parseArgs(argv) {
     const value = Number(raw);
     if (!Number.isFinite(value) || value < opts.min || opts.max !== void 0 && value > opts.max || opts.integer && !Number.isInteger(value)) {
       const range = opts.max === void 0 ? `at least ${opts.min}` : `${opts.min} to ${opts.max}`;
-      throw new Error(`${flag} must be ${opts.integer ? "a whole number " : "a number "}${range}, got "${raw}"`);
+      throw new UsageError(`${flag} must be ${opts.integer ? "a whole number " : "a number "}${range}, got "${raw}"`);
     }
     return value;
   };
   const rawGridConfidence = get("--min-grid-confidence");
   if (rawGridConfidence !== void 0 && rawGridConfidence !== "low" && rawGridConfidence !== "medium" && rawGridConfidence !== "high") {
-    throw new Error(
+    throw new UsageError(
       `--min-grid-confidence must be low, medium, or high, got "${rawGridConfidence}"`
     );
   }
@@ -505,10 +571,11 @@ function measureBalanceChange(before, after) {
   };
 }
 var DEFAULT_RATE_LIMIT = { spacingMs: 2500, maxInFlight: 8 };
-var UnsupportedCapabilityError = class extends Error {
+var UnsupportedCapabilityError = class extends PixelKilnError {
   constructor(providerId, capability) {
     super(
-      `Provider "${providerId}" does not support ${capability}. That command is unavailable with this backend.`
+      `Provider "${providerId}" does not support ${capability}. That command is unavailable with this backend.`,
+      "capability"
     );
     this.name = "UnsupportedCapabilityError";
   }
@@ -539,8 +606,8 @@ function formatCost(unit, amount) {
 }
 
 // src/pipeline/plan.ts
-import { existsSync as existsSync6 } from "fs";
-import path9 from "path";
+import { existsSync as existsSync5 } from "fs";
+import path8 from "path";
 
 // src/hash.ts
 import { createHash } from "crypto";
@@ -776,6 +843,18 @@ var StyleObjectSchema = z.object({
    * chocolate bar.
    */
   palette: z.array(HexColorSchema).default([]),
+  /**
+   * Snap every visible pixel of the downloaded art to the nearest `palette`
+   * colour, without dithering. The palette is sent to providers that take
+   * one, and most honour it most of the time; this makes it a guarantee
+   * for every generator, including the ones with no palette parameter.
+   * Applied by `fetch` as the file is written and recorded on the lock
+   * entry, so a restore reproduces the same bytes. Turning it on or off
+   * does not change the spec hash: `plan` reports the entry as recoverable
+   * and the next `fetch` or `restore` re-applies it from the art already
+   * on disk or in the cache, spending nothing.
+   */
+  enforcePalette: z.boolean().default(false),
   /** Fail-closed native-grid, palette, and human-approval policy for derived art. */
   quality: QualityProfileSchema.optional(),
   /**
@@ -817,6 +896,13 @@ var StyleSchema = StyleObjectSchema.refine((s) => !(s.tileFeature && s.styleImag
       path: ["quality"]
     });
   }
+  if (style.enforcePalette && style.palette.length < 2) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "enforcePalette needs a palette of at least two colours to snap to",
+      path: ["enforcePalette"]
+    });
+  }
 });
 var InheritedStyleSchema = StyleObjectSchema.partial().extend({
   extends: z.string().min(1),
@@ -939,7 +1025,21 @@ var LockOutputSchema = z.object({
   path: z.string(),
   sha256: z.string(),
   role: z.string().optional(),
-  mediaType: MediaTypeSchema.optional()
+  mediaType: MediaTypeSchema.optional(),
+  /**
+   * Hash of the provider's bytes before post-processing changed them, when
+   * it did. The content cache keeps both, so the post-processing can be
+   * undone or redone without contacting the provider.
+   */
+  raw: z.string().optional()
+});
+var PostprocessSchema = z.object({
+  palette: z.object({
+    /** Canonical lowercase `#rrggbb` values, in manifest order. */
+    colors: z.array(z.string()).min(2).max(256),
+    dither: z.literal("none"),
+    distance: z.literal("redmean")
+  }).optional()
 });
 var LockSourceSchema = z.object({
   url: z.string(),
@@ -965,6 +1065,7 @@ var LockHistoryEntrySchema = z.object({
   cost: z.number().finite().nonnegative().default(0),
   costUnit: z.string().min(1).default("generations"),
   provider: z.string().default("pixellab"),
+  postprocess: PostprocessSchema.optional(),
   /** When the replacement was submitted. */
   retiredAt: z.string()
 });
@@ -1036,14 +1137,7 @@ var LockEntrySchema = z.object({
    * `role` labels non-primary artifacts (e.g. "portrait", "spriteframes") so a
    * consumer can find the one it wants without pattern-matching on paths.
    */
-  outputs: z.array(
-    z.object({
-      path: z.string(),
-      sha256: z.string(),
-      role: z.string().optional(),
-      mediaType: MediaTypeSchema.optional()
-    })
-  ).default([]),
+  outputs: z.array(LockOutputSchema).default([]),
   /**
    * Provider-owned data retained for downstream consumers, namespaced by
    * provider id. PixelLab connectable sets keep their exact `tileRules` here
@@ -1059,7 +1153,9 @@ var LockEntrySchema = z.object({
   /** Which provider produced this. Absent on entries written before providers. */
   provider: z.string().default("pixellab"),
   /** Generations this entry replaced, newest first; see LockHistoryEntrySchema. */
-  history: z.array(LockHistoryEntrySchema).optional()
+  history: z.array(LockHistoryEntrySchema).optional(),
+  /** Post-processing applied to the recorded outputs; absent when the bytes are the provider's. */
+  postprocess: PostprocessSchema.optional()
 });
 var LockSchema = z.object({
   version: z.literal(2),
@@ -1086,9 +1182,10 @@ async function loadLock(lockPath) {
   try {
     return parseLock(JSON.parse(await readFile(lockPath, "utf8")));
   } catch (err) {
-    throw new Error(
+    throw new ProjectError(
       `Lockfile at ${lockPath} is malformed:
-${err instanceof Error ? err.message : String(err)}`
+${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
     );
   }
 }
@@ -1122,8 +1219,9 @@ async function writeLockWhileHeld(file, lock) {
     try {
       disk = parseLock(JSON.parse(await readFile(file, "utf8")));
     } catch (err) {
-      throw new Error(
-        `Refusing to overwrite malformed lockfile at ${file}: ${err instanceof Error ? err.message : String(err)}`
+      throw new ProjectError(
+        `Refusing to overwrite malformed lockfile at ${file}: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err }
       );
     }
   }
@@ -1807,13 +1905,13 @@ function resolveSpecOutputs(spec, lock, manifestDir) {
 }
 
 // src/pipeline/quality-profile.ts
-import { existsSync as existsSync4 } from "fs";
-import path7 from "path";
+import { existsSync as existsSync3 } from "fs";
+import path6 from "path";
 
 // src/pipeline/refine.ts
-import path6 from "path";
+import path5 from "path";
 import { execFile } from "child_process";
-import { mkdtemp, readFile as readFile4, rm as rm3 } from "fs/promises";
+import { mkdtemp, readFile as readFile3, rm as rm3 } from "fs/promises";
 import { tmpdir } from "os";
 import { promisify } from "util";
 
@@ -2051,10 +2149,11 @@ async function writeManagedArtifactBundle(manifestPath, outputs, provenance, opt
       if (!expected || digest(current) !== expected) conflicts.push(destination);
     }
     if (conflicts.length) {
-      throw new Error(
+      throw new OverwriteRefusedError(
         `Refusing to overwrite modified or unowned artifact file(s):
 ` + conflicts.map((file) => `  ${file}`).join("\n") + `
-Pass { force: true } (CLI: --force) to take ownership and replace the complete bundle.`
+Pass { force: true } (CLI: --force) to take ownership and replace the complete bundle.`,
+        conflicts
       );
     }
   }
@@ -2273,10 +2372,19 @@ async function writeArtifactBundle(files, options = {}) {
   };
 }
 
-// src/pipeline/audit.ts
-import { readFile as readFile3 } from "fs/promises";
-import { existsSync as existsSync3 } from "fs";
-import path5 from "path";
+// src/palette.ts
+function normalizePalette(values) {
+  const colors = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const rgb = parseHex(value);
+    const hex2 = `#${rgb.r.toString(16).padStart(2, "0")}${rgb.g.toString(16).padStart(2, "0")}${rgb.b.toString(16).padStart(2, "0")}`;
+    if (!colors.has(hex2)) colors.set(hex2, { hex: hex2, ...rgb });
+  }
+  if (colors.size < 2 || colors.size > 256) {
+    throw new Error(`A palette must contain 2\u2013256 unique colors; got ${colors.size}.`);
+  }
+  return [...colors.values()];
+}
 function colorDistance(a, b) {
   const rmean = (a.r + b.r) / 2;
   const dr = a.r - b.r;
@@ -2286,146 +2394,45 @@ function colorDistance(a, b) {
     (512 + rmean) * dr * dr / 256 + 4 * dg * dg + (767 - rmean) * db * db / 256
   );
 }
-function paletteDistance(asset, reference) {
-  if (!asset.length || !reference.length) return 0;
-  let total = 0;
-  let weight = 0;
-  for (const color of asset) {
-    let nearest = Infinity;
-    for (const ref of reference) nearest = Math.min(nearest, colorDistance(color, ref));
-    total += nearest * color.weight;
-    weight += color.weight;
-  }
-  return weight === 0 ? 0 : total / weight;
-}
-function mergePalettes(palettes, topN = 24) {
-  const totals = /* @__PURE__ */ new Map();
-  for (const palette of palettes) {
-    for (const color of palette) {
-      const key = `${color.r},${color.g},${color.b}`;
-      const existing = totals.get(key);
-      if (existing) existing.weight += color.weight;
-      else totals.set(key, { ...color });
+function quantize(png, palette) {
+  const colors = normalizePalette(palette);
+  const pixels = Buffer.from(png.pixels);
+  const nearestOf = /* @__PURE__ */ new Map();
+  let changed = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const alpha = pixels[i + 3];
+    if (alpha === 0) {
+      if (pixels[i] || pixels[i + 1] || pixels[i + 2]) changed++;
+      pixels[i] = 0;
+      pixels[i + 1] = 0;
+      pixels[i + 2] = 0;
+      continue;
     }
-  }
-  const merged = [...totals.values()].sort((a, b) => b.weight - a.weight).slice(0, topN);
-  const sum = merged.reduce((s, c) => s + c.weight, 0) || 1;
-  return merged.map((c) => ({ ...c, weight: c.weight / sum }));
-}
-async function auditStyle(loaded, specs, styleId, lock) {
-  const style = loaded.manifest.styles[styleId];
-  if (!style) throw new Error(`Unknown style "${styleId}"`);
-  const mine = specs.filter((s) => s.styleId === styleId);
-  const assets = [];
-  const missing = [];
-  const unreadable = [];
-  for (const spec of mine) {
-    for (const output of resolveSpecOutputs(spec, lock, loaded.root)) {
-      if (!existsSync3(output.absolutePath)) {
-        missing.push(output.id);
-        continue;
-      }
-      try {
-        const png = decodePng(await readFile3(output.absolutePath));
-        const palette = extractPalette(png, 12);
-        assets.push({
-          assetId: spec.assetId,
-          ...output.role ? { outputRole: output.role } : {},
-          id: output.id,
-          file: output.absolutePath,
-          width: png.width,
-          height: png.height,
-          paletteDistance: 0,
-          // filled once the reference is known
-          transparency: transparencyRatio(png),
-          colorCount: countColors(png),
-          palette
-        });
-      } catch (err) {
-        unreadable.push(`${output.id}: ${err instanceof Error ? err.message : String(err)}`);
+    const key = pixels[i] << 16 | pixels[i + 1] << 8 | pixels[i + 2];
+    let nearest = nearestOf.get(key);
+    if (!nearest) {
+      const pixel = { r: pixels[i], g: pixels[i + 1], b: pixels[i + 2] };
+      nearest = colors[0];
+      let distance = colorDistance(pixel, nearest);
+      for (let j = 1; j < colors.length; j++) {
+        const candidate = colors[j];
+        const candidateDistance = colorDistance(pixel, candidate);
+        if (candidateDistance < distance) {
+          nearest = candidate;
+          distance = candidateDistance;
+        }
       }
+      nearestOf.set(key, nearest);
     }
+    if (pixels[i] !== nearest.r || pixels[i + 1] !== nearest.g || pixels[i + 2] !== nearest.b) changed++;
+    pixels[i] = nearest.r;
+    pixels[i + 1] = nearest.g;
+    pixels[i + 2] = nearest.b;
   }
-  let reference = [];
-  let referenceFromStyleImages = false;
-  const refPalettes = [];
-  for (const img of style.styleImages) {
-    const abs = path5.resolve(loaded.root, img.path);
-    if (!existsSync3(abs)) continue;
-    try {
-      refPalettes.push(extractPalette(decodePng(await readFile3(abs)), 12));
-    } catch {
-    }
-  }
-  if (refPalettes.length) {
-    reference = mergePalettes(refPalettes);
-    referenceFromStyleImages = true;
-    for (const asset of assets) {
-      asset.paletteDistance = paletteDistance(asset.palette, reference);
-    }
-  } else {
-    reference = mergePalettes(assets.map((a) => a.palette));
-    for (const asset of assets) {
-      const others = assets.filter((a) => a !== asset).map((a) => a.palette);
-      asset.paletteDistance = others.length ? paletteDistance(asset.palette, mergePalettes(others)) : 0;
-    }
-  }
-  assets.sort((a, b) => b.paletteDistance - a.paletteDistance);
-  return { styleId, referenceFromStyleImages, reference, assets, missing, unreadable };
-}
-function countColors(png) {
-  const seen = /* @__PURE__ */ new Set();
-  for (let i = 0; i < png.pixels.length; i += 4) {
-    if (png.pixels[i + 3] < 128) continue;
-    seen.add(png.pixels[i] << 16 | png.pixels[i + 1] << 8 | png.pixels[i + 2]);
-  }
-  return seen.size;
-}
-function outliers(audit, sigma = 1.5) {
-  const n = audit.assets.length;
-  if (n < 3) return [];
-  const mean = audit.assets.reduce((s, a) => s + a.paletteDistance, 0) / n;
-  const variance = audit.assets.reduce((s, a) => s + (a.paletteDistance - mean) ** 2, 0) / n;
-  const sd = Math.sqrt(variance);
-  if (sd === 0) return [];
-  return audit.assets.filter((a) => a.paletteDistance > mean + sigma * sd);
-}
-function evaluateAudit(audit, thresholds = {}) {
-  const resolved = { ...thresholds, sigma: thresholds.sigma ?? 1.5 };
-  const relative = outliers(audit, resolved.sigma);
-  const relativeIds = new Set(relative.map((asset) => asset.id));
-  const violations = [];
-  for (const asset of audit.assets) {
-    const reasons = [];
-    if (relativeIds.has(asset.id)) {
-      reasons.push(`palette outlier beyond ${resolved.sigma} standard deviations`);
-    }
-    if (resolved.maxDistance !== void 0 && asset.paletteDistance > resolved.maxDistance) {
-      reasons.push(
-        `palette distance ${asset.paletteDistance.toFixed(1)} exceeds ${resolved.maxDistance}`
-      );
-    }
-    if (resolved.minTransparency !== void 0 && asset.transparency < resolved.minTransparency) {
-      reasons.push(
-        `transparency ${(asset.transparency * 100).toFixed(1)}% is below ${(resolved.minTransparency * 100).toFixed(1)}%`
-      );
-    }
-    if (resolved.maxColors !== void 0 && asset.colorCount > resolved.maxColors) {
-      reasons.push(`color count ${asset.colorCount} exceeds ${resolved.maxColors}`);
-    }
-    if (reasons.length) violations.push({ id: asset.id, reasons });
-  }
-  return {
-    safe: violations.length === 0 && audit.missing.length === 0 && audit.unreadable.length === 0,
-    thresholds: resolved,
-    outliers: [...relativeIds],
-    violations,
-    missing: [...audit.missing],
-    unreadable: [...audit.unreadable]
-  };
+  return { png: { width: png.width, height: png.height, pixels }, changed };
 }
-function hex(c) {
-  return `#${[c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+function quantizeToPalette(png, palette) {
+  return quantize(png, palette).png;
 }
 
 // src/pipeline/refine.ts
@@ -2512,48 +2519,12 @@ function parseDetection(raw) {
     confidence: confidenceFor(consensus)
   };
 }
-function normalizePalette(values) {
-  const colors = /* @__PURE__ */ new Map();
-  for (const value of values) {
-    const rgb = parseHex(value);
-    const hex2 = `#${rgb.r.toString(16).padStart(2, "0")}${rgb.g.toString(16).padStart(2, "0")}${rgb.b.toString(16).padStart(2, "0")}`;
-    colors.set(hex2, { hex: hex2, ...rgb });
-  }
-  if (colors.size < 2 || colors.size > 256) {
-    throw new Error(`A refinement palette must contain 2\u2013256 unique colors; got ${colors.size}.`);
-  }
-  return [...colors.values()];
-}
 function normalizeRefinementPalette(values) {
-  return normalizePalette(values).map((color) => color.hex);
-}
-function quantizeToPalette(png, palette) {
-  const colors = normalizePalette(palette);
-  const pixels = Buffer.from(png.pixels);
-  for (let i = 0; i < pixels.length; i += 4) {
-    const alpha = pixels[i + 3];
-    if (alpha === 0) {
-      pixels[i] = 0;
-      pixels[i + 1] = 0;
-      pixels[i + 2] = 0;
-      continue;
-    }
-    const pixel = { r: pixels[i], g: pixels[i + 1], b: pixels[i + 2] };
-    let nearest = colors[0];
-    let distance = colorDistance(pixel, nearest);
-    for (let j = 1; j < colors.length; j++) {
-      const candidate = colors[j];
-      const candidateDistance = colorDistance(pixel, candidate);
-      if (candidateDistance < distance) {
-        nearest = candidate;
-        distance = candidateDistance;
-      }
-    }
-    pixels[i] = nearest.r;
-    pixels[i + 1] = nearest.g;
-    pixels[i + 2] = nearest.b;
+  try {
+    return normalizePalette(values).map((color) => color.hex);
+  } catch (err) {
+    throw new Error(`A refinement palette must contain 2\u2013256 unique colors; got ${new Set(values.map((v) => v.toLowerCase())).size}.`, { cause: err });
   }
-  return { width: png.width, height: png.height, pixels };
 }
 function colorCount(png) {
   const colors = /* @__PURE__ */ new Set();
@@ -2663,16 +2634,16 @@ function sameFrameGrid(first, next) {
   return next.detection.stepX === first.detection.stepX && next.detection.stepY === first.detection.stepY && next.detection.columns === first.detection.columns && next.detection.rows === first.detection.rows && phaseMatches(next.detection.phaseX, first.detection.phaseX, first.detection.stepX) && phaseMatches(next.detection.phaseY, first.detection.phaseY, first.detection.stepY) && next.audit.width === first.audit.width && next.audit.height === first.audit.height && next.sourceWidth === first.sourceWidth && next.sourceHeight === first.sourceHeight;
 }
 async function refineAsset(options) {
-  const source = path6.resolve(options.source);
-  const output = path6.resolve(options.output);
+  const source = path5.resolve(options.source);
+  const output = path5.resolve(options.output);
   if (source === output) throw new Error("Refinement source and output must be different files.");
-  const record = path6.resolve(qualityRecordPath(output));
+  const record = path5.resolve(qualityRecordPath(output));
   const palette = normalizePalette(options.palette).map((color) => color.hex);
   const minGridConfidence = requireConfidence(options.minGridConfidence ?? "high");
   if (options.minTransparency !== void 0 && (!Number.isFinite(options.minTransparency) || options.minTransparency < 0 || options.minTransparency > 1)) throw new Error("minTransparency must be between 0 and 1.");
   let sourcePng;
   try {
-    sourcePng = decodePng(await readFile4(source));
+    sourcePng = decodePng(await readFile3(source));
   } catch (error) {
     throw new Error(`Cannot read refinement source ${source}: ${message2(error)}`, { cause: error });
   }
@@ -2689,8 +2660,8 @@ async function refineAsset(options) {
       );
     }
   }
-  const temp = await mkdtemp(path6.join(tmpdir(), "pixelkiln-refine-"));
-  const recovered = path6.join(temp, "native.png");
+  const temp = await mkdtemp(path5.join(tmpdir(), "pixelkiln-refine-"));
+  const recovered = path5.join(temp, "native.png");
   const fixerCommand = compatibilityCommand ?? options.fixerPython ?? process.env.PIXELKILN_PIXEL_FIXER_PYTHON ?? "python3";
   const args = compatibilityCommand ? [...options.fixerArgsPrefix ?? [], source, "--extract", recovered] : ["-c", PYTHON_FIXER_BRIDGE, source, recovered];
   try {
@@ -2711,7 +2682,7 @@ async function refineAsset(options) {
       );
     }
     const detection = parseDetection(firstJsonObject(stdout));
-    const native = decodePng(await readFile4(recovered));
+    const native = decodePng(await readFile3(recovered));
     const quantized = quantizeToPalette(native, palette);
     const png = encodeRgbaPng(quantized.width, quantized.height, quantized.pixels);
     const audit = auditRefinement(
@@ -2775,18 +2746,18 @@ async function refineFrameSet(options) {
   if (roles.some((role) => !role.trim()) || new Set(roles).size !== roles.length) {
     throw new Error("Frame-set roles must be non-empty and unique.");
   }
-  const output = path6.resolve(options.output);
-  const record = path6.resolve(qualityRecordPath(output));
+  const output = path5.resolve(options.output);
+  const record = path5.resolve(qualityRecordPath(output));
   const palette = normalizeRefinementPalette(options.palette);
   const finalOutputs = options.sources.map((source, index) => qualityFrameOutputPath(output, source.role, index));
   if (new Set(finalOutputs).size !== finalOutputs.length) {
     throw new Error("Frame-set roles resolve to duplicate output filenames.");
   }
-  const sourceSet = new Set(options.sources.map((source) => path6.resolve(source.path)));
+  const sourceSet = new Set(options.sources.map((source) => path5.resolve(source.path)));
   if (finalOutputs.some((file) => sourceSet.has(file))) {
     throw new Error("Frame-set refinement sources and outputs must be different files.");
   }
-  const temp = await mkdtemp(path6.join(tmpdir(), "pixelkiln-refine-frames-"));
+  const temp = await mkdtemp(path5.join(tmpdir(), "pixelkiln-refine-frames-"));
   try {
     const frames = [];
     const outputs = [];
@@ -2794,8 +2765,8 @@ async function refineFrameSet(options) {
     const sourcePaths = [];
     let firstOptions = null;
     for (const [index, sourceEntry] of options.sources.entries()) {
-      const source = path6.resolve(sourceEntry.path);
-      const temporaryOutput = path6.join(temp, `${String(index).padStart(2, "0")}.png`);
+      const source = path5.resolve(sourceEntry.path);
+      const temporaryOutput = path5.join(temp, `${String(index).padStart(2, "0")}.png`);
       const refined = await refineAsset({
         source,
         output: temporaryOutput,
@@ -2827,7 +2798,7 @@ async function refineFrameSet(options) {
       });
       outputs.push({
         path: finalOutputs[index],
-        data: await readFile4(temporaryOutput)
+        data: await readFile3(temporaryOutput)
       });
     }
     const first = frames[0];
@@ -2870,7 +2841,7 @@ async function refineFrameSet(options) {
     );
     return {
       sources: sourcePaths,
-      outputs: outputs.map((item) => path6.resolve(item.path)),
+      outputs: outputs.map((item) => path5.resolve(item.path)),
       record,
       frames,
       palette,
@@ -2881,12 +2852,12 @@ async function refineFrameSet(options) {
   }
 }
 async function checkQualityRecord(recordPath) {
-  const record = path6.resolve(recordPath);
+  const record = path5.resolve(recordPath);
   const manifest = await readArtifactBundleManifest(record);
   const options = parseRecordOptions(manifest, record);
   const verification = await verifyArtifactBundle(record);
-  const sources = manifest.sources.map((source2) => path6.resolve(path6.dirname(record), source2.path));
-  const outputs = manifest.outputs.map((output2) => path6.resolve(path6.dirname(record), output2.path));
+  const sources = manifest.sources.map((source2) => path5.resolve(path5.dirname(record), source2.path));
+  const outputs = manifest.outputs.map((output2) => path5.resolve(path5.dirname(record), output2.path));
   const source = sources[0] ?? "";
   const output = outputs[0] ?? "";
   const expectedCount = options.frameSet?.count ?? 1;
@@ -2919,7 +2890,7 @@ async function checkQualityRecord(recordPath) {
 async function approveQualityRecord(recordPath, approval) {
   const reviewer = approval.reviewer.trim();
   if (!reviewer) throw new Error("A human reviewer name is required.");
-  const record = path6.resolve(recordPath);
+  const record = path5.resolve(recordPath);
   const manifest = await readArtifactBundleManifest(record);
   const options = parseRecordOptions(manifest, record);
   const verification = await verifyArtifactBundle(record);
@@ -2940,14 +2911,14 @@ async function approveQualityRecord(recordPath, approval) {
       `A refinement record must contain exactly ${expectedCount} source(s) and output(s).`
     );
   }
-  const root = path6.dirname(record);
+  const root = path5.dirname(record);
   const outputs = await Promise.all(manifest.outputs.map(async (entry) => {
-    const outputPath = path6.resolve(root, entry.path);
-    return { path: outputPath, data: await readFile4(outputPath) };
+    const outputPath = path5.resolve(root, entry.path);
+    return { path: outputPath, data: await readFile3(outputPath) };
   }));
   const sources = manifest.sources.map((source) => ({
     ...source,
-    path: path6.resolve(root, source.path)
+    path: path5.resolve(root, source.path)
   }));
   const approved = {
     ...options,
@@ -2979,8 +2950,8 @@ async function qualitySource(spec, lock) {
     if (spec.generator === "frames") {
       return { items: null, reason: "frame-set quality requires ordered downloaded provider outputs" };
     }
-    const source = path7.resolve(spec.root, spec.source);
-    return existsSync4(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
+    const source = path6.resolve(spec.root, spec.source);
+    return existsSync3(source) ? { items: [{ role: "source", path: source }] } : { items: null, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
   if (!entry) return { items: null, reason: "raw provider output is not in the lockfile" };
@@ -3009,7 +2980,7 @@ async function qualitySource(spec, lock) {
     }
     if (role) roles.add(role);
     const source = currentEntryOutputPath(entry, spec, index);
-    if (!existsSync4(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
+    if (!existsSync3(source)) return { items: null, reason: `raw provider output is missing: ${source}` };
     if (await sha256File(source) !== output.sha256) {
       return { items: null, reason: "raw provider output was modified after download" };
     }
@@ -3028,7 +2999,7 @@ async function inspectQualityProfile(spec, lock) {
   }
   const sourcePaths = source.items.map((item) => item.path);
   const expectedOutputs = spec.generator === "frames" ? source.items.map((item, index) => qualityFrameOutputPath(output, item.role, index)) : [output];
-  if (!existsSync4(record)) {
+  if (!existsSync3(record)) {
     return {
       key,
       state: "needs-refinement",
@@ -3046,7 +3017,7 @@ async function inspectQualityProfile(spec, lock) {
     const expectedRevision = spec.quality.fixerRevision ?? PIXEL_ART_FIXER_REVISION;
     const expectedTransparency = spec.quality.minTransparency ?? null;
     const expectedFrameSet = spec.generator === "frames" ? { fps: spec.quality.fps ?? 12, count: source.items.length, roles: source.items.map((item) => item.role) } : null;
-    const contractChanged = JSON.stringify(check.sources.map((item) => path7.resolve(item))) !== JSON.stringify(sourcePaths.map((item) => path7.resolve(item))) || JSON.stringify(check.outputs.map((item) => path7.resolve(item))) !== JSON.stringify(expectedOutputs.map((item) => path7.resolve(item))) || JSON.stringify(check.options.palette.colors) !== JSON.stringify(expectedPalette) || check.options.nativeGrid.revision !== expectedRevision || check.options.audit.thresholds.minGridConfidence !== spec.quality.minGridConfidence || check.options.audit.thresholds.minTransparency !== expectedTransparency || (expectedFrameSet ? !check.options.frameSet || check.options.frameSet.fps !== expectedFrameSet.fps || check.options.frameSet.count !== expectedFrameSet.count || JSON.stringify(check.options.frameSet.roles) !== JSON.stringify(expectedFrameSet.roles) : check.options.frameSet !== void 0);
+    const contractChanged = JSON.stringify(check.sources.map((item) => path6.resolve(item))) !== JSON.stringify(sourcePaths.map((item) => path6.resolve(item))) || JSON.stringify(check.outputs.map((item) => path6.resolve(item))) !== JSON.stringify(expectedOutputs.map((item) => path6.resolve(item))) || JSON.stringify(check.options.palette.colors) !== JSON.stringify(expectedPalette) || check.options.nativeGrid.revision !== expectedRevision || check.options.audit.thresholds.minGridConfidence !== spec.quality.minGridConfidence || check.options.audit.thresholds.minTransparency !== expectedTransparency || (expectedFrameSet ? !check.options.frameSet || check.options.frameSet.fps !== expectedFrameSet.fps || check.options.frameSet.count !== expectedFrameSet.count || JSON.stringify(check.options.frameSet.roles) !== JSON.stringify(expectedFrameSet.roles) : check.options.frameSet !== void 0);
     if (contractChanged) {
       return {
         key,
@@ -3208,9 +3179,38 @@ async function requireApprovedQualitySources(specs, lock, assetIds, outputRoles)
   return sources;
 }
 
+// src/pipeline/postprocess.ts
+function postprocessFor(spec) {
+  if (!spec.enforcePalette || spec.palette.length < 2) return void 0;
+  return {
+    palette: {
+      colors: normalizePalette(spec.palette).map((color) => color.hex),
+      dither: "none",
+      distance: "redmean"
+    }
+  };
+}
+function samePostprocess(a, b) {
+  const pa = a?.palette;
+  const pb = b?.palette;
+  if (!pa && !pb) return true;
+  if (!pa || !pb) return false;
+  return pa.dither === pb.dither && pa.distance === pb.distance && pa.colors.length === pb.colors.length && pa.colors.every((color, i) => color === pb.colors[i]);
+}
+function postprocessCurrent(entry, spec) {
+  return samePostprocess(entry.postprocess, postprocessFor(spec));
+}
+function applyPostprocess(bytes, mediaType, record) {
+  if (!record?.palette || mediaType !== MediaType.PNG) return { bytes, changed: false };
+  const png = decodePng(bytes);
+  const { png: snapped, changed } = quantize(png, record.palette.colors);
+  if (!changed) return { bytes, changed: false };
+  return { bytes: encodeRgbaPng(snapped.width, snapped.height, snapped.pixels), changed: true };
+}
+
 // src/pipeline/revision.ts
-import { existsSync as existsSync5 } from "fs";
-import path8 from "path";
+import { existsSync as existsSync4 } from "fs";
+import path7 from "path";
 async function inspectRevisionReadiness(spec, lock) {
   if (!spec.revision) return null;
   return inspectRevision(spec, lock, /* @__PURE__ */ new Set());
@@ -3225,14 +3225,14 @@ async function inspectRevision(spec, lock, seen) {
       reason: `revision source ${spec.styleId}/${revision.sourceAssetId} is not ready: ${dependency.reason}`
     };
   }
-  if (!revision.sourceSha256 || !existsSync5(revision.sourceFile)) {
+  if (!revision.sourceSha256 || !existsSync4(revision.sourceFile)) {
     return { ready: false, reason: `revision source is missing: ${revision.sourceFile}` };
   }
   if (await sha256File(revision.sourceFile) !== revision.sourceSha256) {
     return { ready: false, reason: "revision source changed after the manifest was resolved" };
   }
   if (revision.maskFile) {
-    if (!revision.maskSha256 || !existsSync5(revision.maskFile)) {
+    if (!revision.maskSha256 || !existsSync4(revision.maskFile)) {
       return { ready: false, reason: `revision mask is missing: ${revision.maskFile}` };
     }
     if (await sha256File(revision.maskFile) !== revision.maskSha256) {
@@ -3262,8 +3262,8 @@ async function inspectParent(spec, lock, seen) {
     };
   }
   if (spec.source) {
-    const source = path8.resolve(spec.root, spec.source);
-    return existsSync5(source) ? { ready: true, reason: "declared source is present" } : { ready: false, reason: `declared source is missing: ${spec.source}` };
+    const source = path7.resolve(spec.root, spec.source);
+    return existsSync4(source) ? { ready: true, reason: "declared source is present" } : { ready: false, reason: `declared source is missing: ${spec.source}` };
   }
   const entry = lock.entries[key];
   if (!entry) return { ready: false, reason: "parent is not in the lockfile" };
@@ -3277,7 +3277,7 @@ async function inspectParent(spec, lock, seen) {
   for (let index = 0; index < entry.outputs.length; index++) {
     const output = entry.outputs[index];
     const file = currentEntryOutputPath(entry, spec, index);
-    if (!existsSync5(file)) return { ready: false, reason: `parent output is missing: ${file}` };
+    if (!existsSync4(file)) return { ready: false, reason: `parent output is missing: ${file}` };
     if (await sha256File(file) !== output.sha256) {
       return { ready: false, reason: `parent output was modified: ${file}` };
     }
@@ -3306,7 +3306,7 @@ function resumeActions(specs, lock) {
     const entry = lock.entries[key];
     if (!entry || entry.specHash !== spec.specHash) continue;
     if (entry.submissionComplete === false) continue;
-    const command = resumeCommandForStatus(entry.status);
+    const command = resumeCommandForStatus(entry.status) ?? (entry.status === "downloaded" && entry.outputs.length && !postprocessCurrent(entry, spec) ? "fetch" : null);
     if (!command) continue;
     if (command === "poll" && !entry.jobId) continue;
     if (command === "pick" && !entry.reviewObjectId) continue;
@@ -3332,7 +3332,7 @@ async function buildPlan(specs, lock, opts = {}) {
       state = "missing";
       reason = "--force";
     } else if (!entry && spec.source && spec.generator !== "frames") {
-      if (existsSync6(path9.resolve(spec.root, spec.source))) {
+      if (existsSync5(path8.resolve(spec.root, spec.source))) {
         state = "ok";
         reason = `placed from ${spec.source}; not generated`;
       } else {
@@ -3340,7 +3340,7 @@ async function buildPlan(specs, lock, opts = {}) {
         reason = `declared source is missing: ${spec.source}`;
       }
     } else if (!entry) {
-      if (existsSync6(spec.outFile)) {
+      if (existsSync5(spec.outFile)) {
         state = "untracked";
         reason = "file on disk, no provenance recorded";
       } else {
@@ -3372,12 +3372,15 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (entry.status !== "downloaded") {
       state = "in-flight";
       reason = `awaiting ${entry.status}`;
-    } else if (entry.outputs.length === 0 || entry.outputs.some((_output, index) => !existsSync6(currentEntryOutputPath(entry, spec, index)))) {
+    } else if (entry.outputs.length === 0 || entry.outputs.some((_output, index) => !existsSync5(currentEntryOutputPath(entry, spec, index)))) {
       state = "orphaned";
-      reason = entry.outputs.length === 0 ? "no recorded output files" : `missing on disk: ${entry.outputs.filter((_output, index) => !existsSync6(currentEntryOutputPath(entry, spec, index))).map((o) => o.role ?? "asset").join(", ")}`;
+      reason = entry.outputs.length === 0 ? "no recorded output files" : `missing on disk: ${entry.outputs.filter((_output, index) => !existsSync5(currentEntryOutputPath(entry, spec, index))).map((o) => o.role ?? "asset").join(", ")}`;
     } else if (await anyOutputModified(entry, spec)) {
       state = "orphaned";
       reason = "output modified since download";
+    } else if (!postprocessCurrent(entry, spec)) {
+      state = "recoverable";
+      reason = spec.enforcePalette ? "palette enforcement turned on; run pixelkiln fetch to snap the file (no generation cost)" : "palette enforcement turned off; run pixelkiln fetch to restore the provider's bytes (no generation cost)";
     } else {
       state = "ok";
       reason = "up to date";
@@ -3537,12 +3540,12 @@ async function confirm(question, auto) {
 }
 
 // src/cli/commands/account.ts
-import path21 from "path";
-import { existsSync as existsSync16 } from "fs";
+import path20 from "path";
+import { existsSync as existsSync15 } from "fs";
 
 // src/env.ts
-import { readFileSync, existsSync as existsSync7 } from "fs";
-import path10 from "path";
+import { readFileSync, existsSync as existsSync6 } from "fs";
+import path9 from "path";
 function loadEnvFiles(dir) {
   const loaded = [];
   for (const [file, vars] of envFiles(dir)) {
@@ -3565,8 +3568,8 @@ function readEnvFiles(dir) {
 function envFiles(dir) {
   const out = [];
   for (const name of [".env.local", ".env"]) {
-    const file = path10.join(dir, name);
-    if (!existsSync7(file)) continue;
+    const file = path9.join(dir, name);
+    if (!existsSync6(file)) continue;
     try {
       out.push([file, parseEnv(readFileSync(file, "utf8"))]);
     } catch {
@@ -3595,8 +3598,8 @@ function parseEnv(contents) {
 
 // src/providers/comfyui.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { readFile as readFile5 } from "fs/promises";
-import path11 from "path";
+import { readFile as readFile4 } from "fs/promises";
+import path10 from "path";
 
 // src/http.ts
 var MAX_RETRIES = 4;
@@ -3706,8 +3709,10 @@ var ComfyUIClient = class {
       value = null;
     }
     if (!response.ok) {
-      throw new Error(
-        `ComfyUI image upload failed (${response.status})` + (apiError(value) ? `: ${apiError(value)}` : "")
+      throw new ProviderError(
+        "comfyui",
+        `ComfyUI image upload failed (${response.status})` + (apiError(value) ? `: ${apiError(value)}` : ""),
+        { status: response.status }
       );
     }
     if (!isObject(value) || typeof value.name !== "string" || !value.name) {
@@ -3730,7 +3735,7 @@ var ComfyUIClient = class {
     let target = source;
     if (source.startsWith("comfyui://")) target = this.viewUrl(parseSource(source));
     const response = await this.request(target);
-    if (!response.ok) throw new Error(`ComfyUI download failed (${response.status})`);
+    if (!response.ok) throw new ProviderError("comfyui", `ComfyUI download failed (${response.status})`, { status: response.status });
     return Buffer.from(await response.arrayBuffer());
   }
   endpoint(route) {
@@ -3755,8 +3760,10 @@ var ComfyUIClient = class {
     }
     if (!response.ok) {
       const detail = apiError(value);
-      throw new Error(
-        `ComfyUI request failed (${response.status}) at ${url.pathname}` + (detail ? `: ${detail}` : "")
+      throw new ProviderError(
+        "comfyui",
+        `ComfyUI request failed (${response.status}) at ${url.pathname}` + (detail ? `: ${detail}` : ""),
+        { status: response.status }
       );
     }
     return value;
@@ -3779,10 +3786,10 @@ var ComfyUIProvider = class _ComfyUIProvider {
   }
   async resolveOptions(value, context) {
     const options = parseOptions(value);
-    const workflowPath = path11.resolve(context.root, options.workflowFile);
+    const workflowPath = path10.resolve(context.root, options.workflowFile);
     let raw;
     try {
-      raw = await readFile5(workflowPath, "utf8");
+      raw = await readFile4(workflowPath, "utf8");
     } catch (err) {
       throw new Error(
         `ComfyUI workflow for style "${context.styleId}" could not be read at ${workflowPath}: ${err instanceof Error ? err.message : String(err)}`
@@ -3834,10 +3841,10 @@ var ComfyUIProvider = class _ComfyUIProvider {
           if (typeof item !== "string") {
             throw new Error(`ComfyUI ${label} must be a manifest-relative PNG or JPEG path`);
           }
-          const file = path11.resolve(context.root, item);
+          const file = path10.resolve(context.root, item);
           let bytes;
           try {
-            bytes = await readFile5(file);
+            bytes = await readFile4(file);
           } catch (error) {
             throw new Error(
               `ComfyUI ${label} could not be read at ${file}: ${error instanceof Error ? error.message : String(error)}`
@@ -3969,7 +3976,7 @@ var ComfyUIProvider = class _ComfyUIProvider {
         setBinding(workflow2, binding, input);
         return;
       }
-      const bytes = await readFile5(input.path);
+      const bytes = await readFile4(input.path);
       if (sha256(bytes) !== input.sha256) {
         throw new Error(`ComfyUI provider input "${name}" changed before upload`);
       }
@@ -4036,7 +4043,7 @@ var ComfyUIProvider = class _ComfyUIProvider {
       if (!spec.revision.sourceSha256 || !spec.revision.sourceFormat) {
         throw new Error("ComfyUI revision source is not ready");
       }
-      const sourceBytes = await readFile5(spec.revision.sourceFile);
+      const sourceBytes = await readFile4(spec.revision.sourceFile);
       if (sha256(sourceBytes) !== spec.revision.sourceSha256) {
         throw new Error("ComfyUI revision source changed before upload");
       }
@@ -4050,7 +4057,7 @@ var ComfyUIProvider = class _ComfyUIProvider {
         if (!spec.revision.maskSha256 || !spec.revision.maskFormat) {
           throw new Error("ComfyUI revision mask is not ready");
         }
-        const maskBytes = await readFile5(spec.revision.maskFile);
+        const maskBytes = await readFile4(spec.revision.maskFile);
         if (sha256(maskBytes) !== spec.revision.maskSha256) {
           throw new Error("ComfyUI revision mask changed before upload");
         }
@@ -4521,10 +4528,10 @@ function canonical2(value) {
 }
 
 // src/providers/pixellab.ts
-import { mkdirSync, existsSync as existsSync8, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { mkdirSync, existsSync as existsSync7, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { randomUUID as randomUUID3 } from "crypto";
 import os from "os";
-import path12 from "path";
+import path11 from "path";
 
 // src/client.ts
 import { z as z2 } from "zod";
@@ -4592,14 +4599,12 @@ function validateResponse(schema, raw, operation) {
   const issues = parsed.error.issues.slice(0, 4).map((i) => `${i.path.join(".") || "response"}: ${i.message}`).join("; ");
   throw new Error(`Invalid PixelLab response for ${operation}: ${issues}`);
 }
-var PixelLabError = class extends Error {
+var PixelLabError = class extends ProviderError {
   constructor(message6, status, body) {
-    super(message6);
-    this.status = status;
+    super("pixellab", message6, { status });
     this.body = body;
     this.name = "PixelLabError";
   }
-  status;
   body;
 };
 var PixelLabClient = class {
@@ -4878,7 +4883,7 @@ var PixelLabProvider = class _PixelLabProvider {
    * filename, polling is an existence check, and downloading is a file read.
    */
   static cacheDir() {
-    const dir = path12.join(os.tmpdir(), "pixelkiln-pixflux");
+    const dir = path11.join(os.tmpdir(), "pixelkiln-pixflux");
     mkdirSync(dir, { recursive: true });
     return dir;
   }
@@ -4947,7 +4952,7 @@ var PixelLabProvider = class _PixelLabProvider {
         seed: spec.seed
       });
       const jobId = randomUUID3();
-      writeFileSync(path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), png);
+      writeFileSync(path11.join(_PixelLabProvider.cacheDir(), `${jobId}.png`), png);
       return { jobId };
     }
     if (spec.generator === "tiles") {
@@ -4988,8 +4993,8 @@ var PixelLabProvider = class _PixelLabProvider {
   }
   async poll(jobId, generator, context) {
     if (generator === "pixflux") {
-      const file = path12.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
-      if (existsSync8(file)) {
+      const file = path11.join(_PixelLabProvider.cacheDir(), `${jobId}.png`);
+      if (existsSync7(file)) {
         const sourceUrl = `file://${file}`;
         return { status: "ready", objectId: jobId, sourceUrl, sources: [{ url: sourceUrl }] };
       }
@@ -5180,7 +5185,7 @@ var RetroDiffusionClient = class {
   /** Result URLs are signed; no token header, and the same retry policy as the API. */
   async download(url) {
     const response = await this.request(url);
-    if (!response.ok) throw new Error(`Retro Diffusion download failed (${response.status})`);
+    if (!response.ok) throw new ProviderError("retrodiffusion", `Retro Diffusion download failed (${response.status})`, { status: response.status });
     return Buffer.from(await response.arrayBuffer());
   }
   async call(path43, init = {}) {
@@ -5203,8 +5208,10 @@ var RetroDiffusionClient = class {
     if (!response.ok) {
       const retry = response.headers.get("retry-after");
       const detail = retroError(value);
-      throw new Error(
-        `Retro Diffusion request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : "")
+      throw new ProviderError(
+        "retrodiffusion",
+        `Retro Diffusion request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : ""),
+        { status: response.status }
       );
     }
     return value;
@@ -5596,7 +5603,7 @@ var ScenarioClient = class {
       throw new Error("Scenario downloads must use HTTP or HTTPS");
     }
     const response = await this.request(parsed);
-    if (!response.ok) throw new Error(`Scenario download failed (${response.status})`);
+    if (!response.ok) throw new ProviderError("scenario", `Scenario download failed (${response.status})`, { status: response.status });
     const declared = Number(response.headers.get("content-length"));
     if (Number.isFinite(declared) && declared > MAX_DOWNLOAD_BYTES) {
       throw new Error(`Scenario download exceeds the ${MAX_DOWNLOAD_BYTES}-byte safety limit`);
@@ -5643,8 +5650,10 @@ var ScenarioClient = class {
     if (!response.ok) {
       const retry = response.headers.get("retry-after");
       const detail = redactScenarioError(value, [this.apiKey, this.apiSecret, auth]);
-      throw new Error(
-        `Scenario request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : "")
+      throw new ProviderError(
+        "scenario",
+        `Scenario request failed (${response.status}): ${detail}` + (retry ? `; retry after ${retry}s` : ""),
+        { status: response.status }
       );
     }
     return value;
@@ -6038,23 +6047,23 @@ registerProvider({
 });
 
 // src/manifest.ts
-import { readFile as readFile6 } from "fs/promises";
-import { existsSync as existsSync9 } from "fs";
-import path13 from "path";
+import { readFile as readFile5 } from "fs/promises";
+import { existsSync as existsSync8 } from "fs";
+import path12 from "path";
 async function loadManifest(manifestPath) {
-  const abs = path13.resolve(manifestPath);
-  if (!existsSync9(abs)) throw new Error(`No manifest at ${abs}`);
-  const input = ManifestInputSchema.safeParse(JSON.parse(await readFile6(abs, "utf8")));
+  const abs = path12.resolve(manifestPath);
+  if (!existsSync8(abs)) throw new ProjectError(`No manifest at ${abs}`);
+  const input = ManifestInputSchema.safeParse(JSON.parse(await readFile5(abs, "utf8")));
   if (!input.success) {
     const issues = formatManifestIssues(input.error.issues);
-    throw new Error(`Manifest at ${abs} is invalid:
+    throw new ProjectError(`Manifest at ${abs} is invalid:
 ${issues}`);
   }
   let styles;
   try {
     styles = resolveStyleInheritance(input.data.styles);
   } catch (error) {
-    throw new Error(
+    throw new ProjectError(
       `Manifest at ${abs} is invalid:
   ${error instanceof Error ? error.message : String(error)}`
     );
@@ -6062,7 +6071,7 @@ ${issues}`);
   const parsed = ManifestSchema.safeParse({ ...input.data, styles });
   if (!parsed.success) {
     const issues = formatManifestIssues(parsed.error.issues);
-    throw new Error(`Manifest at ${abs} is invalid:
+    throw new ProjectError(`Manifest at ${abs} is invalid:
 ${issues}`);
   }
   const styleIds = new Set(Object.keys(parsed.data.styles));
@@ -6112,10 +6121,10 @@ ${issues}`);
   };
   for (const assetId of Object.keys(parsed.data.assets)) visitRevision(assetId, []);
   if (unknownReferences.length) {
-    throw new Error(`Manifest at ${abs} is invalid:
+    throw new ProjectError(`Manifest at ${abs} is invalid:
 ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
   }
-  return { manifest: parsed.data, root: path13.dirname(abs), path: abs };
+  return { manifest: parsed.data, root: path12.dirname(abs), path: abs };
 }
 function formatManifestIssues(issues) {
   return issues.flatMap((issue) => {
@@ -6191,14 +6200,14 @@ async function resolveSpecs(loaded, filter) {
   );
   for (const unknownStyle of filter?.styles ?? []) {
     if (!manifest.styles[unknownStyle]) {
-      throw new Error(
+      throw new UsageError(
         `Unknown style "${unknownStyle}". Defined: ${Object.keys(manifest.styles).join(", ") || "(none)"}`
       );
     }
   }
   for (const unknownAsset of filter?.assets ?? []) {
     if (!manifest.assets[unknownAsset]) {
-      throw new Error(`Unknown asset "${unknownAsset}".`);
+      throw new UsageError(`Unknown asset "${unknownAsset}".`);
     }
   }
   const requestedAssetIds = new Set(filter?.assets?.length ? filter.assets : Object.keys(manifest.assets));
@@ -6212,11 +6221,11 @@ async function resolveSpecs(loaded, filter) {
   }
   const styleImageCache = /* @__PURE__ */ new Map();
   async function loadStyleImage(rel) {
-    const abs = path13.resolve(root, rel);
+    const abs = path12.resolve(root, rel);
     let hit = styleImageCache.get(abs);
     if (!hit) {
-      if (!existsSync9(abs)) throw new Error(`Style image not found: ${abs}`);
-      const buf = await readFile6(abs);
+      if (!existsSync8(abs)) throw new Error(`Style image not found: ${abs}`);
+      const buf = await readFile5(abs);
       const metadata = imageMetadata(buf);
       if (!metadata) throw new Error(`Style image is not a readable PNG or JPEG: ${abs}`);
       if (metadata.width < 1 || metadata.height < 1) {
@@ -6242,7 +6251,7 @@ async function resolveSpecs(loaded, filter) {
       styleImageDimensions.push(loadedImage);
     }
     const resolvedImages = style.styleImages.map((image) => {
-      const hit = styleImageCache.get(path13.resolve(root, image.path));
+      const hit = styleImageCache.get(path12.resolve(root, image.path));
       return { base64: hit.base64, width: hit.width, height: hit.height, format: hit.format };
     });
     const styleSpecs = /* @__PURE__ */ new Map();
@@ -6287,9 +6296,9 @@ async function resolveSpecs(loaded, filter) {
       }
       const subject = asset.promptByStyle[styleId] ?? asset.prompt;
       const prompt = [style.promptPrefix, subject, style.promptSuffix].map((p) => p.trim()).filter(Boolean).join(", ");
-      const relFile = asset.file ?? path13.join(asset.category ?? "", `${assetId}.png`);
-      const outFile = path13.resolve(root, style.outDir, relFile);
-      const qualityOutFile = style.quality ? path13.resolve(root, style.quality.outDir, pngPath(relFile)) : void 0;
+      const relFile = asset.file ?? path12.join(asset.category ?? "", `${assetId}.png`);
+      const outFile = path12.resolve(root, style.outDir, relFile);
+      const qualityOutFile = style.quality ? path12.resolve(root, style.quality.outDir, pngPath(relFile)) : void 0;
       const tileSize = generator === "tiles" ? size : style.tileSize ?? 32;
       const tileVariations = tileFeatureOutputCount(generator === "tiles" ? style.tileFeature : void 0) ?? tileVariationCount(countNumberedDescriptions(prompt));
       const base = {
@@ -6310,6 +6319,7 @@ async function resolveSpecs(loaded, filter) {
         detail: style.detail,
         seed: style.seed,
         palette: style.palette,
+        enforcePalette: style.enforcePalette,
         noBackground: style.noBackground,
         tileSize: generator === "tiles" ? tileSize : void 0,
         tileType: generator === "tiles" ? style.tileType : void 0,
@@ -6340,7 +6350,7 @@ async function resolveSpecs(loaded, filter) {
             minGridConfidence: style.quality.minGridConfidence,
             ...style.quality.minTransparency == null ? {} : { minTransparency: style.quality.minTransparency },
             ...style.quality.fixerRevision ? { fixerRevision: style.quality.fixerRevision } : {},
-            ...style.quality.fixerPython ? { fixerPython: path13.resolve(root, style.quality.fixerPython) } : {},
+            ...style.quality.fixerPython ? { fixerPython: path12.resolve(root, style.quality.fixerPython) } : {},
             ...style.quality.fps == null ? {} : { fps: style.quality.fps }
           }
         } : {},
@@ -6369,9 +6379,9 @@ async function resolveSpecs(loaded, filter) {
           );
         }
         const sourceSpec = await finalize(asset.revision.from);
-        const sourceFile = sourceSpec.quality?.outFile ?? (sourceSpec.source ? path13.resolve(root, sourceSpec.source) : sourceSpec.outFile);
+        const sourceFile = sourceSpec.quality?.outFile ?? (sourceSpec.source ? path12.resolve(root, sourceSpec.source) : sourceSpec.outFile);
         const sourceImage = await optionalRevisionImage(sourceFile, "revision source");
-        const maskFile = asset.revision.mask ? path13.resolve(root, asset.revision.mask) : void 0;
+        const maskFile = asset.revision.mask ? path12.resolve(root, asset.revision.mask) : void 0;
         const maskImage = maskFile ? await optionalRevisionImage(maskFile, "revision mask", "png") : null;
         if (sourceImage && maskImage && (sourceImage.width !== maskImage.width || sourceImage.height !== maskImage.height)) {
           throw new Error(
@@ -6452,12 +6462,12 @@ async function resolveSpecs(loaded, filter) {
   return specs;
 }
 function pngPath(file) {
-  const extension = path13.extname(file);
+  const extension = path12.extname(file);
   return extension ? `${file.slice(0, -extension.length)}.png` : `${file}.png`;
 }
 async function optionalRevisionImage(file, label, requiredFormat) {
-  if (!existsSync9(file)) return null;
-  const bytes = await readFile6(file);
+  if (!existsSync8(file)) return null;
+  const bytes = await readFile5(file);
   const metadata = imageMetadata(bytes);
   if (!metadata) throw new Error(`${label} is not a readable PNG or JPEG: ${file}`);
   if (requiredFormat && metadata.format !== requiredFormat) {
@@ -6470,8 +6480,8 @@ async function resolveStyleImages(loaded, styleId) {
   if (!style) throw new Error(`Unknown style "${styleId}"`);
   const out = [];
   for (const img of style.styleImages) {
-    const file = path13.resolve(loaded.root, img.path);
-    const buf = await readFile6(file);
+    const file = path12.resolve(loaded.root, img.path);
+    const buf = await readFile5(file);
     const metadata = imageMetadata(buf);
     if (!metadata) throw new Error(`Style image is not a readable PNG or JPEG: ${file}`);
     if (metadata.width < 1 || metadata.height < 1) {
@@ -6511,9 +6521,9 @@ function imageMetadata(buf) {
 }
 
 // src/pipeline/fetch.ts
-import { existsSync as existsSync10, readFileSync as readFileSync3 } from "fs";
-import { mkdir as mkdir3, readFile as readFile7, rename as rename3, rm as rm4, writeFile as writeFile3 } from "fs/promises";
-import path14 from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync3 } from "fs";
+import { mkdir as mkdir3, readFile as readFile6, rename as rename3, rm as rm4, writeFile as writeFile3 } from "fs/promises";
+import path13 from "path";
 
 // src/source-url.ts
 var SENSITIVE_QUERY_KEYS = /* @__PURE__ */ new Set([
@@ -6559,18 +6569,24 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   const result = { downloaded: 0, skipped: 0, failed: 0, ...opts.refresh ? { unchanged: 0 } : {} };
   const specByKey = new Map(specs.map((s) => [lockKey(s.styleId, s.assetId), s]));
   normalizeLockOutputPaths(lock, specs);
-  const cacheDir = opts.cacheDir === false ? null : path14.resolve(opts.cacheDir ?? path14.join(path14.dirname(lockPath), ".pixelkiln", "cache"));
+  const cacheDir = opts.cacheDir === false ? null : path13.resolve(opts.cacheDir ?? path13.join(path13.dirname(lockPath), ".pixelkiln", "cache"));
   const pending = Object.entries(lock.entries).filter(([key, e]) => {
     if (e.provider !== provider.id || !specByKey.has(key)) return false;
     if (e.status === "selected" || e.status === "download-failed") return true;
     if (e.status !== "downloaded") return false;
     if (opts.refresh) return e.outputs.length > 0 && Boolean(e.sourceUrls?.length || e.sourceUrl);
-    if (!opts.repair) return false;
     const spec = specByKey.get(key);
+    if (spec && e.specHash === spec.specHash && e.outputs.length && !postprocessCurrent(e, spec)) {
+      return Boolean(opts.force) || e.outputs.every((output) => {
+        const file = resolveOutputPath(output.path, spec.root);
+        return existsSync9(file) && sha256(readFileSync3(file)) === output.sha256;
+      });
+    }
+    if (!opts.repair) return false;
     if (e.outputs.length === 0 || !spec) return true;
     return e.outputs.some((output) => {
       const file = resolveOutputPath(output.path, spec.root);
-      if (!existsSync10(file)) return true;
+      if (!existsSync9(file)) return true;
       const current = sha256(readFileSync3(file));
       if (current === output.sha256) return false;
       return Boolean(opts.force) || (e.supersededOutputs ?? []).some((old) => old.sha256 === current);
@@ -6605,6 +6621,8 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
       }
       const outputs = [];
       let wrote = false;
+      const wanted = postprocessFor(spec);
+      const reapply = entry.status === "downloaded" && !postprocessCurrent(entry, spec);
       try {
         for (let index = 0; index < sources.length; index++) {
           const source = sources[index];
@@ -6612,24 +6630,28 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             (o) => source.role ? o.role === source.role : !o.role && sources.length === 1
           );
           const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length, source.mediaType);
+          const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
+          const recordedRaw = recorded?.raw ?? recorded?.sha256;
           let fresh = null;
           if (opts.refresh) {
             if (!source.url) throw new Error(`no durable source URL to refresh ${source.role ?? "asset"} from`);
             fresh = await provider.download(source.url);
-            if (recorded && sha256(fresh) === recorded.sha256) {
-              log2(`  current ${path14.relative(process.cwd(), target)}`);
+            if (recorded && sha256(fresh) === recordedRaw && !reapply) {
+              log2(`  current ${path13.relative(process.cwd(), target)}`);
               outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
               continue;
             }
           }
-          if (existsSync10(target)) {
+          let raw = null;
+          let final = null;
+          if (existsSync9(target)) {
             const currentHash = await sha256File(target);
             if (recorded && currentHash === recorded.sha256) {
-              if (!fresh) {
+              if (!fresh && !reapply) {
                 if (cacheDir) {
                   await cacheMedia(
                     cacheDir,
-                    await readFile7(target),
+                    await readFile6(target),
                     recorded.mediaType ?? MediaType.PNG,
                     recorded.sha256
                   );
@@ -6637,7 +6659,12 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
                 outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
                 continue;
               }
-              log2(`  changed ${path14.relative(process.cwd(), target)} (upstream)`);
+              if (reapply && !fresh) {
+                if (!recorded.raw) raw = await readFile6(target);
+                log2(`  reapply ${path13.relative(process.cwd(), target)}`);
+              } else {
+                log2(`  changed ${path13.relative(process.cwd(), target)} (upstream)`);
+              }
             } else {
               const superseded = (entry.supersededOutputs ?? []).find(
                 (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
@@ -6655,45 +6682,61 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
                 }
               }
               log2(
-                `  replace ${path14.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
+                `  replace ${path13.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
               );
             }
           }
-          const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
-          let buf = fresh ?? (recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null);
-          if (buf) {
-            log2(`  cached  ${path14.relative(process.cwd(), target)}`);
-          } else {
+          if (fresh) {
+            raw = fresh;
+          } else if (!raw && recorded && cacheDir) {
+            if (!reapply) final = await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType);
+            if (!final && recordedRaw) raw = await readCachedMedia(cacheDir, recordedRaw, expectedMediaType);
+            if (final || raw) log2(`  cached  ${path13.relative(process.cwd(), target)}`);
+          }
+          if (!final && !raw) {
             if (!source.url) {
               throw new Error(`no source URL or cached bytes remain for ${source.role ?? "asset"}`);
             }
-            buf = await provider.download(source.url);
+            raw = await provider.download(source.url);
           }
           let mediaType;
+          const bytes = final ?? raw;
           try {
-            mediaType = validateMedia(buf, expectedMediaType);
+            mediaType = validateMedia(bytes, expectedMediaType);
           } catch (err) {
             const label = expectedMediaType === MediaType.GIF ? "GIF" : "PNG";
-            const mismatch = detectMediaType(buf) !== expectedMediaType;
+            const mismatch = detectMediaType(bytes) !== expectedMediaType;
             throw new Error(
-              `response for ${source.role ?? "asset"} was not ${mismatch ? "a" : "a valid"} ${label}` + (mismatch ? ` (${buf.length} bytes)` : `: ${err instanceof Error ? err.message : String(err)}`)
+              `response for ${source.role ?? "asset"} was not ${mismatch ? "a" : "a valid"} ${label}` + (mismatch ? ` (${bytes.length} bytes)` : `: ${err instanceof Error ? err.message : String(err)}`)
             );
           }
+          let rawHash = final ? recorded?.raw : void 0;
+          let buf = bytes;
+          if (!final) {
+            if (cacheDir) await cacheMedia(cacheDir, raw, mediaType);
+            const processed = applyPostprocess(raw, mediaType, wanted);
+            buf = processed.bytes;
+            if (processed.changed) {
+              rawHash = sha256(raw);
+              log2(`  snapped ${path13.relative(process.cwd(), target)} to ${wanted.palette.colors.length} colours`);
+            }
+          }
           if (cacheDir) await cacheMedia(cacheDir, buf, mediaType);
-          await mkdir3(path14.dirname(target), { recursive: true });
+          await mkdir3(path13.dirname(target), { recursive: true });
           const tmp = `${target}.pixelkiln.tmp`;
           await writeFile3(tmp, buf);
           outputs.push({
             path: portableOutputPath(target, spec.root),
             sha256: sha256(buf),
             ...source.role ? { role: source.role } : {},
-            mediaType
+            mediaType,
+            ...rawHash ? { raw: rawHash } : {}
           });
           upsert(lock, key, { outputs: mergeOutputs(entry.outputs, outputs) });
           await saveLock(lockPath, lock);
           await rename3(tmp, target);
           wrote = true;
-          log2(`  wrote   ${path14.relative(process.cwd(), target)}`);
+          log2(`  wrote   ${path13.relative(process.cwd(), target)}`);
         }
         if (opts.refresh && !wrote) {
           result.unchanged = (result.unchanged ?? 0) + 1;
@@ -6711,7 +6754,8 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           sourceUrls: persistentSources,
           downloadedAt: (/* @__PURE__ */ new Date()).toISOString(),
           error: null,
-          supersededOutputs: []
+          supersededOutputs: [],
+          postprocess: wanted
         });
         result.downloaded++;
       } catch (err) {
@@ -6732,10 +6776,10 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   return result;
 }
 async function readCachedMedia(cacheDir, hash, mediaType) {
-  const file = path14.join(cacheDir, cacheFileName(hash, mediaType));
-  if (!existsSync10(file)) return null;
+  const file = path13.join(cacheDir, cacheFileName(hash, mediaType));
+  if (!existsSync9(file)) return null;
   try {
-    const buf = await readFile7(file);
+    const buf = await readFile6(file);
     if (sha256(buf) !== hash) return null;
     validateMedia(buf, mediaType);
     return buf;
@@ -6746,7 +6790,7 @@ async function readCachedMedia(cacheDir, hash, mediaType) {
 async function cacheMedia(cacheDir, buf, mediaType, knownHash) {
   const hash = knownHash ?? sha256(buf);
   validateMedia(buf, mediaType);
-  const file = path14.join(cacheDir, cacheFileName(hash, mediaType));
+  const file = path13.join(cacheDir, cacheFileName(hash, mediaType));
   if (await readCachedMedia(cacheDir, hash, mediaType)) return;
   await mkdir3(cacheDir, { recursive: true });
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
@@ -6754,7 +6798,7 @@ async function cacheMedia(cacheDir, buf, mediaType, knownHash) {
   try {
     await rename3(tmp, file);
   } catch (err) {
-    if (!existsSync10(file)) throw err;
+    if (!existsSync9(file)) throw err;
   } finally {
     await rm4(tmp, { force: true });
   }
@@ -6787,13 +6831,13 @@ async function pushTags(provider, specs, lock, opts = {}) {
 }
 
 // src/pipeline/adopt.ts
-import { existsSync as existsSync12 } from "fs";
-import { readFile as readFile9, writeFile as writeFile5 } from "fs/promises";
-import path15 from "path";
+import { existsSync as existsSync11 } from "fs";
+import { readFile as readFile8, writeFile as writeFile5 } from "fs/promises";
+import path14 from "path";
 
 // src/cache.ts
-import { mkdir as mkdir4, readFile as readFile8, rename as rename4, rm as rm5, writeFile as writeFile4 } from "fs/promises";
-import { existsSync as existsSync11 } from "fs";
+import { mkdir as mkdir4, readFile as readFile7, rename as rename4, rm as rm5, writeFile as writeFile4 } from "fs/promises";
+import { existsSync as existsSync10 } from "fs";
 import pathModule from "path";
 import { z as z3 } from "zod";
 var HashCacheSchema = z3.object({
@@ -6809,9 +6853,9 @@ function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
 async function loadCache(path43) {
-  if (!existsSync11(path43)) return { version: 1, hashes: {} };
+  if (!existsSync10(path43)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile8(path43, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile7(path43, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -6865,11 +6909,11 @@ async function adopt(provider, specs, lock, lockPath, opts = {}) {
   const localByHash = /* @__PURE__ */ new Map();
   const unmatchedLocal = [];
   for (const spec of specs) {
-    if (!existsSync12(spec.outFile)) {
+    if (!existsSync11(spec.outFile)) {
       unmatchedLocal.push(`${spec.styleId}/${spec.assetId} (no file at ${spec.outFile})`);
       continue;
     }
-    const bytes = await readFile9(spec.outFile);
+    const bytes = await readFile8(spec.outFile);
     try {
       decodePng(bytes);
     } catch (err) {
@@ -6989,7 +7033,7 @@ async function writePromptsBack(manifestPath, lock, opts = {}) {
   const log2 = opts.onProgress ?? (() => {
   });
   const selectedAssets = opts.assetIds ? new Set(opts.assetIds) : null;
-  const raw = JSON.parse(await readFile9(manifestPath, "utf8"));
+  const raw = JSON.parse(await readFile8(manifestPath, "utf8"));
   const best = /* @__PURE__ */ new Map();
   for (const entry of Object.values(lock.entries)) {
     if (opts.provider && entry.provider !== opts.provider) continue;
@@ -7022,19 +7066,19 @@ function formatUnmatchedRemote(objects, limit = 15) {
 }
 
 // src/pipeline/salvage.ts
-import { readFile as readFile10 } from "fs/promises";
-import { existsSync as existsSync13 } from "fs";
-import path16 from "path";
+import { readFile as readFile9 } from "fs/promises";
+import { existsSync as existsSync12 } from "fs";
+import path15 from "path";
 function providerClaimId(provider, objectId) {
   return `${encodeURIComponent(provider)}:${encodeURIComponent(objectId)}`;
 }
 async function loadClaims(lockPaths, opts = {}) {
   const claimed = /* @__PURE__ */ new Set();
   for (const p of lockPaths) {
-    if (!existsSync13(p)) throw new Error(`Claim lockfile not found: ${p}`);
+    if (!existsSync12(p)) throw new Error(`Claim lockfile not found: ${p}`);
     let parsed;
     try {
-      parsed = parseLock(JSON.parse(await readFile10(p, "utf8")));
+      parsed = parseLock(JSON.parse(await readFile9(p, "utf8")));
     } catch {
       throw new Error(`Claim lockfile is malformed: ${p}`);
     }
@@ -7082,20 +7126,20 @@ function matchStyleByPattern(prompt, manifest) {
   return null;
 }
 async function loadSiblingManifests(ownManifestPath, workspaceManifestPaths, claimPaths) {
-  const own = path16.resolve(ownManifestPath);
+  const own = path15.resolve(ownManifestPath);
   const siblingManifestPaths = [
     .../* @__PURE__ */ new Set([
       ...workspaceManifestPaths,
-      ...claimPaths.map((c) => path16.join(path16.dirname(path16.resolve(c)), "pixelkiln.manifest.json"))
+      ...claimPaths.map((c) => path15.join(path15.dirname(path15.resolve(c)), "pixelkiln.manifest.json"))
     ])
   ];
   const siblings = [];
   for (const siblingManifestPath of siblingManifestPaths) {
-    if (path16.resolve(siblingManifestPath) === own) continue;
-    if (!existsSync13(siblingManifestPath)) continue;
+    if (path15.resolve(siblingManifestPath) === own) continue;
+    if (!existsSync12(siblingManifestPath)) continue;
     try {
       const { manifest } = await loadManifest(siblingManifestPath);
-      siblings.push({ label: path16.basename(path16.dirname(siblingManifestPath)), manifest });
+      siblings.push({ label: path15.basename(path15.dirname(siblingManifestPath)), manifest });
     } catch {
     }
   }
@@ -7211,9 +7255,9 @@ async function applyTags(provider, decisions, existing, opts = {}) {
 }
 
 // src/workspace.ts
-import { mkdir as mkdir5, readFile as readFile11, rename as rename5, rm as rm6, writeFile as writeFile6 } from "fs/promises";
-import { existsSync as existsSync14 } from "fs";
-import path17 from "path";
+import { mkdir as mkdir5, readFile as readFile10, rename as rename5, rm as rm6, writeFile as writeFile6 } from "fs/promises";
+import { existsSync as existsSync13 } from "fs";
+import path16 from "path";
 import { z as z4 } from "zod";
 var WorkspaceProjectSchema = z4.object({
   id: z4.string().min(1),
@@ -7232,18 +7276,18 @@ var WorkspaceSchema = z4.object({
 function parseWorkspace(raw) {
   const parsed = WorkspaceSchema.safeParse(raw);
   if (parsed.success) return parsed.data;
-  throw new Error(
+  throw new ProjectError(
     `Workspace catalog is not valid v1:
 ${parsed.error.issues.slice(0, 5).map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n")}`
   );
 }
 async function loadWorkspace(workspacePath) {
-  if (!existsSync14(workspacePath)) return { version: 1, projects: [] };
+  if (!existsSync13(workspacePath)) return { version: 1, projects: [] };
   let raw;
   try {
-    raw = JSON.parse(await readFile11(workspacePath, "utf8"));
+    raw = JSON.parse(await readFile10(workspacePath, "utf8"));
   } catch (err) {
-    throw new Error(
+    throw new ProjectError(
       `Workspace catalog at ${workspacePath} is malformed:
 ${err instanceof Error ? err.message : String(err)}`
     );
@@ -7255,7 +7299,7 @@ async function saveWorkspace(workspacePath, ws) {
     version: 1,
     projects: [...ws.projects].sort((a, b) => a.id.localeCompare(b.id))
   };
-  await mkdir5(path17.dirname(path17.resolve(workspacePath)), { recursive: true });
+  await mkdir5(path16.dirname(path16.resolve(workspacePath)), { recursive: true });
   const tmp = `${workspacePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile6(tmp, JSON.stringify(sorted, null, 2) + "\n");
@@ -7265,12 +7309,12 @@ async function saveWorkspace(workspacePath, ws) {
   }
 }
 function toPortablePath(dir, absolute) {
-  return path17.relative(dir, absolute).split(path17.sep).join("/");
+  return path16.relative(dir, absolute).split(path16.sep).join("/");
 }
 function resolveProject(dir, project) {
   return {
-    manifestPath: path17.resolve(dir, project.manifest.split("/").join(path17.sep)),
-    lockPath: path17.resolve(dir, project.lock.split("/").join(path17.sep))
+    manifestPath: path16.resolve(dir, project.manifest.split("/").join(path16.sep)),
+    lockPath: path16.resolve(dir, project.lock.split("/").join(path16.sep))
   };
 }
 function validateWorkspace(ws, dir) {
@@ -7283,21 +7327,21 @@ function validateWorkspace(ws, dir) {
     const { manifestPath, lockPath } = resolveProject(dir, project);
     lockOwners.set(lockPath, [...lockOwners.get(lockPath) ?? [], project.id]);
     manifestOwners.set(manifestPath, [...manifestOwners.get(manifestPath) ?? [], project.id]);
-    if (path17.isAbsolute(project.manifest) || path17.isAbsolute(project.lock)) {
+    if (path16.isAbsolute(project.manifest) || path16.isAbsolute(project.lock)) {
       diagnostics.push({
         id: "absolute-path",
         level: "warning",
         message: `project "${project.id}" stores an absolute path \u2014 the catalog will not resolve correctly if this tree is cloned or moved elsewhere`
       });
     }
-    if (!existsSync14(manifestPath)) {
+    if (!existsSync13(manifestPath)) {
       diagnostics.push({
         id: "missing-manifest",
         level: "error",
         message: `project "${project.id}" manifest not found: ${manifestPath}`
       });
     }
-    if (!existsSync14(lockPath)) {
+    if (!existsSync13(lockPath)) {
       diagnostics.push({
         id: "missing-lock",
         level: "error",
@@ -7344,8 +7388,8 @@ function validateWorkspace(ws, dir) {
 }
 
 // src/pick/salvage-server.ts
-import { mkdir as mkdir6, writeFile as writeFile7, readFile as readFile13 } from "fs/promises";
-import path18 from "path";
+import { mkdir as mkdir6, writeFile as writeFile7, readFile as readFile12 } from "fs/promises";
+import path17 from "path";
 
 // src/pick/salvage-sheet.ts
 var escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -7505,7 +7549,7 @@ refresh();
 
 // src/pick/review-server.ts
 import { createServer } from "http";
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 
 // src/open.ts
 import { spawn } from "child_process";
@@ -7532,7 +7576,7 @@ function serveReviewPage(opts) {
       if (req.method === "GET" && req.url && opts.assets?.has(req.url)) {
         try {
           const asset = opts.assets.get(req.url);
-          const bytes = await readFile12(asset.path);
+          const bytes = await readFile11(asset.path);
           res.writeHead(200, {
             "Content-Type": asset.contentType,
             "Cache-Control": "no-store",
@@ -7609,7 +7653,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
   });
   const html = renderSalvageSheet(orphans, {
     styleId: ctx.styleId,
-    importDir: path18.relative(process.cwd(), ctx.importDir) || "."
+    importDir: path17.relative(process.cwd(), ctx.importDir) || "."
   });
   const byId = new Map(orphans.map((o) => [o.id, o]));
   const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
@@ -7638,9 +7682,9 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
             if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
             decodePng(buf);
             const assetId = idFromPrompt(orphan.prompt, taken);
-            const rel = path18.join("_salvaged", `${assetId}.png`);
-            const outFile = path18.resolve(ctx.importDir, rel);
-            await mkdir6(path18.dirname(outFile), { recursive: true });
+            const rel = path17.join("_salvaged", `${assetId}.png`);
+            const outFile = path17.resolve(ctx.importDir, rel);
+            await mkdir6(path17.dirname(outFile), { recursive: true });
             await writeFile7(outFile, buf);
             ctx.manifest.assets[assetId] = {
               prompt: orphan.prompt,
@@ -7673,7 +7717,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               sourceUrl: durableSource,
               sourceUrls: durableSource ? [{ url: durableSource }] : [],
               outputs: [{
-                path: portableOutputPath(outFile, path18.dirname(ctx.manifestPath)),
+                path: portableOutputPath(outFile, path17.dirname(ctx.manifestPath)),
                 sha256: sha256(buf)
               }],
               submittedAt: orphan.createdAt,
@@ -7697,7 +7741,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
         }
       }
       await applyTags(provider, decisions, existingTags, { onProgress: log2 });
-      const raw = JSON.parse(await readFile13(ctx.manifestPath, "utf8"));
+      const raw = JSON.parse(await readFile12(ctx.manifestPath, "utf8"));
       for (const id of importedAssetIds) raw.assets[id] = ctx.manifest.assets[id];
       await writeFile7(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
       await saveLock(ctx.lockPath, ctx.lock);
@@ -7707,19 +7751,19 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
 }
 
 // src/cli/project.ts
-import path20 from "path";
-import { existsSync as existsSync15 } from "fs";
+import path19 from "path";
+import { existsSync as existsSync14 } from "fs";
 
 // src/project.ts
-import path19 from "path";
+import path18 from "path";
 async function openProject(manifestPath = "pixelkiln.manifest.json", opts = {}) {
-  const absolute = path19.resolve(manifestPath);
-  const root = path19.dirname(absolute);
+  const absolute = path18.resolve(manifestPath);
+  const root = path18.dirname(absolute);
   if (opts.env !== false) {
     loadEnvFiles(root);
-    if (path19.resolve(process.cwd()) !== root) loadEnvFiles(process.cwd());
+    if (path18.resolve(process.cwd()) !== root) loadEnvFiles(process.cwd());
   }
-  const lockPath = path19.resolve(opts.lockPath ?? path19.join(root, "pixelkiln.lock.json"));
+  const lockPath = path18.resolve(opts.lockPath ?? path18.join(root, "pixelkiln.lock.json"));
   const loaded = await loadManifest(absolute);
   const specs = await resolveSpecs(loaded, { styles: opts.styles ?? [], assets: opts.assets ?? [] });
   const lock = await loadLock(lockPath);
@@ -7850,11 +7894,11 @@ async function workspaceStatus(ws, dir) {
 
 // src/cli/project.ts
 async function provenanceFile(id, file) {
-  const absolute = path20.resolve(file);
+  const absolute = path19.resolve(file);
   return {
     id,
     path: absolute,
-    sha256: existsSync15(absolute) ? await sha256File(absolute) : null,
+    sha256: existsSync14(absolute) ? await sha256File(absolute) : null,
     included: true
   };
 }
@@ -7885,14 +7929,14 @@ function accountProviderId(manifest, requested, command) {
   const providers = manifestProviderIds(manifest);
   if (requested) {
     if (!providers.includes(requested)) {
-      throw new Error(
+      throw new UsageError(
         `Provider "${requested}" is not used by this manifest. Used: ${providers.join(", ")}.`
       );
     }
     return requested;
   }
   if (providers.length > 1) {
-    throw new Error(
+    throw new UsageError(
       `${command} is account-scoped and this manifest uses ${providers.join(", ")}. Pass --provider <id>.`
     );
   }
@@ -7903,13 +7947,13 @@ function budgetsForPlan(plan, args) {
   const keyed = Object.entries(args.providerBudgets);
   for (const [provider] of keyed) {
     if (!providerIds.has(provider)) {
-      throw new Error(
+      throw new BudgetError(
         `Budget names provider "${provider}", but this run has work only for ${[...providerIds].join(", ") || "no providers"}.`
       );
     }
   }
   if (plan.groups.length > 1 && args.budget !== void 0) {
-    throw new Error(
+    throw new BudgetError(
       "A mixed-provider run needs provider-keyed budgets, for example --budget pixellab=40 --budget retrodiffusion=1.25."
     );
   }
@@ -7917,7 +7961,7 @@ function budgetsForPlan(plan, args) {
   for (const group of plan.groups) {
     const ceiling = args.providerBudgets[group.provider];
     if (plan.groups.length > 1 && group.costUnit !== "free" && group.cost > 0 && ceiling === void 0) {
-      throw new Error(
+      throw new BudgetError(
         `Mixed-provider run is missing --budget ${group.provider}=<amount> for ${formatCost(group.costUnit, group.cost)} of planned work.`
       );
     }
@@ -7926,15 +7970,15 @@ function budgetsForPlan(plan, args) {
   return out;
 }
 async function requireCompleteWorkspaceClaims(workspacePath) {
-  if (!existsSync15(workspacePath)) {
-    throw new Error(`Workspace catalog not found: ${workspacePath}`);
+  if (!existsSync14(workspacePath)) {
+    throw new ProjectError(`Workspace catalog not found: ${workspacePath}`);
   }
-  const dir = path20.dirname(path20.resolve(workspacePath));
+  const dir = path19.dirname(path19.resolve(workspacePath));
   const ws = await loadWorkspace(workspacePath);
   const diagnostics = validateWorkspace(ws, dir);
   const errors = diagnostics.filter((d) => d.level === "error");
   if (errors.length) {
-    throw new Error(
+    throw new ProjectError(
       `Workspace catalog at ${workspacePath} is not safe to derive a claim set from:
 ` + errors.map((d) => `  ${d.id}: ${d.message}`).join("\n")
     );
@@ -7952,9 +7996,9 @@ async function openAccountProject(args) {
   return project;
 }
 async function open(args) {
-  if (!existsSync15(path20.resolve(args.manifest))) {
-    throw new Error(
-      `No manifest at ${path20.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
+  if (!existsSync14(path19.resolve(args.manifest))) {
+    throw new ProjectError(
+      `No manifest at ${path19.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
     );
   }
   const project = await openProject(args.manifest, { lockPath: args.lock, styles: args.styles, assets: args.assets });
@@ -7962,7 +8006,7 @@ async function open(args) {
   let specs = project.specs;
   const accountProvider = ACCOUNT_COMMANDS.has(args.command) ? accountProviderId(loaded.manifest, args.provider, args.command) : void 0;
   if (args.provider && !accountProvider) {
-    throw new Error("--provider is only used by balance, adopt, salvage, purge, or workspace add.");
+    throw new UsageError("--provider is only used by balance, adopt, salvage, purge, or workspace add.");
   }
   if (accountProvider) specs = specs.filter((spec) => spec.provider === accountProvider);
   const accountManifest = accountProvider ? {
@@ -7975,7 +8019,7 @@ async function open(args) {
     )
   } : loaded.manifest;
   if (accountProvider && args.styles.some((styleId) => !accountManifest.styles[styleId])) {
-    throw new Error(`Selected style is not assigned to provider "${accountProvider}".`);
+    throw new UsageError(`Selected style is not assigned to provider "${accountProvider}".`);
   }
   return { loaded, specs, lock, accountProvider, accountManifest };
 }
@@ -7996,7 +8040,7 @@ function providerCache(mode2) {
 
 // src/cli/commands/account.ts
 async function runBalance(args) {
-  loadEnvFiles(path21.dirname(path21.resolve(args.manifest)));
+  loadEnvFiles(path20.dirname(path20.resolve(args.manifest)));
   loadEnvFiles(process.cwd());
   const loaded = await loadManifest(args.manifest);
   const selectedProvider = accountProviderId(loaded.manifest, args.provider, "balance");
@@ -8043,12 +8087,12 @@ async function runAdopt(args) {
   tagged ${n} object(s) upstream`);
   }
   if (args.writePrompts) {
-    const { filled, stillEmpty } = await writePromptsBack(path21.resolve(args.manifest), lock, {
+    const { filled, stillEmpty } = await writePromptsBack(path20.resolve(args.manifest), lock, {
       onProgress: log,
       provider: provider.id,
       assetIds: specs.map((spec) => spec.assetId)
     });
-    log(`  recovered ${filled} prompt(s) into ${path21.relative(process.cwd(), args.manifest)}`);
+    log(`  recovered ${filled} prompt(s) into ${path20.relative(process.cwd(), args.manifest)}`);
     const reloaded = await loadManifest(args.manifest);
     const rebased = (await resolveSpecs(reloaded, {
       styles: args.styles,
@@ -8078,12 +8122,12 @@ async function runSalvage2(args) {
   const provider = providerFor(accountProvider);
   const jsonMode = args.dryRun && args.json;
   const diag = jsonMode ? (msg = "") => console.error(msg) : log;
-  const ownLock = path21.resolve(args.lock);
+  const ownLock = path20.resolve(args.lock);
   let workspaceProjects = [];
   let workspaceDir = "";
   if (args.workspace) {
-    const workspacePath = path21.resolve(args.workspace);
-    workspaceDir = path21.dirname(workspacePath);
+    const workspacePath = path20.resolve(args.workspace);
+    workspaceDir = path20.dirname(workspacePath);
     const complete = await requireCompleteWorkspaceClaims(workspacePath);
     workspaceProjects = complete.ws.projects;
     for (const d of complete.diagnostics) diag(`  WARN  ${d.id}: ${d.message}`);
@@ -8092,12 +8136,12 @@ async function runSalvage2(args) {
   const lockPaths = [
     .../* @__PURE__ */ new Set([
       ...workspaceLockPaths,
-      ...existsSync16(ownLock) ? [ownLock] : [],
-      ...args.claims.map((c) => path21.resolve(c))
+      ...existsSync15(ownLock) ? [ownLock] : [],
+      ...args.claims.map((c) => path20.resolve(c))
     ])
   ];
   diag(`  claim set (${lockPaths.length} lockfile(s)):`);
-  for (const p of lockPaths) diag(`    ${path21.relative(process.cwd(), p)}`);
+  for (const p of lockPaths) diag(`    ${path20.relative(process.cwd(), p)}`);
   if (!args.claims.length && !args.workspace) {
     diag(
       `
@@ -8105,7 +8149,7 @@ async function runSalvage2(args) {
   pass every other project's lockfile via --claims a.json,b.json, or
   register every project in a workspace catalog and pass --workspace.`
     );
-  } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path21.resolve(args.manifest))) {
+  } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path20.resolve(args.manifest))) {
     diag(
       `
   This project's manifest is not registered in the workspace catalog. Its own
@@ -8189,7 +8233,7 @@ async function runSalvage2(args) {
         manifestPath: loaded.path,
         manifest: accountManifest,
         styleId,
-        importDir: path21.resolve(loaded.root, style.outDir),
+        importDir: path20.resolve(loaded.root, style.outDir),
         lock,
         lockPath: args.lock
       },
@@ -8290,17 +8334,17 @@ async function runTag(args) {
 }
 
 // src/cli/commands/edit.ts
-import path24 from "path";
+import path23 from "path";
 
 // src/pipeline/hand-edit.ts
-import { existsSync as existsSync17 } from "fs";
-import { copyFile, mkdir as mkdir7, readFile as readFile15, rename as rename7, rm as rm8, writeFile as writeFile9 } from "fs/promises";
-import path23 from "path";
+import { existsSync as existsSync16 } from "fs";
+import { copyFile, mkdir as mkdir7, readFile as readFile14, rename as rename7, rm as rm8, writeFile as writeFile9 } from "fs/promises";
+import path22 from "path";
 import { z as z6 } from "zod";
 
 // src/manifest-edit.ts
-import { readFile as readFile14, rename as rename6, rm as rm7, writeFile as writeFile8 } from "fs/promises";
-import path22 from "path";
+import { readFile as readFile13, rename as rename6, rm as rm7, writeFile as writeFile8 } from "fs/promises";
+import path21 from "path";
 import { z as z5 } from "zod";
 var HexSha = z5.string().regex(/^[0-9a-f]{64}$/);
 var AssetPatchSchema = z5.object({
@@ -8374,6 +8418,8 @@ var ManifestEditSchema = z5.discriminatedUnion("action", [
       promptSuffix: z5.string().optional(),
       /** `#rrggbb` values; null or empty clears the style's own palette. */
       palette: z5.array(z5.string().regex(/^#?[0-9a-f]{6}$/i, "expected a six-digit hex colour")).max(256).nullable().optional(),
+      /** Snap downloaded art to the palette; false clears the style's own value. */
+      enforcePalette: z5.boolean().optional(),
       /** Provider view name (PixelLab: low top-down, high top-down, side); empty clears. */
       view: z5.string().max(64).nullable().optional(),
       /** pixflux only; null clears the style's own value. */
@@ -8465,6 +8511,7 @@ function applyEdit(raw, edit) {
       const colors = (patch2.palette ?? []).map((color) => "#" + color.replace(/^#/, "").toLowerCase());
       setOrDelete(style, "palette", colors.length ? colors : null);
     }
+    if (patch2.enforcePalette !== void 0) setOrDelete(style, "enforcePalette", patch2.enforcePalette || null);
     if (patch2.view !== void 0) setOrDelete(style, "view", patch2.view?.trim() || null);
     if (patch2.noBackground !== void 0) setOrDelete(style, "noBackground", patch2.noBackground);
     return;
@@ -8512,8 +8559,8 @@ function applyEdit(raw, edit) {
   }
 }
 async function applyManifestEdit(manifestPath, edit) {
-  const absolute = path22.resolve(manifestPath);
-  const original = await readFile14(absolute, "utf8");
+  const absolute = path21.resolve(manifestPath);
+  const original = await readFile13(absolute, "utf8");
   const before = sha256(original);
   if (before !== edit.expectedSha256) throw new ManifestDriftError(absolute);
   let raw;
@@ -8527,9 +8574,9 @@ async function applyManifestEdit(manifestPath, edit) {
   applyEdit(raw, edit);
   const next = serializeLike(original, raw);
   if (next === original) return { manifestPath: absolute, sha256: before, changed: false };
-  const tmp = path22.join(
-    path22.dirname(absolute),
-    `.${path22.basename(absolute)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
+  const tmp = path21.join(
+    path21.dirname(absolute),
+    `.${path21.basename(absolute)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
   );
   try {
     await writeFile8(tmp, next);
@@ -8551,11 +8598,11 @@ async function applyManifestEdit(manifestPath, edit) {
 var HAND_EDIT_DIR = "edits";
 function handEditPath(loaded, spec) {
   const style = loaded.manifest.styles[spec.styleId];
-  const outDir = path23.resolve(loaded.root, style?.outDir ?? ".");
-  const relative = path23.relative(outDir, spec.outFile);
-  const inside = relative && !relative.startsWith("..") && !path23.isAbsolute(relative);
-  const file = inside ? relative : path23.basename(spec.outFile);
-  return path23.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
+  const outDir = path22.resolve(loaded.root, style?.outDir ?? ".");
+  const relative = path22.relative(outDir, spec.outFile);
+  const inside = relative && !relative.startsWith("..") && !path22.isAbsolute(relative);
+  const file = inside ? relative : path22.basename(spec.outFile);
+  return path22.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
 }
 function handEditBases(spec, lock) {
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
@@ -8568,10 +8615,10 @@ function handEditBases(spec, lock) {
     }));
     if (members.some((member) => member.mediaType && member.mediaType !== "image/png")) return null;
     if (entry.outputs.length === 1 && !primaryOutput(entry)) return null;
-    if (!members.every((member) => existsSync17(member.path))) return null;
+    if (!members.every((member) => existsSync16(member.path))) return null;
     return members.map(({ role, path: file }) => ({ role, path: file }));
   }
-  return existsSync17(spec.outFile) ? [{ role: null, path: spec.outFile }] : null;
+  return existsSync16(spec.outFile) ? [{ role: null, path: spec.outFile }] : null;
 }
 function handEditMembers(loaded, spec, lock, editPath) {
   const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
@@ -8597,18 +8644,18 @@ async function startHandEdit(loaded, lock, spec, opts = {}) {
       `${spec.styleId}/${spec.assetId} declares ${spec.source}, one committed file placed for the whole set; clear that source (pixelkiln edit detach) to hand-edit the members one by one`
     );
   }
-  const existing = spec.source ? path23.resolve(loaded.root, spec.source) : null;
+  const existing = spec.source ? path22.resolve(loaded.root, spec.source) : null;
   const editPath = existing ?? handEditPath(loaded, spec);
   const members = handEditMembers(loaded, spec, lock, editPath);
   let created = false;
   for (const member of members) {
-    if (existsSync17(member.path)) continue;
+    if (existsSync16(member.path)) continue;
     if (!member.base) {
       throw new ManifestEditError(
         `${spec.styleId}/${spec.assetId} has no generated PNG on disk to start from; generate or restore it first`
       );
     }
-    await mkdir7(path23.dirname(member.path), { recursive: true });
+    await mkdir7(path22.dirname(member.path), { recursive: true });
     await copyFile(member.base, member.path);
     created = true;
   }
@@ -8687,7 +8734,7 @@ function handEditProjectPath(editPath) {
 async function readHandEditCompanion(editPath) {
   let text;
   try {
-    text = await readFile15(handEditCompanionPath(editPath), "utf8");
+    text = await readFile14(handEditCompanionPath(editPath), "utf8");
   } catch {
     return null;
   }
@@ -8730,7 +8777,7 @@ async function saveHandEdit(loaded, lock, spec, input) {
     }
   });
   const bases = handEditBases(spec, lock);
-  const expectedSize = bases?.[0] ? decodePng(await readFile15(bases[0].path)) : { width: spec.width, height: spec.height };
+  const expectedSize = bases?.[0] ? decodePng(await readFile14(bases[0].path)) : { width: spec.width, height: spec.height };
   for (const [index, image] of decoded.entries()) {
     if (image.width !== expectedSize.width || image.height !== expectedSize.height) {
       const which = memberSet ? `member ${incoming[index].role ?? index}` : "the edit";
@@ -8746,7 +8793,7 @@ async function saveHandEdit(loaded, lock, spec, input) {
     editor: input.editor,
     protocol: input.protocol,
     savedAt: (input.now ?? /* @__PURE__ */ new Date()).toISOString(),
-    project: projectPath ? path23.basename(projectPath) : null,
+    project: projectPath ? path22.basename(projectPath) : null,
     outputs: incoming.map((frame, index) => ({
       role: frame.role,
       basedOn: basedOnHash(entry, index),
@@ -8806,7 +8853,7 @@ async function runEdit(args) {
   const set = started.members.length > 1;
   const kind = spec.generator === "frames" ? "frames" : "members";
   log(`  ${started.created ? "created" : "found"} ${started.source}${set ? ` (${started.members.length} ${kind})` : ""}${started.declared ? " and declared it as the asset's source" : ""}`);
-  if (set) for (const member of started.members) log(`    ${member.role ?? ""}  ${path24.relative(process.cwd(), member.path)}`);
+  if (set) for (const member of started.members) log(`    ${member.role ?? ""}  ${path23.relative(process.cwd(), member.path)}`);
   if (args.noOpen) {
     log(`  edit ${set ? "them" : "it"} with your own tool, then run pixelkiln plan; mount and pack place ${set ? "them" : "it"} in place of the generated art`);
   } else {
@@ -8816,17 +8863,17 @@ async function runEdit(args) {
 }
 
 // src/cli/commands/gallery.ts
-import path31 from "path";
-import { existsSync as existsSync23 } from "fs";
+import path30 from "path";
+import { existsSync as existsSync22 } from "fs";
 
 // src/gallery/snapshot.ts
 import { createHash as createHash3 } from "crypto";
-import { existsSync as existsSync19 } from "fs";
-import { readFile as readFile16, stat as stat2 } from "fs/promises";
-import path27 from "path";
+import { existsSync as existsSync18 } from "fs";
+import { readFile as readFile15, stat as stat2 } from "fs/promises";
+import path26 from "path";
 
 // src/gallery/edit.ts
-import path25 from "path";
+import path24 from "path";
 import { z as z7 } from "zod";
 var Base64 = z7.string().regex(/^[A-Za-z0-9+/]*={0,2}$/).max(Math.ceil(MAX_HAND_EDIT_BYTES / 3) * 4);
 var HandEditRequestSchema = z7.discriminatedUnion("action", [
@@ -8916,7 +8963,7 @@ function createGalleryEditHandler(opts) {
     }
     const result = await applyManifestEdit(manifestPath, parsed.data);
     if (result.changed) {
-      const relative = path25.relative(process.cwd(), result.manifestPath);
+      const relative = path24.relative(process.cwd(), result.manifestPath);
       const shown = !relative || relative.startsWith("..") ? result.manifestPath : relative;
       const subject = parsed.data.action === "patch-style" ? `style ${parsed.data.styleId}` : parsed.data.action === "set-source" || parsed.data.action === "clear-source" ? `${parsed.data.styleId}/${parsed.data.assetId} source` : parsed.data.assetId;
       log2(`  manifest edited: ${parsed.data.action === "add-asset" ? "added" : "changed"} ${subject} in ${shown}`);
@@ -8926,8 +8973,8 @@ function createGalleryEditHandler(opts) {
 }
 
 // src/pipeline/history.ts
-import { existsSync as existsSync18 } from "fs";
-import path26 from "path";
+import { existsSync as existsSync17 } from "fs";
+import path25 from "path";
 var HISTORY_ENV = "PIXELKILN_HISTORY";
 function historyLimit(manifest, env = process.env) {
   if (manifest?.history !== void 0) return manifest.history;
@@ -8959,6 +9006,7 @@ function retireGeneration(entry, retiredAt) {
     cost: entry.cost,
     costUnit: entry.costUnit,
     provider: entry.provider,
+    postprocess: entry.postprocess,
     retiredAt
   };
 }
@@ -8971,9 +9019,13 @@ function historyAfterReplacing(previous, limit, retiredAt) {
 }
 function referencedHashes(lock) {
   const hashes = /* @__PURE__ */ new Set();
+  const add = (output) => {
+    hashes.add(output.sha256);
+    if (output.raw) hashes.add(output.raw);
+  };
   for (const entry of Object.values(lock.entries)) {
-    for (const output of entry.outputs) hashes.add(output.sha256);
-    for (const generation of entry.history ?? []) for (const output of generation.outputs) hashes.add(output.sha256);
+    for (const output of entry.outputs) add(output);
+    for (const generation of entry.history ?? []) for (const output of generation.outputs) add(output);
   }
   return hashes;
 }
@@ -9008,10 +9060,11 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
   }
   for (let i = 0; i < entry.outputs.length; i++) {
     const file = currentEntryOutputPath(entry, spec, i);
-    if (!existsSync18(file)) continue;
+    if (!existsSync17(file)) continue;
     if (await sha256File(file) !== entry.outputs[i].sha256 && !opts.force) {
-      throw new Error(
-        `${path26.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`
+      throw new OverwriteRefusedError(
+        `${path25.relative(process.cwd(), file)} was changed after download; keep it with pixelkiln edit, or pass --force to replace it`,
+        [file]
       );
     }
   }
@@ -9043,6 +9096,7 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     cost: generation.cost,
     costUnit: generation.costUnit,
     provider: generation.provider,
+    postprocess: generation.postprocess,
     history
   });
   await saveLock(lockPath, lock);
@@ -9061,7 +9115,7 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
 // src/gallery/snapshot.ts
 var PROJECT_FILE_TYPE = "application/octet-stream";
 function galleryMediaId(absolutePath) {
-  return createHash3("sha256").update(path27.resolve(absolutePath)).digest("hex").slice(0, 24);
+  return createHash3("sha256").update(path26.resolve(absolutePath)).digest("hex").slice(0, 24);
 }
 function galleryMediaRoute(id) {
   return `/media/${id}`;
@@ -9080,9 +9134,9 @@ function describeHistory(media, entry, cacheDir) {
   return (entry.history ?? []).map((generation, i) => {
     const outputs = generation.outputs.map((output) => {
       const mediaType = output.mediaType ?? MediaType.PNG;
-      const file = path27.join(cacheDir, cacheFileName(output.sha256, mediaType));
+      const file = path26.join(cacheDir, cacheFileName(output.sha256, mediaType));
       let url = null;
-      if (existsSync19(file)) {
+      if (existsSync18(file)) {
         const id = galleryMediaId(file);
         media.set(id, { path: file, contentType: mediaType });
         url = `${galleryMediaRoute(id)}?v=${output.sha256.slice(0, 24)}`;
@@ -9111,7 +9165,7 @@ function describeHistory(media, entry, cacheDir) {
 var MAX_COMPARED_BYTES = 8 * 1024 * 1024;
 async function samePixels(a, b) {
   try {
-    const [left, right] = await Promise.all([readFile16(a), readFile16(b)]);
+    const [left, right] = await Promise.all([readFile15(a), readFile15(b)]);
     if (left.length > MAX_COMPARED_BYTES || right.length > MAX_COMPARED_BYTES) return false;
     const x = decodePng(left);
     const y = decodePng(right);
@@ -9164,10 +9218,10 @@ async function describeOutput(media, root, absolutePath, recorded = {}) {
 async function describeQuality(media, root, inspection) {
   const outputPaths = inspection.outputs ?? [inspection.output];
   const outputs = await Promise.all(
-    outputPaths.map((file) => describeOutput(media, root, path27.resolve(root, file)))
+    outputPaths.map((file) => describeOutput(media, root, path26.resolve(root, file)))
   );
-  const recordPath = path27.resolve(root, inspection.record);
-  const recordExists = existsSync19(recordPath);
+  const recordPath = path26.resolve(root, inspection.record);
+  const recordExists = existsSync18(recordPath);
   let options = null;
   let check = null;
   if (recordExists) {
@@ -9186,7 +9240,7 @@ async function describeQuality(media, root, inspection) {
   return {
     state: inspection.state,
     reason: inspection.reason,
-    output: portableOutputPath(path27.resolve(root, inspection.output), root),
+    output: portableOutputPath(path26.resolve(root, inspection.output), root),
     record: portableOutputPath(recordPath, root),
     recordExists,
     outputs,
@@ -9223,9 +9277,9 @@ async function buildGallerySnapshot(opts) {
   const media = /* @__PURE__ */ new Map();
   const plan = await buildPlan(specs, lock);
   const items = [];
-  const manifestText = await readFile16(loaded.path, "utf8");
+  const manifestText = await readFile15(loaded.path, "utf8");
   const manifestSha256 = sha256(manifestText);
-  const cacheDir = path27.resolve(path27.dirname(opts.lockPath), ".pixelkiln", "cache");
+  const cacheDir = path26.resolve(path26.dirname(opts.lockPath), ".pixelkiln", "cache");
   let rawStyles = {};
   try {
     const raw = JSON.parse(manifestText);
@@ -9249,12 +9303,12 @@ async function buildGallerySnapshot(opts) {
         )
       );
       if (spec.source) {
-        const editPath = path27.resolve(root, spec.source);
+        const editPath = path26.resolve(root, spec.source);
         const memberCount = sourceIsStem(spec.source, entry, root) ? entry.outputs.length : 1;
         const editShas = await Promise.all(
           Array.from({ length: memberCount }, async (_, index) => {
             const file = sourceOutputPath(spec.source, entry, index, root);
-            return { file, sha256: existsSync19(file) ? await sha256File(file) : null };
+            return { file, sha256: existsSync18(file) ? await sha256File(file) : null };
           })
         );
         edits = await Promise.all(editShas.map(({ file, sha256: editSha }) => describeOutput(media, root, file, { sha256: editSha })));
@@ -9262,7 +9316,7 @@ async function buildGallerySnapshot(opts) {
         const companion = await readHandEditCompanion(editPath);
         if (companion) {
           const projectPath = handEditProjectPath(editPath);
-          const project = companion.project && existsSync19(projectPath) ? await fileInfo(projectPath) : null;
+          const project = companion.project && existsSync18(projectPath) ? await fileInfo(projectPath) : null;
           let projectUrl = null;
           if (project) {
             const id = galleryMediaId(projectPath);
@@ -9298,8 +9352,8 @@ async function buildGallerySnapshot(opts) {
         editStatus = edits.some((member) => !member.exists) ? "missing" : editChanged.every((changed) => !changed) ? "same" : regenerated ? "regenerated-since" : "edited";
       }
     } else if (spec.source) {
-      outputs = [await describeOutput(media, root, path27.resolve(root, spec.source))];
-    } else if (!entry && existsSync19(spec.outFile)) {
+      outputs = [await describeOutput(media, root, path26.resolve(root, spec.source))];
+    } else if (!entry && existsSync18(spec.outFile)) {
       outputs = [await describeOutput(media, root, spec.outFile)];
     } else {
       outputs = [];
@@ -9341,6 +9395,7 @@ async function buildGallerySnapshot(opts) {
       outputs,
       quality,
       providerMetadata: entry?.providerMetadata ?? {},
+      postprocess: entry?.postprocess ?? null,
       asset,
       source: spec.source ?? null,
       edit,
@@ -9401,6 +9456,7 @@ async function buildGallerySnapshot(opts) {
       outputs,
       quality: null,
       providerMetadata: entry.providerMetadata ?? {},
+      postprocess: entry.postprocess ?? null,
       asset: null,
       source: null,
       edit: null,
@@ -9449,6 +9505,7 @@ async function buildGallerySnapshot(opts) {
       promptPrefix: style?.promptPrefix ?? "",
       promptSuffix: style?.promptSuffix ?? "",
       palette: style?.palette ?? [],
+      enforcePalette: style?.enforcePalette ?? false,
       view: style?.view ?? null,
       noBackground: style?.noBackground ?? true,
       quality: Boolean(style?.quality),
@@ -9478,7 +9535,7 @@ async function buildGallerySnapshot(opts) {
       id: loaded.manifest.name,
       name: loaded.manifest.name,
       manifest: loaded.path,
-      lock: path27.resolve(opts.lockPath),
+      lock: path26.resolve(opts.lockPath),
       root,
       provider: loaded.manifest.provider,
       account: null,
@@ -9504,7 +9561,7 @@ async function buildGallerySnapshot(opts) {
   return { snapshot, media };
 }
 async function buildWorkspaceGallerySnapshot(opts) {
-  const dir = path27.dirname(path27.resolve(opts.workspacePath));
+  const dir = path26.dirname(path26.resolve(opts.workspacePath));
   const media = /* @__PURE__ */ new Map();
   const projects = [];
   const items = [];
@@ -9547,11 +9604,11 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: loaded.manifest.name,
         manifest: manifestPath,
-        lock: path27.resolve(lockPath),
+        lock: path26.resolve(lockPath),
         root: loaded.root,
         provider: loaded.manifest.provider,
         account: project.account ?? null,
-        manifestSha256: manifestSha256 ?? sha256(await readFile16(manifestPath, "utf8")),
+        manifestSha256: manifestSha256 ?? sha256(await readFile15(manifestPath, "utf8")),
         historyLimit: historyLimit(loaded.manifest),
         entries: Object.keys(lock.entries).length,
         items: projectItems.length,
@@ -9563,8 +9620,8 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: project.id,
         manifest: manifestPath,
-        lock: path27.resolve(lockPath),
-        root: path27.dirname(manifestPath),
+        lock: path26.resolve(lockPath),
+        root: path26.dirname(manifestPath),
         provider: project.provider,
         account: project.account ?? null,
         manifestSha256: null,
@@ -9591,7 +9648,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
       version: 1,
       generatedAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
       project: null,
-      workspace: { path: path27.resolve(opts.workspacePath), dir, projects },
+      workspace: { path: path26.resolve(opts.workspacePath), dir, projects },
       filter,
       totals: {
         entries: projects.reduce((sum, project) => sum + project.entries, 0),
@@ -9610,7 +9667,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
 // src/gallery/server.ts
 import { randomBytes } from "crypto";
 import { createServer as createServer2 } from "http";
-import { readFile as readFile17 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 
 // src/gallery/page.ts
 import { readFileSync as readFileSync4 } from "fs";
@@ -9851,7 +9908,7 @@ async function serveGallery(opts) {
         const asset = reviewAssets.get(jobId)?.get(url2.pathname);
         if (!asset) return fail(404, "no such review asset");
         try {
-          const bytes = await readFile17(asset.path);
+          const bytes = await readFile16(asset.path);
           res.writeHead(200, {
             "Content-Type": asset.contentType,
             "Cache-Control": "no-store",
@@ -9927,7 +9984,7 @@ async function serveGallery(opts) {
         if (!asset) return fail(404, "no such gallery media");
         let bytes;
         try {
-          bytes = await readFile17(asset.path);
+          bytes = await readFile16(asset.path);
         } catch {
           return fail(404, "gallery media is no longer on disk; refresh the page");
         }
@@ -10080,7 +10137,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
   if (opts.budget != null) {
     const cost = [...estimates.values()].reduce((sum, estimate) => sum + estimate.amount, 0);
     if (cost > opts.budget) {
-      throw new Error(
+      throw new BudgetError(
         `This run would spend ${formatCost(unit, cost)} but the budget is ${formatCost(unit, opts.budget)}. Narrow it with --only/--style, or raise --budget.`
       );
     }
@@ -10240,13 +10297,13 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
 }
 
 // src/pick/server.ts
-import { existsSync as existsSync21 } from "fs";
-import { readFile as readFile19 } from "fs/promises";
+import { existsSync as existsSync20 } from "fs";
+import { readFile as readFile18 } from "fs/promises";
 
 // src/pipeline/init.ts
-import { readdir, readFile as readFile18, writeFile as writeFile10 } from "fs/promises";
-import { existsSync as existsSync20 } from "fs";
-import path28 from "path";
+import { readdir, readFile as readFile17, writeFile as writeFile10 } from "fs/promises";
+import { existsSync as existsSync19 } from "fs";
+import path27 from "path";
 function pngSize(buf) {
   if (buf.length < 24) return null;
   const isPng = buf.readUInt32BE(0) === 2303741511 && buf.readUInt32BE(4) === 218765834;
@@ -10260,7 +10317,7 @@ function slugify(value) {
 async function walk(dir, exclude) {
   const out = [];
   for (const entry of await readdir(dir, { withFileTypes: true })) {
-    const full = path28.join(dir, entry.name);
+    const full = path27.join(dir, entry.name);
     if (exclude.some((x) => full.includes(x))) continue;
     if (entry.isDirectory()) out.push(...await walk(full, exclude));
     else if (entry.name.toLowerCase().endsWith(".png")) out.push(full);
@@ -10274,14 +10331,14 @@ async function scanAssets(root, opts = {}) {
   const skipped = [];
   const seen = /* @__PURE__ */ new Map();
   for (const file of files.sort()) {
-    const size = pngSize(await readFile18(file));
+    const size = pngSize(await readFile17(file));
     if (!size) {
       skipped.push(`${file} (not a readable PNG)`);
       continue;
     }
-    const rel = path28.relative(root, file);
-    const category = path28.dirname(rel) === "." ? "" : path28.dirname(rel);
-    let id = slugify(path28.basename(rel));
+    const rel = path27.relative(root, file);
+    const category = path27.dirname(rel) === "." ? "" : path27.dirname(rel);
+    let id = slugify(path27.basename(rel));
     if (seen.has(id)) {
       const n = seen.get(id) + 1;
       seen.set(id, n);
@@ -10324,6 +10381,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
         promptSuffix: "",
         styleImages: [],
         palette: [],
+        enforcePalette: false,
         outDir,
         tags: [name],
         providerOptions: {}
@@ -10338,7 +10396,7 @@ function mode(values) {
   return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? 64;
 }
 async function writeManifestFile(target, manifest) {
-  if (existsSync20(target)) {
+  if (existsSync19(target)) {
     throw new Error(`${target} already exists \u2014 refusing to overwrite an existing manifest.`);
   }
   await writeFile10(target, JSON.stringify(manifest, null, 2) + "\n");
@@ -10741,13 +10799,13 @@ async function currentArt(entry, spec) {
   const previous = primaryOutput({ ...entry, outputs: entry.supersededOutputs });
   if (!previous) return null;
   const file = resolveOutputPath(previous.path, spec.root);
-  if (!existsSync21(file)) return null;
+  if (!existsSync20(file)) return null;
   const contentType = previous.mediaType ?? mediaTypeFromExtension(file);
   if (!contentType) return null;
   let width = entry.width;
   let height = entry.height;
   if (contentType === "image/png") {
-    const size = pngSize(await readFile19(file));
+    const size = pngSize(await readFile18(file));
     if (size) ({ width, height } = size);
   }
   return { path: file, contentType, width, height };
@@ -11240,15 +11298,15 @@ function createGenerateHandlers(opts) {
 }
 
 // src/gallery/editor.ts
-import { readFile as readFile21 } from "fs/promises";
-import path30 from "path";
+import { readFile as readFile20 } from "fs/promises";
+import path29 from "path";
 
 // src/editor/install.ts
 import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync22 } from "fs";
-import { mkdir as mkdir8, readFile as readFile20, rename as rename8, rm as rm9, stat as stat3, writeFile as writeFile11 } from "fs/promises";
+import { existsSync as existsSync21 } from "fs";
+import { mkdir as mkdir8, readFile as readFile19, rename as rename8, rm as rm9, stat as stat3, writeFile as writeFile11 } from "fs/promises";
 import os2 from "os";
-import path29 from "path";
+import path28 from "path";
 
 // tools/pixelorama-bridge/pin.json
 var pin_default = {
@@ -11312,15 +11370,15 @@ var EditorInstallError = class extends Error {
 };
 function editorToolsRoot() {
   const override = process.env.PIXELKILN_TOOLS_DIR?.trim();
-  if (override) return path29.resolve(override);
-  if (process.platform === "darwin") return path29.join(os2.homedir(), "Library", "Caches", "pixelkiln", "tools");
+  if (override) return path28.resolve(override);
+  if (process.platform === "darwin") return path28.join(os2.homedir(), "Library", "Caches", "pixelkiln", "tools");
   if (process.platform === "win32") {
-    return path29.join(process.env.LOCALAPPDATA ?? path29.join(os2.homedir(), "AppData", "Local"), "pixelkiln", "tools");
+    return path28.join(process.env.LOCALAPPDATA ?? path28.join(os2.homedir(), "AppData", "Local"), "pixelkiln", "tools");
   }
-  return path29.join(process.env.XDG_CACHE_HOME ?? path29.join(os2.homedir(), ".cache"), "pixelkiln", "tools");
+  return path28.join(process.env.XDG_CACHE_HOME ?? path28.join(os2.homedir(), ".cache"), "pixelkiln", "tools");
 }
 function editorDir(pin = EDITOR_PIN, root = editorToolsRoot()) {
-  return path29.join(root, "pixelorama", pin.release ?? "unpublished");
+  return path28.join(root, "pixelorama", pin.release ?? "unpublished");
 }
 function editorBaseUrl(pin = EDITOR_PIN) {
   const override = process.env.PIXELKILN_EDITOR_URL?.trim();
@@ -11330,7 +11388,7 @@ function editorBaseUrl(pin = EDITOR_PIN) {
 }
 async function sha256Of(file) {
   try {
-    return createHash4("sha256").update(await readFile20(file)).digest("hex");
+    return createHash4("sha256").update(await readFile19(file)).digest("hex");
   } catch {
     return null;
   }
@@ -11343,8 +11401,8 @@ async function editorStatus(opts = {}) {
   let totalBytes = 0;
   for (const [name, expected] of Object.entries(pin.files)) {
     totalBytes += expected.bytes;
-    const file = path29.join(dir, name);
-    const info = existsSync22(file) ? await stat3(file).catch(() => null) : null;
+    const file = path28.join(dir, name);
+    const info = existsSync21(file) ? await stat3(file).catch(() => null) : null;
     if (info && info.size === expected.bytes && await sha256Of(file) === expected.sha256) {
       installedBytes += expected.bytes;
     } else {
@@ -11401,7 +11459,7 @@ async function installEditor(opts = {}) {
     if (digest2 !== expected.sha256) {
       throw new EditorInstallError(`${name}: sha256 ${digest2.slice(0, 12)}\u2026 does not match the pinned ${expected.sha256.slice(0, 12)}\u2026`, name);
     }
-    const final = path29.join(dir, name);
+    const final = path28.join(dir, name);
     const tmp = `${final}.${process.pid}.part`;
     try {
       await writeFile11(tmp, bytes);
@@ -11447,7 +11505,7 @@ var EDITOR_CONTENT_TYPES = {
   ".json": "application/json; charset=utf-8"
 };
 function editorContentType(name) {
-  return EDITOR_CONTENT_TYPES[path29.extname(name).toLowerCase()] ?? null;
+  return EDITOR_CONTENT_TYPES[path28.extname(name).toLowerCase()] ?? null;
 }
 
 // src/gallery/editor.ts
@@ -11523,7 +11581,7 @@ function createGalleryEditorHandlers(opts = {}) {
       if (!status.installed) return null;
       let bytes;
       try {
-        bytes = await readFile21(path30.join(dir, name));
+        bytes = await readFile20(path29.join(dir, name));
       } catch {
         verified = null;
         return null;
@@ -11563,13 +11621,13 @@ async function serveUntilStopped(initial, reload, args, access2) {
   };
   const loadProject = async (project) => {
     const ctx = await access2.loadProject(project);
-    const dir = path31.dirname(ctx.loaded.path);
+    const dir = path30.dirname(ctx.loaded.path);
     const declared = readEnvFiles(dir);
     const credentialNames = new Set(availableProviders().flatMap((id) => providerCredentialEnvs(providerFactory(id))));
     for (const [name, value] of Object.entries(declared)) {
       if (credentialNames.has(name) && name in process.env && process.env[name] !== value) {
         throw new Error(
-          `${path31.relative(process.cwd(), dir) || "."} sets ${name} to a different value than the one this gallery already loaded; run a separate gallery for that project so its work uses its own account.`
+          `${path30.relative(process.cwd(), dir) || "."} sets ${name} to a different value than the one this gallery already loaded; run a separate gallery for that project so its work uses its own account.`
         );
       }
     }
@@ -11614,8 +11672,8 @@ async function serveUntilStopped(initial, reload, args, access2) {
 }
 async function runGallery(args) {
   if (args.workspace) {
-    const workspacePath = path31.resolve(args.workspace);
-    if (!existsSync23(workspacePath)) {
+    const workspacePath = path30.resolve(args.workspace);
+    if (!existsSync22(workspacePath)) {
       throw new Error(`Workspace catalog not found: ${workspacePath}`);
     }
     const filter2 = { styles: args.styles, assets: args.assets };
@@ -11635,7 +11693,7 @@ async function runGallery(args) {
     const registered = async (projectId) => {
       const project = (await loadWorkspace(workspacePath)).projects.find((candidate) => candidate.id === projectId);
       if (!projectId || !project) throw new Error(`unknown workspace project "${projectId ?? ""}"`);
-      return resolveProject(path31.dirname(workspacePath), project);
+      return resolveProject(path30.dirname(workspacePath), project);
     };
     await serveUntilStopped(initial, build2, args, {
       manifestFor: async (projectId) => (await registered(projectId)).manifestPath,
@@ -11660,7 +11718,7 @@ async function runGallery(args) {
     return buildGallerySnapshot({ ...fresh, filter });
   };
   await serveUntilStopped(await build(), reload, args, {
-    manifestFor: () => path31.resolve(args.manifest),
+    manifestFor: () => path30.resolve(args.manifest),
     loadProject: () => openProject(args.manifest, { lockPath: args.lock, env: false })
   });
 }
@@ -11690,12 +11748,12 @@ async function runGenerate(args) {
   balance: ${formatCost(balance.unit, balance.remaining)} remaining (${group.provider})`
           );
           if (balance.unit !== group.costUnit) {
-            throw new Error(
+            throw new BudgetError(
               `Provider ${group.provider} estimate unit ${group.costUnit} does not match balance unit ${balance.unit}.`
             );
           }
           if (balance.unit !== "free" && group.cost > balance.remaining) {
-            throw new Error(
+            throw new BudgetError(
               `${group.provider} needs ${formatCost(balance.unit, group.cost)} but only ${formatCost(balance.unit, balance.remaining)} remain.`
             );
           }
@@ -11707,7 +11765,7 @@ async function runGenerate(args) {
         }
         const ceiling = budgets.get(group.provider);
         if (ceiling !== void 0 && group.cost > ceiling) {
-          throw new Error(
+          throw new BudgetError(
             `${group.provider} would spend ${formatCost(group.costUnit, group.cost)} but its budget is ${formatCost(group.costUnit, ceiling)}.`
           );
         }
@@ -11912,18 +11970,18 @@ async function runRestoreGeneration(args) {
 }
 
 // src/cli/commands/housekeeping.ts
-import { existsSync as existsSync25 } from "fs";
+import { existsSync as existsSync24 } from "fs";
 
 // src/pipeline/cache-health.ts
-import { existsSync as existsSync24 } from "fs";
-import { readFile as readFile22, readdir as readdir2, rm as rm10 } from "fs/promises";
-import path32 from "path";
+import { existsSync as existsSync23 } from "fs";
+import { readFile as readFile21, readdir as readdir2, rm as rm10 } from "fs/promises";
+import path31 from "path";
 async function inspectCaches(lock, lockPath, options = {}) {
-  if (options.prune && !existsSync24(lockPath)) {
-    throw new Error(`Refusing to prune without an existing lockfile at ${path32.resolve(lockPath)}`);
+  if (options.prune && !existsSync23(lockPath)) {
+    throw new Error(`Refusing to prune without an existing lockfile at ${path31.resolve(lockPath)}`);
   }
-  const contentDir = path32.resolve(path32.dirname(lockPath), ".pixelkiln", "cache");
-  const remotePath = path32.resolve(cachePathFor(lockPath));
+  const contentDir = path31.resolve(path31.dirname(lockPath), ".pixelkiln", "cache");
+  const remotePath = path31.resolve(cachePathFor(lockPath));
   const referenced = referencedHashes(lock);
   let content = await inspectContentCache(contentDir, referenced);
   let remoteHashes = await inspectRemoteHashCache(remotePath);
@@ -11935,7 +11993,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
     ]);
     for (const name of names) {
       try {
-        await rm10(path32.join(contentDir, name), { force: true });
+        await rm10(path31.join(contentDir, name), { force: true });
         removed.contentFiles++;
       } catch {
       }
@@ -11944,7 +12002,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
       await saveCache(remotePath, { version: 1, hashes: {} });
       removed.resetRemoteHashCache = true;
     } else if (remoteHashes.invalidIds.length) {
-      const cache = parseCache(JSON.parse(await readFile22(remotePath, "utf8")));
+      const cache = parseCache(JSON.parse(await readFile21(remotePath, "utf8")));
       for (const id of remoteHashes.invalidIds) delete cache.hashes[id];
       removed.remoteHashEntries = remoteHashes.invalidIds.length;
       await saveCache(remotePath, cache);
@@ -11962,7 +12020,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
 async function inspectContentCache(contentDir, referenced) {
   const report = {
     path: contentDir,
-    exists: existsSync24(contentDir),
+    exists: existsSync23(contentDir),
     files: 0,
     bytes: 0,
     valid: 0,
@@ -11983,12 +12041,12 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     report.files++;
-    const file = path32.join(contentDir, entry.name);
+    const file = path31.join(contentDir, entry.name);
     const mediaType = mediaTypeFromExtension(entry.name);
     const expected = mediaType ? entry.name.slice(0, -4) : "";
     let bytes;
     try {
-      bytes = await readFile22(file);
+      bytes = await readFile21(file);
       report.bytes += bytes.length;
     } catch (err) {
       report.invalid.push({
@@ -12026,7 +12084,7 @@ async function inspectContentCache(contentDir, referenced) {
 async function inspectRemoteHashCache(remotePath) {
   const report = {
     path: remotePath,
-    exists: existsSync24(remotePath),
+    exists: existsSync23(remotePath),
     entries: 0,
     valid: 0,
     invalidIds: [],
@@ -12035,7 +12093,7 @@ async function inspectRemoteHashCache(remotePath) {
   if (!report.exists) return report;
   let cache;
   try {
-    cache = parseCache(JSON.parse(await readFile22(remotePath, "utf8")));
+    cache = parseCache(JSON.parse(await readFile21(remotePath, "utf8")));
   } catch (err) {
     report.error = err instanceof Error ? err.message : String(err);
     return report;
@@ -12099,7 +12157,7 @@ async function runAccept(args) {
     let intact = true;
     for (const output of entry.outputs) {
       const file = resolveOutputPath(output.path, item.spec.root);
-      if (!existsSync25(file) || await sha256File(file) !== output.sha256) {
+      if (!existsSync24(file) || await sha256File(file) !== output.sha256) {
         intact = false;
         break;
       }
@@ -12154,42 +12212,42 @@ This drops their provenance from the lockfile. The art on disk is`);
 }
 
 // src/cli/commands/init.ts
-import path33 from "path";
-import { existsSync as existsSync26 } from "fs";
+import path32 from "path";
+import { existsSync as existsSync25 } from "fs";
 async function runInit(args) {
   if (!args.from) throw new Error("init needs --from <dir> pointing at your existing PNGs.");
-  const root = path33.resolve(args.from);
-  if (!existsSync26(root)) throw new Error(`No directory at ${root}`);
+  const root = path32.resolve(args.from);
+  if (!existsSync25(root)) throw new Error(`No directory at ${root}`);
   const generator = args.generator ?? "map";
   if (generator !== "1dir" && generator !== "map") {
     throw new Error(`--generator must be "1dir" or "map", got "${args.generator}".`);
   }
-  const target = path33.resolve(args.out ?? "pixelkiln.manifest.json");
+  const target = path32.resolve(args.out ?? "pixelkiln.manifest.json");
   const { assets, skipped } = await scanAssets(root, { exclude: args.exclude });
   if (!assets.length) throw new Error(`No PNGs found under ${root}`);
   const manifest = buildManifest(
-    args.name ?? path33.basename(path33.dirname(target)),
+    args.name ?? path32.basename(path32.dirname(target)),
     args.styles[0] ?? "base",
     generator,
-    path33.relative(path33.dirname(target), root) || ".",
+    path32.relative(path32.dirname(target), root) || ".",
     assets
   );
   await writeManifestFile(target, manifest);
-  log(`  scanned ${assets.length} PNG(s) under ${path33.relative(process.cwd(), root)}`);
+  log(`  scanned ${assets.length} PNG(s) under ${path32.relative(process.cwd(), root)}`);
   if (skipped.length) log(`  skipped ${skipped.length} unreadable file(s)`);
-  log(`  wrote ${path33.relative(process.cwd(), target)}`);
+  log(`  wrote ${path32.relative(process.cwd(), target)}`);
   log(`
   Prompts are intentionally empty. To recover the real ones from your`);
   log(`  PixelLab account instead of inventing them:`);
   log(`
-    pixelkiln adopt --manifest ${path33.relative(process.cwd(), target)} --write-prompts
+    pixelkiln adopt --manifest ${path32.relative(process.cwd(), target)} --write-prompts
 `);
 }
 
 // src/pipeline/doctor.ts
-import { constants, existsSync as existsSync27 } from "fs";
+import { constants, existsSync as existsSync26 } from "fs";
 import { access, stat as stat4 } from "fs/promises";
-import path34 from "path";
+import path33 from "path";
 async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   const checks = [];
   const add = (id, level, message6) => checks.push({ id, level, message: message6 });
@@ -12200,8 +12258,8 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   );
   add("lock", "ok", `${Object.keys(lock.entries).length} valid v2 lock entr(ies)`);
   const dirs = [...new Set(specs.flatMap((spec) => [
-    path34.dirname(spec.outFile),
-    ...spec.quality ? [path34.dirname(spec.quality.outFile)] : []
+    path33.dirname(spec.outFile),
+    ...spec.quality ? [path33.dirname(spec.quality.outFile)] : []
   ]))];
   const unwritable = [];
   for (const dir of dirs) {
@@ -12224,7 +12282,7 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     for (let index = 0; index < entry.outputs.length; index++) {
       const output = entry.outputs[index];
       const spec = specByKey.get(key);
-      const absolute = spec ? currentEntryOutputPath(entry, spec, index) : resolveOutputPath(output.path, path34.dirname(lockPath));
+      const absolute = spec ? currentEntryOutputPath(entry, spec, index) : resolveOutputPath(output.path, path33.dirname(lockPath));
       const owner = outputOwners.get(absolute);
       if (owner && owner !== key) duplicateOutputs.push(`${output.path} (${owner}, ${key})`);
       outputOwners.set(absolute, key);
@@ -12239,7 +12297,7 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   } else {
     add("lock-outputs", "ok", `${outputOwners.size} recorded output path(s) are uniquely owned`);
   }
-  const cacheDir = path34.join(path34.dirname(lockPath), ".pixelkiln", "cache");
+  const cacheDir = path33.join(path33.dirname(lockPath), ".pixelkiln", "cache");
   const stranded = [];
   const invalidState = [];
   const staleMapUrls = [];
@@ -12255,11 +12313,11 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     const hasSource = Boolean(entry.sourceUrl || entry.sourceUrls?.length);
     let hasCache = false;
     for (const output of entry.outputs) {
-      const cached = path34.join(
+      const cached = path33.join(
         cacheDir,
         cacheFileName(output.sha256, output.mediaType ?? MediaType.PNG)
       );
-      if (existsSync27(cached) && await sha256File(cached) === output.sha256) {
+      if (existsSync26(cached) && await sha256File(cached) === output.sha256) {
         hasCache = true;
         break;
       }
@@ -12355,12 +12413,158 @@ async function nearestExistingDirectory(start) {
       if ((await stat4(current)).isDirectory()) return current;
     } catch {
     }
-    const parent = path34.dirname(current);
+    const parent = path33.dirname(current);
     if (parent === current) return current;
     current = parent;
   }
 }
 
+// src/pipeline/audit.ts
+import { readFile as readFile22 } from "fs/promises";
+import { existsSync as existsSync27 } from "fs";
+import path34 from "path";
+function paletteDistance(asset, reference) {
+  if (!asset.length || !reference.length) return 0;
+  let total = 0;
+  let weight = 0;
+  for (const color of asset) {
+    let nearest = Infinity;
+    for (const ref of reference) nearest = Math.min(nearest, colorDistance(color, ref));
+    total += nearest * color.weight;
+    weight += color.weight;
+  }
+  return weight === 0 ? 0 : total / weight;
+}
+function mergePalettes(palettes, topN = 24) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const palette of palettes) {
+    for (const color of palette) {
+      const key = `${color.r},${color.g},${color.b}`;
+      const existing = totals.get(key);
+      if (existing) existing.weight += color.weight;
+      else totals.set(key, { ...color });
+    }
+  }
+  const merged = [...totals.values()].sort((a, b) => b.weight - a.weight).slice(0, topN);
+  const sum = merged.reduce((s, c) => s + c.weight, 0) || 1;
+  return merged.map((c) => ({ ...c, weight: c.weight / sum }));
+}
+async function auditStyle(loaded, specs, styleId, lock) {
+  const style = loaded.manifest.styles[styleId];
+  if (!style) throw new Error(`Unknown style "${styleId}"`);
+  const mine = specs.filter((s) => s.styleId === styleId);
+  const assets = [];
+  const missing = [];
+  const unreadable = [];
+  for (const spec of mine) {
+    for (const output of resolveSpecOutputs(spec, lock, loaded.root)) {
+      if (!existsSync27(output.absolutePath)) {
+        missing.push(output.id);
+        continue;
+      }
+      try {
+        const png = decodePng(await readFile22(output.absolutePath));
+        const palette = extractPalette(png, 12);
+        assets.push({
+          assetId: spec.assetId,
+          ...output.role ? { outputRole: output.role } : {},
+          id: output.id,
+          file: output.absolutePath,
+          width: png.width,
+          height: png.height,
+          paletteDistance: 0,
+          // filled once the reference is known
+          transparency: transparencyRatio(png),
+          colorCount: countColors(png),
+          palette
+        });
+      } catch (err) {
+        unreadable.push(`${output.id}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+  let reference = [];
+  let referenceFromStyleImages = false;
+  const refPalettes = [];
+  for (const img of style.styleImages) {
+    const abs = path34.resolve(loaded.root, img.path);
+    if (!existsSync27(abs)) continue;
+    try {
+      refPalettes.push(extractPalette(decodePng(await readFile22(abs)), 12));
+    } catch {
+    }
+  }
+  if (refPalettes.length) {
+    reference = mergePalettes(refPalettes);
+    referenceFromStyleImages = true;
+    for (const asset of assets) {
+      asset.paletteDistance = paletteDistance(asset.palette, reference);
+    }
+  } else {
+    reference = mergePalettes(assets.map((a) => a.palette));
+    for (const asset of assets) {
+      const others = assets.filter((a) => a !== asset).map((a) => a.palette);
+      asset.paletteDistance = others.length ? paletteDistance(asset.palette, mergePalettes(others)) : 0;
+    }
+  }
+  assets.sort((a, b) => b.paletteDistance - a.paletteDistance);
+  return { styleId, referenceFromStyleImages, reference, assets, missing, unreadable };
+}
+function countColors(png) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < png.pixels.length; i += 4) {
+    if (png.pixels[i + 3] < 128) continue;
+    seen.add(png.pixels[i] << 16 | png.pixels[i + 1] << 8 | png.pixels[i + 2]);
+  }
+  return seen.size;
+}
+function outliers(audit, sigma = 1.5) {
+  const n = audit.assets.length;
+  if (n < 3) return [];
+  const mean = audit.assets.reduce((s, a) => s + a.paletteDistance, 0) / n;
+  const variance = audit.assets.reduce((s, a) => s + (a.paletteDistance - mean) ** 2, 0) / n;
+  const sd = Math.sqrt(variance);
+  if (sd === 0) return [];
+  return audit.assets.filter((a) => a.paletteDistance > mean + sigma * sd);
+}
+function evaluateAudit(audit, thresholds = {}) {
+  const resolved = { ...thresholds, sigma: thresholds.sigma ?? 1.5 };
+  const relative = outliers(audit, resolved.sigma);
+  const relativeIds = new Set(relative.map((asset) => asset.id));
+  const violations = [];
+  for (const asset of audit.assets) {
+    const reasons = [];
+    if (relativeIds.has(asset.id)) {
+      reasons.push(`palette outlier beyond ${resolved.sigma} standard deviations`);
+    }
+    if (resolved.maxDistance !== void 0 && asset.paletteDistance > resolved.maxDistance) {
+      reasons.push(
+        `palette distance ${asset.paletteDistance.toFixed(1)} exceeds ${resolved.maxDistance}`
+      );
+    }
+    if (resolved.minTransparency !== void 0 && asset.transparency < resolved.minTransparency) {
+      reasons.push(
+        `transparency ${(asset.transparency * 100).toFixed(1)}% is below ${(resolved.minTransparency * 100).toFixed(1)}%`
+      );
+    }
+    if (resolved.maxColors !== void 0 && asset.colorCount > resolved.maxColors) {
+      reasons.push(`color count ${asset.colorCount} exceeds ${resolved.maxColors}`);
+    }
+    if (reasons.length) violations.push({ id: asset.id, reasons });
+  }
+  return {
+    safe: violations.length === 0 && audit.missing.length === 0 && audit.unreadable.length === 0,
+    thresholds: resolved,
+    outliers: [...relativeIds],
+    violations,
+    missing: [...audit.missing],
+    unreadable: [...audit.unreadable]
+  };
+}
+function hex(c) {
+  return `#${[c.r, c.g, c.b].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+}
+
 // src/cli/commands/inspect.ts
 async function runStatus(args) {
   const { lock } = await openProject2(args);
@@ -13522,7 +13726,10 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   if (existsSync28(absolute) && !options.force) {
     const current = await readFile24(absolute);
     if (!current.equals(data)) {
-      throw new Error(`Quality baseline already exists with different content: ${absolute}. Pass --force to replace it.`);
+      throw new OverwriteRefusedError(
+        `Quality baseline already exists with different content: ${absolute}. Pass --force to replace it.`,
+        [absolute]
+      );
     }
   }
   const result = await writeArtifactBundle([{ path: absolute, data }]);
@@ -13913,7 +14120,7 @@ async function readRecipeFile(recipePath, bundled) {
 ` + parsed.error.issues.map((issue) => `  ${issue.path.join(".") || "$"}: ${issue.message}`).join("\n")
     );
   }
-  return { recipe: parsed.data, path: absolute, dir: path39.dirname(absolute), bundled };
+  return { recipe: parsed.data, authored: raw, path: absolute, dir: path39.dirname(absolute), bundled };
 }
 async function walkRecipeFiles(root) {
   if (!existsSync29(root)) return [];
@@ -13983,7 +14190,7 @@ async function verifyFile(root, file) {
 }
 async function verifyRecipe(target, options = {}) {
   const loaded = await resolveRecipe(target, options.bundledRoot);
-  const actualIntegrity = recipeDigest(loaded.recipe);
+  const actualIntegrity = recipeDigest(loaded.authored);
   const files = await Promise.all(loaded.recipe.files.map((file) => verifyFile(loaded.dir, file)));
   const modelRoot = options.modelRoot ? path39.resolve(options.modelRoot) : null;
   const models = modelRoot ? await Promise.all(loaded.recipe.models.map(async (model) => ({
@@ -14051,8 +14258,9 @@ async function installRecipe(target, options = {}) {
       if (!existsSync29(file.path)) continue;
       const current = await readFile26(file.path);
       if (!current.equals(file.data)) {
-        throw new Error(
-          `Recipe destination has local changes: ${file.path}. Choose another --out or pass --force to replace declared recipe files.`
+        throw new OverwriteRefusedError(
+          `Recipe destination has local changes: ${file.path}. Choose another --out or pass --force to replace declared recipe files.`,
+          [file.path]
         );
       }
     }
@@ -14519,9 +14727,12 @@ async function main(argv = process.argv.slice(2)) {
 
 // src/cli.ts
 main().catch((err) => {
+  const message6 = err instanceof Error ? err.message : String(err);
+  const hint = err instanceof PixelKilnError && err.hint ? `  ${err.hint}
+` : "";
   console.error(`
-  error: ${err instanceof Error ? err.message : String(err)}
-`);
-  process.exit(1);
+  error: ${message6}
+${hint}`);
+  process.exit(exitCodeFor(err));
 });
 //# sourceMappingURL=cli.js.map