pixelkiln 0.23.0 → 0.25.0

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import path26 from "path";
-import { existsSync as existsSync21 } from "fs";
+import path28 from "path";
+import { existsSync as existsSync22 } from "fs";
 import { readFile as readFile22 } from "fs/promises";
 
 // src/env.ts
@@ -134,10 +134,10 @@ import { createReadStream } from "fs";
 function sha256(data) {
   return createHash("sha256").update(data).digest("hex");
 }
-async function sha256File(path27) {
+async function sha256File(path29) {
   return new Promise((resolve, reject) => {
     const hash = createHash("sha256");
-    const stream = createReadStream(path27);
+    const stream = createReadStream(path29);
     stream.on("data", (chunk2) => hash.update(chunk2));
     stream.on("error", reject);
     stream.on("end", () => resolve(hash.digest("hex")));
@@ -1617,11 +1617,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(path27, init, attempt = 0) {
+  async request(path29, init, attempt = 0) {
     const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
     let res;
     try {
-      res = await fetch(`${BASE}${path27}`, {
+      res = await fetch(`${BASE}${path29}`, {
         ...init,
         signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs),
         headers: {
@@ -1633,24 +1633,24 @@ var PixelLabClient = class {
     } catch (err) {
       if (attempt < MAX_RETRIES) {
         await sleep(backoffMs(attempt));
-        return this.request(path27, init, attempt + 1);
+        return this.request(path29, 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(path27, init, attempt + 1);
+      return this.request(path29, init, attempt + 1);
     }
     const text = await res.text();
     if (!res.ok) {
-      throw new PixelLabError(`${init?.method ?? "GET"} ${path27} \u2192 ${res.status}`, res.status, text);
+      throw new PixelLabError(`${init?.method ?? "GET"} ${path29} \u2192 ${res.status}`, res.status, text);
     }
     if (!text) return {};
     try {
       return JSON.parse(text);
     } catch {
-      throw new Error(`${init?.method ?? "GET"} ${path27} returned invalid JSON`);
+      throw new Error(`${init?.method ?? "GET"} ${path29} returned invalid JSON`);
     }
   }
   async balance() {
@@ -2112,6 +2112,15 @@ var AssetSchema = z2.object({
    * that wasn't. `prompt` still records what was asked for.
    */
   source: z2.string().optional(),
+  /**
+   * Per-style replacement for `source`, keyed by style id.
+   *
+   * A hand edit belongs to one generation: the same asset generated in two
+   * styles is two different pictures, so the touch-up of one must not be
+   * placed for the other. `pixelkiln edit` writes here when an asset is in
+   * more than one style, and to `source` when it is in exactly one.
+   */
+  sourceByStyle: z2.record(z2.string().min(1)).default({}),
   /** Controlled generation derived from another asset in the same style. */
   revision: RevisionSchema.optional(),
   /**
@@ -2146,7 +2155,7 @@ var AssetSchema = z2.object({
     z2.array(z2.union([z2.string(), z2.number().finite(), z2.boolean()])).min(2).max(64)
   ])).default({})
 }).strict().superRefine((asset, context) => {
-  if (asset.source && asset.revision) {
+  if ((asset.source || Object.keys(asset.sourceByStyle).length) && asset.revision) {
     context.addIssue({
       code: z2.ZodIssueCode.custom,
       message: "source and revision are mutually exclusive",
@@ -2280,6 +2289,10 @@ function lockKey(styleId, assetId) {
 }
 
 // src/providers/pixellab.ts
+function pixelLabObjectUrl(generator, objectId) {
+  if (!objectId || generator !== "map" && generator !== "1dir") return null;
+  return `https://www.pixellab.ai/objects/${encodeURIComponent(objectId)}`;
+}
 var PixelLabProvider = class _PixelLabProvider {
   constructor(client) {
     this.client = client;
@@ -2613,9 +2626,9 @@ var RetroDiffusionClient = class {
     }
     return balance;
   }
-  async call(path27, init = {}) {
+  async call(path29, init = {}) {
     if (!this.token) throw new Error("RD_API_KEY is not set");
-    const response = await this.request(`${this.baseUrl}${path27}`, {
+    const response = await this.request(`${this.baseUrl}${path29}`, {
       ...init,
       headers: {
         "Content-Type": "application/json",
@@ -3784,6 +3797,11 @@ ${issues}`);
         unknownReferences.push(`assets.${assetId}.promptByStyle: unknown style "${styleId}"`);
       }
     }
+    for (const styleId of Object.keys(asset.sourceByStyle)) {
+      if (!styleIds.has(styleId)) {
+        unknownReferences.push(`assets.${assetId}.sourceByStyle: unknown style "${styleId}"`);
+      }
+    }
     if (asset.revision) {
       if (!parsed.data.assets[asset.revision.from]) {
         unknownReferences.push(
@@ -4048,7 +4066,7 @@ async function resolveSpecs(loaded, filter) {
           }
         } : {},
         tags,
-        source: asset.source,
+        source: asset.sourceByStyle[styleId] ?? asset.source,
         // Revision identity is attached after every dependency in this style
         // has a concrete output target. Finalization below computes the hash.
         specHash: ""
@@ -4306,16 +4324,24 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
   }
   const prefix = `${styleId}/`;
   const entries = Object.entries(lock.entries).filter(([key]) => key.startsWith(prefix));
-  if (!entries.length) {
+  const sources = options.sources ?? {};
+  if (!entries.length && !Object.keys(sources).length) {
     throw new Error(
       `No locked assets for style "${styleId}". Run \`pixelkiln gen --style ${styleId}\` first.`
     );
   }
   const inputs = [];
   const noOutput = [];
+  const locked = /* @__PURE__ */ new Set();
   for (const [key, entry] of entries) {
     const id = key.slice(prefix.length);
+    locked.add(id);
     const outputs = resolveEntryOutputs(entry, id, manifestDir);
+    const source = sources[id];
+    if (source && outputs.length <= 1) {
+      inputs.push({ id, path: path7.resolve(manifestDir, source) });
+      continue;
+    }
     let selected = outputs;
     if (options.outputRoles?.length) {
       selected = outputs.filter(
@@ -4332,6 +4358,9 @@ function packStyle(lock, styleId, manifestDir, options = {}) {
     }
     for (const output of selected) inputs.push({ id: output.id, path: output.absolutePath });
   }
+  for (const [id, source] of Object.entries(sources)) {
+    if (!locked.has(id)) inputs.push({ id, path: path7.resolve(manifestDir, source) });
+  }
   if (!inputs.length) {
     throw new Error(`No readable sprites for style "${styleId}" \u2014 ${noOutput.length} skipped.`);
   }
@@ -6423,14 +6452,16 @@ function shouldPersistSourceUrl(value) {
 async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
   const log2 = opts.onProgress ?? (() => {
   });
-  const result = { downloaded: 0, skipped: 0, failed: 0 };
+  const result = { downloaded: 0, skipped: 0, failed: 0, ...opts.refresh ? { unchanged: 0 } : {} };
   const specByKey = new Map(specs.map((s) => [lockKey(s.styleId, s.assetId), s]));
   normalizeLockOutputPaths(lock, specs);
   const cacheDir = opts.cacheDir === false ? null : path14.resolve(opts.cacheDir ?? path14.join(path14.dirname(lockPath), ".pixelkiln", "cache"));
   const pending = Object.entries(lock.entries).filter(([key, e]) => {
     if (e.provider !== provider.id || !specByKey.has(key)) return false;
     if (e.status === "selected" || e.status === "download-failed") return true;
-    if (!opts.repair || e.status !== "downloaded") return false;
+    if (e.status !== "downloaded") return false;
+    if (opts.refresh) return e.outputs.length > 0 && Boolean(e.sourceUrls?.length || e.sourceUrl);
+    if (!opts.repair) return false;
     const spec = specByKey.get(key);
     return e.outputs.length === 0 || !spec || e.outputs.some((output) => !existsSync9(resolveOutputPath(output.path, spec.root)));
   });
@@ -6462,6 +6493,7 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
         continue;
       }
       const outputs = [];
+      let wrote = false;
       try {
         for (let index = 0; index < sources.length; index++) {
           const source = sources[index];
@@ -6469,41 +6501,55 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
             (o) => source.role ? o.role === source.role : !o.role && sources.length === 1
           );
           const target = recorded ? resolveOutputPath(recorded.path, spec.root) : expectedOutputPath(spec, source.role, index, sources.length, source.mediaType);
+          let fresh = null;
+          if (opts.refresh) {
+            if (!source.url) throw new Error(`no durable source URL to refresh ${source.role ?? "asset"} from`);
+            fresh = await provider.download(source.url);
+            if (recorded && sha256(fresh) === recorded.sha256) {
+              log2(`  current ${path14.relative(process.cwd(), target)}`);
+              outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
+              continue;
+            }
+          }
           if (existsSync9(target)) {
             const currentHash = await sha256File(target);
             if (recorded && currentHash === recorded.sha256) {
-              if (cacheDir) {
-                await cacheMedia(
-                  cacheDir,
-                  await readFile7(target),
-                  recorded.mediaType ?? MediaType.PNG,
-                  recorded.sha256
-                );
+              if (!fresh) {
+                if (cacheDir) {
+                  await cacheMedia(
+                    cacheDir,
+                    await readFile7(target),
+                    recorded.mediaType ?? MediaType.PNG,
+                    recorded.sha256
+                  );
+                }
+                outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
+                continue;
               }
-              outputs.push({ ...recorded, path: portableOutputPath(target, spec.root) });
-              continue;
-            }
-            const superseded = (entry.supersededOutputs ?? []).find(
-              (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
-            );
-            if (!opts.force) {
-              if (!recorded && superseded && currentHash === superseded.sha256) {
-              } else if (recorded || superseded) {
-                throw new Error(
-                  `refusing to overwrite modified output ${target}; pass --force to replace it`
-                );
-              } else {
-                throw new Error(
-                  `refusing to overwrite untracked output ${target}; pass --force to replace it`
-                );
+              log2(`  changed ${path14.relative(process.cwd(), target)} (upstream)`);
+            } else {
+              const superseded = (entry.supersededOutputs ?? []).find(
+                (output, oldIndex, all) => currentOutputPath(output, spec, oldIndex, all.length) === target
+              );
+              if (!opts.force) {
+                if (!recorded && superseded && currentHash === superseded.sha256) {
+                } else if (recorded || superseded) {
+                  throw new Error(
+                    `refusing to overwrite modified output ${target}; pass --force to replace it`
+                  );
+                } else {
+                  throw new Error(
+                    `refusing to overwrite untracked output ${target}; pass --force to replace it`
+                  );
+                }
               }
+              log2(
+                `  replace ${path14.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
+              );
             }
-            log2(
-              `  replace ${path14.relative(process.cwd(), target)}` + (opts.force ? " (--force)" : " (previous tracked generation)")
-            );
           }
           const expectedMediaType = source.mediaType ?? recorded?.mediaType ?? MediaType.PNG;
-          let buf = recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null;
+          let buf = fresh ?? (recorded && cacheDir ? await readCachedMedia(cacheDir, recorded.sha256, expectedMediaType) : null);
           if (buf) {
             log2(`  cached  ${path14.relative(process.cwd(), target)}`);
           } else {
@@ -6535,8 +6581,13 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           upsert(lock, key, { outputs: mergeOutputs(entry.outputs, outputs) });
           await saveLock(lockPath, lock);
           await rename3(tmp, target);
+          wrote = true;
           log2(`  wrote   ${path14.relative(process.cwd(), target)}`);
         }
+        if (opts.refresh && !wrote) {
+          result.unchanged = (result.unchanged ?? 0) + 1;
+          continue;
+        }
         const persistentSources = sources.filter((source) => shouldPersistSourceUrl(source.url));
         upsert(lock, key, {
           status: "downloaded",
@@ -6821,10 +6872,10 @@ function isSha256Hash(value) {
 function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
-async function loadCache(path27) {
-  if (!existsSync11(path27)) return { version: 1, hashes: {} };
+async function loadCache(path29) {
+  if (!existsSync11(path29)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile8(path27, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile8(path29, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -6836,18 +6887,18 @@ async function loadCache(path27) {
     return { version: 1, hashes: {} };
   }
 }
-async function saveCache(path27, cache) {
+async function saveCache(path29, 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 mkdir4(pathModule.dirname(pathModule.resolve(path27)), { recursive: true });
-  const tmp = `${path27}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await mkdir4(pathModule.dirname(pathModule.resolve(path29)), { recursive: true });
+  const tmp = `${path29}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile4(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
-    await rename4(tmp, path27);
+    await rename4(tmp, path29);
   } finally {
     await rm5(tmp, { force: true });
   }
@@ -7096,6 +7147,7 @@ function buildManifest(name, styleId, generator, outDir, scanned) {
     assets[asset.id] = {
       prompt: "",
       promptByStyle: {},
+      sourceByStyle: {},
       category: asset.category || void 0,
       file: asset.file,
       tags: [],
@@ -7789,9 +7841,9 @@ async function runPicker(provider, lock, lockPath, opts = {}) {
 
 // src/gallery/snapshot.ts
 import { createHash as createHash3 } from "crypto";
-import { existsSync as existsSync16 } from "fs";
+import { existsSync as existsSync17 } from "fs";
 import { readFile as readFile15, stat as stat3 } from "fs/promises";
-import path20 from "path";
+import path22 from "path";
 
 // src/workspace.ts
 import { mkdir as mkdir5, readFile as readFile13, rename as rename5, rm as rm6, writeFile as writeFile7 } from "fs/promises";
@@ -7927,6 +7979,10 @@ function validateWorkspace(ws, dir) {
 }
 
 // src/gallery/edit.ts
+import path21 from "path";
+import { z as z6 } from "zod";
+
+// src/manifest-edit.ts
 import { readFile as readFile14, rename as rename6, rm as rm7, writeFile as writeFile8 } from "fs/promises";
 import path19 from "path";
 import { z as z5 } from "zod";
@@ -7973,6 +8029,22 @@ var ManifestEditSchema = z5.discriminatedUnion("action", [
     expectedSha256: HexSha,
     asset: NewAssetSchema
   }).strict(),
+  z5.object({
+    action: z5.literal("set-source"),
+    project: z5.string().min(1).optional(),
+    assetId: z5.string().min(1),
+    styleId: z5.string().min(1),
+    /** Manifest-relative path of the art that stands in for this asset in this style. */
+    source: z5.string().min(1),
+    expectedSha256: HexSha
+  }).strict(),
+  z5.object({
+    action: z5.literal("clear-source"),
+    project: z5.string().min(1).optional(),
+    assetId: z5.string().min(1),
+    styleId: z5.string().min(1),
+    expectedSha256: HexSha
+  }).strict(),
   z5.object({
     action: z5.literal("patch-style"),
     project: z5.string().min(1).optional(),
@@ -8023,8 +8095,38 @@ function setOrDelete(target, key, value) {
   if (value === null || value === void 0) delete target[key];
   else target[key] = value;
 }
+function assetStyles(raw, asset) {
+  const own = Array.isArray(asset.styles) ? asset.styles : [];
+  return own.length ? own : Object.keys(raw.styles ?? {});
+}
 function applyEdit(raw, edit) {
   raw.assets ??= {};
+  if (edit.action === "set-source" || edit.action === "clear-source") {
+    const asset2 = Object.hasOwn(raw.assets, edit.assetId) ? raw.assets[edit.assetId] : void 0;
+    if (!asset2) throw new ManifestEditError(`asset "${edit.assetId}" is not declared by the manifest`);
+    if (!raw.styles || !Object.hasOwn(raw.styles, edit.styleId)) {
+      throw new ManifestEditError(`unknown style "${edit.styleId}"`);
+    }
+    if (!assetStyles(raw, asset2).includes(edit.styleId)) {
+      throw new ManifestEditError(`asset "${edit.assetId}" is not in style "${edit.styleId}"`);
+    }
+    const single = assetStyles(raw, asset2).length === 1;
+    const byStyle = { ...asset2.sourceByStyle ?? {} };
+    if (edit.action === "set-source") {
+      if (single) {
+        asset2.source = edit.source;
+        delete byStyle[edit.styleId];
+      } else {
+        byStyle[edit.styleId] = edit.source;
+      }
+    } else {
+      delete byStyle[edit.styleId];
+      if (single) delete asset2.source;
+    }
+    if (Object.keys(byStyle).length) asset2.sourceByStyle = byStyle;
+    else delete asset2.sourceByStyle;
+    return;
+  }
   if (edit.action === "patch-style") {
     const style = raw.styles && Object.hasOwn(raw.styles, edit.styleId) ? raw.styles[edit.styleId] : void 0;
     if (!style) throw new ManifestEditError(`style "${edit.styleId}" is not declared by the manifest`);
@@ -8128,10 +8230,134 @@ async function applyManifestEdit(manifestPath, edit) {
   }
   return { manifestPath: absolute, sha256: sha256(next), changed: true };
 }
+
+// src/pipeline/hand-edit.ts
+import { spawn as spawn2 } from "child_process";
+import { existsSync as existsSync16 } from "fs";
+import { copyFile, mkdir as mkdir6 } from "fs/promises";
+import path20 from "path";
+var HAND_EDIT_DIR = "edits";
+function handEditPath(loaded, spec) {
+  const style = loaded.manifest.styles[spec.styleId];
+  const outDir = path20.resolve(loaded.root, style?.outDir ?? ".");
+  const relative = path20.relative(outDir, spec.outFile);
+  const inside = relative && !relative.startsWith("..") && !path20.isAbsolute(relative);
+  const file = inside ? relative : path20.basename(spec.outFile);
+  return path20.join(outDir, HAND_EDIT_DIR, file.replace(/\.gif$/i, ".png"));
+}
+function handEditBase(spec, lock) {
+  const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
+  if (entry) {
+    if (entry.outputs.length !== 1) return null;
+    const primary = primaryOutput(entry);
+    if (!primary || primary.mediaType && primary.mediaType !== "image/png") return null;
+    const file = currentEntryOutputPath(entry, spec, 0);
+    return existsSync16(file) ? file : null;
+  }
+  return existsSync16(spec.outFile) ? spec.outFile : null;
+}
+async function startHandEdit(loaded, lock, spec, opts = {}) {
+  const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
+  if (entry && entry.outputs.length > 1) {
+    throw new ManifestEditError(
+      `${spec.styleId}/${spec.assetId} has ${entry.outputs.length} outputs; hand edits currently cover single-image assets`
+    );
+  }
+  const existing = spec.source ? path20.resolve(loaded.root, spec.source) : null;
+  const editPath = existing ?? handEditPath(loaded, spec);
+  let created = false;
+  if (!existsSync16(editPath)) {
+    const base = handEditBase(spec, lock);
+    if (!base) {
+      throw new ManifestEditError(
+        `${spec.styleId}/${spec.assetId} has no generated PNG on disk to start from; generate or restore it first`
+      );
+    }
+    await mkdir6(path20.dirname(editPath), { recursive: true });
+    await copyFile(base, editPath);
+    created = true;
+  }
+  const source = portableOutputPath(editPath, loaded.root);
+  let declared = false;
+  let manifestSha256 = opts.expectedSha256 ?? await sha256File(loaded.path);
+  if (spec.source !== source) {
+    const result = await applyManifestEdit(loaded.path, {
+      action: "set-source",
+      assetId: spec.assetId,
+      styleId: spec.styleId,
+      source,
+      expectedSha256: manifestSha256
+    });
+    declared = result.changed;
+    manifestSha256 = result.sha256;
+  }
+  return { editPath, source, created, declared, manifestSha256 };
+}
+async function detachHandEdit(loaded, spec, opts = {}) {
+  if (!spec.source) {
+    return { manifestSha256: opts.expectedSha256 ?? await sha256File(loaded.path), changed: false };
+  }
+  const result = await applyManifestEdit(loaded.path, {
+    action: "clear-source",
+    assetId: spec.assetId,
+    styleId: spec.styleId,
+    expectedSha256: opts.expectedSha256 ?? await sha256File(loaded.path)
+  });
+  return { manifestSha256: result.sha256, changed: result.changed };
+}
+function openInEditor(file, editor = process.env.PIXELKILN_EDITOR) {
+  const command = editor?.trim() ? editor.trim().split(/\s+/) : process.platform === "darwin" ? ["open"] : process.platform === "win32" ? ["cmd", "/c", "start", ""] : ["xdg-open"];
+  const [program, ...args] = command;
+  const child = spawn2(program, [...args, file], { stdio: "ignore", detached: true });
+  child.on("error", () => {
+  });
+  child.unref();
+  return command.join(" ");
+}
+
+// src/gallery/edit.ts
+var HandEditRequestSchema = z6.discriminatedUnion("action", [
+  z6.object({
+    action: z6.literal("start-edit"),
+    project: z6.string().min(1).optional(),
+    assetId: z6.string().min(1),
+    styleId: z6.string().min(1),
+    expectedSha256: z6.string().regex(/^[0-9a-f]{64}$/),
+    /** Also launch the author's editor on the file. */
+    open: z6.boolean().optional()
+  }).strict(),
+  z6.object({
+    action: z6.literal("detach-edit"),
+    project: z6.string().min(1).optional(),
+    assetId: z6.string().min(1),
+    styleId: z6.string().min(1),
+    expectedSha256: z6.string().regex(/^[0-9a-f]{64}$/)
+  }).strict()
+]);
 function createGalleryEditHandler(opts) {
   const log2 = opts.onProgress ?? (() => {
   });
   return async (body) => {
+    const handEdit = HandEditRequestSchema.safeParse(body);
+    if (handEdit.success) {
+      if (!opts.loadProject) throw new ManifestEditError("hand edits are not available in this gallery");
+      const request = handEdit.data;
+      const ctx = await opts.loadProject(request.project);
+      const spec = ctx.specs.find((candidate) => lockKey(candidate.styleId, candidate.assetId) === lockKey(request.styleId, request.assetId));
+      if (!spec) throw new ManifestEditError(`"${request.styleId}/${request.assetId}" is not declared by the manifest`);
+      if (request.action === "start-edit") {
+        const started = await startHandEdit(ctx.loaded, ctx.lock, spec, { expectedSha256: request.expectedSha256 });
+        log2(`  hand edit ${started.created ? "created" : "found"}: ${started.source}${started.declared ? " (declared in the manifest)" : ""}`);
+        if (request.open) {
+          const command = (opts.openEditor ?? openInEditor)(started.editPath);
+          log2(`  opened with: ${command}`);
+        }
+      } else {
+        const result2 = await detachHandEdit(ctx.loaded, spec, { expectedSha256: request.expectedSha256 });
+        if (result2.changed) log2(`  hand edit detached: ${request.styleId}/${request.assetId} (file kept)`);
+      }
+      return opts.reload();
+    }
     const parsed = ManifestEditSchema.safeParse(body);
     if (!parsed.success) {
       throw new ManifestEditError(
@@ -8146,9 +8372,9 @@ function createGalleryEditHandler(opts) {
     }
     const result = await applyManifestEdit(manifestPath, parsed.data);
     if (result.changed) {
-      const relative = path19.relative(process.cwd(), result.manifestPath);
+      const relative = path21.relative(process.cwd(), result.manifestPath);
       const shown = !relative || relative.startsWith("..") ? result.manifestPath : relative;
-      const subject = parsed.data.action === "patch-style" ? `style ${parsed.data.styleId}` : parsed.data.assetId;
+      const subject = parsed.data.action === "patch-style" ? `style ${parsed.data.styleId}` : parsed.data.action === "set-source" || parsed.data.action === "clear-source" ? `${parsed.data.styleId}/${parsed.data.assetId} source` : parsed.data.assetId;
       log2(`  manifest edited: ${parsed.data.action === "add-asset" ? "added" : "changed"} ${subject} in ${shown}`);
     }
     return opts.reload();
@@ -8157,7 +8383,7 @@ function createGalleryEditHandler(opts) {
 
 // src/gallery/snapshot.ts
 function galleryMediaId(absolutePath) {
-  return createHash3("sha256").update(path20.resolve(absolutePath)).digest("hex").slice(0, 24);
+  return createHash3("sha256").update(path22.resolve(absolutePath)).digest("hex").slice(0, 24);
 }
 function galleryMediaRoute(id) {
   return `/media/${id}`;
@@ -8182,23 +8408,24 @@ function metadataFps(entry) {
   }
   return null;
 }
-async function fileBytes(absolutePath) {
+async function fileInfo(absolutePath) {
   try {
     const info = await stat3(absolutePath);
-    return info.isFile() ? info.size : null;
+    return info.isFile() ? { bytes: info.size, modifiedAt: info.mtime.toISOString() } : null;
   } catch {
     return null;
   }
 }
 async function describeOutput(media, root, absolutePath, recorded = {}) {
-  const bytes = await fileBytes(absolutePath);
-  const exists = bytes !== null;
+  const info = await fileInfo(absolutePath);
+  const exists = info !== null;
   const mediaType = recorded.mediaType ?? mediaTypeFromExtension(absolutePath);
   let url = null;
   if (exists && mediaType) {
     const id = galleryMediaId(absolutePath);
     media.set(id, { path: absolutePath, contentType: mediaType });
-    url = `${galleryMediaRoute(id)}?v=${(recorded.sha256 ?? String(bytes)).slice(0, 16)}`;
+    const version = recorded.sha256 ?? `${info.bytes}-${Date.parse(info.modifiedAt).toString(36)}`;
+    url = `${galleryMediaRoute(id)}?v=${version.slice(0, 24)}`;
   }
   return {
     path: portableOutputPath(absolutePath, root),
@@ -8207,17 +8434,18 @@ async function describeOutput(media, root, absolutePath, recorded = {}) {
     role: recorded.role ?? null,
     mediaType,
     exists,
-    bytes,
+    bytes: info?.bytes ?? null,
+    modifiedAt: info?.modifiedAt ?? null,
     url
   };
 }
 async function describeQuality(media, root, inspection) {
   const outputPaths = inspection.outputs ?? [inspection.output];
   const outputs = await Promise.all(
-    outputPaths.map((file) => describeOutput(media, root, path20.resolve(root, file)))
+    outputPaths.map((file) => describeOutput(media, root, path22.resolve(root, file)))
   );
-  const recordPath = path20.resolve(root, inspection.record);
-  const recordExists = existsSync16(recordPath);
+  const recordPath = path22.resolve(root, inspection.record);
+  const recordExists = existsSync17(recordPath);
   let options = null;
   let check = null;
   if (recordExists) {
@@ -8236,7 +8464,7 @@ async function describeQuality(media, root, inspection) {
   return {
     state: inspection.state,
     reason: inspection.reason,
-    output: portableOutputPath(path20.resolve(root, inspection.output), root),
+    output: portableOutputPath(path22.resolve(root, inspection.output), root),
     record: portableOutputPath(recordPath, root),
     recordExists,
     outputs,
@@ -8286,15 +8514,24 @@ async function buildGallerySnapshot(opts) {
     const entry = lock.entries[key];
     const asset = loaded.manifest.assets[spec.assetId] ?? null;
     let outputs;
+    let edit = null;
+    let editStatus = null;
     if (entry && entry.outputs.length) {
       outputs = await Promise.all(
         entry.outputs.map(
           (output, index) => describeOutput(media, root, currentEntryOutputPath(entry, spec, index), output)
         )
       );
+      if (spec.source) {
+        const editPath = path22.resolve(root, spec.source);
+        const editSha = existsSync17(editPath) ? await sha256File(editPath) : null;
+        edit = await describeOutput(media, root, editPath, { sha256: editSha });
+        const generated = outputs[0];
+        editStatus = !edit.exists ? "missing" : generated && editSha === generated.sha256 ? "same" : generated?.modifiedAt && edit.modifiedAt && generated.modifiedAt > edit.modifiedAt && generated.exists ? "regenerated-since" : "edited";
+      }
     } else if (spec.source) {
-      outputs = [await describeOutput(media, root, path20.resolve(root, spec.source))];
-    } else if (!entry && existsSync16(spec.outFile)) {
+      outputs = [await describeOutput(media, root, path22.resolve(root, spec.source))];
+    } else if (!entry && existsSync17(spec.outFile)) {
       outputs = [await describeOutput(media, root, spec.outFile)];
     } else {
       outputs = [];
@@ -8338,6 +8575,10 @@ async function buildGallerySnapshot(opts) {
       providerMetadata: entry?.providerMetadata ?? {},
       asset,
       source: spec.source ?? null,
+      edit,
+      editStatus,
+      upstreamUrl: entry?.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
+      refreshable: Boolean(entry && entry.status === "downloaded" && entry.outputs.length && (entry.sourceUrls?.length || entry.sourceUrl)),
       tags: spec.tags,
       category: asset?.category ?? null
     });
@@ -8390,6 +8631,10 @@ async function buildGallerySnapshot(opts) {
       providerMetadata: entry.providerMetadata ?? {},
       asset: null,
       source: null,
+      edit: null,
+      editStatus: null,
+      upstreamUrl: entry.provider === "pixellab" ? pixelLabObjectUrl(entry.generator, entry.objectId) : null,
+      refreshable: false,
       tags: [],
       category: null
     });
@@ -8457,7 +8702,7 @@ async function buildGallerySnapshot(opts) {
       id: loaded.manifest.name,
       name: loaded.manifest.name,
       manifest: loaded.path,
-      lock: path20.resolve(opts.lockPath),
+      lock: path22.resolve(opts.lockPath),
       root,
       provider: loaded.manifest.provider,
       account: null,
@@ -8482,7 +8727,7 @@ async function buildGallerySnapshot(opts) {
   return { snapshot, media };
 }
 async function buildWorkspaceGallerySnapshot(opts) {
-  const dir = path20.dirname(path20.resolve(opts.workspacePath));
+  const dir = path22.dirname(path22.resolve(opts.workspacePath));
   const media = /* @__PURE__ */ new Map();
   const projects = [];
   const items = [];
@@ -8525,7 +8770,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: loaded.manifest.name,
         manifest: manifestPath,
-        lock: path20.resolve(lockPath),
+        lock: path22.resolve(lockPath),
         root: loaded.root,
         provider: loaded.manifest.provider,
         account: project.account ?? null,
@@ -8540,8 +8785,8 @@ async function buildWorkspaceGallerySnapshot(opts) {
         id: project.id,
         name: project.id,
         manifest: manifestPath,
-        lock: path20.resolve(lockPath),
-        root: path20.dirname(manifestPath),
+        lock: path22.resolve(lockPath),
+        root: path22.dirname(manifestPath),
         provider: project.provider,
         account: project.account ?? null,
         manifestSha256: null,
@@ -8567,7 +8812,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
       version: 1,
       generatedAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
       project: null,
-      workspace: { path: path20.resolve(opts.workspacePath), dir, projects },
+      workspace: { path: path22.resolve(opts.workspacePath), dir, projects },
       filter,
       totals: {
         entries: projects.reduce((sum, project) => sum + project.entries, 0),
@@ -8584,7 +8829,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
 }
 
 // src/gallery/server.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import { randomBytes } from "crypto";
 import { createServer as createServer2 } from "http";
 import { readFile as readFile16 } from "fs/promises";
@@ -8860,6 +9105,14 @@ function renderGallery(snapshot, opts = {}) {
   .tray > button { padding:5px 11px; font-size:12.5px; }
   @media (max-width: 900px) { .sheet.review-host, .sheet.compare-host { width:100vw; } }
   .drawer .gen { display:flex; gap:8px; flex-wrap:wrap; margin-top:12px; }
+  .pair { display:grid; grid-template-columns:1fr 1fr; gap:8px; margin:8px 0 10px; }
+  .pair figure { margin:0; border:1px solid var(--line); background:var(--panel-deep); background-image:var(--checker);
+    background-size:12px 12px; background-position:0 0,6px 6px; display:grid; place-items:center; padding:8px; min-height:96px; }
+  .pair figure img { image-rendering:pixelated; display:block; max-width:100%; }
+  .pair figcaption { font:11px/1.4 var(--mono); color:var(--dim); background:var(--panel); padding:2px 6px; margin-top:6px; }
+  .card .pen { position:absolute; right:6px; top:6px; background:var(--panel); color:var(--accent-soft); border:1px solid var(--accent);
+    font:700 11px/1 var(--mono); padding:3px 5px; }
+  .hand-actions { display:flex; gap:8px; flex-wrap:wrap; margin-top:8px; }
   .drawer .gen button.primary { padding:7px 14px; }
   @media (max-width: 720px) {
     .bar, .totals, .chips, .style, footer { padding-inline:14px; }
@@ -9059,7 +9312,7 @@ function renderJobs() {
     const row = el('div', 'job');
     const ph = el('span', 'ph');
     ph.append(el('i', 'dot ' + PHASE_TONE[job.phase]), document.createTextNode(job.phase));
-    const what = (job.mode === 'resume' ? 'resume ' : 'generate ') + job.keys.length + (job.keys.length === 1 ? ' asset' : ' assets') +
+    const what = (job.mode === 'refresh' ? 'pull upstream for ' : job.mode === 'resume' ? 'resume ' : 'generate ') + job.keys.length + (job.keys.length === 1 ? ' asset' : ' assets') +
       (job.project ? ' in ' + job.project : '');
     const last = el('span', 'last', what + (job.messages.length ? ' \u2014 ' + job.messages[job.messages.length - 1].trim() : ''));
     last.title = job.keys.join('\\n');
@@ -9098,13 +9351,15 @@ function budgetLine() {
 
 // The confirm step: what will be sent, what it is estimated to cost, and what
 // this session may still spend. Mirrors gen's "Spend \u2026 on N asset(s)?" prompt.
-function generateDialog(items, { project = null, force = false, resume = false } = {}) {
+function generateDialog(items, { project = null, force = false, resume = false, refresh = false } = {}) {
   const host = $('dialog-host');
   host.textContent = '';
   const wrap = el('div', 'dialog');
   const form = el('form');
-  form.append(el('h3', null, resume ? 'Resume ' + items.length + (items.length === 1 ? ' asset' : ' assets')
-    : (force ? 'Regenerate ' : 'Generate ') + items.length + (items.length === 1 ? ' asset' : ' assets')));
+  const noun = items.length + (items.length === 1 ? ' asset' : ' assets');
+  form.append(el('h3', null, refresh ? 'Pull upstream changes for ' + noun
+    : resume ? 'Resume ' + noun
+    : (force ? 'Regenerate ' : 'Generate ') + noun));
   const table = el('table');
   const thead = el('tr'); thead.append(el('th', null, 'asset'), el('th', null, 'state'), el('th', 'n', 'candidates'), el('th', 'n', 'estimate'));
   table.append(thead);
@@ -9112,16 +9367,18 @@ function generateDialog(items, { project = null, force = false, resume = false }
   for (const item of items) {
     const tr = el('tr');
     tr.append(el('td', 'mono', item.key), el('td', null, item.state), el('td', 'n', item.candidates ?? '\u2014'),
-      el('td', 'n', resume ? 'no cost' : fmtCost(item.costUnit, item.estimatedCost ?? 0)));
+      el('td', 'n', resume || refresh ? 'no cost' : fmtCost(item.costUnit, item.estimatedCost ?? 0)));
     table.append(tr);
-    if (!resume) {
+    if (!resume && !refresh) {
       const g = byProvider.get(item.provider) || { cost: 0, unit: item.costUnit };
       g.cost += item.estimatedCost ?? 0; byProvider.set(item.provider, g);
     }
   }
   form.append(table);
   const sum = el('div', 'sum');
-  if (resume) {
+  if (refresh) {
+    sum.append(el('div', null, 'Re-downloads each object from the provider and replaces the local file only when the object changed upstream \u2014 for example after editing it in the provider\u2019s own editor. Unchanged objects are left alone; a file you changed locally is refused. Nothing is submitted.'));
+  } else if (resume) {
     sum.append(el('div', null, 'Polls, reviews, and downloads existing provider work. Nothing is submitted.'));
   } else {
     for (const [provider, g] of byProvider) {
@@ -9138,7 +9395,7 @@ function generateDialog(items, { project = null, force = false, resume = false }
   }
   form.append(sum);
   const actions = el('div', 'actions');
-  const go = el('button', 'primary', resume ? 'Resume' : 'Generate');
+  const go = el('button', 'primary', refresh ? 'Pull changes' : resume ? 'Resume' : 'Generate');
   go.type = 'submit';
   const cancel = el('button', null, 'Cancel'); cancel.type = 'button'; cancel.onclick = () => { host.textContent = ''; };
   const msg = el('span', 'msg');
@@ -9152,6 +9409,7 @@ function generateDialog(items, { project = null, force = false, resume = false }
       if (project) body.project = project;
       if (force) body.force = true;
       if (resume) body.resume = true;
+      if (refresh) body.refresh = true;
       const job = await postGenerate(body);
       host.textContent = '';
       GEN.jobs.unshift(job);
@@ -9306,7 +9564,8 @@ function clearFilters() {
 
 function thumb(item) {
   const cell = el('div', 'cell');
-  const shown = item.outputs.filter((o) => o.url);
+  // A hand edit is what ships, so it is what the card shows.
+  const shown = item.edit && item.edit.url && item.editStatus === 'edited' ? [item.edit] : item.outputs.filter((o) => o.url);
   if (!shown.length) {
     cell.classList.add('none');
     cell.append(el('span', null, item.state === 'missing' ? 'not generated yet'
@@ -9357,6 +9616,9 @@ function card(item) {
   body.append(meta);
   const cell = thumb(item);
   if (slot >= 0) cell.append(el('span', 'slot', String(slot + 1)));
+  if (item.editStatus === 'edited' || item.editStatus === 'regenerated-since') {
+    const pen = el('span', 'pen', '\u270E'); pen.title = 'hand-edited'; cell.append(pen);
+  }
   c.append(cell, body);
   c.onclick = (e) => { if (e.shiftKey) toggleCompare(item.id); else openItem(item.id); };
   return c;
@@ -9437,6 +9699,13 @@ function renderMain(items) {
         g.onclick = () => generateDialog(snap.items.filter((i) => i.project === s.project && s.actionable.keys.includes(i.key)), { project: s.project });
         tools.append(g);
       }
+      const refreshable = snap.items.filter((i) => i.project === s.project && i.styleId === s.id && i.refreshable && i.upstreamUrl);
+      if (GENERATION && refreshable.length) {
+        const r = el('button', null, 'Pull upstream ' + refreshable.length); r.type = 'button';
+        r.title = 'Re-download objects edited in the provider\u2019s own editor; no cost';
+        r.onclick = () => generateDialog(refreshable, { project: s.project, refresh: true });
+        tools.append(r);
+      }
       const styleKey = 'style:' + (s.project || '') + ':' + s.id;
       if (EDITABLE && s.outDir) {
         const es = el('button', null, ui.editing === styleKey ? 'Cancel' : 'Edit style');
@@ -9530,6 +9799,30 @@ function candidatesControl(style) {
   return wrap;
 }
 
+function upstreamSection(item) {
+  if (!item.upstreamUrl && !(GENERATION && item.refreshable)) return null;
+  const s = el('section', 'meta');
+  s.append(el('h3', null, 'Upstream'));
+  const dl = el('dl');
+  if (item.upstreamUrl) {
+    const a = el('a', null, 'Open in ' + item.provider + ' \u2197');
+    a.href = item.upstreamUrl; a.target = '_blank'; a.rel = 'noopener';
+    row(dl, 'object', a);
+    row(dl, 'note', item.provider === 'pixellab'
+      ? 'The account object this generation came from. Edit it there with PixelLab\u2019s editor, then pull the changes back here; the lockfile records the new bytes as this generation.'
+      : 'The provider\u2019s page for this object.');
+  }
+  s.append(dl);
+  if (GENERATION && item.refreshable) {
+    const acts = el('div', 'hand-actions');
+    const b = el('button', null, 'Pull upstream changes \xB7 no cost'); b.type = 'button';
+    b.onclick = () => generateDialog([item], { project: item.project, refresh: true });
+    acts.append(b);
+    s.append(acts);
+  }
+  return s;
+}
+
 function generateActions(item) {
   const row = el('div', 'gen');
   if (!GENERATION || !item.declared || item.currentSpecHash === null) return row;
@@ -9683,6 +9976,78 @@ function openCompare() {
   close.focus({ preventScroll: true });
 }
 
+// ---- hand edits -------------------------------------------------------------
+
+const EDIT_STATUS_TEXT = {
+  same: 'A copy of the generated art, not changed yet. Open it in your editor and save.',
+  edited: 'Differs from the generated art. mount and pack place this file; the generated file stays as the record.',
+  'regenerated-since': 'The generated art changed after this edit was saved \u2014 the edit is based on an older generation.',
+  missing: 'The declared file is not on disk.',
+};
+async function postHandEdit(item, action, extra) {
+  const pr = projectOf(item);
+  const body = { action, assetId: item.assetId, styleId: item.styleId, expectedSha256: pr.manifestSha256, ...extra };
+  if (item.project) body.project = item.project;
+  snap = await postEdit(body);
+}
+function handEditSection(item) {
+  const canStart = EDITABLE && item.declared && item.asset && projectOf(item)?.manifestSha256 &&
+    item.outputs.length === 1 && item.outputs[0].exists && item.outputs[0].mediaType === 'image/png';
+  if (!item.edit && !canStart) return null;
+  const s = el('section', 'meta');
+  s.append(el('h3', null, 'Hand edit'));
+  if (item.edit) {
+    const pair = el('div', 'pair');
+    const shared = displayScale(item.width, item.height, 200, 160);
+    const fig = (out, label) => {
+      const f = el('figure');
+      if (out && out.url) {
+        const img = el('img'); img.src = out.url; img.alt = label;
+        if (shared >= 1) { img.width = item.width * shared; img.height = item.height * shared; }
+        f.append(img);
+      } else f.append(el('span', 'state-dim', 'not on disk'));
+      f.append(el('figcaption', null, label));
+      return f;
+    };
+    pair.append(fig(item.outputs[0], 'generated'), fig(item.edit, 'edit'));
+    s.append(pair);
+    const dl = el('dl');
+    const tone = item.editStatus === 'edited' ? 'ok' : item.editStatus === 'same' ? 'dim' : 'warn';
+    const st = el('span', 'state-' + tone); st.append(el('i', 'dot ' + tone), document.createTextNode(' ' + item.editStatus));
+    row(dl, 'status', st);
+    row(dl, 'why', EDIT_STATUS_TEXT[item.editStatus] || '');
+    row(dl, 'file', item.edit.path, { mono: true, copy: item.edit.absolutePath });
+    if (item.edit.sha256) row(dl, 'sha256', item.edit.sha256.slice(0, 16) + '\u2026', { mono: true, copy: item.edit.sha256 });
+    row(dl, 'saved', fmtWhen(item.edit.modifiedAt));
+    s.append(dl);
+  } else {
+    s.append(el('div', 'state-dim', 'Touch it up in your own editor. The generated file stays untouched; the edit is a sibling file the manifest points at, and mount and pack place that instead.'));
+  }
+  if (EDITABLE && item.declared && projectOf(item)?.manifestSha256) {
+    const acts = el('div', 'hand-actions');
+    const msg = el('span', 'msg');
+    const go = async (label, action, extra, done) => {
+      const b = el('button', label === 'Detach edit' ? null : 'primary', label); b.type = 'button';
+      b.onclick = async () => {
+        b.disabled = true; msg.className = 'msg'; msg.textContent = '\u2026';
+        try { await postHandEdit(item, action, extra); ui.notice = { id: item.id, text: done }; render(); }
+        catch (err) { b.disabled = false; msg.className = 'msg bad'; msg.textContent = err.message + (err.status === 409 ? ' \u2014 press Refresh.' : ''); }
+      };
+      acts.append(b);
+    };
+    if (item.edit) {
+      go('Open in editor', 'start-edit', { open: true }, 'Opened ' + item.edit.path + ' in your editor. Save there, then Refresh.');
+      go('Detach edit', 'detach-edit', {}, 'Detached. The file is still at ' + item.edit.path + '; the generated art is placed again.');
+    } else if (canStart) {
+      go('Edit by hand', 'start-edit', { open: true }, 'Created the edit file and opened it in your editor. Save there, then Refresh to see it here.');
+      go('Create edit file only', 'start-edit', { open: false }, 'Created the edit file and declared it in the manifest.');
+    }
+    acts.append(msg);
+    s.append(acts);
+  }
+  return s;
+}
+
 // ---- editing (only when the server minted a session) ---------------------
 
 // Styles a parent edit reaches: every descendant (via extends) that does not
@@ -10174,6 +10539,11 @@ function renderDrawer() {
     body.append(s);
   }
 
+  const hand = handEditSection(item);
+  if (hand) body.append(hand);
+  const upstream = upstreamSection(item);
+  if (upstream) body.append(upstream);
+
   if (item.revision || item.revisionParentKey) {
     const { s, dl } = section('Lineage');
     row(dl, 'mode', item.revision ? item.revision.mode : (item.asset && item.asset.revision && item.asset.revision.mode));
@@ -10641,7 +11011,7 @@ async function serveGallery(opts) {
   });
   opts.onReady?.(url);
   if (opts.open !== false && process.platform === "darwin") {
-    spawn2("open", [url], { stdio: "ignore", detached: true }).unref();
+    spawn3("open", [url], { stdio: "ignore", detached: true }).unref();
   }
   return {
     url,
@@ -10655,15 +11025,17 @@ async function serveGallery(opts) {
 
 // src/gallery/generate.ts
 import { randomBytes as randomBytes2 } from "crypto";
-import { z as z6 } from "zod";
-var GenerateRequestSchema = z6.object({
-  project: z6.string().min(1).optional(),
-  keys: z6.array(z6.string().min(1)).min(1).max(500),
+import { z as z7 } from "zod";
+var GenerateRequestSchema = z7.object({
+  project: z7.string().min(1).optional(),
+  keys: z7.array(z7.string().min(1)).min(1).max(500),
   /** Regenerate work that is up to date, as `gen --force` does. */
-  force: z6.boolean().optional(),
+  force: z7.boolean().optional(),
   /** Advance in-flight, review, or selected work without submitting anything. */
-  resume: z6.boolean().optional()
-}).strict();
+  resume: z7.boolean().optional(),
+  /** Re-download downloaded outputs and replace files whose object changed upstream. */
+  refresh: z7.boolean().optional()
+}).strict().refine((request) => !(request.resume && request.refresh), { message: "resume and refresh are exclusive" });
 var GenerateRequestError = class extends Error {
   constructor(message6, status = 400) {
     super(message6);
@@ -10721,6 +11093,20 @@ function createGenerateHandlers(opts) {
     }
     return groups;
   };
+  async function refresh(job, ctx, specs) {
+    job.phase = "fetching";
+    for (const [providerId, providerSpecs] of groupByRecordedProvider(specs, ctx.lock)) {
+      const provider = opts.providerFor(job.project ?? void 0, providerId);
+      const res = await fetchAssets(provider, providerSpecs, ctx.lock, ctx.lockPath, {
+        onProgress: (line) => say(job, line),
+        refresh: true
+      });
+      job.counts.downloaded += res.downloaded;
+      say(job, `${providerId}: ${res.downloaded} changed upstream and replaced, ${res.unchanged ?? 0} unchanged, ${res.skipped} skipped, ${res.failed} failed`);
+    }
+    job.phase = "done";
+    job.finishedAt = now().toISOString();
+  }
   async function settle(job, ctx, specs) {
     job.phase = "polling";
     for (const [providerId, providerSpecs] of groupByRecordedProvider(specs, ctx.lock)) {
@@ -10754,6 +11140,10 @@ function createGenerateHandlers(opts) {
   }
   async function run(job, ctx, specs, groups) {
     try {
+      if (job.mode === "refresh") {
+        await refresh(job, ctx, specs);
+        return;
+      }
       if (job.mode === "generate") {
         job.phase = "submitting";
         for (const group of groups) {
@@ -10817,7 +11207,7 @@ function createGenerateHandlers(opts) {
         if (holder) throw new GenerateRequestError(`"${key}" is already being worked on by job ${holder}`, 409);
       }
       let groups = [];
-      if (!request.resume) {
+      if (!request.resume && !request.refresh) {
         const plan = await buildPlan(specs, ctx.lock, { force: request.force });
         if (!plan.actionable.length) {
           const reasons = plan.items.map((item) => `${item.key}: ${item.state} \u2014 ${item.reason}`).slice(0, 5);
@@ -10837,7 +11227,7 @@ function createGenerateHandlers(opts) {
         id: randomBytes2(8).toString("hex"),
         project: request.project ?? null,
         keys: request.keys,
-        mode: request.resume ? "resume" : "generate",
+        mode: request.refresh ? "refresh" : request.resume ? "resume" : "generate",
         phase: "queued",
         startedAt: now().toISOString(),
         finishedAt: null,
@@ -10849,7 +11239,7 @@ function createGenerateHandlers(opts) {
       };
       jobs.set(job.id, job);
       contexts.set(job.id, ctx);
-      say(job, request.resume ? `resuming ${request.keys.length} asset(s) at no cost` : `generating ${groups.reduce((n, g) => n + g.actionable.length, 0)} asset(s): ` + groups.map((g) => `${g.provider} ${formatCost(g.costUnit, g.cost)}`).join("; "));
+      say(job, request.refresh ? `checking ${request.keys.length} asset(s) upstream at no cost` : request.resume ? `resuming ${request.keys.length} asset(s) at no cost` : `generating ${groups.reduce((n, g) => n + g.actionable.length, 0)} asset(s): ` + groups.map((g) => `${g.provider} ${formatCost(g.costUnit, g.cost)}`).join("; "));
       void run(job, ctx, specs, groups);
       return job;
     },
@@ -10900,15 +11290,15 @@ function createGenerateHandlers(opts) {
 
 // src/pipeline/salvage.ts
 import { readFile as readFile17 } from "fs/promises";
-import { existsSync as existsSync17 } from "fs";
-import path21 from "path";
+import { existsSync as existsSync18 } from "fs";
+import path23 from "path";
 function providerClaimId(provider, objectId) {
   return `${encodeURIComponent(provider)}:${encodeURIComponent(objectId)}`;
 }
 async function loadClaims(lockPaths, opts = {}) {
   const claimed = /* @__PURE__ */ new Set();
   for (const p of lockPaths) {
-    if (!existsSync17(p)) throw new Error(`Claim lockfile not found: ${p}`);
+    if (!existsSync18(p)) throw new Error(`Claim lockfile not found: ${p}`);
     let parsed;
     try {
       parsed = parseLock(JSON.parse(await readFile17(p, "utf8")));
@@ -10959,20 +11349,20 @@ function matchStyleByPattern(prompt, manifest) {
   return null;
 }
 async function loadSiblingManifests(ownManifestPath, workspaceManifestPaths, claimPaths) {
-  const own = path21.resolve(ownManifestPath);
+  const own = path23.resolve(ownManifestPath);
   const siblingManifestPaths = [
     .../* @__PURE__ */ new Set([
       ...workspaceManifestPaths,
-      ...claimPaths.map((c) => path21.join(path21.dirname(path21.resolve(c)), "pixelkiln.manifest.json"))
+      ...claimPaths.map((c) => path23.join(path23.dirname(path23.resolve(c)), "pixelkiln.manifest.json"))
     ])
   ];
   const siblings = [];
   for (const siblingManifestPath of siblingManifestPaths) {
-    if (path21.resolve(siblingManifestPath) === own) continue;
-    if (!existsSync17(siblingManifestPath)) continue;
+    if (path23.resolve(siblingManifestPath) === own) continue;
+    if (!existsSync18(siblingManifestPath)) continue;
     try {
       const { manifest } = await loadManifest(siblingManifestPath);
-      siblings.push({ label: path21.basename(path21.dirname(siblingManifestPath)), manifest });
+      siblings.push({ label: path23.basename(path23.dirname(siblingManifestPath)), manifest });
     } catch {
     }
   }
@@ -11191,15 +11581,15 @@ async function workspaceStatus(ws, dir) {
 }
 
 // src/pipeline/cache-health.ts
-import { existsSync as existsSync18 } from "fs";
+import { existsSync as existsSync19 } from "fs";
 import { readFile as readFile18, readdir as readdir2, rm as rm8 } from "fs/promises";
-import path22 from "path";
+import path24 from "path";
 async function inspectCaches(lock, lockPath, options = {}) {
-  if (options.prune && !existsSync18(lockPath)) {
-    throw new Error(`Refusing to prune without an existing lockfile at ${path22.resolve(lockPath)}`);
+  if (options.prune && !existsSync19(lockPath)) {
+    throw new Error(`Refusing to prune without an existing lockfile at ${path24.resolve(lockPath)}`);
   }
-  const contentDir = path22.resolve(path22.dirname(lockPath), ".pixelkiln", "cache");
-  const remotePath = path22.resolve(cachePathFor(lockPath));
+  const contentDir = path24.resolve(path24.dirname(lockPath), ".pixelkiln", "cache");
+  const remotePath = path24.resolve(cachePathFor(lockPath));
   const referenced = new Set(
     Object.values(lock.entries).flatMap((entry) => entry.outputs.map((output) => output.sha256))
   );
@@ -11213,7 +11603,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
     ]);
     for (const name of names) {
       try {
-        await rm8(path22.join(contentDir, name), { force: true });
+        await rm8(path24.join(contentDir, name), { force: true });
         removed.contentFiles++;
       } catch {
       }
@@ -11240,7 +11630,7 @@ async function inspectCaches(lock, lockPath, options = {}) {
 async function inspectContentCache(contentDir, referenced) {
   const report = {
     path: contentDir,
-    exists: existsSync18(contentDir),
+    exists: existsSync19(contentDir),
     files: 0,
     bytes: 0,
     valid: 0,
@@ -11261,7 +11651,7 @@ async function inspectContentCache(contentDir, referenced) {
       continue;
     }
     report.files++;
-    const file = path22.join(contentDir, entry.name);
+    const file = path24.join(contentDir, entry.name);
     const mediaType = mediaTypeFromExtension(entry.name);
     const expected = mediaType ? entry.name.slice(0, -4) : "";
     let bytes;
@@ -11304,7 +11694,7 @@ async function inspectContentCache(contentDir, referenced) {
 async function inspectRemoteHashCache(remotePath) {
   const report = {
     path: remotePath,
-    exists: existsSync18(remotePath),
+    exists: existsSync19(remotePath),
     entries: 0,
     valid: 0,
     invalidIds: [],
@@ -11584,8 +11974,8 @@ function isRecord2(value) {
 }
 
 // src/pick/salvage-server.ts
-import { mkdir as mkdir6, writeFile as writeFile9, readFile as readFile19 } from "fs/promises";
-import path23 from "path";
+import { mkdir as mkdir7, writeFile as writeFile9, readFile as readFile19 } from "fs/promises";
+import path25 from "path";
 
 // src/pick/salvage-sheet.ts
 var escapeHtml3 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -11750,7 +12140,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
   });
   const html = renderSalvageSheet(orphans, {
     styleId: ctx.styleId,
-    importDir: path23.relative(process.cwd(), ctx.importDir) || "."
+    importDir: path25.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]));
@@ -11779,13 +12169,14 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
             if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
             decodePng(buf);
             const assetId = idFromPrompt(orphan.prompt, taken);
-            const rel = path23.join("_salvaged", `${assetId}.png`);
-            const outFile = path23.resolve(ctx.importDir, rel);
-            await mkdir6(path23.dirname(outFile), { recursive: true });
+            const rel = path25.join("_salvaged", `${assetId}.png`);
+            const outFile = path25.resolve(ctx.importDir, rel);
+            await mkdir7(path25.dirname(outFile), { recursive: true });
             await writeFile9(outFile, buf);
             ctx.manifest.assets[assetId] = {
               prompt: orphan.prompt,
               promptByStyle: {},
+              sourceByStyle: {},
               category: "_salvaged",
               file: rel,
               tags: ["salvaged"],
@@ -11813,7 +12204,7 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
               sourceUrl: durableSource,
               sourceUrls: durableSource ? [{ url: durableSource }] : [],
               outputs: [{
-                path: portableOutputPath(outFile, path23.dirname(ctx.manifestPath)),
+                path: portableOutputPath(outFile, path25.dirname(ctx.manifestPath)),
                 sha256: sha256(buf)
               }],
               submittedAt: orphan.createdAt,
@@ -11847,51 +12238,51 @@ async function runSalvage(provider, orphans, ctx, opts = {}) {
 }
 
 // src/recipes.ts
-import path24 from "path";
-import { existsSync as existsSync19 } from "fs";
+import path26 from "path";
+import { existsSync as existsSync20 } from "fs";
 import { readdir as readdir3, readFile as readFile20 } from "fs/promises";
 import { fileURLToPath } from "url";
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var SHA256_RE = /^[0-9a-f]{64}$/;
 var RECIPE_ID_RE = /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
 var VERSION_RE = /^\d+\.\d+\.\d+$/;
 var RECIPE_FILE = "pixelkiln.recipe.json";
 var RECIPE_DIR_TOKEN = "{{recipeDir}}";
-var PortablePathSchema = z7.string().min(1).refine((value) => {
-  if (value.includes("\\") || path24.posix.isAbsolute(value)) return false;
+var PortablePathSchema = z8.string().min(1).refine((value) => {
+  if (value.includes("\\") || path26.posix.isAbsolute(value)) return false;
   const parts = value.split("/");
   return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
 }, "expected a portable relative path without '.', '..', or backslashes");
-var RecipeBindingSchema = z7.object({
-  nodeId: z7.string().min(1),
-  input: z7.string().min(1)
+var RecipeBindingSchema = z8.object({
+  nodeId: z8.string().min(1),
+  input: z8.string().min(1)
 }).strict();
-var RecipeSchema = z7.object({
-  $schema: z7.string().url().optional(),
-  format: z7.literal("pixelkiln-recipe"),
-  schemaVersion: z7.literal(1),
-  id: z7.string().regex(RECIPE_ID_RE, "expected provider/name"),
-  version: z7.string().regex(VERSION_RE, "expected x.y.z"),
-  provider: z7.string().regex(/^[a-z0-9][a-z0-9-]*$/),
-  summary: z7.string().min(1).max(240),
-  files: z7.array(z7.object({
+var RecipeSchema = z8.object({
+  $schema: z8.string().url().optional(),
+  format: z8.literal("pixelkiln-recipe"),
+  schemaVersion: z8.literal(1),
+  id: z8.string().regex(RECIPE_ID_RE, "expected provider/name"),
+  version: z8.string().regex(VERSION_RE, "expected x.y.z"),
+  provider: z8.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+  summary: z8.string().min(1).max(240),
+  files: z8.array(z8.object({
     path: PortablePathSchema,
-    role: z7.enum(["workflow", "reference"]),
-    sha256: z7.string().regex(SHA256_RE)
+    role: z8.enum(["workflow", "reference"]),
+    sha256: z8.string().regex(SHA256_RE)
   }).strict()).default([]),
-  models: z7.array(z7.object({
+  models: z8.array(z8.object({
     path: PortablePathSchema,
-    sha256: z7.string().regex(SHA256_RE),
-    source: z7.string().url(),
-    license: z7.string().min(1)
+    sha256: z8.string().regex(SHA256_RE),
+    source: z8.string().url(),
+    license: z8.string().min(1)
   }).strict()).default([]),
-  styleId: z7.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+  styleId: z8.string().regex(/^[a-z0-9][a-z0-9-]*$/),
   style: StyleSchema,
-  workflow: z7.object({
+  workflow: z8.object({
     path: PortablePathSchema,
-    outputNodeId: z7.string().min(1),
-    numImages: z7.number().int().min(1).max(16),
-    bindings: z7.object({
+    outputNodeId: z8.string().min(1),
+    numImages: z8.number().int().min(1).max(16),
+    bindings: z8.object({
       prompt: RecipeBindingSchema,
       width: RecipeBindingSchema.optional(),
       height: RecipeBindingSchema.optional(),
@@ -11902,67 +12293,67 @@ var RecipeSchema = z7.object({
       strength: RecipeBindingSchema.optional()
     }).strict()
   }).strict().optional(),
-  quality: z7.object({
-    stage: z7.enum(["composition-source", "production-candidate"]),
-    workingCanvas: z7.object({
-      width: z7.number().int().min(16),
-      height: z7.number().int().min(16)
+  quality: z8.object({
+    stage: z8.enum(["composition-source", "production-candidate"]),
+    workingCanvas: z8.object({
+      width: z8.number().int().min(16),
+      height: z8.number().int().min(16)
     }).strict(),
-    recommendedNativeSize: z7.object({
-      min: z7.number().int().min(1),
-      max: z7.number().int().min(1)
+    recommendedNativeSize: z8.object({
+      min: z8.number().int().min(1),
+      max: z8.number().int().min(1)
     }).strict(),
-    paletteColors: z7.object({
-      min: z7.number().int().min(1),
-      max: z7.number().int().min(1)
+    paletteColors: z8.object({
+      min: z8.number().int().min(1),
+      max: z8.number().int().min(1)
     }).strict(),
-    background: z7.enum(["opaque", "transparent", "full-bleed"]),
-    checks: z7.array(z7.enum([
+    background: z8.enum(["opaque", "transparent", "full-bleed"]),
+    checks: z8.array(z8.enum([
       "prompt-coverage",
       "native-grid",
       "final-palette",
       "alpha-edge",
       "human-1x"
     ])).min(1),
-    notes: z7.array(z7.string().min(1)).default([])
+    notes: z8.array(z8.string().min(1)).default([])
   }).strict(),
-  integrity: z7.object({
-    algorithm: z7.literal("sha256"),
-    digest: z7.string().regex(SHA256_RE)
+  integrity: z8.object({
+    algorithm: z8.literal("sha256"),
+    digest: z8.string().regex(SHA256_RE)
   }).strict()
 }).strict().superRefine((recipe, context) => {
   if (recipe.style.provider && recipe.style.provider !== recipe.provider) {
     context.addIssue({
-      code: z7.ZodIssueCode.custom,
+      code: z8.ZodIssueCode.custom,
       path: ["style", "provider"],
       message: "must match the recipe provider"
     });
   }
   const filePaths = recipe.files.map((file) => file.path);
   if (new Set(filePaths).size !== filePaths.length) {
-    context.addIssue({ code: z7.ZodIssueCode.custom, path: ["files"], message: "duplicate file path" });
+    context.addIssue({ code: z8.ZodIssueCode.custom, path: ["files"], message: "duplicate file path" });
   }
   const modelPaths = recipe.models.map((model) => model.path);
   if (new Set(modelPaths).size !== modelPaths.length) {
-    context.addIssue({ code: z7.ZodIssueCode.custom, path: ["models"], message: "duplicate model path" });
+    context.addIssue({ code: z8.ZodIssueCode.custom, path: ["models"], message: "duplicate model path" });
   }
   if (filePaths.includes(RECIPE_FILE)) {
     context.addIssue({
-      code: z7.ZodIssueCode.custom,
+      code: z8.ZodIssueCode.custom,
       path: ["files"],
       message: `${RECIPE_FILE} cannot hash itself`
     });
   }
   if (recipe.quality.recommendedNativeSize.min > recipe.quality.recommendedNativeSize.max) {
     context.addIssue({
-      code: z7.ZodIssueCode.custom,
+      code: z8.ZodIssueCode.custom,
       path: ["quality", "recommendedNativeSize"],
       message: "min cannot exceed max"
     });
   }
   if (recipe.quality.paletteColors.min > recipe.quality.paletteColors.max) {
     context.addIssue({
-      code: z7.ZodIssueCode.custom,
+      code: z8.ZodIssueCode.custom,
       path: ["quality", "paletteColors"],
       message: "min cannot exceed max"
     });
@@ -11971,7 +12362,7 @@ var RecipeSchema = z7.object({
     (file) => file.path === recipe.workflow.path && file.role === "workflow"
   )) {
     context.addIssue({
-      code: z7.ZodIssueCode.custom,
+      code: z8.ZodIssueCode.custom,
       path: ["workflow", "path"],
       message: "must name a file whose role is workflow"
     });
@@ -11979,7 +12370,7 @@ var RecipeSchema = z7.object({
   if (recipe.provider === "comfyui") {
     if (!recipe.workflow) {
       context.addIssue({
-        code: z7.ZodIssueCode.custom,
+        code: z8.ZodIssueCode.custom,
         path: ["workflow"],
         message: "ComfyUI recipes require workflow metadata"
       });
@@ -11988,7 +12379,7 @@ var RecipeSchema = z7.object({
     const options = recipe.style.providerOptions.comfyui;
     if (!options || typeof options !== "object" || Array.isArray(options)) {
       context.addIssue({
-        code: z7.ZodIssueCode.custom,
+        code: z8.ZodIssueCode.custom,
         path: ["style", "providerOptions", "comfyui"],
         message: "ComfyUI recipes require ComfyUI provider options"
       });
@@ -12002,7 +12393,7 @@ var RecipeSchema = z7.object({
     };
     if (JSON.stringify(canonical3(options)) !== JSON.stringify(canonical3(expected))) {
       context.addIssue({
-        code: z7.ZodIssueCode.custom,
+        code: z8.ZodIssueCode.custom,
         path: ["style", "providerOptions", "comfyui"],
         message: "must match workflow metadata and use {{recipeDir}} for workflowFile"
       });
@@ -12034,7 +12425,7 @@ function message4(error) {
   return error instanceof Error ? error.message : String(error);
 }
 async function readRecipeFile(recipePath, bundled) {
-  const absolute = path24.resolve(recipePath);
+  const absolute = path26.resolve(recipePath);
   let raw;
   try {
     raw = JSON.parse(await readFile20(absolute, "utf8"));
@@ -12048,13 +12439,13 @@ async function readRecipeFile(recipePath, bundled) {
 ` + parsed.error.issues.map((issue) => `  ${issue.path.join(".") || "$"}: ${issue.message}`).join("\n")
     );
   }
-  return { recipe: parsed.data, path: absolute, dir: path24.dirname(absolute), bundled };
+  return { recipe: parsed.data, path: absolute, dir: path26.dirname(absolute), bundled };
 }
 async function walkRecipeFiles(root) {
-  if (!existsSync19(root)) return [];
+  if (!existsSync20(root)) return [];
   const out = [];
   for (const entry of await readdir3(root, { withFileTypes: true })) {
-    const resolved = path24.join(root, entry.name);
+    const resolved = path26.join(root, entry.name);
     if (entry.isDirectory()) out.push(...await walkRecipeFiles(resolved));
     else if (entry.isFile() && entry.name === RECIPE_FILE) out.push(resolved);
   }
@@ -12065,7 +12456,7 @@ function bundledRecipeRoot() {
 }
 async function listBundledRecipes(root = bundledRecipeRoot()) {
   const recipes = await Promise.all(
-    (await walkRecipeFiles(path24.resolve(root))).map((file) => readRecipeFile(file, true))
+    (await walkRecipeFiles(path26.resolve(root))).map((file) => readRecipeFile(file, true))
   );
   return recipes.sort(
     (a, b) => a.recipe.id.localeCompare(b.recipe.id) || compareVersions(b.recipe.version, a.recipe.version)
@@ -12088,9 +12479,9 @@ function parseSelector(selector) {
   return { id: match[1], version: match[2] };
 }
 async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
-  const local = path24.resolve(target);
-  if (existsSync19(local)) {
-    const recipePath = path24.basename(local) === RECIPE_FILE ? local : path24.join(local, RECIPE_FILE);
+  const local = path26.resolve(target);
+  if (existsSync20(local)) {
+    const recipePath = path26.basename(local) === RECIPE_FILE ? local : path26.join(local, RECIPE_FILE);
     return readRecipeFile(recipePath, false);
   }
   if (target.startsWith(".") || target.startsWith("/") || target.includes("\\")) {
@@ -12104,8 +12495,8 @@ async function resolveRecipe(target, bundledRoot = bundledRecipeRoot()) {
   return matches[0];
 }
 async function verifyFile(root, file) {
-  const absolute = path24.resolve(root, ...file.path.split("/"));
-  if (!existsSync19(absolute)) {
+  const absolute = path26.resolve(root, ...file.path.split("/"));
+  if (!existsSync20(absolute)) {
     return { path: file.path, expectedSha256: file.sha256, actualSha256: null, status: "missing" };
   }
   const actualSha256 = await sha256File(absolute);
@@ -12120,7 +12511,7 @@ async function verifyRecipe(target, options = {}) {
   const loaded = await resolveRecipe(target, options.bundledRoot);
   const actualIntegrity = recipeDigest(loaded.recipe);
   const files = await Promise.all(loaded.recipe.files.map((file) => verifyFile(loaded.dir, file)));
-  const modelRoot = options.modelRoot ? path24.resolve(options.modelRoot) : null;
+  const modelRoot = options.modelRoot ? path26.resolve(options.modelRoot) : null;
   const models = modelRoot ? await Promise.all(loaded.recipe.models.map(async (model) => ({
     ...await verifyFile(modelRoot, model),
     source: model.source,
@@ -12154,7 +12545,7 @@ async function verifyRecipe(target, options = {}) {
   };
 }
 function renderStyle(style, destination, cwd) {
-  const portableDir = path24.relative(cwd, destination).split(path24.sep).join("/") || ".";
+  const portableDir = path26.relative(cwd, destination).split(path26.sep).join("/") || ".";
   const replace = (value) => {
     if (typeof value === "string") return value.replaceAll(RECIPE_DIR_TOKEN, portableDir);
     if (Array.isArray(value)) return value.map(replace);
@@ -12166,24 +12557,24 @@ function renderStyle(style, destination, cwd) {
   return replace(style);
 }
 async function installRecipe(target, options = {}) {
-  const cwd = path24.resolve(options.cwd ?? process.cwd());
+  const cwd = path26.resolve(options.cwd ?? process.cwd());
   const loaded = await resolveRecipe(target, options.bundledRoot);
   const verification = await verifyRecipe(loaded.path);
   if (!verification.ok) {
     throw new Error(`Recipe ${loaded.recipe.id}@${loaded.recipe.version} failed integrity verification.`);
   }
-  const destination = options.out ? path24.resolve(cwd, options.out) : path24.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
+  const destination = options.out ? path26.resolve(cwd, options.out) : path26.join(cwd, "pixelkiln-recipes", ...loaded.recipe.id.split("/"), loaded.recipe.version);
   const sources = [
     { path: RECIPE_FILE, source: loaded.path },
-    ...loaded.recipe.files.map((file) => ({ path: file.path, source: path24.join(loaded.dir, ...file.path.split("/")) }))
+    ...loaded.recipe.files.map((file) => ({ path: file.path, source: path26.join(loaded.dir, ...file.path.split("/")) }))
   ];
   const files = await Promise.all(sources.map(async (file) => ({
-    path: path24.join(destination, ...file.path.split("/")),
+    path: path26.join(destination, ...file.path.split("/")),
     data: await readFile20(file.source)
   })));
   if (!options.force) {
     for (const file of files) {
-      if (!existsSync19(file.path)) continue;
+      if (!existsSync20(file.path)) continue;
       const current = await readFile20(file.path);
       if (!current.equals(file.data)) {
         throw new Error(
@@ -12207,15 +12598,15 @@ async function installRecipe(target, options = {}) {
 }
 
 // src/pipeline/quality-regression.ts
-import path25 from "path";
-import { existsSync as existsSync20 } from "fs";
+import path27 from "path";
+import { existsSync as existsSync21 } from "fs";
 import { readFile as readFile21 } from "fs/promises";
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var SHA256_RE2 = /^[0-9a-f]{64}$/;
 var HEX_RE = /^#[0-9a-f]{6}$/;
 var MAX_REDMEAN_DISTANCE = 765;
-var QualityPathSchema = z8.string().min(1).refine(
-  (value) => !path25.posix.isAbsolute(value) && !value.includes("\\"),
+var QualityPathSchema = z9.string().min(1).refine(
+  (value) => !path27.posix.isAbsolute(value) && !value.includes("\\"),
   "expected a portable relative path"
 );
 var DEFAULT_QUALITY_TOLERANCES = {
@@ -12228,53 +12619,53 @@ var DEFAULT_QUALITY_TOLERANCES = {
   maxEdgeContrastDrop: 0.03,
   maxIsolatedPixelIncrease: 5e-3
 };
-var QualityToleranceSchema = z8.object({
-  requireExactHash: z8.boolean(),
-  maxColorCountIncrease: z8.number().int().min(0),
-  maxNewColors: z8.number().int().min(0),
-  maxTransparencyDelta: z8.number().min(0).max(1),
-  maxPartialAlphaIncrease: z8.number().min(0).max(1),
-  maxEdgeDensityDelta: z8.number().min(0).max(1),
-  maxEdgeContrastDrop: z8.number().min(0).max(1),
-  maxIsolatedPixelIncrease: z8.number().min(0).max(1)
+var QualityToleranceSchema = z9.object({
+  requireExactHash: z9.boolean(),
+  maxColorCountIncrease: z9.number().int().min(0),
+  maxNewColors: z9.number().int().min(0),
+  maxTransparencyDelta: z9.number().min(0).max(1),
+  maxPartialAlphaIncrease: z9.number().min(0).max(1),
+  maxEdgeDensityDelta: z9.number().min(0).max(1),
+  maxEdgeContrastDrop: z9.number().min(0).max(1),
+  maxIsolatedPixelIncrease: z9.number().min(0).max(1)
 }).strict();
-var ImageQualityMetricsSchema = z8.object({
-  sha256: z8.string().regex(SHA256_RE2),
-  width: z8.number().int().min(1),
-  height: z8.number().int().min(1),
-  colorCount: z8.number().int().min(0),
-  colors: z8.array(z8.string().regex(HEX_RE)),
-  transparency: z8.number().min(0).max(1),
-  partialAlpha: z8.number().min(0).max(1),
-  edgeDensity: z8.number().min(0).max(1),
-  meanEdgeContrast: z8.number().min(0).max(1),
-  isolatedPixelRatio: z8.number().min(0).max(1)
+var ImageQualityMetricsSchema = z9.object({
+  sha256: z9.string().regex(SHA256_RE2),
+  width: z9.number().int().min(1),
+  height: z9.number().int().min(1),
+  colorCount: z9.number().int().min(0),
+  colors: z9.array(z9.string().regex(HEX_RE)),
+  transparency: z9.number().min(0).max(1),
+  partialAlpha: z9.number().min(0).max(1),
+  edgeDensity: z9.number().min(0).max(1),
+  meanEdgeContrast: z9.number().min(0).max(1),
+  isolatedPixelRatio: z9.number().min(0).max(1)
 }).strict();
-var QualityBaselineCaseSchema = z8.object({
-  id: z8.string().regex(/^[a-z0-9][a-z0-9/_-]*$/),
+var QualityBaselineCaseSchema = z9.object({
+  id: z9.string().regex(/^[a-z0-9][a-z0-9/_-]*$/),
   file: QualityPathSchema,
-  record: z8.object({
+  record: z9.object({
     path: QualityPathSchema,
-    sha256: z8.string().regex(SHA256_RE2)
+    sha256: z9.string().regex(SHA256_RE2)
   }).strict().optional(),
   expected: ImageQualityMetricsSchema,
   tolerances: QualityToleranceSchema
 }).strict();
-var QualityBaselineSchema = z8.object({
-  $schema: z8.string().url().optional(),
-  format: z8.literal("pixelkiln-quality-baseline"),
-  schemaVersion: z8.literal(1),
-  cases: z8.array(QualityBaselineCaseSchema).min(1)
+var QualityBaselineSchema = z9.object({
+  $schema: z9.string().url().optional(),
+  format: z9.literal("pixelkiln-quality-baseline"),
+  schemaVersion: z9.literal(1),
+  cases: z9.array(QualityBaselineCaseSchema).min(1)
 }).strict().superRefine((baseline, context) => {
   const ids = baseline.cases.map((entry) => entry.id);
   if (new Set(ids).size !== ids.length) {
-    context.addIssue({ code: z8.ZodIssueCode.custom, path: ["cases"], message: "duplicate case id" });
+    context.addIssue({ code: z9.ZodIssueCode.custom, path: ["cases"], message: "duplicate case id" });
   }
 });
-var QualityInputSchema = z8.object({
-  id: z8.string().regex(/^[a-z0-9][a-z0-9/_-]*$/),
-  path: z8.string().min(1),
-  record: z8.string().min(1).optional(),
+var QualityInputSchema = z9.object({
+  id: z9.string().regex(/^[a-z0-9][a-z0-9/_-]*$/),
+  path: z9.string().min(1),
+  record: z9.string().min(1).optional(),
   tolerances: QualityToleranceSchema.partial().optional()
 }).strict();
 function message5(error) {
@@ -12362,7 +12753,7 @@ function measureDecodedImageQuality(png, digest2) {
   };
 }
 async function measureImageQuality(file) {
-  const absolute = path25.resolve(file);
+  const absolute = path27.resolve(file);
   let bytes;
   try {
     bytes = await readFile21(absolute);
@@ -12376,7 +12767,7 @@ async function measureImageQuality(file) {
   }
 }
 function resolveQualityInputs(raw, inputsFilePath) {
-  const parsed = z8.array(QualityInputSchema).min(1).safeParse(raw);
+  const parsed = z9.array(QualityInputSchema).min(1).safeParse(raw);
   if (!parsed.success) {
     throw new Error(
       "--inputs must be a non-empty JSON array of quality cases:\n" + parsed.error.issues.map((issue) => `  ${issue.path.join(".") || "$"}: ${issue.message}`).join("\n")
@@ -12384,11 +12775,11 @@ function resolveQualityInputs(raw, inputsFilePath) {
   }
   const ids = parsed.data.map((entry) => entry.id);
   if (new Set(ids).size !== ids.length) throw new Error("--inputs contains a duplicate quality case id.");
-  const root = path25.dirname(path25.resolve(inputsFilePath));
+  const root = path27.dirname(path27.resolve(inputsFilePath));
   return parsed.data.map((entry) => ({
     id: entry.id,
-    file: path25.resolve(root, entry.path),
-    ...entry.record ? { record: path25.resolve(root, entry.record) } : {},
+    file: path27.resolve(root, entry.path),
+    ...entry.record ? { record: path27.resolve(root, entry.record) } : {},
     tolerances: QualityToleranceSchema.parse({
       ...DEFAULT_QUALITY_TOLERANCES,
       ...entry.tolerances
@@ -12396,7 +12787,7 @@ function resolveQualityInputs(raw, inputsFilePath) {
   }));
 }
 function portableRelative2(from, to) {
-  return path25.relative(from, path25.resolve(to)).split(path25.sep).join("/") || ".";
+  return path27.relative(from, path27.resolve(to)).split(path27.sep).join("/") || ".";
 }
 async function verifyRecordForImage(recordPath, imagePath) {
   const verification = await verifyArtifactBundle(recordPath);
@@ -12411,20 +12802,20 @@ async function verifyRecordForImage(recordPath, imagePath) {
   if (record.kind !== "refine" || options === null || typeof options !== "object" || options.schema !== "pixelkiln-quality") {
     throw new Error(`Quality record ${recordPath} is not a PixelKiln refinement record.`);
   }
-  const outputs = record.outputs.map((output) => path25.resolve(path25.dirname(recordPath), output.path));
-  if (!outputs.includes(path25.resolve(imagePath))) {
+  const outputs = record.outputs.map((output) => path27.resolve(path27.dirname(recordPath), output.path));
+  if (!outputs.includes(path27.resolve(imagePath))) {
     throw new Error(`Quality record ${recordPath} does not own ${imagePath}.`);
   }
 }
 async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   if (!inputs.length) throw new Error("Cannot snapshot an empty quality baseline.");
-  const absolute = path25.resolve(baselinePath);
+  const absolute = path27.resolve(baselinePath);
   for (const input of inputs) {
-    if (path25.resolve(input.file) === absolute || input.record && path25.resolve(input.record) === absolute) {
+    if (path27.resolve(input.file) === absolute || input.record && path27.resolve(input.record) === absolute) {
       throw new Error(`Quality baseline output would overwrite an input: ${absolute}.`);
     }
   }
-  const root = path25.dirname(absolute);
+  const root = path27.dirname(absolute);
   const cases = [];
   for (const input of [...inputs].sort((a, b) => a.id.localeCompare(b.id))) {
     const expected = await measureImageQuality(input.file);
@@ -12451,7 +12842,7 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
     cases
   });
   const data = Buffer.from(JSON.stringify(baseline, null, 2) + "\n");
-  if (existsSync20(absolute) && !options.force) {
+  if (existsSync21(absolute) && !options.force) {
     const current = await readFile21(absolute);
     if (!current.equals(data)) {
       throw new Error(`Quality baseline already exists with different content: ${absolute}. Pass --force to replace it.`);
@@ -12461,7 +12852,7 @@ async function snapshotQualityBaseline(inputs, baselinePath, options = {}) {
   return { baseline, path: absolute, changed: result.changed.length > 0 };
 }
 async function readQualityBaseline(baselinePath) {
-  const absolute = path25.resolve(baselinePath);
+  const absolute = path27.resolve(baselinePath);
   let raw;
   try {
     raw = JSON.parse(await readFile21(absolute, "utf8"));
@@ -12534,12 +12925,12 @@ function regressionViolations(expected, actual, tolerances) {
   return { violations, warnings };
 }
 async function checkQualityBaseline(baselinePath) {
-  const absolute = path25.resolve(baselinePath);
+  const absolute = path27.resolve(baselinePath);
   const baseline = await readQualityBaseline(absolute);
-  const root = path25.dirname(absolute);
+  const root = path27.dirname(absolute);
   const cases = [];
   for (const entry of baseline.cases) {
-    const file = path25.resolve(root, entry.file);
+    const file = path27.resolve(root, entry.file);
     let actual = null;
     const violations = [];
     const warnings = [];
@@ -12552,7 +12943,7 @@ async function checkQualityBaseline(baselinePath) {
       violations.push(message5(error));
     }
     if (entry.record) {
-      const recordPath = path25.resolve(root, entry.record.path);
+      const recordPath = path27.resolve(root, entry.record.path);
       try {
         const recordHash = await sha256File(recordPath);
         if (recordHash !== entry.record.sha256) violations.push("quality record hash changed");
@@ -12638,13 +13029,13 @@ async function runGallery(initial, reload, args, access2) {
   };
   const loadProject = async (project) => {
     const ctx = await access2.loadProject(project);
-    const dir = path26.dirname(ctx.loaded.path);
+    const dir = path28.dirname(ctx.loaded.path);
     const declared = readEnvFiles(dir);
     const credentialNames = new Set(availableProviders().flatMap((id) => providerCredentialEnvs(providerFactory(id))));
     for (const [name, value] of Object.entries(declared)) {
       if (credentialNames.has(name) && name in process.env && process.env[name] !== value) {
         throw new Error(
-          `${path26.relative(process.cwd(), dir) || "."} sets ${name} to a different value than the one this gallery already loaded; run a separate gallery for that project so its work uses its own account.`
+          `${path28.relative(process.cwd(), dir) || "."} sets ${name} to a different value than the one this gallery already loaded; run a separate gallery for that project so its work uses its own account.`
         );
       }
     }
@@ -12670,7 +13061,7 @@ async function runGallery(initial, reload, args, access2) {
       args.edit,
       budget ? describeBudget(budget) : null
     ),
-    ...args.edit ? { edit: createGalleryEditHandler({ manifestFor: access2.manifestFor, reload, onProgress: log }) } : {},
+    ...args.edit ? { edit: createGalleryEditHandler({ manifestFor: access2.manifestFor, loadProject: access2.loadProject, reload, onProgress: log }) } : {},
     ...budget ? { generate: createGenerateHandlers({ loadProject, providerFor, budget, reload, onProgress: log }) } : {}
   });
   await new Promise((resolve) => {
@@ -12686,11 +13077,11 @@ async function runGallery(initial, reload, args, access2) {
   log("\n  gallery closed");
 }
 async function provenanceFile(id, file) {
-  const absolute = path26.resolve(file);
+  const absolute = path28.resolve(file);
   return {
     id,
     path: absolute,
-    sha256: existsSync21(absolute) ? await sha256File(absolute) : null,
+    sha256: existsSync22(absolute) ? await sha256File(absolute) : null,
     included: true
   };
 }
@@ -12739,7 +13130,8 @@ var BOOL_FLAGS = [
   "--write-prompts",
   "--primary-only",
   "--prune",
-  "--edit"
+  "--edit",
+  "--refresh"
 ];
 var COMMANDS = [
   "init",
@@ -12765,6 +13157,7 @@ var COMMANDS = [
   "balance",
   "status",
   "gallery",
+  "edit",
   "quality",
   "refine",
   "recipe",
@@ -12779,6 +13172,7 @@ var WORKSPACE_SUBCOMMANDS = ["add", "remove", "list", "status", "claims"];
 var REFINE_SUBCOMMANDS = ["run", "approve", "check"];
 var RECIPE_SUBCOMMANDS = ["list", "inspect", "install", "verify"];
 var QUALITY_SUBCOMMANDS = ["snapshot", "check"];
+var EDIT_SUBCOMMANDS = ["start", "detach"];
 function parseArgs(argv) {
   const [command = "help"] = argv;
   if (!COMMANDS.includes(command)) {
@@ -12836,6 +13230,12 @@ function parseArgs(argv) {
       }
       rest = rest.slice(1);
     }
+  } else if (command === "edit") {
+    subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "start" : rest[0];
+    if (!EDIT_SUBCOMMANDS.includes(subcommand)) {
+      throw new Error(`Unknown edit subcommand "${subcommand}". Known: ${EDIT_SUBCOMMANDS.join(", ")}`);
+    }
+    if (rest[0] === subcommand) rest = rest.slice(1);
   } else if (command === "refine") {
     subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "run" : rest[0];
     if (!REFINE_SUBCOMMANDS.includes(subcommand)) {
@@ -12949,7 +13349,7 @@ function parseArgs(argv) {
   return {
     command,
     manifest,
-    lock: get("--lock") ?? path26.join(path26.dirname(path26.resolve(manifest)), "pixelkiln.lock.json"),
+    lock: get("--lock") ?? path28.join(path28.dirname(path28.resolve(manifest)), "pixelkiln.lock.json"),
     explicitLock: get("--lock"),
     styles: list("--style"),
     assets: list("--only"),
@@ -12964,6 +13364,7 @@ function parseArgs(argv) {
     noOpen: rest.includes("--no-open"),
     tag: rest.includes("--tag"),
     edit: rest.includes("--edit"),
+    refresh: rest.includes("--refresh"),
     from: get("--from"),
     out: get("--out"),
     generator: get("--generator"),
@@ -13030,6 +13431,9 @@ Commands
   tag       Push manifest tags to the objects upstream (free).
   balance   Show the provider's remaining balance.
   status    Summarise the lockfile.
+  edit      Hand-edit an asset in your own editor: copies the generated PNG to
+            <outDir>/edits/, declares it as the asset's source, and opens it.
+            edit detach places the generated art again (the file is kept).
   gallery   Open a local read-only gallery of every generation and its
             provenance: prompt, provider, cost, outputs, lineage, quality.
             --workspace <catalog> shows every registered project at once;
@@ -13072,9 +13476,11 @@ Options
                       and the gallery snapshot (no server)
   --check             plan/audit/cache: exit nonzero when the selected state is unsafe
   --yes, -y           Skip the confirmation prompt
-  --no-open           Do not auto-open the browser during pick, salvage, or gallery
+  --no-open           Do not auto-open the browser (pick, salvage, gallery) or editor (edit)
   --edit              gallery: allow manifest edits from the page (never spends)
   --tag               Also push tags upstream after fetch
+  --refresh           fetch: re-download and replace files whose object changed
+                      upstream (e.g. edited in PixelLab's editor); no generation
   --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,
@@ -13089,6 +13495,8 @@ Examples
   pixelkiln gallery --style heybud-premium
   pixelkiln gallery --workspace pixelkiln.workspace.json
   pixelkiln gallery --edit --budget 80
+  pixelkiln edit --style base --only anvil
+  PIXELKILN_EDITOR="open -a Aseprite" pixelkiln edit --only anvil --style base
   pixelkiln adopt --tag
   pixelkiln pack --style heybud-premium
   pixelkiln pack --inputs sprites.json --out dist/sheet   # no manifest needed
@@ -13165,6 +13573,15 @@ function printResumeActions(specs, lock) {
   }
   return actions.length;
 }
+function manifestSources(manifest, styleId) {
+  const sources = {};
+  for (const [assetId, asset] of Object.entries(manifest.assets)) {
+    if (asset.styles.length && !asset.styles.includes(styleId)) continue;
+    const source = asset.sourceByStyle[styleId] ?? asset.source;
+    if (source) sources[assetId] = source;
+  }
+  return sources;
+}
 function manifestProviderIds(manifest) {
   return [...new Set(
     Object.values(manifest.styles).map((style) => style.provider ?? manifest.provider)
@@ -13238,10 +13655,10 @@ async function confirm(question, auto) {
   return answer === "y" || answer === "yes";
 }
 async function requireCompleteWorkspaceClaims(workspacePath) {
-  if (!existsSync21(workspacePath)) {
+  if (!existsSync22(workspacePath)) {
     throw new Error(`Workspace catalog not found: ${workspacePath}`);
   }
-  const dir = path26.dirname(path26.resolve(workspacePath));
+  const dir = path28.dirname(path28.resolve(workspacePath));
   const ws = await loadWorkspace(workspacePath);
   const diagnostics = validateWorkspace(ws, dir);
   const errors = diagnostics.filter((d) => d.level === "error");
@@ -13273,15 +13690,15 @@ async function main() {
       if (!args.out) throw new Error("quality snapshot needs --out <pixelkiln.quality.json>.");
       let raw;
       try {
-        raw = JSON.parse(await readFile22(path26.resolve(args.inputs), "utf8"));
+        raw = JSON.parse(await readFile22(path28.resolve(args.inputs), "utf8"));
       } catch (error) {
         throw new Error(
-          `Could not read quality inputs ${path26.resolve(args.inputs)}: ${error instanceof Error ? error.message : String(error)}`,
+          `Could not read quality inputs ${path28.resolve(args.inputs)}: ${error instanceof Error ? error.message : String(error)}`,
           { cause: error }
         );
       }
       const inputs = resolveQualityInputs(raw, args.inputs);
-      if (path26.resolve(args.inputs) === path26.resolve(args.out)) {
+      if (path28.resolve(args.inputs) === path28.resolve(args.out)) {
         throw new Error("quality snapshot --out must not overwrite its --inputs file.");
       }
       const result = await snapshotQualityBaseline(inputs, args.out, { force: args.force });
@@ -13294,7 +13711,7 @@ async function main() {
         }, null, 2));
       } else {
         log(
-          `  ${result.changed ? "wrote" : "unchanged"} ${path26.relative(process.cwd(), result.path)} (${result.baseline.cases.length} case(s))`
+          `  ${result.changed ? "wrote" : "unchanged"} ${path28.relative(process.cwd(), result.path)} (${result.baseline.cases.length} case(s))`
         );
         log(`  Review the tolerances, commit the baseline, then run quality check in CI.`);
       }
@@ -13389,14 +13806,14 @@ async function main() {
         }, null, 2));
       } else {
         log(`  installed ${result.recipe.id}@${result.recipe.version}`);
-        log(`  ${path26.relative(process.cwd(), result.destination) || "."}`);
+        log(`  ${path28.relative(process.cwd(), result.destination) || "."}`);
         log(`
   Add this entry under your manifest's styles object:`);
         log(JSON.stringify({ [result.styleId]: result.style }, null, 2));
         if (result.recipe.models.length) {
           log(`
   Models are not downloaded automatically. Verify them with:`);
-          log(`  pixelkiln recipe verify ${path26.relative(process.cwd(), result.destination)} --model-root <ComfyUI/models>`);
+          log(`  pixelkiln recipe verify ${path28.relative(process.cwd(), result.destination)} --model-root <ComfyUI/models>`);
         }
       }
       return;
@@ -13430,12 +13847,12 @@ async function main() {
           `  recovered ${result2.detection.columns}x${result2.detection.rows} native grid (${result2.detection.confidence}: ${result2.detection.consensus})`
         );
         log(`  enforced ${result2.palette.length}-color palette without dithering`);
-        log(`  wrote ${path26.relative(process.cwd(), result2.output)}`);
-        log(`  quality record: ${path26.relative(process.cwd(), result2.record)}`);
+        log(`  wrote ${path28.relative(process.cwd(), result2.output)}`);
+        log(`  quality record: ${path28.relative(process.cwd(), result2.record)}`);
         log(`
   Automated checks passed. Human 1\xD7 review is still required:`);
         log(
-          `    pixelkiln refine approve --from ${path26.relative(process.cwd(), result2.record)} --reviewer "Your Name"`
+          `    pixelkiln refine approve --from ${path28.relative(process.cwd(), result2.record)} --reviewer "Your Name"`
         );
       }
       return;
@@ -13463,7 +13880,7 @@ async function main() {
       if (args.json) log(JSON.stringify(result2, null, 2));
       else {
         log(
-          result2.options.frameSet ? `  approved ${result2.outputs.length} frames in ${path26.relative(process.cwd(), result2.record)} by ${args.reviewer.trim()}` : `  approved ${path26.relative(process.cwd(), result2.output)} by ${args.reviewer.trim()}`
+          result2.options.frameSet ? `  approved ${result2.outputs.length} frames in ${path28.relative(process.cwd(), result2.record)} by ${args.reviewer.trim()}` : `  approved ${path28.relative(process.cwd(), result2.output)} by ${args.reviewer.trim()}`
         );
       }
       return;
@@ -13472,14 +13889,14 @@ async function main() {
     if (args.json) {
       log(JSON.stringify(result, null, 2));
     } else {
-      log(`  ${result.safe ? "release-ready" : "not release-ready"}: ${path26.relative(process.cwd(), result.output || result.record)}`);
+      log(`  ${result.safe ? "release-ready" : "not release-ready"}: ${path28.relative(process.cwd(), result.output || result.record)}`);
       for (const reason of result.reasons) log(`    ${reason}`);
     }
     if (!result.safe) process.exitCode = 1;
     return;
   }
   if (args.command === "balance") {
-    loadEnvFiles(path26.dirname(path26.resolve(args.manifest)));
+    loadEnvFiles(path28.dirname(path28.resolve(args.manifest)));
     loadEnvFiles(process.cwd());
     const loaded2 = await loadManifest(args.manifest);
     const selectedProvider = accountProviderId(loaded2.manifest, args.provider, "balance");
@@ -13492,31 +13909,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 = path26.resolve(args.from);
-    if (!existsSync21(root)) throw new Error(`No directory at ${root}`);
+    const root = path28.resolve(args.from);
+    if (!existsSync22(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 = path26.resolve(args.out ?? "pixelkiln.manifest.json");
+    const target = path28.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 ?? path26.basename(path26.dirname(target)),
+      args.name ?? path28.basename(path28.dirname(target)),
       args.styles[0] ?? "base",
       generator,
-      path26.relative(path26.dirname(target), root) || ".",
+      path28.relative(path28.dirname(target), root) || ".",
       assets
     );
     await writeManifestFile(target, manifest);
-    log(`  scanned ${assets.length} PNG(s) under ${path26.relative(process.cwd(), root)}`);
+    log(`  scanned ${assets.length} PNG(s) under ${path28.relative(process.cwd(), root)}`);
     if (skipped.length) log(`  skipped ${skipped.length} unreadable file(s)`);
-    log(`  wrote ${path26.relative(process.cwd(), target)}`);
+    log(`  wrote ${path28.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 ${path26.relative(process.cwd(), target)} --write-prompts
+    pixelkiln adopt --manifest ${path28.relative(process.cwd(), target)} --write-prompts
 `);
     return;
   }
@@ -13564,10 +13981,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 readFile22(path26.resolve(args.inputs), "utf8"));
+    const raw = JSON.parse(await readFile22(path28.resolve(args.inputs), "utf8"));
     const inputs = resolvePackInputs(raw, args.inputs);
     const { png, atlas, skipped, sources } = packSprites(inputs, { columns: args.columns });
-    const base = path26.resolve(args.out.replace(/\.png$/, ""));
+    const base = path28.resolve(args.out.replace(/\.png$/, ""));
     const outputs = [
       { path: `${base}.png`, data: png },
       { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
@@ -13580,17 +13997,17 @@ 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(`    ${path26.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+    log(`    ${path28.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     return;
   }
   if (args.command === "workspace") {
-    const workspacePath = path26.resolve(args.workspace ?? "pixelkiln.workspace.json");
-    const dir = path26.dirname(workspacePath);
+    const workspacePath = path28.resolve(args.workspace ?? "pixelkiln.workspace.json");
+    const dir = path28.dirname(workspacePath);
     if (args.subcommand === "add") {
-      const manifestPath = path26.resolve(args.target);
+      const manifestPath = path28.resolve(args.target);
       const loadedTarget = await loadManifest(manifestPath);
-      const lockPath = args.explicitLock ? path26.resolve(args.explicitLock) : path26.join(path26.dirname(manifestPath), "pixelkiln.lock.json");
+      const lockPath = args.explicitLock ? path28.resolve(args.explicitLock) : path28.join(path28.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)) {
@@ -13610,10 +14027,10 @@ async function main() {
         ...args.account ? { account: args.account } : {}
       };
       await saveWorkspace(workspacePath, { version: 1, projects: [...ws.projects, project] });
-      log(`  registered "${id}" in ${path26.relative(process.cwd(), workspacePath)}`);
+      log(`  registered "${id}" in ${path28.relative(process.cwd(), workspacePath)}`);
       log(`    manifest: ${project.manifest}`);
       log(`    lock:     ${project.lock}`);
-      if (!existsSync21(lockPath)) {
+      if (!existsSync22(lockPath)) {
         log(
           `  warning: no lockfile there yet \u2014 this project contributes no claims until one is generated`
         );
@@ -13622,7 +14039,7 @@ async function main() {
     }
     if (args.subcommand === "remove") {
       const ws = await loadWorkspace(workspacePath);
-      const resolvedTarget = path26.resolve(args.target);
+      const resolvedTarget = path28.resolve(args.target);
       const match = ws.projects.find(
         (p) => p.id === args.target || resolveProject(dir, p).manifestPath === resolvedTarget
       );
@@ -13633,11 +14050,11 @@ async function main() {
         version: 1,
         projects: ws.projects.filter((p) => p !== match)
       });
-      log(`  removed "${match.id}" from ${path26.relative(process.cwd(), workspacePath)}`);
+      log(`  removed "${match.id}" from ${path28.relative(process.cwd(), workspacePath)}`);
       return;
     }
     if (args.subcommand === "list") {
-      if (!existsSync21(workspacePath)) {
+      if (!existsSync22(workspacePath)) {
         throw new Error(`Workspace catalog not found: ${workspacePath}`);
       }
       const ws = await loadWorkspace(workspacePath);
@@ -13645,9 +14062,9 @@ async function main() {
       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 ${path26.relative(process.cwd(), workspacePath)}`);
+        log(`  no projects registered in ${path28.relative(process.cwd(), workspacePath)}`);
       } else {
-        log(`  ${ws.projects.length} project(s) in ${path26.relative(process.cwd(), workspacePath)}:`);
+        log(`  ${ws.projects.length} project(s) in ${path28.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}` : ""})`);
         }
@@ -13657,7 +14074,7 @@ async function main() {
       return;
     }
     if (args.subcommand === "status") {
-      if (!existsSync21(workspacePath)) {
+      if (!existsSync22(workspacePath)) {
         throw new Error(`Workspace catalog not found: ${workspacePath}`);
       }
       const ws = await loadWorkspace(workspacePath);
@@ -13665,7 +14082,7 @@ async function main() {
       if (args.json) {
         log(JSON.stringify({ ...report, workspace: workspacePath }, null, 2));
       } else {
-        log(`  workspace: ${path26.relative(process.cwd(), workspacePath)}`);
+        log(`  workspace: ${path28.relative(process.cwd(), workspacePath)}`);
         for (const p of report.projects) {
           if (p.error) {
             log(`
@@ -13712,8 +14129,8 @@ async function main() {
     }
   }
   if (args.command === "gallery" && args.workspace) {
-    const workspacePath = path26.resolve(args.workspace);
-    if (!existsSync21(workspacePath)) {
+    const workspacePath = path28.resolve(args.workspace);
+    if (!existsSync22(workspacePath)) {
       throw new Error(`Workspace catalog not found: ${workspacePath}`);
     }
     const filter = { styles: args.styles, assets: args.assets };
@@ -13733,7 +14150,7 @@ async function main() {
     const registered = async (projectId) => {
       const project = (await loadWorkspace(workspacePath)).projects.find((candidate) => candidate.id === projectId);
       if (!projectId || !project) throw new Error(`unknown workspace project "${projectId ?? ""}"`);
-      return resolveProject(path26.dirname(workspacePath), project);
+      return resolveProject(path28.dirname(workspacePath), project);
     };
     await runGallery(initial, build, args, {
       manifestFor: async (projectId) => (await registered(projectId)).manifestPath,
@@ -13748,14 +14165,14 @@ async function main() {
     });
     return;
   }
-  if (!existsSync21(path26.resolve(args.manifest))) {
+  if (!existsSync22(path28.resolve(args.manifest))) {
     throw new Error(
-      `No manifest at ${path26.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
+      `No manifest at ${path28.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
     );
   }
-  const manifestDir = path26.dirname(path26.resolve(args.manifest));
+  const manifestDir = path28.dirname(path28.resolve(args.manifest));
   const envFiles2 = [...loadEnvFiles(manifestDir)];
-  if (path26.resolve(process.cwd()) !== manifestDir) envFiles2.push(...loadEnvFiles(process.cwd()));
+  if (path28.resolve(process.cwd()) !== manifestDir) envFiles2.push(...loadEnvFiles(process.cwd()));
   const loaded = await loadManifest(args.manifest);
   let specs = await resolveSpecs(loaded, {
     styles: args.styles,
@@ -13828,7 +14245,7 @@ async function main() {
       });
     };
     await runGallery(await build(), reload, args, {
-      manifestFor: () => path26.resolve(args.manifest),
+      manifestFor: () => path28.resolve(args.manifest),
       loadProject: async () => {
         const freshLoaded = await loadManifest(args.manifest);
         const freshSpecs = await resolveSpecs(freshLoaded);
@@ -13839,6 +14256,29 @@ async function main() {
     });
     return;
   }
+  if (args.command === "edit") {
+    if (!args.assets.length) throw new Error("edit needs --only <asset id> (and --style when the asset is in several styles).");
+    if (specs.length !== 1) {
+      throw new Error(
+        specs.length ? `edit works on one asset in one style; --only ${args.assets.join(",")} resolves to ${specs.length}: ` + specs.map((spec2) => `${spec2.styleId}/${spec2.assetId}`).join(", ") + ". Add --style." : "edit matched no asset."
+      );
+    }
+    const spec = specs[0];
+    if (args.subcommand === "detach") {
+      const result = await detachHandEdit(loaded, spec);
+      log(result.changed ? `  detached the hand edit for ${spec.styleId}/${spec.assetId}; the generated art is placed again (the edit file is kept)` : `  ${spec.styleId}/${spec.assetId} has no hand edit`);
+      return;
+    }
+    const started = await startHandEdit(loaded, lock, spec);
+    log(`  ${started.created ? "created" : "found"} ${started.source}${started.declared ? " and declared it as the asset's source" : ""}`);
+    if (args.noOpen) {
+      log(`  edit it with your own tool, then run pixelkiln plan; mount and pack place it in place of the generated art`);
+    } else {
+      const command = openInEditor(started.editPath);
+      log(`  opened with: ${command}${process.env.PIXELKILN_EDITOR ? "" : " (set PIXELKILN_EDITOR to choose the program)"}`);
+    }
+    return;
+  }
   const plan = await buildPlan(specs, lock, { force: args.force });
   if (args.command === "refine") {
     const pathOwnedFlags = [
@@ -13880,7 +14320,7 @@ async function main() {
         log(`  ${item.state.padEnd(16)} ${item.key}  ${item.reason}`);
         if (item.state === "needs-approval") {
           log(
-            `    pixelkiln refine approve --from ${path26.relative(process.cwd(), item.record)} --reviewer "Your Name"`
+            `    pixelkiln refine approve --from ${path28.relative(process.cwd(), item.record)} --reviewer "Your Name"`
           );
         }
       }
@@ -13971,7 +14411,7 @@ async function main() {
       let intact = true;
       for (const output of entry.outputs) {
         const file = resolveOutputPath(output.path, item.spec.root);
-        if (!existsSync21(file) || await sha256File(file) !== output.sha256) {
+        if (!existsSync22(file) || await sha256File(file) !== output.sha256) {
           intact = false;
           break;
         }
@@ -14029,7 +14469,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 = path26.dirname(path26.resolve(args.manifest));
+    const manifestDir2 = path28.dirname(path28.resolve(args.manifest));
     const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
     for (const styleId of styleIds) {
       const packagingSpecs = await resolveSpecs(loaded, { styles: [styleId] });
@@ -14038,10 +14478,11 @@ async function main() {
         columns: args.columns,
         outputRoles: args.outputRoles,
         primaryOnly: args.primaryOnly,
-        sourceOverrides: qualitySources
+        sourceOverrides: qualitySources,
+        sources: manifestSources(loaded.manifest, styleId)
       });
       const style = loaded.manifest.styles[styleId];
-      const base = args.out ? path26.resolve(args.out.replace(/\.png$/, "")) : path26.resolve(manifestDir2, style.outDir, `${styleId}-sheet`);
+      const base = args.out ? path28.resolve(args.out.replace(/\.png$/, "")) : path28.resolve(manifestDir2, style.outDir, `${styleId}-sheet`);
       const outputs = [
         { path: `${base}.png`, data: png },
         { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
@@ -14071,13 +14512,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(`    ${path26.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+      log(`    ${path28.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 = path26.dirname(path26.resolve(args.manifest));
+    const manifestDir2 = path28.dirname(path28.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];
@@ -14092,10 +14533,11 @@ async function main() {
       const cells = {};
       const sources = {};
       const outputRoles = {};
+      const styleSources = manifestSources(loaded.manifest, styleId);
       for (const [assetId, asset] of Object.entries(loaded.manifest.assets)) {
         if (!asset.cell) continue;
         cells[assetId] = asset.cell;
-        if (asset.source) sources[assetId] = asset.source;
+        if (styleSources[assetId]) sources[assetId] = styleSources[assetId];
         if (asset.outputRole) outputRoles[assetId] = asset.outputRole;
       }
       const packagingSpecs = await resolveSpecs(loaded, { styles: [styleId] });
@@ -14115,7 +14557,7 @@ async function main() {
         sources,
         outputRoles
       );
-      const out = path26.resolve(manifestDir2, style.mount.out);
+      const out = path28.resolve(manifestDir2, style.mount.out);
       const metadata = out.replace(/\.png$/, "") + ".json";
       const companion = out.replace(/\.png$/, "") + ".pixelkiln.json";
       const outputs = [
@@ -14135,7 +14577,7 @@ async function main() {
           await provenanceFile("$lock", args.lock),
           ...qualityRecords,
           ...artifactSources.filter(
-            (source) => source.id !== "$base" || path26.resolve(source.path) !== out
+            (source) => source.id !== "$base" || path28.resolve(source.path) !== out
           )
         ],
         options: {
@@ -14148,7 +14590,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(`    ${path26.relative(process.cwd(), out)} + atlas/provenance JSON`);
+      log(`    ${path28.relative(process.cwd(), out)} + atlas/provenance JSON`);
       for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     }
     return;
@@ -14204,7 +14646,7 @@ async function main() {
   }
   if (args.command === "export") {
     const format = args.format ?? "generic";
-    const manifestDir2 = path26.dirname(path26.resolve(args.manifest));
+    const manifestDir2 = path28.dirname(path28.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;
@@ -14220,12 +14662,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 = path26.resolve(manifestDir2, style.outDir, `${spec.assetId}-tileset`);
-      const base = args.out ? path26.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
+      const defaultBase = path28.resolve(manifestDir2, style.outDir, `${spec.assetId}-tileset`);
+      const base = args.out ? path28.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
       const result = exportTileset(entry, spec, {
         format,
         manifestDir: manifestDir2,
-        imageName: path26.basename(`${base}.png`),
+        imageName: path28.basename(`${base}.png`),
         columns: args.columns
       });
       const outputs = [
@@ -14243,7 +14685,7 @@ async function main() {
           asset: spec.assetId,
           columns: args.columns ?? null,
           format,
-          image: path26.basename(`${base}.png`),
+          image: path28.basename(`${base}.png`),
           providerRules: result.generic.providerRules,
           style: spec.styleId,
           tileType: spec.tileType ?? null
@@ -14253,7 +14695,7 @@ 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(
-        `    ${path26.relative(process.cwd(), base)}.png + ${path26.basename(base)}${result.extension} + .pixelkiln.json`
+        `    ${path28.relative(process.cwd(), base)}.png + ${path28.basename(base)}${result.extension} + .pixelkiln.json`
       );
     }
     return;
@@ -14303,12 +14745,12 @@ async function main() {
   tagged ${n} object(s) upstream`);
     }
     if (args.writePrompts) {
-      const { filled, stillEmpty } = await writePromptsBack(path26.resolve(args.manifest), lock, {
+      const { filled, stillEmpty } = await writePromptsBack(path28.resolve(args.manifest), lock, {
         onProgress: log,
         provider: provider.id,
         assetIds: specs.map((spec) => spec.assetId)
       });
-      log(`  recovered ${filled} prompt(s) into ${path26.relative(process.cwd(), args.manifest)}`);
+      log(`  recovered ${filled} prompt(s) into ${path28.relative(process.cwd(), args.manifest)}`);
       const reloaded = await loadManifest(args.manifest);
       const rebased = (await resolveSpecs(reloaded, {
         styles: args.styles,
@@ -14337,12 +14779,12 @@ async function main() {
     const provider = providerFor(selectedAccountProvider);
     const jsonMode = args.dryRun && args.json;
     const diag = jsonMode ? (msg = "") => console.error(msg) : log;
-    const ownLock = path26.resolve(args.lock);
+    const ownLock = path28.resolve(args.lock);
     let workspaceProjects = [];
     let workspaceDir = "";
     if (args.workspace) {
-      const workspacePath = path26.resolve(args.workspace);
-      workspaceDir = path26.dirname(workspacePath);
+      const workspacePath = path28.resolve(args.workspace);
+      workspaceDir = path28.dirname(workspacePath);
       const complete = await requireCompleteWorkspaceClaims(workspacePath);
       workspaceProjects = complete.ws.projects;
       for (const d of complete.diagnostics) diag(`  WARN  ${d.id}: ${d.message}`);
@@ -14351,12 +14793,12 @@ async function main() {
     const lockPaths = [
       .../* @__PURE__ */ new Set([
         ...workspaceLockPaths,
-        ...existsSync21(ownLock) ? [ownLock] : [],
-        ...args.claims.map((c) => path26.resolve(c))
+        ...existsSync22(ownLock) ? [ownLock] : [],
+        ...args.claims.map((c) => path28.resolve(c))
       ])
     ];
     diag(`  claim set (${lockPaths.length} lockfile(s)):`);
-    for (const p of lockPaths) diag(`    ${path26.relative(process.cwd(), p)}`);
+    for (const p of lockPaths) diag(`    ${path28.relative(process.cwd(), p)}`);
     if (!args.claims.length && !args.workspace) {
       diag(
         `
@@ -14364,7 +14806,7 @@ async function main() {
   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 === path26.resolve(args.manifest))) {
+    } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path28.resolve(args.manifest))) {
       diag(
         `
   This project's manifest is not registered in the workspace catalog. Its own
@@ -14448,7 +14890,7 @@ async function main() {
           manifestPath: loaded.path,
           manifest: accountManifest,
           styleId,
-          importDir: path26.resolve(loaded.root, style.outDir),
+          importDir: path28.resolve(loaded.root, style.outDir),
           lock,
           lockPath: args.lock
         },
@@ -14683,17 +15125,19 @@ async function main() {
   if (args.command === "fetch" || args.command === "restore" || args.command === "gen") {
     log(`
   downloading\u2026`);
-    const total = { downloaded: 0, skipped: 0, failed: 0, tagged: 0 };
+    const total = { downloaded: 0, skipped: 0, failed: 0, tagged: 0, unchanged: 0 };
     for (const [providerId, providerSpecsForRun] of specsByRecordedProvider(specs, lock)) {
       const groupProvider = providerFor(providerId);
       const res = await fetchAssets(groupProvider, providerSpecsForRun, lock, args.lock, {
         onProgress: log,
         repair: args.command === "restore",
-        force: args.force
+        force: args.force,
+        refresh: args.command === "fetch" && args.refresh
       });
       total.downloaded += res.downloaded;
       total.skipped += res.skipped;
       total.failed += res.failed;
+      total.unchanged += res.unchanged ?? 0;
       if (args.tag) {
         total.tagged += await pushTags(groupProvider, providerSpecsForRun, lock, {
           onProgress: log
@@ -14702,7 +15146,7 @@ async function main() {
     }
     log(
       `
-  downloaded ${total.downloaded}, skipped ${total.skipped}, failed ${total.failed}`
+  downloaded ${total.downloaded}, skipped ${total.skipped}, failed ${total.failed}` + (args.refresh ? `, unchanged upstream ${total.unchanged}` : "")
     );
     if (total.failed) process.exitCode = 1;
     if (args.tag) log(`  tagged ${total.tagged} object(s) upstream`);