@mcptoolshop/style-dataset-lab 3.0.0 → 3.0.1

package/scripts/init.js

@@ -13,6 +13,7 @@ import { mkdir, readdir, readFile, writeFile, copyFile } from 'node:fs/promises'
 import { join, basename } from 'node:path';
 import { existsSync } from 'node:fs';
 import { REPO_ROOT } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 
 const TEMPLATES_DIR = join(REPO_ROOT, 'templates');
 const PROJECTS_DIR = join(REPO_ROOT, 'projects');
@@ -82,15 +83,28 @@ export async function run(argv = process.argv.slice(2)) {
   }
 
   if (!isValidName(projectName)) {
-    throw new Error(
-      `Invalid project name "${projectName}".\n` +
+    throw inputError(
+      'INPUT_BAD_NAME',
+      `Invalid project name "${projectName}".`,
       `Use lowercase letters, numbers, and hyphens (e.g. "my-project").`
     );
   }
 
+  // Validate --domain to prevent path traversal via template lookup.
+  if (!isValidName(domain)) {
+    throw inputError(
+      'INPUT_BAD_DOMAIN',
+      `Invalid --domain "${domain}".`,
+      `Use lowercase letters, numbers, and hyphens (e.g. "character-design").`
+    );
+  }
+
   const projectDir = join(PROJECTS_DIR, projectName);
   if (existsSync(projectDir)) {
-    throw new Error(`Project "${projectName}" already exists at ${projectDir}`);
+    throw inputError(
+      'INPUT_PROJECT_EXISTS',
+      `Project "${projectName}" already exists at ${projectDir}`
+    );
   }
 
   // Resolve domain template source
@@ -99,8 +113,9 @@ export async function run(argv = process.argv.slice(2)) {
     domainDir = join(TEMPLATES_DIR, 'domains', domain);
     if (!existsSync(domainDir)) {
       const domains = await listDomains();
-      throw new Error(
-        `Domain "${domain}" not found.\n` +
+      throw inputError(
+        'INPUT_UNKNOWN_DOMAIN',
+        `Domain "${domain}" not found.`,
         `Available: generic, ${domains.join(', ')}`
       );
     }
@@ -206,18 +221,30 @@ export async function run(argv = process.argv.slice(2)) {
 
   // Copy canon markdown templates
   const canonTemplates = ['constitution.md', 'review-rubric.md'];
+  const wroteCanon = {};
   for (const file of canonTemplates) {
     const src = join(TEMPLATES_DIR, 'canon', file);
     if (existsSync(src)) {
       await copyFile(src, join(projectDir, 'canon', file));
+      wroteCanon[file] = true;
       console.log(`  \x1b[32m✓\x1b[0m canon/${file}`);
     }
   }
 
-  // Copy example prompt pack
-  const examplePack = join(TEMPLATES_DIR, 'inputs', 'prompts', 'example-wave.json');
-  if (existsSync(examplePack)) {
+  // Copy example prompt pack — prefer per-domain example (subjects match domain lane id_patterns),
+  // fall back to legacy global template if it exists (pre-v3.0.1 installs may still ship it).
+  let wroteExamplePack = false;
+  const domainExamplePack = domainDir
+    ? join(domainDir, 'inputs', 'prompts', 'example-wave.json')
+    : null;
+  const globalExamplePack = join(TEMPLATES_DIR, 'inputs', 'prompts', 'example-wave.json');
+  const examplePack =
+    domainExamplePack && existsSync(domainExamplePack) ? domainExamplePack
+    : existsSync(globalExamplePack) ? globalExamplePack
+    : null;
+  if (examplePack) {
     await copyFile(examplePack, join(projectDir, 'inputs', 'prompts', 'example-wave.json'));
+    wroteExamplePack = true;
     console.log(`  \x1b[32m✓\x1b[0m inputs/prompts/example-wave.json`);
   }
 
@@ -236,21 +263,92 @@ export async function run(argv = process.argv.slice(2)) {
     }
   }
 
+  // Write a starter README.md inside the project so users have a home base
+  // with copy-pasteable next commands and a place for their notes.
+  const readmeLines = [
+    `# ${projectName}`,
+    '',
+    `A \`style-dataset-lab\` project — domain: **${domain}**.`,
+    '',
+    '## Quick commands',
+    '',
+    '```bash',
+    `# Validate that the scaffold is healthy`,
+    `sdlab project doctor --project ${projectName}`,
+    '',
+  ];
+  if (wroteExamplePack) {
+    readmeLines.push(
+      `# Generate candidates from the example prompt pack`,
+      `sdlab generate inputs/prompts/example-wave.json --project ${projectName}`,
+      ''
+    );
+  } else {
+    readmeLines.push(
+      `# Generate candidates (add a prompt pack under inputs/prompts/ first)`,
+      `sdlab generate <pack-path> --project ${projectName}`,
+      ''
+    );
+  }
+  readmeLines.push(
+    `# Curate a candidate (approved | rejected | borderline)`,
+    `sdlab curate <asset_id> approved "reads clean" --project ${projectName}`,
+    '',
+    `# Bind approved records to constitution rules`,
+    `sdlab canon-bind --project ${projectName}`,
+    '',
+    `# Create a frozen dataset snapshot`,
+    `sdlab snapshot create --project ${projectName}`,
+    '```',
+    '',
+    '## Project layout',
+    '',
+    '- `project.json` — defaults (checkpoint, width, height, sampler)',
+    '- `constitution.json` — machine-readable style rules',
+    '- `canon/` — human-authored style reference (constitution.md, review-rubric.md)',
+    '- `inputs/prompts/` — generation prompt packs',
+    '- `outputs/candidates/` — raw generated PNGs',
+    '- `outputs/approved/` · `outputs/rejected/` · `outputs/borderline/` — curated outputs',
+    '- `records/` — provenance + judgment records (one JSON per candidate)',
+    '- `snapshots/` · `splits/` · `exports/` — frozen dataset artifacts',
+    '',
+    '## Docs',
+    '',
+    '- Handbook: https://mcp-tool-shop-org.github.io/style-dataset-lab/',
+    '- CLI reference: `sdlab --help` (or `sdlab <cmd> --help` for any command)',
+    '',
+    '## TODO',
+    '',
+    '- [ ] Fill in `canon/constitution.md` with your style rules',
+    '- [ ] Encode those rules in `constitution.json` for canon-bind',
+    '- [ ] Add at least one prompt pack under `inputs/prompts/`',
+    '- [ ] Run `sdlab project doctor` and fix any warnings',
+    ''
+  );
+  await writeFile(join(projectDir, 'README.md'), readmeLines.join('\n'));
+  console.log(`  \x1b[32m✓\x1b[0m README.md`);
+
   console.log('');
   console.log(`\x1b[32m✓\x1b[0m Project "${projectName}" initialized`);
   console.log('');
   console.log('Next steps:');
-  console.log(`  1. Edit ${projectName}/canon/constitution.md — define your visual rules`);
-  console.log(`  2. Edit ${projectName}/constitution.json — encode rules for canon-bind`);
-  console.log(`  3. Create prompt packs in ${projectName}/inputs/prompts/`);
-  console.log(`  4. Run: sdlab generate <pack> --project ${projectName}`);
-  console.log(`  5. Run: sdlab project doctor --project ${projectName}`);
+  let step = 1;
+  if (wroteCanon['constitution.md']) {
+    console.log(`  ${step++}. Edit ${projectName}/canon/constitution.md — define your visual rules`);
+  }
+  console.log(`  ${step++}. Edit ${projectName}/constitution.json — encode rules for canon-bind`);
+  if (wroteExamplePack) {
+    console.log(`  ${step++}. Run: sdlab generate inputs/prompts/example-wave.json --project ${projectName}`);
+  } else {
+    console.log(`  ${step++}. Create prompt packs under ${projectName}/inputs/prompts/`);
+    console.log(`  ${step++}. Run: sdlab generate <pack> --project ${projectName}`);
+  }
+  console.log(`  ${step++}. Run: sdlab project doctor --project ${projectName}`);
+  console.log('');
+  console.log(`See ${projectName}/README.md for the full quick-start.`);
 }
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('init.js') || process.argv[1].endsWith('init'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/painterly.js

@@ -18,8 +18,9 @@
 import { writeFile, mkdir, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
-import { getProjectName } from "../lib/args.js";
-import { REPO_ROOT } from "../lib/paths.js";
+import { getProjectName, parseNumberFlag } from "../lib/args.js";
+import { REPO_ROOT, resolveSafeProjectPath } from "../lib/paths.js";
+import { runtimeError, handleCliError } from "../lib/errors.js";
 import { comfyHealth, submitAndWait, downloadImage, uploadImage } from "../lib/comfyui.js";
 
 // ── Config ──
@@ -156,11 +157,11 @@ export async function run(argv = process.argv.slice(2)) {
 
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === "--source" && argv[i + 1]) sourceDir = argv[++i];
-    if (argv[i] === "--limit" && argv[i + 1]) limit = parseInt(argv[++i]);
-    if (argv[i] === "--offset" && argv[i + 1]) offset = parseInt(argv[++i]);
+    else if (argv[i] === "--limit" && argv[i + 1]) limit = parseNumberFlag('limit', argv[++i], { int: true, min: 1 });
+    else if (argv[i] === "--offset" && argv[i + 1]) offset = parseNumberFlag('offset', argv[++i], { int: true, min: 0 });
   }
 
-  const fullSourceDir = join(GAME_ROOT, sourceDir);
+  const fullSourceDir = resolveSafeProjectPath(GAME_ROOT, sourceDir, { flagName: 'source' });
   const outDir = join(GAME_ROOT, "outputs/painterly");
   await mkdir(outDir, { recursive: true });
 
@@ -195,7 +196,7 @@ export async function run(argv = process.argv.slice(2)) {
   if (!dryRun) {
     const online = await comfyHealth(COMFY_URL);
     if (!online) {
-      throw new Error("ComfyUI not reachable at " + COMFY_URL);
+      throw runtimeError('RUNTIME_COMFY_UNREACHABLE', "ComfyUI not reachable at " + COMFY_URL);
     }
     console.log("\x1b[32m✓\x1b[0m ComfyUI online");
   }
@@ -263,8 +264,5 @@ export async function run(argv = process.argv.slice(2)) {
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('painterly.js') || process.argv[1].endsWith('painterly'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }

package/scripts/refine.js

@@ -11,7 +11,7 @@
 
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot, getRunsDir } from '../lib/paths.js';
 import { loadCritique } from '../lib/critique-engine.js';
 import {
@@ -25,7 +25,7 @@ import { info } from '../lib/log.js';
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       run: { type: 'string' },
       pick: { type: 'string' },
       preserve: { type: 'string' },
@@ -49,7 +49,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const runId = flags.run;
   const pickedFilename = flags.pick;

package/scripts/reingest-selected.js

@@ -8,7 +8,7 @@
  *   sdlab reingest selected --selection selection_2026-04-16_001 --dry-run
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { reingestSelection } from '../lib/reingest-selected.js';
 import { info } from '../lib/log.js';
@@ -16,7 +16,7 @@ import { info } from '../lib/log.js';
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       selection: { type: 'string' },
       'dry-run': { type: 'boolean' },
       json: { type: 'boolean' },
@@ -34,7 +34,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const dryRun = flags['dry-run'] || false;
 

package/scripts/reingest.js

@@ -5,38 +5,51 @@
  *
  * Usage:
  *   sdlab reingest generated --source <dir> --manifest <id> [--dry-run] [--project <name>]
+ *   sdlab reingest selected --selection <id> [--project <name>]
  *   sdlab reingest audit [--project <name>]
  */
 
 import { join } from 'node:path';
-import { getProjectName } from '../lib/args.js';
-import { REPO_ROOT } from '../lib/paths.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { REPO_ROOT, resolveSafeProjectPath } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import { reingestGenerated, auditReingest } from '../lib/reingest.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      source: { type: 'string' },
+      manifest: { type: 'string' },
+      selection: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+    allowUnknown: true, // forward unknowns to delegated 'selected' path
+  });
+
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--')) || 'audit';
-  const args = argv.filter(a => a !== subcommand);
+  const subcommand = positionals[0] || 'audit';
 
   if (subcommand === 'generated') {
-    const sourceIdx = args.indexOf('--source');
-    if (sourceIdx < 0) throw new Error('--source <dir> is required (directory of generated images)');
-    const sourcePath = args[sourceIdx + 1];
-
-    const manifestIdx = args.indexOf('--manifest');
-    if (manifestIdx < 0) throw new Error('--manifest <id> is required (training manifest that produced the outputs)');
-    const manifestId = args[manifestIdx + 1];
+    if (!flags.source) {
+      throw inputError('INPUT_MISSING_FLAG', '--source <dir> is required (directory of generated images)');
+    }
+    if (!flags.manifest) {
+      throw inputError('INPUT_MISSING_FLAG', '--manifest <id> is required (training manifest that produced the outputs)');
+    }
 
-    const dryRun = args.includes('--dry-run');
+    const safeSource = resolveSafeProjectPath(projectRoot, flags.source, { baseRoot: REPO_ROOT, flagName: 'source' });
+    const dryRun = flags['dry-run'] || flags.dryRun;
 
     console.log(`\x1b[1msdlab reingest generated\x1b[0m — ${projectName}`);
-    console.log(`  Source:   ${sourcePath}`);
-    console.log(`  Manifest: ${manifestId}`);
+    console.log(`  Source:   ${flags.source}`);
+    console.log(`  Manifest: ${flags.manifest}`);
     if (dryRun) console.log(`  Mode:     DRY RUN (no records written)`);
     console.log('');
 
-    const result = await reingestGenerated(projectRoot, sourcePath, manifestId, { dryRun });
+    const result = await reingestGenerated(projectRoot, safeSource, flags.manifest, { dryRun });
 
     console.log(`  \x1b[32m✓\x1b[0m Created: ${result.created} records`);
     if (result.skipped > 0) {
@@ -51,9 +64,9 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'selected') {
-    // Delegate to reingest-selected.js
+    // Delegate to reingest-selected.js — pass the full argv so it can re-parse
     const { run: runSelected } = await import('./reingest-selected.js');
-    await runSelected(args);
+    await runSelected(argv.slice(argv.indexOf(subcommand) + 1));
     return;
 
   } else if (subcommand === 'audit') {
@@ -83,10 +96,10 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: generated, selected, audit`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: generated, selected, audit`);
   }
 }
 
 if (process.argv[1] && (process.argv[1].endsWith('reingest.js') || process.argv[1].endsWith('reingest'))) {
-  run().catch((err) => { console.error(err.message || err); process.exit(1); });
+  run().catch(handleCliError);
 }

package/scripts/run-generate.js

@@ -9,7 +9,7 @@
  *   sdlab run generate --brief brief_2026-04-15_001 --project star-freight --seed 42
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName, parseNumberFlag } from '../lib/args.js';
 import { getProjectRoot, getRunsDir } from '../lib/paths.js';
 import { loadCompiledBrief } from '../lib/brief-compiler.js';
 import { executeRun } from '../lib/adapters/comfyui-runner.js';
@@ -20,7 +20,7 @@ import { join } from 'node:path';
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       brief: { type: 'string' },
       seed: { type: 'string' },
       'dry-run': { type: 'boolean' },
@@ -40,7 +40,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
 
   console.log(`\x1b[1mstyle-dataset-lab\x1b[0m run generate`);
@@ -57,7 +57,7 @@ export async function run(argv = process.argv.slice(2)) {
     projectRoot,
     projectName,
     brief,
-    baseSeed: flags.seed ? parseInt(flags.seed, 10) : undefined,
+    baseSeed: flags.seed ? parseNumberFlag('seed', flags.seed, { int: true, min: 0 }) : undefined,
     dryRun: flags['dry-run'] || false,
   });
 

package/scripts/run-list.js

@@ -8,20 +8,20 @@
  *   sdlab run list --project star-freight --json
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { listRuns } from '../lib/runtime-runs.js';
 
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       json: { type: 'boolean' },
     },
     deprecated: { game: 'project' },
   });
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const runs = listRuns(projectRoot);
 

package/scripts/run-show.js

@@ -9,7 +9,7 @@
  *   sdlab run show run_2026-04-16_001 --project star-freight --md
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { loadRun, listRuns } from '../lib/runtime-runs.js';
 import { renderRunText, renderRunMarkdown } from '../lib/run-summary.js';
@@ -17,7 +17,7 @@ import { renderRunText, renderRunMarkdown } from '../lib/run-summary.js';
 export async function run(argv = process.argv.slice(2)) {
   const { positionals, flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       json: { type: 'boolean' },
       md: { type: 'boolean' },
     },
@@ -25,7 +25,7 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   const runId = positionals[0];
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
 
   // No run ID → list runs

package/scripts/select.js

@@ -9,8 +9,9 @@
  *   sdlab select --run run_2026-04-15_001 --approve 001.png --reason "best continuity" --tags portrait,keeper
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import {
   createSelectionFromRun,
   createSelectionFromBatch,
@@ -21,7 +22,7 @@ import { info } from '../lib/log.js';
 export async function run(argv = process.argv.slice(2)) {
   const { flags } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       run: { type: 'string' },
       batch: { type: 'string' },
       approve: { type: 'string' },
@@ -46,7 +47,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const reason = flags.reason || undefined;
   const tags = flags.tags ? flags.tags.split(',').map(t => t.trim()) : undefined;
@@ -71,7 +72,7 @@ export async function run(argv = process.argv.slice(2)) {
     const approvedSlots = pairs.map(pair => {
       const colonIdx = pair.indexOf(':');
       if (colonIdx < 0) {
-        throw new Error(`Invalid batch approve format: "${pair}". Use slot_id:filename`);
+        throw inputError('INPUT_BAD_FORMAT', `Invalid batch approve format: "${pair}". Use slot_id:filename`);
       }
       return {
         slotId: pair.slice(0, colonIdx),

package/scripts/selection-show.js

@@ -9,7 +9,7 @@
  *   sdlab selection show selection_2026-04-16_001 --json
  */
 
-import { parseArgs } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { loadSelection, listSelections, getSelectionsDir } from '../lib/selections.js';
 import { join } from 'node:path';
@@ -18,14 +18,14 @@ import { existsSync, readFileSync } from 'node:fs';
 export async function run(argv = process.argv.slice(2)) {
   const { flags, positionals } = parseArgs(argv, {
     flags: {
-      project: { type: 'string', default: 'star-freight' },
+      project: { type: 'string' },
       selection: { type: 'string' },
       json: { type: 'boolean' },
     },
     deprecated: { game: 'project' },
   });
 
-  const projectName = flags.project;
+  const projectName = flags.project || getProjectName(argv);
   const projectRoot = getProjectRoot(projectName);
   const selectionId = positionals[0] || flags.selection;
 

package/scripts/snapshot.js

@@ -12,30 +12,33 @@
 
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { existsSync } from 'node:fs';
-import { getProjectName } from '../lib/args.js';
+import { parseArgs, getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
 import { loadSelectionProfile } from '../lib/config.js';
+import { inputError, handleCliError } from '../lib/errors.js';
 import { createSnapshot, loadSnapshot, listSnapshots, diffSnapshots } from '../lib/snapshot.js';
-import { evaluateEligibility } from '../lib/eligibility.js';
 import { categorizeExclusions } from '../lib/eligibility.js';
 
 export async function run(argv = process.argv.slice(2)) {
-  const projectName = getProjectName(argv);
-  const projectRoot = join(REPO_ROOT, 'projects', projectName);
-  const subcommand = argv.find(a => !a.startsWith('--')) || 'list';
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      profile: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+  });
 
-  // Strip subcommand from argv for flag parsing
-  const args = argv.filter(a => a !== subcommand);
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const subcommand = positionals[0] || 'list';
+  const dryRun = flags['dry-run'] || flags.dryRun;
 
   if (subcommand === 'create') {
-    const profileIdx = args.indexOf('--profile');
-    const profileId = profileIdx >= 0 ? args[profileIdx + 1] : null;
-    const profile = loadSelectionProfile(projectRoot, profileId);
-    const dryRun = argv.includes('--dry-run');
+    const profile = loadSelectionProfile(projectRoot, flags.profile);
 
     console.log(`\x1b[1msdlab snapshot create\x1b[0m — ${projectName}`);
-    console.log(`  Profile: ${profileId || 'training-default (built-in)'}`);
+    console.log(`  Profile: ${flags.profile || 'training-default (built-in)'}`);
     if (dryRun) console.log('  Mode: DRY RUN (no files written)');
     console.log('');
 
@@ -46,7 +49,6 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(`  Excluded: ${result.excluded}`);
 
     if (!dryRun) {
-      // Read and display summary
       const summary = JSON.parse(
         await readFile(join(projectRoot, 'snapshots', result.snapshotId, 'summary.json'), 'utf-8')
       );
@@ -59,7 +61,6 @@ export async function run(argv = process.argv.slice(2)) {
         console.log(`    ${f}: ${c}`);
       }
 
-      // Read and categorize exclusions
       const excludedRaw = await readFile(
         join(projectRoot, 'snapshots', result.snapshotId, 'excluded.jsonl'), 'utf-8'
       );
@@ -83,8 +84,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'show') {
-    const snapshotId = args.find(a => a.startsWith('snap-'));
-    if (!snapshotId) throw new Error('Usage: sdlab snapshot show <snapshot-id>');
+    const snapshotId = positionals[1] || positionals.find(a => a.startsWith('snap-'));
+    if (!snapshotId) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab snapshot show <snapshot-id>');
 
     const manifest = await loadSnapshot(projectRoot, snapshotId);
     console.log(`\x1b[1mSnapshot\x1b[0m — ${snapshotId}\n`);
@@ -102,8 +103,8 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else if (subcommand === 'diff') {
-    const snapIds = args.filter(a => a.startsWith('snap-'));
-    if (snapIds.length < 2) throw new Error('Usage: sdlab snapshot diff <id-a> <id-b>');
+    const snapIds = positionals.slice(1).filter(a => a.startsWith('snap-'));
+    if (snapIds.length < 2) throw inputError('INPUT_MISSING_ARGS', 'Usage: sdlab snapshot diff <id-a> <id-b>');
 
     const diff = await diffSnapshots(projectRoot, snapIds[0], snapIds[1]);
     console.log(`\x1b[1mSnapshot diff\x1b[0m — ${snapIds[0]} vs ${snapIds[1]}\n`);
@@ -123,14 +124,11 @@ export async function run(argv = process.argv.slice(2)) {
     }
 
   } else {
-    throw new Error(`Unknown subcommand: ${subcommand}. Use: create, list, show, diff`);
+    throw inputError('INPUT_BAD_SUBCOMMAND', `Unknown subcommand: ${subcommand}. Use: create, list, show, diff`);
   }
 }
 
 // Direct execution guard
 if (process.argv[1] && (process.argv[1].endsWith('snapshot.js') || process.argv[1].endsWith('snapshot'))) {
-  run().catch((err) => {
-    console.error(err.message || err);
-    process.exit(1);
-  });
+  run().catch(handleCliError);
 }