infernoflow 0.16.0 → 0.18.0

package/dist/bin/infernoflow.mjs

@@ -37,6 +37,11 @@ const COMMAND_DESCRIPTIONS = {
   "team-sync": "Sync capability contract across a team via a shared git branch (push | pull | status | init)",
   onboard: "Interactive onboarding wizard for new developers — explains infernoflow in 5 minutes",
   cloud:   "Sync capability contracts via infernoflow cloud (init | push | pull | status | dashboard)",
+  share:   "Generate a public read-only HTML snapshot of your capability contract",
+  watch:   "Watch source files and run suggest automatically on save",
+  ci:      "CI-native check: GitHub Actions annotations, GitLab code quality, exit codes",
+  notify:  "Post capability drift summary to Slack or Discord",
+  report:  "Generate a weekly/monthly HTML or Markdown report of capability activity",
 };
 
 const COMMAND_HANDLERS = {
@@ -67,6 +72,11 @@ const COMMAND_HANDLERS = {
   "team-sync": async (args) => (await import("../lib/commands/teamSync.mjs")).teamSyncCommand(args),
   onboard: async (args) => (await import("../lib/commands/onboard.mjs")).onboardCommand(args),
   cloud:   async (args) => (await import("../lib/commands/cloud.mjs")).cloudCommand(args),
+  share:   async (args) => (await import("../lib/commands/share.mjs")).shareCommand(args),
+  watch:   async (args) => (await import("../lib/commands/watch.mjs")).watchCommand(args),
+  ci:      async (args) => (await import("../lib/commands/ci.mjs")).ciCommand(args),
+  notify:  async (args) => (await import("../lib/commands/notify.mjs")).notifyCommand(args),
+  report:  async (args) => (await import("../lib/commands/report.mjs")).reportCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -201,6 +211,38 @@ ${formatCommandsHelp()}
     --dry-run                 Print what would happen without sending
     --json                    Machine-readable output
 
+  ${bold("share options:")}
+    --upload                  Upload to dpaste.com and print a public URL
+    --open                    Open the snapshot in your browser immediately
+    --copy                    Copy HTML to clipboard
+    --out <path>              Custom output path (default: inferno/share.html)
+    --json                    Machine-readable: { ok, file, url }
+
+  ${bold("watch options:")}
+    [dirs...]                 Directories to watch (default: src/, lib/, app/)
+    --interval <secs>         Debounce interval in seconds (default: 3)
+    --dry-run                 Print what would run without executing
+    --silent                  No output (for git hook use)
+
+  ${bold("notify options:")}
+    --slack <url>             Slack incoming webhook URL
+    --discord <url>           Discord webhook URL
+    --on-change               Only notify if capabilities actually changed
+    --dry-run                 Print message without sending
+    --json                    Machine-readable result
+
+  ${bold("report options:")}
+    --format html|md          Output format (default: html)
+    --since <period>          7d, 30d, 90d, or YYYY-MM-DD (default: 30d)
+    --out <path>              Output file path (default: inferno/report.html)
+    --open                    Open HTML report in browser after generating
+    --json                    Machine-readable summary
+
+  ${bold("ci options:")}
+    --platform <name>         github | gitlab | bitbucket | generic (auto-detected)
+    --fail-on <level>         error | warning (default: error)
+    --json                    Machine-readable result + exit code
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/ci.mjs

@@ -0,0 +1,207 @@
+/**
+ * infernoflow ci
+ *
+ * Auto-detect the CI environment and output structured annotations that
+ * integrate natively with each platform's UI.
+ *
+ * Supported platforms:
+ *   GitHub Actions   → ::error:: / ::warning:: / step summary (GITHUB_STEP_SUMMARY)
+ *   GitLab CI        → gl-code-quality.json artifact
+ *   Bitbucket        → annotations API via curl
+ *   Generic          → exit code + JSON output (for any CI)
+ *
+ * Usage:
+ *   infernoflow ci                     Auto-detect platform, run check + diff
+ *   infernoflow ci --platform github   Force a platform
+ *   infernoflow ci --fail-on warning   Fail on warning or higher (default: error)
+ *   infernoflow ci --json              Machine-readable result
+ *
+ * Exits 0 on success, 1 on error/warning (based on --fail-on).
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import { header, ok, warn, info, done, bold, cyan, gray, green, red, yellow } from "../ui/output.mjs";
+
+// ── Platform detection ────────────────────────────────────────────────────────
+
+function detectPlatform() {
+  if (process.env.GITHUB_ACTIONS === "true")       return "github";
+  if (process.env.GITLAB_CI === "true")            return "gitlab";
+  if (process.env.BITBUCKET_BUILD_NUMBER)          return "bitbucket";
+  if (process.env.CIRCLECI === "true")             return "circleci";
+  if (process.env.JENKINS_URL)                     return "jenkins";
+  if (process.env.CI === "true")                   return "generic";
+  return "local";
+}
+
+// ── CLI runner ────────────────────────────────────────────────────────────────
+
+function runJson(command, cwd) {
+  try {
+    const [bin, ...args] = command.split(" ");
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(new URL(import.meta.url).pathname)), "..", "bin", "infernoflow.mjs"),
+      ...command.split(" ").slice(1)
+    ], { cwd, encoding: "utf8", timeout: 30_000 });
+    const out = result.stdout?.trim();
+    if (out) return JSON.parse(out);
+  } catch {}
+  return null;
+}
+
+function runCli(args, cwd) {
+  try {
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(new URL(import.meta.url).pathname)), "..", "bin", "infernoflow.mjs"),
+      ...args
+    ], { cwd, encoding: "utf8", timeout: 30_000 });
+    return result.stdout?.trim() || "";
+  } catch { return ""; }
+}
+
+// ── GitHub Actions output ─────────────────────────────────────────────────────
+
+function emitGithub(checkResult, diffResult, failOn) {
+  const status = checkResult?.status || "unknown";
+  const issues = checkResult?.issues || [];
+  const caps   = checkResult?.capabilities || 0;
+  const added  = diffResult?.added?.length || 0;
+  const removed = diffResult?.removed?.length || 0;
+  const changed = diffResult?.changed?.length || 0;
+
+  // GitHub workflow commands
+  if (status === "error") {
+    issues.filter(i => i.severity === "error").forEach(i => {
+      console.log(`::error::infernoflow: ${i.message}`);
+    });
+  } else if (status === "warning") {
+    issues.filter(i => i.severity === "warning").forEach(i => {
+      console.log(`::warning::infernoflow: ${i.message}`);
+    });
+  }
+
+  if (added > 0)   console.log(`::notice::infernoflow: ${added} new capability${added !== 1 ? "ies" : "y"} added`);
+  if (removed > 0) console.log(`::warning::infernoflow: ${removed} capability${removed !== 1 ? "ies" : "y"} removed`);
+
+  // Step summary
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryPath) {
+    const statusIcon = status === "ok" ? "✅" : status === "warning" ? "⚠️" : "❌";
+    const lines = [
+      `## 🔥 infernoflow CI report`,
+      "",
+      `${statusIcon} **Status:** ${status.toUpperCase()}  ·  **Capabilities:** ${caps}`,
+      "",
+    ];
+    if (added || removed || changed) {
+      lines.push("### Capability changes");
+      if (added)   lines.push(`- ✅ **${added}** added`);
+      if (removed) lines.push(`- ❌ **${removed}** removed`);
+      if (changed) lines.push(`- 📝 **${changed}** changed`);
+      lines.push("");
+    }
+    if (issues.length) {
+      lines.push("### Issues");
+      issues.forEach(i => lines.push(`- **${i.severity?.toUpperCase() || "INFO"}**: ${i.message}`));
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("*Generated by [infernoflow](https://github.com/ronmiz/infernoflow)*");
+    try { fs.appendFileSync(summaryPath, lines.join("\n") + "\n"); } catch {}
+  }
+}
+
+// ── GitLab code quality report ────────────────────────────────────────────────
+
+function emitGitlab(checkResult, cwd) {
+  const issues = checkResult?.issues || [];
+  const report = issues.map((issue, i) => ({
+    description:      issue.message || "infernoflow issue",
+    fingerprint:      Buffer.from(`infernoflow-${i}-${issue.message}`).toString("hex").slice(0, 40),
+    severity:         issue.severity === "error" ? "critical" : "minor",
+    location: {
+      path:       "inferno/contract.json",
+      lines:      { begin: 1 },
+    },
+  }));
+  const reportPath = path.join(cwd, "gl-code-quality-report.json");
+  fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  console.log(`infernoflow: GitLab code quality report written → gl-code-quality-report.json`);
+}
+
+// ── Generic CI output ─────────────────────────────────────────────────────────
+
+function emitGeneric(checkResult, diffResult, platform) {
+  const status = checkResult?.status || "unknown";
+  const caps   = checkResult?.capabilities || 0;
+  const added  = diffResult?.added?.length || 0;
+  const removed = diffResult?.removed?.length || 0;
+
+  console.log(`[infernoflow] platform=${platform} status=${status} capabilities=${caps} added=${added} removed=${removed}`);
+  if (checkResult?.issues?.length) {
+    checkResult.issues.forEach(i => {
+      console.log(`[infernoflow] ${(i.severity || "info").toUpperCase()}: ${i.message}`);
+    });
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+export async function ciCommand(rawArgs) {
+  const args        = rawArgs.slice(1);
+  const jsonMode    = args.includes("--json");
+  const platformArg = args.includes("--platform") ? args[args.indexOf("--platform") + 1] : null;
+  const failOn      = args.includes("--fail-on") ? args[args.indexOf("--fail-on") + 1] : "error";
+  const cwd         = process.cwd();
+  const infernoDir  = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "inferno/ not found" })); }
+    else { console.log("[infernoflow] inferno/ not found — skipping CI check"); }
+    process.exit(0); // Don't block CI if infernoflow isn't set up
+  }
+
+  const platform = platformArg || detectPlatform();
+
+  if (!jsonMode) {
+    console.log(`[infernoflow] running CI check (platform: ${platform})`);
+  }
+
+  // Run check + diff
+  const checkResult = runJson("check --json", cwd);
+  const diffResult  = runJson("diff --json", cwd);
+  const status      = checkResult?.status || "unknown";
+
+  // Platform-specific output
+  switch (platform) {
+    case "github":
+      emitGithub(checkResult, diffResult, failOn);
+      break;
+    case "gitlab":
+      emitGitlab(checkResult, cwd);
+      emitGeneric(checkResult, diffResult, platform);
+      break;
+    default:
+      emitGeneric(checkResult, diffResult, platform);
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      ok:       status === "ok" || status === "warning",
+      platform,
+      status,
+      capabilities: checkResult?.capabilities || 0,
+      issues:   checkResult?.issues || [],
+      diff:     { added: diffResult?.added || [], removed: diffResult?.removed || [], changed: diffResult?.changed || [] },
+    }));
+  }
+
+  // Exit code
+  const shouldFail = failOn === "warning"
+    ? (status === "error" || status === "warning")
+    : (status === "error");
+
+  process.exit(shouldFail ? 1 : 0);
+}

package/dist/lib/commands/notify.mjs

@@ -0,0 +1,258 @@
+/**
+ * infernoflow notify
+ *
+ * Post capability drift summaries to Slack or Discord.
+ * Runs automatically after significant capability changes (via git hook or CI).
+ * Can also be triggered manually.
+ *
+ * Usage:
+ *   infernoflow notify                    Auto-detect channel from config
+ *   infernoflow notify --slack <url>      Post to Slack webhook URL
+ *   infernoflow notify --discord <url>    Post to Discord webhook URL
+ *   infernoflow notify --dry-run          Print message without sending
+ *   infernoflow notify --json             Machine-readable: { ok, platform, message }
+ *   infernoflow notify --on-change        Only notify if capabilities actually changed
+ *
+ * Config (inferno/notify.json):
+ *   { "slack": "https://hooks.slack.com/...", "discord": "https://discord.com/api/webhooks/..." }
+ *
+ * Or set env vars:
+ *   INFERNOFLOW_SLACK_WEBHOOK
+ *   INFERNOFLOW_DISCORD_WEBHOOK
+ */
+
+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 { spawnSync } from "node:child_process";
+import { done, warn, info, bold, cyan, gray, green, red, yellow } from "../ui/output.mjs";
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+function loadNotifyConfig(infernoDir, args) {
+  const configPath = path.join(infernoDir, "notify.json");
+  const fileConfig = fs.existsSync(configPath)
+    ? (() => { try { return JSON.parse(fs.readFileSync(configPath, "utf8")); } catch { return {}; } })()
+    : {};
+
+  const slackIdx   = args.indexOf("--slack");
+  const discordIdx = args.indexOf("--discord");
+
+  return {
+    slack:   slackIdx   !== -1 ? args[slackIdx + 1]   : process.env.INFERNOFLOW_SLACK_WEBHOOK   || fileConfig.slack,
+    discord: discordIdx !== -1 ? args[discordIdx + 1] : process.env.INFERNOFLOW_DISCORD_WEBHOOK || fileConfig.discord,
+  };
+}
+
+// ── Data loading ──────────────────────────────────────────────────────────────
+
+function runJson(cmd, cwd) {
+  try {
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(new URL(import.meta.url).pathname)), "..", "bin", "infernoflow.mjs"),
+      ...cmd.split(" ").slice(1),
+    ], { cwd, encoding: "utf8", timeout: 20_000 });
+    const out = result.stdout?.trim();
+    if (out) return JSON.parse(out);
+  } catch {}
+  return null;
+}
+
+function buildSummary(checkResult, diffResult, contract) {
+  const status  = checkResult?.status || "unknown";
+  const caps    = (contract?.capabilities || []).length;
+  const version = contract?.policyVersion || "?";
+  const project = contract?.policyId || "project";
+  const added   = diffResult?.added   || [];
+  const removed = diffResult?.removed || [];
+  const changed = diffResult?.changed || [];
+
+  return { status, caps, version, project, added, removed, changed };
+}
+
+// ── Slack message builder ─────────────────────────────────────────────────────
+
+function buildSlackMessage(summary) {
+  const { status, caps, version, project, added, removed, changed } = summary;
+  const statusEmoji = status === "ok" ? "✅" : status === "warning" ? "⚠️" : "❌";
+  const hasChanges  = added.length || removed.length || changed.length;
+
+  const blocks = [
+    {
+      type: "header",
+      text: { type: "plain_text", text: `🔥 infernoflow — ${project} v${version}`, emoji: true },
+    },
+    {
+      type: "section",
+      fields: [
+        { type: "mrkdwn", text: `*Status*\n${statusEmoji} ${status.toUpperCase()}` },
+        { type: "mrkdwn", text: `*Capabilities*\n${caps} tracked` },
+      ],
+    },
+  ];
+
+  if (hasChanges) {
+    const lines = [];
+    if (added.length)   lines.push(`✅ *${added.length}* added: ${added.slice(0, 3).join(", ")}${added.length > 3 ? ` +${added.length - 3} more` : ""}`);
+    if (removed.length) lines.push(`❌ *${removed.length}* removed: ${removed.slice(0, 3).join(", ")}${removed.length > 3 ? ` +${removed.length - 3} more` : ""}`);
+    if (changed.length) lines.push(`📝 *${changed.length}* changed`);
+    blocks.push({ type: "section", text: { type: "mrkdwn", text: lines.join("\n") } });
+  }
+
+  blocks.push({
+    type: "context",
+    elements: [{ type: "mrkdwn", text: `<https://github.com/ronmiz/infernoflow|infernoflow> · ${new Date().toLocaleString()}` }],
+  });
+
+  return { blocks };
+}
+
+// ── Discord message builder ───────────────────────────────────────────────────
+
+function buildDiscordMessage(summary) {
+  const { status, caps, version, project, added, removed, changed } = summary;
+  const color  = status === "ok" ? 0x4ade80 : status === "warning" ? 0xf97316 : 0xf87171;
+  const hasChanges = added.length || removed.length || changed.length;
+
+  const fields = [
+    { name: "Status",       value: status.toUpperCase(), inline: true },
+    { name: "Capabilities", value: String(caps),         inline: true },
+    { name: "Version",      value: `v${version}`,        inline: true },
+  ];
+
+  if (added.length)   fields.push({ name: "✅ Added",   value: added.slice(0,5).join(", ") + (added.length > 5 ? ` +${added.length-5}` : ""),   inline: false });
+  if (removed.length) fields.push({ name: "❌ Removed", value: removed.slice(0,5).join(", ") + (removed.length > 5 ? ` +${removed.length-5}` : ""), inline: false });
+
+  return {
+    embeds: [{
+      title:       `🔥 infernoflow — ${project}`,
+      description: hasChanges ? "Capability changes detected" : "Contract healthy",
+      color,
+      fields,
+      footer:      { text: "infernoflow · " + new Date().toLocaleString() },
+      url:         "https://github.com/ronmiz/infernoflow",
+    }],
+  };
+}
+
+// ── HTTP post ─────────────────────────────────────────────────────────────────
+
+function postWebhook(url, payload) {
+  return new Promise((resolve, reject) => {
+    const body    = JSON.stringify(payload);
+    const parsed  = new URL(url);
+    const isHttps = parsed.protocol === "https:";
+    const lib     = isHttps ? https : http;
+
+    const req = lib.request({
+      hostname: parsed.hostname,
+      port:     parsed.port || (isHttps ? 443 : 80),
+      path:     parsed.pathname + (parsed.search || ""),
+      method:   "POST",
+      headers:  { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body), "User-Agent": "infernoflow-cli" },
+    }, (res) => {
+      let data = "";
+      res.on("data", d => (data += d));
+      res.on("end", () => resolve({ status: res.statusCode, body: data }));
+    });
+
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+export async function notifyCommand(rawArgs) {
+  const args       = rawArgs.slice(1);
+  const jsonMode   = args.includes("--json");
+  const dryRun     = args.includes("--dry-run");
+  const onlyChange = args.includes("--on-change");
+  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 config = loadNotifyConfig(infernoDir, args);
+
+  if (!config.slack && !config.discord) {
+    const msg = "No webhook configured. Use --slack <url>, --discord <url>, or set INFERNOFLOW_SLACK_WEBHOOK / INFERNOFLOW_DISCORD_WEBHOOK.";
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); } else { warn(msg); }
+    if (!jsonMode) {
+      console.log();
+      console.log(`  ${gray("To configure permanently, create inferno/notify.json:")}`);
+      console.log(`  ${cyan('{ "slack": "https://hooks.slack.com/...", "discord": "https://discord.com/api/webhooks/..." }')}`);
+      console.log();
+    }
+    process.exit(1);
+  }
+
+  // Load data
+  const contract    = (() => {
+    for (const f of ["contract.json", "capabilities.json"]) {
+      const p = path.join(infernoDir, f);
+      if (fs.existsSync(p)) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch {} }
+    }
+    return {};
+  })();
+  const checkResult = runJson("check --json", cwd);
+  const diffResult  = runJson("diff --json", cwd);
+  const summary     = buildSummary(checkResult, diffResult, contract);
+
+  // --on-change: skip if nothing changed
+  if (onlyChange && !summary.added.length && !summary.removed.length && !summary.changed.length) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: true, skipped: true, reason: "no capability changes" })); }
+    else { info("No capability changes — skipping notification."); }
+    return;
+  }
+
+  const results = [];
+
+  // Slack
+  if (config.slack) {
+    const payload = buildSlackMessage(summary);
+    if (dryRun) {
+      if (!jsonMode) { info("Slack payload (dry run):"); console.log(JSON.stringify(payload, null, 2)); }
+      results.push({ platform: "slack", ok: true, dryRun: true });
+    } else {
+      try {
+        const resp = await postWebhook(config.slack, payload);
+        const ok   = resp.status >= 200 && resp.status < 300;
+        if (!jsonMode) { ok ? done("Slack notification sent") : warn(`Slack returned ${resp.status}`); }
+        results.push({ platform: "slack", ok, status: resp.status });
+      } catch (err) {
+        if (!jsonMode) warn(`Slack failed: ${err.message}`);
+        results.push({ platform: "slack", ok: false, error: err.message });
+      }
+    }
+  }
+
+  // Discord
+  if (config.discord) {
+    const payload = buildDiscordMessage(summary);
+    if (dryRun) {
+      if (!jsonMode) { info("Discord payload (dry run):"); console.log(JSON.stringify(payload, null, 2)); }
+      results.push({ platform: "discord", ok: true, dryRun: true });
+    } else {
+      try {
+        const resp = await postWebhook(config.discord, payload);
+        const ok   = resp.status >= 200 && resp.status < 300;
+        if (!jsonMode) { ok ? done("Discord notification sent") : warn(`Discord returned ${resp.status}`); }
+        results.push({ platform: "discord", ok, status: resp.status });
+      } catch (err) {
+        if (!jsonMode) warn(`Discord failed: ${err.message}`);
+        results.push({ platform: "discord", ok: false, error: err.message });
+      }
+    }
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: results.every(r => r.ok), results, summary }));
+  }
+}

package/dist/lib/commands/report.mjs

@@ -0,0 +1,320 @@
+/**
+ * infernoflow report
+ *
+ * Generate a weekly/monthly HTML or Markdown report of capability changes,
+ * version history, drift events, and agent usage. Can be committed to the
+ * repo on a schedule or emailed to the team.
+ *
+ * Usage:
+ *   infernoflow report                   Generate HTML report (last 30 days)
+ *   infernoflow report --format md       Markdown instead of HTML
+ *   infernoflow report --since 7d        Last 7 days
+ *   infernoflow report --since 2024-01-01  Since a specific date
+ *   infernoflow report --out report.html   Custom output path
+ *   infernoflow report --open            Open in browser after generating
+ *   infernoflow report --json            Machine-readable summary
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { execSync, spawnSync } from "node:child_process";
+import { done, warn, info, bold, cyan, gray } from "../ui/output.mjs";
+
+// ── Git helpers ───────────────────────────────────────────────────────────────
+
+function git(cmd, cwd) {
+  try { return execSync(cmd, { cwd, encoding: "utf8", timeout: 15_000 }).trim(); }
+  catch { return ""; }
+}
+
+function parseSinceDuration(since) {
+  if (!since) return new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+  if (/^\d+d$/.test(since)) return new Date(Date.now() - parseInt(since) * 24 * 60 * 60 * 1000);
+  if (/^\d+w$/.test(since)) return new Date(Date.now() - parseInt(since) * 7 * 24 * 60 * 60 * 1000);
+  if (/^\d{4}-\d{2}-\d{2}$/.test(since)) return new Date(since);
+  return new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+}
+
+function getCommitsSince(cwd, since) {
+  const iso = since.toISOString();
+  const out = git(`git log --after="${iso}" --format="%H|%s|%an|%ad" --date=short`, cwd);
+  if (!out) return [];
+  return out.split("\n").filter(Boolean).map(line => {
+    const [hash, subject, author, date] = line.split("|");
+    return { hash: hash?.slice(0, 8), subject, author, date };
+  });
+}
+
+function getCapabilityHistory(infernoDir, cwd, since) {
+  const out = git(`git log --after="${since.toISOString()}" --format="%H|%ad" --date=short -- inferno/`, cwd);
+  if (!out) return [];
+  return out.split("\n").filter(Boolean).map(line => {
+    const [hash, date] = line.split("|");
+    return { hash: hash?.slice(0, 8), date };
+  });
+}
+
+function getVersionTags(cwd, since) {
+  const out = git(`git tag --sort=-version:refname`, cwd);
+  if (!out) return [];
+  return out.split("\n").filter(t => t.startsWith("v")).slice(0, 10).map(tag => {
+    const date = git(`git log -1 --format=%ad --date=short ${tag}`, cwd);
+    return { tag, date };
+  }).filter(t => !since || new Date(t.date) >= since);
+}
+
+// ── Data gathering ────────────────────────────────────────────────────────────
+
+function gatherData(cwd, infernoDir, since) {
+  const contract = (() => {
+    for (const f of ["contract.json", "capabilities.json"]) {
+      const p = path.join(infernoDir, f);
+      if (fs.existsSync(p)) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch {} }
+    }
+    return {};
+  })();
+
+  const caps    = contract.capabilities || [];
+  const covered = caps.filter(c => typeof c === "object" && c.covered).length;
+
+  const commits     = getCommitsSince(cwd, since);
+  const capCommits  = getCapabilityHistory(infernoDir, cwd, since);
+  const versionTags = getVersionTags(cwd, since);
+
+  const agents = (() => {
+    const dir = path.join(infernoDir, "agents");
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter(f => f.endsWith(".json")).map(f => {
+      try { return JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")); }
+      catch { return null; }
+    }).filter(Boolean);
+  })();
+
+  const changelog = (() => {
+    const p = path.join(cwd, "CHANGELOG.md");
+    if (!fs.existsSync(p)) return null;
+    try {
+      const lines = fs.readFileSync(p, "utf8").split("\n");
+      const start = lines.findIndex(l => l.startsWith("## "));
+      if (start === -1) return null;
+      const end = lines.findIndex((l, i) => i > start && l.startsWith("## "));
+      return lines.slice(start, end === -1 ? start + 20 : end).join("\n");
+    } catch { return null; }
+  })();
+
+  return {
+    project:      contract.policyId || path.basename(cwd),
+    version:      contract.policyVersion || "?",
+    caps,
+    covered,
+    commits,
+    capCommits,
+    versionTags,
+    agents,
+    changelog,
+    since,
+    generatedAt:  new Date().toLocaleString(),
+  };
+}
+
+// ── HTML report ───────────────────────────────────────────────────────────────
+
+function buildHtmlReport(data) {
+  const { project, version, caps, covered, commits, capCommits, versionTags, agents, changelog, since, generatedAt } = data;
+  const sinceStr = since.toLocaleDateString();
+  const coverage = caps.length ? Math.round((covered / caps.length) * 100) : 0;
+
+  const capRows = caps.slice(0, 30).map(c => {
+    const id  = typeof c === "string" ? c : c.id;
+    const cov = typeof c === "object" ? c.covered : undefined;
+    const badge = cov === true ? `<span style="color:#4ade80">✔</span>` : cov === false ? `<span style="color:#f87171">✗</span>` : `<span style="color:#475569">·</span>`;
+    return `<tr><td style="padding:4px 10px">${badge}</td><td style="padding:4px 10px;font-weight:600">${id}</td></tr>`;
+  }).join("");
+
+  const versionRows = versionTags.map(t =>
+    `<tr><td style="padding:4px 10px;font-weight:600">${t.tag}</td><td style="padding:4px 10px;color:#94a3b8">${t.date}</td></tr>`
+  ).join("") || `<tr><td colspan="2" style="padding:4px 10px;color:#475569">No version tags in this period</td></tr>`;
+
+  const agentRows = agents.map(a => {
+    const steps = (a.steps || []).map(s => typeof s === "string" ? s : s.command).join(" → ");
+    const conf  = a.confidence ? Math.round(a.confidence * 100) + "%" : "—";
+    return `<tr><td style="padding:4px 10px;font-weight:600">${a.name}</td><td style="padding:4px 10px;color:#94a3b8">${conf}</td><td style="padding:4px 10px;color:#64748b;font-size:0.8em">${steps}</td></tr>`;
+  }).join("") || `<tr><td colspan="3" style="padding:4px 10px;color:#475569">No agents synthesized yet</td></tr>`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>infernoflow report — ${project}</title>
+<style>
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:#0f0f1a;color:#e2e8f0;font-family:'Segoe UI',system-ui,sans-serif;padding:0 0 3rem}
+  header{background:#1a1a2e;border-bottom:2px solid #f97316;padding:1.5rem 2rem;display:flex;justify-content:space-between;align-items:flex-end}
+  header h1{font-size:1.4rem;font-weight:700;color:#f97316}
+  header .meta{color:#64748b;font-size:0.8rem}
+  main{max-width:960px;margin:2rem auto;padding:0 1.5rem}
+  .grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:1rem;margin-bottom:2rem}
+  .card{background:#1a1a2e;border:1px solid #2d2d4e;border-radius:8px;padding:1rem 1.25rem}
+  .card .n{font-size:2rem;font-weight:700;color:#f97316}
+  .card .l{font-size:0.72rem;color:#64748b;text-transform:uppercase;letter-spacing:0.06em;margin-top:2px}
+  .section{margin-bottom:2rem}
+  h2{font-size:0.78rem;text-transform:uppercase;letter-spacing:0.08em;color:#64748b;margin-bottom:0.6rem;padding-bottom:0.35rem;border-bottom:1px solid #2d2d4e}
+  table{width:100%;border-collapse:collapse;background:#1a1a2e;border:1px solid #2d2d4e;border-radius:6px;overflow:hidden;font-size:0.875rem}
+  tr:nth-child(even) td{background:#16162a}
+  .prog{background:#2d2d4e;border-radius:999px;height:8px;margin-top:6px}
+  .prog-bar{background:#f97316;border-radius:999px;height:100%;transition:width 0.3s}
+  pre{background:#1a1a2e;border:1px solid #2d2d4e;border-radius:6px;padding:1rem;font-size:0.78rem;white-space:pre-wrap;color:#94a3b8;overflow-x:auto}
+  footer{text-align:center;color:#334155;font-size:0.72rem;margin-top:3rem}
+  footer a{color:#f97316;text-decoration:none}
+</style>
+</head>
+<body>
+<header>
+  <div>
+    <h1>🔥 infernoflow report — ${project}</h1>
+    <div class="meta">v${version} · ${sinceStr} → ${generatedAt}</div>
+  </div>
+  <div class="meta" style="text-align:right">${commits.length} commits · ${capCommits.length} contract updates</div>
+</header>
+<main>
+  <div class="grid">
+    <div class="card"><div class="n">${caps.length}</div><div class="l">capabilities</div></div>
+    <div class="card"><div class="n">${coverage}%</div><div class="l">coverage</div><div class="prog"><div class="prog-bar" style="width:${coverage}%"></div></div></div>
+    <div class="card"><div class="n">${commits.length}</div><div class="l">commits</div></div>
+    <div class="card"><div class="n">${capCommits.length}</div><div class="l">contract updates</div></div>
+    <div class="card"><div class="n">${versionTags.length}</div><div class="l">releases</div></div>
+    <div class="card"><div class="n">${agents.length}</div><div class="l">agents</div></div>
+  </div>
+
+  <div class="section">
+    <h2>Capabilities (${caps.length})</h2>
+    <table><tbody>${capRows}${caps.length > 30 ? `<tr><td colspan="2" style="padding:6px 10px;color:#475569">… and ${caps.length - 30} more</td></tr>` : ""}</tbody></table>
+  </div>
+
+  <div class="section">
+    <h2>Version history</h2>
+    <table><tbody>${versionRows}</tbody></table>
+  </div>
+
+  <div class="section">
+    <h2>Agents (${agents.length})</h2>
+    <table><tbody>${agentRows}</tbody></table>
+  </div>
+
+  ${changelog ? `<div class="section"><h2>Latest changelog</h2><pre>${changelog.replace(/</g, "&lt;")}</pre></div>` : ""}
+</main>
+<footer>Generated by <a href="https://github.com/ronmiz/infernoflow">infernoflow</a> on ${generatedAt}</footer>
+</body>
+</html>`;
+}
+
+// ── Markdown report ───────────────────────────────────────────────────────────
+
+function buildMarkdownReport(data) {
+  const { project, version, caps, covered, commits, capCommits, versionTags, agents, changelog, since, generatedAt } = data;
+  const coverage = caps.length ? Math.round((covered / caps.length) * 100) : 0;
+
+  const lines = [
+    `# 🔥 infernoflow report — ${project}`,
+    ``,
+    `**Version:** v${version}  ·  **Period:** ${since.toLocaleDateString()} → ${generatedAt}`,
+    ``,
+    `## Summary`,
+    ``,
+    `| Metric | Value |`,
+    `|---|---|`,
+    `| Capabilities | ${caps.length} |`,
+    `| Coverage | ${coverage}% |`,
+    `| Commits | ${commits.length} |`,
+    `| Contract updates | ${capCommits.length} |`,
+    `| Releases | ${versionTags.length} |`,
+    `| Agents | ${agents.length} |`,
+    ``,
+    `## Capabilities`,
+    ``,
+    ...caps.slice(0, 30).map(c => {
+      const id  = typeof c === "string" ? c : c.id;
+      const cov = typeof c === "object" ? c.covered : undefined;
+      return `- ${cov === true ? "✅" : cov === false ? "❌" : "·"} **${id}**`;
+    }),
+    caps.length > 30 ? `- *… and ${caps.length - 30} more*` : "",
+    ``,
+    `## Version history`,
+    ``,
+    ...(versionTags.length
+      ? versionTags.map(t => `- **${t.tag}** — ${t.date}`)
+      : ["- *No releases in this period*"]),
+    ``,
+    `## Agents`,
+    ``,
+    ...(agents.length
+      ? agents.map(a => `- **${a.name}** (${a.confidence ? Math.round(a.confidence * 100) + "%" : "—"}) — ${a.description || ""}`)
+      : ["- *No agents synthesized yet*"]),
+    ``,
+    changelog ? `## Latest changelog\n\n\`\`\`\n${changelog}\n\`\`\`` : "",
+    ``,
+    `---`,
+    `*Generated by [infernoflow](https://github.com/ronmiz/infernoflow) on ${generatedAt}*`,
+  ];
+
+  return lines.filter(l => l !== undefined).join("\n");
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+export async function reportCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json");
+  const openBrowser = args.includes("--open");
+  const format    = args.includes("--format") ? args[args.indexOf("--format") + 1] : "html";
+  const sinceArg  = args.includes("--since") ? args[args.indexOf("--since") + 1] : null;
+  const outArg    = args.includes("--out") ? args[args.indexOf("--out") + 1] : null;
+  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);
+  }
+
+  if (!jsonMode) info(`Generating ${format} report…`);
+
+  const since = parseSinceDuration(sinceArg);
+  const data  = gatherData(cwd, infernoDir, since);
+
+  const ext       = format === "md" ? "md" : "html";
+  const outPath   = outArg || path.join(infernoDir, `report.${ext}`);
+  const content   = format === "md" ? buildMarkdownReport(data) : buildHtmlReport(data);
+
+  fs.writeFileSync(outPath, content, "utf8");
+
+  if (openBrowser && format === "html") {
+    try {
+      const cmd = process.platform === "win32" ? `start "" "${outPath}"`
+                : process.platform === "darwin" ? `open "${outPath}"`
+                : `xdg-open "${outPath}"`;
+      execSync(cmd, { stdio: "ignore" });
+    } catch {}
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      ok: true,
+      file: outPath,
+      format,
+      project: data.project,
+      version: data.version,
+      capabilities: data.caps.length,
+      commits: data.commits.length,
+      agents: data.agents.length,
+    }));
+    return;
+  }
+
+  done(`Report generated`);
+  console.log(`  ${cyan(outPath)}`);
+  console.log(`  ${gray(data.caps.length + " capabilities · " + data.commits.length + " commits · " + data.agents.length + " agents")}`);
+  console.log();
+}

package/dist/lib/commands/share.mjs

@@ -0,0 +1,236 @@
+/**
+ * infernoflow share
+ *
+ * Generate a public read-only snapshot of your capability contract — no cloud
+ * account needed. Creates a self-contained HTML file you can host anywhere,
+ * or uploads to a paste service and prints a short link.
+ *
+ * Usage:
+ *   infernoflow share                  Generate share.html locally
+ *   infernoflow share --open           Open in browser immediately
+ *   infernoflow share --upload         Upload to dpaste.com and print URL
+ *   infernoflow share --copy           Copy HTML to clipboard
+ *   infernoflow share --json           Machine-readable: { ok, file, url }
+ *   infernoflow share --out <path>     Custom output path
+ */
+
+import * as fs    from "node:fs";
+import * as path  from "node:path";
+import * as https from "node:https";
+import { execSync } from "node:child_process";
+import { done, warn, info, bold, cyan, gray, green } from "../ui/output.mjs";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function readContract(infernoDir) {
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (fs.existsSync(p)) {
+      try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+    }
+  }
+  return null;
+}
+
+function readChangelog(cwd) {
+  const p = path.join(cwd, "CHANGELOG.md");
+  if (!fs.existsSync(p)) return null;
+  try {
+    const lines = fs.readFileSync(p, "utf8").split("\n");
+    const start = lines.findIndex(l => l.startsWith("## "));
+    if (start === -1) return null;
+    const end   = lines.findIndex((l, i) => i > start && l.startsWith("## "));
+    return lines.slice(start, end === -1 ? start + 30 : end).join("\n");
+  } catch { return null; }
+}
+
+// ── HTML generator ────────────────────────────────────────────────────────────
+
+function buildHtml(contract, changelog, generatedAt) {
+  const caps     = contract.capabilities || [];
+  const policyId = contract.policyId || "project";
+  const version  = contract.policyVersion || "?";
+
+  const capRows = caps.map(c => {
+    const id    = typeof c === "string" ? c : c.id;
+    const title = typeof c === "string" ? c : (c.title || c.id);
+    const cov   = typeof c === "object" ? c.covered : undefined;
+    const badge = cov === true  ? `<span class="cov yes">✔</span>`
+                : cov === false ? `<span class="cov no">✗</span>`
+                : `<span class="cov uk">·</span>`;
+    const desc  = typeof c === "object" && c.description ? `<div class="cap-desc">${c.description}</div>` : "";
+    return `<div class="cap-row">${badge}<div class="cap-body"><div class="cap-id">${id}</div><div class="cap-title">${title !== id ? title : ""}</div>${desc}</div></div>`;
+  }).join("");
+
+  const changelogHtml = changelog
+    ? `<section><h2>Latest changes</h2><pre class="changelog">${changelog.replace(/</g, "&lt;")}</pre></section>`
+    : "";
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${policyId} v${version} — infernoflow snapshot</title>
+<style>
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:#0f0f1a;color:#e2e8f0;font-family:'Segoe UI',system-ui,sans-serif;line-height:1.5;padding:0 0 3rem}
+  header{background:#1a1a2e;border-bottom:2px solid #f97316;padding:1.5rem 2rem}
+  header h1{font-size:1.5rem;font-weight:700;color:#f97316}
+  header .meta{color:#64748b;font-size:0.85rem;margin-top:0.25rem}
+  main{max-width:860px;margin:2rem auto;padding:0 1.5rem}
+  section{margin-bottom:2rem}
+  h2{font-size:0.8rem;text-transform:uppercase;letter-spacing:0.08em;color:#64748b;margin-bottom:0.75rem;padding-bottom:0.4rem;border-bottom:1px solid #2d2d4e}
+  .stats{display:flex;gap:1rem;flex-wrap:wrap;margin-bottom:2rem}
+  .stat{background:#1a1a2e;border:1px solid #2d2d4e;border-radius:8px;padding:1rem 1.5rem;min-width:130px}
+  .stat .n{font-size:2rem;font-weight:700;color:#f97316}
+  .stat .l{font-size:0.75rem;color:#64748b;margin-top:2px}
+  .cap-row{display:flex;align-items:flex-start;gap:0.75rem;padding:0.6rem 0;border-bottom:1px solid #1e1e30}
+  .cap-row:last-child{border-bottom:none}
+  .cov{font-size:0.9rem;min-width:18px;text-align:center;margin-top:2px}
+  .cov.yes{color:#4ade80}.cov.no{color:#f87171}.cov.uk{color:#475569}
+  .cap-id{font-weight:600;font-size:0.9rem}
+  .cap-title{color:#94a3b8;font-size:0.8rem}
+  .cap-desc{color:#64748b;font-size:0.78rem;margin-top:2px}
+  .changelog{background:#1a1a2e;border:1px solid #2d2d4e;border-radius:6px;padding:1rem;font-size:0.8rem;white-space:pre-wrap;color:#94a3b8;overflow-x:auto}
+  footer{text-align:center;color:#334155;font-size:0.75rem;margin-top:3rem}
+  footer a{color:#f97316;text-decoration:none}
+</style>
+</head>
+<body>
+<header>
+  <h1>🔥 ${policyId}</h1>
+  <div class="meta">v${version} · ${caps.length} capabilities · snapshot ${generatedAt}</div>
+</header>
+<main>
+  <div class="stats">
+    <div class="stat"><div class="n">${caps.length}</div><div class="l">capabilities</div></div>
+    <div class="stat"><div class="n">${caps.filter(c => typeof c === "object" && c.covered).length || "—"}</div><div class="l">covered</div></div>
+    <div class="stat"><div class="n">v${version}</div><div class="l">version</div></div>
+  </div>
+  <section>
+    <h2>Capabilities</h2>
+    <div>${capRows || '<p style="color:#475569">No capabilities yet.</p>'}</div>
+  </section>
+  ${changelogHtml}
+</main>
+<footer>Generated by <a href="https://github.com/ronmiz/infernoflow">infernoflow</a> on ${generatedAt}</footer>
+</body>
+</html>`;
+}
+
+// ── Upload to dpaste ──────────────────────────────────────────────────────────
+
+function uploadToDpaste(content) {
+  return new Promise((resolve, reject) => {
+    const body = `content=${encodeURIComponent(content)}&syntax=html&expiry_days=365`;
+    const req  = https.request({
+      hostname: "dpaste.com",
+      path:     "/api/v2/",
+      method:   "POST",
+      headers: {
+        "Content-Type":   "application/x-www-form-urlencoded",
+        "Content-Length": Buffer.byteLength(body),
+        "User-Agent":     "infernoflow-cli",
+      },
+    }, (res) => {
+      let data = "";
+      res.on("data", d => (data += d));
+      res.on("end", () => {
+        const url = data.trim();
+        if (url.startsWith("http")) resolve(url + ".html");
+        else reject(new Error("Unexpected response: " + data));
+      });
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+export async function shareCommand(rawArgs) {
+  const args       = rawArgs.slice(1);
+  const jsonMode   = args.includes("--json");
+  const openBrowser = args.includes("--open");
+  const upload     = args.includes("--upload");
+  const copyToClip = args.includes("--copy");
+  const outIdx     = args.indexOf("--out");
+  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 contract = readContract(infernoDir);
+  if (!contract) {
+    const msg = "No contract.json found. Run: infernoflow init";
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); } else { warn(msg); }
+    process.exit(1);
+  }
+
+  const changelog   = readChangelog(cwd);
+  const generatedAt = new Date().toLocaleString();
+  const htmlContent = buildHtml(contract, changelog, generatedAt);
+
+  const outPath = outIdx !== -1 ? args[outIdx + 1] : path.join(cwd, "inferno", "share.html");
+  fs.writeFileSync(outPath, htmlContent, "utf8");
+
+  let url = null;
+
+  if (upload) {
+    if (!jsonMode) info("Uploading to dpaste.com…");
+    try {
+      url = await uploadToDpaste(htmlContent);
+    } catch (err) {
+      if (!jsonMode) warn(`Upload failed: ${err.message}`);
+    }
+  }
+
+  if (copyToClip) {
+    try {
+      const cmd = process.platform === "win32" ? `echo ${JSON.stringify(htmlContent)} | clip`
+                : process.platform === "darwin" ? `pbcopy`
+                : `xclip -selection clipboard`;
+      if (process.platform === "darwin") {
+        const { execSync: ex } = await import("node:child_process");
+        const proc = ex;
+        require("child_process").execSync("pbcopy", { input: htmlContent });
+      } else {
+        execSync(cmd, { input: htmlContent });
+      }
+      if (!jsonMode) info("HTML copied to clipboard");
+    } catch {}
+  }
+
+  if (openBrowser) {
+    try {
+      const target = url || outPath;
+      const cmd = process.platform === "win32" ? `start "" "${target}"`
+                : process.platform === "darwin" ? `open "${target}"`
+                : `xdg-open "${target}"`;
+      execSync(cmd, { stdio: "ignore" });
+    } catch {}
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, file: outPath, url }));
+    return;
+  }
+
+  const caps = (contract.capabilities || []).length;
+  done(`Snapshot created — ${bold(String(caps))} capabilities`);
+  console.log();
+  console.log(`  File: ${cyan(outPath)}`);
+  if (url) console.log(`  URL:  ${cyan(url)}`);
+  console.log();
+  if (!url) {
+    console.log(`  ${gray("Share the file or run with --upload to get a public URL:")}`);
+    console.log(`  ${cyan("infernoflow share --upload --open")}`);
+  }
+  console.log();
+}

package/dist/lib/commands/watch.mjs

@@ -0,0 +1,203 @@
+/**
+ * infernoflow watch
+ *
+ * File-system watcher that runs `infernoflow suggest` automatically whenever
+ * source files are saved. Zero manual steps — just code, save, and the
+ * contract stays in sync.
+ *
+ * Usage:
+ *   infernoflow watch                  Watch src/ (or auto-detected root)
+ *   infernoflow watch src lib          Watch specific directories
+ *   infernoflow watch --interval 5     Debounce interval in seconds (default: 3)
+ *   infernoflow watch --dry-run        Print what would run, don't actually run
+ *   infernoflow watch --silent         No output (git-hook friendly)
+ *
+ * What it does on each save:
+ *   1. Debounce (3 s default) — batches rapid multi-file saves
+ *   2. Diff changed files against capability-map.json
+ *   3. If relevant capabilities may be affected → run suggest
+ *   4. Run check silently — log issues to inferno/WATCH.log
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { execSync, spawnSync } from "node:child_process";
+import { ok, warn, info, bold, cyan, gray, green, yellow } from "../ui/output.mjs";
+
+// ── Source file detection ─────────────────────────────────────────────────────
+
+const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".java", ".cs", ".rb", ".swift"]);
+const SKIP_DIRS   = new Set(["node_modules", ".git", "dist", "build", "out", ".next", ".angular", "vendor", "coverage", "__pycache__"]);
+
+function defaultWatchDirs(cwd) {
+  const candidates = ["src", "lib", "app", "pages", "components", "server", "api"];
+  const found = candidates.filter(d => fs.existsSync(path.join(cwd, d)));
+  return found.length ? found.map(d => path.join(cwd, d)) : [cwd];
+}
+
+function isSourceFile(filePath) {
+  return SOURCE_EXTS.has(path.extname(filePath).toLowerCase());
+}
+
+// ── Capability relevance check ────────────────────────────────────────────────
+
+function capabilityRelevance(changedFiles, infernoDir) {
+  const mapPath = path.join(infernoDir, "capability-map.json");
+  if (!fs.existsSync(mapPath)) return { relevant: true, reason: "no cap-map — suggesting broadly" };
+
+  let capMap;
+  try { capMap = JSON.parse(fs.readFileSync(mapPath, "utf8")); } catch { return { relevant: true, reason: "cap-map unreadable" }; }
+
+  const hits = [];
+  for (const file of changedFiles) {
+    const rel = path.relative(process.cwd(), file).replace(/\\/g, "/");
+    for (const [prefix, capIds] of Object.entries(capMap)) {
+      if (rel.startsWith(prefix.replace(/\\/g, "/"))) {
+        hits.push(...capIds);
+      }
+    }
+  }
+
+  if (hits.length > 0) return { relevant: true, reason: `touches: ${[...new Set(hits)].slice(0,3).join(", ")}` };
+  return { relevant: false, reason: "no mapped capabilities affected" };
+}
+
+// ── Run suggest + check ───────────────────────────────────────────────────────
+
+function runSuggest(changedFiles, cwd, infernoDir, dryRun, silent) {
+  const names = changedFiles.map(f => path.basename(f, path.extname(f))).slice(0, 3).join(", ");
+  const desc  = `code changes in ${names}`;
+
+  if (!silent) {
+    process.stdout.write(`  ${yellow("⟳")}  suggesting from ${bold(String(changedFiles.length))} changed file${changedFiles.length !== 1 ? "s" : ""}… `);
+  }
+
+  if (dryRun) {
+    if (!silent) console.log(gray("(dry run)"));
+    return;
+  }
+
+  try {
+    spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(path.dirname(new URL(import.meta.url).pathname))), "bin", "infernoflow.mjs"),
+      "suggest", desc, "--json"
+    ], { cwd, encoding: "utf8", timeout: 30_000, stdio: "ignore" });
+
+    if (!silent) console.log(green("done"));
+  } catch {
+    if (!silent) console.log(gray("skipped (no changes)"));
+  }
+
+  // Silent check — write issues to WATCH.log
+  try {
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(path.dirname(new URL(import.meta.url).pathname))), "bin", "infernoflow.mjs"),
+      "check", "--json"
+    ], { cwd, encoding: "utf8", timeout: 15_000 });
+
+    const out = result.stdout?.trim();
+    if (out) {
+      const data = JSON.parse(out);
+      if (data.status === "error" || data.status === "warning") {
+        fs.writeFileSync(path.join(infernoDir, "WATCH.log"), out + "\n");
+        if (!silent) warn(`Contract issues detected — see inferno/WATCH.log`);
+      } else {
+        const logPath = path.join(infernoDir, "WATCH.log");
+        if (fs.existsSync(logPath)) fs.unlinkSync(logPath);
+      }
+    }
+  } catch {}
+}
+
+// ── Watcher ───────────────────────────────────────────────────────────────────
+
+export async function watchCommand(rawArgs) {
+  const args       = rawArgs.slice(1);
+  const dryRun     = args.includes("--dry-run");
+  const silent     = args.includes("--silent");
+  const intervalIdx = args.indexOf("--interval");
+  const debounceMs = ((intervalIdx !== -1 ? parseFloat(args[intervalIdx + 1]) : 3) || 3) * 1000;
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    warn("inferno/ not found. Run: infernoflow init");
+    process.exit(1);
+  }
+
+  // Collect directories to watch
+  const dirArgs  = args.filter(a => !a.startsWith("-") && a !== String(args[intervalIdx + 1]));
+  const watchDirs = dirArgs.length
+    ? dirArgs.map(d => path.resolve(cwd, d))
+    : defaultWatchDirs(cwd);
+
+  const validDirs = watchDirs.filter(d => fs.existsSync(d));
+  if (!validDirs.length) {
+    warn("No valid directories to watch.");
+    process.exit(1);
+  }
+
+  if (!silent) {
+    console.log();
+    console.log(`  ${bold("🔥 infernoflow watch")}  ${gray("(Ctrl+C to stop)")}`);
+    console.log();
+    validDirs.forEach(d => console.log(`  ${cyan("watching")} ${gray(path.relative(cwd, d) || ".")}`));
+    console.log(`  ${gray(`debounce: ${debounceMs / 1000}s`)}`);
+    console.log();
+  }
+
+  let debounceTimer = null;
+  const pendingFiles = new Set();
+
+  const handleChange = (filePath) => {
+    if (!isSourceFile(filePath)) return;
+    pendingFiles.add(filePath);
+
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      const changed = Array.from(pendingFiles);
+      pendingFiles.clear();
+
+      if (!silent) {
+        const names = changed.map(f => path.relative(cwd, f)).slice(0, 3).join(", ");
+        process.stdout.write(`\n  ${gray(new Date().toLocaleTimeString())}  ${bold(names)}${changed.length > 3 ? ` +${changed.length - 3} more` : ""}  `);
+      }
+
+      const { relevant, reason } = capabilityRelevance(changed, infernoDir);
+      if (!relevant) {
+        if (!silent) console.log(gray(`skip (${reason})`));
+        return;
+      }
+
+      runSuggest(changed, cwd, infernoDir, dryRun, silent);
+    }, debounceMs);
+  };
+
+  // Start watchers on each directory
+  const watchers = [];
+  for (const dir of validDirs) {
+    try {
+      const watcher = fs.watch(dir, { recursive: true }, (event, filename) => {
+        if (filename) handleChange(path.join(dir, filename));
+      });
+      watchers.push(watcher);
+    } catch (err) {
+      if (!silent) warn(`Cannot watch ${dir}: ${err.message}`);
+    }
+  }
+
+  if (!watchers.length) {
+    warn("No directories could be watched.");
+    process.exit(1);
+  }
+
+  // Keep alive
+  process.on("SIGINT", () => {
+    watchers.forEach(w => w.close());
+    if (!silent) { console.log("\n\n  Stopped."); console.log(); }
+    process.exit(0);
+  });
+
+  // Block forever
+  await new Promise(() => {});
+}

package/package.json

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