pixelkiln 0.2.0 → 0.4.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import path16 from "path";
-import { existsSync as existsSync14 } from "fs";
-import { readFile as readFile13 } from "fs/promises";
+import path18 from "path";
+import { existsSync as existsSync15 } from "fs";
+import { readFile as readFile14 } from "fs/promises";
 
 // src/env.ts
 import { readFileSync, existsSync } from "fs";
@@ -38,6 +38,71 @@ function applyEnv(contents) {
   }
 }
 
+// src/provider.ts
+function validateCostEstimate(providerId, value) {
+  if (!value || typeof value !== "object") {
+    throw new Error(`Provider "${providerId}" returned an invalid cost estimate`);
+  }
+  const estimate = value;
+  if (typeof estimate.unit !== "string" || !estimate.unit.trim()) {
+    throw new Error(`Provider "${providerId}" returned an invalid cost unit`);
+  }
+  if (!Number.isFinite(estimate.amount) || estimate.amount < 0) {
+    throw new Error(`Provider "${providerId}" returned an invalid cost amount`);
+  }
+  if (estimate.unit === "free" && estimate.amount !== 0) {
+    throw new Error(`Provider "${providerId}" returned a nonzero amount with the free cost unit`);
+  }
+  if (!Number.isInteger(estimate.candidates) || estimate.candidates < 1) {
+    throw new Error(`Provider "${providerId}" returned an invalid candidate count`);
+  }
+  return estimate;
+}
+function measureBalanceChange(before, after) {
+  if (before.unit !== after.unit || !Number.isFinite(before.remaining) || !Number.isFinite(after.remaining)) return null;
+  const delta = before.remaining - after.remaining;
+  return {
+    unit: before.unit,
+    before: before.remaining,
+    after: after.remaining,
+    spent: Math.max(0, delta),
+    credited: Math.max(0, -delta)
+  };
+}
+var DEFAULT_RATE_LIMIT = { spacingMs: 2500, maxInFlight: 8 };
+var UnsupportedCapabilityError = class extends Error {
+  constructor(providerId, capability) {
+    super(
+      `Provider "${providerId}" does not support ${capability}. That command is unavailable with this backend.`
+    );
+    this.name = "UnsupportedCapabilityError";
+  }
+};
+function requireList(provider) {
+  if (!provider.list) throw new UnsupportedCapabilityError(provider.id, "listing remote assets");
+  return provider.list.bind(provider);
+}
+function requireDelete(provider) {
+  if (!provider.delete) throw new UnsupportedCapabilityError(provider.id, "deleting remote assets");
+  return provider.delete.bind(provider);
+}
+function requireSelectCandidate(provider) {
+  if (!provider.selectCandidate) {
+    throw new UnsupportedCapabilityError(provider.id, "candidate selection");
+  }
+  return provider.selectCandidate.bind(provider);
+}
+function requireBalance(provider) {
+  if (!provider.balance) throw new UnsupportedCapabilityError(provider.id, "account balance");
+  return provider.balance.bind(provider);
+}
+function formatCost(unit, amount) {
+  if (unit === "free") return "free";
+  if (unit === "usd") return `$${amount.toFixed(2)}`;
+  if (unit === "generations") return `${amount} generation${amount === 1 ? "" : "s"}`;
+  return `${amount} ${unit}`;
+}
+
 // src/providers/pixellab.ts
 import { mkdirSync, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { randomUUID } from "crypto";
@@ -154,11 +219,11 @@ var PixelLabClient = class {
    * common than the failure mode of retrying (a duplicate object), and a
    * duplicate is visible and free to delete whereas a silent gap is neither.
    */
-  async request(path17, init, attempt = 0) {
+  async request(path19, init, attempt = 0) {
     const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
     let res;
     try {
-      res = await fetch(`${BASE}${path17}`, {
+      res = await fetch(`${BASE}${path19}`, {
         ...init,
         signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs),
         headers: {
@@ -170,24 +235,24 @@ var PixelLabClient = class {
     } catch (err) {
       if (attempt < MAX_RETRIES) {
         await sleep(backoffMs(attempt));
-        return this.request(path17, init, attempt + 1);
+        return this.request(path19, init, attempt + 1);
       }
       throw err;
     }
     if (!res.ok && shouldRetry(res.status) && attempt < MAX_RETRIES) {
       const waitMs = retryAfterMs(res.headers.get("retry-after")) ?? backoffMs(attempt);
       await sleep(waitMs);
-      return this.request(path17, init, attempt + 1);
+      return this.request(path19, init, attempt + 1);
     }
     const text = await res.text();
     if (!res.ok) {
-      throw new PixelLabError(`${init?.method ?? "GET"} ${path17} \u2192 ${res.status}`, res.status, text);
+      throw new PixelLabError(`${init?.method ?? "GET"} ${path19} \u2192 ${res.status}`, res.status, text);
     }
     if (!text) return {};
     try {
       return JSON.parse(text);
     } catch {
-      throw new Error(`${init?.method ?? "GET"} ${path17} returned invalid JSON`);
+      throw new Error(`${init?.method ?? "GET"} ${path19} returned invalid JSON`);
     }
   }
   async balance() {
@@ -748,7 +813,8 @@ function parseHex(hex2) {
 
 // src/types.ts
 import { z as z2 } from "zod";
-var GeneratorSchema = z2.enum(["1dir", "map", "pixflux", "tiles"]);
+var MediaTypeSchema = z2.enum(["image/png", "image/gif"]);
+var GeneratorSchema = z2.enum(["1dir", "map", "pixflux", "tiles", "animation"]);
 function tileVariationCount(descriptions) {
   return Math.max(1, descriptions) * 4;
 }
@@ -780,7 +846,7 @@ function tilesCost(tileSize, variations) {
   return 40;
 }
 var StyleImageSchema = z2.object({
-  /** Path to a PNG/JPEG, relative to the manifest file. Max 256x256. */
+  /** Path to a PNG/JPEG, relative to the manifest; the active provider validates limits. */
   path: z2.string()
 });
 var StyleSchema = z2.object({
@@ -891,7 +957,9 @@ var StyleSchema = z2.object({
     out: z2.string()
   }).strict().optional(),
   /** Tags applied to every object generated in this style, for server-side filtering. */
-  tags: z2.array(z2.string()).default([])
+  tags: z2.array(z2.string()).default([]),
+  /** Adapter-owned settings, keyed by provider id. */
+  providerOptions: z2.record(z2.record(z2.unknown())).default({})
 }).strict().refine((s) => !(s.tileFeature && s.styleImages.length), {
   message: "tileFeature and styleImages cannot be combined \u2014 a connectable set derives its own tile geometry, so remove one or the other",
   path: ["tileFeature"]
@@ -906,7 +974,7 @@ var AssetSchema = z2.object({
   height: z2.number().int().min(16).max(400).optional(),
   /** Overrides the style default. `1dir` generator only. */
   size: z2.number().int().min(32).max(256).optional(),
-  /** Explicit output path relative to outDir. Defaults to `<category>/<id>.png`. */
+  /** Explicit output path relative to outDir. Media-aware providers may replace its extension. */
   file: z2.string().optional(),
   /**
    * Grid cell this asset owns in a mounted style, as [column, row].
@@ -958,6 +1026,8 @@ var AssetSchema = z2.object({
 var ManifestSchema = z2.object({
   $schema: z2.string().optional(),
   name: z2.string(),
+  /** Generation backend. Existing manifests remain PixelLab by default. */
+  provider: z2.string().min(1).default("pixellab"),
   styles: z2.record(StyleSchema),
   assets: z2.record(AssetSchema)
 }).strict();
@@ -995,7 +1065,8 @@ var LockEntrySchema = z2.object({
   sourceUrls: z2.array(
     z2.object({
       url: z2.string(),
-      role: z2.string().optional()
+      role: z2.string().optional(),
+      mediaType: MediaTypeSchema.optional()
     })
   ).default([]),
   /**
@@ -1010,7 +1081,8 @@ var LockEntrySchema = z2.object({
     z2.object({
       path: z2.string(),
       sha256: z2.string(),
-      role: z2.string().optional()
+      role: z2.string().optional(),
+      mediaType: MediaTypeSchema.optional()
     })
   ).default([]),
   /**
@@ -1024,7 +1096,7 @@ var LockEntrySchema = z2.object({
   /** Successful-submission estimate in `costUnit`; may be fractional USD. */
   cost: z2.number().finite().nonnegative().default(0),
   /** Unit for `cost`. Defaults preserve pre-unit PixelLab lockfiles. */
-  costUnit: z2.enum(["generations", "usd", "free"]).default("generations"),
+  costUnit: z2.string().min(1).default("generations"),
   /** Which provider produced this. Absent on entries written before providers. */
   provider: z2.string().default("pixellab")
 });
@@ -1094,7 +1166,44 @@ var PixelLabProvider = class _PixelLabProvider {
       candidates: spec.generator === "1dir" ? candidateCount(spec.size) : 1
     };
   }
+  validate(spec, styleImages) {
+    if (spec.generator === "map") {
+      requirePixelLabOption("view", spec.view, ["low top-down", "high top-down", "side"]);
+      requirePixelLabOption("outline", spec.outline, [
+        "single color outline",
+        "selective outline",
+        "lineless"
+      ]);
+      requirePixelLabOption("shading", spec.shading, [
+        "flat shading",
+        "basic shading",
+        "medium shading",
+        "detailed shading"
+      ]);
+      requirePixelLabOption("detail", spec.detail, [
+        "low detail",
+        "medium detail",
+        "high detail"
+      ]);
+    }
+    if ((spec.generator === "map" || spec.generator === "pixflux") && styleImages.length) {
+      throw new Error(`PixelLab ${spec.generator} does not support style images`);
+    }
+    for (const image of styleImages) {
+      if (image.width > 256 || image.height > 256) {
+        throw new Error(
+          `Style image exceeds PixelLab's 256x256 limit (${image.width}x${image.height})`
+        );
+      }
+    }
+    if (spec.tags.length > 20) {
+      throw new Error(
+        `${spec.styleId}/${spec.assetId} resolves to ${spec.tags.length} tags, but PixelLab allows at most 20`
+      );
+    }
+  }
   async submit(spec, styleImages) {
+    this.validate(spec, styleImages);
     if (spec.generator === "pixflux") {
       const swatch = spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0;
       const { png } = await this.client.createImagePixflux({
@@ -1280,6 +1389,11 @@ var PixelLabProvider = class _PixelLabProvider {
     await this.client.deleteObject(assetId);
   }
 };
+function requirePixelLabOption(name, value, allowed) {
+  if (value != null && !allowed.includes(value)) {
+    throw new Error(`PixelLab map ${name} must be one of: ${allowed.join(", ")}`);
+  }
+}
 function tilesInIndexOrder(urls) {
   return Object.entries(urls).map(([key, url]) => ({ index: Number(key.replace(/^tile_/, "")), url })).filter((tile) => Number.isFinite(tile.index)).sort((a, b) => a.index - b.index);
 }
@@ -1288,60 +1402,442 @@ function firstUrl(urls) {
   return Object.values(urls).find((u) => typeof u === "string") ?? null;
 }
 
-// src/provider.ts
-function validateCostEstimate(providerId, value) {
-  if (!value || typeof value !== "object") {
-    throw new Error(`Provider "${providerId}" returned an invalid cost estimate`);
+// src/media.ts
+var MediaType = {
+  PNG: "image/png",
+  GIF: "image/gif"
+};
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function mediaExtension(mediaType) {
+  return mediaType === MediaType.GIF ? ".gif" : ".png";
+}
+function mediaTypeFromExtension(file) {
+  const lower = file.toLowerCase();
+  if (lower.endsWith(".png")) return MediaType.PNG;
+  if (lower.endsWith(".gif")) return MediaType.GIF;
+  return null;
+}
+function detectMediaType(bytes) {
+  if (bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) return MediaType.PNG;
+  const header = bytes.subarray(0, 6).toString("ascii");
+  if (header === "GIF87a" || header === "GIF89a") return MediaType.GIF;
+  return null;
+}
+function validateMedia(bytes, expected) {
+  const actual = detectMediaType(bytes);
+  if (!actual) throw new Error(`response was not a supported PNG or GIF (${bytes.length} bytes)`);
+  if (expected && actual !== expected) {
+    throw new Error(`response was ${actual}, expected ${expected}`);
   }
-  const estimate = value;
-  if (!["generations", "usd", "free"].includes(estimate.unit)) {
-    throw new Error(`Provider "${providerId}" returned an invalid cost unit`);
+  if (actual === MediaType.PNG) {
+    decodePng(bytes);
+  } else {
+    validateGif(bytes);
+  }
+  return actual;
+}
+function validateGif(bytes) {
+  if (bytes.length < 14) throw new Error("invalid GIF: truncated logical screen descriptor");
+  const width = bytes.readUInt16LE(6);
+  const height = bytes.readUInt16LE(8);
+  if (!width || !height) throw new Error("invalid GIF: zero-sized logical screen");
+  const packed = bytes[10];
+  let offset = 13;
+  if (packed & 128) offset += 3 * 2 ** ((packed & 7) + 1);
+  if (offset > bytes.length) throw new Error("invalid GIF: truncated global color table");
+  let sawImage = false;
+  while (offset < bytes.length) {
+    const marker = bytes[offset];
+    if (marker === 59) {
+      if (!sawImage) throw new Error("invalid GIF: contains no image frame");
+      return;
+    }
+    if (marker === 44) {
+      if (offset + 10 > bytes.length) throw new Error("invalid GIF: truncated image descriptor");
+      const imagePacked = bytes[offset + 9];
+      offset += 10;
+      if (imagePacked & 128) offset += 3 * 2 ** ((imagePacked & 7) + 1);
+      if (offset >= bytes.length) throw new Error("invalid GIF: missing image data");
+      offset++;
+      offset = skipSubBlocks(bytes, offset);
+      sawImage = true;
+      continue;
+    }
+    if (marker === 33) {
+      if (offset + 2 > bytes.length) throw new Error("invalid GIF: truncated extension");
+      offset = skipSubBlocks(bytes, offset + 2);
+      continue;
+    }
+    throw new Error(`invalid GIF: unexpected block marker 0x${marker.toString(16)}`);
   }
-  if (!Number.isFinite(estimate.amount) || estimate.amount < 0) {
-    throw new Error(`Provider "${providerId}" returned an invalid cost amount`);
+  throw new Error("invalid GIF: missing trailer");
+}
+function skipSubBlocks(bytes, start) {
+  let offset = start;
+  for (; ; ) {
+    if (offset >= bytes.length) throw new Error("invalid GIF: truncated data blocks");
+    const size = bytes[offset];
+    offset++;
+    if (size === 0) return offset;
+    offset += size;
+    if (offset > bytes.length) throw new Error("invalid GIF: truncated data block");
   }
-  if (estimate.unit === "free" && estimate.amount !== 0) {
-    throw new Error(`Provider "${providerId}" returned a nonzero amount with the free cost unit`);
+}
+function cacheFileName(hash, mediaType = MediaType.PNG) {
+  return `${hash}${mediaExtension(mediaType)}`;
+}
+
+// src/providers/retrodiffusion.ts
+var DEFAULT_BASE_URL = "https://api.retrodiffusion.ai/v1";
+var RetroDiffusionClient = class {
+  constructor(token, baseUrl = DEFAULT_BASE_URL, request = fetch) {
+    this.token = token;
+    this.baseUrl = baseUrl;
+    this.request = request;
+  }
+  token;
+  baseUrl;
+  request;
+  async submit(body) {
+    const response = await this.call("/inferences", { method: "POST", body: JSON.stringify(body) });
+    const taskId = response.task_id;
+    if (typeof taskId !== "string" || !taskId) {
+      throw new Error("Retro Diffusion did not return an async task id");
+    }
+    return taskId;
+  }
+  async quote(body) {
+    const response = await this.call("/inferences", {
+      method: "POST",
+      body: JSON.stringify({ ...body, check_cost: true })
+    });
+    const amount = response.balance_cost;
+    if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) {
+      throw new Error("Retro Diffusion returned an invalid cost quote");
+    }
+    return amount;
   }
-  if (!Number.isInteger(estimate.candidates) || estimate.candidates < 1) {
-    throw new Error(`Provider "${providerId}" returned an invalid candidate count`);
+  async task(id) {
+    return await this.call(`/inferences/tasks/${encodeURIComponent(id)}`);
   }
-  return estimate;
+  async balance() {
+    const response = await this.call("/inferences/credits");
+    const balance = response.balance;
+    if (typeof balance !== "number" || !Number.isFinite(balance)) {
+      throw new Error("Retro Diffusion returned an invalid balance");
+    }
+    return balance;
+  }
+  async call(path19, init = {}) {
+    if (!this.token) throw new Error("RD_API_KEY is not set");
+    const response = await this.request(`${this.baseUrl}${path19}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        "X-RD-Token": this.token,
+        ...init.headers
+      }
+    });
+    const text = await response.text();
+    let value = null;
+    try {
+      value = text ? JSON.parse(text) : null;
+    } catch {
+      value = text;
+    }
+    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` : "")
+      );
+    }
+    return value;
+  }
+};
+var RetroDiffusionProvider = class _RetroDiffusionProvider {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  id = "retrodiffusion";
+  static fromEnv() {
+    return new _RetroDiffusionProvider(new RetroDiffusionClient(process.env.RD_API_KEY));
+  }
+  static forOffline() {
+    return new _RetroDiffusionProvider(new RetroDiffusionClient(void 0));
+  }
+  static forDownloads() {
+    return _RetroDiffusionProvider.forOffline();
+  }
+  supports(generator) {
+    return generator === "map" || generator === "pixflux" || generator === "tiles" || generator === "animation";
+  }
+  estimate(spec) {
+    const options = retroOptions(spec);
+    const style = resolvedPromptStyle(spec, options);
+    const count = options.numImages ?? 1;
+    const pixels = spec.width * spec.height;
+    let each;
+    if (style.startsWith("rd_advanced_animation__")) {
+      each = /__(?:custom_action|subtle_motion)$/.test(style) ? 0.25 : 0.14;
+    } else if (style.startsWith("rd_animation__")) {
+      each = /__(?:any_animation|8_dir_rotation)$/.test(style) ? 0.25 : 0.07;
+    } else if (/^rd_tile__tileset(?:_advanced)?$/.test(style)) {
+      each = 0.1;
+    } else if (style.startsWith("rd_pro__")) {
+      each = 0.18;
+    } else if (style.startsWith("rd_fast__")) {
+      each = Math.max(0.015, (pixels + 1e5) / 6e6);
+    } else if (isLowResolutionStyle(style)) {
+      each = Math.max(0.02, (pixels + 13700) / 6e5);
+    } else {
+      each = Math.max(0.025, (pixels + 5e4) / 2e6);
+    }
+    return { unit: "usd", amount: roundUsdEstimate(each * count), candidates: count };
+  }
+  validate(spec, styleImages) {
+    const options = retroOptions(spec);
+    const promptStyle = resolvedPromptStyle(spec, options);
+    const count = options.numImages ?? 1;
+    const isAnimation = /^(?:rd_animation__|rd_advanced_animation__)/.test(promptStyle);
+    const isTile = promptStyle.startsWith("rd_tile__");
+    if (!promptStyle || spec.generator === "animation" && !isAnimation || spec.generator === "tiles" && !isTile || spec.generator !== "animation" && spec.generator !== "tiles" && (isAnimation || isTile)) {
+      throw new Error(
+        `Retro Diffusion style "${promptStyle}" does not match generator "${spec.generator}"`
+      );
+    }
+    if (!Number.isInteger(count) || count < 1 || count > 16) {
+      throw new Error("Retro Diffusion numImages must be a whole number from 1 to 16");
+    }
+    if (spec.width < 16 || spec.height < 16 || spec.width > 512 || spec.height > 512) {
+      throw new Error("Retro Diffusion output dimensions must be between 16 and 512 pixels");
+    }
+    if (styleImages.length > 9) {
+      throw new Error("Retro Diffusion accepts at most 9 reference images");
+    }
+    if (spec.generator === "animation") {
+      if (count !== 1) throw new Error("Retro Diffusion animations currently require numImages: 1");
+      validateAnimation(promptStyle, spec, styleImages, options);
+    } else if (spec.generator === "tiles") {
+      validateTile(promptStyle, spec, styleImages, count, options);
+    } else if (styleImages.length && !/^(?:rd_pro__|user__)/.test(promptStyle)) {
+      throw new Error(
+        `Retro Diffusion style "${promptStyle}" does not accept reference_images; use an RD Pro or user style`
+      );
+    }
+  }
+  async submit(spec, styleImages) {
+    this.validate(spec, styleImages);
+    const options = retroOptions(spec);
+    const promptStyle = resolvedPromptStyle(spec, options);
+    const animation = spec.generator === "animation";
+    const tiles = spec.generator === "tiles";
+    const body = {
+      prompt: spec.prompt,
+      prompt_style: promptStyle,
+      width: spec.width,
+      height: spec.height,
+      num_images: options.numImages ?? 1,
+      ...!animation && !tiles ? { remove_bg: options.removeBg ?? spec.noBackground } : {},
+      ...spec.seed != null ? { seed: spec.seed } : {},
+      ...animation || tiles ? styleImages[0] ? { input_image: styleImages[0].base64 } : {} : styleImages.length ? { reference_images: styleImages.map((image) => image.base64) } : {},
+      ...tiles && styleImages[1] ? { extra_input_image: styleImages[1].base64 } : {},
+      ...tiles && options.extraPrompt ? { extra_prompt: options.extraPrompt } : {},
+      ...animation && options.framesDuration ? { frames_duration: options.framesDuration } : {},
+      ...animation && options.returnSpritesheet ? { return_spritesheet: true } : {},
+      ...!animation && options.tileX != null ? { tile_x: options.tileX } : {},
+      ...!animation && options.tileY != null ? { tile_y: options.tileY } : {},
+      ...spec.palette.length ? { input_palette: paletteSwatch(spec.palette).toString("base64") } : {}
+    };
+    const quoted = await this.client.quote(body);
+    const estimated = this.estimate(spec).amount;
+    if (quoted > estimated + 1e-6) {
+      throw new Error(
+        `Retro Diffusion quoted $${quoted.toFixed(6)}, above the offline estimate $${estimated.toFixed(6)}; no paid request was sent`
+      );
+    }
+    return {
+      jobId: await this.client.submit({ ...body, async: true, upload_outputs: true })
+    };
+  }
+  async poll(jobId, generator, context) {
+    const task = await this.client.task(jobId);
+    if (task.status === "pending" || task.status === "running") return { status: "processing" };
+    if (task.status === "failed") return { status: "failed", error: retroError(task.error) };
+    if (task.status !== "succeeded") {
+      return { status: "failed", error: `Retro Diffusion returned unknown task status "${String(task.status)}"` };
+    }
+    const options = context?.spec ? retroOptions(context.spec) : {};
+    const mediaType = generator === "animation" && !options.returnSpritesheet ? MediaType.GIF : MediaType.PNG;
+    const sources = resultSources(task.result, mediaType);
+    const urls = sources.map((source) => source.url);
+    if (!urls.length) return { status: "failed", error: "Retro Diffusion task returned no images" };
+    if (urls.length > 1) return { status: "review", candidateUrls: urls };
+    return {
+      status: "ready",
+      objectId: `${jobId}#0`,
+      sourceUrl: urls[0],
+      sources,
+      metadata: {
+        balanceCost: task.result?.balance_cost ?? null,
+        remainingBalance: task.result?.remaining_balance ?? null,
+        mediaType,
+        kind: generator === "animation" ? "animation" : generator === "tiles" ? "tileset" : "image",
+        ...context?.spec ? {
+          promptStyle: resolvedPromptStyle(context.spec, options),
+          width: context.spec.width,
+          height: context.spec.height
+        } : {}
+      }
+    };
+  }
+  async selectCandidate(jobId, index) {
+    const task = await this.client.task(jobId);
+    if (task.status !== "succeeded") throw new Error(`Retro Diffusion task ${jobId} is not ready`);
+    const url = resultSources(task.result, MediaType.PNG)[index]?.url;
+    if (!url) throw new Error(`Retro Diffusion task ${jobId} has no candidate at index ${index}`);
+    return { objectId: `${jobId}#${index}`, sourceUrl: url };
+  }
+  async download(url) {
+    const data = /^data:[^;]+;base64,(.+)$/.exec(url)?.[1];
+    if (data) return Buffer.from(data, "base64");
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Retro Diffusion download failed (${response.status})`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+  async balance() {
+    return { unit: "usd", remaining: await this.client.balance() };
+  }
+};
+function retroOptions(spec) {
+  return spec.providerOptions;
+}
+function resultSources(result, mediaType) {
+  const hosted = (result?.output_urls ?? []).filter((url) => typeof url === "string" && url.length > 0).map((url) => ({ url, mediaType }));
+  if (hosted.length) return hosted;
+  return (result?.base64_images ?? []).filter((data) => typeof data === "string" && data.length > 0).map((data) => ({
+    url: `data:${mediaType};base64,${data}`,
+    mediaType
+  }));
 }
-function measureBalanceChange(before, after) {
-  if (before.unit !== after.unit || !Number.isFinite(before.remaining) || !Number.isFinite(after.remaining)) return null;
-  const delta = before.remaining - after.remaining;
-  return {
-    unit: before.unit,
-    before: before.remaining,
-    after: after.remaining,
-    spent: Math.max(0, delta),
-    credited: Math.max(0, -delta)
-  };
+function resolvedPromptStyle(spec, options) {
+  return options.promptStyle ?? (spec.generator === "animation" ? "rd_animation__any_animation" : spec.generator === "tiles" ? "rd_tile__tileset" : "rd_plus__default");
 }
-var DEFAULT_RATE_LIMIT = { spacingMs: 2500, maxInFlight: 8 };
-var UnsupportedCapabilityError = class extends Error {
-  constructor(providerId, capability) {
-    super(
-      `Provider "${providerId}" does not support ${capability}. That command is unavailable with this backend.`
-    );
-    this.name = "UnsupportedCapabilityError";
+function validateAnimation(style, spec, styleImages, options) {
+  if (spec.width !== spec.height) throw new Error("Retro Diffusion animations must be square");
+  if (style.startsWith("rd_advanced_animation__")) {
+    if (styleImages.length !== 1) {
+      throw new Error(`Retro Diffusion advanced animation style "${style}" requires one input image`);
+    }
+    if (spec.width < 32 || spec.width > 256) {
+      throw new Error("Retro Diffusion advanced animations require dimensions from 32 to 256 pixels");
+    }
+  } else if (styleImages.length > 1) {
+    throw new Error("Retro Diffusion prompt animations accept at most one input image");
+  }
+  const exact = style.includes("four_angle_walking") ? 48 : style.endsWith("__small_sprites") ? 32 : style.endsWith("__any_animation") ? 64 : style.endsWith("__big_animation") ? 128 : style.endsWith("__8_dir_rotation") ? 80 : null;
+  if (exact && spec.width !== exact) {
+    throw new Error(`Retro Diffusion style "${style}" requires ${exact}x${exact} dimensions`);
+  }
+  if (style.endsWith("__vfx") && (spec.width < 24 || spec.width > 96)) {
+    throw new Error("Retro Diffusion VFX animations require dimensions from 24 to 96 pixels");
+  }
+  if (options.framesDuration != null && ![4, 6, 8, 10, 12, 16].includes(options.framesDuration)) {
+    throw new Error("Retro Diffusion framesDuration must be 4, 6, 8, 10, 12, or 16");
   }
-};
-function requireList(provider) {
-  if (!provider.list) throw new UnsupportedCapabilityError(provider.id, "listing remote assets");
-  return provider.list.bind(provider);
 }
-function requireDelete(provider) {
-  if (!provider.delete) throw new UnsupportedCapabilityError(provider.id, "deleting remote assets");
-  return provider.delete.bind(provider);
+function validateTile(style, spec, styleImages, count, options) {
+  if (spec.width !== spec.height) throw new Error("Retro Diffusion tiles must be square");
+  const size = spec.width;
+  if (/^rd_tile__tileset(?:_advanced)?$/.test(style)) {
+    if (size < 16 || size > 32) throw new Error("Retro Diffusion tilesets require 16\u201332px tiles");
+    if (count !== 1) throw new Error("Retro Diffusion tilesets require numImages: 1");
+  } else if (style === "rd_tile__single_tile" && (size < 16 || size > 64)) {
+    throw new Error("Retro Diffusion single tiles require dimensions from 16 to 64 pixels");
+  } else if (style === "rd_tile__tile_variation") {
+    if (size < 16 || size > 128) throw new Error("Retro Diffusion tile variations require 16\u2013128px tiles");
+    if (styleImages.length !== 1) throw new Error("Retro Diffusion tile variations require one input image");
+  } else if (style === "rd_tile__tile_object" && (size < 16 || size > 96)) {
+    throw new Error("Retro Diffusion tile objects require dimensions from 16 to 96 pixels");
+  } else if (style === "rd_tile__scene_object" && (size < 64 || size > 384)) {
+    throw new Error("Retro Diffusion tile scene objects require dimensions from 64 to 384 pixels");
+  }
+  if (style === "rd_tile__tileset" && styleImages.length > 1) {
+    throw new Error("Retro Diffusion basic tilesets accept at most one input image");
+  }
+  if (style === "rd_tile__tileset_advanced") {
+    if (styleImages.length > 2) throw new Error("Retro Diffusion advanced tilesets accept at most two input images");
+    if (!options.extraPrompt && styleImages.length < 2) {
+      throw new Error("Retro Diffusion advanced tilesets require extraPrompt or a second input image");
+    }
+  }
 }
-function formatCost(unit, amount) {
-  if (unit === "free") return "free";
-  if (unit === "usd") return `$${amount.toFixed(2)}`;
-  return `${amount} generation${amount === 1 ? "" : "s"}`;
+function isLowResolutionStyle(style) {
+  return /(?:^|__)(?:mc_|low_res|classic|skill_icon|topdown_item)/.test(style);
+}
+function roundUsdEstimate(value) {
+  return Math.ceil((value - 1e-9) * 1e3) / 1e3;
+}
+function retroError(value) {
+  if (typeof value === "string") return value || "unknown error";
+  if (!value || typeof value !== "object") return "unknown error";
+  const record = value;
+  if (typeof record.message === "string") return record.message;
+  if (typeof record.detail === "string") return record.detail;
+  if (Array.isArray(record.detail)) {
+    const details = record.detail.map((item) => {
+      if (!item || typeof item !== "object") return String(item);
+      const detail = item;
+      return typeof detail.msg === "string" ? detail.msg : JSON.stringify(item);
+    }).filter(Boolean);
+    if (details.length) return details.join("; ");
+  }
+  if (record.detail && typeof record.detail === "object") {
+    const message2 = record.detail.message;
+    if (typeof message2 === "string") return message2;
+  }
+  return JSON.stringify(value);
 }
 
+// src/providers/registry.ts
+var factories = /* @__PURE__ */ new Map();
+function registerProvider(factory) {
+  const id = factory.id.trim();
+  if (!id) throw new Error("Provider id cannot be empty");
+  if (factories.has(id)) throw new Error(`Provider "${id}" is already registered`);
+  factories.set(id, factory);
+}
+function providerFactory(id) {
+  const factory = factories.get(id);
+  if (!factory) {
+    const available = [...factories.keys()].sort().join(", ") || "(none)";
+    throw new Error(`Unknown provider "${id}". Available providers: ${available}`);
+  }
+  return factory;
+}
+function createProvider(id, mode2) {
+  return providerFactory(id).create(mode2);
+}
+registerProvider({
+  id: "pixellab",
+  credentialEnv: "PIXELLAB_API_KEY",
+  create(mode2) {
+    if (mode2 === "online") return PixelLabProvider.fromEnv();
+    if (mode2 === "downloads") return PixelLabProvider.forDownloads();
+    return PixelLabProvider.forOffline();
+  }
+});
+registerProvider({
+  id: "retrodiffusion",
+  credentialEnv: "RD_API_KEY",
+  create(mode2) {
+    if (mode2 === "online") return RetroDiffusionProvider.fromEnv();
+    if (mode2 === "downloads") return RetroDiffusionProvider.forDownloads();
+    return RetroDiffusionProvider.forOffline();
+  }
+});
+
 // src/manifest.ts
 import { readFile as readFile2 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
@@ -1353,12 +1849,16 @@ import { readFile } from "fs/promises";
 function sha256(data) {
   return createHash("sha256").update(data).digest("hex");
 }
-async function sha256File(path17) {
-  return sha256(await readFile(path17));
+async function sha256File(path19) {
+  return sha256(await readFile(path19));
 }
 function specHash(spec, styleImageHashes) {
   return sha256(
     JSON.stringify({
+      // Preserve every existing PixelLab hash while making a provider switch
+      // invalidate the spec. Older manifests implicitly mean pixellab.
+      provider: spec.provider === "pixellab" ? void 0 : spec.provider,
+      providerOptions: Object.keys(spec.providerOptions).length > 0 ? spec.providerOptions : void 0,
       generator: spec.generator,
       prompt: spec.prompt,
       width: spec.width,
@@ -1372,7 +1872,7 @@ function specHash(spec, styleImageHashes) {
       // `noBackground` only reaches the wire for pixflux; the tile fields are
       // undefined for every other generator. `tileSize` is intentionally
       // absent — width/height are derived from it, so it is already covered.
-      noBackground: spec.generator === "pixflux" ? spec.noBackground : void 0,
+      noBackground: spec.generator === "pixflux" || spec.provider !== "pixellab" ? spec.noBackground : void 0,
       tileType: spec.tileType,
       tileView: spec.tileView,
       tileFeature: spec.tileFeature,
@@ -1412,6 +1912,7 @@ ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
 }
 async function resolveSpecs(loaded, filter) {
   const { manifest, root } = loaded;
+  const activeProvider = filter?.provider ?? createProvider(manifest.provider, "offline");
   const specs = [];
   const styleIds = Object.keys(manifest.styles).filter(
     (id) => !filter?.styles?.length || filter.styles.includes(id)
@@ -1437,10 +1938,8 @@ async function resolveSpecs(loaded, filter) {
       const buf = await readFile2(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 || metadata.width > 256 || metadata.height > 256) {
-        throw new Error(
-          `Style image exceeds the API's 256x256 limit: ${abs} (${metadata.width}x${metadata.height})`
-        );
+      if (metadata.width < 1 || metadata.height < 1) {
+        throw new Error(`Style image has invalid dimensions: ${abs}`);
       }
       hit = { base64: buf.toString("base64"), hash: sha256(buf), ...metadata };
       styleImageCache.set(abs, hit);
@@ -1460,8 +1959,8 @@ async function resolveSpecs(loaded, filter) {
       if (filter?.assets?.length && !filter.assets.includes(assetId)) continue;
       if (asset.styles.length && !asset.styles.includes(styleId)) continue;
       const generator = style.generator;
-      if (filter?.provider && !filter.provider.supports(generator)) {
-        throw new Error(`Provider "${filter.provider.id}" does not support generator "${generator}"`);
+      if (!activeProvider.supports(generator)) {
+        throw new Error(`Provider "${activeProvider.id}" does not support generator "${generator}"`);
       }
       let width;
       let height;
@@ -1488,6 +1987,8 @@ async function resolveSpecs(loaded, filter) {
       const base = {
         styleId,
         assetId,
+        provider: activeProvider.id,
+        providerOptions: style.providerOptions[activeProvider.id] ?? {},
         generator,
         prompt,
         width,
@@ -1519,11 +2020,6 @@ async function resolveSpecs(loaded, filter) {
           `style:${styleId}`
         ])
       ];
-      if (tags.length > 20) {
-        throw new Error(
-          `${styleId}/${assetId} resolves to ${tags.length} tags, but PixelLab allows at most 20`
-        );
-      }
       const resolved = {
         ...base,
         root,
@@ -1532,12 +2028,15 @@ async function resolveSpecs(loaded, filter) {
         source: asset.source,
         specHash: specHash(base, styleImageHashes)
       };
-      if (filter?.provider) {
-        const estimate = validateCostEstimate(filter.provider.id, filter.provider.estimate(resolved));
-        resolved.cost = estimate.amount;
-        resolved.costUnit = estimate.unit;
-        resolved.candidates = estimate.candidates;
-      }
+      const resolvedImages = style.styleImages.map((image) => {
+        const hit = styleImageCache.get(path3.resolve(root, image.path));
+        return { base64: hit.base64, width: hit.width, height: hit.height, format: hit.format };
+      });
+      activeProvider.validate?.(resolved, resolvedImages);
+      const estimate = validateCostEstimate(activeProvider.id, activeProvider.estimate(resolved));
+      resolved.cost = estimate.amount;
+      resolved.costUnit = estimate.unit;
+      resolved.candidates = estimate.candidates;
       specs.push(resolved);
     }
   }
@@ -1561,10 +2060,8 @@ async function resolveStyleImages(loaded, styleId) {
     const buf = await readFile2(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 || metadata.width > 256 || metadata.height > 256) {
-      throw new Error(
-        `Style image exceeds the API's 256x256 limit: ${file} (${metadata.width}x${metadata.height})`
-      );
+    if (metadata.width < 1 || metadata.height < 1) {
+      throw new Error(`Style image has invalid dimensions: ${file}`);
     }
     out.push({ base64: buf.toString("base64"), ...metadata });
   }
@@ -1770,7 +2267,8 @@ async function acquireFileLock(file) {
 function spendByUnit(lock) {
   const totals = { generations: 0, usd: 0, free: 0 };
   for (const entry of Object.values(lock.entries)) {
-    totals[entry.costUnit ?? "generations"] += entry.cost ?? 0;
+    const unit = entry.costUnit ?? "generations";
+    totals[unit] = (totals[unit] ?? 0) + (entry.cost ?? 0);
   }
   return totals;
 }
@@ -1788,16 +2286,16 @@ function resolveOutputPath(recordedPath, manifestDir) {
   if (path5.win32.isAbsolute(recordedPath)) return recordedPath;
   return path5.resolve(manifestDir, recordedPath.split(/[\\/]/).join(path5.sep));
 }
-function expectedOutputPath(spec, role, index, total) {
-  if (total === 1) return spec.outFile;
+function expectedOutputPath(spec, role, index, total, mediaType) {
   const originalExt = path5.extname(spec.outFile);
-  const ext = originalExt || ".png";
+  const ext = mediaType ? mediaExtension(mediaType) : originalExt || ".png";
   const stem = originalExt ? spec.outFile.slice(0, -originalExt.length) : spec.outFile;
+  if (total === 1) return `${stem}${ext}`;
   const safeRole = (role ?? fallbackOutputRole(index)).replace(/[^a-zA-Z0-9_-]+/g, "-");
   return `${stem}-${safeRole}${ext}`;
 }
 function currentOutputPath(output, spec, index, total) {
-  return expectedOutputPath(spec, output.role, index, total);
+  return expectedOutputPath(spec, output.role, index, total, output.mediaType);
 }
 function currentEntryOutputPath(entry, spec, index) {
   const output = entry.outputs[index];
@@ -2255,7 +2753,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
   async function pruneInFlight() {
     for (const [id, spec] of [...inFlight]) {
       try {
-        const state = await provider.poll(id, spec.generator, spec);
+        const state = await provider.poll(id, spec.generator, { spec, tileFeature: spec.tileFeature });
         if (state.status !== "processing") inFlight.delete(id);
         lastSlotError = null;
       } catch (err) {
@@ -2307,7 +2805,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
     await saveLock(lockPath, lock);
     lastSubmitAt = Date.now();
     try {
-      const refs = spec.generator === "1dir" || spec.generator === "tiles" ? styleImages.get(spec.styleId) ?? [] : [];
+      const refs = styleImages.get(spec.styleId) ?? [];
       const { jobId } = await provider.submit(spec, refs);
       upsert(lock, key, {
         jobId,
@@ -2357,7 +2855,8 @@ async function poll(provider, lock, lockPath, opts = {}) {
       try {
         const currentSpec = specByKey.get(key);
         const state = await provider.poll(entry.jobId, entry.generator, {
-          tileFeature: entry.tileFeature ?? currentSpec?.tileFeature
+          tileFeature: entry.tileFeature ?? currentSpec?.tileFeature,
+          spec: currentSpec
         });
         if (state.status === "review") {
           upsert(lock, key, { status: "review", reviewObjectId: entry.jobId });
@@ -2395,7 +2894,6 @@ async function poll(provider, lock, lockPath, opts = {}) {
 import { existsSync as existsSync6 } from "fs";
 import { mkdir as mkdir2, readFile as readFile4, rename as rename2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
 import path8 from "path";
-var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   const log2 = opts.onProgress ?? (() => {
   });
@@ -2427,7 +2925,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
         result.skipped++;
         continue;
       }
-      const sources = entry.sourceUrls?.length ? entry.sourceUrls : entry.sourceUrl ? [{ url: entry.sourceUrl }] : opts.repair && entry.outputs.length ? entry.outputs.map((o) => ({ url: "", role: o.role })) : [];
+      const sources = entry.sourceUrls?.length ? entry.sourceUrls : entry.sourceUrl ? [{ url: entry.sourceUrl }] : opts.repair && entry.outputs.length ? entry.outputs.map((o) => ({ url: "", role: o.role, mediaType: o.mediaType })) : [];
       if (!sources.length) {
         upsert(lock, key, {
           status: "download-failed",
@@ -2443,7 +2941,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           const recorded = entry.outputs.find(
             (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);
+          const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length, source.mediaType);
           if (existsSync6(target)) {
             if (!recorded) {
               throw new Error(`refusing to overwrite untracked output ${target}`);
@@ -2451,11 +2949,19 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             if (await sha256File(target) !== recorded.sha256) {
               throw new Error(`refusing to overwrite modified output ${target}`);
             }
-            if (cacheDir) await cachePng(cacheDir, await readFile4(target), recorded.sha256);
+            if (cacheDir) {
+              await cacheMedia(
+                cacheDir,
+                await readFile4(target),
+                recorded.mediaType ?? MediaType.PNG,
+                recorded.sha256
+              );
+            }
             outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
             continue;
           }
-          let buf = recorded && cacheDir ? await readCachedPng(cacheDir, recorded.sha256) : null;
+          const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
+          let buf = recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null;
           if (buf) {
             log2(`  cached  ${path8.relative(process.cwd(), target)}`);
           } else {
@@ -2464,24 +2970,25 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             }
             buf = await provider.download(source.url);
           }
-          if (!buf.subarray(0, 8).equals(PNG_SIGNATURE)) {
-            throw new Error(`response for ${source.role ?? "asset"} was not a PNG (${buf.length} bytes)`);
-          }
+          let mediaType;
           try {
-            decodePng(buf);
+            mediaType = validateMedia(buf, expectedMediaType);
           } catch (err) {
+            const label = expectedMediaType === MediaType.GIF ? "GIF" : "PNG";
+            const mismatch = detectMediaType(buf) !== expectedMediaType;
             throw new Error(
-              `response for ${source.role ?? "asset"} was not a valid PNG: ${err instanceof Error ? err.message : String(err)}`
+              `response for ${source.role ?? "asset"} was not ${mismatch ? "a" : "a valid"} ${label}` + (mismatch ? ` (${buf.length} bytes)` : `: ${err instanceof Error ? err.message : String(err)}`)
             );
           }
-          if (cacheDir) await cachePng(cacheDir, buf);
+          if (cacheDir) await cacheMedia(cacheDir, buf, mediaType);
           await mkdir2(path8.dirname(target), { recursive: true });
           const tmp = `${target}.pixelkiln.tmp`;
           await writeFile2(tmp, buf);
           outputs.push({
             path: portableOutputPath(target, spec.root),
             sha256: sha256(buf),
-            ...source.role ? { role: source.role } : {}
+            ...source.role ? { role: source.role } : {},
+            mediaType
           });
           upsert(lock, key, { outputs: mergeOutputs(entry.outputs, outputs) });
           await saveLock(lockPath, lock);
@@ -2518,22 +3025,23 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   await saveLock(lockPath, lock);
   return result;
 }
-async function readCachedPng(cacheDir, hash) {
-  const file = path8.join(cacheDir, `${hash}.png`);
+async function readCachedMedia(cacheDir, hash, mediaType) {
+  const file = path8.join(cacheDir, cacheFileName(hash, mediaType));
   if (!existsSync6(file)) return null;
   try {
     const buf = await readFile4(file);
-    if (!buf.subarray(0, 8).equals(PNG_SIGNATURE) || sha256(buf) !== hash) return null;
-    decodePng(buf);
+    if (sha256(buf) !== hash) return null;
+    validateMedia(buf, mediaType);
     return buf;
   } catch {
     return null;
   }
 }
-async function cachePng(cacheDir, buf, knownHash) {
+async function cacheMedia(cacheDir, buf, mediaType, knownHash) {
   const hash = knownHash ?? sha256(buf);
-  const file = path8.join(cacheDir, `${hash}.png`);
-  if (await readCachedPng(cacheDir, hash)) return;
+  validateMedia(buf, mediaType);
+  const file = path8.join(cacheDir, cacheFileName(hash, mediaType));
+  if (await readCachedMedia(cacheDir, hash, mediaType)) return;
   await mkdir2(cacheDir, { recursive: true });
   const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   await writeFile2(tmp, buf);
@@ -2638,7 +3146,10 @@ 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 = path9.join(cacheDir, `${output.sha256}.png`);
+      const cached = path9.join(
+        cacheDir,
+        cacheFileName(output.sha256, output.mediaType ?? MediaType.PNG)
+      );
       if (existsSync7(cached) && await sha256File(cached) === output.sha256) {
         hasCache = true;
         break;
@@ -2668,11 +3179,14 @@ async function doctor(loaded, specs, lock, lockPath, opts = {}) {
     add(
       "provider",
       "error",
-      opts.apiKeyPresent === false ? "PIXELLAB_API_KEY is not configured" : "provider is not configured"
+      opts.apiKeyPresent === false ? `${opts.credentialEnv ?? "PIXELLAB_API_KEY"} is not configured` : "provider is not configured"
     );
+  } else if (!opts.provider.balance) {
+    add("provider", "ok", `${opts.provider.id} configured; balance reporting unavailable`);
   } else {
+    const balanceFn = opts.provider.balance.bind(opts.provider);
     try {
-      const balance = await opts.provider.balance();
+      const balance = await balanceFn();
       add("provider", "ok", `${opts.provider.id} reachable; ${balance.remaining} ${balance.unit} remaining`);
     } catch (err) {
       add("provider", "error", `provider connectivity failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -2715,10 +3229,10 @@ function isSha256Hash(value) {
 function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
-async function loadCache(path17) {
-  if (!existsSync8(path17)) return { version: 1, hashes: {} };
+async function loadCache(path19) {
+  if (!existsSync8(path19)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile5(path17, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile5(path19, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -2730,18 +3244,18 @@ async function loadCache(path17) {
     return { version: 1, hashes: {} };
   }
 }
-async function saveCache(path17, cache) {
+async function saveCache(path19, cache) {
   const sorted = {};
   for (const key of Object.keys(cache.hashes).sort()) {
     const hash = cache.hashes[key];
     if (!isSha256Hash(hash)) throw new Error(`Refusing to cache invalid SHA-256 for ${key}`);
     sorted[key] = hash;
   }
-  await mkdir3(pathModule.dirname(pathModule.resolve(path17)), { recursive: true });
-  const tmp = `${path17}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await mkdir3(pathModule.dirname(pathModule.resolve(path19)), { recursive: true });
+  const tmp = `${path19}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile3(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
-    await rename3(tmp, path17);
+    await rename3(tmp, path19);
   } finally {
     await rm3(tmp, { force: true });
   }
@@ -3259,7 +3773,7 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
         const entry = lock.entries[key];
         if (!group || !entry?.reviewObjectId) continue;
         if (!Number.isInteger(index) || index < 0 || index >= group.frameUrls.length) continue;
-        const { objectId, sourceUrl } = await provider.selectCandidate(
+        const { objectId, sourceUrl } = await requireSelectCandidate(provider)(
           entry.reviewObjectId,
           index,
           `asset:${entry.assetId}`,
@@ -3349,6 +3863,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
   }
   return {
     name,
+    provider: "pixellab",
     styles: {
       [styleId]: {
         generator,
@@ -3361,7 +3876,8 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
         styleImages: [],
         palette: [],
         outDir,
-        tags: [name]
+        tags: [name],
+        providerOptions: {}
       }
     },
     assets
@@ -3382,6 +3898,7 @@ async function writeManifestFile(target, manifest) {
 // src/pipeline/salvage.ts
 import { readFile as readFile8 } from "fs/promises";
 import { existsSync as existsSync11 } from "fs";
+import path12 from "path";
 async function loadClaims(lockPaths) {
   const claimed = /* @__PURE__ */ new Set();
   for (const p of lockPaths) {
@@ -3429,6 +3946,26 @@ function matchStyleByPattern(prompt, manifest) {
   }
   return null;
 }
+async function loadSiblingManifests(ownManifestPath, workspaceManifestPaths, claimPaths) {
+  const own = path12.resolve(ownManifestPath);
+  const siblingManifestPaths = [
+    .../* @__PURE__ */ new Set([
+      ...workspaceManifestPaths,
+      ...claimPaths.map((c) => path12.join(path12.dirname(path12.resolve(c)), "pixelkiln.manifest.json"))
+    ])
+  ];
+  const siblings = [];
+  for (const siblingManifestPath of siblingManifestPaths) {
+    if (path12.resolve(siblingManifestPath) === own) continue;
+    if (!existsSync11(siblingManifestPath)) continue;
+    try {
+      const { manifest } = await loadManifest(siblingManifestPath);
+      siblings.push({ label: path12.basename(path12.dirname(siblingManifestPath)), manifest });
+    } catch {
+    }
+  }
+  return siblings;
+}
 function groupOrphansByStyle(orphans, manifest, siblings = []) {
   const matched = /* @__PURE__ */ new Map();
   const elsewhere = /* @__PURE__ */ new Map();
@@ -3538,10 +4075,237 @@ async function applyTags(provider, decisions, existing, opts = {}) {
   return { tagged, failed };
 }
 
-// src/pipeline/audit.ts
-import { readFile as readFile9 } from "fs/promises";
+// src/workspace.ts
+import { mkdir as mkdir4, readFile as readFile9, rename as rename4, rm as rm4, writeFile as writeFile6 } from "fs/promises";
 import { existsSync as existsSync12 } from "fs";
-import path12 from "path";
+import path13 from "path";
+import { z as z4 } from "zod";
+var WorkspaceProjectSchema = z4.object({
+  id: z4.string().min(1),
+  /** Manifest path, relative to the catalog file's own directory. */
+  manifest: z4.string().min(1),
+  /** Lockfile path, relative to the catalog file's own directory. */
+  lock: z4.string().min(1),
+  provider: z4.string().min(1).default("pixellab"),
+  /** Free-form label for a shared account, e.g. distinguishing sandboxes. */
+  account: z4.string().optional()
+}).strict();
+var WorkspaceSchema = z4.object({
+  version: z4.literal(1),
+  projects: z4.array(WorkspaceProjectSchema).default([])
+}).strict();
+function parseWorkspace(raw) {
+  const parsed = WorkspaceSchema.safeParse(raw);
+  if (parsed.success) return parsed.data;
+  throw new Error(
+    `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 (!existsSync12(workspacePath)) return { version: 1, projects: [] };
+  let raw;
+  try {
+    raw = JSON.parse(await readFile9(workspacePath, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `Workspace catalog at ${workspacePath} is malformed:
+${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return parseWorkspace(raw);
+}
+async function saveWorkspace(workspacePath, ws) {
+  const sorted = {
+    version: 1,
+    projects: [...ws.projects].sort((a, b) => a.id.localeCompare(b.id))
+  };
+  await mkdir4(path13.dirname(path13.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");
+    await rename4(tmp, workspacePath);
+  } finally {
+    await rm4(tmp, { force: true });
+  }
+}
+function toPortablePath(dir, absolute) {
+  return path13.relative(dir, absolute).split(path13.sep).join("/");
+}
+function resolveProject(dir, project) {
+  return {
+    manifestPath: path13.resolve(dir, project.manifest.split("/").join(path13.sep)),
+    lockPath: path13.resolve(dir, project.lock.split("/").join(path13.sep))
+  };
+}
+function validateWorkspace(ws, dir) {
+  const diagnostics = [];
+  const idCounts = /* @__PURE__ */ new Map();
+  const lockOwners = /* @__PURE__ */ new Map();
+  const manifestOwners = /* @__PURE__ */ new Map();
+  for (const project of ws.projects) {
+    idCounts.set(project.id, (idCounts.get(project.id) ?? 0) + 1);
+    const { manifestPath, lockPath } = resolveProject(dir, project);
+    lockOwners.set(lockPath, [...lockOwners.get(lockPath) ?? [], project.id]);
+    manifestOwners.set(manifestPath, [...manifestOwners.get(manifestPath) ?? [], project.id]);
+    if (path13.isAbsolute(project.manifest) || path13.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 (!existsSync12(manifestPath)) {
+      diagnostics.push({
+        id: "missing-manifest",
+        level: "error",
+        message: `project "${project.id}" manifest not found: ${manifestPath}`
+      });
+    }
+    if (!existsSync12(lockPath)) {
+      diagnostics.push({
+        id: "missing-lock",
+        level: "error",
+        message: `project "${project.id}" lockfile not found: ${lockPath}`
+      });
+    }
+  }
+  for (const [id, count] of idCounts) {
+    if (count > 1) {
+      diagnostics.push({
+        id: "duplicate-id",
+        level: "error",
+        message: `project id "${id}" is registered ${count} times`
+      });
+    }
+  }
+  for (const [lockPath, ids] of lockOwners) {
+    if (ids.length > 1) {
+      diagnostics.push({
+        id: "duplicate-lock",
+        level: "error",
+        message: `${ids.join(", ")} all register the same lockfile: ${lockPath}`
+      });
+    }
+  }
+  for (const [manifestPath, ids] of manifestOwners) {
+    if (ids.length > 1) {
+      diagnostics.push({
+        id: "duplicate-manifest",
+        level: "warning",
+        message: `${ids.join(", ")} share manifest ${manifestPath} \u2014 expected only when they are variant lockfiles beside one manifest`
+      });
+    }
+  }
+  const providers = new Set(ws.projects.map((p) => p.provider));
+  if (providers.size > 1) {
+    diagnostics.push({
+      id: "mixed-provider",
+      level: "warning",
+      message: `registered projects use different providers: ${[...providers].sort().join(", ")} \u2014 spend totals are kept separate per unit, but confirm this is intentional`
+    });
+  }
+  return diagnostics;
+}
+
+// src/pipeline/workspace.ts
+async function workspaceClaims(ws, dir) {
+  const lockPaths = [];
+  const byProject = {};
+  const claimed = /* @__PURE__ */ new Set();
+  for (const project of ws.projects) {
+    const { lockPath } = resolveProject(dir, project);
+    lockPaths.push(lockPath);
+    let projectClaims;
+    try {
+      projectClaims = await loadClaims([lockPath]);
+    } catch (err) {
+      throw new Error(
+        `Project "${project.id}" lockfile is unreadable: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    byProject[project.id] = projectClaims.size;
+    for (const id of projectClaims) claimed.add(id);
+  }
+  return { claimed, byProject, lockPaths };
+}
+function emptyStateCounts() {
+  return {
+    ok: 0,
+    missing: 0,
+    untracked: 0,
+    stale: 0,
+    orphaned: 0,
+    "in-flight": 0,
+    recoverable: 0,
+    failed: 0
+  };
+}
+async function workspaceStatus(ws, dir) {
+  const diagnostics = validateWorkspace(ws, dir);
+  const projects = [];
+  const totalsByState = emptyStateCounts();
+  const totalsSpend = { generations: 0, usd: 0, free: 0 };
+  for (const project of ws.projects) {
+    const { manifestPath, lockPath } = resolveProject(dir, project);
+    const base = {
+      id: project.id,
+      provider: project.provider,
+      account: project.account ?? null,
+      manifest: manifestPath,
+      lock: lockPath
+    };
+    try {
+      const provider = createProvider(project.provider, "offline");
+      const loaded = await loadManifest(manifestPath);
+      const specs = await resolveSpecs(loaded, { provider });
+      const lock = await loadLock(lockPath);
+      normalizeLockOutputPaths(lock, specs);
+      const plan = await buildPlan(specs, lock);
+      const byState = summarize(plan);
+      const spend = spendByUnit(lock);
+      for (const state of Object.keys(byState)) {
+        totalsByState[state] += byState[state];
+      }
+      for (const unit of Object.keys(spend)) {
+        totalsSpend[unit] = (totalsSpend[unit] ?? 0) + (spend[unit] ?? 0);
+      }
+      projects.push({
+        ...base,
+        entries: Object.keys(lock.entries).length,
+        byState,
+        spendByUnit: spend,
+        error: null
+      });
+    } catch (err) {
+      projects.push({
+        ...base,
+        entries: 0,
+        byState: emptyStateCounts(),
+        spendByUnit: { generations: 0, usd: 0, free: 0 },
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  let claims = 0;
+  try {
+    claims = (await workspaceClaims(ws, dir)).claimed.size;
+  } catch {
+  }
+  return {
+    version: 1,
+    safe: !diagnostics.some((d) => d.level === "error") && projects.every((p) => !p.error),
+    dir,
+    projects,
+    totals: { byState: totalsByState, spendByUnit: totalsSpend, claims },
+    diagnostics
+  };
+}
+
+// src/pipeline/audit.ts
+import { readFile as readFile10 } from "fs/promises";
+import { existsSync as existsSync13 } from "fs";
+import path14 from "path";
 function colorDistance(a, b) {
   const rmean = (a.r + b.r) / 2;
   const dr = a.r - b.r;
@@ -3586,12 +4350,12 @@ async function auditStyle(loaded, specs, styleId, lock) {
   const unreadable = [];
   for (const spec of mine) {
     for (const output of resolveSpecOutputs(spec, lock, loaded.root)) {
-      if (!existsSync12(output.absolutePath)) {
+      if (!existsSync13(output.absolutePath)) {
         missing.push(output.id);
         continue;
       }
       try {
-        const png = decodePng(await readFile9(output.absolutePath));
+        const png = decodePng(await readFile10(output.absolutePath));
         const palette = extractPalette(png, 12);
         assets.push({
           assetId: spec.assetId,
@@ -3615,10 +4379,10 @@ async function auditStyle(loaded, specs, styleId, lock) {
   let referenceFromStyleImages = false;
   const refPalettes = [];
   for (const img of style.styleImages) {
-    const abs = path12.resolve(loaded.root, img.path);
-    if (!existsSync12(abs)) continue;
+    const abs = path14.resolve(loaded.root, img.path);
+    if (!existsSync13(abs)) continue;
     try {
-      refPalettes.push(extractPalette(decodePng(await readFile9(abs)), 12));
+      refPalettes.push(extractPalette(decodePng(await readFile10(abs)), 12));
     } catch {
     }
   }
@@ -3694,16 +4458,15 @@ function hex(c) {
 }
 
 // src/pipeline/cache-health.ts
-import { existsSync as existsSync13 } from "fs";
-import { readFile as readFile10, readdir as readdir2, rm as rm4 } from "fs/promises";
-import path13 from "path";
-var PNG_SIGNATURE2 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+import { existsSync as existsSync14 } from "fs";
+import { readFile as readFile11, readdir as readdir2, rm as rm5 } from "fs/promises";
+import path15 from "path";
 async function inspectCaches(lock, lockPath, options = {}) {
-  if (options.prune && !existsSync13(lockPath)) {
-    throw new Error(`Refusing to prune without an existing lockfile at ${path13.resolve(lockPath)}`);
+  if (options.prune && !existsSync14(lockPath)) {
+    throw new Error(`Refusing to prune without an existing lockfile at ${path15.resolve(lockPath)}`);
   }
-  const contentDir = path13.resolve(path13.dirname(lockPath), ".pixelkiln", "cache");
-  const remotePath = path13.resolve(cachePathFor(lockPath));
+  const contentDir = path15.resolve(path15.dirname(lockPath), ".pixelkiln", "cache");
+  const remotePath = path15.resolve(cachePathFor(lockPath));
   const referenced = new Set(
     Object.values(lock.entries).flatMap((entry) => entry.outputs.map((output) => output.sha256))
   );
@@ -3717,7 +4480,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
     ]);
     for (const name of names) {
       try {
-        await rm4(path13.join(contentDir, name), { force: true });
+        await rm5(path15.join(contentDir, name), { force: true });
         removed.contentFiles++;
       } catch {
       }
@@ -3726,7 +4489,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 readFile10(remotePath, "utf8")));
+      const cache = parseCache(JSON.parse(await readFile11(remotePath, "utf8")));
       for (const id of remoteHashes.invalidIds) delete cache.hashes[id];
       removed.remoteHashEntries = remoteHashes.invalidIds.length;
       await saveCache(remotePath, cache);
@@ -3744,7 +4507,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
 async function inspectContentCache(contentDir, referenced) {
   const report = {
     path: contentDir,
-    exists: existsSync13(contentDir),
+    exists: existsSync14(contentDir),
     files: 0,
     bytes: 0,
     valid: 0,
@@ -3765,11 +4528,12 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     report.files++;
-    const file = path13.join(contentDir, entry.name);
-    const expected = entry.name.endsWith(".png") ? entry.name.slice(0, -4) : "";
+    const file = path15.join(contentDir, entry.name);
+    const mediaType = mediaTypeFromExtension(entry.name);
+    const expected = mediaType ? entry.name.slice(0, -4) : "";
     let bytes;
     try {
-      bytes = await readFile10(file);
+      bytes = await readFile11(file);
       report.bytes += bytes.length;
     } catch (err) {
       report.invalid.push({
@@ -3779,11 +4543,7 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     if (!isSha256Hash(expected)) {
-      report.invalid.push({ name: entry.name, reason: "filename is not <sha256>.png" });
-      continue;
-    }
-    if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE2)) {
-      report.invalid.push({ name: entry.name, reason: "not a PNG" });
+      report.invalid.push({ name: entry.name, reason: "filename is not <sha256>.png or <sha256>.gif" });
       continue;
     }
     if (sha256(bytes) !== expected) {
@@ -3791,11 +4551,11 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     try {
-      decodePng(bytes);
+      validateMedia(bytes, mediaType);
     } catch (err) {
       report.invalid.push({
         name: entry.name,
-        reason: `invalid PNG: ${err instanceof Error ? err.message : String(err)}`
+        reason: `invalid ${mediaType === "image/gif" ? "GIF" : "PNG"}: ${err instanceof Error ? err.message : String(err)}`
       });
       continue;
     }
@@ -3811,7 +4571,7 @@ async function inspectContentCache(contentDir, referenced) {
 async function inspectRemoteHashCache(remotePath) {
   const report = {
     path: remotePath,
-    exists: existsSync13(remotePath),
+    exists: existsSync14(remotePath),
     entries: 0,
     valid: 0,
     invalidIds: [],
@@ -3820,7 +4580,7 @@ async function inspectRemoteHashCache(remotePath) {
   if (!report.exists) return report;
   let cache;
   try {
-    cache = parseCache(JSON.parse(await readFile10(remotePath, "utf8")));
+    cache = parseCache(JSON.parse(await readFile11(remotePath, "utf8")));
   } catch (err) {
     report.error = err instanceof Error ? err.message : String(err);
     return report;
@@ -4091,8 +4851,8 @@ function isRecord(value) {
 }
 
 // src/pick/salvage-server.ts
-import { mkdir as mkdir4, writeFile as writeFile6, readFile as readFile11 } from "fs/promises";
-import path14 from "path";
+import { mkdir as mkdir5, writeFile as writeFile7, readFile as readFile12 } from "fs/promises";
+import path16 from "path";
 
 // src/pick/salvage-sheet.ts
 var escapeHtml2 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -4251,13 +5011,13 @@ refresh();
 }
 
 // src/pick/salvage-server.ts
-var PNG_SIGNATURE3 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+var PNG_SIGNATURE2 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 async function runSalvage(provider, orphans, ctx, opts = {}) {
   const log2 = opts.onProgress ?? (() => {
   });
   const html = renderSalvageSheet(orphans, {
     styleId: ctx.styleId,
-    importDir: path14.relative(process.cwd(), ctx.importDir) || "."
+    importDir: path16.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]));
@@ -4283,13 +5043,13 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
         if (decision.action === "import") {
           try {
             const buf = await provider.download(orphan.previewUrl);
-            if (!buf.subarray(0, 8).equals(PNG_SIGNATURE3)) throw new Error("not a PNG");
+            if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
             decodePng(buf);
             const assetId = idFromPrompt(orphan.prompt, taken);
-            const rel = path14.join("_salvaged", `${assetId}.png`);
-            const outFile = path14.resolve(ctx.importDir, rel);
-            await mkdir4(path14.dirname(outFile), { recursive: true });
-            await writeFile6(outFile, buf);
+            const rel = path16.join("_salvaged", `${assetId}.png`);
+            const outFile = path16.resolve(ctx.importDir, rel);
+            await mkdir5(path16.dirname(outFile), { recursive: true });
+            await writeFile7(outFile, buf);
             ctx.manifest.assets[assetId] = {
               prompt: orphan.prompt,
               promptByStyle: {},
@@ -4315,7 +5075,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               error: null,
               sourceUrl: orphan.previewUrl,
               outputs: [{
-                path: portableOutputPath(outFile, path14.dirname(ctx.manifestPath)),
+                path: portableOutputPath(outFile, path16.dirname(ctx.manifestPath)),
                 sha256: sha256(buf)
               }],
               submittedAt: orphan.createdAt,
@@ -4339,9 +5099,9 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
         }
       }
       await applyTags(provider, decisions, existingTags, { onProgress: log2 });
-      const raw = JSON.parse(await readFile11(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 writeFile6(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
+      await writeFile7(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
       await saveLock(ctx.lockPath, ctx.lock);
       return result;
     }
@@ -4349,9 +5109,9 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
 }
 
 // src/artifacts.ts
-import path15 from "path";
+import path17 from "path";
 import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
-import { mkdir as mkdir5, readFile as readFile12, rename as rename4, rm as rm5, writeFile as writeFile7 } from "fs/promises";
+import { mkdir as mkdir6, readFile as readFile13, rename as rename5, rm as rm6, writeFile as writeFile8 } from "fs/promises";
 var activeTransactions = /* @__PURE__ */ new Set();
 function message(error) {
   return error instanceof Error ? error.message : String(error);
@@ -4360,7 +5120,7 @@ function digest(data) {
   return createHash2("sha256").update(data).digest("hex");
 }
 function portableRelative(from, to) {
-  return path15.relative(from, path15.resolve(to)).split(path15.sep).join("/") || ".";
+  return path17.relative(from, path17.resolve(to)).split(path17.sep).join("/") || ".";
 }
 function canonical(value) {
   if (value === null || typeof value === "string" || typeof value === "boolean") return value;
@@ -4411,7 +5171,7 @@ function parseArtifactManifest(absolute, data) {
 }
 async function readOptional(file) {
   try {
-    return await readFile12(file);
+    return await readFile13(file);
   } catch (error) {
     if (isCode(error, "ENOENT")) return null;
     throw error;
@@ -4430,8 +5190,8 @@ function processIsAlive(pid) {
   }
 }
 function validTemporaryPath(candidate, destination, type) {
-  return path15.dirname(candidate) === path15.dirname(destination) && path15.basename(candidate).startsWith(
-    `.${path15.basename(destination)}.pixelkiln-${type}-`
+  return path17.dirname(candidate) === path17.dirname(destination) && path17.basename(candidate).startsWith(
+    `.${path17.basename(destination)}.pixelkiln-${type}-`
   );
 }
 function parseTransaction(journal, data) {
@@ -4447,14 +5207,14 @@ function parseTransaction(journal, data) {
   return raw;
 }
 async function removeTransactionFiles(journal) {
-  await rm5(journal, { force: true });
-  await rm5(transactionMarker(journal), { force: true });
+  await rm6(journal, { force: true });
+  await rm6(transactionMarker(journal), { force: true });
 }
 async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
-  const journal = path15.resolve(recoveryFile);
+  const journal = path17.resolve(recoveryFile);
   const bytes = await readOptional(journal);
   if (!bytes) {
-    await rm5(transactionMarker(journal), { force: true });
+    await rm6(transactionMarker(journal), { force: true });
     return;
   }
   if (activeTransactions.has(journal)) {
@@ -4467,7 +5227,7 @@ async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
     );
   }
   for (const entry of transaction.entries) {
-    if (typeof entry.destination !== "string" || typeof entry.stage !== "string" || typeof entry.sha256 !== "string" || entry.backup !== void 0 && typeof entry.backup !== "string" || !allowedDestinations.has(path15.resolve(entry.destination)) || !validTemporaryPath(entry.stage, entry.destination, "stage") || entry.backup !== void 0 && !validTemporaryPath(entry.backup, entry.destination, "backup")) {
+    if (typeof entry.destination !== "string" || typeof entry.stage !== "string" || typeof entry.sha256 !== "string" || entry.backup !== void 0 && typeof entry.backup !== "string" || !allowedDestinations.has(path17.resolve(entry.destination)) || !validTemporaryPath(entry.stage, entry.destination, "stage") || entry.backup !== void 0 && !validTemporaryPath(entry.backup, entry.destination, "backup")) {
       throw new Error(
         `Refusing unsafe artifact recovery from ${journal}; its destinations or temporary paths do not match the current bundle.`
       );
@@ -4493,7 +5253,7 @@ async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
         }
         await remove2(entry.destination, errors);
         try {
-          await rename4(entry.backup, entry.destination);
+          await rename5(entry.backup, entry.destination);
         } catch (error) {
           errors.push(
             `could not restore ${entry.destination}; previous file remains at ${entry.backup}: ${message(error)}`
@@ -4513,7 +5273,7 @@ async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
   await removeTransactionFiles(journal);
 }
 function createArtifactBundleManifest(manifestPath, outputs, provenance) {
-  const root = path15.dirname(path15.resolve(manifestPath));
+  const root = path17.dirname(path17.resolve(manifestPath));
   const sources = provenance.sources.map((source) => ({
     ...source,
     path: portableRelative(root, source.path)
@@ -4543,11 +5303,11 @@ function withArtifactManifest(manifestPath, outputs, provenance) {
   ];
 }
 async function writeManagedArtifactBundle(manifestPath, outputs, provenance, options = {}) {
-  const absoluteManifest = path15.resolve(manifestPath);
+  const absoluteManifest = path17.resolve(manifestPath);
   const recoveryFile = `${absoluteManifest}.transaction`;
   const allowedDestinations = /* @__PURE__ */ new Set([
     absoluteManifest,
-    ...outputs.map((output) => path15.resolve(output.path))
+    ...outputs.map((output) => path17.resolve(output.path))
   ]);
   await recoverArtifactTransaction(recoveryFile, allowedDestinations);
   const existingManifestBytes = await readOptional(absoluteManifest);
@@ -4565,13 +5325,13 @@ async function writeManagedArtifactBundle(manifestPath, outputs, provenance, opt
     }
   }
   if (!options.force) {
-    const root = path15.dirname(absoluteManifest);
+    const root = path17.dirname(absoluteManifest);
     const recorded = new Map(
-      previous?.outputs.map((output) => [path15.resolve(root, output.path), output.sha256]) ?? []
+      previous?.outputs.map((output) => [path17.resolve(root, output.path), output.sha256]) ?? []
     );
     const conflicts = [];
     for (const output of outputs) {
-      const destination = path15.resolve(output.path);
+      const destination = path17.resolve(output.path);
       const current = await readOptional(destination);
       if (!current || digest(current) === digest(output.data)) continue;
       const expected = recorded.get(destination);
@@ -4596,7 +5356,7 @@ function isCode(error, code) {
 }
 async function remove2(file, errors) {
   try {
-    await rm5(file, { force: true });
+    await rm6(file, { force: true });
   } catch (error) {
     errors?.push(`could not remove ${file}: ${message(error)}`);
   }
@@ -4609,7 +5369,7 @@ async function rollback(prepared) {
   for (const artifact of [...prepared].reverse()) {
     if (!artifact.backup || !artifact.backedUp) continue;
     try {
-      await rename4(artifact.backup, artifact.destination);
+      await rename5(artifact.backup, artifact.destination);
       artifact.backedUp = false;
     } catch (error) {
       errors.push(
@@ -4626,7 +5386,7 @@ async function writeArtifactBundle(files, options = {}) {
   if (!files.length) throw new Error("An artifact bundle must contain at least one file.");
   const normalized = files.map((file) => {
     if (!file.path.trim()) throw new Error("Artifact paths cannot be empty.");
-    return { destination: path15.resolve(file.path), data: Buffer.from(file.data) };
+    return { destination: path17.resolve(file.path), data: Buffer.from(file.data) };
   });
   const destinations = /* @__PURE__ */ new Set();
   for (const artifact of normalized) {
@@ -4642,7 +5402,7 @@ async function writeArtifactBundle(files, options = {}) {
   const unchanged = [];
   for (const artifact of normalized) {
     try {
-      const current = await readFile12(artifact.destination);
+      const current = await readFile13(artifact.destination);
       if (current.equals(artifact.data)) {
         unchanged.push(artifact.destination);
       } else {
@@ -4656,21 +5416,21 @@ async function writeArtifactBundle(files, options = {}) {
   if (!changed.length) return { changed: [], unchanged };
   const token = randomUUID2();
   for (const [index, artifact] of changed.entries()) {
-    const basename = path15.basename(artifact.destination);
-    artifact.stage = path15.join(
-      path15.dirname(artifact.destination),
+    const basename = path17.basename(artifact.destination);
+    artifact.stage = path17.join(
+      path17.dirname(artifact.destination),
       `.${basename}.pixelkiln-stage-${token}-${index}`
     );
     if (artifact.existed) {
-      artifact.backup = path15.join(
-        path15.dirname(artifact.destination),
+      artifact.backup = path17.join(
+        path17.dirname(artifact.destination),
         `.${basename}.pixelkiln-backup-${token}-${index}`
       );
     }
   }
-  const journal = options.recoveryFile ? path15.resolve(options.recoveryFile) : null;
+  const journal = options.recoveryFile ? path17.resolve(options.recoveryFile) : null;
   if (journal) {
-    await mkdir5(path15.dirname(journal), { recursive: true });
+    await mkdir6(path17.dirname(journal), { recursive: true });
     const transaction = {
       format: "pixelkiln-artifact-transaction",
       version: 1,
@@ -4684,7 +5444,7 @@ async function writeArtifactBundle(files, options = {}) {
       }))
     };
     try {
-      await writeFile7(journal, JSON.stringify(transaction, null, 2) + "\n", { flag: "wx" });
+      await writeFile8(journal, JSON.stringify(transaction, null, 2) + "\n", { flag: "wx" });
       activeTransactions.add(journal);
     } catch (error) {
       throw new Error(
@@ -4695,9 +5455,9 @@ async function writeArtifactBundle(files, options = {}) {
   }
   try {
     for (const [index, artifact] of changed.entries()) {
-      await mkdir5(path15.dirname(artifact.destination), { recursive: true });
+      await mkdir6(path17.dirname(artifact.destination), { recursive: true });
       await options.beforeStage?.(artifact.destination, index);
-      await writeFile7(artifact.stage, artifact.data, { flag: "wx" });
+      await writeFile8(artifact.stage, artifact.data, { flag: "wx" });
     }
   } catch (error) {
     const cleanupErrors2 = await rollback(changed);
@@ -4710,17 +5470,17 @@ async function writeArtifactBundle(files, options = {}) {
   try {
     for (const artifact of changed) {
       if (!artifact.existed) continue;
-      await rename4(artifact.destination, artifact.backup);
+      await rename5(artifact.destination, artifact.backup);
       artifact.backedUp = true;
     }
     for (const [index, artifact] of changed.entries()) {
       await options.beforePromote?.(artifact.destination, index);
-      await rename4(artifact.stage, artifact.destination);
+      await rename5(artifact.stage, artifact.destination);
       artifact.stage = void 0;
       artifact.promoted = true;
     }
     if (journal) {
-      await writeFile7(transactionMarker(journal), `${token}
+      await writeFile8(transactionMarker(journal), `${token}
 `, { flag: "wx" });
       durableCommit = true;
       await options.afterCommit?.();
@@ -4765,11 +5525,11 @@ async function writeArtifactBundle(files, options = {}) {
 // src/cli.ts
 var log = (msg = "") => console.log(msg);
 async function provenanceFile(id, file) {
-  const absolute = path16.resolve(file);
+  const absolute = path18.resolve(file);
   return {
     id,
     path: absolute,
-    sha256: existsSync14(absolute) ? await sha256File(absolute) : null,
+    sha256: existsSync15(absolute) ? await sha256File(absolute) : null,
     included: true
   };
 }
@@ -4793,7 +5553,10 @@ var VALUE_FLAGS = [
   "--max-distance",
   "--min-transparency",
   "--max-colors",
-  "--sigma"
+  "--sigma",
+  "--workspace",
+  "--provider",
+  "--account"
 ];
 var BOOL_FLAGS = [
   "--force",
@@ -4832,18 +5595,43 @@ var COMMANDS = [
   "tag",
   "balance",
   "status",
+  "workspace",
   "help",
   "--help",
   "-h",
   "--version",
   "-v"
 ];
+var WORKSPACE_SUBCOMMANDS = ["add", "remove", "list", "status", "claims"];
 function parseArgs(argv) {
   const [command = "help"] = argv;
   if (!COMMANDS.includes(command)) {
     throw new Error(`Unknown command "${command}". Run \`pixelkiln help\` for the list.`);
   }
-  const rest = argv.slice(1);
+  let rest = argv.slice(1);
+  let subcommand;
+  let target;
+  if (command === "workspace") {
+    subcommand = rest[0];
+    if (subcommand === void 0 || subcommand.startsWith("-")) {
+      throw new Error(`workspace needs a subcommand: ${WORKSPACE_SUBCOMMANDS.join(", ")}`);
+    }
+    if (!WORKSPACE_SUBCOMMANDS.includes(subcommand)) {
+      throw new Error(
+        `Unknown workspace subcommand "${subcommand}". Known: ${WORKSPACE_SUBCOMMANDS.join(", ")}`
+      );
+    }
+    rest = rest.slice(1);
+    if (subcommand === "add" || subcommand === "remove") {
+      target = rest[0];
+      if (target === void 0 || target.startsWith("-")) {
+        throw new Error(
+          subcommand === "add" ? "workspace add needs a manifest path." : "workspace remove needs a project id or manifest path."
+        );
+      }
+      rest = rest.slice(1);
+    }
+  }
   for (let i = 0; i < rest.length; i++) {
     const token = rest[i];
     if (!token.startsWith("-")) {
@@ -4920,7 +5708,8 @@ function parseArgs(argv) {
   return {
     command,
     manifest,
-    lock: get("--lock") ?? path16.join(path16.dirname(path16.resolve(manifest)), "pixelkiln.lock.json"),
+    lock: get("--lock") ?? path18.join(path18.dirname(path18.resolve(manifest)), "pixelkiln.lock.json"),
+    explicitLock: get("--lock"),
     styles: list("--style"),
     assets: list("--only"),
     force: rest.includes("--force"),
@@ -4949,10 +5738,15 @@ function parseArgs(argv) {
     maxDistance: numberOption("--max-distance", { min: 0 }),
     minTransparency: numberOption("--min-transparency", { min: 0, max: 1 }),
     maxColors: numberOption("--max-colors", { min: 1, integer: true }),
-    sigma: numberOption("--sigma", { min: Number.EPSILON })
+    sigma: numberOption("--sigma", { min: Number.EPSILON }),
+    subcommand,
+    workspace: get("--workspace"),
+    target,
+    provider: get("--provider"),
+    account: get("--account")
   };
 }
-var HELP = `pixelkiln \u2014 manifest-driven pixel art generation (PixelLab)
+var HELP = `pixelkiln \u2014 manifest-driven pixel art generation
 
   pixelkiln <command> [options]
 
@@ -4982,6 +5776,8 @@ Commands
   tag       Push manifest tags to the objects upstream (free).
   balance   Show the provider's remaining balance.
   status    Summarise the lockfile.
+  workspace Register sibling projects and derive account-wide claims/status.
+            add/remove/list/status/claims. Offline.
 
 Options
   --columns <n>       pack/export: sprites or tiles per row (default: near-square)
@@ -5009,6 +5805,8 @@ Options
   --no-open           Do not auto-open the browser during pick
   --tag               Also push tags upstream after fetch
   --claims a.json,b   Other projects' lockfiles (salvage; required if account is shared)
+  --workspace <path>  Workspace catalog (default: pixelkiln.workspace.json). Also
+                       derives salvage's claim set instead of repeated --claims.
   --from <dir>        Source tree for init
   --write-prompts     adopt: recover prompts into the manifest
 
@@ -5021,6 +5819,9 @@ Examples
   pixelkiln pack --inputs sprites.json --out dist/sheet   # no manifest needed
   pixelkiln mount --style ground
   pixelkiln export --style ground --only terrain --format tiled
+  pixelkiln workspace add ../other-game/pixelkiln.manifest.json
+  pixelkiln workspace status --json
+  pixelkiln salvage --workspace pixelkiln.workspace.json
 `;
 function printPlan(plan) {
   const counts = summarize(plan);
@@ -5061,6 +5862,23 @@ async function confirm(question, auto) {
   process.stdin.pause();
   return answer === "y" || answer === "yes";
 }
+async function requireCompleteWorkspaceClaims(workspacePath) {
+  if (!existsSync15(workspacePath)) {
+    throw new Error(`Workspace catalog not found: ${workspacePath}`);
+  }
+  const dir = path18.dirname(path18.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(
+      `Workspace catalog at ${workspacePath} is not safe to derive a claim set from:
+` + errors.map((d) => `  ${d.id}: ${d.message}`).join("\n")
+    );
+  }
+  const claims = await workspaceClaims(ws, dir);
+  return { ws, dir, diagnostics, claims };
+}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.command === "help" || args.command === "--help" || args.command === "-h") {
@@ -5069,16 +5887,17 @@ async function main() {
   }
   if (args.command === "--version" || args.command === "-v") {
     const pkg = JSON.parse(
-      await readFile13(new URL("../package.json", import.meta.url), "utf8")
+      await readFile14(new URL("../package.json", import.meta.url), "utf8")
     );
     log(`${pkg.name} ${pkg.version}`);
     return;
   }
   if (args.command === "balance") {
-    loadEnvFiles(path16.dirname(path16.resolve(args.manifest)));
+    loadEnvFiles(path18.dirname(path18.resolve(args.manifest)));
     loadEnvFiles(process.cwd());
-    const p = PixelLabProvider.fromEnv();
-    const b = await p.balance();
+    const loaded2 = await loadManifest(args.manifest);
+    const p = createProvider(loaded2.manifest.provider, "online");
+    const b = await requireBalance(p)();
     log(`  provider:  ${p.id}`);
     log(`  plan:      ${b.plan ?? "n/a"}`);
     log(`  remaining: ${formatCost(b.unit, b.remaining)}${b.total ? ` of ${b.total}` : ""}`);
@@ -5086,31 +5905,31 @@ async function main() {
   }
   if (args.command === "init") {
     if (!args.from) throw new Error("init needs --from <dir> pointing at your existing PNGs.");
-    const root = path16.resolve(args.from);
-    if (!existsSync14(root)) throw new Error(`No directory at ${root}`);
+    const root = path18.resolve(args.from);
+    if (!existsSync15(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 = path16.resolve(args.out ?? "pixelkiln.manifest.json");
+    const target = path18.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 ?? path16.basename(path16.dirname(target)),
+      args.name ?? path18.basename(path18.dirname(target)),
       args.styles[0] ?? "base",
       generator,
-      path16.relative(path16.dirname(target), root) || ".",
+      path18.relative(path18.dirname(target), root) || ".",
       assets
     );
     await writeManifestFile(target, manifest);
-    log(`  scanned ${assets.length} PNG(s) under ${path16.relative(process.cwd(), root)}`);
+    log(`  scanned ${assets.length} PNG(s) under ${path18.relative(process.cwd(), root)}`);
     if (skipped.length) log(`  skipped ${skipped.length} unreadable file(s)`);
-    log(`  wrote ${path16.relative(process.cwd(), target)}`);
+    log(`  wrote ${path18.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 ${path16.relative(process.cwd(), target)} --write-prompts
+    pixelkiln adopt --manifest ${path18.relative(process.cwd(), target)} --write-prompts
 `);
     return;
   }
@@ -5158,10 +5977,10 @@ async function main() {
     if (args.primaryOnly || args.outputRoles.length) {
       throw new Error("--primary-only and --output-role require manifest-driven pack");
     }
-    const raw = JSON.parse(await readFile13(path16.resolve(args.inputs), "utf8"));
+    const raw = JSON.parse(await readFile14(path18.resolve(args.inputs), "utf8"));
     const inputs = resolvePackInputs(raw, args.inputs);
     const { png, atlas, skipped, sources } = packSprites(inputs, { columns: args.columns });
-    const base = path16.resolve(args.out.replace(/\.png$/, ""));
+    const base = path18.resolve(args.out.replace(/\.png$/, ""));
     const outputs = [
       { path: `${base}.png`, data: png },
       { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
@@ -5174,20 +5993,145 @@ async function main() {
     log(
       `  ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s) \u2014 ${(png.length / 1024).toFixed(1)} KB`
     );
-    log(`    ${path16.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+    log(`    ${path18.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     return;
   }
-  if (!existsSync14(path16.resolve(args.manifest))) {
+  if (args.command === "workspace") {
+    const workspacePath = path18.resolve(args.workspace ?? "pixelkiln.workspace.json");
+    const dir = path18.dirname(workspacePath);
+    if (args.subcommand === "add") {
+      const manifestPath = path18.resolve(args.target);
+      const loadedTarget = await loadManifest(manifestPath);
+      const lockPath = args.explicitLock ? path18.resolve(args.explicitLock) : path18.join(path18.dirname(manifestPath), "pixelkiln.lock.json");
+      const ws = await loadWorkspace(workspacePath);
+      const id = args.name ?? loadedTarget.manifest.name;
+      if (ws.projects.some((p) => p.id === id)) {
+        throw new Error(
+          `Project id "${id}" is already registered in ${workspacePath}. Pass --name for a different id.`
+        );
+      }
+      const lockOwner = ws.projects.find((p) => resolveProject(dir, p).lockPath === lockPath);
+      if (lockOwner) {
+        throw new Error(`Lockfile ${lockPath} is already registered under project id "${lockOwner.id}".`);
+      }
+      const project = {
+        id,
+        manifest: toPortablePath(dir, manifestPath),
+        lock: toPortablePath(dir, lockPath),
+        provider: args.provider ?? loadedTarget.manifest.provider,
+        ...args.account ? { account: args.account } : {}
+      };
+      await saveWorkspace(workspacePath, { version: 1, projects: [...ws.projects, project] });
+      log(`  registered "${id}" in ${path18.relative(process.cwd(), workspacePath)}`);
+      log(`    manifest: ${project.manifest}`);
+      log(`    lock:     ${project.lock}`);
+      if (!existsSync15(lockPath)) {
+        log(
+          `  warning: no lockfile there yet \u2014 this project contributes no claims until one is generated`
+        );
+      }
+      return;
+    }
+    if (args.subcommand === "remove") {
+      const ws = await loadWorkspace(workspacePath);
+      const resolvedTarget = path18.resolve(args.target);
+      const match = ws.projects.find(
+        (p) => p.id === args.target || resolveProject(dir, p).manifestPath === resolvedTarget
+      );
+      if (!match) {
+        throw new Error(`No registered project matches "${args.target}" (checked id and manifest path).`);
+      }
+      await saveWorkspace(workspacePath, {
+        version: 1,
+        projects: ws.projects.filter((p) => p !== match)
+      });
+      log(`  removed "${match.id}" from ${path18.relative(process.cwd(), workspacePath)}`);
+      return;
+    }
+    if (args.subcommand === "list") {
+      if (!existsSync15(workspacePath)) {
+        throw new Error(`Workspace catalog not found: ${workspacePath}`);
+      }
+      const ws = await loadWorkspace(workspacePath);
+      const diagnostics = validateWorkspace(ws, dir);
+      if (args.json) {
+        log(JSON.stringify({ version: 1, workspace: workspacePath, projects: ws.projects, diagnostics }, null, 2));
+      } else if (!ws.projects.length) {
+        log(`  no projects registered in ${path18.relative(process.cwd(), workspacePath)}`);
+      } else {
+        log(`  ${ws.projects.length} project(s) in ${path18.relative(process.cwd(), workspacePath)}:`);
+        for (const p of ws.projects) {
+          log(`    ${p.id.padEnd(24)} ${p.manifest.padEnd(40)} (${p.provider}${p.account ? `, ${p.account}` : ""})`);
+        }
+        for (const d of diagnostics) log(`  ${d.level === "error" ? "ERROR" : "WARN "} ${d.id.padEnd(18)} ${d.message}`);
+      }
+      if (args.check && diagnostics.some((d) => d.level === "error")) process.exitCode = 1;
+      return;
+    }
+    if (args.subcommand === "status") {
+      if (!existsSync15(workspacePath)) {
+        throw new Error(`Workspace catalog not found: ${workspacePath}`);
+      }
+      const ws = await loadWorkspace(workspacePath);
+      const report = await workspaceStatus(ws, dir);
+      if (args.json) {
+        log(JSON.stringify({ ...report, workspace: workspacePath }, null, 2));
+      } else {
+        log(`  workspace: ${path18.relative(process.cwd(), workspacePath)}`);
+        for (const p of report.projects) {
+          if (p.error) {
+            log(`
+  ${p.id} \u2014 ERROR: ${p.error}`);
+            continue;
+          }
+          log(`
+  ${p.id}  (${p.provider}${p.account ? `, ${p.account}` : ""})`);
+          log(`    ${p.entries} lock entries`);
+          for (const [state, n] of Object.entries(p.byState)) if (n) log(`      ${state.padEnd(12)} ${n}`);
+          for (const [unit, amount] of Object.entries(p.spendByUnit).sort()) {
+            if (amount) log(`    spend: ${formatCost(unit, amount)}`);
+          }
+        }
+        log(`
+  totals:`);
+        for (const [state, n] of Object.entries(report.totals.byState)) if (n) log(`    ${state.padEnd(12)} ${n}`);
+        for (const [unit, amount] of Object.entries(report.totals.spendByUnit).sort()) {
+          if (amount) log(`    spend: ${formatCost(unit, amount)}`);
+        }
+        log(`    claims: ${report.totals.claims}`);
+        for (const d of report.diagnostics) log(`  ${d.level === "error" ? "ERROR" : "WARN "} ${d.id.padEnd(18)} ${d.message}`);
+      }
+      if (args.check && !report.safe) process.exitCode = 1;
+      return;
+    }
+    if (args.subcommand === "claims") {
+      const { claims, diagnostics } = await requireCompleteWorkspaceClaims(workspacePath);
+      if (args.json) {
+        log(JSON.stringify({
+          version: 1,
+          claimed: [...claims.claimed].sort(),
+          byProject: claims.byProject,
+          lockPaths: claims.lockPaths
+        }, null, 2));
+      } else {
+        log(`  ${claims.claimed.size} claimed id(s) across ${claims.lockPaths.length} lockfile(s):`);
+        for (const [id, n] of Object.entries(claims.byProject).sort()) log(`    ${id.padEnd(24)} ${n}`);
+        for (const d of diagnostics) log(`  WARN  ${d.id.padEnd(18)} ${d.message}`);
+      }
+      return;
+    }
+  }
+  if (!existsSync15(path18.resolve(args.manifest))) {
     throw new Error(
-      `No manifest at ${path16.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
+      `No manifest at ${path18.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
     );
   }
-  const manifestDir = path16.dirname(path16.resolve(args.manifest));
+  const manifestDir = path18.dirname(path18.resolve(args.manifest));
   const envFiles = [...loadEnvFiles(manifestDir)];
-  if (path16.resolve(process.cwd()) !== manifestDir) envFiles.push(...loadEnvFiles(process.cwd()));
+  if (path18.resolve(process.cwd()) !== manifestDir) envFiles.push(...loadEnvFiles(process.cwd()));
   const loaded = await loadManifest(args.manifest);
-  const estimator = PixelLabProvider.forOffline();
+  const estimator = createProvider(loaded.manifest.provider, "offline");
   const specs = await resolveSpecs(loaded, {
     styles: args.styles,
     assets: args.assets,
@@ -5206,9 +6150,9 @@ async function main() {
     for (const [s, n] of Object.entries(byStatus).sort()) log(`    ${s.padEnd(12)} ${n}`);
     const spend = spendByUnit(lock);
     let reported = false;
-    for (const unit of ["generations", "usd", "free"]) {
-      if (spend[unit]) {
-        log(`  recorded successful submissions: ${formatCost(unit, spend[unit])}`);
+    for (const [unit, amount] of Object.entries(spend).sort()) {
+      if (amount) {
+        log(`  recorded successful submissions: ${formatCost(unit, amount)}`);
         reported = true;
       }
     }
@@ -5217,12 +6161,14 @@ async function main() {
   }
   const plan = await buildPlan(specs, lock, { force: args.force });
   if (args.command === "doctor") {
-    const apiKeyPresent = Boolean(process.env.PIXELLAB_API_KEY);
-    const provider2 = !args.dryRun && apiKeyPresent ? PixelLabProvider.fromEnv() : void 0;
+    const factory = providerFactory(loaded.manifest.provider);
+    const apiKeyPresent = !factory.credentialEnv || Boolean(process.env[factory.credentialEnv]);
+    const provider2 = !args.dryRun && apiKeyPresent ? createProvider(loaded.manifest.provider, "online") : void 0;
     const report = await doctor(loaded, specs, lock, args.lock, {
       provider: provider2,
       offline: args.dryRun,
-      apiKeyPresent
+      apiKeyPresent,
+      credentialEnv: factory.credentialEnv
     });
     if (args.json) {
       log(JSON.stringify(report, null, 2));
@@ -5260,7 +6206,7 @@ async function main() {
       let intact = true;
       for (const output of entry.outputs) {
         const file = resolveOutputPath(output.path, item.spec.root);
-        if (!existsSync14(file) || await sha256File(file) !== output.sha256) {
+        if (!existsSync15(file) || await sha256File(file) !== output.sha256) {
           intact = false;
           break;
         }
@@ -5318,7 +6264,7 @@ async function main() {
     if (args.primaryOnly && args.outputRoles.length) {
       throw new Error("pack accepts either --primary-only or --output-role, not both");
     }
-    const manifestDir2 = path16.dirname(path16.resolve(args.manifest));
+    const manifestDir2 = path18.dirname(path18.resolve(args.manifest));
     const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
     for (const styleId of styleIds) {
       const { png, atlas, skipped, sources } = packStyle(lock, styleId, manifestDir2, {
@@ -5327,7 +6273,7 @@ async function main() {
         primaryOnly: args.primaryOnly
       });
       const style = loaded.manifest.styles[styleId];
-      const base = args.out ? path16.resolve(args.out.replace(/\.png$/, "")) : path16.resolve(manifestDir2, style.outDir, `${styleId}-sheet`);
+      const base = args.out ? path18.resolve(args.out.replace(/\.png$/, "")) : path18.resolve(manifestDir2, style.outDir, `${styleId}-sheet`);
       const outputs = [
         { path: `${base}.png`, data: png },
         { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
@@ -5350,13 +6296,13 @@ async function main() {
       log(
         `  ${styleId} \u2014 ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s)`
       );
-      log(`    ${path16.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+      log(`    ${path18.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
       for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     }
     return;
   }
   if (args.command === "mount") {
-    const manifestDir2 = path16.dirname(path16.resolve(args.manifest));
+    const manifestDir2 = path18.dirname(path18.resolve(args.manifest));
     const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
     for (const styleId of styleIds) {
       const style = loaded.manifest.styles[styleId];
@@ -5386,7 +6332,7 @@ async function main() {
         sources,
         outputRoles
       );
-      const out = path16.resolve(manifestDir2, style.mount.out);
+      const out = path18.resolve(manifestDir2, style.mount.out);
       const metadata = out.replace(/\.png$/, "") + ".json";
       const companion = out.replace(/\.png$/, "") + ".pixelkiln.json";
       const outputs = [
@@ -5399,7 +6345,7 @@ async function main() {
           await provenanceFile("$manifest", args.manifest),
           await provenanceFile("$lock", args.lock),
           ...artifactSources.filter(
-            (source) => source.id !== "$base" || path16.resolve(source.path) !== out
+            (source) => source.id !== "$base" || path18.resolve(source.path) !== out
           )
         ],
         options: {
@@ -5412,7 +6358,7 @@ async function main() {
       log(
         `  ${styleId} \u2014 ${atlas.frames.length} cell(s) into ${atlas.sheet.width}x${atlas.sheet.height}` + (overBase ? ` over ${style.mount.base}` : " (new sheet)")
       );
-      log(`    ${path16.relative(process.cwd(), out)} + atlas/provenance JSON`);
+      log(`    ${path18.relative(process.cwd(), out)} + atlas/provenance JSON`);
       for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     }
     return;
@@ -5468,7 +6414,7 @@ async function main() {
   }
   if (args.command === "export") {
     const format = args.format ?? "generic";
-    const manifestDir2 = path16.dirname(path16.resolve(args.manifest));
+    const manifestDir2 = path18.dirname(path18.resolve(args.manifest));
     const selected = specs.filter((spec) => {
       if (spec.generator !== "tiles") return false;
       if (args.styles.length && !args.styles.includes(spec.styleId)) return false;
@@ -5484,12 +6430,12 @@ async function main() {
     for (const spec of selected) {
       const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
       const style = loaded.manifest.styles[spec.styleId];
-      const defaultBase = path16.resolve(manifestDir2, style.outDir, `${spec.assetId}-tileset`);
-      const base = args.out ? path16.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
+      const defaultBase = path18.resolve(manifestDir2, style.outDir, `${spec.assetId}-tileset`);
+      const base = args.out ? path18.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
       const result = exportTileset(entry, spec, {
         format,
         manifestDir: manifestDir2,
-        imageName: path16.basename(`${base}.png`),
+        imageName: path18.basename(`${base}.png`),
         columns: args.columns
       });
       const outputs = [
@@ -5507,7 +6453,7 @@ async function main() {
           asset: spec.assetId,
           columns: args.columns ?? null,
           format,
-          image: path16.basename(`${base}.png`),
+          image: path18.basename(`${base}.png`),
           providerRules: result.generic.providerRules,
           style: spec.styleId,
           tileType: spec.tileType ?? null
@@ -5517,12 +6463,12 @@ async function main() {
         `  ${spec.styleId}/${spec.assetId} \u2014 ${result.generic.tiles.length} tile(s), ${result.generic.sheet.width}x${result.generic.sheet.height} (${format})`
       );
       log(
-        `    ${path16.relative(process.cwd(), base)}.png + ${path16.basename(base)}${result.extension} + .pixelkiln.json`
+        `    ${path18.relative(process.cwd(), base)}.png + ${path18.basename(base)}${result.extension} + .pixelkiln.json`
       );
     }
     return;
   }
-  const provider = args.command === "restore" || args.command === "fetch" && !args.tag ? PixelLabProvider.forDownloads() : PixelLabProvider.fromEnv();
+  const provider = args.command === "restore" || args.command === "fetch" && !args.tag ? createProvider(loaded.manifest.provider, "downloads") : createProvider(loaded.manifest.provider, "online");
   if (args.command === "adopt") {
     log(`
   Reconciling account objects against files already on disk\u2026`);
@@ -5557,10 +6503,10 @@ async function main() {
   tagged ${n} object(s) upstream`);
     }
     if (args.writePrompts) {
-      const { filled, stillEmpty } = await writePromptsBack(path16.resolve(args.manifest), lock, {
+      const { filled, stillEmpty } = await writePromptsBack(path18.resolve(args.manifest), lock, {
         onProgress: log
       });
-      log(`  recovered ${filled} prompt(s) into ${path16.relative(process.cwd(), args.manifest)}`);
+      log(`  recovered ${filled} prompt(s) into ${path18.relative(process.cwd(), args.manifest)}`);
       const reloaded = await loadManifest(args.manifest);
       const rebased = await resolveSpecs(reloaded, {
         styles: args.styles,
@@ -5589,19 +6535,39 @@ async function main() {
   if (args.command === "salvage") {
     const jsonMode = args.dryRun && args.json;
     const diag = jsonMode ? (msg = "") => console.error(msg) : log;
-    const ownLock = path16.resolve(args.lock);
+    const ownLock = path18.resolve(args.lock);
+    let workspaceProjects = [];
+    let workspaceDir = "";
+    if (args.workspace) {
+      const workspacePath = path18.resolve(args.workspace);
+      workspaceDir = path18.dirname(workspacePath);
+      const complete = await requireCompleteWorkspaceClaims(workspacePath);
+      workspaceProjects = complete.ws.projects;
+      for (const d of complete.diagnostics) diag(`  WARN  ${d.id}: ${d.message}`);
+    }
+    const workspaceLockPaths = workspaceProjects.map((p) => resolveProject(workspaceDir, p).lockPath);
     const lockPaths = [
-      ...existsSync14(ownLock) ? [ownLock] : [],
-      ...args.claims.map((c) => path16.resolve(c))
+      .../* @__PURE__ */ new Set([
+        ...workspaceLockPaths,
+        ...existsSync15(ownLock) ? [ownLock] : [],
+        ...args.claims.map((c) => path18.resolve(c))
+      ])
     ];
     diag(`  claim set (${lockPaths.length} lockfile(s)):`);
-    for (const p of lockPaths) diag(`    ${path16.relative(process.cwd(), p)}`);
-    if (!args.claims.length) {
+    for (const p of lockPaths) diag(`    ${path18.relative(process.cwd(), p)}`);
+    if (!args.claims.length && !args.workspace) {
       diag(
         `
   Only this project's lockfile was consulted. If the account is shared,
-  pass every other project's lockfile via --claims a.json,b.json or you
-  will see their assets listed as unclaimed.`
+  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 === path18.resolve(args.manifest))) {
+      diag(
+        `
+  This project's manifest is not registered in the workspace catalog. Its own
+  lockfile is still included above, so this run's claim set is complete \u2014 but
+  \`pixelkiln workspace add ${args.manifest}\` would keep it aggregated too.`
       );
     }
     const claimed = await loadClaims(lockPaths);
@@ -5613,16 +6579,11 @@ async function main() {
   nothing to triage`);
       return;
     }
-    const siblings = [];
-    for (const claimPath of args.claims.map((c) => path16.resolve(c))) {
-      const siblingManifestPath = path16.join(path16.dirname(claimPath), "pixelkiln.manifest.json");
-      if (!existsSync14(siblingManifestPath)) continue;
-      try {
-        const siblingLoaded = await loadManifest(siblingManifestPath);
-        siblings.push({ label: path16.basename(path16.dirname(siblingManifestPath)), manifest: siblingLoaded.manifest });
-      } catch {
-      }
-    }
+    const siblings = await loadSiblingManifests(
+      args.manifest,
+      workspaceProjects.map((p) => resolveProject(workspaceDir, p).manifestPath),
+      args.claims
+    );
     const { matched, unmatched, elsewhere } = groupOrphansByStyle(orphans, loaded.manifest, siblings);
     const multiStyle = Object.keys(loaded.manifest.styles).length > 1;
     if (multiStyle) {
@@ -5685,7 +6646,7 @@ async function main() {
           manifestPath: loaded.path,
           manifest: loaded.manifest,
           styleId,
-          importDir: path16.resolve(loaded.root, style.outDir),
+          importDir: path18.resolve(loaded.root, style.outDir),
           lock,
           lockPath: args.lock
         },
@@ -5750,7 +6711,7 @@ async function main() {
       return;
     }
     log(`
-  This permanently deletes them from your PixelLab account.`);
+  This permanently deletes them from your ${provider.id} account.`);
     log(`  Any local files already downloaded are untouched, but the objects`);
     log(`  and their URLs are gone and cannot be re-downloaded.`);
     if (!await confirm(`  Delete ${doomed.length} object(s)?`, args.yes)) {
@@ -5785,21 +6746,26 @@ async function main() {
       return;
     }
     if (plan.actionable.length) {
-      const balance = await provider.balance();
-      log(`
+      const balance = provider.balance ? await provider.balance() : null;
+      if (balance) {
+        log(`
   balance: ${formatCost(balance.unit, balance.remaining)} remaining (${provider.id})`);
-      if (balance.unit !== plan.costUnit) {
-        throw new Error(
-          `Provider estimate unit ${plan.costUnit} does not match balance unit ${balance.unit}.`
-        );
-      }
-      if (balance.unit !== "free" && plan.cost > balance.remaining) {
-        throw new Error(
-          `This run needs ${formatCost(balance.unit, plan.cost)} but only ${formatCost(balance.unit, balance.remaining)} remain.`
-        );
+        if (balance.unit !== plan.costUnit) {
+          throw new Error(
+            `Provider estimate unit ${plan.costUnit} does not match balance unit ${balance.unit}.`
+          );
+        }
+        if (balance.unit !== "free" && plan.cost > balance.remaining) {
+          throw new Error(
+            `This run needs ${formatCost(balance.unit, plan.cost)} but only ${formatCost(balance.unit, balance.remaining)} remain.`
+          );
+        }
+      } else {
+        log(`
+  ${provider.id} does not expose an account balance; enforcing the explicit run budget`);
       }
       const ok = await confirm(
-        `  Spend ${formatCost(balance.unit, plan.cost)} on ${plan.actionable.length} asset(s)?`,
+        `  Spend ${formatCost(plan.costUnit, plan.cost)} on ${plan.actionable.length} asset(s)?`,
         args.yes
       );
       if (!ok) {
@@ -5817,7 +6783,8 @@ async function main() {
   submitted ${res.submitted}, failed ${res.failed}, estimated ${formatCost(res.unit, res.spent)}`
       );
       try {
-        const after = await provider.balance();
+        const after = balance && provider.balance ? await provider.balance() : null;
+        if (!balance || !after) throw new Error("balance reporting is unsupported");
         const measured = measureBalanceChange(balance, after);
         if (measured) {
           const movement = measured.credited ? `${formatCost(measured.unit, measured.credited)} credited` : `${formatCost(measured.unit, measured.spent)} consumed`;