@mcptoolshop/style-dataset-lab 2.2.1 → 3.0.0

package/lib/runtime-runs.js

@@ -0,0 +1,168 @@
+/**
+ * Runtime run management — create, load, list run artifacts.
+ *
+ * A run is a frozen execution artifact: brief + seeds + outputs + manifest.
+ * The run folder IS the review surface — humans open it directly.
+ */
+
+import { readFile, writeFile, mkdir, readdir, copyFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { getRunsDir, getBriefsDir } from './paths.js';
+import { inputError } from './errors.js';
+
+// ─── Run ID generation ───────────────────────────────────────────
+
+/**
+ * Generate a run ID: run_YYYY-MM-DD_NNN
+ */
+export function generateRunId(runsDir) {
+  const today = new Date().toISOString().slice(0, 10);
+  const prefix = `run_${today}_`;
+
+  let maxSeq = 0;
+  if (existsSync(runsDir)) {
+    const existing = readdirSync(runsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name.startsWith(prefix));
+    for (const e of existing) {
+      const seqStr = e.name.slice(prefix.length);
+      const seq = parseInt(seqStr, 10);
+      if (!isNaN(seq) && seq > maxSeq) maxSeq = seq;
+    }
+  }
+
+  const seq = String(maxSeq + 1).padStart(3, '0');
+  return `${prefix}${seq}`;
+}
+
+// ─── Seed planning ───────────────────────────────────────────────
+
+/**
+ * Build a deterministic seed plan.
+ * @param {Object} opts
+ * @param {'fixed'|'increment'|'random'} opts.seedMode
+ * @param {number} opts.outputCount
+ * @param {number} [opts.baseSeed] — explicit base seed (default: random)
+ * @returns {{ base_seed: number, seeds: number[] }}
+ */
+export function buildSeedPlan({ seedMode, outputCount, baseSeed }) {
+  const base = baseSeed ?? Math.floor(Math.random() * 2_147_483_647);
+  const seeds = [];
+
+  switch (seedMode) {
+    case 'fixed':
+      for (let i = 0; i < outputCount; i++) seeds.push(base);
+      break;
+    case 'increment':
+      for (let i = 0; i < outputCount; i++) seeds.push(base + i);
+      break;
+    case 'random':
+      seeds.push(base);
+      for (let i = 1; i < outputCount; i++) {
+        seeds.push(Math.floor(Math.random() * 2_147_483_647));
+      }
+      break;
+    default:
+      // Default to increment
+      for (let i = 0; i < outputCount; i++) seeds.push(base + i);
+  }
+
+  return { base_seed: base, seeds };
+}
+
+// ─── Run directory setup ─────────────────────────────────────────
+
+/**
+ * Prepare a run directory and copy brief artifacts into it.
+ * @returns {{ runId: string, runDir: string }}
+ */
+export async function prepareRunDir(projectRoot, brief) {
+  const runsDir = getRunsDir(projectRoot);
+  const runId = generateRunId(runsDir);
+  const runDir = join(runsDir, runId);
+
+  await mkdir(join(runDir, 'outputs'), { recursive: true });
+
+  // Copy brief artifacts
+  const briefsDir = getBriefsDir(projectRoot);
+  const briefJsonSrc = join(briefsDir, `${brief.brief_id}.json`);
+  const briefMdSrc = join(briefsDir, `${brief.brief_id}.md`);
+
+  await writeFile(join(runDir, 'brief.json'), JSON.stringify(brief, null, 2) + '\n');
+
+  if (existsSync(briefMdSrc)) {
+    await copyFile(briefMdSrc, join(runDir, 'brief.md'));
+  }
+
+  // Write standalone prompt/negative files for easy inspection
+  await writeFile(join(runDir, 'prompt.txt'), brief.prompt || '');
+  await writeFile(join(runDir, 'negative-prompt.txt'), brief.negative_prompt || '');
+
+  return { runId, runDir };
+}
+
+// ─── Manifest ────────────────────────────────────────────────────
+
+/**
+ * Build and save a run manifest.
+ */
+export async function saveRunManifest(runDir, manifest) {
+  await writeFile(
+    join(runDir, 'manifest.json'),
+    JSON.stringify(manifest, null, 2) + '\n'
+  );
+}
+
+// ─── Load / List ─────────────────────────────────────────────────
+
+/**
+ * Load a run manifest by ID.
+ */
+export async function loadRun(projectRoot, runId) {
+  const runDir = join(getRunsDir(projectRoot), runId);
+  const manifestPath = join(runDir, 'manifest.json');
+
+  if (!existsSync(manifestPath)) {
+    throw inputError(
+      'RUN_NOT_FOUND',
+      `Run "${runId}" not found`,
+      `Check the run ID or run: sdlab run generate --brief <id>`
+    );
+  }
+
+  return JSON.parse(await readFile(manifestPath, 'utf-8'));
+}
+
+/**
+ * List all runs in a project.
+ */
+export function listRuns(projectRoot) {
+  const runsDir = getRunsDir(projectRoot);
+  if (!existsSync(runsDir)) return [];
+
+  const entries = readdirSync(runsDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && e.name.startsWith('run_'))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const runs = [];
+  for (const entry of entries) {
+    const manifestPath = join(runsDir, entry.name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      runs.push({
+        run_id: manifest.run_id,
+        brief_id: manifest.brief_id,
+        workflow_template_id: manifest.workflow_template_id,
+        output_count: manifest.output_count,
+        created_at: manifest.created_at,
+        adapter_target: manifest.adapter_target,
+      });
+    } catch {
+      // Skip malformed
+    }
+  }
+
+  return runs;
+}

package/lib/selections.js

@@ -0,0 +1,323 @@
+/**
+ * Selection engine — approve outputs from runs or batches into
+ * durable selection artifacts.
+ *
+ * A selection is a creative decision: what was chosen, why, and
+ * where it came from. Re-ingest consumes selections; this module
+ * only builds and stores the artifact.
+ */
+
+import { readFileSync, existsSync, readdirSync, mkdirSync, copyFileSync } from 'node:fs';
+import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { getRunsDir } from './paths.js';
+import { getBatchesDir } from './batch-runs.js';
+import { inputError } from './errors.js';
+
+// ─── Selection ID generation ─────────────────────────────────────
+
+export function getSelectionsDir(projectRoot) {
+  return join(projectRoot, 'selections');
+}
+
+export function generateSelectionId(selectionsDir) {
+  const today = new Date().toISOString().slice(0, 10);
+  const prefix = `selection_${today}_`;
+
+  let maxSeq = 0;
+  if (existsSync(selectionsDir)) {
+    const existing = readdirSync(selectionsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name.startsWith(prefix));
+    for (const e of existing) {
+      const seqStr = e.name.slice(prefix.length);
+      const seq = parseInt(seqStr, 10);
+      if (!isNaN(seq) && seq > maxSeq) maxSeq = seq;
+    }
+  }
+
+  return `${prefix}${String(maxSeq + 1).padStart(3, '0')}`;
+}
+
+// ─── Run selection ───────────────────────────────────────────────
+
+/**
+ * Create a selection from a single run.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.projectId
+ * @param {string} opts.runId
+ * @param {string[]} opts.approvedFiles — filenames to approve (e.g. ['001.png', '003.png'])
+ * @param {string} [opts.reason]
+ * @param {string[]} [opts.tags]
+ * @returns {Promise<Object>} selection manifest
+ */
+export async function createSelectionFromRun({
+  projectRoot, projectId, runId, approvedFiles, reason, tags,
+}) {
+  const runsDir = getRunsDir(projectRoot);
+  const runDir = join(runsDir, runId);
+  const manifestPath = join(runDir, 'manifest.json');
+
+  if (!existsSync(manifestPath)) {
+    throw inputError('RUN_NOT_FOUND', `Run "${runId}" not found`, 'Check the run ID.');
+  }
+
+  const runManifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  const outputsDir = join(runDir, 'outputs');
+
+  // Validate all approved files exist
+  for (const file of approvedFiles) {
+    if (!existsSync(join(outputsDir, file))) {
+      throw inputError(
+        'OUTPUT_NOT_FOUND',
+        `Output "${file}" not found in ${runId}/outputs/`,
+        `Available: ${readdirSync(outputsDir).filter(f => f.endsWith('.png')).join(', ') || '(none)'}`,
+      );
+    }
+  }
+
+  // Create selection directory
+  const selectionsDir = getSelectionsDir(projectRoot);
+  const selectionId = generateSelectionId(selectionsDir);
+  const selectionDir = join(selectionsDir, selectionId);
+  await mkdir(join(selectionDir, 'chosen'), { recursive: true });
+
+  // Copy chosen files
+  const items = [];
+  for (let i = 0; i < approvedFiles.length; i++) {
+    const file = approvedFiles[i];
+    const destName = `sel_${String(i + 1).padStart(3, '0')}.png`;
+    copyFileSync(join(outputsDir, file), join(selectionDir, 'chosen', destName));
+
+    // Find seed from run manifest
+    const outputEntry = runManifest.outputs?.find(o => o.filename === file);
+    items.push({
+      slot_or_output: file,
+      filename: destName,
+      seed: outputEntry?.seed,
+      reason: reason || 'selected',
+      tags: tags || [],
+    });
+  }
+
+  // Build selection manifest
+  const manifest = {
+    selection_id: selectionId,
+    project_id: projectId,
+    source_type: 'run',
+    source_id: runId,
+    workflow_id: runManifest.workflow_template_id,
+    created_at: new Date().toISOString(),
+    items,
+    reingest_ready: true,
+  };
+
+  // Attach subject from brief if available
+  const briefPath = join(runDir, 'brief.json');
+  if (existsSync(briefPath)) {
+    try {
+      const brief = JSON.parse(readFileSync(briefPath, 'utf-8'));
+      if (brief.subject_id) manifest.subject_id = brief.subject_id;
+    } catch { /* skip */ }
+  }
+
+  return { selectionId, selectionDir, manifest, runManifest };
+}
+
+// ─── Batch selection ─────────────────────────────────────────────
+
+/**
+ * Create a selection from a batch.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.projectId
+ * @param {string} opts.batchId
+ * @param {Array<{slotId: string, filename: string}>} opts.approvedSlots
+ * @param {string} [opts.reason]
+ * @param {string[]} [opts.tags]
+ * @returns {Promise<Object>} selection manifest
+ */
+export async function createSelectionFromBatch({
+  projectRoot, projectId, batchId, approvedSlots, reason, tags,
+}) {
+  const batchesDir = getBatchesDir(projectRoot);
+  const batchDir = join(batchesDir, batchId);
+  const batchManifestPath = join(batchDir, 'manifest.json');
+
+  if (!existsSync(batchManifestPath)) {
+    throw inputError('BATCH_NOT_FOUND', `Batch "${batchId}" not found`, 'Check the batch ID.');
+  }
+
+  const batchManifest = JSON.parse(readFileSync(batchManifestPath, 'utf-8'));
+  const runsDir = getRunsDir(projectRoot);
+
+  // Build slot → run lookup
+  const slotRunMap = new Map();
+  for (const slot of batchManifest.slots || []) {
+    slotRunMap.set(slot.slot_id, slot);
+  }
+
+  // Validate each approved slot
+  const runManifests = new Map();
+  for (const { slotId, filename } of approvedSlots) {
+    const slot = slotRunMap.get(slotId);
+    if (!slot) {
+      throw inputError(
+        'SLOT_NOT_FOUND',
+        `Slot "${slotId}" not found in batch ${batchId}`,
+        `Available: ${[...slotRunMap.keys()].join(', ')}`,
+      );
+    }
+
+    const runDir = join(runsDir, slot.run_id);
+    const outputPath = join(runDir, 'outputs', filename);
+    if (!existsSync(outputPath)) {
+      throw inputError(
+        'OUTPUT_NOT_FOUND',
+        `Output "${filename}" not found in ${slot.run_id}/outputs/`,
+        `Check the filename.`,
+      );
+    }
+
+    // Cache run manifests
+    if (!runManifests.has(slot.run_id)) {
+      const rmPath = join(runDir, 'manifest.json');
+      if (existsSync(rmPath)) {
+        runManifests.set(slot.run_id, JSON.parse(readFileSync(rmPath, 'utf-8')));
+      }
+    }
+  }
+
+  // Create selection directory
+  const selectionsDir = getSelectionsDir(projectRoot);
+  const selectionId = generateSelectionId(selectionsDir);
+  const selectionDir = join(selectionsDir, selectionId);
+  await mkdir(join(selectionDir, 'chosen'), { recursive: true });
+
+  // Copy chosen files and build items
+  const items = [];
+  for (let i = 0; i < approvedSlots.length; i++) {
+    const { slotId, filename } = approvedSlots[i];
+    const slot = slotRunMap.get(slotId);
+    const runDir = join(runsDir, slot.run_id);
+    const destName = `sel_${String(i + 1).padStart(3, '0')}.png`;
+
+    copyFileSync(join(runDir, 'outputs', filename), join(selectionDir, 'chosen', destName));
+
+    const rm = runManifests.get(slot.run_id);
+    const outputEntry = rm?.outputs?.find(o => o.filename === filename);
+
+    items.push({
+      slot_or_output: `${slotId}:${filename}`,
+      filename: destName,
+      seed: outputEntry?.seed,
+      reason: reason || `selected from slot ${slot.label || slotId}`,
+      tags: tags || [],
+    });
+  }
+
+  const manifest = {
+    selection_id: selectionId,
+    project_id: projectId,
+    source_type: 'batch',
+    source_id: batchId,
+    workflow_id: batchManifest.mode_id,
+    created_at: new Date().toISOString(),
+    items,
+    reingest_ready: true,
+  };
+
+  if (batchManifest.subject_id) manifest.subject_id = batchManifest.subject_id;
+
+  return { selectionId, selectionDir, manifest, batchManifest, runManifests };
+}
+
+// ─── Save / Load / List ──────────────────────────────────────────
+
+/**
+ * Save a selection manifest + summary to disk.
+ */
+export async function saveSelection(selectionDir, manifest) {
+  await writeFile(
+    join(selectionDir, 'manifest.json'),
+    JSON.stringify(manifest, null, 2) + '\n',
+  );
+
+  // Summary JSON
+  await writeFile(
+    join(selectionDir, 'summary.json'),
+    JSON.stringify({
+      selection_id: manifest.selection_id,
+      source_type: manifest.source_type,
+      source_id: manifest.source_id,
+      workflow_id: manifest.workflow_id,
+      subject_id: manifest.subject_id,
+      items: manifest.items.length,
+      reingest_ready: manifest.reingest_ready,
+      created_at: manifest.created_at,
+    }, null, 2) + '\n',
+  );
+
+  // Summary markdown
+  const lines = [
+    `# Selection: ${manifest.selection_id}`,
+    '',
+    `**Source:** ${manifest.source_type} \`${manifest.source_id}\``,
+    `**Workflow:** ${manifest.workflow_id || '—'}`,
+  ];
+  if (manifest.subject_id) lines.push(`**Subject:** ${manifest.subject_id}`);
+  lines.push(`**Created:** ${manifest.created_at}`);
+  lines.push(`**Re-ingest ready:** ${manifest.reingest_ready ? 'yes' : 'no'}`);
+  lines.push('');
+  lines.push('## Chosen outputs');
+  lines.push('');
+  lines.push('| # | Source | File | Seed | Reason |');
+  lines.push('|---|--------|------|------|--------|');
+  for (let i = 0; i < manifest.items.length; i++) {
+    const item = manifest.items[i];
+    lines.push(
+      `| ${i + 1} | ${item.slot_or_output} | ${item.filename} | ${item.seed ?? '—'} | ${item.reason} |`,
+    );
+  }
+  lines.push('');
+  if (manifest.items.some(it => it.tags?.length)) {
+    lines.push('## Tags');
+    for (const item of manifest.items) {
+      if (item.tags?.length) {
+        lines.push(`- ${item.filename}: ${item.tags.join(', ')}`);
+      }
+    }
+    lines.push('');
+  }
+  await writeFile(join(selectionDir, 'summary.md'), lines.join('\n'));
+}
+
+/**
+ * Load a selection manifest by ID.
+ */
+export function loadSelection(projectRoot, selectionId) {
+  const selectionDir = join(getSelectionsDir(projectRoot), selectionId);
+  const manifestPath = join(selectionDir, 'manifest.json');
+  if (!existsSync(manifestPath)) {
+    throw inputError(
+      'SELECTION_NOT_FOUND',
+      `Selection "${selectionId}" not found`,
+      'Check the selection ID or run: sdlab select --run <id> --approve <files>',
+    );
+  }
+  return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+}
+
+/**
+ * List all selections in a project.
+ */
+export function listSelections(projectRoot) {
+  const dir = getSelectionsDir(projectRoot);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && e.name.startsWith('selection_'))
+    .map(e => e.name)
+    .sort();
+}

package/lib/snapshot.js

@@ -53,7 +53,7 @@ export function computeConfigFingerprint(projectRoot) {
  * @param {Object} profile — selection profile
  * @returns {Promise<{snapshotId: string, included: number, excluded: number}>}
  */
-export async function createSnapshot(projectRoot, profile) {
+export async function createSnapshot(projectRoot, profile, options = {}) {
   const config = loadProjectConfig(projectRoot);
   const recordsDir = join(projectRoot, 'records');
   const snapshotId = generateSnapshotId();
@@ -104,7 +104,10 @@ export async function createSnapshot(projectRoot, profile) {
     }
   }
 
-  // Write snapshot files
+  // Write snapshot files (skip if dry run)
+  if (options.dryRun) {
+    return { snapshotId, included: included.length, excluded: excluded.length };
+  }
   await mkdir(snapshotDir, { recursive: true });
 
   const manifest = {

package/lib/split.js

@@ -127,7 +127,7 @@ function buildAncestorMap(records) {
  * @param {Object} profile — split profile (from loadSplitProfile)
  * @returns {Promise<{splitId: string, train: number, val: number, test: number}>}
  */
-export async function createSplit(projectRoot, snapshotId, profile) {
+export async function createSplit(projectRoot, snapshotId, profile, options = {}) {
   const config = loadProjectConfig(projectRoot);
   const snapshot = await loadSnapshot(projectRoot, snapshotId);
   const includedEntries = await loadSnapshotIncluded(projectRoot, snapshotId);
@@ -242,8 +242,11 @@ export async function createSplit(projectRoot, snapshotId, profile) {
     records, trainRecords, valRecords, testRecords, config.lanes
   );
 
-  // Write output
+  // Write output (skip if dry run)
   const splitId = generateSplitId();
+  if (options.dryRun) {
+    return { splitId, train: trainRecords.length, val: valRecords.length, test: testRecords.length };
+  }
   const splitDir = join(projectRoot, 'splits', splitId);
   await mkdir(splitDir, { recursive: true });
 

package/lib/workflow-profiles.js

@@ -0,0 +1,161 @@
+/**
+ * Workflow profile management.
+ *
+ * A workflow profile is a production recipe — it defines how to generate
+ * a specific kind of output set (portrait pack, expression sheet, moodboard, etc.)
+ * using project canon and trained assets.
+ *
+ * Workflow profiles are NOT training profiles. They drive generation, not training.
+ */
+
+import { readFile, readdir, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { getWorkflowProfilesDir } from './paths.js';
+
+const REQUIRED_FIELDS = [
+  'workflow_id', 'label', 'lane_id', 'output_mode', 'output_count',
+  'prompt_strategy', 'negative_strategy', 'canon_focus', 'drift_guards',
+  'runtime_defaults',
+];
+
+const VALID_SUBJECT_MODES = ['required', 'optional', 'forbidden'];
+
+const VALID_OUTPUT_MODES = [
+  'portrait_set', 'expression_sheet', 'variant_pack',
+  'moodboard', 'silhouette_sheet', 'turnaround',
+];
+
+const VALID_CANON_FOCUS = [
+  'silhouette', 'material_language', 'palette', 'anatomy',
+  'costume_logic', 'era_logic', 'scale_logic', 'lighting',
+  'surface_wear', 'gesture', 'composition', 'faction_read',
+];
+
+/**
+ * Validate a workflow profile object.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateWorkflowProfile(profile) {
+  const errors = [];
+
+  for (const field of REQUIRED_FIELDS) {
+    if (profile[field] === undefined || profile[field] === null) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+
+  if (profile.subject_mode && !VALID_SUBJECT_MODES.includes(profile.subject_mode)) {
+    errors.push(`invalid subject_mode "${profile.subject_mode}" — must be one of: ${VALID_SUBJECT_MODES.join(', ')}`);
+  }
+
+  if (profile.output_mode && !VALID_OUTPUT_MODES.includes(profile.output_mode)) {
+    errors.push(`invalid output_mode "${profile.output_mode}" — must be one of: ${VALID_OUTPUT_MODES.join(', ')}`);
+  }
+
+  if (!Number.isInteger(profile.output_count) || profile.output_count < 1) {
+    errors.push('output_count must be a positive integer');
+  }
+
+  // Prompt strategy structure
+  const ps = profile.prompt_strategy;
+  if (ps) {
+    if (!Array.isArray(ps.style_prefix)) errors.push('prompt_strategy.style_prefix must be an array');
+    if (typeof ps.structure !== 'string') errors.push('prompt_strategy.structure must be a string');
+    if (!Array.isArray(ps.must_include)) errors.push('prompt_strategy.must_include must be an array');
+  }
+
+  // Negative strategy structure
+  const ns = profile.negative_strategy;
+  if (ns) {
+    if (!Array.isArray(ns.must_avoid)) errors.push('negative_strategy.must_avoid must be an array');
+  }
+
+  // Canon focus items
+  if (Array.isArray(profile.canon_focus)) {
+    for (const item of profile.canon_focus) {
+      if (!VALID_CANON_FOCUS.includes(item)) {
+        errors.push(`invalid canon_focus item "${item}" — must be one of: ${VALID_CANON_FOCUS.join(', ')}`);
+      }
+    }
+  } else if (profile.canon_focus !== undefined) {
+    errors.push('canon_focus must be an array');
+  }
+
+  if (profile.drift_guards && !Array.isArray(profile.drift_guards)) {
+    errors.push('drift_guards must be an array');
+  }
+
+  // Runtime defaults
+  const rd = profile.runtime_defaults;
+  if (rd) {
+    if (!rd.adapter_target) errors.push('runtime_defaults.adapter_target is required');
+    if (rd.seed_mode && !['fixed', 'increment', 'random'].includes(rd.seed_mode)) {
+      errors.push(`invalid runtime_defaults.seed_mode "${rd.seed_mode}" — must be fixed, increment, or random`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Load a single workflow profile by ID.
+ */
+export async function getWorkflowProfile(projectRoot, workflowId) {
+  const dir = getWorkflowProfilesDir(projectRoot);
+  const path = join(dir, `${workflowId}.json`);
+  if (!existsSync(path)) {
+    throw new Error(`Workflow profile "${workflowId}" not found at ${path}`);
+  }
+  const data = JSON.parse(await readFile(path, 'utf-8'));
+  const { valid, errors } = validateWorkflowProfile(data);
+  if (!valid) {
+    throw new Error(`Workflow profile "${workflowId}" is invalid:\n  ${errors.join('\n  ')}`);
+  }
+  return data;
+}
+
+/**
+ * List all workflow profiles in a project.
+ */
+export async function listWorkflowProfiles(projectRoot) {
+  const dir = getWorkflowProfilesDir(projectRoot);
+  if (!existsSync(dir)) return [];
+
+  const files = (await readdir(dir)).filter(f => f.endsWith('.json')).sort();
+  const profiles = [];
+
+  for (const file of files) {
+    try {
+      const data = JSON.parse(await readFile(join(dir, file), 'utf-8'));
+      profiles.push({
+        workflow_id: data.workflow_id,
+        label: data.label,
+        lane_id: data.lane_id,
+        subject_mode: data.subject_mode || 'optional',
+        output_mode: data.output_mode,
+        output_count: data.output_count,
+      });
+    } catch {
+      // Skip malformed
+    }
+  }
+
+  return profiles;
+}
+
+/**
+ * Save a workflow profile to a project.
+ */
+export async function saveWorkflowProfile(projectRoot, profile) {
+  const { valid, errors } = validateWorkflowProfile(profile);
+  if (!valid) {
+    throw new Error(`Invalid workflow profile:\n  ${errors.join('\n  ')}`);
+  }
+  const dir = getWorkflowProfilesDir(projectRoot);
+  await mkdir(dir, { recursive: true });
+  await writeFile(
+    join(dir, `${profile.workflow_id}.json`),
+    JSON.stringify(profile, null, 2) + '\n'
+  );
+}