@mcptoolshop/style-dataset-lab 1.1.0

package/scripts/curate-wave25.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Curation for wave 25 (expanded universe).
+ *
+ * Based on visual review of all 60 candidates:
+ * - REJECT25* subjects → rejected (anti-examples)
+ * - Strong hits → approved with high scores
+ * - Partial hits → approved with moderate scores + notes
+ * - Misses → rejected with explanations of what went wrong
+ *
+ * Usage:
+ *   node scripts/curate-wave25.js
+ *   node scripts/curate-wave25.js --dry-run
+ */
+
+import { readFileSync, writeFileSync, readdirSync, renameSync, existsSync, mkdirSync } from 'fs';
+import { join, basename } from 'path';
+
+const REPO_ROOT = new URL("..", import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1");
+const GAME = process.argv.find((a, i) => process.argv[i - 1] === '--game') || 'star-freight';
+const GAME_ROOT = join(REPO_ROOT, 'games', GAME);
+
+const RECORDS_DIR = join(GAME_ROOT, 'records');
+const CANDIDATES_DIR = join(GAME_ROOT, 'outputs', 'candidates');
+const APPROVED_DIR = join(GAME_ROOT, 'outputs', 'approved');
+const REJECTED_DIR = join(GAME_ROOT, 'outputs', 'rejected');
+const DRY_RUN = process.argv.includes('--dry-run');
+
+for (const dir of [APPROVED_DIR, REJECTED_DIR]) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// ─── Scoring profiles ──────────────────────────────────────────
+
+const STRONG_HIT = {
+  silhouette_clarity: 0.85, palette_adherence: 0.80, material_fidelity: 0.80,
+  faction_read: 0.75, wear_level: 0.85, style_consistency: 0.85,
+  clothing_logic: 0.70, composition: 0.85
+};
+
+const PARTIAL_HIT = {
+  silhouette_clarity: 0.70, palette_adherence: 0.70, material_fidelity: 0.70,
+  faction_read: 0.50, wear_level: 0.75, style_consistency: 0.75,
+  clothing_logic: 0.55, composition: 0.75
+};
+
+// ─── Subject classifications ──────────────────────────────────────────
+
+// Strong hits — approved with high scores
+const STRONG_HITS = new Set([
+  'keth_molt_before', 'keth_molt_emerging', 'keth_hivesong', 'keth_pheromone_library',
+  'veshan_forge_trial', 'veshan_forge_trial_judgment',
+  'orryn_sealed_mantle', 'orryn_crystal_inheritance',
+  'thresh_young',
+  'mire_at_work',
+  'vaelk_proxy_market',
+  'architect_jump_gate', 'architect_archive_node', 'architect_ruin_surface',
+  'drift_kelp_bed',
+  'translator_rig'
+]);
+
+// Partial hits — approved with moderate scores
+const PARTIAL_HITS = new Set([
+  'veshan_battle_opera', 'veshan_scale_reader',
+  'orryn_drift_parliament', 'orryn_drift_parliament_failed',
+  'drift_kelp_ambush',
+  'vaelk_proxy_trade',
+  'station_climate_border',
+  'pidgin_trade_sign'
+]);
+
+// Misses — rejected with explanations
+const MISS_EXPLANATIONS = {
+  thresh_old_station: {
+    explanation: "Thresh crystalline organism not visible — rendered as standard station corridor with human. Need to foreground the crystalline growth formation.",
+    failures: ["species_not_rendered", "concept_miss"],
+    scores: { silhouette_clarity: 0.6, palette_adherence: 0.5, material_fidelity: 0.6, faction_read: 0.1, wear_level: 0.7, style_consistency: 0.7, clothing_logic: 0.3, composition: 0.6 }
+  },
+  smuggler_cant_meeting: {
+    explanation: "All figures rendered as human — no multi-species element. The cross-species communication concept requires at least 2 different species visible.",
+    failures: ["species_not_rendered", "concept_miss"],
+    scores: { silhouette_clarity: 0.7, palette_adherence: 0.6, material_fidelity: 0.7, faction_read: 0.1, wear_level: 0.7, style_consistency: 0.7, clothing_logic: 0.5, composition: 0.7 }
+  },
+  mire_reforming: {
+    explanation: "Green-tinted corridor with organic matter but no clear colonial organism reforming. The aggregation process needs to be the focal point.",
+    failures: ["concept_miss"],
+    scores: { silhouette_clarity: 0.5, palette_adherence: 0.6, material_fidelity: 0.6, faction_read: 0.3, wear_level: 0.7, style_consistency: 0.7, clothing_logic: 0.3, composition: 0.6 }
+  },
+  mire_hull_breach: {
+    explanation: "Rendered as military cockpit scene — no Mire organism flowing through hull breach. Complete concept miss.",
+    failures: ["species_not_rendered", "concept_miss"],
+    scores: { silhouette_clarity: 0.6, palette_adherence: 0.4, material_fidelity: 0.5, faction_read: 0.0, wear_level: 0.6, style_consistency: 0.5, clothing_logic: 0.3, composition: 0.6 }
+  }
+};
+
+// Reject examples — always rejected
+const REJECT_EXPLANATIONS = {
+  REJECT25_clean_alien: {
+    explanation: "Clean sterile alien civilization — Star Trek utopia aesthetic. Violates every grit principle.",
+    failures: ["too_clean", "generic_scifi"],
+    scores: { silhouette_clarity: 0.7, palette_adherence: 0.1, material_fidelity: 0.2, faction_read: 0.0, wear_level: 0.0, style_consistency: 0.3, clothing_logic: 0.2, composition: 0.7 }
+  },
+  REJECT25_fantasy_alien: {
+    explanation: "Fantasy wizard alien with robes and magic staff — high fantasy, not grounded sci-fi.",
+    failures: ["wrong_genre", "costume_not_clothes"],
+    scores: { silhouette_clarity: 0.6, palette_adherence: 0.1, material_fidelity: 0.2, faction_read: 0.0, wear_level: 0.1, style_consistency: 0.1, clothing_logic: 0.1, composition: 0.6 }
+  }
+};
+
+// ─── Process ──────────────────────────────────────────
+
+const wave25Files = readdirSync(CANDIDATES_DIR).filter(f =>
+  f.endsWith('.png') && readdirSync(RECORDS_DIR).some(r => {
+    try {
+      const rec = JSON.parse(readFileSync(join(RECORDS_DIR, r), 'utf-8'));
+      return rec.file === f && rec.lane === 'wave25-expanded-universe';
+    } catch { return false; }
+  })
+);
+
+// Fallback: match by known subject IDs
+const ALL_SUBJECTS = [
+  ...STRONG_HITS, ...PARTIAL_HITS,
+  ...Object.keys(MISS_EXPLANATIONS),
+  ...Object.keys(REJECT_EXPLANATIONS)
+];
+
+// Find wave25 records directly by filename match
+const recordFiles = readdirSync(RECORDS_DIR).filter(r => r.endsWith('.json'));
+const candidates = recordFiles.filter(rf => {
+  return ALL_SUBJECTS.some(subj => rf.startsWith(subj));
+});
+
+let approved = 0, rejected = 0, skipped = 0;
+
+for (const recordFile of candidates) {
+  let record;
+  try {
+    record = JSON.parse(readFileSync(join(RECORDS_DIR, recordFile), 'utf-8'));
+  } catch { continue; }
+
+  const file = basename(record.asset_path || '');
+  const subjectId = record.id?.replace(/_v[12]$/, '') || file.replace(/_v[12]\.png$/, '');
+
+  // Already curated?
+  if (record.verdict) {
+    console.log(`  ⏭ ${file} already curated (${record.verdict})`);
+    skipped++;
+    continue;
+  }
+
+  let verdict, scores, explanation, failures;
+
+  if (REJECT_EXPLANATIONS[subjectId]) {
+    const r = REJECT_EXPLANATIONS[subjectId];
+    verdict = 'rejected';
+    scores = r.scores;
+    explanation = r.explanation;
+    failures = r.failures;
+  } else if (MISS_EXPLANATIONS[subjectId]) {
+    const m = MISS_EXPLANATIONS[subjectId];
+    verdict = 'rejected';
+    scores = m.scores;
+    explanation = m.explanation;
+    failures = m.failures;
+  } else if (STRONG_HITS.has(subjectId)) {
+    verdict = 'approved';
+    scores = { ...STRONG_HIT };
+    explanation = `Strong hit — concept reads clearly, style consistent, gritty lived-in aesthetic.`;
+    failures = [];
+  } else if (PARTIAL_HITS.has(subjectId)) {
+    verdict = 'approved';
+    scores = { ...PARTIAL_HIT };
+    explanation = `Partial hit — atmosphere and style correct, some species anatomy or concept details missed.`;
+    failures = ['partial_species_accuracy'];
+  } else {
+    console.log(`  ⚠ Unknown subject ${subjectId} for ${file}, skipping`);
+    skipped++;
+    continue;
+  }
+
+  // Update record
+  record.verdict = verdict;
+  record.scores = scores;
+  record.explanation = explanation;
+  record.failures = failures;
+  record.curated_at = new Date().toISOString();
+  record.curator = 'wave25-script';
+
+  // Move file
+  const srcPath = join(CANDIDATES_DIR, file);
+  const dstDir = verdict === 'approved' ? APPROVED_DIR : REJECTED_DIR;
+  const dstPath = join(dstDir, file);
+
+  if (!DRY_RUN) {
+    writeFileSync(join(RECORDS_DIR, recordFile), JSON.stringify(record, null, 2));
+    if (existsSync(srcPath)) {
+      renameSync(srcPath, dstPath);
+    }
+  }
+
+  const icon = verdict === 'approved' ? '✓' : '✗';
+  console.log(`  ${icon} ${file} → ${verdict}`);
+  if (verdict === 'approved') approved++;
+  else rejected++;
+}
+
+console.log(`\nWave 25 curation: ${approved} approved, ${rejected} rejected, ${skipped} skipped`);
+if (DRY_RUN) console.log('  (dry run — no files moved)');

package/scripts/curate.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+/**
+ * curate.js — Move a candidate to approved/rejected/borderline and record judgment.
+ *
+ * Usage:
+ *   node scripts/curate.js <asset_id> approved "Clean silhouette, correct palette" --scores silhouette:0.9,palette:0.8
+ *   node scripts/curate.js <asset_id> rejected "3D render look, alpha halo" --failures alpha_halo,3d_render_look
+ *   node scripts/curate.js --list  (show uncurated candidates)
+ */
+
+import { readFile, writeFile, rename, readdir, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+const REPO_ROOT = new URL("..", import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1");
+const GAME = process.argv.find((a, i) => process.argv[i - 1] === '--game') || 'star-freight';
+const GAME_ROOT = join(REPO_ROOT, 'games', GAME);
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes("--list")) {
+    return listUncurated();
+  }
+
+  const [assetId, status, explanation, ...rest] = args;
+
+  if (!assetId || !status || !explanation) {
+    console.log("Usage: node scripts/curate.js <asset_id> <approved|rejected|borderline> <explanation> [--scores k:v,...] [--failures f1,f2]");
+    process.exit(1);
+  }
+
+  if (!["approved", "rejected", "borderline"].includes(status)) {
+    console.error(`Invalid status: ${status}. Must be approved, rejected, or borderline.`);
+    process.exit(1);
+  }
+
+  // Parse optional flags
+  const scoresStr = getFlagValue(rest, "scores");
+  const failuresStr = getFlagValue(rest, "failures");
+  const notesStr = getFlagValue(rest, "notes");
+
+  const criteria_scores = {};
+  if (scoresStr) {
+    for (const pair of scoresStr.split(",")) {
+      const [k, v] = pair.split(":");
+      if (k && v) criteria_scores[k.trim()] = parseFloat(v);
+    }
+  }
+
+  const failure_modes = failuresStr ? failuresStr.split(",").map((s) => s.trim()) : [];
+
+  // Load existing record
+  const recordPath = join(GAME_ROOT, `records/${assetId}.json`);
+  let record;
+  try {
+    record = JSON.parse(await readFile(recordPath, "utf-8"));
+  } catch {
+    console.error(`Record not found: ${recordPath}`);
+    process.exit(1);
+  }
+
+  // Update record first (write before move to avoid orphaned images)
+  const oldPath = join(GAME_ROOT, record.asset_path);
+  const newDir = `outputs/${status}`;
+  const newPath = `${newDir}/${assetId}.png`;
+  await mkdir(join(GAME_ROOT, newDir), { recursive: true });
+
+  record.asset_path = newPath;
+  record.judgment = {
+    status,
+    reviewer: "human:mike",
+    reviewed_at: new Date().toISOString(),
+    explanation,
+    criteria_scores,
+    failure_modes,
+    improvement_notes: notesStr || null,
+    confidence: 0.9,
+  };
+
+  await writeFile(recordPath, JSON.stringify(record, null, 2));
+
+  // Move image file
+  try {
+    await rename(oldPath, join(GAME_ROOT, newPath));
+  } catch {
+    console.error(`Could not move ${oldPath} to ${newPath}`);
+    process.exit(1);
+  }
+
+  console.log(`\x1b[32m✓\x1b[0m ${assetId} → ${status}`);
+  console.log(`  ${explanation}`);
+  if (failure_modes.length) console.log(`  Failures: ${failure_modes.join(", ")}`);
+}
+
+async function listUncurated() {
+  const recordsDir = join(GAME_ROOT, "records");
+  let files;
+  try {
+    files = await readdir(recordsDir);
+  } catch {
+    console.log("No records directory.");
+    return;
+  }
+
+  let uncurated = 0;
+  let curated = 0;
+
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    const record = JSON.parse(await readFile(join(recordsDir, file), "utf-8"));
+    if (!record.judgment) {
+      console.log(`  ${record.id}`);
+      uncurated++;
+    } else {
+      curated++;
+    }
+  }
+
+  console.log(`\n${uncurated} uncurated, ${curated} curated`);
+}
+
+function getFlagValue(args, flag) {
+  const prefix = `--${flag}=`;
+  for (const a of args) {
+    if (a.startsWith(prefix)) return a.slice(prefix.length);
+  }
+  const idx = args.indexOf(`--${flag}`);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  return undefined;
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/generate-controlnet.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+
+/**
+ * generate-controlnet.js — ControlNet-guided discovery for structural subjects.
+ *
+ * For subjects where txt2img fails on anatomy (Naia) or scale (Corrigan),
+ * this script uses a structural guide image with ControlNet to force
+ * the body plan / hull shape, then lets SDXL fill surface language.
+ *
+ * Usage:
+ *   node scripts/generate-controlnet.js --subject naia --guide inputs/control-guides/naia_structural_guide.png --seeds 4
+ *   node scripts/generate-controlnet.js --subject corrigan --guide inputs/control-guides/corrigan_structural_guide.png --seeds 4
+ *   node scripts/generate-controlnet.js --subject naia --guide ... --dry-run
+ *
+ * Options:
+ *   --subject NAME   Subject name (used for output file naming)
+ *   --guide PATH     Path to structural guide image (white-on-black silhouette)
+ *   --prompt TEXT     Generation prompt (or reads from --prompt-file)
+ *   --prompt-file F   JSON file with {prompt, negative} fields
+ *   --negative TEXT   Negative prompt override
+ *   --seeds N         Number of seeds (default: 4)
+ *   --weight W        ControlNet weight (default: 0.70)
+ *   --guidance-end E  ControlNet guidance end (default: 0.65)
+ *   --model M         ControlNet model filename (default: controlnet-canny-sdxl-1.0.safetensors)
+ *   --dry-run         Print workflow without running
+ */
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+const COMFY_URL = process.env.COMFY_URL || "http://127.0.0.1:8188";
+const REPO_ROOT = new URL("..", import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1");
+const GAME = process.argv.find((a, i) => process.argv[i - 1] === '--game') || 'star-freight';
+const GAME_ROOT = join(REPO_ROOT, 'games', GAME);
+
+const DEFAULTS = {
+  checkpoint: "dreamshaperXL_v21TurboDPMSDE.safetensors",
+  loras: [{ name: "classipeintxl_v21.safetensors", weight: 1.0 }],
+  steps: 12,
+  cfg: 2.5,
+  sampler: "dpmpp_sde",
+  scheduler: "karras",
+  width: 1024,
+  height: 1024,
+  base_seed: 27100,
+};
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const get = (flag, def) => {
+    const i = args.indexOf(flag);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : def;
+  };
+  return {
+    subject: get("--subject", "unknown"),
+    guidePath: get("--guide", null),
+    prompt: get("--prompt", null),
+    promptFile: get("--prompt-file", null),
+    negative: get("--negative", null),
+    seeds: parseInt(get("--seeds", "4"), 10),
+    weight: parseFloat(get("--weight", "0.70")),
+    guidanceEnd: parseFloat(get("--guidance-end", "0.65")),
+    controlModel: get("--model", "controlnet-canny-sdxl-1.0.safetensors"),
+    dryRun: args.includes("--dry-run"),
+  };
+}
+
+function buildControlNetWorkflow(prompt, negativePrompt, seed, guideImagePath, controlModel, weight, guidanceEnd) {
+  const nodes = {};
+  let nextId = 1;
+
+  // Checkpoint
+  const ckptId = String(nextId++);
+  nodes[ckptId] = {
+    class_type: "CheckpointLoaderSimple",
+    inputs: { ckpt_name: DEFAULTS.checkpoint },
+  };
+
+  let modelOut = [ckptId, 0];
+  let clipOut = [ckptId, 1];
+
+  // LoRA
+  for (const lora of DEFAULTS.loras) {
+    const loraId = String(nextId++);
+    nodes[loraId] = {
+      class_type: "LoraLoader",
+      inputs: {
+        model: modelOut,
+        clip: clipOut,
+        lora_name: lora.name,
+        strength_model: lora.weight,
+        strength_clip: lora.weight,
+      },
+    };
+    modelOut = [loraId, 0];
+    clipOut = [loraId, 1];
+  }
+
+  // Load guide image
+  const loadGuideId = String(nextId++);
+  nodes[loadGuideId] = {
+    class_type: "LoadImage",
+    inputs: { image: guideImagePath },
+  };
+
+  // Load ControlNet model
+  const cnLoadId = String(nextId++);
+  nodes[cnLoadId] = {
+    class_type: "ControlNetLoader",
+    inputs: { control_net_name: controlModel },
+  };
+
+  // Positive prompt
+  const posId = String(nextId++);
+  nodes[posId] = {
+    class_type: "CLIPTextEncode",
+    inputs: { text: prompt, clip: clipOut },
+  };
+
+  // Negative prompt
+  const negId = String(nextId++);
+  nodes[negId] = {
+    class_type: "CLIPTextEncode",
+    inputs: { text: negativePrompt, clip: clipOut },
+  };
+
+  // Apply ControlNet (Advanced for start/end control)
+  const cnApplyId = String(nextId++);
+  nodes[cnApplyId] = {
+    class_type: "ControlNetApplyAdvanced",
+    inputs: {
+      positive: [posId, 0],
+      negative: [negId, 0],
+      control_net: [cnLoadId, 0],
+      image: [loadGuideId, 0],
+      strength: weight,
+      start_percent: 0.0,
+      end_percent: guidanceEnd,
+    },
+  };
+
+  // Empty latent
+  const latentId = String(nextId++);
+  nodes[latentId] = {
+    class_type: "EmptyLatentImage",
+    inputs: { width: DEFAULTS.width, height: DEFAULTS.height, batch_size: 1 },
+  };
+
+  // KSampler
+  const samplerId = String(nextId++);
+  nodes[samplerId] = {
+    class_type: "KSampler",
+    inputs: {
+      model: modelOut,
+      positive: [cnApplyId, 0],
+      negative: [cnApplyId, 1],
+      latent_image: [latentId, 0],
+      seed,
+      steps: DEFAULTS.steps,
+      cfg: DEFAULTS.cfg,
+      sampler_name: DEFAULTS.sampler,
+      scheduler: DEFAULTS.scheduler,
+      denoise: 1.0,
+    },
+  };
+
+  // VAE Decode
+  const vaeId = String(nextId++);
+  nodes[vaeId] = {
+    class_type: "VAEDecode",
+    inputs: { samples: [samplerId, 0], vae: [ckptId, 2] },
+  };
+
+  // Save
+  const saveId = String(nextId++);
+  nodes[saveId] = {
+    class_type: "SaveImage",
+    inputs: { images: [vaeId, 0], filename_prefix: "cn" },
+  };
+
+  return nodes;
+}
+
+async function comfyHealth() {
+  try {
+    const res = await fetch(`${COMFY_URL}/system_stats`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+const MAX_POLL_MS = 600_000; // 10 minutes
+
+async function submitAndWait(workflow) {
+  const clientId = `cn-${Date.now()}`;
+  const res = await fetch(`${COMFY_URL}/prompt`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ prompt: workflow, client_id: clientId }),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`ComfyUI submit failed: ${res.status} ${text}`);
+  }
+
+  const { prompt_id: promptId } = await res.json();
+
+  const start = Date.now();
+  while (true) {
+    if (Date.now() - start > MAX_POLL_MS) throw new Error(`ComfyUI poll timeout after ${MAX_POLL_MS/1000}s for prompt ${promptId}`);
+    await new Promise((r) => setTimeout(r, 1000));
+    const histRes = await fetch(`${COMFY_URL}/history/${promptId}`);
+    if (!histRes.ok) continue;
+    const history = await histRes.json();
+    const entry = history[promptId];
+    if (!entry) continue;
+    if (entry.status?.completed) return entry;
+    if (entry.status?.status_str === "error") {
+      throw new Error(`ComfyUI error: ${JSON.stringify(entry.status)}`);
+    }
+  }
+}
+
+async function downloadImage(filename, subfolder, type = "output") {
+  const url = `${COMFY_URL}/view?filename=${encodeURIComponent(filename)}&subfolder=${encodeURIComponent(subfolder || "")}&type=${type}`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+async function main() {
+  const opts = parseArgs();
+
+  if (!opts.guidePath) {
+    console.error("Error: --guide <path> is required");
+    process.exit(1);
+  }
+
+  // Resolve prompt
+  let prompt = opts.prompt;
+  let negative = opts.negative;
+
+  if (opts.promptFile && !prompt) {
+    const pf = JSON.parse(await readFile(join(GAME_ROOT, opts.promptFile), "utf-8"));
+    prompt = pf.prompt;
+    negative = negative || pf.negative;
+  }
+
+  if (!prompt) {
+    console.error("Error: --prompt or --prompt-file required");
+    process.exit(1);
+  }
+
+  if (!negative) {
+    negative = "photorealistic, photograph, 3d render, smooth CG, anime, cartoon, text, watermark, blurry, low quality";
+  }
+
+  console.log("\x1b[1mstyle-dataset-lab\x1b[0m ControlNet structural discovery");
+  console.log(`  Subject: ${opts.subject}`);
+  console.log(`  Guide: ${opts.guidePath}`);
+  console.log(`  ControlNet model: ${opts.controlModel}`);
+  console.log(`  Weight: ${opts.weight}, Guidance end: ${opts.guidanceEnd}`);
+  console.log(`  Seeds: ${opts.seeds}`);
+  console.log(`  Steps: ${DEFAULTS.steps}, CFG: ${DEFAULTS.cfg}`);
+  console.log("");
+
+  if (!opts.dryRun) {
+    const online = await comfyHealth();
+    if (!online) {
+      console.error("\x1b[31mError:\x1b[0m ComfyUI not reachable at " + COMFY_URL);
+      process.exit(1);
+    }
+    console.log("\x1b[32m+\x1b[0m ComfyUI online");
+  }
+
+  // The guide image needs to be in ComfyUI's input directory
+  // Copy it there
+  const guideFullPath = join(GAME_ROOT, opts.guidePath);
+  const guideData = await readFile(guideFullPath);
+  const guideFilename = `cn_guide_${opts.subject}.png`;
+
+  if (!opts.dryRun) {
+    // Upload via ComfyUI upload endpoint
+    const formData = new FormData();
+    formData.append("image", new Blob([guideData], { type: "image/png" }), guideFilename);
+    formData.append("overwrite", "true");
+
+    const uploadRes = await fetch(`${COMFY_URL}/upload/image`, {
+      method: "POST",
+      body: formData,
+    });
+
+    if (!uploadRes.ok) {
+      const text = await uploadRes.text();
+      console.error(`Guide upload failed: ${uploadRes.status} ${text}`);
+      process.exit(1);
+    }
+    const uploadResult = await uploadRes.json();
+    console.log(`\x1b[32m+\x1b[0m Guide uploaded: ${uploadResult.name}`);
+  }
+
+  await mkdir(join(GAME_ROOT, "outputs/candidates"), { recursive: true });
+
+  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`;
+
+    console.log(`  [${si + 1}/${opts.seeds}] ${assetId} (seed: ${seed})`);
+
+    if (opts.dryRun) continue;
+
+    const startMs = Date.now();
+    const workflow = buildControlNetWorkflow(
+      prompt, negative, seed,
+      guideFilename, opts.controlModel,
+      opts.weight, opts.guidanceEnd
+    );
+
+    try {
+      const result = await submitAndWait(workflow);
+      const elapsed = Date.now() - startMs;
+
+      const outputs = result.outputs || {};
+      let imageFile = null;
+      let imageSubfolder = "";
+      for (const nodeOut of Object.values(outputs)) {
+        if (nodeOut.images?.length > 0) {
+          imageFile = nodeOut.images[0].filename;
+          imageSubfolder = nodeOut.images[0].subfolder || "";
+          break;
+        }
+      }
+
+      if (!imageFile) {
+        console.log("    \x1b[33m!\x1b[0m No output image");
+        continue;
+      }
+
+      const imgData = await downloadImage(imageFile, imageSubfolder);
+      await writeFile(join(GAME_ROOT, destPath), imgData);
+      console.log(`    \x1b[32m+\x1b[0m ${destPath} (${elapsed}ms, ${imgData.length} bytes)`);
+    } catch (err) {
+      console.log(`    \x1b[31mx\x1b[0m ${err.message}`);
+    }
+  }
+
+  console.log("\n\x1b[32m+\x1b[0m ControlNet discovery complete");
+  if (opts.dryRun) console.log("  (dry run)");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});