@stacksjs/defaults 0.74.40 → 0.74.42

package/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env bun
 
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { runtimeArgs } from '../renderers/shared/bun-runtime.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const skillRoot = path.resolve(__dirname, '..');
@@ -13,13 +15,21 @@ const TYPES = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'life
 
 function usage() {
   return `Usage:
-  technical-diagrams render <type> <input.json> [output.html]
-  technical-diagrams validate <type> <input.json> [--json] [--layout-json]
-  technical-diagrams inspect <type> <input.json>
-  technical-diagrams check <output.html>
-  technical-diagrams examples [output-directory]
-  technical-diagrams doctor
-  technical-diagrams demo [output-directory]
+  diagrams render <type> <input.json> [output.html] [--quality standard|showcase] [--repo-root path (architecture only)]
+  diagrams compare architecture <base.json> <head.json> [output.html] [--receipt path] [--json] [--quality standard|showcase] [--repo-root path]
+  diagrams deliver <type> <input.json> [output.html] [--json] [--open] [--quality standard|showcase] [--repo-root path (architecture only)]
+  diagrams preview <type> <input.json> [output.html] [--no-open] [--quality standard|showcase] [--repo-root path (architecture only)]
+  diagrams validate <type> <input.json> [--json] [--layout-json] [--quality standard|showcase] [--repo-root path (architecture only)]
+  diagrams migrate workflow <old.json> <new.json> --to-schema 2 [--json]
+  diagrams inspect <type> <input.json>
+  diagrams check <output.html>
+  diagrams visual-check <output.html> [--json]
+  diagrams guide [scenario or question] [--json] [--lang en|zh]
+  diagrams brands [name, alias, domain, or category] [--json]
+  diagrams brands capture <url> [--json]
+  diagrams examples [output-directory]
+  diagrams doctor
+  diagrams demo [output-directory]
 
 Types:
   architecture, workflow, sequence, dataflow, lifecycle
@@ -31,62 +41,1266 @@ function fail(message, code = 2) {
   process.exit(code);
 }
 
+function rejectCliArgument(message, details = {}) {
+  const error = new Error(message);
+  error.archifyArgument = {
+    code: details.code || 'cli/invalid-arguments',
+    subject: details.subject || {},
+    evidence: details.evidence || {},
+    supportedFixes: details.supportedFixes || ['correct the command arguments and retry'],
+  };
+  throw error;
+}
+
 function rendererPath(type) {
   if (!TYPES.has(type)) {
-    fail(`Unknown diagram type "${type}". Expected one of: ${[...TYPES].join(', ')}`);
+    rejectCliArgument(`Unknown diagram type "${type}". Expected one of: ${[...TYPES].join(', ')}`, {
+      code: 'cli/unknown-diagram-type',
+      subject: { type },
+      evidence: { supportedTypes: [...TYPES] },
+      supportedFixes: [`use one of: ${[...TYPES].join(', ')}`],
+    });
   }
   return path.join(skillRoot, 'renderers', type, `render-${type}.mjs`);
 }
 
-function runRuntime(args, options = {}) {
-  return spawnSync(process.execPath, [
-    `--config=${path.join(skillRoot, 'bunfig.toml')}`,
-    '--no-env-file',
-    ...args,
-  ], {
+function runNode(args, options = {}) {
+  return spawnSync(process.execPath, runtimeArgs(args), {
     cwd: options.cwd || process.cwd(),
     encoding: 'utf8',
     stdio: options.stdio || 'inherit',
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+  });
+}
+
+function extractQualityArgs(args) {
+  const rest = [];
+  let quality;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--quality') {
+      quality = args[index + 1];
+      if (!quality || quality.startsWith('--')) rejectCliArgument('--quality requires standard or showcase.', {
+        code: 'cli/missing-option-value',
+        subject: { option: '--quality' },
+        supportedFixes: ['provide --quality standard or --quality showcase'],
+      });
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--quality=')) {
+      quality = arg.slice('--quality='.length);
+      if (!quality) rejectCliArgument('--quality requires standard or showcase.', {
+        code: 'cli/missing-option-value',
+        subject: { option: '--quality' },
+        supportedFixes: ['provide --quality standard or --quality showcase'],
+      });
+      continue;
+    }
+    rest.push(arg);
+  }
+  if (quality !== undefined && !['standard', 'showcase'].includes(quality)) {
+    rejectCliArgument(`Unknown quality profile "${quality}". Expected standard or showcase.`, {
+      code: 'cli/invalid-option-value',
+      subject: { option: '--quality' },
+      evidence: { value: quality, supportedValues: ['standard', 'showcase'] },
+      supportedFixes: ['use --quality standard or --quality showcase'],
+    });
+  }
+  return { rest, quality };
+}
+
+function extractRepoRootArgs(args) {
+  const rest = [];
+  let repoRoot;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--repo-root') {
+      repoRoot = args[index + 1];
+      if (!repoRoot || repoRoot.startsWith('--')) rejectCliArgument('--repo-root requires a repository path.', {
+        code: 'cli/missing-option-value',
+        subject: { option: '--repo-root' },
+        supportedFixes: ['provide one repository path after --repo-root'],
+      });
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--repo-root=')) {
+      repoRoot = arg.slice('--repo-root='.length);
+      if (!repoRoot) rejectCliArgument('--repo-root requires a repository path.', {
+        code: 'cli/missing-option-value',
+        subject: { option: '--repo-root' },
+        supportedFixes: ['provide one repository path after --repo-root'],
+      });
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { rest, repoRoot: repoRoot ? path.resolve(repoRoot) : undefined };
+}
+
+function rendererEnv(quality, repoRoot, diagnosticJson = false) {
+  return {
+    ...(quality ? { ARCHIFY_QUALITY_PROFILE: quality } : {}),
+    ...(repoRoot ? { ARCHIFY_REPO_ROOT: repoRoot } : {}),
+    ...(diagnosticJson ? { ARCHIFY_DIAGNOSTIC_FORMAT: 'json' } : {}),
+  };
+}
+
+function diagnostic({ code, message, subject = {}, evidence = {}, supportedFixes = [], severity = 'error' }) {
+  return {
+    code,
+    severity,
+    message,
+    subject,
+    evidence,
+    supportedFixes,
+  };
+}
+
+function inputDiagnostic(error, inputPath) {
+  const isSyntax = error instanceof SyntaxError;
+  return diagnostic({
+    code: isSyntax ? 'input/json-parse' : 'input/read',
+    message: isSyntax
+      ? `Input JSON could not be parsed: ${error.message}`
+      : `Input could not be read: ${error.message}`,
+    subject: { input: inputPath },
+    evidence: {
+      ...(error?.code ? { systemCode: error.code } : {}),
+      reason: error.message,
+    },
+    supportedFixes: [isSyntax
+      ? 'repair the JSON syntax and run validation again'
+      : 'provide one readable JSON input file'],
   });
 }
 
+function rendererFailure(result) {
+  if (result.error) {
+    return {
+      error: 'Renderer process could not start.',
+      diagnostics: [diagnostic({
+        code: 'internal/renderer-process',
+        message: 'Renderer process could not start.',
+        evidence: { reason: result.error.message },
+      })],
+    };
+  }
+  try {
+    const payload = JSON.parse((result.stderr || '').trim());
+    if (payload?.ok === false && Array.isArray(payload.diagnostics) && payload.diagnostics.length) {
+      return {
+        error: payload.error || payload.diagnostics[0].message,
+        diagnostics: payload.diagnostics,
+      };
+    }
+  } catch {
+    // The diagnostic boundary is intentionally fail-closed. Never copy a raw
+    // Node stack into a machine receipt when a renderer exits unexpectedly.
+  }
+  return {
+    error: 'Renderer failed before emitting a structured diagnostic.',
+    diagnostics: [diagnostic({
+      code: 'internal/unclassified',
+      message: 'Renderer failed before emitting a structured diagnostic.',
+      evidence: { exitCode: result.status ?? 1 },
+    })],
+  };
+}
+
+const COMPOSITION_CHECKS = new Set([
+  'label_route_clearance',
+  'relationship_crossings',
+  'relationship_corridors',
+  'container_border_runs',
+  'route_rhythm',
+]);
+
+const CHECK_FIXES = {
+  single_svg: ['remove additional SVG roots so the artifact contains exactly one diagram SVG'],
+  finite_svg: ['replace non-finite coordinates before rendering again'],
+  orthogonal_arrows: ['use renderer-supported orthogonal routing controls'],
+  legend_clearance: ['move the route or enlarge the viewBox so relationships do not enter the legend'],
+};
+
+const COMPOSITION_FIXES = {
+  'composition/proper-crossing': ['adjust route/via or channel coordinates so unrelated relationships use separate corridors'],
+  'composition/ambiguous-corridor': ['adjust route/via or channel coordinates so unrelated relationships do not visually merge'],
+  'composition/container-border-run': ['route across the frame perpendicularly through a clear opening'],
+  'composition/label-route-clearance': ['adjust labelAt, labelDx, labelDy, labelSegment, message y, or the other relationship route'],
+  'composition/desktop-readability': ['reduce the viewBox width, shorten node copy, widen affected nodes, or split the diagram so node context remains at least 6px at a 1440px desktop viewport'],
+  'composition/micro-segment': ['move the route/channel/via point so every visible segment is at least 8px'],
+  'composition/short-interior-segment': ['move the route/channel/via point so every interior turn has at least 16px'],
+};
+
+function checkerDiagnostics(checker) {
+  const diagnostics = [];
+  for (const issue of checker?.composition?.issues || []) {
+    if (issue.severity !== 'error') continue;
+    const { severity, code, relationship, ...evidence } = issue;
+    diagnostics.push(diagnostic({
+      code,
+      severity,
+      message: `Final artifact failed ${code}.`,
+      subject: relationship ? { relationship } : { check: 'composition' },
+      evidence,
+      supportedFixes: COMPOSITION_FIXES[code] || [],
+    }));
+  }
+  for (const check of checker?.checks || []) {
+    if (check.ok || COMPOSITION_CHECKS.has(check.name)) continue;
+    diagnostics.push(diagnostic({
+      code: `artifact/${check.name.replaceAll('_', '-')}`,
+      message: (check.details || []).find(Boolean) || `Final artifact failed ${check.name}.`,
+      subject: { check: check.name },
+      evidence: { details: check.details || [] },
+      supportedFixes: CHECK_FIXES[check.name] || [],
+    }));
+  }
+  return diagnostics.length ? diagnostics : [diagnostic({
+    code: 'artifact/check-failed',
+    message: 'Final artifact check failed without a classified diagnostic.',
+    subject: { check: 'unknown' },
+    evidence: {},
+  })];
+}
+
+function formatDiagnostics(error, diagnostics = []) {
+  if (!diagnostics.length) return error;
+  return [
+    error,
+    ...diagnostics.map((entry) => {
+      const fix = entry.supportedFixes?.length ? ` Fix: ${entry.supportedFixes.join('; ')}.` : '';
+      return `[${entry.code}] ${entry.message}${fix}`;
+    }),
+  ].join('\n');
+}
+
+function assertEvidenceType(type, repoRoot) {
+  if (repoRoot && type !== 'architecture') {
+    rejectCliArgument('--repo-root is currently supported for architecture diagrams only.', {
+      code: 'cli/unsupported-option',
+      subject: { option: '--repo-root', type },
+      supportedFixes: ['remove --repo-root or use an architecture diagram'],
+    });
+  }
+}
+
 function exitFrom(result) {
   if (result.error) fail(result.error.message, 1);
   process.exit(result.status ?? 1);
 }
 
+function reportCompareFailure({ json, stage, error, code = 'delta/internal', details = {}, status = 1 }) {
+  const receipt = {
+    schemaVersion: 1,
+    ok: false,
+    command: 'compare',
+    type: 'architecture',
+    stage,
+    error,
+    diagnostics: [{
+      code,
+      severity: 'error',
+      message: error,
+      subject: details.side ? { side: details.side, ...(details.path ? { path: details.path } : {}) } : {},
+      evidence: Object.fromEntries(Object.entries(details).filter(([key]) => !['side', 'path', 'supportedFixes'].includes(key))),
+      supportedFixes: details.supportedFixes || [],
+    }],
+  };
+  if (json) console.log(JSON.stringify(receipt, null, 2));
+  else console.error(formatDiagnostics(error, receipt.diagnostics));
+  process.exitCode = status;
+}
+
+function extractCompareOptions(args) {
+  const positional = [];
+  let receipt;
+  let json = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg === '--receipt') {
+      receipt = args[index + 1];
+      if (!receipt || receipt.startsWith('--')) fail('--receipt requires a JSON output path.');
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--receipt=')) {
+      receipt = arg.slice('--receipt='.length);
+      if (!receipt) fail('--receipt requires a JSON output path.');
+      continue;
+    }
+    if (arg.startsWith('--')) fail(`Unknown compare option "${arg}".`);
+    positional.push(arg);
+  }
+  return { positional, receipt, json };
+}
+
+function compareReceiptPath(outputPath) {
+  const extension = path.extname(outputPath);
+  return extension ? `${outputPath.slice(0, -extension.length)}.receipt.json` : `${outputPath}.receipt.json`;
+}
+
+function compareCommitError(message, code, details = {}) {
+  const error = new Error(message);
+  error.compareStage = 'commit';
+  error.compareCode = code;
+  error.compareDetails = details;
+  return error;
+}
+
+function commitComparePair({ htmlCandidate, receiptCandidate, outputPath, receiptPath, stagingDirectory }) {
+  const targets = [
+    { label: 'HTML artifact', target: outputPath, candidate: htmlCandidate, backup: path.join(stagingDirectory, '.previous-output') },
+    { label: 'receipt', target: receiptPath, candidate: receiptCandidate, backup: path.join(stagingDirectory, '.previous-receipt') },
+  ];
+
+  // Preflight the whole pair before moving either trusted target. This avoids
+  // replacing the HTML and only then discovering that its receipt destination
+  // cannot be committed (for example, because it is a directory).
+  for (const item of targets) {
+    if (!fs.existsSync(item.target)) continue;
+    const existing = fs.lstatSync(item.target);
+    if (!existing.isFile()) {
+      throw compareCommitError(
+        `Could not commit Architecture Delta: existing ${item.label} target is not a regular file.`,
+        'delta/commit-target',
+        {
+          target: path.basename(item.target),
+          targetType: existing.isDirectory() ? 'directory' : 'non-file',
+          supportedFixes: [`choose a regular-file path for the ${item.label}`],
+        },
+      );
+    }
+  }
+
+  const backedUp = [];
+  const committed = [];
+  try {
+    for (const item of targets) {
+      if (!fs.existsSync(item.target)) continue;
+      fs.renameSync(item.target, item.backup);
+      backedUp.push(item);
+    }
+    for (const item of targets) {
+      fs.renameSync(item.candidate, item.target);
+      committed.push(item);
+    }
+  } catch (cause) {
+    const rollbackErrors = [];
+    for (const item of [...committed].reverse()) {
+      try {
+        fs.rmSync(item.target, { force: true });
+      } catch (error) {
+        rollbackErrors.push(`${item.label}: remove failed (${error.message})`);
+      }
+    }
+    for (const item of [...backedUp].reverse()) {
+      try {
+        if (fs.existsSync(item.target)) fs.rmSync(item.target, { force: true });
+        fs.renameSync(item.backup, item.target);
+      } catch (error) {
+        rollbackErrors.push(`${item.label}: restore failed (${error.message})`);
+      }
+    }
+    throw compareCommitError(
+      rollbackErrors.length
+        ? 'Architecture Delta pair commit failed and its previous files could not be fully restored.'
+        : 'Architecture Delta pair commit failed; the previous files were restored.',
+      rollbackErrors.length ? 'delta/commit-rollback-failed' : 'delta/commit-failed',
+      {
+        reason: cause.message,
+        ...(rollbackErrors.length ? { rollbackErrors } : {}),
+        supportedFixes: ['check that both output paths are writable regular files, then retry'],
+      },
+    );
+  }
+}
+
+function renderValidatedArchitecture(inputPath, outputPath, quality, repoRoot) {
+  const render = runNode([rendererPath('architecture'), inputPath, outputPath], {
+    stdio: 'pipe',
+    env: rendererEnv(quality, repoRoot, true),
+  });
+  if (render.status !== 0) {
+    const failure = rendererFailure(render);
+    const error = new Error(failure.error);
+    error.compareStage = 'input';
+    error.compareStatus = render.status ?? 1;
+    error.diagnostics = failure.diagnostics;
+    throw error;
+  }
+  const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), outputPath], { stdio: 'pipe' });
+  if (check.status !== 0) {
+    const error = new Error('Validated snapshot failed final artifact checks.');
+    error.compareStage = 'check';
+    error.compareStatus = check.status ?? 1;
+    try {
+      error.checker = JSON.parse(check.stdout);
+      error.diagnostics = checkerDiagnostics(error.checker);
+    } catch {
+      error.diagnostics = [];
+    }
+    throw error;
+  }
+  const artifact = fs.readFileSync(outputPath);
+  return {
+    artifact,
+    html: artifact.toString('utf8'),
+    checks: JSON.parse(check.stdout),
+    sourceEvidence: sourceEvidenceFromArtifact(artifact),
+  };
+}
+
+async function commandCompare(args) {
+  const { resolveOutputPath } = await import('../renderers/shared/output-path.mjs');
+  const qualityArgs = extractQualityArgs(args);
+  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
+  const options = extractCompareOptions(repoArgs.rest);
+  const [type, baseInput, headInput, requestedOutput] = options.positional;
+  if (type !== 'architecture' || !baseInput || !headInput || options.positional.length > 4) fail(usage());
+  let deltaRuntime;
+  try {
+    deltaRuntime = await import(pathToFileURL(path.join(skillRoot, 'delta/architecture-delta.mjs')).href);
+  } catch (error) {
+    reportCompareFailure({ json: options.json, stage: 'prepare', error: 'Architecture compare runtime is unavailable.', code: 'delta/runtime-missing', details: { reason: error.message, supportedFixes: ['restore the complete stacks-technical-diagrams skill directory'] } });
+    return;
+  }
+  const {
+    ArchitectureDeltaError,
+    annotateArchitectureSideSvg,
+    buildDeltaSvg,
+    canonicalArchitecture,
+    canonicalArchitectureJson,
+    compareArchitecture,
+    extractArchitectureSvg,
+    extractArtifactCss,
+    renderArchitectureDeltaHtml,
+    validateArchitectureDeltaHtml,
+  } = deltaRuntime;
+
+  const basePath = path.resolve(baseInput);
+  const headPath = path.resolve(headInput);
+  const receiptTarget = options.receipt || compareReceiptPath(path.resolve(requestedOutput || 'architecture-delta.html'));
+  let outputPath;
+  try {
+    ({ outputPath } = resolveOutputPath({
+      requestedOutput,
+      defaultOutput: 'architecture-delta.html',
+      inputPaths: [basePath, headPath],
+      otherOutputPaths: [path.resolve(receiptTarget)],
+    }));
+  } catch (error) {
+    const outputDiagnostic = error.archifyDiagnostics?.[0];
+    reportCompareFailure({
+      json: options.json,
+      stage: 'prepare',
+      error: error.message,
+      code: outputDiagnostic?.code || 'output/path-resolution',
+      details: {
+        ...(outputDiagnostic?.subject || {}),
+        ...(outputDiagnostic?.evidence || {}),
+        supportedFixes: outputDiagnostic?.supportedFixes || ['choose a safe output path and retry'],
+      },
+    });
+    return;
+  }
+  let receiptPath;
+  try {
+    ({ outputPath: receiptPath } = resolveOutputPath({
+      requestedOutput: options.receipt || compareReceiptPath(outputPath),
+      defaultOutput: compareReceiptPath(outputPath),
+      requiredExtension: '.json',
+      inputPaths: [basePath, headPath],
+      otherOutputPaths: [outputPath],
+    }));
+  } catch (error) {
+    const outputDiagnostic = error.archifyDiagnostics?.[0];
+    reportCompareFailure({
+      json: options.json,
+      stage: 'prepare',
+      error: error.message,
+      code: outputDiagnostic?.code || 'output/path-resolution',
+      details: {
+        ...(outputDiagnostic?.subject || {}),
+        ...(outputDiagnostic?.evidence || {}),
+        supportedFixes: outputDiagnostic?.supportedFixes || ['choose a safe receipt path and retry'],
+      },
+    });
+    return;
+  }
+  let baseBuffer;
+  let headBuffer;
+  let base;
+  let head;
+  try {
+    baseBuffer = fs.readFileSync(basePath);
+    base = JSON.parse(baseBuffer.toString('utf8'));
+  } catch (error) {
+    reportCompareFailure({ json: options.json, stage: 'input', error: `Could not read base input: ${error.message}`, code: 'delta/base-input', details: { side: 'base', reason: error.message } });
+    return;
+  }
+  try {
+    headBuffer = fs.readFileSync(headPath);
+    head = JSON.parse(headBuffer.toString('utf8'));
+  } catch (error) {
+    reportCompareFailure({ json: options.json, stage: 'input', error: `Could not read head input: ${error.message}`, code: 'delta/head-input', details: { side: 'head', reason: error.message } });
+    return;
+  }
+
+  const outputDirectory = path.dirname(outputPath);
+  if (path.dirname(receiptPath) !== outputDirectory) {
+    reportCompareFailure({ json: options.json, stage: 'prepare', error: 'The compare receipt must be written beside the HTML artifact.', code: 'delta/receipt-directory', details: { supportedFixes: ['choose a --receipt path in the same directory as output.html'] } });
+    return;
+  }
+  try {
+    fs.mkdirSync(outputDirectory, { recursive: true });
+  } catch (error) {
+    reportCompareFailure({ json: options.json, stage: 'prepare', error: `Could not create compare output directory: ${error.message}`, code: 'delta/output-directory', details: { reason: error.message } });
+    return;
+  }
+
+  let stagingDirectory;
+  try {
+    stagingDirectory = fs.mkdtempSync(path.join(outputDirectory, '.archify-compare-'));
+  } catch (error) {
+    reportCompareFailure({ json: options.json, stage: 'prepare', error: `Could not create compare candidate: ${error.message}`, code: 'delta/candidate-directory', details: { reason: error.message } });
+    return;
+  }
+
+  const baseCandidate = path.join(stagingDirectory, 'base.html');
+  const headCandidate = path.join(stagingDirectory, 'head.html');
+  const rawBaseCandidate = path.join(stagingDirectory, 'base.raw.html');
+  const rawHeadCandidate = path.join(stagingDirectory, 'head.raw.html');
+  const canonicalBaseInput = path.join(stagingDirectory, 'base.architecture.json');
+  const canonicalHeadInput = path.join(stagingDirectory, 'head.architecture.json');
+  const htmlCandidate = path.join(stagingDirectory, path.basename(outputPath));
+  const receiptCandidate = path.join(stagingDirectory, path.basename(receiptPath));
+
+  try {
+    let baseResult;
+    let headResult;
+    try {
+      renderValidatedArchitecture(basePath, rawBaseCandidate, qualityArgs.quality, repoArgs.repoRoot);
+    } catch (error) {
+      const diagnosticEntry = error.diagnostics?.[0];
+      reportCompareFailure({
+        json: options.json,
+        stage: error.compareStage || 'validate',
+        error: `Base snapshot failed validation: ${error.message}`,
+        code: diagnosticEntry?.code || 'delta/base-validation',
+        details: { side: 'base', ...(diagnosticEntry?.subject?.path ? { path: diagnosticEntry.subject.path } : {}), ...(diagnosticEntry?.evidence || {}), supportedFixes: diagnosticEntry?.supportedFixes || [] },
+        status: error.compareStatus || 1,
+      });
+      return;
+    }
+    try {
+      renderValidatedArchitecture(headPath, rawHeadCandidate, qualityArgs.quality, repoArgs.repoRoot);
+    } catch (error) {
+      const diagnosticEntry = error.diagnostics?.[0];
+      reportCompareFailure({
+        json: options.json,
+        stage: error.compareStage || 'validate',
+        error: `Head snapshot failed validation: ${error.message}`,
+        code: diagnosticEntry?.code || 'delta/head-validation',
+        details: { side: 'head', ...(diagnosticEntry?.subject?.path ? { path: diagnosticEntry.subject.path } : {}), ...(diagnosticEntry?.evidence || {}), supportedFixes: diagnosticEntry?.supportedFixes || [] },
+        status: error.compareStatus || 1,
+      });
+      return;
+    }
+
+    // Validation must see the exact authored inputs. Only after both sides
+    // pass do we canonicalize their collection order for deterministic SVG
+    // geometry and stable artifact bytes.
+    fs.writeFileSync(canonicalBaseInput, JSON.stringify(canonicalArchitecture(base)));
+    fs.writeFileSync(canonicalHeadInput, JSON.stringify(canonicalArchitecture(head)));
+    baseResult = renderValidatedArchitecture(canonicalBaseInput, baseCandidate, qualityArgs.quality, repoArgs.repoRoot);
+    headResult = renderValidatedArchitecture(canonicalHeadInput, headCandidate, qualityArgs.quality, repoArgs.repoRoot);
+
+    const semanticHash = (diagram) => createHash('sha256').update(canonicalArchitectureJson(diagram)).digest('hex');
+    let compareIr;
+    try {
+      compareIr = compareArchitecture(base, head, {
+        baseRawSha256: createHash('sha256').update(baseBuffer).digest('hex'),
+        headRawSha256: createHash('sha256').update(headBuffer).digest('hex'),
+        baseSemanticSha256: semanticHash(base),
+        headSemanticSha256: semanticHash(head),
+        baseBytes: baseBuffer.byteLength,
+        headBytes: headBuffer.byteLength,
+        baseVerified: Boolean(baseResult.sourceEvidence),
+        headVerified: Boolean(headResult.sourceEvidence),
+      });
+    } catch (error) {
+      if (!(error instanceof ArchitectureDeltaError)) throw error;
+      reportCompareFailure({ json: options.json, stage: 'compare', error: error.message, code: error.code, details: error.details });
+      return;
+    }
+
+    const baseSourceSvg = extractArchitectureSvg(baseResult.html);
+    const headSourceSvg = extractArchitectureSvg(headResult.html);
+    const baseSvg = annotateArchitectureSideSvg(baseSourceSvg, compareIr, 'base');
+    const headSvg = annotateArchitectureSideSvg(headSourceSvg, compareIr, 'head');
+    const deltaSvg = buildDeltaSvg(baseSourceSvg, headSourceSvg, compareIr);
+    // Raw input hashes and byte counts belong in the sidecar receipt, not the
+    // artifact. Keeping them out makes formatting-only input rewrites produce
+    // the exact same canonical review HTML and artifact hash.
+    const artifactIr = {
+      ...compareIr,
+      base: Object.fromEntries(Object.entries(compareIr.base).filter(([key]) => !['rawSha256', 'bytes'].includes(key))),
+      head: Object.fromEntries(Object.entries(compareIr.head).filter(([key]) => !['rawSha256', 'bytes'].includes(key))),
+    };
+    const html = renderArchitectureDeltaHtml({
+      receipt: artifactIr,
+      baseSvg,
+      deltaSvg,
+      headSvg,
+      baseHtml: baseResult.html,
+      headHtml: headResult.html,
+      artifactCss: extractArtifactCss(headResult.html),
+    });
+    const deltaValidation = validateArchitectureDeltaHtml(html, artifactIr);
+    fs.writeFileSync(htmlCandidate, html);
+    const artifact = fs.readFileSync(htmlCandidate);
+    const baseChecks = baseResult.checks.checks.filter((check) => check.ok).length;
+    const headChecks = headResult.checks.checks.filter((check) => check.ok).length;
+    const finalReceipt = {
+      ...compareIr,
+      artifact: { sha256: createHash('sha256').update(artifact).digest('hex'), bytes: artifact.byteLength },
+      validation: {
+        checksPassed: baseChecks + headChecks + deltaValidation.checksPassed,
+        checkCount: baseResult.checks.checks.length + headResult.checks.checks.length + deltaValidation.checkCount,
+        baseComposition: baseResult.checks.composition.status,
+        headComposition: headResult.checks.composition.status,
+      },
+    };
+    fs.writeFileSync(receiptCandidate, `${JSON.stringify(finalReceipt, null, 2)}\n`);
+
+    try {
+      const currentOutput = resolveOutputPath({
+        requestedOutput,
+        defaultOutput: 'architecture-delta.html',
+        inputPaths: [basePath, headPath],
+        otherOutputPaths: [receiptPath],
+      }).outputPath;
+      resolveOutputPath({
+        requestedOutput: options.receipt || compareReceiptPath(currentOutput),
+        defaultOutput: compareReceiptPath(currentOutput),
+        requiredExtension: '.json',
+        inputPaths: [basePath, headPath],
+        otherOutputPaths: [currentOutput],
+      });
+    } catch (error) {
+      const outputDiagnostic = error.archifyDiagnostics?.[0];
+      reportCompareFailure({
+        json: options.json,
+        stage: 'commit',
+        error: error.message,
+        code: outputDiagnostic?.code || 'output/path-resolution',
+        details: {
+          ...(outputDiagnostic?.subject || {}),
+          ...(outputDiagnostic?.evidence || {}),
+          supportedFixes: outputDiagnostic?.supportedFixes || ['restore safe output paths and retry'],
+        },
+      });
+      return;
+    }
+
+    commitComparePair({ htmlCandidate, receiptCandidate, outputPath, receiptPath, stagingDirectory });
+    if (options.json) console.log(JSON.stringify(finalReceipt, null, 2));
+    else {
+      console.log(`compared architecture ${outputPath}`);
+      console.log(`${finalReceipt.validation.checksPassed}/${finalReceipt.validation.checkCount} checks; completeness ${finalReceipt.completeness}; ${finalReceipt.proofLevel}; sha256 ${finalReceipt.artifact.sha256.slice(0, 12)}`);
+      console.log(`receipt ${receiptPath}`);
+    }
+  } catch (error) {
+    if (error instanceof ArchitectureDeltaError) {
+      reportCompareFailure({ json: options.json, stage: 'artifact', error: error.message, code: error.code, details: error.details });
+    } else if (error.compareStage === 'commit') {
+      reportCompareFailure({
+        json: options.json,
+        stage: error.compareStage,
+        error: error.message,
+        code: error.compareCode,
+        details: error.compareDetails,
+      });
+    } else {
+      reportCompareFailure({ json: options.json, stage: 'internal', error: 'Architecture compare failed before commit.', code: 'delta/internal', details: { reason: error.message } });
+    }
+  } finally {
+    try {
+      fs.rmSync(stagingDirectory, { recursive: true, force: true });
+    } catch (error) {
+      console.error(`Warning: could not remove compare staging directory: ${error.message}`);
+    }
+  }
+}
+
 function commandRender(args) {
-  const [type, input, output] = args;
-  if (!type || !input) fail(usage());
-  const result = runRuntime([rendererPath(type), input, ...(output ? [output] : [])]);
+  const qualityArgs = extractQualityArgs(args);
+  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
+  // render takes no options of its own once --quality and --repo-root are
+  // stripped, so anything left starting with -- is a typo. Without this a
+  // mistyped flag was taken as the output path: `render architecture spec.json
+  // --json out.html` wrote a file literally named `--json` and never wrote
+  // out.html, exiting 0. Every sibling subcommand already guards this.
+  const unknown = repoArgs.rest.filter((arg) => arg.startsWith('--'));
+  if (unknown.length) fail(`Unknown render option "${unknown[0]}".`);
+  const [type, input, output] = repoArgs.rest;
+  if (!type || !input || repoArgs.rest.length > 3) fail(usage());
+  assertEvidenceType(type, repoArgs.repoRoot);
+  const result = runNode([rendererPath(type), input, ...(output ? [output] : [])], {
+    env: rendererEnv(qualityArgs.quality, repoArgs.repoRoot),
+  });
   if (result.status !== 0) exitFrom(result);
 }
 
+function reportArtifactFailure({ command, json, stage, type, input, output, error, diagnostics = [], status = 1, checker }) {
+  const receipt = {
+    schemaVersion: 1,
+    ok: false,
+    command,
+    stage,
+    type,
+    input,
+    ...(output === undefined ? {} : { output }),
+    error,
+    diagnostics,
+    ...(checker ? { checker } : {}),
+  };
+  if (json) console.log(JSON.stringify(receipt, null, 2));
+  else console.error(formatDiagnostics(error, diagnostics));
+  process.exitCode = status;
+}
+
+function reportDeliveryFailure(options) {
+  reportArtifactFailure({ ...options, command: 'deliver' });
+}
+
+function reportValidateFailure(options) {
+  reportArtifactFailure({ ...options, command: 'validate' });
+}
+
+function reportArtifactArgumentFailure(command, error) {
+  const details = error.archifyArgument || {};
+  reportArtifactFailure({
+    command,
+    json: true,
+    stage: 'arguments',
+    error: error.message,
+    diagnostics: [diagnostic({
+      code: details.code || 'cli/invalid-arguments',
+      message: error.message,
+      subject: { command, ...(details.subject || {}) },
+      evidence: details.evidence || {},
+      supportedFixes: details.supportedFixes || ['correct the command arguments and retry'],
+    })],
+    status: 2,
+  });
+}
+
+function sourceEvidenceFromArtifact(artifact) {
+  const html = artifact.toString('utf8');
+  const match = html.match(/<script id="archify-source-evidence-data" type="application\/json">([\s\S]*?)<\/script>/);
+  if (!match) return null;
+  const evidence = JSON.parse(match[1]);
+  if (evidence?.verified !== true || !evidence.repository?.url || !evidence.repository?.revision || !Number.isInteger(evidence.referenceCount)) {
+    throw new Error('Rendered source evidence receipt is incomplete.');
+  }
+  return evidence;
+}
+
+function engineeringProfileFromArtifact(artifact) {
+  const match = artifact.toString('utf8').match(/<svg[^>]*\sdata-engineering-profile="([^"]+)"/);
+  return match ? match[1] : null;
+}
+
+async function commandDeliver(args) {
+  const qualityArgs = extractQualityArgs(args);
+  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
+  const json = repoArgs.rest.includes('--json');
+  const open = repoArgs.rest.includes('--open');
+  const knownOptions = new Set(['--json', '--open']);
+  const unknown = repoArgs.rest.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
+  if (unknown.length) rejectCliArgument(`Unknown deliver option "${unknown[0]}".`, {
+    code: 'cli/unknown-option',
+    subject: { option: unknown[0] },
+    supportedFixes: ['remove the unknown option and retry'],
+  });
+  const positional = repoArgs.rest.filter((arg) => !knownOptions.has(arg));
+  const [type, input, requestedOutput] = positional;
+  if (!type || !input || positional.length > 3) rejectCliArgument(usage(), {
+    code: 'cli/usage',
+    supportedFixes: ['use: diagrams deliver <type> <input.json> [output.html] [options]'],
+  });
+  assertEvidenceType(type, repoArgs.repoRoot);
+  const renderer = rendererPath(type);
+  const { resolveOutputPath } = await import('../renderers/shared/output-path.mjs');
+  const inputPath = path.resolve(input);
+  let specification;
+  let diagram;
+  try {
+    specification = fs.readFileSync(inputPath);
+    diagram = JSON.parse(specification.toString('utf8'));
+  } catch (error) {
+    const repair = inputDiagnostic(error, inputPath);
+    reportDeliveryFailure({
+      json,
+      stage: 'input',
+      type,
+      input: inputPath,
+      output: path.resolve(requestedOutput || `${type}.html`),
+      error: `Could not read delivery input "${inputPath}": ${error.message}`,
+      diagnostics: [repair],
+    });
+    return;
+  }
+
+  const authoredOutput = typeof diagram?.meta?.output === 'string' && diagram.meta.output
+    ? diagram.meta.output
+    : undefined;
+  let outputPath;
+  try {
+    ({ outputPath } = resolveOutputPath({
+      requestedOutput,
+      authoredOutput,
+      defaultOutput: `${type}.html`,
+      inputPaths: [inputPath],
+    }));
+  } catch (error) {
+    const attemptedOutput = path.resolve(requestedOutput || authoredOutput || `${type}.html`);
+    reportDeliveryFailure({
+      json,
+      stage: 'prepare',
+      type,
+      input: inputPath,
+      output: attemptedOutput,
+      error: error.message,
+      diagnostics: error.archifyDiagnostics || [diagnostic({
+        code: 'output/path-resolution',
+        message: error.message,
+        subject: { output: attemptedOutput },
+        evidence: { ...(error?.code ? { systemCode: error.code } : {}) },
+        supportedFixes: ['choose a safe output path and retry'],
+      })],
+    });
+    return;
+  }
+  const outputDirectory = path.dirname(outputPath);
+  try {
+    fs.mkdirSync(outputDirectory, { recursive: true });
+  } catch (error) {
+    const message = `Could not create delivery directory "${outputDirectory}": ${error.message}`;
+    reportDeliveryFailure({
+      json,
+      stage: 'prepare',
+      type,
+      input: inputPath,
+      output: outputPath,
+      error: message,
+      diagnostics: [diagnostic({
+        code: 'delivery/prepare-directory',
+        message,
+        subject: { outputDirectory },
+        evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
+        supportedFixes: ['choose a writable output directory'],
+      })],
+    });
+    return;
+  }
+
+  // Keep the candidate beside the target so the final rename is one
+  // same-filesystem commit. A render or artifact-check failure never touches
+  // an existing trusted output.
+  let stagingDirectory;
+  try {
+    stagingDirectory = fs.mkdtempSync(path.join(outputDirectory, '.archify-delivery-'));
+  } catch (error) {
+    const message = `Could not create a delivery candidate beside "${outputPath}": ${error.message}`;
+    reportDeliveryFailure({
+      json,
+      stage: 'prepare',
+      type,
+      input: inputPath,
+      output: outputPath,
+      error: message,
+      diagnostics: [diagnostic({
+        code: 'delivery/prepare-candidate',
+        message,
+        subject: { output: outputPath },
+        evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
+        supportedFixes: ['choose a writable output directory on the target filesystem'],
+      })],
+    });
+    return;
+  }
+  const candidatePath = path.join(stagingDirectory, path.basename(outputPath));
+  const specificationSnapshotPath = path.join(stagingDirectory, 'specification.snapshot.json');
+
+  try {
+    try {
+      fs.writeFileSync(specificationSnapshotPath, specification, { flag: 'wx' });
+    } catch (error) {
+      const message = `Could not freeze the delivery specification: ${error.message}`;
+      reportDeliveryFailure({
+        json,
+        stage: 'prepare',
+        type,
+        input: inputPath,
+        output: outputPath,
+        error: message,
+        diagnostics: [diagnostic({
+          code: 'delivery/freeze-specification',
+          message,
+          subject: { input: inputPath },
+          evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
+          supportedFixes: ['choose a writable output directory on the target filesystem'],
+        })],
+      });
+      return;
+    }
+
+    const render = runNode([renderer, specificationSnapshotPath, candidatePath], {
+      stdio: 'pipe',
+      env: rendererEnv(qualityArgs.quality, repoArgs.repoRoot, true),
+    });
+    if (render.status !== 0) {
+      const failure = rendererFailure(render);
+      reportDeliveryFailure({
+        json,
+        stage: 'render',
+        type,
+        input: inputPath,
+        output: outputPath,
+        error: failure.error,
+        diagnostics: failure.diagnostics,
+        status: render.status ?? 1,
+      });
+      return;
+    }
+
+    const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), candidatePath], {
+      stdio: 'pipe',
+    });
+    if (check.status !== 0) {
+      if (check.stderr) process.stderr.write(check.stderr);
+      let checker;
+      try {
+        checker = JSON.parse(check.stdout);
+        checker.file = outputPath;
+      } catch {
+        checker = { ok: false, file: outputPath, diagnostic: check.stdout.trim() };
+      }
+      reportDeliveryFailure({
+        json,
+        stage: 'check',
+        type,
+        input: inputPath,
+        output: outputPath,
+        error: 'Final artifact check failed; the previous artifact was preserved.',
+        diagnostics: checkerDiagnostics(checker),
+        status: check.status ?? 1,
+        checker,
+      });
+      return;
+    }
+
+    let result;
+    try {
+      result = JSON.parse(check.stdout);
+    } catch (error) {
+      const message = `Could not parse the successful artifact-check receipt: ${error.message}`;
+      reportDeliveryFailure({
+        json,
+        stage: 'receipt',
+        type,
+        input: inputPath,
+        output: outputPath,
+        error: message,
+        diagnostics: [diagnostic({
+          code: 'delivery/receipt-invalid',
+          message,
+          subject: { output: outputPath },
+          evidence: { reason: error.message },
+        })],
+      });
+      return;
+    }
+    let artifact;
+    try {
+      artifact = fs.readFileSync(candidatePath);
+    } catch (error) {
+      const message = `Could not read the verified delivery candidate: ${error.message}`;
+      reportDeliveryFailure({
+        json,
+        stage: 'receipt',
+        type,
+        input: inputPath,
+        output: outputPath,
+        error: message,
+        diagnostics: [diagnostic({
+          code: 'delivery/candidate-unreadable',
+          message,
+          subject: { output: outputPath },
+          evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
+        })],
+      });
+      return;
+    }
+    let sourceEvidence;
+    try {
+      sourceEvidence = sourceEvidenceFromArtifact(artifact);
+    } catch (error) {
+      const message = `Could not read the repository evidence receipt: ${error.message}`;
+      reportDeliveryFailure({
+        json,
+        stage: 'receipt',
+        type,
+        input: inputPath,
+        output: outputPath,
+        error: message,
+        diagnostics: [diagnostic({
+          code: 'delivery/evidence-receipt-invalid',
+          message,
+          subject: { output: outputPath },
+          evidence: { reason: error.message },
+        })],
+      });
+      return;
+    }
+    const engineeringProfile = engineeringProfileFromArtifact(artifact);
+    const receipt = {
+      schemaVersion: 1,
+      ok: true,
+      command: 'deliver',
+      type,
+      input: inputPath,
+      output: outputPath,
+      specification: {
+        sha256: createHash('sha256').update(specification).digest('hex'),
+        bytes: specification.byteLength,
+      },
+      artifact: {
+        sha256: createHash('sha256').update(artifact).digest('hex'),
+        bytes: artifact.byteLength,
+      },
+      validation: {
+        checksPassed: result.checks.filter((checkItem) => checkItem.ok).length,
+        checkCount: result.checks.length,
+        compositionProfile: result.composition.profile,
+        compositionStatus: result.composition.status,
+        ...(engineeringProfile ? { engineeringProfile } : {}),
+        errors: result.composition.summary.errors,
+        warnings: result.composition.summary.warnings,
+      },
+      ...(sourceEvidence ? {
+        evidence: {
+          verified: true,
+          repository: sourceEvidence.repository.url,
+          revision: sourceEvidence.repository.revision,
+          references: sourceEvidence.referenceCount,
+          ...(sourceEvidence.repository.linkMode ? { linkMode: sourceEvidence.repository.linkMode } : {}),
+        },
+      } : {}),
+    };
+
+    try {
+      resolveOutputPath({
+        requestedOutput,
+        authoredOutput,
+        defaultOutput: `${type}.html`,
+        inputPaths: [inputPath],
+      });
+    } catch (error) {
+      reportDeliveryFailure({
+        json,
+        stage: 'commit',
+        type,
+        input: inputPath,
+        output: outputPath,
+        error: error.message,
+        diagnostics: error.archifyDiagnostics || [diagnostic({
+          code: 'output/path-resolution',
+          message: error.message,
+          subject: { output: outputPath },
+          evidence: { ...(error?.code ? { systemCode: error.code } : {}) },
+          supportedFixes: ['restore a safe output path and retry'],
+        })],
+      });
+      return;
+    }
+
+    try {
+      fs.renameSync(candidatePath, outputPath);
+    } catch (error) {
+      const message = `Could not commit verified delivery "${outputPath}": ${error.message}`;
+      reportDeliveryFailure({
+        json,
+        stage: 'commit',
+        type,
+        input: inputPath,
+        output: outputPath,
+        error: message,
+        diagnostics: [diagnostic({
+          code: 'delivery/commit',
+          message,
+          subject: { output: outputPath },
+          evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
+          supportedFixes: ['choose a replaceable file target on the same writable filesystem'],
+        })],
+      });
+      return;
+    }
+
+    if (open) {
+      try {
+        const { openArtifact } = await import('./open-artifact.mjs');
+        receipt.open = openArtifact(outputPath);
+      } catch {
+        receipt.open = {
+          requested: true,
+          status: 'unsupported',
+          target: outputPath,
+          method: null,
+        };
+      }
+      if (receipt.open.status !== 'opened') {
+        console.error(`Could not open the verified artifact (${receipt.open.status}). Open it manually: ${outputPath}`);
+      }
+    }
+
+    if (json) {
+      console.log(JSON.stringify(receipt, null, 2));
+    } else {
+      console.log(`delivered ${type} ${outputPath}`);
+      const engineering = receipt.validation.engineeringProfile
+        ? `; engineering ${receipt.validation.engineeringProfile}: pass`
+        : '';
+      console.log(`${receipt.validation.checksPassed}/${receipt.validation.checkCount} artifact checks; composition ${receipt.validation.compositionProfile}: ${receipt.validation.compositionStatus}${engineering}; sha256 ${receipt.artifact.sha256.slice(0, 12)}`);
+      if (receipt.open?.status === 'opened') console.log(`opened ${outputPath}`);
+    }
+  } finally {
+    try {
+      fs.rmSync(stagingDirectory, { recursive: true, force: true });
+    } catch (error) {
+      console.error(`Warning: could not remove delivery staging directory "${stagingDirectory}": ${error.message}`);
+    }
+  }
+}
+
+async function commandPreview(args) {
+  const qualityArgs = extractQualityArgs(args);
+  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
+  const noOpen = repoArgs.rest.includes('--no-open');
+  const knownOptions = new Set(['--no-open']);
+  const unknown = repoArgs.rest.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
+  if (unknown.length) fail(`Unknown preview option "${unknown[0]}".`);
+  const positional = repoArgs.rest.filter((arg) => !knownOptions.has(arg));
+  const [type, input, output] = positional;
+  if (!type || !input || positional.length > 3) fail(usage());
+  assertEvidenceType(type, repoArgs.repoRoot);
+  rendererPath(type);
+
+  let runPreview;
+  try {
+    ({ runPreview } = await import('./preview.mjs'));
+  } catch (error) {
+    fail(`Could not load live preview: ${error.message}`, 1);
+  }
+  try {
+    await runPreview({
+      type,
+      input,
+      output,
+      quality: qualityArgs.quality,
+      repoRoot: repoArgs.repoRoot,
+      open: !noOpen,
+    });
+  } catch (error) {
+    fail(`Could not start live preview: ${error.message}`, 1);
+  }
+}
+
 function commandCheck(args) {
   const [html] = args;
   if (!html) fail(usage());
-  const result = runRuntime([path.join(skillRoot, 'scripts/check-render-output.mjs'), html]);
+  const result = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), html]);
   if (result.status !== 0) exitFrom(result);
 }
 
+async function commandVisualCheck(args) {
+  const json = args.includes('--json');
+  const knownOptions = new Set(['--json']);
+  const unknown = args.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
+  if (unknown.length) fail(`Unknown visual-check option "${unknown[0]}".`, 1);
+  const positional = args.filter((arg) => !knownOptions.has(arg));
+  if (positional.length !== 1) fail(usage(), 1);
+
+  let runVisualCheck;
+  try {
+    ({ runVisualCheck } = await import('./visual-check.mjs'));
+  } catch (error) {
+    fail(`Could not load visual-check: ${error.message}`, 1);
+  }
+
+  let result;
+  try {
+    result = await runVisualCheck({ artifactPath: positional[0] });
+  } catch (error) {
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        ok: false,
+        command: 'visual-check',
+        evidenceKind: 'automated-browser',
+        status: 'fail',
+        visualReview: 'pending',
+        artifact: { path: path.resolve(positional[0]) },
+        error: error.message,
+      }, null, 2));
+    } else {
+      console.error(`automated browser evidence failed: ${error.message}`);
+      console.error('perceptual visual review pending');
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (json) {
+    console.log(JSON.stringify(result.receipt, null, 2));
+  } else {
+    console.log(`automated browser evidence ${result.receipt.status}: ${result.receipt.artifact.path}`);
+    console.log(`visual-check containment ${result.receipt.containment.status}; captures ${result.receipt.captures.status}; perceptual visual review pending`);
+    console.log(`receipt ${path.join(path.dirname(result.receipt.artifact.path), result.receipt.sidecars.receipt)}`);
+    if (result.receipt.captures.contactSheet) {
+      console.log(`contact sheet ${path.join(path.dirname(result.receipt.artifact.path), result.receipt.captures.contactSheet)}`);
+    }
+    if (result.receipt.error) console.error(result.receipt.error);
+  }
+  process.exitCode = result.exitCode;
+}
+
 function commandExamples(args) {
-  if (args.length > 1) fail(usage());
-  const outputDirectory = path.resolve(args[0] || process.cwd());
+  // Stacks port: the skill directory is tracked in git, so rendering the bundled
+  // examples in place would drop several megabytes of generated HTML into the
+  // working tree. Default to a temp directory and say where the files landed.
+  const outputDirectory = path.resolve(args[0] || path.join(os.tmpdir(), 'technical-diagrams-examples'));
   fs.mkdirSync(outputDirectory, { recursive: true });
-  const result = runRuntime([
-    path.join(skillRoot, 'scripts/render-examples.mjs'),
-    outputDirectory,
-  ]);
+  const result = runNode([path.join(skillRoot, 'scripts/render-examples.mjs'), outputDirectory], { cwd: skillRoot });
   if (result.status !== 0) exitFrom(result);
+  console.log(`\nRendered examples: ${outputDirectory}`);
 }
 
 async function commandDoctor() {
   const checks = [];
-  const bunVersion = process.versions.bun || '0.0.0';
-  const [bunMajor, bunMinor] = bunVersion.split('.').map(Number);
+  const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
   checks.push({
-    label: `Bun v${bunVersion} (requires >=1.3)`,
-    ok: bunMajor > 1 || (bunMajor === 1 && bunMinor >= 3),
+    label: `Node.js v${process.versions.node} (requires >=18)`,
+    ok: nodeMajor >= 18,
     missing: 0,
     failureLabel: 'unsupported',
   });
@@ -105,11 +1319,56 @@ async function commandDoctor() {
     missing: fs.existsSync(examplesRenderer) ? 0 : 1,
   });
 
-  const isolatedConfig = path.join(skillRoot, 'bunfig.toml');
+  const previewRuntime = path.join(skillRoot, 'bin/preview.mjs');
+  checks.push({
+    label: 'Live preview runtime',
+    ok: fs.existsSync(previewRuntime),
+    missing: fs.existsSync(previewRuntime) ? 0 : 1,
+  });
+
+  const visualCheckRuntime = path.join(skillRoot, 'bin/visual-check.mjs');
+  checks.push({
+    label: 'Visual-check runtime',
+    ok: fs.existsSync(visualCheckRuntime),
+    missing: fs.existsSync(visualCheckRuntime) ? 0 : 1,
+  });
+
+  const outputPathRuntime = path.join(skillRoot, 'renderers/shared/output-path.mjs');
+  checks.push({
+    label: 'Output path safety runtime',
+    ok: fs.existsSync(outputPathRuntime),
+    missing: fs.existsSync(outputPathRuntime) ? 0 : 1,
+  });
+
+  const scenarioGuide = path.join(skillRoot, 'recipes/scenarios.mjs');
+  checks.push({
+    label: 'Scenario recipe guide',
+    ok: fs.existsSync(scenarioGuide),
+    missing: fs.existsSync(scenarioGuide) ? 0 : 1,
+  });
+
+  const authoringReferences = [
+    path.join(skillRoot, 'references', 'authoring-contract.md'),
+    path.join(skillRoot, 'references', 'viewer-runtime.md'),
+    path.join(skillRoot, 'references', 'delivery-contract.md'),
+  ];
+  const authoringReferencesMissing = authoringReferences.filter((file) => !fs.existsSync(file)).length;
+  checks.push({
+    label: 'Progressive authoring references',
+    ok: authoringReferencesMissing === 0,
+    missing: authoringReferencesMissing,
+  });
+
+  const compareRuntime = path.join(skillRoot, 'delta/architecture-delta.mjs');
+  const compareFixtures = [
+    path.join(skillRoot, 'examples/checkout-platform.base.architecture.json'),
+    path.join(skillRoot, 'examples/checkout-platform.head.architecture.json'),
+  ];
+  const compareMissing = [compareRuntime, ...compareFixtures].filter((file) => !fs.existsSync(file)).length;
   checks.push({
-    label: 'Isolated Bun configuration',
-    ok: fs.existsSync(isolatedConfig),
-    missing: fs.existsSync(isolatedConfig) ? 0 : 1,
+    label: 'Architecture compare runtime and proof fixtures',
+    ok: compareMissing === 0,
+    missing: compareMissing,
   });
 
   const validators = path.join(skillRoot, 'renderers/shared/generated-validators.mjs');
@@ -153,32 +1412,141 @@ async function commandDoctor() {
     });
   }
 
-  console.log('Technical diagram renderer doctor\n');
+  console.log('Technical Diagrams doctor\n');
   for (const check of checks) {
     console.log(`[${check.ok ? 'ok' : (check.failureLabel || 'missing')}] ${check.label}`);
   }
 
-  const runtimeFailed = checks[0].ok ? 0 : 1;
+  const nodeFailed = checks[0].ok ? 0 : 1;
   const missingFiles = checks.reduce((count, check) => count + check.missing, 0);
   const invalidRuntime = checks.reduce((count, check) => count + (check.invalid || 0), 0);
-  if (runtimeFailed === 0 && missingFiles === 0 && invalidRuntime === 0) {
-    console.log('\nTechnical diagram renderer is ready.');
+  if (nodeFailed === 0 && missingFiles === 0 && invalidRuntime === 0) {
+    console.log('\nThe technical diagrams skill is ready.');
     return;
   }
 
   const problems = [];
-  if (runtimeFailed) problems.push('Bun 1.3 or newer is required');
+  if (nodeFailed) problems.push('Node.js 18 or newer is required');
   if (missingFiles) problems.push(`${missingFiles} required file${missingFiles === 1 ? '' : 's'} missing`);
   if (invalidRuntime) problems.push(`${invalidRuntime} runtime check${invalidRuntime === 1 ? '' : 's'} failed`);
-  console.error(`\nTechnical diagram renderer is not ready: ${problems.join('; ')}.`);
+  console.error(`\nThe technical diagrams skill is not ready: ${problems.join('; ')}.`);
   process.exitCode = 1;
 }
 
+async function commandGuide(args) {
+  let lang;
+  let json = false;
+  const queryParts = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '--lang') {
+      const value = args[index + 1];
+      if (value !== 'en' && value !== 'zh') fail('--lang must be "en" or "zh".');
+      lang = value;
+      index += 1;
+    } else if (arg.startsWith('--lang=')) {
+      const value = arg.slice('--lang='.length);
+      if (value !== 'en' && value !== 'zh') fail('--lang must be "en" or "zh".');
+      lang = value;
+    } else if (arg.startsWith('--')) {
+      fail(`Unknown guide option "${arg}".`);
+    } else {
+      queryParts.push(arg);
+    }
+  }
+
+  const guidePath = path.join(skillRoot, 'recipes/scenarios.mjs');
+  let guide;
+  try {
+    guide = await import(pathToFileURL(guidePath).href);
+  } catch (error) {
+    fail(`Could not load the scenario recipe guide: ${error.message}`, 1);
+  }
+
+  const query = queryParts.join(' ').trim();
+  if (!query) {
+    const selectedLang = lang || 'en';
+    if (json) {
+      console.log(JSON.stringify({
+        ok: true,
+        mode: 'list',
+        lang: selectedLang,
+        recipes: guide.listScenarioRecipes(selectedLang),
+      }, null, 2));
+    } else {
+      console.log(guide.formatScenarioList(selectedLang));
+    }
+    return;
+  }
+
+  const result = guide.recommendScenario(query, lang ? { lang } : {});
+  console.log(json ? JSON.stringify(result, null, 2) : guide.formatScenarioRecommendation(result));
+}
+
+async function commandBrands(args) {
+  const json = args.includes('--json');
+  const unknown = args.filter((arg) => arg.startsWith('--') && arg !== '--json');
+  if (unknown.length) fail(`Unknown brands option "${unknown[0]}".`);
+  const positional = args.filter((arg) => arg !== '--json');
+  if (positional[0] === 'capture') {
+    if (positional.length !== 2) fail('Usage: diagrams brands capture <url> [--json]');
+    const { captureBrandReference } = await import('../renderers/shared/brand-marks.mjs');
+    let capture;
+    try {
+      capture = await captureBrandReference(positional[1]);
+    } catch (error) {
+      fail(error.message);
+    }
+    const result = {
+      schemaVersion: 1,
+      ok: true,
+      command: 'brands capture',
+      brand: capture.brand,
+      evidence: {
+        status: capture.resolved.status,
+        source: capture.resolved.sourceUrl,
+        ...(capture.resolved.sha256 ? { sha256: capture.resolved.sha256 } : {}),
+        ...(capture.resolved.contentType ? { contentType: capture.resolved.contentType } : {}),
+      },
+    };
+    console.log(json ? JSON.stringify(result, null, 2) : JSON.stringify(result.brand));
+    return;
+  }
+  const query = positional.join(' ').trim();
+  const { listBrandMarks } = await import('../renderers/shared/brand-marks.mjs');
+  const marks = listBrandMarks(query);
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      ok: true,
+      command: 'brands',
+      query,
+      count: marks.length,
+      marks,
+      fallback: 'Run "diagrams brands capture <url> --json", then use the returned digest-pinned brand value.',
+    }, null, 2));
+    return;
+  }
+  if (!marks.length) {
+    console.log(`No built-in brand matched "${query}". Run "diagrams brands capture <url> --json", then use the returned digest-pinned brand value.`);
+    return;
+  }
+  const grouped = Map.groupBy
+    ? Map.groupBy(marks, (mark) => mark.category)
+    : marks.reduce((map, mark) => map.set(mark.category, [...(map.get(mark.category) || []), mark]), new Map());
+  for (const [category, entries] of grouped) {
+    console.log(`${category}: ${entries.map((mark) => mark.id).join(', ')}`);
+  }
+}
+
 function commandDemo(args) {
   if (args.length > 1) fail(usage());
 
   const outputDirectory = path.resolve(args[0] || process.cwd());
-  const output = path.join(outputDirectory, 'technical-diagram-demo.html');
+  const output = path.join(outputDirectory, 'technical-diagrams-demo.html');
   const input = path.join(skillRoot, 'examples/web-app.architecture.json');
 
   try {
@@ -187,63 +1555,471 @@ function commandDemo(args) {
     fail(`Could not create demo directory "${outputDirectory}": ${error.message}`, 1);
   }
 
-  const result = runRuntime([rendererPath('architecture'), input, output]);
+  const result = runNode([rendererPath('architecture'), input, output]);
   if (result.status !== 0) exitFrom(result);
 
   console.log(`\nDemo ready: ${output}`);
   console.log('Next: open the HTML in your browser, then render your own diagram:');
-  console.log('  technical-diagrams render architecture <input.json> <output.html>');
+  console.log('  diagrams render architecture <input.json> <output.html>');
+}
+
+function migrationPathDiagnostics(error, sourcePath, destinationPath) {
+  if (Array.isArray(error?.archifyDiagnostics) && error.archifyDiagnostics.length) {
+    return error.archifyDiagnostics.map((entry) => ({
+      ...entry,
+      subject: { ...(entry.subject || {}) },
+      evidence: { ...(entry.evidence || {}) },
+      supportedFixes: [...(entry.supportedFixes || [])],
+    }));
+  }
+  return [diagnostic({
+    code: 'migration/path-preflight',
+    message: 'Could not verify that the workflow migration paths are distinct.',
+    subject: { source: sourcePath, destination: destinationPath },
+    evidence: {
+      ...(error?.code ? { systemCode: error.code } : {}),
+      reason: error?.message || String(error),
+    },
+    supportedFixes: ['remove unsafe path aliases or choose a different destination path'],
+  })];
+}
+
+function migrationReport({
+  ok,
+  sourcePath,
+  destinationPath,
+  sourceBytes,
+  destinationBytes,
+  fromSchemaVersion,
+  preExistingDiagnostics = [],
+  migrationDiagnostics = [],
+  newSchemaDiagnostics = [],
+  changedCoordinates = [],
+  oldRequiredViewBox = null,
+  newRequiredViewBox = null,
+}) {
+  const report = {
+    ok,
+    command: 'migrate',
+    type: 'workflow',
+    source: {
+      path: sourcePath,
+      ...(sourceBytes ? {
+        sha256: createHash('sha256').update(sourceBytes).digest('hex'),
+        bytes: sourceBytes.length,
+      } : {}),
+    },
+    destination: {
+      path: destinationPath,
+      ...(destinationBytes ? {
+        sha256: createHash('sha256').update(destinationBytes).digest('hex'),
+        bytes: destinationBytes.length,
+      } : {}),
+    },
+    fromSchemaVersion: fromSchemaVersion ?? null,
+    toSchemaVersion: 2,
+    preExistingDiagnostics,
+    migrationDiagnostics,
+    newSchemaDiagnostics,
+    changedCoordinates,
+    oldRequiredViewBox,
+    newRequiredViewBox,
+  };
+  if (!ok) {
+    report.diagnostics = [
+      ...migrationDiagnostics,
+      ...newSchemaDiagnostics,
+      ...preExistingDiagnostics,
+    ];
+    if (!report.diagnostics.length) {
+      report.diagnostics.push(diagnostic({
+        code: 'migration/internal',
+        message: 'Workflow migration failed without a classified diagnostic.',
+      }));
+    }
+    report.error = report.diagnostics[0].message;
+  }
+  return report;
+}
+
+function extractMigrationOptions(args) {
+  const positional = [];
+  let json = false;
+  let toSchema;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg === '--to-schema') {
+      toSchema = args[index + 1];
+      if (!toSchema || toSchema.startsWith('--')) fail('--to-schema requires a schema version.');
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('--to-schema=')) {
+      toSchema = arg.slice('--to-schema='.length);
+      if (!toSchema) fail('--to-schema requires a schema version.');
+      continue;
+    }
+    if (arg.startsWith('--')) fail(`Unknown migrate option "${arg}".`);
+    positional.push(arg);
+  }
+  return { positional, json, toSchema };
+}
+
+async function commandMigrate(args) {
+  const options = extractMigrationOptions(args);
+  const [type, sourceArgument, destinationArgument] = options.positional;
+  if (
+    type !== 'workflow'
+    || !sourceArgument
+    || !destinationArgument
+    || options.positional.length !== 3
+    || options.toSchema !== '2'
+  ) {
+    fail('Usage: diagrams migrate workflow <old.json> <new.json> --to-schema 2 [--json]');
+  }
+
+  const sourcePath = path.resolve(sourceArgument);
+  const destinationPath = path.resolve(destinationArgument);
+  let sourceBytes;
+  let sourceDocument;
+  const reportMigrationFailure = ({ status = 1, ...details }) => {
+    const report = migrationReport({
+      ...details,
+      ok: false,
+      sourcePath,
+      destinationPath,
+      sourceBytes,
+      fromSchemaVersion: sourceDocument?.schema_version,
+    });
+    if (options.json) console.log(JSON.stringify(report, null, 2));
+    else console.error(formatDiagnostics(report.error, report.diagnostics));
+    process.exitCode = status;
+  };
+  try {
+    sourceBytes = fs.readFileSync(sourcePath);
+    sourceDocument = JSON.parse(sourceBytes.toString('utf8'));
+  } catch (error) {
+    reportMigrationFailure({
+      preExistingDiagnostics: [inputDiagnostic(error, sourcePath)],
+    });
+    return;
+  }
+  // Unlike render/validate, migrate has no --quality override. Pin every stage
+  // to the document's durable policy and scrub any ambient profile from the
+  // staged renderer by passing this value explicitly.
+  const activeQualityProfile = sourceDocument?.meta?.quality_profile || 'standard';
+
+  const { pathsAlias } = await import('../renderers/shared/output-path.mjs');
+  let sourceDestinationAlias;
+  try {
+    sourceDestinationAlias = pathsAlias(sourcePath, destinationPath);
+  } catch (error) {
+    reportMigrationFailure({
+      migrationDiagnostics: migrationPathDiagnostics(error, sourcePath, destinationPath),
+    });
+    return;
+  }
+  if (sourceDestinationAlias) {
+    reportMigrationFailure({
+      migrationDiagnostics: [diagnostic({
+        code: 'migration/source-destination',
+        message: 'Workflow migration source and destination must be different files.',
+        subject: { source: sourcePath, destination: destinationPath },
+        supportedFixes: ['choose a different destination path and keep the source unchanged'],
+      })],
+    });
+    return;
+  }
+
+  const { migrateWorkflowDocument, serializeMigratedWorkflow } = await import('../migrations/workflow-v2.mjs');
+  let migration;
+  try {
+    migration = migrateWorkflowDocument(sourceDocument);
+  } catch (error) {
+    migration = {
+      ok: false,
+      migrationDiagnostics: [diagnostic({
+        code: 'migration/internal',
+        message: 'Workflow migration failed unexpectedly.',
+        evidence: { reason: error.message },
+        supportedFixes: ['report the source workflow and this diagnostic to the Archify maintainers'],
+      })],
+    };
+  }
+
+  if (!migration.ok) {
+    reportMigrationFailure(migration);
+    return;
+  }
+
+  if (fs.existsSync(destinationPath) && !fs.lstatSync(destinationPath).isFile()) {
+    reportMigrationFailure({
+      ...migration,
+      migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
+        code: 'migration/destination-type',
+        message: 'Workflow migration destination must be a regular file path.',
+        subject: { destination: destinationPath },
+        supportedFixes: ['choose a destination path that is absent or names a regular file'],
+      })],
+    });
+    return;
+  }
+
+  const destinationDirectory = path.dirname(destinationPath);
+  let stagingDirectory;
+  try {
+    fs.mkdirSync(destinationDirectory, { recursive: true });
+    stagingDirectory = fs.mkdtempSync(path.join(destinationDirectory, '.archify-migration-'));
+  } catch (error) {
+    reportMigrationFailure({
+      ...migration,
+      migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
+        code: 'migration/prepare-destination',
+        message: 'Could not prepare the workflow migration destination.',
+        subject: { destination: destinationPath },
+        evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
+        supportedFixes: ['choose a writable destination directory'],
+      })],
+    });
+    return;
+  }
+
+  const candidatePath = path.join(stagingDirectory, 'candidate.workflow.json');
+  const artifactPath = path.join(stagingDirectory, 'migration-check.html');
+  const destinationBytes = Buffer.from(serializeMigratedWorkflow(migration.document));
+  try {
+    fs.writeFileSync(candidatePath, destinationBytes, { flag: 'wx' });
+    const render = runNode([rendererPath('workflow'), candidatePath, artifactPath], {
+      stdio: 'pipe',
+      env: rendererEnv(activeQualityProfile, undefined, true),
+    });
+    if (render.status !== 0) {
+      const failure = rendererFailure(render);
+      reportMigrationFailure({
+        ...migration,
+        newSchemaDiagnostics: [...migration.newSchemaDiagnostics, ...failure.diagnostics],
+        status: render.status ?? 1,
+      });
+      return;
+    }
+
+    const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), artifactPath], {
+      stdio: 'pipe',
+    });
+    if (check.status !== 0) {
+      let checker;
+      try {
+        checker = JSON.parse(check.stdout);
+      } catch {
+        checker = null;
+      }
+      reportMigrationFailure({
+        ...migration,
+        newSchemaDiagnostics: [
+          ...migration.newSchemaDiagnostics,
+          ...checkerDiagnostics(checker),
+        ],
+        status: check.status ?? 1,
+      });
+      return;
+    }
+
+    if (pathsAlias(sourcePath, destinationPath)) {
+      reportMigrationFailure({
+        ...migration,
+        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
+          code: 'migration/source-destination',
+          message: 'Workflow migration source and destination resolved to the same file before commit.',
+          subject: { source: sourcePath, destination: destinationPath },
+          supportedFixes: ['choose a different destination path and retry'],
+        })],
+      });
+      return;
+    }
+    const currentSourceBytes = fs.readFileSync(sourcePath);
+    if (!currentSourceBytes.equals(sourceBytes)) {
+      reportMigrationFailure({
+        ...migration,
+        migrationDiagnostics: [...migration.migrationDiagnostics, diagnostic({
+          code: 'migration/source-changed',
+          message: 'Workflow migration source changed while the destination was being verified.',
+          subject: { source: sourcePath },
+          supportedFixes: ['retry the migration from a stable workflow source file'],
+        })],
+      });
+      return;
+    }
+
+    fs.renameSync(candidatePath, destinationPath);
+    const report = migrationReport({
+      ...migration,
+      sourcePath,
+      destinationPath,
+      sourceBytes,
+      destinationBytes,
+      fromSchemaVersion: sourceDocument.schema_version,
+    });
+    if (options.json) console.log(JSON.stringify(report, null, 2));
+    else if (sourceDocument.schema_version === 1) {
+      console.log(`migrated workflow schema v1→v2: ${sourcePath} → ${destinationPath}`);
+    } else {
+      console.log(`verified workflow schema v2 migration: ${sourcePath} → ${destinationPath}`);
+    }
+  } catch (error) {
+    const migrationDiagnostics = Array.isArray(error?.archifyDiagnostics)
+      ? migrationPathDiagnostics(error, sourcePath, destinationPath)
+      : [diagnostic({
+        code: 'migration/commit',
+        message: 'Could not commit the verified workflow migration.',
+        subject: { destination: destinationPath },
+        evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },
+        supportedFixes: ['choose a writable regular-file destination and retry'],
+      })];
+    reportMigrationFailure({
+      ...migration,
+      migrationDiagnostics: [...migration.migrationDiagnostics, ...migrationDiagnostics],
+    });
+  } finally {
+    try {
+      fs.rmSync(stagingDirectory, { recursive: true, force: true });
+    } catch (error) {
+      console.error(`Warning: could not remove workflow migration staging directory "${stagingDirectory}": ${error.message}`);
+    }
+  }
 }
 
 function commandValidate(args) {
+  const qualityArgs = extractQualityArgs(args);
+  const repoArgs = extractRepoRootArgs(qualityArgs.rest);
+  args = repoArgs.rest;
+  const quality = qualityArgs.quality;
+  const repoRoot = repoArgs.repoRoot;
+  const knownOptions = new Set(['--json', '--layout-json']);
+  const unknown = args.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));
+  if (unknown.length) rejectCliArgument(`Unknown validate option "${unknown[0]}".`, {
+    code: 'cli/unknown-option',
+    subject: { option: unknown[0] },
+    supportedFixes: ['remove the unknown option and retry'],
+  });
   const json = args.includes('--json');
   const layoutJson = args.includes('--layout-json');
-  const rest = args.filter((arg) => arg !== '--json' && arg !== '--layout-json');
+  const rest = args.filter((arg) => !knownOptions.has(arg));
   const [type, input] = rest;
-  if (!type || !input) fail(usage());
+  if (!type || !input || rest.length !== 2) rejectCliArgument(usage(), {
+    code: 'cli/usage',
+    supportedFixes: ['use: diagrams validate <type> <input.json> [options]'],
+  });
+  assertEvidenceType(type, repoRoot);
   const renderer = rendererPath(type);
 
+  if (layoutJson && !['architecture', 'workflow'].includes(type)) {
+    rejectCliArgument('--layout-json is currently supported for architecture and workflow diagrams only.', {
+      code: 'cli/unsupported-option',
+      subject: { option: '--layout-json', type },
+      supportedFixes: ['remove --layout-json or use an architecture or workflow diagram'],
+    });
+  }
+
   if (layoutJson) {
-    if (type !== 'architecture') {
-      fail('--layout-json is currently supported for architecture diagrams only.');
-    }
-    const result = runRuntime([renderer, input, '/dev/null', '--layout-json'], { stdio: 'pipe' });
+    // Layout mode emits JSON without writing HTML; keep its unused target typed.
+    const layoutOutput = path.join(os.tmpdir(), `archify-layout-${process.pid}-${type}.html`);
+    const result = runNode([renderer, input, layoutOutput, '--layout-json'], {
+      stdio: 'pipe',
+      env: rendererEnv(quality, repoRoot, true),
+    });
     if (result.status !== 0) {
-      if (result.stderr) process.stderr.write(result.stderr);
-      if (result.stdout) process.stdout.write(result.stdout);
-      process.exit(result.status ?? 1);
+      try {
+        const receipt = JSON.parse(result.stdout);
+        if (receipt?.contract && Array.isArray(receipt.diagnostics)) {
+          process.stdout.write(`${JSON.stringify(receipt, null, 2)}\n`);
+          process.exitCode = result.status ?? 1;
+          return;
+        }
+      } catch {
+        // Fall through to the renderer failure contract when no compiler
+        // receipt was produced (for example, input JSON could not be read).
+      }
+      const failure = rendererFailure(result);
+      reportValidateFailure({
+        json,
+        stage: failure.diagnostics.some((entry) => entry.code.startsWith('input/')) ? 'input' : 'render',
+        type,
+        input: path.resolve(input),
+        error: failure.error,
+        diagnostics: failure.diagnostics,
+        status: result.status ?? 1,
+      });
+      return;
     }
     process.stdout.write(result.stdout);
     return;
   }
 
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'technical-diagrams-validate-'));
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-validate-'));
   const out = path.join(tmp, `${type}.html`);
   let exitCode = 0;
 
   try {
-    const render = runRuntime([renderer, input, out], { stdio: 'pipe' });
+    const render = runNode([renderer, input, out], {
+      stdio: 'pipe',
+      env: rendererEnv(quality, repoRoot, true),
+    });
     if (render.status !== 0) {
-      if (render.stderr) process.stderr.write(render.stderr);
-      if (render.stdout) process.stdout.write(render.stdout);
+      const failure = rendererFailure(render);
+      reportValidateFailure({
+        json,
+        stage: failure.diagnostics.some((entry) => entry.code.startsWith('input/')) ? 'input' : 'render',
+        type,
+        input: path.resolve(input),
+        error: failure.error,
+        diagnostics: failure.diagnostics,
+        status: render.status ?? 1,
+      });
       exitCode = render.status ?? 1;
     } else {
-      const check = runRuntime([path.join(skillRoot, 'scripts/check-render-output.mjs'), out], { stdio: 'pipe' });
+      const check = runNode([path.join(skillRoot, 'scripts/check-render-output.mjs'), out], { stdio: 'pipe' });
       if (check.status !== 0) {
-        if (check.stdout) process.stdout.write(check.stdout);
-        if (check.stderr) process.stderr.write(check.stderr);
+        let checker;
+        try {
+          checker = JSON.parse(check.stdout);
+          checker.file = path.resolve(input);
+        } catch {
+          checker = { ok: false, diagnostic: 'Artifact checker failed without a parseable receipt.' };
+        }
+        reportValidateFailure({
+          json,
+          stage: 'check',
+          type,
+          input: path.resolve(input),
+          error: 'Final artifact check failed.',
+          diagnostics: checkerDiagnostics(checker),
+          checker,
+          status: check.status ?? 1,
+        });
         exitCode = check.status ?? 1;
       } else {
         const result = JSON.parse(check.stdout);
+        const engineeringProfile = engineeringProfileFromArtifact(fs.readFileSync(out));
         if (json) {
           console.log(JSON.stringify({
+            schemaVersion: 1,
             ok: true,
+            command: 'validate',
             type,
             input: path.resolve(input),
             checks: result.checks,
+            composition: result.composition,
+            ...(engineeringProfile ? { engineeringProfile } : {}),
           }, null, 2));
         } else {
-          console.log(`ok ${type} ${path.resolve(input)} (${result.checks.length} checks)`);
+          const engineering = engineeringProfile
+            ? `; engineering ${engineeringProfile}: pass`
+            : '';
+          console.log(`ok ${type} ${path.resolve(input)} (${result.checks.length} artifact checks; composition ${result.composition.profile}: ${result.composition.summary.errors} errors, ${result.composition.summary.warnings} warnings${engineering})`);
         }
       }
     }
@@ -251,39 +2027,72 @@ function commandValidate(args) {
     fs.rmSync(tmp, { recursive: true, force: true });
   }
 
-  if (exitCode !== 0) process.exit(exitCode);
+  if (exitCode !== 0) process.exitCode = exitCode;
 }
 
 const [command, ...args] = process.argv.slice(2);
 
-switch (command) {
-  case undefined:
-  case '-h':
-  case '--help':
-  case 'help':
-    console.log(usage());
-    break;
-  case 'render':
-    commandRender(args);
-    break;
-  case 'validate':
-    commandValidate(args);
-    break;
-  case 'inspect':
-    commandValidate([...args, '--layout-json']);
-    break;
-  case 'check':
-    commandCheck(args);
-    break;
-  case 'examples':
-    commandExamples(args);
-    break;
-  case 'doctor':
-    await commandDoctor();
-    break;
-  case 'demo':
-    commandDemo(args);
-    break;
-  default:
-    fail(`Unknown command "${command}".\n\n${usage()}`);
+try {
+  switch (command) {
+    case undefined:
+    case '-h':
+    case '--help':
+    case 'help':
+      console.log(usage());
+      break;
+    case 'render':
+      commandRender(args);
+      break;
+    case 'compare':
+      await commandCompare(args);
+      break;
+    case 'deliver':
+      await commandDeliver(args);
+      break;
+    case 'preview':
+      await commandPreview(args);
+      break;
+    case 'validate':
+      commandValidate(args);
+      break;
+    case 'migrate':
+      await commandMigrate(args);
+      break;
+    case 'inspect':
+      if (args[0] !== 'architecture') {
+        fail('inspect is currently supported for architecture diagrams only.');
+      }
+      commandValidate([...args, '--layout-json']);
+      break;
+    case 'check':
+      commandCheck(args);
+      break;
+    case 'visual-check':
+      await commandVisualCheck(args);
+      break;
+    case 'guide':
+      await commandGuide(args);
+      break;
+    case 'brands':
+      await commandBrands(args);
+      break;
+    case 'examples':
+      commandExamples(args);
+      break;
+    case 'doctor':
+      await commandDoctor();
+      break;
+    case 'demo':
+      commandDemo(args);
+      break;
+    default:
+      fail(`Unknown command "${command}".\n\n${usage()}`);
+  }
+} catch (error) {
+  if (!error.archifyArgument) throw error;
+  if (['validate', 'deliver'].includes(command) && args.includes('--json')) {
+    reportArtifactArgumentFailure(command, error);
+  } else {
+    fail(error.message);
+  }
 }