@mcptoolshop/style-dataset-lab 3.3.0 → 3.4.0

package/scripts/generate-controlnet.js

@@ -14,12 +14,13 @@
 
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName, parseNumberFlag } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag, takeFlagValue } from "../lib/args.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { readJsonFile } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
+import { isResumable, logResumedSkip } from "./_resume.js";
 
 const DEFAULTS = {
   checkpoint: "dreamshaperXL_v21TurboDPMSDE.safetensors",
@@ -33,27 +34,32 @@ const DEFAULTS = {
   base_seed: 27100,
 };
 
+// H4: takeFlagValue() (lib/args.js) recognizes BOTH `--flag value` and
+// `--flag=value`. The prior `argv.indexOf(flag)`-based get() only matched a
+// token EXACTLY equal to e.g. "--weight" — false for the single token
+// "--weight=1.1" — so the equals form silently fell back to the default
+// with no error and no warning.
 function parseLocalArgs(argv) {
-  const get = (flag, def) => {
-    const i = argv.indexOf(flag);
-    if (i < 0 || i + 1 >= argv.length) return def;
-    const v = argv[i + 1];
-    if (typeof v === 'string' && v.startsWith('--')) {
-      throw inputError('INPUT_MISSING_VALUE', `Flag ${flag} is missing its value (got another flag: ${v}).`);
-    }
-    return v;
+  const get = (flagName, def) => {
+    const v = takeFlagValue(argv, flagName);
+    return v === undefined ? def : v;
   };
   return {
-    subject: get("--subject", "unknown"),
-    guidePath: get("--guide", null),
-    prompt: get("--prompt", null),
-    promptFile: get("--prompt-file", null),
-    negative: get("--negative", null),
-    seeds: parseNumberFlag('seeds', get("--seeds", "4"), { int: true, min: 1 }),
-    weight: parseNumberFlag('weight', get("--weight", "0.70"), { min: 0, max: 2 }),
-    guidanceEnd: parseNumberFlag('guidance-end', get("--guidance-end", "0.65"), { min: 0, max: 1 }),
-    controlModel: get("--model", "controlnet-canny-sdxl-1.0.safetensors"),
+    subject: get("subject", "unknown"),
+    guidePath: get("guide", null),
+    prompt: get("prompt", null),
+    promptFile: get("prompt-file", null),
+    negative: get("negative", null),
+    seeds: parseNumberFlag('seeds', get("seeds", "4"), { int: true, min: 1 }),
+    weight: parseNumberFlag('weight', get("weight", "0.70"), { min: 0, max: 2 }),
+    guidanceEnd: parseNumberFlag('guidance-end', get("guidance-end", "0.65"), { min: 0, max: 1 }),
+    controlModel: get("model", "controlnet-canny-sdxl-1.0.safetensors"),
     dryRun: argv.includes("--dry-run"),
+    // H5: skip a seed slot whose output image already exists. This script
+    // (unlike generate.js / generate-identity.js) never writes a
+    // records/<id>.json — only the output PNG — so resumability here is
+    // image-existence only; see scripts/_resume.js's requireRecord doc.
+    resume: argv.includes("--resume"),
   };
 }
 
@@ -169,7 +175,7 @@ function buildControlNetWorkflow(prompt, negativePrompt, seed, guideImagePath, c
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
   const opts = parseLocalArgs(argv);
@@ -180,8 +186,7 @@ export async function run(argv = process.argv.slice(2)) {
 
   // Freeze gate (advisory): refuse if the subject's canon entry is frozen.
   // Supports --i-know + --reason bypass for soft-advisory entries.
-  const reasonFlagIdx = argv.indexOf('--reason');
-  const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+  const bypassReason = takeFlagValue(argv, 'reason') ?? null;
   await assertNotFrozenBySubject(GAME_ROOT, opts.subject, {
     action: 'generate:controlnet',
     allowSoftAdvisoryBypass: argv.includes('--i-know'),
@@ -236,14 +241,28 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`\x1b[32m+\x1b[0m Guide uploaded: ${guideFilename}`);
   }
 
-  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+  // SDL-M11: only create the output dir on a real run — a --dry-run preview
+  // must be side-effect-free (README.md promises "preview the effect first").
+  if (!opts.dryRun) {
+    await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+  }
 
-  let successes = 0, failures = 0;
+  let successes = 0, failures = 0, skipped = 0;
   for (let si = 0; si < opts.seeds; si++) {
     const seed = DEFAULTS.base_seed + si;
     const assetId = `${opts.subject}_cn_s${si}`;
     const destPath = `outputs/candidates/${assetId}.png`;
 
+    // H5: --resume skips a seed slot whose output image already exists.
+    // Seed here is derived from the loop index (si), not an externally
+    // mutated running counter, so skipping never desyncs a later seed — the
+    // for-loop's own si++ always fires regardless of this continue.
+    if (opts.resume && !opts.dryRun && isResumable(GAME_ROOT, assetId, { requireRecord: false })) {
+      logResumedSkip(si + 1, opts.seeds, assetId);
+      skipped++;
+      continue;
+    }
+
     console.log(`  [${si + 1}/${opts.seeds}] ${assetId} (seed: ${seed})`);
 
     if (opts.dryRun) continue;
@@ -285,7 +304,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  console.log(`\n\x1b[32m+\x1b[0m ControlNet discovery complete (${successes} success, ${failures} failed)`);
+  const skippedSuffix = skipped > 0 ? `, ${skipped} resumed` : '';
+  console.log(`\n\x1b[32m+\x1b[0m ControlNet discovery complete (${successes} success, ${failures} failed${skippedSuffix})`);
   if (opts.dryRun) console.log("  (dry run)");
   if (!opts.dryRun && failures > 0 && successes === 0) {
     throw runtimeError('RUNTIME_ALL_FAILED', `All ${opts.seeds} ControlNet generation attempts failed.`);

package/scripts/generate-identity.js

@@ -18,16 +18,20 @@
  *   --phase MODE    Generation phase: discovery | follow_on (default: discovery)
  *   --anchor FILE   Anchor source image path (required for --phase follow_on)
  *   --denoise N     Denoise strength for follow_on phase (default: 0.38)
+ *   --resume        Skip shots whose record + output image already exist
+ *                    (seed slots still advance, so a resumed run stays
+ *                    bit-identical to an uninterrupted one)
  */
 
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName, parseNumberFlag } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag, takeFlagValue } from "../lib/args.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { readJsonFile, loadProjectMeta, resolveGpuModel } from "../lib/config.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage } from "../lib/comfyui.js";
 import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
+import { isResumable, logResumedSkip } from "./_resume.js";
 
 // ── Defaults (match existing lab pipeline) ──
 
@@ -378,12 +382,12 @@ function buildRecord(pack, subject, shot, seed, seedIndex, imgData, destPath, el
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
   const gpuModel = resolveGpuModel(loadProjectMeta(GAME_ROOT)?.defaults);
 
   // Collect positionals, skipping values that belong to known flags
-  const knownFlagsWithValue = new Set(['--subject', '--seeds', '--phase', '--anchor', '--denoise', '--project', '--game']);
+  const knownFlagsWithValue = new Set(['--subject', '--seeds', '--phase', '--anchor', '--denoise', '--project', '--game', '--reason']);
   const positionals = [];
   for (let k = 0; k < argv.length; k++) {
     const a = argv[k];
@@ -395,16 +399,23 @@ export async function run(argv = process.argv.slice(2)) {
   }
   const packPath = positionals[0];
   const dryRun = argv.includes("--dry-run");
-  const subjectFilter = argv.includes("--subject")
-    ? argv[argv.indexOf("--subject") + 1]
-    : null;
+  const resume = argv.includes("--resume");
+
+  // H4: takeFlagValue() (lib/args.js) recognizes BOTH `--flag value` and
+  // `--flag=value`. The previous `argv.includes('--x') ?
+  // argv[argv.indexOf('--x')+1] : default` pattern checked argv for a token
+  // EXACTLY EQUAL to "--x" — false for the single token "--phase=follow_on",
+  // so the equals form silently fell back to the default. For --phase that
+  // meant `--phase=follow_on` ran the discovery (txt2img) workflow instead
+  // of follow_on (img2img) — silently, on an hours-long GPU job. Same gap
+  // closed here for --seeds / --anchor / --denoise / --subject / --reason.
+  const subjectFilter = takeFlagValue(argv, 'subject') ?? null;
 
   // Freeze gate (advisory): when --subject is given, refuse if that subject's
   // canon entry is frozen. No-op when --subject is absent (pack-driven) or
   // when the project has no canon-build config.
   if (subjectFilter) {
-    const reasonFlagIdx = argv.indexOf('--reason');
-    const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+    const bypassReason = takeFlagValue(argv, 'reason') ?? null;
     await assertNotFrozenBySubject(GAME_ROOT, subjectFilter, {
       action: 'generate:identity',
       allowSoftAdvisoryBypass: argv.includes('--i-know'),
@@ -412,17 +423,15 @@ export async function run(argv = process.argv.slice(2)) {
       by: 'mike',
     });
   }
-  const seedCount = argv.includes("--seeds")
-    ? parseNumberFlag('seeds', argv[argv.indexOf("--seeds") + 1], { int: true, min: 1 })
+  const seedsRaw = takeFlagValue(argv, 'seeds');
+  const seedCount = seedsRaw !== undefined
+    ? parseNumberFlag('seeds', seedsRaw, { int: true, min: 1 })
     : 3;
-  const phase = argv.includes("--phase")
-    ? argv[argv.indexOf("--phase") + 1]
-    : "discovery";
-  const anchorPath = argv.includes("--anchor")
-    ? argv[argv.indexOf("--anchor") + 1]
-    : null;
-  const denoise = argv.includes("--denoise")
-    ? parseNumberFlag('denoise', argv[argv.indexOf("--denoise") + 1], { min: 0, max: 1 })
+  const phase = takeFlagValue(argv, 'phase') ?? "discovery";
+  const anchorPath = takeFlagValue(argv, 'anchor') ?? null;
+  const denoiseRaw = takeFlagValue(argv, 'denoise');
+  const denoise = denoiseRaw !== undefined
+    ? parseNumberFlag('denoise', denoiseRaw, { min: 0, max: 1 })
     : 0.38;
 
   if (!packPath) {
@@ -474,11 +483,16 @@ export async function run(argv = process.argv.slice(2)) {
     console.log("\x1b[32m+\x1b[0m ComfyUI online");
   }
 
-  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
-  await mkdir(join(GAME_ROOT, "records"), { recursive: true });
+  // SDL-M11: only create output dirs on a real run — a --dry-run preview must
+  // be side-effect-free (README.md promises "preview the effect first").
+  if (!dryRun) {
+    await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+    await mkdir(join(GAME_ROOT, "records"), { recursive: true });
+  }
 
   let generated = 0;
   let errors = 0;
+  let skipped = 0;
   let imageIndex = 0;
 
   for (const subject of subjects) {
@@ -498,6 +512,21 @@ export async function run(argv = process.argv.slice(2)) {
         const assetId = `${shot.id}_s${si}`;
         const destPath = `outputs/candidates/${assetId}.png`;
 
+        // H5: --resume skips a shot whose record AND output image already
+        // exist, but imageIndex (and therefore seed) still advances exactly
+        // as it would have if the shot had been processed — a resumed run
+        // reproduces the identical seed sequence an uninterrupted run would
+        // have produced. Ported from generate.js, the one generator that had
+        // this; generate-identity is the most expensive per-image generator
+        // in the pipeline, so it is the one that most needed it.
+        if (resume && !dryRun && isResumable(GAME_ROOT, assetId)) {
+          logResumedSkip(generated + 1, totalImages, assetId);
+          generated++;
+          skipped++;
+          imageIndex++;
+          continue;
+        }
+
         console.log(`    [${generated + 1}/${totalImages}] ${assetId} (seed: ${seed})`);
 
         if (dryRun) {
@@ -572,8 +601,9 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  const succeeded = generated - errors;
-  console.log(`\n\x1b[32m+\x1b[0m Generated ${succeeded} images (${errors} errors)`);
+  const succeeded = generated - errors - skipped;
+  const skippedSuffix = skipped > 0 ? `, ${skipped} resumed` : '';
+  console.log(`\n\x1b[32m+\x1b[0m Generated ${succeeded} images (${errors} errors${skippedSuffix})`);
   if (dryRun) console.log("  (dry run — no images produced)");
   if (!dryRun && errors > 0 && succeeded === 0) {
     throw runtimeError('RUNTIME_ALL_FAILED', `All ${generated} generation attempts failed.`);

package/scripts/generate-ipadapter.js

@@ -13,11 +13,12 @@
 
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { getProjectName, parseNumberFlag } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag, takeFlagValue } from "../lib/args.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { inputError, runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 import { assertNotFrozenBySubject } from "../lib/freeze-gate.js";
+import { isResumable, logResumedSkip } from "./_resume.js";
 
 const DEFAULTS = {
   checkpoint: "dreamshaperXL_v21TurboDPMSDE.safetensors",
@@ -33,26 +34,31 @@ const DEFAULTS = {
   base_seed: 27200,
 };
 
+// H4: takeFlagValue() (lib/args.js) recognizes BOTH `--flag value` and
+// `--flag=value`. The prior `argv.indexOf(flag)`-based get() only matched a
+// token EXACTLY equal to e.g. "--weight" — false for the single token
+// "--weight=1.1" — so the equals form silently fell back to the default
+// with no error and no warning.
 function parseLocalArgs(argv) {
-  const get = (flag, def) => {
-    const i = argv.indexOf(flag);
-    if (i < 0 || i + 1 >= argv.length) return def;
-    const v = argv[i + 1];
-    if (typeof v === 'string' && v.startsWith('--')) {
-      throw inputError('INPUT_MISSING_VALUE', `Flag ${flag} is missing its value (got another flag: ${v}).`);
-    }
-    return v;
+  const get = (flagName, def) => {
+    const v = takeFlagValue(argv, flagName);
+    return v === undefined ? def : v;
   };
   return {
-    subject: get("--subject", "unknown"),
-    refPath: get("--ref", null),
-    prompt: get("--prompt", null),
-    negative: get("--negative", null),
-    seeds: parseNumberFlag('seeds', get("--seeds", "4"), { int: true, min: 1 }),
-    weight: parseNumberFlag('weight', get("--weight", "0.55"), { min: 0, max: 2 }),
-    start: parseNumberFlag('start', get("--start", "0.0"), { min: 0, max: 1 }),
-    end: parseNumberFlag('end', get("--end", "0.8"), { min: 0, max: 1 }),
+    subject: get("subject", "unknown"),
+    refPath: get("ref", null),
+    prompt: get("prompt", null),
+    negative: get("negative", null),
+    seeds: parseNumberFlag('seeds', get("seeds", "4"), { int: true, min: 1 }),
+    weight: parseNumberFlag('weight', get("weight", "0.55"), { min: 0, max: 2 }),
+    start: parseNumberFlag('start', get("start", "0.0"), { min: 0, max: 1 }),
+    end: parseNumberFlag('end', get("end", "0.8"), { min: 0, max: 1 }),
     dryRun: argv.includes("--dry-run"),
+    // H5: skip a seed slot whose output image already exists. This script
+    // (unlike generate.js / generate-identity.js) never writes a
+    // records/<id>.json — only the output PNG — so resumability here is
+    // image-existence only; see scripts/_resume.js's requireRecord doc.
+    resume: argv.includes("--resume"),
   };
 }
 
@@ -175,7 +181,7 @@ function buildIPAdapterWorkflow(prompt, negativePrompt, seed, refImageName, weig
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
   const opts = parseLocalArgs(argv);
@@ -188,8 +194,7 @@ export async function run(argv = process.argv.slice(2)) {
   }
 
   // Freeze gate (advisory): refuse if the subject's canon entry is frozen.
-  const reasonFlagIdx = argv.indexOf('--reason');
-  const bypassReason = reasonFlagIdx >= 0 && argv[reasonFlagIdx + 1] ? argv[reasonFlagIdx + 1] : null;
+  const bypassReason = takeFlagValue(argv, 'reason') ?? null;
   await assertNotFrozenBySubject(GAME_ROOT, opts.subject, {
     action: 'generate:ipadapter',
     allowSoftAdvisoryBypass: argv.includes('--i-know'),
@@ -224,13 +229,28 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`\x1b[32m+\x1b[0m Reference uploaded: ${refFilename}`);
   }
 
-  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+  // SDL-M11: only create the output dir on a real run — a --dry-run preview
+  // must be side-effect-free (README.md promises "preview the effect first").
+  if (!opts.dryRun) {
+    await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+  }
 
+  let skipped = 0;
   for (let si = 0; si < opts.seeds; si++) {
     const seed = DEFAULTS.base_seed + si;
     const assetId = `${opts.subject}_ipa_s${si}`;
     const destPath = `outputs/candidates/${assetId}.png`;
 
+    // H5: --resume skips a seed slot whose output image already exists.
+    // Seed here is derived from the loop index (si), not an externally
+    // mutated running counter, so skipping never desyncs a later seed — the
+    // for-loop's own si++ always fires regardless of this continue.
+    if (opts.resume && !opts.dryRun && isResumable(GAME_ROOT, assetId, { requireRecord: false })) {
+      logResumedSkip(si + 1, opts.seeds, assetId);
+      skipped++;
+      continue;
+    }
+
     console.log(`  [${si + 1}/${opts.seeds}] ${assetId} (seed: ${seed})`);
 
     if (opts.dryRun) continue;
@@ -269,7 +289,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
-  console.log("\n\x1b[32m+\x1b[0m IP-Adapter discovery complete");
+  const skippedSuffix = skipped > 0 ? ` (${skipped} resumed)` : '';
+  console.log(`\n\x1b[32m+\x1b[0m IP-Adapter discovery complete${skippedSuffix}`);
   if (opts.dryRun) console.log("  (dry run)");
 }
 

package/scripts/generate.js

@@ -14,14 +14,14 @@ import { writeFile, mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { parseArgs, getProjectName } from "../lib/args.js";
-import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { getProjectRoot, resolveSafeProjectPath } from "../lib/paths.js";
 import { readJsonFile, loadProjectMeta, resolveGpuModel } from "../lib/config.js";
 import { runtimeError, inputError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage } from "../lib/comfyui.js";
 import { pickOutputImage } from "../lib/comfyui-output.js";
 import { buildQwenGraph, QWEN_DEFAULTS } from "../lib/adapters/comfyui-workflows.js";
 import { buildPinning, SEED_POLICIES, createHashCache, flushHashCache } from "../lib/run-manifest.js";
-import { info, result } from "../lib/log.js";
+import { info, result, warn } from "../lib/log.js";
 
 /**
  * Format milliseconds as a human ETA string like "6m 12s" or "42s".
@@ -179,6 +179,34 @@ function buildWorkflow(prompt, negativePrompt, checkpoint, loras, seed, steps, c
   return { nodes, saveNodeId: saveId };
 }
 
+/**
+ * Coordinator addendum (same session as H4/H5): every domain template's
+ * example-wave.json ships subject prompts with a literal `[DESCRIBE ...]`
+ * placeholder (e.g. "[DESCRIBE YOUR HERO — head and shoulders, ...]") that
+ * the user is meant to replace before generating. `sdlab init`'s own
+ * printed next-steps run generate before "edit the pack" is ever a
+ * mandatory step, so following them literally on an unedited pack burns a
+ * GPU wave on template text with no feedback until the images come back
+ * looking like a literal instruction string.
+ *
+ * All 5 domain templates use this exact "[DESCRIBE " shape (verified across
+ * templates/domains/*\/inputs/prompts/example-wave.json), so the check is
+ * narrow and specific to it — it does NOT flag ordinary SD prompt-editing
+ * bracket syntax such as "[word]" or "[from:to:0.5]", neither of which
+ * starts with the literal word DESCRIBE.
+ */
+const PLACEHOLDER_PROMPT_RE = /\[DESCRIBE\b/;
+
+function findPlaceholderPrompts(jobs) {
+  const hits = [];
+  for (const job of jobs) {
+    if (typeof job.prompt === 'string' && PLACEHOLDER_PROMPT_RE.test(job.prompt)) {
+      hits.push(job.assetId);
+    }
+  }
+  return hits;
+}
+
 /**
  * Detect the input schema and normalize to a unified shape:
  *   { lane, style_prefix, negative, defaults, base, jobs:[{assetId, subjectId, variationId, prompt, seed, loras}] }
@@ -264,7 +292,7 @@ function normalizeGenerationInput(raw, projectMeta) {
 
 export async function run(argv = process.argv.slice(2)) {
   const projectName = getProjectName(argv);
-  const GAME_ROOT = join(REPO_ROOT, 'projects', projectName);
+  const GAME_ROOT = getProjectRoot(projectName);
   const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
 
   const parsed = parseArgs(argv, {
@@ -323,6 +351,17 @@ export async function run(argv = process.argv.slice(2)) {
   console.log(`  Total candidates: ${pack.jobs.length}`);
   console.log("");
 
+  // Coordinator addendum: catch unedited template text before it burns GPU
+  // time (or, under --dry-run, before the user thinks the pack is ready).
+  const placeholderHits = findPlaceholderPrompts(pack.jobs);
+  if (placeholderHits.length > 0) {
+    warn(
+      `${placeholderHits.length} of ${pack.jobs.length} prompt(s) still contain unedited "[DESCRIBE ...]" template ` +
+      `text (e.g. "${placeholderHits[0]}"). Edit the prompt pack before generating for real — otherwise you'll spend ` +
+      `GPU time rendering placeholder instructions instead of your subject.`
+    );
+  }
+
   if (!dryRun) {
     const online = await comfyHealth(COMFY_URL);
     if (!online) {
@@ -331,8 +370,12 @@ export async function run(argv = process.argv.slice(2)) {
     console.log("\x1b[32m✓\x1b[0m ComfyUI online");
   }
 
-  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
-  await mkdir(join(GAME_ROOT, "records"), { recursive: true });
+  // SDL-M11: only create output dirs on a real run — a --dry-run preview must
+  // be side-effect-free (README.md promises "preview the effect first").
+  if (!dryRun) {
+    await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+    await mkdir(join(GAME_ROOT, "records"), { recursive: true });
+  }
 
   let generated = 0;
   let errors = 0;

package/scripts/implementation-pack.js

@@ -11,7 +11,7 @@
 
 import { join } from 'node:path';
 import { parseArgs, getProjectName } from '../lib/args.js';
-import { REPO_ROOT } from '../lib/paths.js';
+import { getProjectRoot } from '../lib/paths.js';
 import { inputError, handleCliError } from '../lib/errors.js';
 import { listTrainingManifests } from '../lib/training-manifests.js';
 import { buildImplementationPack, listImplementationPacks, loadImplementationPack } from '../lib/implementation-packs.js';
@@ -26,7 +26,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const projectName = flags.project || getProjectName(argv);
-  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const projectRoot = getProjectRoot(projectName);
   const subcommand = positionals.find(a => !a.startsWith('impl-') && !a.startsWith('tm-')) || 'list';
 
   if (subcommand === 'build') {

package/scripts/ingest.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+/**
+ * ingest.js — Bring a directory of pre-existing images into the pipeline
+ * as bare, uncurated candidate records.
+ *
+ * Closes the gap where generation happened OUTSIDE sdlab entirely (a hand
+ * batch, external Python against Comfy Cloud, salvage from somewhere else)
+ * and there was no CLI path to get those images into records/ for review.
+ * Unlike `sdlab reingest generated` (which requires a trained LoRA's
+ * training manifest) or `sdlab reingest selected` (which requires a
+ * selection id only the production loop can mint), this takes any folder
+ * of images and any project — no pipeline history required.
+ *
+ * Usage:
+ *   sdlab ingest <dir> --project <name>
+ *   sdlab ingest <dir> --project <name> --wave inputs/prompts/wave-v2.json
+ *   sdlab ingest <dir> --project <name> --dry-run
+ *   sdlab ingest <dir> --project <name> --json
+ */
+
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { REPO_ROOT, getProjectRoot, resolveSafeProjectPath } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
+import { ingestDirectory } from '../lib/ingest.js';
+import { result } from '../lib/log.js';
+
+const USAGE = `Usage: sdlab ingest <dir> --project <name> [--wave <wave.json>] [--dry-run] [--json]
+
+Scan <dir> for images and create bare candidate records (judgment: null,
+canon: null, provenance.source: "external") ready for "sdlab curate".
+
+Positional:
+  dir                  Directory of images to ingest (png/jpg/jpeg/webp)
+
+Flags:
+  --project <name>     Project to operate on
+  --wave <path>        Optional wave JSON (inputs/prompts/*.json shape) to
+                        attach real generation provenance (seed, prompt, ...)
+                        by matching each image's filename stem to an item id.
+                        A sibling receipts.jsonl next to <dir> is picked up
+                        automatically when present (prompt_id, seconds, status).
+  --dry-run            Preview what would be created — no files written
+  --json               Emit the result as JSON on stdout
+
+Next steps after ingesting:
+  1. Review: sdlab curate <id> approved/rejected "explanation"
+  2. Bind:   sdlab bind --project <name>`;
+
+export async function run(argv = process.argv.slice(2)) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(USAGE);
+    return;
+  }
+
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      wave: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const dirArg = positionals[0];
+  if (!dirArg) {
+    throw inputError(
+      'INPUT_MISSING_ARGS',
+      'A source directory is required.',
+      USAGE
+    );
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const dryRun = flags['dry-run'] || flags.dryRun;
+
+  // Mirrors scripts/reingest.js's --source handling: the source directory
+  // of pre-existing images is allowed to live anywhere under the workspace
+  // root, not just inside this specific project (e.g. a shared staging
+  // inbox), while still refusing to escape the workspace entirely.
+  const safeSourceDir = resolveSafeProjectPath(projectRoot, dirArg, { baseRoot: REPO_ROOT, flagName: 'dir' });
+
+  // Mirrors scripts/generate.js's pack-path handling: a --wave file is
+  // expected to live inside THIS project (inputs/prompts/*.json), so its
+  // containment root defaults to the project root, not the whole workspace.
+  const safeWavePath = flags.wave
+    ? resolveSafeProjectPath(projectRoot, flags.wave, { flagName: 'wave' })
+    : null;
+
+  if (!flags.json) {
+    console.log(`\x1b[1msdlab ingest\x1b[0m — ${projectName}`);
+    console.log(`  Source: ${dirArg}`);
+    if (flags.wave) console.log(`  Wave:   ${flags.wave}`);
+    if (dryRun) console.log(`  Mode:   DRY RUN (no files written)`);
+    console.log('');
+  }
+
+  const { created, skipped, rejected, receiptsFile } = await ingestDirectory(projectRoot, safeSourceDir, {
+    wavePath: safeWavePath,
+    dryRun,
+  });
+
+  if (flags.json) {
+    console.log(JSON.stringify({ created, skipped, rejected, receiptsFile, dryRun }, null, 2));
+    return;
+  }
+
+  if (receiptsFile) {
+    console.log(`  \x1b[2mreceipts: ${receiptsFile}\x1b[0m`);
+  }
+
+  console.log(`  \x1b[32m✓\x1b[0m Created: ${created.length} record(s)${dryRun ? ' (dry run — nothing written)' : ''}`);
+  if (created.length > 0 && created.length <= 25) {
+    for (const id of created) console.log(`    ✓ ${id}`);
+  }
+
+  if (skipped.length > 0) {
+    console.log(`  Skipped: ${skipped.length} (record already exists)`);
+    if (skipped.length <= 25) {
+      for (const id of skipped) console.log(`    ○ ${id}`);
+    }
+  }
+
+  if (rejected.length > 0) {
+    console.log(`  \x1b[33m⚠\x1b[0m Rejected: ${rejected.length} (unsafe id derived from filename — rename and re-run)`);
+    for (const r of rejected) console.log(`    ✗ ${r.file}: ${r.reason}`);
+  }
+
+  if (!dryRun && created.length > 0) {
+    console.log('');
+    result(`Candidates: outputs/candidates/`);
+    result(`Records: records/`);
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    1. Review: sdlab curate <id> approved/rejected "explanation"');
+    console.log('    2. Bind:   sdlab bind --project ' + projectName);
+  }
+}
+
+// Direct execution guard
+if (process.argv[1] && (process.argv[1].endsWith('ingest.js') || process.argv[1].endsWith('ingest'))) {
+  run().catch(handleCliError);
+}