infernoflow 0.19.0 → 0.20.0

package/dist/bin/infernoflow.mjs

@@ -45,6 +45,10 @@ const COMMAND_DESCRIPTIONS = {
   monorepo: "Manage infernoflow across monorepo packages (init | list | status | diff | sync)",
   link:    "Link capabilities to Jira, Linear, or GitHub Issues tickets",
   audit:   "Classify capabilities by sensitivity (auth, payment, PII, admin) and generate security surface map",
+  scout:   "Scan source files for undocumented capabilities not yet in the contract",
+  export:  "Export contract to OpenAPI, Backstage catalog-info.yaml, CSV, or Markdown",
+  snapshot: "Save/diff/restore named snapshots of the capability contract",
+  health:  "Compute a 0–100 health score across coverage, docs, freshness, completeness, drift",
 };
 
 const COMMAND_HANDLERS = {
@@ -82,7 +86,11 @@ const COMMAND_HANDLERS = {
   report:  async (args) => (await import("../lib/commands/report.mjs")).reportCommand(args),
   monorepo: async (args) => (await import("../lib/commands/monorepo.mjs")).monorepoCommand(args),
   link:    async (args) => (await import("../lib/commands/link.mjs")).linkCommand(args),
-  audit:   async (args) => (await import("../lib/commands/audit.mjs")).auditCommand(args),
+  audit:    async (args) => (await import("../lib/commands/audit.mjs")).auditCommand(args),
+  scout:    async (args) => (await import("../lib/commands/scout.mjs")).scoutCommand(args),
+  export:   async (args) => (await import("../lib/commands/export.mjs")).exportCommand(args),
+  snapshot: async (args) => (await import("../lib/commands/snapshot.mjs")).snapshotCommand(args),
+  health:   async (args) => (await import("../lib/commands/health.mjs")).healthCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -279,6 +287,34 @@ ${formatCommandsHelp()}
     --fail-on high|medium     Exit 1 if unreviewed caps at given severity exist
     --json                    Machine-readable output
 
+  ${bold("scout options:")}
+    --dir <dirs>              Comma-separated directories to scan (default: src,lib,app,api,routes)
+    --apply                   Write discovered capabilities to the contract file
+    --min-confidence <0-1>    Minimum confidence threshold (default: 0.6)
+    --json                    Machine-readable output
+
+  ${bold("export options:")}
+    --format openapi|backstage|csv|markdown|json   Output format (required)
+    --out <path>              Output file path (default: project root, auto-named)
+    --json                    Machine-readable summary
+
+  ${bold("snapshot sub-commands:")}
+    save <name>               Save current contract as a named snapshot
+    list                      List all snapshots
+    show <name>               Print a snapshot's capabilities
+    diff <name1> [<name2>]    Diff two snapshots (omit name2 to diff against current)
+    restore <name>            Overwrite contract with snapshot contents
+    delete <name>             Delete a snapshot
+
+  ${bold("snapshot options:")}
+    --json                    Machine-readable output
+
+  ${bold("health options:")}
+    --fail-below <score>      Exit 1 if health score is below this threshold (CI gate)
+    --watch                   Re-run every 30s (live terminal view)
+    --interval <secs>         Watch interval in seconds (default: 30)
+    --json                    Machine-readable score + breakdown
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/export.mjs

@@ -0,0 +1,239 @@
+/**
+ * infernoflow export
+ *
+ * Export the capability contract to external formats so it can travel
+ * outside the repo — into API docs, service catalogs, spreadsheets, wikis.
+ *
+ * Formats:
+ *   openapi      OpenAPI 3.1 JSON (stubs for each capability)
+ *   backstage    Backstage catalog-info.yaml
+ *   csv          Spreadsheet-ready CSV
+ *   markdown     Confluence/Notion-ready Markdown table
+ *   json         Clean JSON (normalised, no internal infernoflow fields)
+ *
+ * Usage:
+ *   infernoflow export --format openapi
+ *   infernoflow export --format backstage --out catalog-info.yaml
+ *   infernoflow export --format csv --out capabilities.csv
+ *   infernoflow export --format markdown
+ *   infernoflow export --format json --out contract-export.json
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { done, warn, info, bold, cyan, gray } from "../ui/output.mjs";
+
+// ── Contract reader ───────────────────────────────────────────────────────────
+
+function readContract(infernoDir) {
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+  }
+  return null;
+}
+
+function normaliseCaps(contract) {
+  const raw = contract?.capabilities || [];
+  return raw.map(c => {
+    if (typeof c === "string") return { id: c, description: "", tags: [], status: "active" };
+    return {
+      id:          c.id || c.name || "unknown",
+      description: c.description || "",
+      tags:        c.tags || [],
+      status:      c.status || "active",
+      since:       c.since || "",
+      owner:       c.owner || "",
+    };
+  });
+}
+
+function readMeta(infernoDir) {
+  const pkgPath = path.join(path.dirname(infernoDir), "package.json");
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return { name: pkg.name || "my-service", version: pkg.version || "0.0.0", description: pkg.description || "" };
+  } catch {
+    return { name: path.basename(path.dirname(infernoDir)), version: "0.0.0", description: "" };
+  }
+}
+
+// ── Formatters ────────────────────────────────────────────────────────────────
+
+function toOpenApi(caps, meta) {
+  const paths = {};
+  for (const cap of caps) {
+    const route = `/${cap.id.replace(/_/g, "-")}`;
+    paths[route] = {
+      get: {
+        operationId: cap.id,
+        summary:     cap.description || cap.id,
+        tags:        cap.tags.length ? cap.tags : [meta.name],
+        parameters:  [],
+        responses: {
+          "200": { description: "Success", content: { "application/json": { schema: { type: "object" } } } },
+          "401": { description: "Unauthorized" },
+          "500": { description: "Internal Server Error" },
+        },
+      },
+    };
+  }
+
+  return JSON.stringify({
+    openapi: "3.1.0",
+    info: {
+      title:       meta.name,
+      version:     meta.version,
+      description: meta.description || `Capability contract for ${meta.name}`,
+    },
+    paths,
+    components: { schemas: {}, securitySchemes: {} },
+  }, null, 2);
+}
+
+function toBackstage(caps, meta) {
+  const tags = [...new Set(caps.flatMap(c => c.tags))].slice(0, 10);
+  const lines = [
+    `apiVersion: backstage.io/v1alpha1`,
+    `kind: Component`,
+    `metadata:`,
+    `  name: ${meta.name}`,
+    `  description: "${(meta.description || meta.name).replace(/"/g, '\\"')}"`,
+    `  annotations:`,
+    `    infernoflow/capability-count: "${caps.length}"`,
+    `    infernoflow/generated-at: "${new Date().toISOString()}"`,
+    tags.length ? `  tags:\n${tags.map(t => `    - ${t}`).join("\n")}` : "",
+    `spec:`,
+    `  type: service`,
+    `  lifecycle: production`,
+    `  owner: team-default`,
+    `  providesApis: []`,
+    `---`,
+    `# Capabilities`,
+    ...caps.map(c => [
+      `# ${c.id}`,
+      `#   ${c.description || "(no description)"}`,
+      `#   tags: ${c.tags.join(", ") || "none"}`,
+      `#   status: ${c.status}`,
+    ].join("\n")),
+  ].filter(Boolean);
+  return lines.join("\n") + "\n";
+}
+
+function toCsv(caps) {
+  const header = ["id", "description", "tags", "status", "since", "owner"];
+  const rows   = caps.map(c => [
+    c.id,
+    (c.description || "").replace(/"/g, '""'),
+    c.tags.join("|"),
+    c.status,
+    c.since,
+    c.owner,
+  ].map(v => `"${v}"`).join(","));
+  return [header.join(","), ...rows].join("\n") + "\n";
+}
+
+function toMarkdown(caps, meta) {
+  const lines = [
+    `# ${meta.name} — Capability Contract`,
+    ``,
+    `> Generated by infernoflow on ${new Date().toISOString().slice(0, 10)}`,
+    `> ${caps.length} capabilities tracked`,
+    ``,
+    `| Capability | Description | Tags | Status |`,
+    `|---|---|---|---|`,
+    ...caps.map(c =>
+      `| \`${c.id}\` | ${c.description || ""} | ${c.tags.join(", ") || "—"} | ${c.status} |`
+    ),
+    ``,
+  ];
+  return lines.join("\n");
+}
+
+function toCleanJson(caps, meta) {
+  return JSON.stringify({
+    name:        meta.name,
+    version:     meta.version,
+    exportedAt:  new Date().toISOString(),
+    capabilities: caps,
+  }, null, 2) + "\n";
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+const FORMAT_EXT = {
+  openapi:   "openapi.json",
+  backstage: "catalog-info.yaml",
+  csv:       "capabilities.csv",
+  markdown:  "capabilities.md",
+  json:      "capabilities-export.json",
+};
+
+export async function exportCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json");
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ not found. Run: infernoflow init";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  const fmtIdx   = args.indexOf("--format");
+  const format   = fmtIdx !== -1 ? args[fmtIdx + 1] : null;
+  const outIdx   = args.indexOf("--out");
+  const outArg   = outIdx !== -1 ? args[outIdx + 1] : null;
+
+  const validFormats = Object.keys(FORMAT_EXT);
+
+  if (!format || !validFormats.includes(format)) {
+    const msg = `Usage: infernoflow export --format <${validFormats.join("|")}> [--out <path>]`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else {
+      warn(msg);
+      console.log();
+      console.log(`  ${gray("Available formats:")}`);
+      console.log(`  ${bold("openapi")}   — OpenAPI 3.1 JSON with a stub path per capability`);
+      console.log(`  ${bold("backstage")} — Backstage catalog-info.yaml component definition`);
+      console.log(`  ${bold("csv")}       — Spreadsheet-ready CSV`);
+      console.log(`  ${bold("markdown")} — Confluence/Notion table`);
+      console.log(`  ${bold("json")}      — Clean normalised JSON`);
+      console.log();
+    }
+    return;
+  }
+
+  const contract = readContract(infernoDir);
+  if (!contract) {
+    const msg = "No contract.json or capabilities.json found.";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  const caps = normaliseCaps(contract);
+  const meta = readMeta(infernoDir);
+  const outPath = outArg || path.join(cwd, FORMAT_EXT[format]);
+
+  let output;
+  switch (format) {
+    case "openapi":   output = toOpenApi(caps, meta);   break;
+    case "backstage": output = toBackstage(caps, meta); break;
+    case "csv":       output = toCsv(caps);             break;
+    case "markdown":  output = toMarkdown(caps, meta);  break;
+    case "json":      output = toCleanJson(caps, meta); break;
+  }
+
+  fs.writeFileSync(outPath, output);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, format, file: outPath, capabilities: caps.length }));
+  } else {
+    done(`Exported ${bold(String(caps.length))} capabilities → ${cyan(path.relative(cwd, outPath))}`);
+    console.log();
+  }
+}

package/dist/lib/commands/health.mjs

@@ -0,0 +1,309 @@
+/**
+ * infernoflow health
+ *
+ * Computes a weighted 0–100 health score for the capability contract.
+ * Breaks it down across five dimensions so you know exactly where to improve.
+ *
+ * Dimensions:
+ *   Coverage      % of capabilities that have descriptions      (weight 25)
+ *   Documentation % with at least one scenario/test             (weight 20)
+ *   Freshness     How recently the contract was updated          (weight 20)
+ *   Completeness  Version field, owner, tags present            (weight 15)
+ *   Drift risk    Open issues from `infernoflow check`           (weight 20)
+ *
+ * Usage:
+ *   infernoflow health                  Print score + breakdown
+ *   infernoflow health --json           Machine-readable
+ *   infernoflow health --fail-below 70  Exit 1 if score < 70 (CI gate)
+ *   infernoflow health --watch          Re-run every 30s (for terminals)
+ */
+
+import * as fs          from "node:fs";
+import * as path        from "node:path";
+import { execSync }     from "node:child_process";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+const WEIGHTS = {
+  coverage:      25,
+  documentation: 20,
+  freshness:     20,
+  completeness:  15,
+  drift:         20,
+};
+
+// ── Readers ───────────────────────────────────────────────────────────────────
+
+function readContract(infernoDir) {
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+  }
+  return null;
+}
+
+function readScenarios(infernoDir) {
+  const scenDir = path.join(infernoDir, "scenarios");
+  if (!fs.existsSync(scenDir)) return [];
+  return fs.readdirSync(scenDir)
+    .filter(f => f.endsWith(".json"))
+    .flatMap(f => {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(scenDir, f), "utf8"));
+        return data.capability ? [data.capability] : (data.capabilities || []);
+      } catch { return []; }
+    });
+}
+
+function runCheck(cwd) {
+  try {
+    const out = execSync("npx infernoflow check --json", {
+      cwd, encoding: "utf8", timeout: 15_000, stdio: ["ignore", "pipe", "pipe"],
+    });
+    return JSON.parse(out);
+  } catch (err) {
+    try { return JSON.parse(err.stdout || "{}"); } catch { return {}; }
+  }
+}
+
+function lastModifiedDaysAgo(infernoDir) {
+  const files = ["contract.json", "capabilities.json"]
+    .map(f => path.join(infernoDir, f))
+    .filter(fs.existsSync);
+  if (!files.length) return 999;
+  const mtime = Math.max(...files.map(f => fs.statSync(f).mtimeMs));
+  return (Date.now() - mtime) / (1000 * 60 * 60 * 24);
+}
+
+// ── Scorers ───────────────────────────────────────────────────────────────────
+
+function scoreCoverage(caps) {
+  if (!caps.length) return { score: 0, detail: "No capabilities" };
+  const withDesc = caps.filter(c => c.description && c.description.length > 5).length;
+  const pct = Math.round((withDesc / caps.length) * 100);
+  return {
+    score:  pct,
+    detail: `${withDesc}/${caps.length} capabilities have descriptions`,
+    pct,
+  };
+}
+
+function scoreDocumentation(caps, scenarioCaps) {
+  if (!caps.length) return { score: 0, detail: "No capabilities" };
+  const scenSet = new Set(scenarioCaps.map(s => String(s).toLowerCase()));
+  const withScen = caps.filter(c => scenSet.has(c.id.toLowerCase())).length;
+  const pct = Math.round((withScen / caps.length) * 100);
+  return {
+    score:  Math.min(100, pct + (scenSet.size === 0 ? 0 : 10)), // bonus for having any scenarios
+    detail: `${withScen}/${caps.length} capabilities have test scenarios`,
+    pct,
+  };
+}
+
+function scoreFreshness(daysAgo) {
+  let score;
+  let label;
+  if (daysAgo <= 1)   { score = 100; label = "updated today"; }
+  else if (daysAgo <= 3)  { score = 95;  label = `updated ${Math.round(daysAgo)}d ago`; }
+  else if (daysAgo <= 7)  { score = 85;  label = `updated ${Math.round(daysAgo)}d ago`; }
+  else if (daysAgo <= 14) { score = 70;  label = `updated ${Math.round(daysAgo)}d ago`; }
+  else if (daysAgo <= 30) { score = 50;  label = `updated ${Math.round(daysAgo)}d ago`; }
+  else if (daysAgo <= 60) { score = 30;  label = `updated ${Math.round(daysAgo)}d ago — stale`; }
+  else                    { score = 10;  label = `not updated in ${Math.round(daysAgo)}d — very stale`; }
+  return { score, detail: label };
+}
+
+function scoreCompleteness(caps, contract) {
+  if (!caps.length) return { score: 0, detail: "No capabilities" };
+  const hasVersion = !!(contract?.version || contract?.contractVersion);
+  const withTags   = caps.filter(c => c.tags?.length).length;
+  const withOwner  = caps.filter(c => c.owner).length;
+  const withSince  = caps.filter(c => c.since).length;
+
+  const tagPct   = Math.round((withTags  / caps.length) * 100);
+  const ownerPct = Math.round((withOwner / caps.length) * 100);
+  const sincePct = Math.round((withSince / caps.length) * 100);
+
+  const score = Math.round(
+    (hasVersion ? 20 : 0) +
+    tagPct   * 0.3 +
+    ownerPct * 0.3 +
+    sincePct * 0.2
+  );
+
+  return {
+    score: Math.min(100, score),
+    detail: `version: ${hasVersion ? "✓" : "✗"}, tags: ${tagPct}%, owner: ${ownerPct}%, since: ${sincePct}%`,
+  };
+}
+
+function scoreDrift(checkResult) {
+  const issues   = checkResult?.issues || [];
+  const warnings = issues.filter(i => (i.severity || i.level || "error") === "warning").length;
+  const errors   = issues.filter(i => (i.severity || i.level || "error") === "error").length;
+  const status   = checkResult?.status;
+
+  if (status === "ok" || (!errors && !warnings)) return { score: 100, detail: "No issues found" };
+
+  const score = Math.max(0, 100 - (errors * 20) - (warnings * 8));
+  return {
+    score,
+    detail: `${errors} error${errors !== 1 ? "s" : ""}, ${warnings} warning${warnings !== 1 ? "s" : ""}`,
+  };
+}
+
+// ── Aggregate ─────────────────────────────────────────────────────────────────
+
+function computeHealth(infernoDir, cwd) {
+  const contract     = readContract(infernoDir);
+  const caps         = (contract?.capabilities || []).map(c =>
+    typeof c === "string" ? { id: c, description: "", tags: [], owner: "", since: "" } : c
+  );
+  const scenarioCaps = readScenarios(infernoDir);
+  const daysAgo      = lastModifiedDaysAgo(infernoDir);
+  const checkResult  = runCheck(cwd);
+
+  const dimensions = {
+    coverage:      scoreCoverage(caps),
+    documentation: scoreDocumentation(caps, scenarioCaps),
+    freshness:     scoreFreshness(daysAgo),
+    completeness:  scoreCompleteness(caps, contract),
+    drift:         scoreDrift(checkResult),
+  };
+
+  const totalScore = Math.round(
+    Object.entries(dimensions).reduce((sum, [key, dim]) => {
+      return sum + (dim.score * WEIGHTS[key]) / 100;
+    }, 0)
+  );
+
+  return { totalScore, dimensions, caps, daysAgo, checkResult };
+}
+
+// ── Renderer ──────────────────────────────────────────────────────────────────
+
+function scoreColor(score) {
+  if (score >= 80) return green;
+  if (score >= 60) return yellow;
+  return red;
+}
+
+function scoreGrade(score) {
+  if (score >= 90) return "A";
+  if (score >= 80) return "B";
+  if (score >= 70) return "C";
+  if (score >= 60) return "D";
+  return "F";
+}
+
+function barOf(score, width = 30) {
+  const filled = Math.round((score / 100) * width);
+  const empty  = width - filled;
+  return "█".repeat(filled) + "░".repeat(empty);
+}
+
+function printReport(totalScore, dimensions) {
+  const col   = scoreColor(totalScore);
+  const grade = scoreGrade(totalScore);
+
+  console.log();
+  console.log(`  ${bold("🔥 infernoflow health score")}`);
+  console.log();
+  console.log(`  ${col(bold(String(totalScore)))} / 100   ${col(bold(grade))}   ${col(barOf(totalScore))}`);
+  console.log();
+
+  const dimNames = {
+    coverage:      "Coverage     ",
+    documentation: "Docs/Tests   ",
+    freshness:     "Freshness    ",
+    completeness:  "Completeness ",
+    drift:         "Drift risk   ",
+  };
+
+  for (const [key, dim] of Object.entries(dimensions)) {
+    const w  = WEIGHTS[key];
+    const sc = dim.score;
+    const c  = scoreColor(sc);
+    const bar = barOf(sc, 20);
+    const weighted = Math.round((sc * w) / 100);
+    console.log(
+      `  ${bold(dimNames[key])} ${c(String(sc).padStart(3))}   ${c(bar)}  ${gray(`×${w}% = ${weighted}pts  ${dim.detail}`)}`
+    );
+  }
+  console.log();
+}
+
+function printTips(totalScore, dimensions) {
+  const tips = [];
+
+  if (dimensions.coverage.score < 70)
+    tips.push("Add descriptions to your capabilities in contract.json");
+  if (dimensions.documentation.score < 60)
+    tips.push("Create scenario files in inferno/scenarios/ for each capability");
+  if (dimensions.freshness.score < 70)
+    tips.push("Run `infernoflow suggest` to sync recent changes to the contract");
+  if (dimensions.completeness.score < 60)
+    tips.push("Add version, tags, owner, and since fields to your capabilities");
+  if (dimensions.drift.score < 80)
+    tips.push("Run `infernoflow check` and fix the reported issues");
+
+  if (tips.length) {
+    console.log(`  ${bold("Tips to improve:")}`);
+    tips.forEach(t => console.log(`  ${yellow("·")} ${t}`));
+    console.log();
+  }
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function healthCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json");
+  const watchMode = args.includes("--watch");
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ not found. Run: infernoflow init";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  const failBelowIdx = args.indexOf("--fail-below");
+  const failBelow    = failBelowIdx !== -1 ? parseInt(args[failBelowIdx + 1], 10) : null;
+
+  const intervalIdx  = args.indexOf("--interval");
+  const intervalSecs = intervalIdx !== -1 ? parseInt(args[intervalIdx + 1], 10) : 30;
+
+  const runOnce = () => {
+    const { totalScore, dimensions } = computeHealth(infernoDir, cwd);
+
+    if (jsonMode) {
+      const dimFlat = Object.fromEntries(
+        Object.entries(dimensions).map(([k, v]) => [k, { score: v.score, detail: v.detail, weight: WEIGHTS[k] }])
+      );
+      console.log(JSON.stringify({ ok: true, score: totalScore, grade: scoreGrade(totalScore), dimensions: dimFlat }));
+    } else {
+      if (watchMode) process.stdout.write("\x1Bc"); // clear screen
+      printReport(totalScore, dimensions);
+      if (!watchMode) printTips(totalScore, dimensions);
+    }
+
+    if (failBelow !== null && totalScore < failBelow) {
+      if (!jsonMode) console.error(red(`  ✗  Score ${totalScore} is below threshold ${failBelow} — failing.\n`));
+      process.exit(1);
+    }
+
+    return totalScore;
+  };
+
+  if (watchMode) {
+    if (!jsonMode) info(`Watching health score every ${intervalSecs}s — press Ctrl+C to stop`);
+    runOnce();
+    setInterval(runOnce, intervalSecs * 1000);
+    await new Promise(() => {});
+  } else {
+    runOnce();
+  }
+}

package/dist/lib/commands/scout.mjs

@@ -0,0 +1,291 @@
+/**
+ * infernoflow scout
+ *
+ * Scans your source files for undocumented capabilities — functions, routes,
+ * exports, controllers — that exist in code but are missing from the contract.
+ *
+ * Smarter than --adopt: it reads your existing contract, diffs against what
+ * it finds in source, and only surfaces genuine gaps.
+ *
+ * Usage:
+ *   infernoflow scout                   Scan src/, lib/, app/ (auto-detected)
+ *   infernoflow scout --dir src,api     Custom scan directories
+ *   infernoflow scout --apply           Write discovered caps to capabilities.json
+ *   infernoflow scout --json            Machine-readable output
+ *   infernoflow scout --min-confidence 0.7   Only show high-confidence hits
+ *
+ * Output:
+ *   Lists undocumented capabilities with confidence score + source location.
+ *   With --apply, merges them into the contract file.
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── Pattern library ───────────────────────────────────────────────────────────
+
+const PATTERNS = [
+  // Express / Fastify / Hono routes
+  {
+    name: "http-route",
+    regex: /(?:app|router|server)\s*\.\s*(get|post|put|patch|delete|head|options)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+    extract: (m) => ({ id: routeToId(m[2], m[1]), hint: `${m[1].toUpperCase()} ${m[2]}`, confidence: 0.85 }),
+  },
+  // Next.js / Nuxt API route files  (path from filename)
+  {
+    name: "api-file",
+    filePattern: /[/\\](pages[/\\]api|app[/\\]api)[/\\](.+)\.(js|ts|mjs)$/,
+    extract: (filePath) => {
+      const m = filePath.match(/[/\\](pages[/\\]api|app[/\\]api)[/\\](.+)\.(js|ts|mjs)$/);
+      if (!m) return null;
+      const route = m[2].replace(/[/\\]index$/, "").replace(/\[([^\]]+)\]/g, ":$1");
+      return { id: routeToId("/" + route, "api"), hint: `Next.js API: /${route}`, confidence: 0.9 };
+    },
+  },
+  // Named exports (functions, classes, consts)
+  {
+    name: "export",
+    regex: /export\s+(?:async\s+)?(?:function|class|const|let)\s+([A-Z][A-Za-z0-9]+)/g,
+    extract: (m) => ({ id: camelToId(m[1]), hint: `export ${m[1]}`, confidence: 0.65 }),
+  },
+  // Default export object keys (controller-style)
+  {
+    name: "controller-method",
+    regex: /^\s{2,}(?:async\s+)?([a-z][A-Za-z0-9]+)\s*[:(]/gm,
+    extract: (m) => ({ id: camelToId(m[1]), hint: `method ${m[1]}`, confidence: 0.5 }),
+    minLen: 5,
+  },
+  // GraphQL resolver fields
+  {
+    name: "graphql-resolver",
+    regex: /['"`]?([A-Za-z][A-Za-z0-9]+)['"`]?\s*:\s*(?:async\s+)?\([^)]*\)\s*(?:=>|{)/g,
+    extract: (m) => ({ id: camelToId(m[1]), hint: `resolver ${m[1]}`, confidence: 0.6 }),
+  },
+  // Django / Flask URL patterns
+  {
+    name: "python-route",
+    regex: /(?:path|url|re_path)\s*\(\s*['"`]([^'"`]+)['"`]\s*,\s*([A-Za-z0-9_.]+)/g,
+    extract: (m) => ({ id: routeToId(m[1], "view"), hint: `view ${m[2]} @ ${m[1]}`, confidence: 0.8 }),
+  },
+  // Rails routes
+  {
+    name: "rails-route",
+    regex: /(?:get|post|put|patch|delete)\s+['"`]([^'"`]+)['"`]\s*,\s*to:\s*['"`]([^'"`]+)['"`]/g,
+    extract: (m) => ({ id: routeToId(m[1], "rails"), hint: `Rails: ${m[2]}`, confidence: 0.8 }),
+  },
+];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function routeToId(route, method) {
+  return route
+    .replace(/^\//, "")
+    .replace(/\/:?[^/]+/g, "")    // strip params
+    .replace(/\//g, "-")
+    .replace(/[^a-zA-Z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase() || method.toLowerCase() + "-root";
+}
+
+function camelToId(name) {
+  return name
+    .replace(/([A-Z])/g, "-$1")
+    .toLowerCase()
+    .replace(/^-/, "")
+    .replace(/-+/g, "-");
+}
+
+// ── File scanner ──────────────────────────────────────────────────────────────
+
+const SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py", ".rb"]);
+const IGNORE_DIRS       = new Set(["node_modules", ".git", "dist", "build", ".next", "__pycache__", "vendor", "coverage"]);
+
+function* walkFiles(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (IGNORE_DIRS.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      yield* walkFiles(full);
+    } else if (e.isFile() && SOURCE_EXTENSIONS.has(path.extname(e.name))) {
+      yield full;
+    }
+  }
+}
+
+function scanFile(filePath) {
+  const hits = [];
+
+  // File-pattern rules (e.g. Next.js API files)
+  for (const pat of PATTERNS) {
+    if (pat.filePattern && pat.filePattern.test(filePath)) {
+      const result = pat.extract(filePath);
+      if (result) hits.push({ ...result, source: filePath, pattern: pat.name });
+    }
+  }
+
+  let content;
+  try { content = fs.readFileSync(filePath, "utf8"); } catch { return hits; }
+
+  for (const pat of PATTERNS) {
+    if (!pat.regex) continue;
+    pat.regex.lastIndex = 0;
+    let m;
+    while ((m = pat.regex.exec(content)) !== null) {
+      const result = pat.extract(m);
+      if (!result) continue;
+      if (pat.minLen && result.id.length < pat.minLen) continue;
+      hits.push({ ...result, source: filePath, pattern: pat.name });
+    }
+  }
+
+  return hits;
+}
+
+// ── Gap detection ─────────────────────────────────────────────────────────────
+
+function readContract(infernoDir) {
+  for (const f of ["capabilities.json", "contract.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try { return { file: f, data: JSON.parse(fs.readFileSync(p, "utf8")) }; } catch {}
+  }
+  return null;
+}
+
+function getKnownIds(contract) {
+  const caps = contract?.data?.capabilities || [];
+  return new Set(caps.map(c => (typeof c === "string" ? c : c.id || c.name || "").toLowerCase()));
+}
+
+function dedupeHits(hits) {
+  const seen = new Map();
+  for (const h of hits) {
+    const key = h.id;
+    const existing = seen.get(key);
+    if (!existing || h.confidence > existing.confidence) {
+      seen.set(key, h);
+    }
+  }
+  return [...seen.values()].sort((a, b) => b.confidence - a.confidence);
+}
+
+// ── Apply ─────────────────────────────────────────────────────────────────────
+
+function applyToContract(infernoDir, contract, newCaps) {
+  const caps    = contract.data.capabilities || [];
+  const added   = [];
+
+  for (const cap of newCaps) {
+    const entry = {
+      id:          cap.id,
+      description: cap.hint,
+      since:       new Date().toISOString().slice(0, 10),
+      source:      "scout",
+    };
+    caps.push(entry);
+    added.push(cap.id);
+  }
+
+  contract.data.capabilities = caps;
+  fs.writeFileSync(
+    path.join(infernoDir, contract.file),
+    JSON.stringify(contract.data, null, 2) + "\n"
+  );
+  return added;
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function scoutCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json");
+  const apply     = args.includes("--apply");
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ not found. Run: infernoflow init";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  // Parse --dir flag
+  const dirIdx = args.indexOf("--dir");
+  const scanDirs = dirIdx !== -1
+    ? args[dirIdx + 1].split(",").map(d => path.resolve(cwd, d.trim()))
+    : ["src", "lib", "app", "api", "pages", "routes", "controllers", "handlers"]
+        .map(d => path.join(cwd, d))
+        .filter(fs.existsSync);
+
+  // Parse --min-confidence
+  const confIdx     = args.indexOf("--min-confidence");
+  const minConfidence = confIdx !== -1 ? parseFloat(args[confIdx + 1]) : 0.6;
+
+  if (!scanDirs.length) {
+    const msg = "No source directories found. Use --dir src,lib,api";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  const contract = readContract(infernoDir);
+  const knownIds = getKnownIds(contract);
+
+  if (!jsonMode) {
+    info(`Scanning ${scanDirs.map(d => path.relative(cwd, d)).join(", ")} …`);
+    console.log();
+  }
+
+  // Collect hits from all source dirs
+  const allHits = [];
+  for (const dir of scanDirs) {
+    for (const file of walkFiles(dir)) {
+      allHits.push(...scanFile(file));
+    }
+  }
+
+  // Filter: unknown, above confidence threshold, non-trivial id
+  const candidates = dedupeHits(allHits).filter(h =>
+    !knownIds.has(h.id.toLowerCase()) &&
+    h.confidence >= minConfidence &&
+    h.id.length >= 3 &&
+    !["index", "app", "main", "root", "default", "handler"].includes(h.id)
+  );
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, found: candidates.length, candidates }));
+    return;
+  }
+
+  if (!candidates.length) {
+    done("No undocumented capabilities found — contract looks complete.");
+    return;
+  }
+
+  console.log(`  ${bold(`${candidates.length} undocumented capability candidate${candidates.length !== 1 ? "s" : ""} found`)}`);
+  console.log();
+
+  const w = Math.max(...candidates.map(c => c.id.length), 10) + 2;
+  for (const c of candidates) {
+    const confStr  = `${Math.round(c.confidence * 100)}%`;
+    const confColor = c.confidence >= 0.8 ? green : c.confidence >= 0.65 ? yellow : gray;
+    const rel      = path.relative(cwd, c.source);
+    console.log(`  ${bold(c.id.padEnd(w))} ${confColor(confStr.padEnd(5))} ${gray(c.hint)}`);
+    console.log(`  ${" ".repeat(w + 7)}${gray(rel)}`);
+  }
+  console.log();
+
+  if (apply) {
+    const added = applyToContract(infernoDir, contract, candidates);
+    done(`Added ${bold(String(added.length))} capabilities to ${contract.file}`);
+    console.log();
+  } else {
+    info(`Run with ${cyan("--apply")} to add these to your contract.`);
+    console.log();
+  }
+}

package/dist/lib/commands/snapshot.mjs

@@ -0,0 +1,383 @@
+/**
+ * infernoflow snapshot
+ *
+ * Named, timestamped snapshots of the full capability contract.
+ * Stored in inferno/snapshots/ — travel with the repo.
+ *
+ * Like git tags, but for the capability contract specifically.
+ *
+ * Usage:
+ *   infernoflow snapshot save <name>           Save current contract as a named snapshot
+ *   infernoflow snapshot list                  List all snapshots
+ *   infernoflow snapshot show <name>           Print a snapshot's capabilities
+ *   infernoflow snapshot diff <name1> <name2>  Diff two snapshots (or name vs current)
+ *   infernoflow snapshot restore <name>        Overwrite contract with a snapshot
+ *   infernoflow snapshot delete <name>         Delete a snapshot
+ *   infernoflow snapshot --json                Machine-readable output on any subcommand
+ *
+ * Snapshot file format (inferno/snapshots/<name>.json):
+ *   {
+ *     "name": "v1.2-release",
+ *     "savedAt": "2025-06-01T12:00:00Z",
+ *     "capabilities": [...],
+ *     "meta": { "version": "1.2.0", "capabilityCount": 12 }
+ *   }
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+const SNAPSHOTS_DIR = "snapshots";
+
+// ── Storage ───────────────────────────────────────────────────────────────────
+
+function snapshotsDir(infernoDir) {
+  return path.join(infernoDir, SNAPSHOTS_DIR);
+}
+
+function snapshotPath(infernoDir, name) {
+  return path.join(infernoDir, SNAPSHOTS_DIR, `${name}.json`);
+}
+
+function ensureSnapshotsDir(infernoDir) {
+  const d = snapshotsDir(infernoDir);
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+function listSnapshots(infernoDir) {
+  const d = snapshotsDir(infernoDir);
+  if (!fs.existsSync(d)) return [];
+  return fs.readdirSync(d)
+    .filter(f => f.endsWith(".json"))
+    .map(f => {
+      try { return JSON.parse(fs.readFileSync(path.join(d, f), "utf8")); } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => new Date(b.savedAt) - new Date(a.savedAt));
+}
+
+function readSnapshot(infernoDir, name) {
+  const p = snapshotPath(infernoDir, name);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+function readContract(infernoDir) {
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try { return { file: f, data: JSON.parse(fs.readFileSync(p, "utf8")) }; } catch {}
+  }
+  return null;
+}
+
+function normaliseCaps(contract) {
+  const raw = contract?.capabilities || contract?.data?.capabilities || contract || [];
+  return raw.map(c => (typeof c === "string" ? { id: c } : c));
+}
+
+function readPackageVersion(cwd) {
+  try { return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).version || ""; } catch { return ""; }
+}
+
+// ── Diff engine ───────────────────────────────────────────────────────────────
+
+function diffCaps(capsBefore, capsAfter) {
+  const beforeIds = new Map(capsBefore.map(c => [c.id, c]));
+  const afterIds  = new Map(capsAfter.map(c => [c.id, c]));
+
+  const added    = capsAfter.filter(c => !beforeIds.has(c.id));
+  const removed  = capsBefore.filter(c => !afterIds.has(c.id));
+  const changed  = capsAfter.filter(c => {
+    const prev = beforeIds.get(c.id);
+    if (!prev) return false;
+    return JSON.stringify(c) !== JSON.stringify(prev);
+  });
+
+  return { added, removed, changed };
+}
+
+// ── Sub-commands ──────────────────────────────────────────────────────────────
+
+function subcmdSave(name, infernoDir, cwd, jsonMode) {
+  if (!name || name.startsWith("--")) {
+    const msg = "Usage: infernoflow snapshot save <name>";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  // Validate name (no spaces, no slashes)
+  if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+    const msg = `Invalid snapshot name "${name}" — use letters, digits, dots, dashes, underscores only`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const contract = readContract(infernoDir);
+  if (!contract) {
+    const msg = "No contract found. Run: infernoflow init";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  ensureSnapshotsDir(infernoDir);
+
+  const caps = normaliseCaps(contract.data);
+  const snapshot = {
+    name,
+    savedAt:      new Date().toISOString(),
+    capabilities: caps,
+    meta: {
+      version:         readPackageVersion(cwd),
+      capabilityCount: caps.length,
+      contractFile:    contract.file,
+    },
+  };
+
+  const p = snapshotPath(infernoDir, name);
+  const overwriting = fs.existsSync(p);
+  fs.writeFileSync(p, JSON.stringify(snapshot, null, 2) + "\n");
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, action: "saved", name, capabilities: caps.length }));
+  } else {
+    done(`${overwriting ? "Updated" : "Saved"} snapshot ${bold(cyan(name))} — ${bold(String(caps.length))} capabilities`);
+    console.log();
+  }
+}
+
+function subcmdList(infernoDir, jsonMode) {
+  const snapshots = listSnapshots(infernoDir);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, snapshots: snapshots.map(s => ({ name: s.name, savedAt: s.savedAt, capabilities: s.meta?.capabilityCount ?? s.capabilities?.length ?? 0 })) }));
+    return;
+  }
+
+  if (!snapshots.length) {
+    info("No snapshots yet. Use: infernoflow snapshot save <name>");
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold(`${snapshots.length} snapshot${snapshots.length !== 1 ? "s" : ""}`)}`);
+  console.log();
+
+  const w = Math.max(...snapshots.map(s => s.name.length), 8) + 2;
+  for (const s of snapshots) {
+    const date = new Date(s.savedAt).toLocaleString();
+    const caps = s.meta?.capabilityCount ?? s.capabilities?.length ?? "?";
+    console.log(`  ${bold(s.name.padEnd(w))} ${gray(date)}  ${cyan(String(caps))} caps`);
+  }
+  console.log();
+}
+
+function subcmdShow(name, infernoDir, jsonMode) {
+  if (!name || name.startsWith("--")) {
+    const msg = "Usage: infernoflow snapshot show <name>";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const snap = readSnapshot(infernoDir, name);
+  if (!snap) {
+    const msg = `Snapshot not found: ${name}`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, snapshot: snap }));
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold("Snapshot:")} ${cyan(snap.name)}`);
+  console.log(`  ${bold("Saved:")}    ${gray(new Date(snap.savedAt).toLocaleString())}`);
+  console.log(`  ${bold("Version:")}  ${gray(snap.meta?.version || "—")}`);
+  console.log(`  ${bold("Caps:")}     ${snap.capabilities.length}`);
+  console.log();
+
+  const caps = normaliseCaps(snap.capabilities);
+  for (const c of caps) {
+    console.log(`  ${cyan("·")} ${bold(c.id)}${c.description ? gray("  " + c.description) : ""}`);
+  }
+  console.log();
+}
+
+function subcmdDiff(nameA, nameB, infernoDir, jsonMode) {
+  if (!nameA) {
+    const msg = "Usage: infernoflow snapshot diff <name1> [<name2>]  (omit name2 to diff against current)";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const snapA = readSnapshot(infernoDir, nameA);
+  if (!snapA) {
+    const msg = `Snapshot not found: ${nameA}`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  let capsBefore = normaliseCaps(snapA.capabilities);
+  let capsAfter;
+  let labelAfter;
+
+  if (nameB) {
+    const snapB = readSnapshot(infernoDir, nameB);
+    if (!snapB) {
+      const msg = `Snapshot not found: ${nameB}`;
+      if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+      else warn(msg);
+      return;
+    }
+    capsAfter  = normaliseCaps(snapB.capabilities);
+    labelAfter = nameB;
+  } else {
+    const contract = readContract(infernoDir);
+    if (!contract) {
+      const msg = "No current contract found.";
+      if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+      else warn(msg);
+      return;
+    }
+    capsAfter  = normaliseCaps(contract.data);
+    labelAfter = "current";
+  }
+
+  const diff = diffCaps(capsBefore, capsAfter);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, from: nameA, to: labelAfter, ...diff }));
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold("Diff:")} ${cyan(nameA)} → ${cyan(labelAfter)}`);
+  console.log();
+
+  if (!diff.added.length && !diff.removed.length && !diff.changed.length) {
+    console.log(`  ${gray("No differences — snapshots are identical")}`);
+    console.log();
+    return;
+  }
+
+  if (diff.added.length) {
+    console.log(`  ${green("+")} ${bold(`${diff.added.length} added`)}`);
+    diff.added.forEach(c => console.log(`    ${green("+")} ${c.id}`));
+    console.log();
+  }
+  if (diff.removed.length) {
+    console.log(`  ${red("-")} ${bold(`${diff.removed.length} removed`)}`);
+    diff.removed.forEach(c => console.log(`    ${red("-")} ${c.id}`));
+    console.log();
+  }
+  if (diff.changed.length) {
+    console.log(`  ${yellow("~")} ${bold(`${diff.changed.length} changed`)}`);
+    diff.changed.forEach(c => console.log(`    ${yellow("~")} ${c.id}`));
+    console.log();
+  }
+}
+
+function subcmdRestore(name, infernoDir, jsonMode) {
+  if (!name || name.startsWith("--")) {
+    const msg = "Usage: infernoflow snapshot restore <name>";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const snap = readSnapshot(infernoDir, name);
+  if (!snap) {
+    const msg = `Snapshot not found: ${name}`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const contract = readContract(infernoDir);
+  const contractFile = contract?.file || "capabilities.json";
+  const contractPath = path.join(infernoDir, contractFile);
+
+  const data = contract?.data || {};
+  data.capabilities = snap.capabilities;
+  fs.writeFileSync(contractPath, JSON.stringify(data, null, 2) + "\n");
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, action: "restored", name, capabilities: snap.capabilities.length }));
+  } else {
+    done(`Restored ${bold(cyan(name))} → ${bold(contractFile)} (${snap.capabilities.length} capabilities)`);
+    console.log();
+  }
+}
+
+function subcmdDelete(name, infernoDir, jsonMode) {
+  if (!name || name.startsWith("--")) {
+    const msg = "Usage: infernoflow snapshot delete <name>";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const p = snapshotPath(infernoDir, name);
+  if (!fs.existsSync(p)) {
+    const msg = `Snapshot not found: ${name}`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  fs.unlinkSync(p);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, action: "deleted", name }));
+  } else {
+    done(`Deleted snapshot ${bold(name)}`);
+    console.log();
+  }
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function snapshotCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json");
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ not found. Run: infernoflow init";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  const subcmd = args.find(a => !a.startsWith("--"));
+
+  if (!subcmd || subcmd === "list") {
+    return subcmdList(infernoDir, jsonMode);
+  }
+
+  const positional = args.filter(a => !a.startsWith("--"));
+
+  if (subcmd === "save")    return subcmdSave(positional[1], infernoDir, cwd, jsonMode);
+  if (subcmd === "show")    return subcmdShow(positional[1], infernoDir, jsonMode);
+  if (subcmd === "restore") return subcmdRestore(positional[1], infernoDir, jsonMode);
+  if (subcmd === "delete")  return subcmdDelete(positional[1], infernoDir, jsonMode);
+
+  if (subcmd === "diff") {
+    return subcmdDiff(positional[1], positional[2], infernoDir, jsonMode);
+  }
+
+  warn(`Unknown snapshot sub-command: ${subcmd}`);
+  info("Available: save | list | show | diff | restore | delete");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infernoflow",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "The forge for liquid code - keep capabilities, contracts, and docs in sync.",
   "type": "module",
   "bin": {