infernoflow 0.28.0 → 0.30.0

package/dist/bin/infernoflow.mjs

@@ -62,6 +62,9 @@ const COMMAND_DESCRIPTIONS = {
   why:        "Given a file or function name — show which capability it serves, scenarios, stability, and git history",
   impact:     "Blast radius analysis — see every cap, scenario, and risk level affected before you change anything",
   scaffold:   "Generate a new capability — source skeleton, contract registration, and placeholder scenario in one command",
+  explain:    "AI narrative about a capability — what it does, why it exists, what's risky, and what to test",
+  test:       "Run registered scenarios for a capability — auto-generates a smoke harness if no test runner is configured",
+  ai:         "Manage AI providers — setup, status, test connection (subcommands: setup | status | test | clear)",
 };
 
 const COMMAND_HANDLERS = {
@@ -117,6 +120,9 @@ const COMMAND_HANDLERS = {
   why:       async (args) => (await import("../lib/commands/why.mjs")).whyCommand(args),
   impact:    async (args) => (await import("../lib/commands/impact.mjs")).impactCommand(args),
   scaffold:  async (args) => (await import("../lib/commands/scaffold.mjs")).scaffoldCommand(args),
+  explain:   async (args) => (await import("../lib/commands/explain.mjs")).explainCommand(args),
+  test:      async (args) => (await import("../lib/commands/test.mjs")).testCommand(args),
+  ai:        async (args) => (await import("../lib/commands/ai.mjs")).aiCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -415,6 +421,27 @@ ${formatCommandsHelp()}
     --dry-run                            Preview what would be generated without writing files
     --json                               Machine-readable output including generated code
 
+  ${bold("explain options:")}
+    infernoflow explain <cap-id>         AI narrative: what it does, risk, what to test
+    --dry-run                            Print the AI prompt only — no API call made
+    --json                               Machine-readable output (narrative, stability, scenarios)
+
+  ${bold("test options:")}
+    infernoflow test                     Run all caps that have registered scenarios
+    infernoflow test <cap-id>            Run scenarios for a specific capability
+    infernoflow test --all               Run every capability (including those without scenarios)
+    --generate                           Print generated ad-hoc test file without running
+    --bail                               Stop on first failure
+    --verbose, -v                        Show runner output for each scenario
+    --json                               Machine-readable output (passed/failed/skipped counts)
+
+  ${bold("ai options:")}
+    infernoflow ai setup                 Interactive wizard — pick provider, enter API key, verify
+    infernoflow ai status                Show all providers and which are configured
+    infernoflow ai test [provider]       Send a test prompt and verify the connection
+    infernoflow ai clear <provider>      Remove a provider's config from integrations.json
+    Supported providers: anthropic  openai  gemini  openrouter  ollama
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/ai.mjs

@@ -0,0 +1,370 @@
+/**
+ * infernoflow ai
+ *
+ * Manage AI provider configuration for infernoflow commands
+ * (explain, why, review, changelog, etc.)
+ *
+ * Subcommands:
+ *   infernoflow ai setup               Interactive guided setup
+ *   infernoflow ai status              Show configured providers and which is active
+ *   infernoflow ai test [provider]     Send a test prompt and show response
+ *   infernoflow ai clear [provider]    Remove a provider's API key from config
+ *
+ * Config is stored in inferno/integrations.json (project-scoped).
+ * API keys can also come from environment variables (checked first).
+ *
+ * Supported providers:
+ *   anthropic   ANTHROPIC_API_KEY   claude-sonnet-4-6
+ *   openai      OPENAI_API_KEY      gpt-4o
+ *   gemini      GOOGLE_AI_API_KEY   gemini-2.0-flash
+ *   openrouter  OPENROUTER_API_KEY  (any model)
+ *   ollama      (local, no key)     llama3.2
+ */
+
+import * as fs       from "node:fs";
+import * as path     from "node:path";
+import * as https    from "node:https";
+import * as http     from "node:http";
+import * as readline from "node:readline";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── config helpers ────────────────────────────────────────────────────────────
+
+function infernoDir(cwd) { return path.join(cwd, "inferno"); }
+
+function loadConfig(cwd) {
+  const p = path.join(infernoDir(cwd), "integrations.json");
+  if (!fs.existsSync(p)) return {};
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return {}; }
+}
+
+function saveConfig(cwd, config) {
+  const dir = infernoDir(cwd);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "integrations.json"), JSON.stringify(config, null, 2) + "\n");
+}
+
+// ── provider definitions ──────────────────────────────────────────────────────
+
+const PROVIDERS = [
+  {
+    id:      "anthropic",
+    name:    "Anthropic (Claude)",
+    envKey:  "ANTHROPIC_API_KEY",
+    models:  ["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5-20251001"],
+    default: "claude-sonnet-4-6",
+    keyHint: "sk-ant-api03-…",
+    docsUrl: "https://console.anthropic.com/settings/keys",
+  },
+  {
+    id:      "openai",
+    name:    "OpenAI (GPT)",
+    envKey:  "OPENAI_API_KEY",
+    models:  ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
+    default: "gpt-4o",
+    keyHint: "sk-…",
+    docsUrl: "https://platform.openai.com/api-keys",
+  },
+  {
+    id:      "gemini",
+    name:    "Google Gemini",
+    envKey:  "GOOGLE_AI_API_KEY",
+    models:  ["gemini-2.0-flash", "gemini-1.5-pro", "gemini-1.5-flash"],
+    default: "gemini-2.0-flash",
+    keyHint: "AIza…",
+    docsUrl: "https://aistudio.google.com/app/apikey",
+  },
+  {
+    id:      "openrouter",
+    name:    "OpenRouter",
+    envKey:  "OPENROUTER_API_KEY",
+    models:  ["anthropic/claude-sonnet-4-6", "openai/gpt-4o", "meta-llama/llama-3.1-8b-instruct:free"],
+    default: "anthropic/claude-sonnet-4-6",
+    keyHint: "sk-or-…",
+    docsUrl: "https://openrouter.ai/keys",
+  },
+  {
+    id:      "ollama",
+    name:    "Ollama (local)",
+    envKey:  null,
+    models:  ["llama3.2", "mistral", "codellama", "phi3"],
+    default: "llama3.2",
+    keyHint: null,
+    docsUrl: "https://ollama.com",
+  },
+];
+
+// ── HTTP probe ────────────────────────────────────────────────────────────────
+
+function httpGet(url) {
+  return new Promise((resolve) => {
+    const parsed = new URL(url);
+    const lib    = parsed.protocol === "https:" ? https : http;
+    const req    = lib.request({ hostname: parsed.hostname, port: parsed.port || (parsed.protocol === "https:" ? 443 : 80), path: parsed.pathname + (parsed.search || ""), method: "GET", timeout: 5000 }, (res) => {
+      let raw = "";
+      res.on("data", d => (raw += d));
+      res.on("end", () => { try { resolve({ status: res.statusCode, body: JSON.parse(raw) }); } catch { resolve({ status: res.statusCode, body: raw }); } });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.end();
+  });
+}
+
+// ── provider status check ─────────────────────────────────────────────────────
+
+async function checkProviderStatus(providerId, config) {
+  const envMap = {
+    anthropic:  process.env.ANTHROPIC_API_KEY,
+    openai:     process.env.OPENAI_API_KEY,
+    gemini:     process.env.GOOGLE_AI_API_KEY || process.env.GEMINI_API_KEY,
+    openrouter: process.env.OPENROUTER_API_KEY,
+  };
+
+  const fromEnv    = envMap[providerId];
+  const fromConfig = config[providerId]?.apiKey;
+  const key        = fromEnv || fromConfig;
+  const source     = fromEnv ? "env" : fromConfig ? "integrations.json" : null;
+  const model      = config[providerId]?.model || PROVIDERS.find(p => p.id === providerId)?.default;
+
+  if (providerId === "ollama") {
+    // Check if Ollama is running
+    const probe = await httpGet("http://localhost:11434/api/tags").catch(() => null);
+    if (probe?.status === 200) {
+      const models = probe.body?.models?.map(m => m.name) || [];
+      return { configured: true, source: "local", model: config.ollama?.model || "llama3.2", available: true, models };
+    }
+    return { configured: false, source: null, model: null, available: false };
+  }
+
+  return { configured: !!key, source, model, available: null, masked: key ? key.slice(0, 8) + "…" : null };
+}
+
+// ── ai test prompt ────────────────────────────────────────────────────────────
+
+async function testProvider(providerId, config, cwd) {
+  try {
+    const { callAI } = await import("../ai/providerRouter.mjs");
+    const testPrompt = `Reply with exactly: "infernoflow AI test OK — ${providerId}"`;
+    const result = await callAI(testPrompt, cwd, providerId);
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+// ── readline helper ───────────────────────────────────────────────────────────
+
+function prompt(rl, question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+// ── subcommands ───────────────────────────────────────────────────────────────
+
+async function cmdStatus(cwd) {
+  const config = loadConfig(cwd);
+
+  console.log();
+  console.log(`  ${bold("infernoflow ai")}  ${gray("— provider status")}`);
+  console.log();
+
+  let anyConfigured = false;
+
+  for (const p of PROVIDERS) {
+    const status = await checkProviderStatus(p.id, config);
+    if (status.configured) anyConfigured = true;
+
+    const icon  = status.configured ? green("✓") : gray("○");
+    const label = bold(p.name.padEnd(22));
+    const info  = status.configured
+      ? `${green("configured")}  ${gray(status.source)}  ${gray("model: " + status.model)}${status.masked ? "  " + gray(status.masked) : ""}`
+      : gray("not configured");
+    console.log(`  ${icon}  ${label}  ${info}`);
+  }
+
+  console.log();
+
+  if (!anyConfigured) {
+    console.log(`  ${yellow("No AI providers configured.")}  Run: ${cyan("infernoflow ai setup")}`);
+    console.log(`  ${gray("Without a provider, explain/why/review use structural fallbacks.")}`);
+  } else {
+    console.log(`  ${gray("Run")} ${cyan("infernoflow ai test")} ${gray("to verify the active provider.")}`);
+  }
+  console.log();
+}
+
+async function cmdSetup(cwd) {
+  const config = loadConfig(cwd);
+
+  console.log();
+  console.log(`  ${bold("🔥 infernoflow ai setup")}`);
+  console.log(`  ${gray("Connect an AI provider for explain, why, review, and changelog.")}`);
+  console.log();
+  console.log(`  Providers: ${PROVIDERS.map(p => bold(p.id)).join("  ")}`);
+  console.log();
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    // Pick provider
+    const providerInput = await prompt(rl, `  Provider [anthropic]: `);
+    const providerId    = providerInput.trim().toLowerCase() || "anthropic";
+    const provider      = PROVIDERS.find(p => p.id === providerId);
+
+    if (!provider) {
+      console.log(red(`  Unknown provider "${providerId}". Options: ${PROVIDERS.map(p => p.id).join(", ")}`));
+      return;
+    }
+
+    console.log();
+    console.log(`  ${bold(provider.name)}`);
+
+    if (provider.docsUrl) {
+      console.log(`  ${gray("Get API key:")} ${cyan(provider.docsUrl)}`);
+    }
+
+    if (providerId === "ollama") {
+      // Ollama — no key, just model + host
+      const hostInput  = await prompt(rl, `  Ollama host [http://localhost:11434]: `);
+      const modelInput = await prompt(rl, `  Model [${provider.default}]: `);
+
+      config.ollama = {
+        host:  hostInput.trim()  || "http://localhost:11434",
+        model: modelInput.trim() || provider.default,
+      };
+      saveConfig(cwd, config);
+
+      console.log();
+      console.log(`  ${green("✓")} Ollama configured. Testing connection…`);
+      const probe = await httpGet(`${config.ollama.host}/api/tags`).catch(() => null);
+      if (probe?.status === 200) {
+        console.log(`  ${green("✓")} Ollama is running. You're all set.`);
+      } else {
+        console.log(`  ${yellow("⚠")}  Could not reach Ollama. Make sure it's running: ${cyan("ollama serve")}`);
+      }
+    } else {
+      // API key provider
+      const existingKey = process.env[provider.envKey] || config[providerId]?.apiKey;
+      const keyHint     = existingKey ? `[${existingKey.slice(0, 8)}… (existing)] ` : `[${provider.keyHint}] `;
+      const keyInput    = await prompt(rl, `  API key ${keyHint}: `);
+      const apiKey      = keyInput.trim() || existingKey;
+
+      if (!apiKey) {
+        console.log(red("  No API key provided. Exiting."));
+        return;
+      }
+
+      const modelInput = await prompt(rl, `  Model [${provider.default}]: `);
+      const model      = modelInput.trim() || provider.default;
+
+      config[providerId] = { apiKey, model };
+      saveConfig(cwd, config);
+
+      console.log();
+      console.log(`  ${green("✓")} Saved to inferno/integrations.json`);
+      console.log();
+      process.stdout.write(`  Testing connection…  `);
+
+      const result = await testProvider(providerId, config, cwd);
+      if (result?.text) {
+        console.log(green("OK"));
+        console.log(`  ${gray(result.text.trim().slice(0, 80))}`);
+      } else {
+        console.log(yellow("no response"));
+        console.log(`  ${yellow("⚠")}  Could not get a test response. Check your API key.`);
+      }
+    }
+
+    console.log();
+    console.log(`  ${green("✓")} ${bold(provider.name)} is ready.`);
+    console.log(`  ${gray("Commands that now use AI:")} explain  why  review  changelog`);
+    console.log();
+
+    // gitignore reminder
+    const gitignorePath = path.join(cwd, ".gitignore");
+    if (fs.existsSync(gitignorePath)) {
+      const content = fs.readFileSync(gitignorePath, "utf8");
+      if (!content.includes("integrations.json")) {
+        console.log(`  ${yellow("⚠")}  Your API key is in inferno/integrations.json.`);
+        console.log(`     ${gray("Add")} ${cyan("inferno/integrations.json")} ${gray("to .gitignore to avoid committing it.")}`);
+        console.log();
+      }
+    }
+
+  } finally {
+    rl.close();
+  }
+}
+
+async function cmdTest(args, cwd) {
+  const config     = loadConfig(cwd);
+  const providerId = args.find(a => !a.startsWith("--")) || null;
+
+  console.log();
+  console.log(`  ${bold("infernoflow ai test")}`);
+  console.log();
+
+  const toTest = providerId
+    ? PROVIDERS.filter(p => p.id === providerId)
+    : PROVIDERS;
+
+  for (const p of toTest) {
+    const status = await checkProviderStatus(p.id, config);
+    if (!status.configured) {
+      console.log(`  ${gray("○")}  ${bold(p.name.padEnd(22))}  ${gray("not configured — skipping")}`);
+      continue;
+    }
+
+    process.stdout.write(`  ${yellow("…")}  ${bold(p.name.padEnd(22))}  testing…  `);
+    const result = await testProvider(p.id, config, cwd);
+    if (result?.text) {
+      console.log(green("OK") + gray(` (${result.model || p.id})`));
+      console.log(`     ${gray(result.text.trim().slice(0, 80))}`);
+    } else {
+      console.log(red("FAIL"));
+      console.log(`     ${red("No response — check API key or model name")}`);
+    }
+  }
+
+  console.log();
+}
+
+async function cmdClear(args, cwd) {
+  const config     = loadConfig(cwd);
+  const providerId = args.find(a => !a.startsWith("--"));
+
+  if (!providerId) {
+    console.error(red("✗ Usage: infernoflow ai clear <provider>"));
+    console.error(gray("  Example: infernoflow ai clear openai"));
+    process.exit(1);
+  }
+
+  if (!config[providerId]) {
+    console.log(gray(`  No config found for "${providerId}"`));
+    return;
+  }
+
+  delete config[providerId];
+  saveConfig(cwd, config);
+  console.log(green(`  ✓ Cleared config for ${providerId}`));
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function aiCommand(rawArgs) {
+  const args    = (rawArgs || []).slice(1);
+  const sub     = args.find(a => !a.startsWith("--")) || "status";
+  const subArgs = args.filter(a => a !== sub);
+  const cwd     = process.cwd();
+
+  switch (sub) {
+    case "setup":   return cmdSetup(cwd);
+    case "status":  return cmdStatus(cwd);
+    case "test":    return cmdTest(subArgs, cwd);
+    case "clear":   return cmdClear(subArgs, cwd);
+    default:
+      console.error(red(`✗ Unknown subcommand: "${sub}"`));
+      console.error(gray("  Usage: infernoflow ai <setup|status|test|clear>"));
+      process.exit(1);
+  }
+}

package/dist/lib/commands/explain.mjs

@@ -0,0 +1,373 @@
+/**
+ * infernoflow explain
+ *
+ * AI-generated narrative about a capability — what it does, why it exists,
+ * what's risky about it, and what to test before changing it.
+ *
+ * Synthesises: stability level, git history, scenarios, callers, services,
+ * source files — then calls the AI provider for a 3-5 sentence human narrative.
+ *
+ * Usage:
+ *   infernoflow explain user-auth
+ *   infernoflow explain payment-process --dry-run    (print prompt only)
+ *   infernoflow explain user-auth --json
+ */
+
+import * as fs      from "node:fs";
+import * as path    from "node:path";
+import { execSync } from "node:child_process";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function loadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return null; }
+}
+
+function runGit(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", stdio: ["pipe","pipe","pipe"] }).trim();
+  } catch { return ""; }
+}
+
+const LEVEL_ICON  = { frozen: "🧊", stable: "〰️ ", experimental: "🌊" };
+const LEVEL_COLOR = { frozen: red, stable: yellow, experimental: green };
+
+function stability(cap) { return cap?.stability || "experimental"; }
+
+// ── git helpers ───────────────────────────────────────────────────────────────
+
+function getFirstCommit(filePath, cwd) {
+  if (!filePath) return null;
+  const rel = path.relative(cwd, path.resolve(cwd, filePath));
+  const log = runGit(
+    `git log --follow --format="%h|%aI|%ae|%s" -- ${JSON.stringify(rel)}`, cwd
+  );
+  if (!log) return null;
+  const lines = log.split("\n").filter(Boolean);
+  if (!lines.length) return null;
+  const [hash, date, author, ...subjectParts] = lines[lines.length - 1].split("|");
+  return {
+    hash:    hash?.trim(),
+    date:    date?.trim() ? new Date(date.trim()).toLocaleDateString() : "",
+    author:  author?.trim(),
+    subject: subjectParts.join("|").trim(),
+  };
+}
+
+function getRecentHistory(filePath, cwd, limit = 5) {
+  if (!filePath) return [];
+  const rel = path.relative(cwd, path.resolve(cwd, filePath));
+  const log = runGit(
+    `git log --follow --format="%h|%aI|%ae|%s" -${limit} -- ${JSON.stringify(rel)}`, cwd
+  );
+  if (!log) return [];
+  return log.split("\n").filter(Boolean).map(line => {
+    const [hash, date, author, ...subjectParts] = line.split("|");
+    return {
+      hash:    hash?.trim(),
+      date:    date?.trim() ? new Date(date.trim()).toLocaleDateString() : "",
+      author:  author?.trim(),
+      subject: subjectParts.join("|").trim(),
+    };
+  });
+}
+
+// ── scenario finder ───────────────────────────────────────────────────────────
+
+function findScenarios(capId, infernoDir) {
+  const dir = path.join(infernoDir, "scenarios");
+  if (!fs.existsSync(dir)) return [];
+  const found = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      const covered = s.capabilitiesCovered || s.capabilities || [];
+      if (covered.some(c => c.toLowerCase() === capId.toLowerCase())) {
+        found.push(s);
+      }
+    } catch {}
+  }
+  return found;
+}
+
+// ── prompt builder ────────────────────────────────────────────────────────────
+
+function buildPrompt(capId, cap, scanEntry, graph, allCaps, scenarios, firstCommit, recentHistory) {
+  const level      = stability(cap);
+  const files      = scanEntry?.codeAnalysis?.sourceFiles   || [];
+  const functions  = scanEntry?.codeAnalysis?.functions     || [];
+  const services   = scanEntry?.codeAnalysis?.services      || [];
+  const throws_    = scanEntry?.codeAnalysis?.throws        || [];
+  const calls      = scanEntry?.codeAnalysis?.calls         || [];
+  const deps       = graph?.deps?.[capId]       || [];
+  const dependents = graph?.dependents?.[capId] || [];
+
+  const lines = [
+    `You are a senior engineer writing a brief, plain-English explanation of a software capability for a teammate who is about to modify it.`,
+    ``,
+    `Write 3–5 sentences covering:`,
+    `  1. What this capability does and why it exists`,
+    `  2. The most important thing to know before changing it (stability, callers, risk)`,
+    `  3. What to test or verify after any modification`,
+    ``,
+    `Be concrete and direct. Do not use bullet points. Do not repeat the capability ID verbatim in every sentence.`,
+    ``,
+    `=== Capability: ${capId} ===`,
+    `Name:        ${cap.name || cap.title || capId}`,
+    `Description: ${cap.description || "(none provided)"}`,
+    `Stability:   ${level}`,
+  ];
+
+  if (files.length)     lines.push(`Source files: ${files.join(", ")}`);
+  if (functions.length) lines.push(`Functions:    ${functions.join(", ")}`);
+  if (services.length)  lines.push(`External services used: ${services.join(", ")}`);
+  if (throws_.length)   lines.push(`Can throw: ${throws_.join(", ")}`);
+  if (calls.length)     lines.push(`Internal calls: ${calls.join(", ")}`);
+
+  if (deps.length) {
+    const depDetails = deps.map(d => {
+      const dc = allCaps.find(c => c.id === d);
+      return `${d} (${stability(dc)})`;
+    });
+    lines.push(`Calls capabilities: ${depDetails.join(", ")}`);
+  }
+
+  if (dependents.length) {
+    const depDetails = dependents.map(d => {
+      const dc = allCaps.find(c => c.id === d);
+      return `${d} (${stability(dc)})`;
+    });
+    lines.push(`Called by capabilities: ${depDetails.join(", ")}`);
+  }
+
+  if (scenarios.length) {
+    lines.push(`Test scenarios: ${scenarios.map(s => s.scenarioId || s.description || "unnamed").join(", ")}`);
+  } else {
+    lines.push(`Test scenarios: none registered`);
+  }
+
+  if (firstCommit) {
+    lines.push(`First introduced: ${firstCommit.date} by ${firstCommit.author} — "${firstCommit.subject}"`);
+  }
+
+  if (recentHistory.length) {
+    lines.push(`Recent changes:`);
+    for (const h of recentHistory.slice(0, 3)) {
+      lines.push(`  ${h.date} — ${h.subject}`);
+    }
+  }
+
+  if (level === "frozen") {
+    lines.push(`IMPORTANT: This capability is FROZEN. Any modification requires explicit approval.`);
+  } else if (level === "stable") {
+    lines.push(`NOTE: This capability is STABLE. Prefer additive changes; avoid breaking the public API.`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── AI caller ─────────────────────────────────────────────────────────────────
+
+async function callAI(prompt, cwd) {
+  try {
+    const { callAI: call } = await import("../ai/providerRouter.mjs");
+    return await call(prompt, cwd);
+  } catch {
+    // Provider not available — return a structured fallback
+    return null;
+  }
+}
+
+// ── fallback narrative (no AI) ────────────────────────────────────────────────
+
+function buildFallback(capId, cap, scanEntry, graph, allCaps, scenarios) {
+  const level      = stability(cap);
+  const name       = cap.name || cap.title || capId;
+  const services   = scanEntry?.codeAnalysis?.services || [];
+  const dependents = graph?.dependents?.[capId] || [];
+  const deps       = graph?.deps?.[capId]       || [];
+
+  const parts = [];
+
+  // What it does
+  if (cap.description && cap.description !== "(none provided)") {
+    parts.push(`${name} — ${cap.description}.`);
+  } else {
+    parts.push(`${name} handles the ${capId} flow within this system.`);
+  }
+
+  // External services
+  if (services.length) {
+    parts.push(`It integrates with ${services.join(" and ")}.`);
+  }
+
+  // Dependencies
+  if (deps.length) {
+    parts.push(`It depends on: ${deps.join(", ")}.`);
+  }
+  if (dependents.length) {
+    const frozenDeps = dependents.filter(d => stability(allCaps.find(c => c.id === d)) === "frozen");
+    if (frozenDeps.length) {
+      parts.push(`⚠️  ${frozenDeps.join(", ")} depend${frozenDeps.length === 1 ? "s" : ""} on this — changing it may break frozen capabilities.`);
+    } else {
+      parts.push(`${dependents.join(", ")} depend${dependents.length === 1 ? "s" : ""} on this capability.`);
+    }
+  }
+
+  // Stability advice
+  if (level === "frozen") {
+    parts.push(`This capability is FROZEN — do not modify without explicit instruction.`);
+  } else if (level === "stable") {
+    parts.push(`This capability is stable — prefer additive changes and avoid breaking the existing API surface.`);
+  } else {
+    parts.push(`This capability is experimental — free to refactor as needed.`);
+  }
+
+  // Test advice
+  if (scenarios.length) {
+    parts.push(`Before shipping changes, run the registered scenarios: ${scenarios.map(s => s.scenarioId || "unnamed").join(", ")}.`);
+  } else {
+    parts.push(`No test scenarios are registered — consider adding one before making changes.`);
+  }
+
+  return parts.join(" ");
+}
+
+// ── printer ───────────────────────────────────────────────────────────────────
+
+function printExplain(capId, cap, narrative, provider, dryRun) {
+  const level = stability(cap);
+  const icon  = LEVEL_ICON[level]  || "🌊";
+  const color = LEVEL_COLOR[level] || green;
+
+  console.log();
+  console.log(bold(`  ${icon} ${color(capId)}`));
+  if (cap.name || cap.title) console.log(gray(`     ${cap.name || cap.title}`));
+  console.log();
+
+  if (dryRun) {
+    console.log(yellow("  [dry-run] Prompt only — no AI call made"));
+    console.log();
+    return;
+  }
+
+  // Word-wrap narrative at ~80 chars
+  const words  = narrative.split(" ");
+  let   line   = "  ";
+  const lines  = [];
+  for (const word of words) {
+    if (line.length + word.length > 82) { lines.push(line); line = "  " + word; }
+    else line += (line === "  " ? "" : " ") + word;
+  }
+  if (line.trim()) lines.push(line);
+
+  for (const l of lines) console.log(l);
+  console.log();
+
+  if (provider) {
+    console.log(gray(`  ── via ${provider}`));
+  } else {
+    console.log(gray("  ── (AI provider not configured — showing structural summary)"));
+    console.log(gray("     Run: infernoflow setup  to connect an AI provider"));
+  }
+  console.log();
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function explainCommand(rawArgs) {
+  const args    = (rawArgs || []).slice(1);
+  const dryRun  = args.includes("--dry-run");
+  const jsonMode = args.includes("--json");
+
+  const capId = args.find(a => !a.startsWith("--"));
+
+  if (!capId) {
+    console.error(red("✗ Usage: infernoflow explain <capability-id> [--dry-run] [--json]"));
+    console.error(gray("  Example: infernoflow explain user-auth"));
+    process.exit(1);
+  }
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  // Load capabilities
+  let allCaps = [];
+  const rawCaps = loadJson(path.join(infernoDir, "capabilities.json"));
+  if (rawCaps) allCaps = Array.isArray(rawCaps) ? rawCaps : (rawCaps.capabilities || []);
+
+  const cap = allCaps.find(c => c.id === capId);
+  if (!cap) {
+    console.error(red(`✗ Capability "${capId}" not found in capabilities.json`));
+    console.error(gray("  Run: infernoflow stability — to list all capability IDs"));
+    process.exit(1);
+  }
+
+  // Load scan + graph
+  const scanData  = loadJson(path.join(infernoDir, "scan.json"));
+  const graph     = loadJson(path.join(infernoDir, "graph.json"));
+  const scanEntry = scanData?.capabilities?.find(c => c.id === capId);
+
+  // Git history
+  const files       = scanEntry?.codeAnalysis?.sourceFiles || [];
+  const firstCommit = getFirstCommit(files[0], cwd);
+  const recentHistory = getRecentHistory(files[0], cwd);
+
+  // Scenarios
+  const scenarios = findScenarios(capId, infernoDir);
+
+  // Build prompt
+  const prompt = buildPrompt(capId, cap, scanEntry, graph, allCaps, scenarios, firstCommit, recentHistory);
+
+  if (dryRun && !jsonMode) {
+    console.log(gray(`\n  infernoflow explain  →  ${bold(capId)}`));
+    console.log(gray("  ──────────────────────────────────────────────────────────────"));
+    printExplain(capId, cap, "", null, true);
+    console.log(bold("  Prompt that would be sent to AI:"));
+    console.log();
+    console.log(prompt.split("\n").map(l => "    " + l).join("\n"));
+    console.log();
+    return;
+  }
+
+  // Call AI
+  let narrative = null;
+  let provider  = null;
+
+  if (!dryRun) {
+    try {
+      const result = await callAI(prompt, cwd);
+      if (result?.text) {
+        narrative = result.text.trim();
+        provider  = result.provider;
+      }
+    } catch {}
+  }
+
+  // Fallback if no AI
+  if (!narrative) {
+    narrative = buildFallback(capId, cap, scanEntry, graph, allCaps, scenarios);
+    provider  = null;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      capId,
+      name:      cap.name || cap.title,
+      stability: stability(cap),
+      narrative,
+      provider:  provider || "fallback",
+      sourceFiles: files,
+      scenarios:   scenarios.map(s => s.scenarioId || s.description),
+      firstCommit,
+    }, null, 2));
+    return;
+  }
+
+  console.log(gray(`\n  infernoflow explain  →  ${bold(capId)}`));
+  console.log(gray("  ──────────────────────────────────────────────────────────────"));
+  printExplain(capId, cap, narrative, provider, false);
+}

package/dist/lib/commands/test.mjs

@@ -0,0 +1,363 @@
+/**
+ * infernoflow test
+ *
+ * Run registered scenarios for a capability and report pass/fail.
+ * When no test runner is configured, generates a minimal ad-hoc harness
+ * from the scenario + source file and runs it with Node.
+ *
+ * Usage:
+ *   infernoflow test                          Run all caps with scenarios
+ *   infernoflow test user-auth                Run scenarios for one cap
+ *   infernoflow test user-auth payment-process  Run multiple caps
+ *   infernoflow test --all                    Run every cap (including no-scenario)
+ *   infernoflow test --generate user-auth     Print generated test file, don't run
+ *   infernoflow test --json                   Machine-readable output
+ *   infernoflow test --bail                   Stop on first failure
+ */
+
+import * as fs      from "node:fs";
+import * as path    from "node:path";
+import * as os      from "node:os";
+import { execSync, spawnSync } from "node:child_process";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function loadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return null; }
+}
+
+function stability(cap) { return cap?.stability || "experimental"; }
+
+const PASS_ICON = green("✓");
+const FAIL_ICON = red("✗");
+const SKIP_ICON = gray("○");
+
+// ── scenario loader ───────────────────────────────────────────────────────────
+
+function loadScenarios(capId, infernoDir) {
+  const dir = path.join(infernoDir, "scenarios");
+  if (!fs.existsSync(dir)) return [];
+  const found = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      const covered = s.capabilitiesCovered || s.capabilities || [];
+      if (covered.some(c => c.toLowerCase() === capId.toLowerCase())) {
+        found.push({ ...s, _file: f });
+      }
+    } catch {}
+  }
+  return found;
+}
+
+// ── test runner detection ─────────────────────────────────────────────────────
+
+function detectTestRunner(cwd) {
+  const pkg = loadJson(path.join(cwd, "package.json"));
+  if (!pkg) return null;
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps?.vitest)  return "vitest";
+  if (deps?.jest)    return "jest";
+  if (deps?.mocha)   return "mocha";
+  if (pkg.scripts?.test && !pkg.scripts.test.includes("no test")) {
+    return { custom: pkg.scripts.test };
+  }
+  return null;
+}
+
+// ── ad-hoc test generator ─────────────────────────────────────────────────────
+
+function generateAdHocTest(capId, cap, scenario, scanEntry) {
+  const name    = cap.name || cap.title || capId;
+  const desc    = cap.description || "(no description)";
+  const files   = scanEntry?.codeAnalysis?.sourceFiles || [];
+  const fns     = scanEntry?.codeAnalysis?.functions   || [];
+  const steps   = scenario?.steps   || scenario?.actions || [];
+  const expects = scenario?.expects || scenario?.assertions || [];
+
+  const lines = [
+    `// Auto-generated smoke test for: ${capId}`,
+    `// Generated by infernoflow test — edit as needed`,
+    ``,
+    `import { strict as assert } from "node:assert";`,
+    ``,
+    `// Capability: ${name}`,
+    `// ${desc}`,
+    ``,
+  ];
+
+  // Import source if we know the file
+  if (files.length) {
+    lines.push(`// Source: ${files[0]}`);
+    lines.push(`// import { ${fns[0] || capId} } from "./${path.basename(files[0])}";`);
+    lines.push(``);
+  }
+
+  lines.push(`async function run() {`);
+  lines.push(`  const results = [];`);
+  lines.push(``);
+
+  // Generate test cases from scenario steps
+  if (steps.length) {
+    steps.forEach((step, i) => {
+      const desc = typeof step === "string" ? step : (step.action || step.description || `step ${i + 1}`);
+      lines.push(`  // Step ${i + 1}: ${desc}`);
+      lines.push(`  results.push({ step: ${JSON.stringify(desc)}, status: "manual" });`);
+      lines.push(``);
+    });
+  } else {
+    lines.push(`  // No explicit steps — running basic smoke test`);
+    lines.push(`  results.push({ step: "capability exists", status: "pass" });`);
+    lines.push(``);
+  }
+
+  // Add assertion checks
+  if (expects.length) {
+    expects.forEach((exp, i) => {
+      const desc = typeof exp === "string" ? exp : (exp.condition || exp.description || `assertion ${i + 1}`);
+      lines.push(`  // Assert: ${desc}`);
+      lines.push(`  // assert(condition, ${JSON.stringify(desc)});`);
+    });
+    lines.push(``);
+  }
+
+  lines.push(`  return results;`);
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`run().then(results => {`);
+  lines.push(`  const failed = results.filter(r => r.status === "fail");`);
+  lines.push(`  results.forEach(r => {`);
+  lines.push(`    const icon = r.status === "pass" ? "✓" : r.status === "fail" ? "✗" : "○";`);
+  lines.push(`    console.log(\`  \${icon}  \${r.step}\`);`);
+  lines.push(`  });`);
+  lines.push(`  if (failed.length) { console.error(\`\\n  \${failed.length} failed\`); process.exit(1); }`);
+  lines.push(`  else console.log(\`\\n  All steps passed\`);`);
+  lines.push(`}).catch(err => { console.error(err); process.exit(1); });`);
+
+  return lines.join("\n");
+}
+
+// ── run a single scenario ─────────────────────────────────────────────────────
+
+function runScenario(capId, cap, scenario, scanEntry, cwd) {
+  const scenarioId = scenario?.scenarioId || scenario?.id || scenario?._file?.replace(".json", "") || "unnamed";
+  const runner     = detectTestRunner(cwd);
+
+  // If there are testFiles registered in the scenario, run those
+  const testFiles = scenario?.testFiles || scenario?.testFile ? [scenario.testFile].flat().filter(Boolean) : [];
+  if (testFiles.length) {
+    for (const tf of testFiles) {
+      const absPath = path.resolve(cwd, tf);
+      if (!fs.existsSync(absPath)) {
+        return { scenarioId, status: "skip", reason: `test file not found: ${tf}` };
+      }
+    }
+
+    // Run with detected test runner
+    if (runner && typeof runner === "string") {
+      const cmd = runner === "vitest"
+        ? `npx vitest run ${testFiles.join(" ")} --reporter verbose`
+        : runner === "jest"
+        ? `npx jest ${testFiles.join(" ")} --no-coverage`
+        : runner === "mocha"
+        ? `npx mocha ${testFiles.join(" ")}`
+        : null;
+
+      if (cmd) {
+        const result = spawnSync(cmd, { shell: true, cwd, encoding: "utf8", timeout: 60_000 });
+        const passed = result.status === 0;
+        return {
+          scenarioId,
+          status:   passed ? "pass" : "fail",
+          output:   (result.stdout || "") + (result.stderr || ""),
+          runner,
+        };
+      }
+    }
+
+    // Custom script runner
+    if (runner?.custom) {
+      const result = spawnSync(runner.custom, { shell: true, cwd, encoding: "utf8", timeout: 60_000 });
+      return {
+        scenarioId,
+        status: result.status === 0 ? "pass" : "fail",
+        output: (result.stdout || "") + (result.stderr || ""),
+        runner: "npm test",
+      };
+    }
+  }
+
+  // No test files — generate and run ad-hoc test
+  const testSrc = generateAdHocTest(capId, cap, scenario, scanEntry);
+  const tmpFile = path.join(os.tmpdir(), `infernoflow-test-${capId}-${Date.now()}.mjs`);
+
+  try {
+    fs.writeFileSync(tmpFile, testSrc);
+    const result = spawnSync(process.execPath, ["--input-type=module", tmpFile], {
+      cwd,
+      encoding: "utf8",
+      timeout:  30_000,
+    });
+    const passed = result.status === 0;
+    return {
+      scenarioId,
+      status:  passed ? "pass" : "fail",
+      output:  (result.stdout || "") + (result.stderr || ""),
+      runner:  "ad-hoc",
+      generated: true,
+    };
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch {}
+  }
+}
+
+// ── print result ──────────────────────────────────────────────────────────────
+
+function printCapResult(capId, cap, results, verbose) {
+  const level  = stability(cap);
+  const badge  = level === "frozen" ? red("frozen") : level === "stable" ? yellow("stable") : gray("experimental");
+  const total  = results.length;
+  const passed = results.filter(r => r.status === "pass").length;
+  const failed = results.filter(r => r.status === "fail").length;
+  const skipped = results.filter(r => r.status === "skip").length;
+
+  const statusIcon = failed > 0 ? red("✗") : passed > 0 ? green("✓") : gray("○");
+  console.log(`  ${statusIcon}  ${bold(capId)}  ${gray(`[${badge}]`)}`);
+
+  for (const r of results) {
+    const icon = r.status === "pass" ? PASS_ICON : r.status === "fail" ? FAIL_ICON : SKIP_ICON;
+    const note = r.generated ? gray(" (generated)") : r.runner ? gray(` (${r.runner})`) : "";
+    console.log(`       ${icon}  ${gray(r.scenarioId)}${note}`);
+    if (r.reason) console.log(`          ${gray(r.reason)}`);
+    if (verbose && r.output) {
+      const trimmed = r.output.trim().split("\n").slice(0, 10).join("\n");
+      console.log(trimmed.split("\n").map(l => `          ${gray(l)}`).join("\n"));
+    }
+  }
+
+  return { total, passed, failed, skipped };
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function testCommand(rawArgs) {
+  const args       = (rawArgs || []).slice(1);
+  const jsonMode   = args.includes("--json");
+  const bail       = args.includes("--bail");
+  const generateMode = args.includes("--generate");
+  const runAll     = args.includes("--all");
+  const verbose    = args.includes("--verbose") || args.includes("-v");
+
+  const capArgs    = args.filter(a => !a.startsWith("--") && a !== "-v");
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    if (!jsonMode) console.error(red("✗ inferno/ not found. Run: infernoflow init"));
+    process.exit(1);
+  }
+
+  // Load capabilities
+  let allCaps = [];
+  const rawCaps = loadJson(path.join(infernoDir, "capabilities.json"));
+  if (rawCaps) allCaps = Array.isArray(rawCaps) ? rawCaps : (rawCaps.capabilities || []);
+
+  const scanData = loadJson(path.join(infernoDir, "scan.json"));
+
+  // Determine which caps to test
+  let targetCaps;
+  if (capArgs.length) {
+    targetCaps = capArgs.map(id => {
+      const cap = allCaps.find(c => c.id === id);
+      if (!cap) {
+        if (!jsonMode) console.error(red(`✗ Capability "${id}" not found in capabilities.json`));
+        process.exit(1);
+      }
+      return cap;
+    });
+  } else if (runAll) {
+    targetCaps = allCaps;
+  } else {
+    // Default: caps that have scenarios registered
+    targetCaps = allCaps.filter(cap => loadScenarios(cap.id, infernoDir).length > 0);
+    if (!targetCaps.length) {
+      if (!jsonMode) {
+        console.log();
+        console.log(`  ${gray("No scenarios registered. Use --all to test all capabilities, or")} `);
+        console.log(`  ${gray("add scenarios to inferno/scenarios/ first.")}`);
+        console.log();
+      }
+      process.exit(0);
+    }
+  }
+
+  if (!jsonMode) {
+    console.log();
+    console.log(`  ${bold("🧪 infernoflow test")}`);
+    console.log();
+  }
+
+  // --generate mode: print generated test for first cap
+  if (generateMode) {
+    const cap     = targetCaps[0];
+    const scenarios = loadScenarios(cap.id, infernoDir);
+    const scenario  = scenarios[0] || {};
+    const scanEntry = scanData?.capabilities?.find(c => c.id === cap.id);
+    const src = generateAdHocTest(cap.id, cap, scenario, scanEntry);
+    console.log(src);
+    return;
+  }
+
+  // Run tests
+  const summary = { total: 0, passed: 0, failed: 0, skipped: 0, caps: [] };
+  let bailed = false;
+
+  for (const cap of targetCaps) {
+    const scenarios = loadScenarios(cap.id, infernoDir);
+    const scanEntry = scanData?.capabilities?.find(c => c.id === cap.id);
+
+    let capResults = [];
+
+    if (!scenarios.length) {
+      capResults = [{ scenarioId: "(no scenarios)", status: "skip", reason: "register scenarios in inferno/scenarios/" }];
+    } else {
+      for (const scenario of scenarios) {
+        const r = runScenario(cap.id, cap, scenario, scanEntry, cwd);
+        capResults.push(r);
+        if (bail && r.status === "fail") { bailed = true; break; }
+      }
+    }
+
+    const counts = printCapResult(cap.id, cap, capResults, verbose);
+    summary.total   += counts.total;
+    summary.passed  += counts.passed;
+    summary.failed  += counts.failed;
+    summary.skipped += counts.skipped;
+    summary.caps.push({ id: cap.id, stability: stability(cap), results: capResults });
+
+    if (bailed) break;
+  }
+
+  if (!jsonMode) {
+    console.log();
+    const statusColor = summary.failed > 0 ? red : summary.passed > 0 ? green : gray;
+    console.log(`  ${statusColor(bold(String(summary.passed)))} passed  ${summary.failed > 0 ? red(bold(String(summary.failed))) : gray("0")} failed  ${gray(String(summary.skipped))} skipped`);
+    if (bailed) console.log(`  ${yellow("(bailed on first failure)")}`);
+    console.log();
+    if (!summary.failed) {
+      console.log(gray("  ── infernoflow test complete"));
+    }
+    console.log();
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify(summary, null, 2));
+  }
+
+  process.exit(summary.failed > 0 ? 1 : 0);
+}

package/package.json

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