infernoflow 0.20.0 → 0.21.0

package/dist/bin/infernoflow.mjs

@@ -49,6 +49,8 @@ const COMMAND_DESCRIPTIONS = {
   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",
+  vibe:    "Vibe coding mode — watches files, auto-syncs contract, regenerates context on every save",
+  adopt:   "Interactive wizard to adopt infernoflow in an existing project (detect → review → wire up)",
 };
 
 const COMMAND_HANDLERS = {
@@ -91,6 +93,8 @@ const COMMAND_HANDLERS = {
   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),
+  vibe:     async (args) => (await import("../lib/commands/vibe.mjs")).vibeCommand(args),
+  adopt:    async (args) => (await import("../lib/commands/adoptWizard.mjs")).adoptWizardCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -287,6 +291,26 @@ ${formatCommandsHelp()}
     --fail-on high|medium     Exit 1 if unreviewed caps at given severity exist
     --json                    Machine-readable output
 
+  ${bold("vibe options:")}
+    --dir <dirs>              Comma-separated directories to watch (default: auto-detected)
+    --no-suggest              Disable automatic contract sync on file save
+    --no-context              Disable CONTEXT.md regeneration
+    --interval <secs>         Debounce seconds between saves (default: 4)
+    --port <n>                Also run a mini status dashboard on localhost:<n>
+    --silent                  Suppress all terminal output (pure background mode)
+
+  ${bold("adopt options:")}
+    --dir <dirs>              Source directories to scan (default: src,lib,app,api,routes,controllers)
+    --yes, -y                 Auto-approve all candidates (non-interactive)
+    --json                    Machine-readable output, implies --yes
+
+  ${bold("init --template options:")}
+    --template rest-api       REST API (Express/Fastify/Hono) starter
+    --template nextjs         Next.js fullstack app starter
+    --template cli            CLI tool (Node.js/Python) starter
+    --template graphql        GraphQL API (Apollo/Pothos) starter
+    --template monorepo       Monorepo workspace starter
+
   ${bold("scout options:")}
     --dir <dirs>              Comma-separated directories to scan (default: src,lib,app,api,routes)
     --apply                   Write discovered capabilities to the contract file

package/dist/lib/commands/adoptWizard.mjs

@@ -0,0 +1,320 @@
+/**
+ * infernoflow adopt
+ *
+ * Interactive adoption wizard for existing projects.
+ * Takes a project from zero to fully wired in one guided flow.
+ *
+ * Steps:
+ *   1. Detect project type, framework, language
+ *   2. Scout capabilities in source files
+ *   3. Interactive approve / rename / skip each candidate
+ *   4. Write capabilities.json + contract.json
+ *   5. Generate starter scenarios
+ *   6. Install git hooks
+ *   7. Regenerate CONTEXT.md
+ *   8. Show health score and next steps
+ *
+ * Usage:
+ *   infernoflow adopt              Full interactive wizard
+ *   infernoflow adopt --yes        Auto-approve all (non-interactive)
+ *   infernoflow adopt --dir src    Custom source directory
+ *   infernoflow adopt --json       Machine-readable, implies --yes
+ */
+
+import * as fs        from "node:fs";
+import * as path      from "node:path";
+import * as readline  from "node:readline";
+import { spawnSync }  from "node:child_process";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── Detection ─────────────────────────────────────────────────────────────────
+
+function detectProject(cwd) {
+  const has  = (...files) => files.some(f => fs.existsSync(path.join(cwd, f)));
+  const read = (f)        => { try { return JSON.parse(fs.readFileSync(path.join(cwd, f), "utf8")); } catch { return {}; } };
+
+  const pkg   = has("package.json") ? read("package.json") : {};
+  const deps  = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  let framework = "unknown", lang = "javascript", type = "backend";
+
+  if (has("tsconfig.json"))                            lang = "typescript";
+  if (has("Pipfile","pyproject.toml","requirements.txt")) lang = "python";
+  if (has("Gemfile"))                                  lang = "ruby";
+  if (has("go.mod"))                                   lang = "go";
+  if (has("Cargo.toml"))                               lang = "rust";
+
+  if      (deps["next"])              { framework = "nextjs";   type = "fullstack"; }
+  else if (deps["nuxt"])              { framework = "nuxt";     type = "fullstack"; }
+  else if (deps["react"])             { framework = "react";    type = "frontend"; }
+  else if (deps["vue"])               { framework = "vue";      type = "frontend"; }
+  else if (deps["@angular/core"])     { framework = "angular";  type = "frontend"; }
+  else if (deps["express"])           { framework = "express";  type = "backend"; }
+  else if (deps["fastify"])           { framework = "fastify";  type = "backend"; }
+  else if (deps["hono"])              { framework = "hono";     type = "backend"; }
+  else if (deps["@nestjs/core"])      { framework = "nestjs";   type = "backend"; }
+  else if (deps["graphql"])           { framework = "graphql";  type = "backend"; }
+  else if (has("config/routes.rb"))   { framework = "rails";    type = "fullstack"; }
+  else if (has("manage.py"))          { framework = "django";   type = "backend"; }
+
+  if (pkg.bin || has("bin/"))         type = "cli";
+  if (has("nx.json","turbo.json","pnpm-workspace.yaml")) type = "monorepo";
+
+  return {
+    name:        pkg.name        || path.basename(cwd),
+    version:     pkg.version     || "0.1.0",
+    description: pkg.description || "",
+    lang, framework, type,
+  };
+}
+
+// ── Scout ─────────────────────────────────────────────────────────────────────
+
+const SRC_EXTS   = new Set([".js",".mjs",".cjs",".ts",".tsx",".jsx",".py",".rb"]);
+const SKIP_DIRS  = new Set(["node_modules",".git","dist","build",".next","__pycache__","vendor","coverage","inferno"]);
+
+const PATTERNS = [
+  {
+    regex: /(?:app|router|server)\s*\.\s*(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+    extract: m => ({ id: routeId(m[2], m[1]), hint: `${m[1].toUpperCase()} ${m[2]}`, confidence: 0.85 }),
+  },
+  {
+    filePattern: /[/\\](pages[/\\]api|app[/\\]api)[/\\](.+)\.(js|ts|mjs)$/,
+    extract: fp => {
+      const m = fp.match(/[/\\](pages[/\\]api|app[/\\]api)[/\\](.+)\.(js|ts|mjs)$/);
+      if (!m) return null;
+      const r = m[2].replace(/[/\\]index$/, "").replace(/\[([^\]]+)\]/g, ":$1");
+      return { id: routeId("/" + r, "api"), hint: `Next.js API: /${r}`, confidence: 0.9 };
+    },
+  },
+  {
+    regex: /export\s+(?:async\s+)?(?:function|class|const)\s+([A-Z][A-Za-z0-9]+)/g,
+    extract: m => ({ id: camelId(m[1]), hint: `export ${m[1]}`, confidence: 0.65 }),
+  },
+];
+
+function routeId(r, method) {
+  const id = r.replace(/^\//, "").replace(/\/:?[^/]+/g, "").replace(/\//g, "-")
+    .replace(/[^a-zA-Z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+  return id || method.toLowerCase() + "-root";
+}
+function camelId(name) {
+  return name.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "").replace(/-+/g, "-");
+}
+
+function* walk(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) yield* walk(full);
+    else if (e.isFile() && SRC_EXTS.has(path.extname(e.name))) yield full;
+  }
+}
+
+function scout(dirs, cwd) {
+  const seen = new Map();
+  const add  = (id, r, file) => {
+    if (!seen.has(id) || r.confidence > seen.get(id).confidence)
+      seen.set(id, { ...r, source: path.relative(cwd, file) });
+  };
+
+  for (const dir of dirs) {
+    for (const file of walk(dir)) {
+      for (const pat of PATTERNS) {
+        if (pat.filePattern && pat.filePattern.test(file)) {
+          const r = pat.extract(file);
+          if (r && r.id.length >= 3) add(r.id, r, file);
+        }
+      }
+      let content;
+      try { content = fs.readFileSync(file, "utf8"); } catch { continue; }
+      for (const pat of PATTERNS) {
+        if (!pat.regex) continue;
+        pat.regex.lastIndex = 0;
+        let m;
+        while ((m = pat.regex.exec(content)) !== null) {
+          const r = pat.extract(m);
+          if (r && r.id.length >= 3 && !["index","app","main","root","default","handler"].includes(r.id))
+            add(r.id, r, file);
+        }
+      }
+    }
+  }
+  return [...seen.values()].filter(c => c.confidence >= 0.5).sort((a, b) => b.confidence - a.confidence);
+}
+
+// ── Interactive review ────────────────────────────────────────────────────────
+
+function ask(rl, q) { return new Promise(r => rl.question(q, r)); }
+
+async function review(candidates, autoYes) {
+  if (autoYes) return candidates.filter(c => c.confidence >= 0.6);
+
+  const approved = [];
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log();
+  console.log(`  ${bold("Review candidates")}  ${cyan("y")} approve · ${yellow("e")} edit · ${red("n")} skip · ${gray("a")} approve all · ${gray("q")} stop`);
+  console.log();
+
+  for (let i = 0; i < candidates.length; i++) {
+    const c    = candidates[i];
+    const conf = `${Math.round(c.confidence * 100)}%`;
+    const col  = c.confidence >= 0.8 ? green : c.confidence >= 0.65 ? yellow : gray;
+    process.stdout.write(
+      `  [${i + 1}/${candidates.length}] ${bold(c.id.padEnd(30))} ${col(conf)}  ${gray(c.hint)}\n` +
+      `  ${gray(c.source)}\n  > `
+    );
+
+    const ans = (await ask(rl, "")).trim().toLowerCase();
+    if (ans === "q") break;
+    if (ans === "a") {
+      for (let j = i; j < candidates.length; j++) approved.push(candidates[j]);
+      break;
+    }
+    if (ans === "n") { console.log(`  ${gray("skipped")}\n`); continue; }
+
+    let id = c.id;
+    if (ans === "e") {
+      const newId = (await ask(rl, `  New id (${c.id}): `)).trim();
+      if (newId && /^[a-z0-9-_]+$/.test(newId)) id = newId;
+    }
+    approved.push({ ...c, id });
+    console.log(`  ${green("✔")} ${bold(id)}\n`);
+  }
+
+  rl.close();
+  return approved;
+}
+
+// ── Writers ───────────────────────────────────────────────────────────────────
+
+function writeFiles(infernoDir, approved, project) {
+  // contract.json
+  const cp = path.join(infernoDir, "contract.json");
+  const existing = fs.existsSync(cp) ? JSON.parse(fs.readFileSync(cp, "utf8")) : {};
+  fs.writeFileSync(cp, JSON.stringify({
+    ...existing,
+    policyId:      existing.policyId || project.name.replace(/[^a-zA-Z0-9-]/g, "-"),
+    policyVersion: existing.policyVersion || 1,
+    capabilities:  approved.map(c => c.id),
+  }, null, 2) + "\n");
+
+  // capabilities.json
+  fs.writeFileSync(path.join(infernoDir, "capabilities.json"), JSON.stringify({
+    capabilities: approved.map(c => ({
+      id: c.id, description: c.hint,
+      since: new Date().toISOString().slice(0, 10), source: "adopt",
+    })),
+  }, null, 2) + "\n");
+
+  // Starter scenarios
+  const scenDir = path.join(infernoDir, "scenarios");
+  if (!fs.existsSync(scenDir)) fs.mkdirSync(scenDir, { recursive: true });
+  for (const c of approved) {
+    const sp = path.join(scenDir, `${c.id}.json`);
+    if (fs.existsSync(sp)) continue;
+    fs.writeFileSync(sp, JSON.stringify({
+      id: `${c.id}-happy-path`, capability: c.id,
+      description: `Happy path for ${c.description || c.id}`,
+      steps: [{ action: "invoke", target: c.id, input: {} }, { action: "assert", field: "status", value: "success" }],
+      capabilitiesCovered: [c.id],
+    }, null, 2) + "\n");
+  }
+}
+
+function runCli(args, cwd) {
+  return spawnSync("infernoflow", args, {
+    cwd, encoding: "utf8", timeout: 30_000,
+    stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, NO_COLOR: "1" },
+  });
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function adoptWizardCommand(rawArgs) {
+  const args     = rawArgs.slice(1);
+  const autoYes  = args.includes("--yes") || args.includes("-y") || args.includes("--json");
+  const jsonMode = args.includes("--json");
+  const cwd      = process.cwd();
+
+  const dirIdx   = args.indexOf("--dir");
+  const dirs     = dirIdx !== -1
+    ? args[dirIdx + 1].split(",").map(d => path.resolve(cwd, d.trim()))
+    : ["src","lib","app","api","pages","routes","controllers","services","handlers"]
+        .map(d => path.join(cwd, d)).filter(d => fs.existsSync(d));
+  if (!dirs.length) dirs.push(cwd);
+
+  const project    = detectProject(cwd);
+  const infernoDir = path.join(cwd, "inferno");
+  if (!fs.existsSync(infernoDir)) {
+    fs.mkdirSync(infernoDir, { recursive: true });
+    fs.mkdirSync(path.join(infernoDir, "scenarios"), { recursive: true });
+  }
+
+  if (!jsonMode) {
+    console.log();
+    console.log(`  ${bold("🔥 infernoflow adopt")} ${gray("— existing project wizard")}`);
+    console.log();
+    console.log(`  ${bold("Project:")}   ${cyan(project.name)} v${project.version}`);
+    console.log(`  ${bold("Language:")}  ${project.lang}   ${bold("Framework:")} ${project.framework}   ${bold("Type:")} ${project.type}`);
+    console.log();
+    info(`Scanning ${dirs.map(d => path.relative(cwd, d) || ".").join(", ")} …`);
+  }
+
+  const candidates = scout(dirs, cwd);
+
+  if (!candidates.length) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "No capabilities detected." })); return; }
+    warn("No capabilities detected. Use --dir src,lib,api");
+    return;
+  }
+
+  if (!jsonMode) {
+    console.log();
+    console.log(`  ${bold(`${candidates.length} capability candidates detected`)}`);
+  }
+
+  const approved = await review(candidates, autoYes);
+
+  if (!approved.length) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "No capabilities approved." })); return; }
+    warn("Nothing approved — exiting.");
+    return;
+  }
+
+  writeFiles(infernoDir, approved, project);
+  runCli(["context"], cwd);
+
+  // Offer hooks in interactive mode
+  let hooksInstalled = false;
+  if (!autoYes) {
+    const rl3 = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ans  = (await ask(rl3, `\n  Install git hooks for auto-sync? ${gray("[Y/n]")} `)).trim().toLowerCase();
+    rl3.close();
+    if (ans !== "n") { runCli(["setup", "--yes"], cwd); hooksInstalled = true; }
+  } else {
+    runCli(["setup", "--yes"], cwd); hooksInstalled = true;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, project, detected: candidates.length, approved: approved.length, capabilities: approved.map(c => c.id), hooksInstalled }));
+    return;
+  }
+
+  console.log();
+  done(`${bold(String(approved.length))} capabilities adopted`);
+  console.log();
+  console.log(`  ${green("✔")} ${bold("inferno/contract.json")} written`);
+  console.log(`  ${green("✔")} ${bold("inferno/capabilities.json")} written`);
+  console.log(`  ${green("✔")} ${bold("inferno/scenarios/")} scaffolded`);
+  console.log(`  ${green("✔")} ${bold("inferno/CONTEXT.md")} generated`);
+  if (hooksInstalled) console.log(`  ${green("✔")} Git hooks installed`);
+  console.log();
+  console.log(`  ${bold("Next steps:")}`);
+  console.log(`  ${cyan("1.")} Paste ${bold("inferno/CONTEXT.md")} into Claude or Cursor`);
+  console.log(`  ${cyan("2.")} Run ${bold("infernoflow vibe")} to keep everything in sync automatically`);
+  console.log(`  ${cyan("3.")} Run ${bold("infernoflow health")} to see your starting score`);
+  console.log();
+}

package/dist/lib/commands/init.mjs

@@ -155,6 +155,76 @@ export async function initCommand(args) {
   const force = args.includes("--force") || args.includes("-f");
   const yes = args.includes("--yes") || args.includes("-y");
   const adopt = args.includes("--adopt");
+
+  // ── Template shortcut ──────────────────────────────────────────────────────
+  const templateIdx  = args.indexOf("--template");
+  const templateName = templateIdx !== -1 ? args[templateIdx + 1] : null;
+
+  if (templateName) {
+    let tmplMod;
+    try { tmplMod = await import("../templates/index.mjs"); } catch {}
+    const tmpl = tmplMod?.getTemplate(templateName);
+    if (!tmpl) {
+      const available = tmplMod ? tmplMod.listTemplates().map(t => t.name).join(", ") : "rest-api, nextjs, cli, graphql, monorepo";
+      warn(`Unknown template: ${templateName}. Available: ${available}`);
+      process.exit(1);
+    }
+
+    const infernoDir = path.join(cwd, "inferno");
+    const scenDir    = path.join(infernoDir, "scenarios");
+    if (!fs.existsSync(infernoDir)) fs.mkdirSync(infernoDir, { recursive: true });
+    if (!fs.existsSync(scenDir))    fs.mkdirSync(scenDir,    { recursive: true });
+
+    const policyId = detectProjectName(cwd);
+    const caps     = tmpl.capabilities;
+
+    // Write contract.json
+    fs.writeFileSync(path.join(infernoDir, "contract.json"), JSON.stringify({
+      policyId, policyVersion: 1,
+      capabilities: caps.map(c => c.id),
+    }, null, 2) + "\n");
+
+    // Write capabilities.json
+    fs.writeFileSync(path.join(infernoDir, "capabilities.json"), JSON.stringify({
+      capabilities: caps.map(c => ({
+        id: c.id, description: c.description,
+        since: new Date().toISOString().slice(0, 10), source: `template:${templateName}`,
+      })),
+    }, null, 2) + "\n");
+
+    // Write one scenario per capability
+    for (const cap of caps) {
+      fs.writeFileSync(path.join(scenDir, `${cap.id}.json`), JSON.stringify({
+        id: `${cap.id}-happy-path`, capability: cap.id,
+        description: `Happy path for ${cap.description || cap.id}`,
+        steps: [
+          { action: "invoke", target: cap.id, input: {} },
+          { action: "assert", field: "status", value: "success" },
+        ],
+        capabilitiesCovered: [cap.id],
+      }, null, 2) + "\n");
+    }
+
+    // Write CHANGELOG.md
+    writeChangelog(path.join(infernoDir, "CHANGELOG.md"), policyId);
+
+    // Write CONTEXT.md hint
+    fs.writeFileSync(path.join(infernoDir, "CONTEXT.md"),
+      `# ${policyId} — infernoflow context\n\n> Template: ${templateName} — ${tmpl.description}\n\n## Hint\n${tmpl.contextHint}\n\n## Capabilities (${caps.length})\n${caps.map(c => `- \`${c.id}\`: ${c.description}`).join("\n")}\n`
+    );
+
+    if (tmpl.scripts) {
+      info(`Suggested package.json scripts for this template:`);
+      Object.entries(tmpl.scripts).forEach(([k, v]) => console.log(`  ${bold(k)}: ${gray(v)}`));
+      console.log();
+    }
+
+    done(`Initialised from template ${bold(cyan(templateName))} — ${bold(String(caps.length))} capabilities`);
+    console.log();
+    info(`Run ${cyan("infernoflow vibe")} to start vibe coding mode`);
+    console.log();
+    return;
+  }
   const cursorHooks = args.includes("--cursor-hooks");
   const vscodeCopilotHooks = args.includes("--vscode-copilot-hooks");
   const reportJson = args.includes("--report-json");

package/dist/lib/commands/vibe.mjs

@@ -0,0 +1,365 @@
+/**
+ * infernoflow vibe
+ *
+ * Persistent background process for vibe coding sessions.
+ * Completely invisible to the developer — just leave it running in a terminal.
+ *
+ * What it does every cycle:
+ *   1. Watches source files for saves
+ *   2. On save: runs infernoflow suggest to sync the contract
+ *   3. Regenerates CONTEXT.md so the next AI prompt is always fresh
+ *   4. Watches inferno/ for contract changes → updates CONTEXT.md automatically
+ *   5. Prints a one-line status ticker — nothing noisy
+ *
+ * Also provides a session summary on exit (Ctrl+C):
+ *   - Files changed
+ *   - Capabilities added / updated
+ *   - Health score delta
+ *
+ * Usage:
+ *   infernoflow vibe                    Start vibe mode (default dirs)
+ *   infernoflow vibe --dir src,api      Watch specific directories
+ *   infernoflow vibe --no-suggest       Watch + context only, skip suggest
+ *   infernoflow vibe --no-context       Skip CONTEXT.md regeneration
+ *   infernoflow vibe --interval 5       Debounce seconds (default 4)
+ *   infernoflow vibe --silent           Suppress all output (pure background)
+ *   infernoflow vibe --port 7337        Also start dashboard on this port
+ */
+
+import * as fs          from "node:fs";
+import * as path        from "node:path";
+import * as http        from "node:http";
+import * as os          from "node:os";
+import { execSync, spawnSync } from "node:child_process";
+import { bold, cyan, gray, green, yellow, red, info, warn } from "../ui/output.mjs";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py", ".rb", ".go", ".rs"]);
+const IGNORE_DIRS       = new Set(["node_modules", ".git", "dist", "build", ".next", "__pycache__", "vendor", "coverage", "inferno"]);
+
+function runCli(args, cwd, silent = false) {
+  const result = spawnSync("infernoflow", args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" },
+    timeout: 30_000,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (!silent && result.error) return { ok: false, out: "", err: result.error.message };
+  return { ok: result.status === 0, out: result.stdout || "", err: result.stderr || "" };
+}
+
+function timestamp() {
+  return new Date().toLocaleTimeString("en-US", { hour12: false });
+}
+
+function readContractCapCount(infernoDir) {
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(p, "utf8"));
+      return (data.capabilities || []).length;
+    } catch {}
+  }
+  return 0;
+}
+
+function readHealthScore(cwd) {
+  const result = spawnSync("infernoflow", ["health", "--json"], {
+    cwd, encoding: "utf8", timeout: 20_000, stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+  try { return JSON.parse(result.stdout || "{}").score ?? null; } catch { return null; }
+}
+
+// ── Session state ─────────────────────────────────────────────────────────────
+
+class VibeSession {
+  constructor() {
+    this.startedAt      = new Date();
+    this.filesChanged   = new Set();
+    this.suggestRuns    = 0;
+    this.contextUpdates = 0;
+    this.capsAtStart    = 0;
+    this.capsNow        = 0;
+    this.scoreAtStart   = null;
+    this.scoreNow       = null;
+  }
+
+  recordChange(filePath) { this.filesChanged.add(filePath); }
+  recordSuggest()        { this.suggestRuns++; }
+  recordContext()        { this.contextUpdates++; }
+
+  elapsed() {
+    const ms   = Date.now() - this.startedAt.getTime();
+    const mins = Math.floor(ms / 60000);
+    const secs = Math.floor((ms % 60000) / 1000);
+    return mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+  }
+
+  printSummary() {
+    const capDelta   = this.capsNow - this.capsAtStart;
+    const scoreDelta = this.scoreNow !== null && this.scoreAtStart !== null
+      ? this.scoreNow - this.scoreAtStart : null;
+
+    console.log();
+    console.log(`  ${bold("🔥 infernoflow vibe — session summary")}`);
+    console.log();
+    console.log(`  ${bold("Duration:")}      ${this.elapsed()}`);
+    console.log(`  ${bold("Files watched:")} ${this.filesChanged.size}`);
+    console.log(`  ${bold("Syncs run:")}     ${this.suggestRuns}`);
+    console.log(`  ${bold("Context refreshes:")} ${this.contextUpdates}`);
+
+    if (capDelta !== 0) {
+      const col = capDelta > 0 ? green : yellow;
+      console.log(`  ${bold("Capabilities:")}  ${col((capDelta > 0 ? "+" : "") + capDelta)} (${this.capsAtStart} → ${this.capsNow})`);
+    } else {
+      console.log(`  ${bold("Capabilities:")}  ${this.capsNow} (no change)`);
+    }
+
+    if (scoreDelta !== null) {
+      const col = scoreDelta > 0 ? green : scoreDelta < 0 ? yellow : gray;
+      console.log(`  ${bold("Health score:")}  ${col((scoreDelta > 0 ? "+" : "") + scoreDelta)} (${this.scoreAtStart} → ${this.scoreNow})`);
+    }
+
+    console.log();
+  }
+}
+
+// ── Status ticker ─────────────────────────────────────────────────────────────
+
+const SPINNERS = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+let spinIdx = 0;
+
+function tick(msg, col = gray) {
+  const spinner = SPINNERS[spinIdx++ % SPINNERS.length];
+  process.stdout.write(`\r  ${col(spinner)}  ${msg}                    `);
+}
+
+function tickDone(msg) {
+  process.stdout.write(`\r  ${green("✔")}  ${msg}                    \n`);
+}
+
+function tickWarn(msg) {
+  process.stdout.write(`\r  ${yellow("⚠")}  ${msg}                    \n`);
+}
+
+// ── Core cycle ────────────────────────────────────────────────────────────────
+
+async function runCycle(changedFile, cwd, infernoDir, opts, session) {
+  const rel = path.relative(cwd, changedFile);
+  session.recordChange(changedFile);
+
+  if (!opts.silent) tick(`${cyan(rel)} changed — syncing…`, cyan);
+
+  // 1. Suggest (sync contract)
+  if (!opts.noSuggest) {
+    const desc = `updated ${path.basename(changedFile)}`;
+    const r    = runCli(["suggest", desc, "--json"], cwd, true);
+    session.recordSuggest();
+
+    if (!opts.silent) {
+      if (r.ok) {
+        tickDone(`Synced: ${cyan(rel)}`);
+      } else {
+        tickWarn(`Suggest skipped (${gray("no AI provider")})`);
+      }
+    }
+  }
+
+  // 2. Regenerate CONTEXT.md
+  if (!opts.noContext) {
+    const r = runCli(["context"], cwd, true);
+    session.recordContext();
+    if (!opts.silent && r.ok) {
+      tick(`Context refreshed`, gray);
+    }
+  }
+
+  // 3. Update cap count
+  session.capsNow = readContractCapCount(infernoDir);
+}
+
+// ── File watcher ──────────────────────────────────────────────────────────────
+
+function watchDirs(dirs, cwd, infernoDir, opts, session) {
+  const watchers = [];
+  const debounceMap = new Map();
+
+  const onFileChange = (eventType, filePath) => {
+    if (!SOURCE_EXTENSIONS.has(path.extname(filePath))) return;
+    if ([...IGNORE_DIRS].some(d => filePath.includes(`${path.sep}${d}${path.sep}`))) return;
+
+    // Debounce per file
+    if (debounceMap.has(filePath)) clearTimeout(debounceMap.get(filePath));
+    debounceMap.set(filePath, setTimeout(async () => {
+      debounceMap.delete(filePath);
+      await runCycle(filePath, cwd, infernoDir, opts, session);
+    }, opts.interval * 1000));
+  };
+
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+    try {
+      const w = fs.watch(dir, { recursive: true }, (eventType, filename) => {
+        if (!filename) return;
+        onFileChange(eventType, path.join(dir, filename));
+      });
+      watchers.push(w);
+    } catch {}
+  }
+
+  // Also watch inferno/ for contract changes → regenerate CONTEXT.md
+  try {
+    const iw = fs.watch(infernoDir, { recursive: true }, (eventType, filename) => {
+      if (!filename) return;
+      if (!filename.endsWith(".json") && !filename.endsWith(".md")) return;
+      if (filename.includes("CONTEXT")) return; // avoid loop
+
+      if (debounceMap.has("__inferno__")) clearTimeout(debounceMap.get("__inferno__"));
+      debounceMap.set("__inferno__", setTimeout(async () => {
+        debounceMap.delete("__inferno__");
+        if (!opts.noContext) {
+          runCli(["context"], cwd, true);
+          session.recordContext();
+          if (!opts.silent) tick(`Contract updated — context refreshed`, gray);
+        }
+        session.capsNow = readContractCapCount(infernoDir);
+      }, 1000));
+    });
+    watchers.push(iw);
+  } catch {}
+
+  return watchers;
+}
+
+// ── Dashboard mini-server ─────────────────────────────────────────────────────
+
+function startMiniDashboard(port, cwd, infernoDir) {
+  const server = http.createServer((req, res) => {
+    if (req.url === "/status") {
+      const caps   = readContractCapCount(infernoDir);
+      const health = readHealthScore(cwd);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, capabilities: caps, health, ts: new Date().toISOString() }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(`<!DOCTYPE html><html><head><meta charset="UTF-8">
+    <meta http-equiv="refresh" content="10">
+    <title>🔥 vibe</title>
+    <style>body{font-family:system-ui;background:#0f1117;color:#e2e8f0;display:flex;align-items:center;justify-content:center;height:100vh;margin:0;flex-direction:column;gap:16px}
+    h1{color:#f97316;margin:0}.sub{color:#64748b;font-size:14px}</style></head>
+    <body><h1>🔥 infernoflow vibe</h1><div class="sub">Auto-refreshes every 10s</div>
+    <script>
+    fetch('/status').then(r=>r.json()).then(d=>{
+      document.body.innerHTML='<h1>🔥 vibe</h1><p style="color:#22c55e">'+d.capabilities+' capabilities</p>'
+        +(d.health!==null?'<p>Health: '+d.health+'/100</p>':'')
+        +'<p style="color:#64748b;font-size:12px">'+new Date(d.ts).toLocaleTimeString()+'</p>';
+    });
+    </script></body></html>`);
+  });
+  server.listen(port, "127.0.0.1", () => {});
+  return server;
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function vibeCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const silent    = args.includes("--silent");
+  const noSuggest = args.includes("--no-suggest");
+  const noContext = args.includes("--no-context");
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    warn("inferno/ not found. Run: infernoflow init");
+    process.exit(1);
+  }
+
+  // Parse flags
+  const dirIdx     = args.indexOf("--dir");
+  const intervalIdx = args.indexOf("--interval");
+  const portIdx    = args.indexOf("--port");
+
+  const interval   = intervalIdx !== -1 ? parseInt(args[intervalIdx + 1], 10) : 4;
+  const port       = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : null;
+
+  const scanDirs   = dirIdx !== -1
+    ? args[dirIdx + 1].split(",").map(d => path.resolve(cwd, d.trim()))
+    : ["src", "lib", "app", "api", "pages", "routes", "controllers", "handlers", "services"]
+        .map(d => path.join(cwd, d))
+        .filter(d => fs.existsSync(d));
+
+  if (!scanDirs.length) {
+    // Watch the whole project root as fallback
+    scanDirs.push(cwd);
+  }
+
+  const opts = { silent, noSuggest, noContext, interval };
+  const session = new VibeSession();
+
+  // Snapshot initial state
+  session.capsAtStart = readContractCapCount(infernoDir);
+  session.capsNow     = session.capsAtStart;
+  session.scoreAtStart = readHealthScore(cwd);
+
+  if (!silent) {
+    console.log();
+    console.log(`  ${bold("🔥 infernoflow vibe")} ${gray("— vibe coding mode active")}`);
+    console.log();
+    console.log(`  ${bold("Watching:")} ${scanDirs.map(d => path.relative(cwd, d) || ".").join(", ")}`);
+    console.log(`  ${bold("Debounce:")} ${interval}s`);
+    if (noSuggest) console.log(`  ${gray("--no-suggest: contract sync disabled")}`);
+    if (noContext)  console.log(`  ${gray("--no-context: CONTEXT.md refresh disabled")}`);
+    console.log();
+    console.log(`  ${cyan(String(session.capsAtStart))} capabilities in contract`);
+    if (session.scoreAtStart !== null) console.log(`  Health score: ${cyan(String(session.scoreAtStart))}/100`);
+    console.log();
+    console.log(`  ${gray("Watching for file saves… Press Ctrl+C to stop and see session summary.")}`);
+    console.log();
+  }
+
+  // Optional mini dashboard
+  if (port) {
+    startMiniDashboard(port, cwd, infernoDir);
+    if (!silent) info(`Mini dashboard → http://localhost:${port}`);
+  }
+
+  // Start watching
+  const watchers = watchDirs(scanDirs, cwd, infernoDir, opts, session);
+
+  if (!watchers.length) {
+    warn("No directories to watch. Use --dir src,lib,api");
+    process.exit(1);
+  }
+
+  // Spinner to show we're alive
+  let spinTimer = null;
+  if (!silent) {
+    let idleMsg = "Watching…";
+    spinTimer = setInterval(() => {
+      tick(idleMsg, gray);
+    }, 150);
+  }
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    if (spinTimer) clearInterval(spinTimer);
+    process.stdout.write("\r                                              \r");
+    watchers.forEach(w => { try { w.close(); } catch {} });
+    session.scoreNow = readHealthScore(cwd);
+    session.capsNow  = readContractCapCount(infernoDir);
+    if (!silent) session.printSummary();
+    process.exit(0);
+  };
+
+  process.on("SIGINT",  shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // Keep alive
+  await new Promise(() => {});
+}

package/dist/lib/templates/index.mjs

@@ -0,0 +1,131 @@
+/**
+ * infernoflow project templates
+ *
+ * Named starters for `infernoflow init --template <name>`.
+ * Each template provides:
+ *   - capabilities  : pre-populated capability list
+ *   - scenarios     : one starter scenario per capability
+ *   - contextHint   : first-session CONTEXT.md guidance
+ *   - scripts       : suggested package.json scripts to add
+ */
+
+export const TEMPLATES = {
+
+  // ── REST API ────────────────────────────────────────────────────────────────
+  "rest-api": {
+    description: "Express / Fastify / Hono REST API",
+    capabilities: [
+      { id: "list-items",      description: "GET /items — paginated list with filtering and sorting" },
+      { id: "get-item",        description: "GET /items/:id — fetch a single resource by ID" },
+      { id: "create-item",     description: "POST /items — create a new resource, validate input" },
+      { id: "update-item",     description: "PUT /items/:id — full update of an existing resource" },
+      { id: "delete-item",     description: "DELETE /items/:id — soft or hard delete" },
+      { id: "authenticate",    description: "POST /auth/login — exchange credentials for a JWT token" },
+      { id: "refresh-token",   description: "POST /auth/refresh — extend session with a new token" },
+      { id: "health-check",    description: "GET /health — liveness probe for load balancers" },
+      { id: "paginate",        description: "Cursor or offset pagination applied across list endpoints" },
+      { id: "validate-input",  description: "Schema validation on all incoming request bodies" },
+    ],
+    contextHint: "Building a REST API. Focus on route handlers, middleware, and input validation.",
+    scripts: {
+      "dev":   "node src/index.js",
+      "start": "node dist/index.js",
+    },
+  },
+
+  // ── Next.js ─────────────────────────────────────────────────────────────────
+  "nextjs": {
+    description: "Next.js full-stack app (App Router or Pages Router)",
+    capabilities: [
+      { id: "render-home-page",    description: "/ — server-rendered landing page with SEO metadata" },
+      { id: "render-dashboard",    description: "/dashboard — authenticated user dashboard" },
+      { id: "api-authenticate",    description: "POST /api/auth/login — issue session cookie or JWT" },
+      { id: "api-list-resources",  description: "GET /api/resources — paginated list, auth-protected" },
+      { id: "api-create-resource", description: "POST /api/resources — create and persist a resource" },
+      { id: "server-side-props",   description: "Fetch user-specific data server-side before render" },
+      { id: "static-generation",   description: "Pre-render marketing pages at build time" },
+      { id: "image-optimization",  description: "next/image usage for responsive, lazy-loaded images" },
+      { id: "middleware-auth",     description: "Edge middleware to protect dashboard routes" },
+      { id: "error-boundary",      description: "Global error.tsx / _error.tsx user-facing error page" },
+    ],
+    contextHint: "Building a Next.js app. Use Server Components by default; Client Components only when needed.",
+    scripts: {
+      "dev":   "next dev",
+      "build": "next build",
+      "start": "next start",
+    },
+  },
+
+  // ── CLI tool ────────────────────────────────────────────────────────────────
+  "cli": {
+    description: "Node.js / Python CLI tool",
+    capabilities: [
+      { id: "parse-args",       description: "Parse CLI arguments and flags, show help on --help" },
+      { id: "validate-config",  description: "Load and validate config file or env vars on startup" },
+      { id: "main-command",     description: "Primary command — the core action the CLI performs" },
+      { id: "output-formatter", description: "Format output as text, JSON, or table based on --format flag" },
+      { id: "error-handler",    description: "Friendly error messages with exit codes, no raw stack traces" },
+      { id: "progress-display", description: "Spinner or progress bar for long-running operations" },
+      { id: "update-check",     description: "Check npm/PyPI for a newer version on startup" },
+      { id: "plugin-loader",    description: "Discover and load user-installed plugins at runtime" },
+    ],
+    contextHint: "Building a CLI tool. Prioritise UX: helpful errors, --json flag, zero-config defaults.",
+    scripts: {
+      "start": "node bin/cli.js",
+      "link":  "npm link",
+    },
+  },
+
+  // ── GraphQL ─────────────────────────────────────────────────────────────────
+  "graphql": {
+    description: "GraphQL API (Apollo, Pothos, or similar)",
+    capabilities: [
+      { id: "query-viewer",       description: "query { viewer } — return the authenticated user" },
+      { id: "query-list",         description: "query { items(first: N, after: cursor) } — paginated list" },
+      { id: "query-node",         description: "query { node(id) } — global object lookup by ID" },
+      { id: "mutation-create",    description: "mutation { createItem(input) } — create and return new object" },
+      { id: "mutation-update",    description: "mutation { updateItem(id, input) } — update fields" },
+      { id: "mutation-delete",    description: "mutation { deleteItem(id) } — remove and return deleted" },
+      { id: "subscription-event", description: "subscription { itemUpdated } — real-time push via WebSocket" },
+      { id: "data-loader",        description: "Batch and cache DB calls with DataLoader to avoid N+1" },
+      { id: "auth-directive",     description: "@auth directive — enforce authentication on resolvers" },
+      { id: "error-formatting",   description: "Consistent GraphQL error shape with extensions and codes" },
+    ],
+    contextHint: "Building a GraphQL API. Use DataLoader for all relations, @auth directive on protected resolvers.",
+    scripts: {
+      "dev":       "ts-node src/server.ts",
+      "codegen":   "graphql-codegen",
+    },
+  },
+
+  // ── Monorepo ────────────────────────────────────────────────────────────────
+  "monorepo": {
+    description: "Monorepo workspace (nx / turborepo / pnpm workspaces)",
+    capabilities: [
+      { id: "build-all",         description: "Build all packages in dependency order" },
+      { id: "test-all",          description: "Run tests across all packages in parallel" },
+      { id: "lint-all",          description: "Lint all packages with shared ESLint / Prettier config" },
+      { id: "publish-packages",  description: "Bump versions and publish changed packages to npm" },
+      { id: "shared-ui-library", description: "packages/ui — shared React component library" },
+      { id: "shared-utils",      description: "packages/utils — shared utility functions and types" },
+      { id: "web-app",           description: "apps/web — primary Next.js or React web application" },
+      { id: "api-service",       description: "apps/api — backend service consumed by apps" },
+      { id: "cache-builds",      description: "Remote build cache via Turborepo or Nx Cloud" },
+      { id: "affected-only",     description: "Run tasks only for packages affected by a git change" },
+    ],
+    contextHint: "Working in a monorepo. Changes in packages/* may affect apps/*. Check affected packages before building.",
+    scripts: {
+      "build": "turbo build",
+      "dev":   "turbo dev",
+      "test":  "turbo test",
+    },
+  },
+};
+
+export function listTemplates() {
+  return Object.entries(TEMPLATES).map(([name, t]) => ({ name, description: t.description }));
+}
+
+export function getTemplate(name) {
+  return TEMPLATES[name] || null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infernoflow",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "The forge for liquid code - keep capabilities, contracts, and docs in sync.",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
     "dist/lib",
     "dist/templates",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "dist/lib/templates"
   ],
   "scripts": {
     "test": "node scripts/smoke.mjs && node scripts/json-smoke.mjs && node scripts/json-negative-smoke.mjs && node scripts/implement-smoke.mjs && node scripts/adopt-smoke.mjs && node scripts/pr-impact-smoke.mjs && node scripts/sync-smoke.mjs && node scripts/run-smoke.mjs",