infernoflow 0.14.0 → 0.16.0

package/dist/bin/infernoflow.mjs

@@ -35,6 +35,8 @@ const COMMAND_DESCRIPTIONS = {
   "pr-comment": "Post capability drift analysis as a GitHub PR comment (works in CI automatically)",
   dashboard: "Launch local web dashboard on localhost:7337 — live contract health, capabilities, agents",
   "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)",
 };
 
 const COMMAND_HANDLERS = {
@@ -63,6 +65,8 @@ const COMMAND_HANDLERS = {
   "pr-comment": async (args) => (await import("../lib/commands/prComment.mjs")).prCommentCommand(args),
   dashboard: async (args) => (await import("../lib/commands/dashboard.mjs")).dashboardCommand(args),
   "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),
 };
 
 function formatCommandsHelp() {
@@ -92,7 +96,9 @@ ${formatCommandsHelp()}
     update                    Draft ## Unreleased from commits (default sub-command)
     show                      Print the current ## Unreleased block
     list                      List commits since last tag
+    ai                        Generate human-readable changelog with AI (Anthropic or Ollama)
     --ref <tag|commit>        Use a specific ref instead of last tag
+    --version <x.y.z>         Version label for the AI-generated entry
     --dry-run                 Print what would be written without modifying file
     --append                  Append to existing ## Unreleased instead of replacing
     --json                    Machine-readable output
@@ -181,6 +187,20 @@ ${formatCommandsHelp()}
     --dry-run             Print the comment without posting it
     --json                Machine-readable output
 
+  ${bold("cloud sub-commands:")}
+    init                      Generate a project token and configure cloud sync
+    push                      Upload local capability contract to cloud
+    pull                      Download latest contract from cloud (conflict detection)
+    status                    Compare local vs cloud (hashes, capability counts)
+    dashboard                 Print hosted dashboard URL and open in browser
+
+  ${bold("cloud options:")}
+    --token <tok>             Override token (or set INFERNOFLOW_TOKEN env var)
+    --endpoint <url>          Override default endpoint (https://cloud.infernoflow.dev)
+    --force, -f               Overwrite on init; overwrite local on conflicted pull
+    --dry-run                 Print what would happen without sending
+    --json                    Machine-readable output
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/changelog.mjs

@@ -303,6 +303,248 @@ async function subcmdUpdate(cwd, changelogPath, opts) {
   console.log(`  Run ${cyan("infernoflow publish")} when ready to cut the release\n`);
 }
 
+// ── AI changelog writer ───────────────────────────────────────────────────────
+
+function parseCaps(jsonText) {
+  if (!jsonText) return [];
+  try {
+    const obj = JSON.parse(jsonText);
+    const raw = obj.capabilities || [];
+    return raw.map(c => typeof c === "string" ? { id: c, title: c } : c);
+  } catch { return []; }
+}
+
+function loadCapsFromDisk(infernoDir) {
+  for (const name of ["capabilities.json", "contract.json"]) {
+    const p = path.join(infernoDir, name);
+    if (fs.existsSync(p)) return parseCaps(fs.readFileSync(p, "utf8"));
+  }
+  return [];
+}
+
+function loadCapsAtRef(ref, cwd) {
+  const { execSync: _exec } = await import ? null : null; // handled below
+  try {
+    const { execSync: ex } = await import("node:child_process");
+    for (const name of ["capabilities.json", "contract.json"]) {
+      try {
+        const content = ex(`git show "${ref}:inferno/${name}"`, {
+          cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"]
+        }).trim();
+        if (content) return parseCaps(content);
+      } catch {}
+    }
+  } catch {}
+  return [];
+}
+
+function diffCapsSimple(before, after) {
+  const beforeMap = new Map(before.map(c => [c.id, c]));
+  const afterMap  = new Map(after.map(c  => [c.id, c]));
+  return {
+    added:   after.filter(c  => !beforeMap.has(c.id)),
+    removed: before.filter(c => !afterMap.has(c.id)),
+    changed: after.filter(c  => {
+      const old = beforeMap.get(c.id);
+      return old && old.title !== c.title;
+    }),
+  };
+}
+
+function buildAiPrompt(commits, diff, ref, version) {
+  const lines = [];
+  lines.push(`You are writing a changelog entry for a software release.`);
+  lines.push(`Write it in a friendly, clear, developer-facing tone.`);
+  lines.push(`Use Markdown. Start with ## ${version || "Unreleased"}`);
+  lines.push(`Include sections: ### Added, ### Fixed, ### Changed, ### Removed (only if non-empty).`);
+  lines.push(`Be concise — one line per item. Do not include commit hashes.`);
+  lines.push(`Do not invent features that are not listed below.`);
+  lines.push(``);
+  lines.push(`## Capability changes since ${ref || "last release"}:`);
+  if (diff.added.length)   lines.push(`Added: ${diff.added.map(c => c.title || c.id).join(", ")}`);
+  if (diff.removed.length) lines.push(`Removed: ${diff.removed.map(c => c.title || c.id).join(", ")}`);
+  if (diff.changed.length) lines.push(`Changed: ${diff.changed.map(c => c.title || c.id).join(", ")}`);
+  if (!diff.added.length && !diff.removed.length && !diff.changed.length) lines.push(`(no capability changes)`);
+  lines.push(``);
+  lines.push(`## Git commits since ${ref || "last release"}:`);
+  for (const c of commits.slice(0, 40)) lines.push(`- ${c.subject}`);
+  lines.push(``);
+  lines.push(`Write the changelog entry now:`);
+  return lines.join("\n");
+}
+
+function buildStructuredFallback(commits, diff, version) {
+  // High-quality template fallback when no AI provider is available
+  const sections = groupCommits(commits);
+
+  // Merge capability changes into sections
+  for (const c of diff.added)   sections.Added.unshift(`${c.title || c.id} capability`);
+  for (const c of diff.removed) sections.Removed.unshift(`${c.title || c.id} capability`);
+  for (const c of diff.changed) sections.Changed.unshift(`Updated ${c.title || c.id} capability`);
+
+  // Deduplicate
+  for (const key of Object.keys(sections)) sections[key] = [...new Set(sections[key])];
+
+  const tag = version || "Unreleased";
+  const date = new Date().toISOString().slice(0, 10);
+  const lines = [`## ${tag} — ${date}`, ""];
+
+  const ORDER = ["Breaking", "Added", "Fixed", "Changed", "Removed"];
+  for (const heading of ORDER) {
+    const items = sections[heading];
+    if (!items?.length) continue;
+    lines.push(`### ${heading}`);
+    for (const item of items) lines.push(`- ${item}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+async function callLocalAi(prompt) {
+  // Try Ollama (localhost:11434) — most common local AI setup
+  try {
+    const { default: http } = await import("node:http");
+    return new Promise((resolve, reject) => {
+      const body = JSON.stringify({ model: "llama3", prompt, stream: false });
+      const req = http.request({
+        hostname: "localhost", port: 11434,
+        path: "/api/generate", method: "POST",
+        headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) },
+      }, (res) => {
+        let raw = "";
+        res.on("data", d => raw += d);
+        res.on("end", () => {
+          try { resolve(JSON.parse(raw).response || null); } catch { resolve(null); }
+        });
+      });
+      req.setTimeout(30_000, () => { req.destroy(); reject(new Error("timeout")); });
+      req.on("error", reject);
+      req.write(body);
+      req.end();
+    });
+  } catch { return null; }
+}
+
+async function callAnthropicAi(prompt, apiKey) {
+  const { default: https } = await import("node:https");
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({
+      model: "claude-haiku-4-5-20251001",
+      max_tokens: 1024,
+      messages: [{ role: "user", content: prompt }],
+    });
+    const req = https.request({
+      hostname: "api.anthropic.com",
+      path: "/v1/messages", method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+      },
+    }, (res) => {
+      let raw = "";
+      res.on("data", d => raw += d);
+      res.on("end", () => {
+        try {
+          const data = JSON.parse(raw);
+          resolve(data.content?.[0]?.text || null);
+        } catch { resolve(null); }
+      });
+    });
+    req.setTimeout(30_000, () => { req.destroy(); reject(new Error("timeout")); });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+async function subcmdAi(cwd, changelogPath, opts) {
+  const { ref, dryRun, asJson, version } = opts;
+  const infernoDir = path.join(cwd, "inferno");
+
+  const tag     = ref || lastTag(cwd);
+  const commits = commitsSince(tag, cwd);
+
+  // Load capability diff
+  const currentCaps = fs.existsSync(infernoDir) ? loadCapsFromDisk(infernoDir) : [];
+  const prevCaps    = tag ? (() => {
+    try {
+      const ex = require("child_process").execSync;
+      for (const name of ["capabilities.json", "contract.json"]) {
+        try {
+          const c = ex(`git show "${tag}:inferno/${name}"`, { cwd, encoding: "utf8", stdio: ["ignore","pipe","pipe"] }).trim();
+          if (c) return parseCaps(c);
+        } catch {}
+      }
+      return [];
+    } catch { return []; }
+  })() : [];
+
+  const diff = diffCapsSimple(prevCaps, currentCaps);
+
+  if (!asJson) {
+    info(`Generating AI changelog since ${bold(tag || "beginning")}...`);
+    info(`${commits.length} commits · ${diff.added.length} added · ${diff.removed.length} removed · ${diff.changed.length} changed`);
+    console.log();
+  }
+
+  const prompt = buildAiPrompt(commits, diff, tag, version);
+  let aiText = null;
+  let provider = "template";
+
+  // Try AI providers in order: Anthropic API → Ollama → structured template
+  const anthropicKey = process.env.ANTHROPIC_API_KEY;
+  if (anthropicKey) {
+    try {
+      aiText = await callAnthropicAi(prompt, anthropicKey);
+      if (aiText) provider = "anthropic";
+    } catch {}
+  }
+
+  if (!aiText) {
+    try {
+      aiText = await callLocalAi(prompt);
+      if (aiText) provider = "ollama";
+    } catch {}
+  }
+
+  // Fallback: structured template
+  if (!aiText) {
+    aiText = buildStructuredFallback(commits, diff, version);
+    provider = "template";
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify({ ok: true, provider, ref: tag, commits: commits.length, markdown: aiText }));
+    return;
+  }
+
+  console.log(gray("  ─── Generated changelog ──────────────────────────────"));
+  aiText.split("\n").forEach(l => console.log("  " + l));
+  console.log(gray("  ──────────────────────────────────────────────────────"));
+  console.log();
+  info(`Generated via: ${bold(provider)}`);
+
+  if (dryRun) {
+    warn("Dry run — CHANGELOG.md not modified");
+    console.log();
+    return;
+  }
+
+  // Write to CHANGELOG.md
+  let text = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, "utf8") : "# Changelog\n\n";
+  const updated = injectUnreleased(text, aiText);
+  fs.writeFileSync(changelogPath, updated);
+
+  ok(`CHANGELOG.md updated with AI-generated entry`);
+  if (provider === "template") {
+    info(`Tip: set ANTHROPIC_API_KEY for richer AI-written changelogs`);
+  }
+  console.log();
+}
+
 // ── main ─────────────────────────────────────────────────────────────────────
 
 export async function changelogCommand(rawArgs) {
@@ -311,12 +553,14 @@ export async function changelogCommand(rawArgs) {
   // Sub-command: first non-flag arg
   const sub = args.find(a => !a.startsWith("-")) || "update";
 
-  const dryRun = args.includes("--dry-run");
-  const append = args.includes("--append");
-  const asJson = args.includes("--json");
+  const dryRun  = args.includes("--dry-run");
+  const append  = args.includes("--append");
+  const asJson  = args.includes("--json");
 
-  const refIdx = args.indexOf("--ref");
-  const ref    = refIdx !== -1 ? args[refIdx + 1] : null;
+  const refIdx     = args.indexOf("--ref");
+  const versionIdx = args.indexOf("--version");
+  const ref     = refIdx     !== -1 ? args[refIdx + 1]     : null;
+  const version = versionIdx !== -1 ? args[versionIdx + 1] : null;
 
   const cwd           = process.cwd();
   const changelogPath = path.join(cwd, "CHANGELOG.md");
@@ -338,6 +582,11 @@ export async function changelogCommand(rawArgs) {
     return;
   }
 
-  fail(`Unknown sub-command: ${sub}`, "Use: update | show | list");
+  if (sub === "ai") {
+    await subcmdAi(cwd, changelogPath, { ref, dryRun, asJson, version });
+    return;
+  }
+
+  fail(`Unknown sub-command: ${sub}`, "Use: update | show | list | ai");
   process.exit(1);
 }

package/dist/lib/commands/cloud.mjs

@@ -0,0 +1,521 @@
+/**
+ * infernoflow cloud
+ *
+ * Sync capability contracts with the infernoflow cloud service.
+ * A hosted alternative to `team-sync` (which uses a shared git branch).
+ *
+ * Sub-commands:
+ *   cloud init                 Generate a project token and write inferno/.cloud.json
+ *   cloud push                 Upload local contract to cloud
+ *   cloud pull                 Download latest contract from cloud
+ *   cloud status               Show local vs cloud diff
+ *   cloud dashboard            Print hosted dashboard URL
+ *
+ * Flags:
+ *   --token <tok>              Override token from env INFERNOFLOW_TOKEN
+ *   --endpoint <url>           Override default endpoint
+ *   --dry-run                  Print what would happen without sending
+ *   --json                     Machine-readable output
+ *
+ * Usage:
+ *   infernoflow cloud init
+ *   infernoflow cloud push
+ *   infernoflow cloud pull
+ *   infernoflow cloud status --json
+ */
+
+import * as fs     from "node:fs";
+import * as path   from "node:path";
+import * as https  from "node:https";
+import * as http   from "node:http";
+import * as crypto from "node:crypto";
+import { header, ok, warn, info, done, bold, cyan, gray, green, red, yellow } from "../ui/output.mjs";
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+const DEFAULT_ENDPOINT = "https://cloud.infernoflow.dev";
+const CLOUD_CONFIG_FILE = ".cloud.json";
+
+function readCloudConfig(infernoDir) {
+  const p = path.join(infernoDir, CLOUD_CONFIG_FILE);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+function writeCloudConfig(infernoDir, config) {
+  const p = path.join(infernoDir, CLOUD_CONFIG_FILE);
+  fs.writeFileSync(p, JSON.stringify(config, null, 2) + "\n");
+}
+
+function getToken(config, args) {
+  const idx = args.indexOf("--token");
+  if (idx !== -1) return args[idx + 1];
+  return process.env.INFERNOFLOW_TOKEN || config?.token || null;
+}
+
+function getEndpoint(config, args) {
+  const idx = args.indexOf("--endpoint");
+  if (idx !== -1) return args[idx + 1];
+  return process.env.INFERNOFLOW_ENDPOINT || config?.endpoint || DEFAULT_ENDPOINT;
+}
+
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+
+function httpsRequest(method, url, body, token) {
+  return new Promise((resolve, reject) => {
+    const parsed  = new URL(url);
+    const isHttps = parsed.protocol === "https:";
+    const lib     = isHttps ? https : http;
+    const payload = body ? JSON.stringify(body) : null;
+
+    const options = {
+      hostname: parsed.hostname,
+      port:     parsed.port || (isHttps ? 443 : 80),
+      path:     parsed.pathname + (parsed.search || ""),
+      method,
+      headers: {
+        "Content-Type":  "application/json",
+        "Accept":        "application/json",
+        "User-Agent":    "infernoflow-cli",
+        ...(token ? { "Authorization": `Bearer ${token}` } : {}),
+        ...(payload ? { "Content-Length": Buffer.byteLength(payload) } : {}),
+      },
+    };
+
+    const req = lib.request(options, (res) => {
+      let data = "";
+      res.on("data", (chunk) => (data += chunk));
+      res.on("end", () => {
+        try {
+          resolve({ status: res.statusCode, body: JSON.parse(data) });
+        } catch {
+          resolve({ status: res.statusCode, body: data });
+        }
+      });
+    });
+
+    req.on("error", reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+// ── Contract helpers ──────────────────────────────────────────────────────────
+
+function readContract(infernoDir) {
+  const candidates = ["contract.json", "capabilities.json"];
+  for (const f of candidates) {
+    const p = path.join(infernoDir, f);
+    if (fs.existsSync(p)) {
+      try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+    }
+  }
+  return null;
+}
+
+function contractHash(contract) {
+  return crypto.createHash("sha256").update(JSON.stringify(contract)).digest("hex").slice(0, 12);
+}
+
+// ── Sub-commands ──────────────────────────────────────────────────────────────
+
+async function subcmdInit(args, cwd, infernoDir) {
+  const jsonMode = args.includes("--json");
+  const endpoint = getEndpoint(null, args);
+  const dryRun   = args.includes("--dry-run");
+
+  // Check for existing config
+  const existing = readCloudConfig(infernoDir);
+  if (existing && !args.includes("--force") && !args.includes("-f")) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: false, error: "Already initialised. Use --force to overwrite.", config: existing }));
+    } else {
+      warn("Cloud already configured for this project.");
+      console.log(`  Token:    ${gray(existing.token)}`);
+      console.log(`  Endpoint: ${gray(existing.endpoint)}`);
+      console.log(`  Project:  ${gray(existing.projectId)}`);
+      console.log();
+      info("Use --force to generate a new token.");
+    }
+    return;
+  }
+
+  // Generate a project ID and token
+  const projectId = crypto.randomBytes(8).toString("hex");
+  const token     = crypto.randomBytes(24).toString("base64url");
+
+  const config = {
+    projectId,
+    token,
+    endpoint,
+    createdAt: new Date().toISOString(),
+  };
+
+  if (dryRun) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, dryRun: true, config }));
+    } else {
+      info("Dry run — would write inferno/.cloud.json:");
+      console.log("  " + JSON.stringify(config, null, 2).split("\n").join("\n  "));
+    }
+    return;
+  }
+
+  if (!jsonMode) header("Initialising infernoflow cloud");
+
+  // Register project with cloud endpoint (best-effort)
+  try {
+    const resp = await httpsRequest("POST", `${endpoint}/api/projects`, { projectId }, null);
+    if (resp.status === 200 || resp.status === 201) {
+      if (!jsonMode) ok("Project registered on cloud");
+    }
+  } catch {
+    if (!jsonMode) info("Cloud endpoint unreachable — saved config locally (will connect on first push)");
+  }
+
+  writeCloudConfig(infernoDir, config);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, projectId, endpoint }));
+  } else {
+    done("Cloud configured!");
+    console.log();
+    console.log(`  Project ID: ${cyan(projectId)}`);
+    console.log(`  Endpoint:   ${gray(endpoint)}`);
+    console.log(`  Token:      ${gray(token.slice(0, 8) + "…")} (stored in inferno/.cloud.json)`);
+    console.log();
+    console.log(`  ${gray("Share the dashboard:")} ${cyan(`${endpoint}/p/${projectId}`)}`);
+    console.log();
+    console.log(`  ${yellow("⚠")}  Add inferno/.cloud.json to .gitignore to protect your token!`);
+    console.log(`     ${gray("echo 'inferno/.cloud.json' >> .gitignore")}`);
+    console.log();
+  }
+}
+
+async function subcmdPush(args, cwd, infernoDir) {
+  const jsonMode = args.includes("--json");
+  const dryRun   = args.includes("--dry-run");
+  const config   = readCloudConfig(infernoDir);
+  const token    = getToken(config, args);
+  const endpoint = getEndpoint(config, args);
+
+  if (!token) {
+    const msg = "No token found. Run: infernoflow cloud 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 projectId = config?.projectId || "unknown";
+  const hash      = contractHash(contract);
+  const caps      = (contract.capabilities || []).length;
+
+  if (dryRun) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, dryRun: true, projectId, hash, capabilities: caps }));
+    } else {
+      info(`Dry run — would push ${bold(String(caps))} capabilities (hash: ${hash}) to ${endpoint}`);
+    }
+    return;
+  }
+
+  if (!jsonMode) header("Pushing contract to cloud");
+
+  try {
+    const resp = await httpsRequest(
+      "PUT",
+      `${endpoint}/api/projects/${projectId}/contract`,
+      { contract, hash, pushedAt: new Date().toISOString() },
+      token
+    );
+
+    if (resp.status === 200 || resp.status === 201 || resp.status === 204) {
+      if (jsonMode) {
+        console.log(JSON.stringify({ ok: true, projectId, hash, capabilities: caps }));
+      } else {
+        done(`Pushed ${bold(String(caps))} capabilities`);
+        console.log(`  ${gray("Dashboard:")} ${cyan(`${endpoint}/p/${projectId}`)}`);
+        console.log();
+      }
+    } else {
+      const errMsg = `Cloud returned ${resp.status}`;
+      if (jsonMode) { console.log(JSON.stringify({ ok: false, error: errMsg, status: resp.status })); }
+      else { warn(errMsg); }
+      process.exit(1);
+    }
+  } catch (err) {
+    // Cloud unreachable — save a pending push marker
+    const pendingPath = path.join(infernoDir, ".cloud-pending.json");
+    fs.writeFileSync(pendingPath, JSON.stringify({ hash, pendingAt: new Date().toISOString() }));
+
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: false, error: err.message, pending: true }));
+    } else {
+      warn("Cloud unreachable — push queued locally.");
+      info("Changes will sync automatically on next successful connection.");
+    }
+  }
+}
+
+async function subcmdPull(args, cwd, infernoDir) {
+  const jsonMode = args.includes("--json");
+  const dryRun   = args.includes("--dry-run");
+  const config   = readCloudConfig(infernoDir);
+  const token    = getToken(config, args);
+  const endpoint = getEndpoint(config, args);
+
+  if (!token) {
+    const msg = "No token found. Run: infernoflow cloud init";
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); } else { warn(msg); }
+    process.exit(1);
+  }
+
+  const projectId = config?.projectId || "unknown";
+
+  if (!jsonMode) header("Pulling contract from cloud");
+
+  try {
+    const resp = await httpsRequest(
+      "GET",
+      `${endpoint}/api/projects/${projectId}/contract`,
+      null,
+      token
+    );
+
+    if (resp.status !== 200) {
+      const errMsg = `Cloud returned ${resp.status}`;
+      if (jsonMode) { console.log(JSON.stringify({ ok: false, error: errMsg })); }
+      else { warn(errMsg); }
+      process.exit(1);
+    }
+
+    const remote   = resp.body?.contract;
+    const localRaw = readContract(infernoDir);
+
+    if (!remote) {
+      const msg = "No contract found on cloud. Push first.";
+      if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); }
+      else { warn(msg); }
+      return;
+    }
+
+    // Detect conflicts (same capability changed on both sides)
+    const localCaps  = (localRaw?.capabilities || []).map(c => typeof c === "string" ? c : c.id);
+    const remoteCaps = (remote.capabilities   || []).map(c => typeof c === "string" ? c : c.id);
+    const localSet   = new Set(localCaps);
+    const remoteSet  = new Set(remoteCaps);
+    const onlyLocal  = localCaps.filter(id => !remoteSet.has(id));
+    const onlyRemote = remoteCaps.filter(id => !localSet.has(id));
+
+    if (onlyLocal.length > 0 && onlyRemote.length > 0) {
+      if (!jsonMode) {
+        warn("Diverged contracts detected:");
+        onlyLocal.forEach(id => console.log(`  ${red("-")} local-only:  ${id}`));
+        onlyRemote.forEach(id => console.log(`  ${green("+")} remote-only: ${id}`));
+        console.log();
+        warn("Merge manually or use --force to overwrite local with remote.");
+      } else {
+        console.log(JSON.stringify({
+          ok: false,
+          conflict: true,
+          onlyLocal,
+          onlyRemote,
+        }));
+      }
+      if (!args.includes("--force") && !args.includes("-f")) return;
+    }
+
+    if (dryRun) {
+      if (jsonMode) {
+        console.log(JSON.stringify({ ok: true, dryRun: true, capabilities: remoteCaps.length, hash: contractHash(remote) }));
+      } else {
+        info(`Dry run — would write ${bold(String(remoteCaps.length))} capabilities from cloud`);
+      }
+      return;
+    }
+
+    // Write pulled contract
+    const contractPath = path.join(infernoDir, "contract.json");
+    fs.writeFileSync(contractPath, JSON.stringify(remote, null, 2) + "\n");
+
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, capabilities: remoteCaps.length, hash: contractHash(remote) }));
+    } else {
+      done(`Pulled ${bold(String(remoteCaps.length))} capabilities from cloud`);
+      if (onlyLocal.length) warn(`${onlyLocal.length} local-only capabilities were overwritten.`);
+      console.log();
+    }
+  } catch (err) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: err.message })); }
+    else { warn(`Cloud unreachable: ${err.message}`); }
+    process.exit(1);
+  }
+}
+
+async function subcmdStatus(args, cwd, infernoDir) {
+  const jsonMode = args.includes("--json");
+  const config   = readCloudConfig(infernoDir);
+  const token    = getToken(config, args);
+  const endpoint = getEndpoint(config, args);
+
+  if (!config) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "Not initialised. Run: infernoflow cloud init" })); }
+    else { warn("Cloud not configured. Run: infernoflow cloud init"); }
+    return;
+  }
+
+  const projectId  = config.projectId;
+  const localContract = readContract(infernoDir);
+  const localHash  = localContract ? contractHash(localContract) : null;
+  const localCaps  = (localContract?.capabilities || []).length;
+
+  if (!jsonMode) header("Cloud status");
+
+  let remoteHash = null;
+  let remoteCaps = 0;
+  let reachable  = false;
+
+  try {
+    const resp = await httpsRequest(
+      "GET",
+      `${endpoint}/api/projects/${projectId}/contract`,
+      null,
+      token
+    );
+    if (resp.status === 200 && resp.body?.contract) {
+      reachable  = true;
+      remoteHash = contractHash(resp.body.contract);
+      remoteCaps = (resp.body.contract?.capabilities || []).length;
+    }
+  } catch {}
+
+  const inSync = localHash === remoteHash;
+  const pending = fs.existsSync(path.join(infernoDir, ".cloud-pending.json"));
+
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      ok: true,
+      projectId,
+      endpoint,
+      reachable,
+      inSync,
+      pending,
+      local:  { hash: localHash, capabilities: localCaps },
+      remote: reachable ? { hash: remoteHash, capabilities: remoteCaps } : null,
+    }));
+    return;
+  }
+
+  console.log(`  Project:   ${cyan(projectId)}`);
+  console.log(`  Endpoint:  ${gray(endpoint)}`);
+  console.log(`  Dashboard: ${cyan(`${endpoint}/p/${projectId}`)}`);
+  console.log();
+  console.log(`  Local:     ${bold(String(localCaps))} capabilities  ${gray("(hash: " + (localHash || "none") + ")")}`);
+
+  if (!reachable) {
+    console.log(`  Cloud:     ${yellow("unreachable")}`);
+  } else {
+    console.log(`  Cloud:     ${bold(String(remoteCaps))} capabilities  ${gray("(hash: " + (remoteHash || "none") + ")")}`);
+    console.log();
+    if (inSync) {
+      console.log(`  ${green("✔")}  In sync with cloud`);
+    } else {
+      console.log(`  ${yellow("⚠")}  Out of sync — run ${cyan("infernoflow cloud push")} or ${cyan("infernoflow cloud pull")}`);
+    }
+  }
+
+  if (pending) {
+    console.log(`  ${yellow("⚠")}  Pending push queued (cloud was unreachable last time)`);
+  }
+
+  console.log();
+}
+
+async function subcmdDashboard(args, cwd, infernoDir) {
+  const config    = readCloudConfig(infernoDir);
+  const endpoint  = getEndpoint(config, args);
+  const projectId = config?.projectId;
+  const jsonMode  = args.includes("--json");
+
+  if (!projectId) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "Run: infernoflow cloud init first" })); }
+    else { warn("Not configured. Run: infernoflow cloud init first."); }
+    return;
+  }
+
+  const url = `${endpoint}/p/${projectId}`;
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, url }));
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold("🔥 infernoflow cloud dashboard")}`);
+  console.log();
+  console.log(`  ${cyan(url)}`);
+  console.log();
+  console.log(`  ${gray("Share this URL with your whole team.")}`);
+  console.log();
+
+  // Try to open in browser
+  try {
+    const { execSync } = await import("node:child_process");
+    const cmd = process.platform === "win32" ? `start "" "${url}"` :
+                process.platform === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
+    execSync(cmd, { stdio: "ignore" });
+  } catch {}
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+export async function cloudCommand(rawArgs) {
+  const args       = rawArgs.slice(1);
+  const subcmd     = args[0];
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ directory not found. Run: infernoflow init";
+    if (args.includes("--json")) { console.log(JSON.stringify({ ok: false, error: msg })); }
+    else { warn(msg); }
+    process.exit(1);
+  }
+
+  const subArgs = args.slice(1);
+
+  switch (subcmd) {
+    case "init":
+      return subcmdInit(subArgs, cwd, infernoDir);
+    case "push":
+      return subcmdPush(subArgs, cwd, infernoDir);
+    case "pull":
+      return subcmdPull(subArgs, cwd, infernoDir);
+    case "status":
+      return subcmdStatus(subArgs, cwd, infernoDir);
+    case "dashboard":
+      return subcmdDashboard(subArgs, cwd, infernoDir);
+    default: {
+      const jsonMode = args.includes("--json");
+      const msg = `Unknown cloud sub-command: ${subcmd || "(none)"}. Use: init | push | pull | status | dashboard`;
+      if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); }
+      else {
+        console.log();
+        console.log(`  ${bold("infernoflow cloud")} — hosted contract sync`);
+        console.log();
+        console.log(`  ${cyan("infernoflow cloud init")}       Set up cloud sync for this project`);
+        console.log(`  ${cyan("infernoflow cloud push")}       Upload local contract to cloud`);
+        console.log(`  ${cyan("infernoflow cloud pull")}       Download latest contract from cloud`);
+        console.log(`  ${cyan("infernoflow cloud status")}     Compare local vs cloud`);
+        console.log(`  ${cyan("infernoflow cloud dashboard")}  Open hosted dashboard in browser`);
+        console.log();
+      }
+    }
+  }
+}

package/dist/lib/commands/onboard.mjs

@@ -0,0 +1,296 @@
+/**
+ * infernoflow onboard
+ *
+ * Interactive step-by-step onboarding wizard for new developers.
+ * Walks through: what infernoflow is, detecting the stack, running init,
+ * showing the first contract, explaining each file, and a test suggest.
+ *
+ * Designed for teams adding a new member — run once, understand everything.
+ *
+ * Usage:
+ *   infernoflow onboard
+ *   infernoflow onboard --yes    # non-interactive (auto-accept all steps)
+ */
+
+import * as fs      from "node:fs";
+import * as path    from "node:path";
+import * as readline from "node:readline";
+import { execSync }  from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { header, ok, warn, info, done, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── readline helpers ──────────────────────────────────────────────────────────
+
+function createRl() {
+  return readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+
+async function ask(rl, question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+async function confirm(rl, question, defaultYes = true) {
+  const hint = defaultYes ? "[Y/n]" : "[y/N]";
+  const answer = await ask(rl, `  ${question} ${gray(hint)} `);
+  if (!answer.trim()) return defaultYes;
+  return answer.trim().toLowerCase().startsWith("y");
+}
+
+// ── step renderer ─────────────────────────────────────────────────────────────
+
+function step(n, total, title) {
+  console.log();
+  console.log(`  ${bold(cyan(`Step ${n}/${total}`))}  ${bold(title)}`);
+  console.log(`  ${gray("─".repeat(50))}`);
+}
+
+function explain(lines) {
+  for (const line of lines) {
+    console.log(`  ${gray(line)}`);
+  }
+  console.log();
+}
+
+// ── project detection ─────────────────────────────────────────────────────────
+
+function detectStack(cwd) {
+  const has = (f) => fs.existsSync(path.join(cwd, f));
+  const pkg = has("package.json") ? JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")) : {};
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  const framework = deps.react    ? "React"
+                  : deps.next     ? "Next.js"
+                  : deps.vue      ? "Vue"
+                  : deps.angular  ? "Angular"
+                  : deps.express  ? "Express"
+                  : deps.fastify  ? "Fastify"
+                  : has("requirements.txt") ? "Python"
+                  : has("go.mod")           ? "Go"
+                  : has("Cargo.toml")       ? "Rust"
+                  : "unknown";
+
+  const language = has("tsconfig.json") ? "TypeScript"
+                 : has("package.json")  ? "JavaScript"
+                 : has("requirements.txt") ? "Python"
+                 : has("go.mod")           ? "Go"
+                 : "unknown";
+
+  return { framework, language, name: pkg.name || path.basename(cwd) };
+}
+
+function capture(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch { return null; }
+}
+
+// ── main wizard ───────────────────────────────────────────────────────────────
+
+export async function onboardCommand(rawArgs) {
+  const args       = rawArgs.slice(1);
+  const autoYes    = args.includes("--yes") || args.includes("-y");
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+  const TOTAL      = 7;
+
+  const rl = autoYes ? null : createRl();
+
+  const ask_confirm = autoYes
+    ? async () => true
+    : (q, def) => confirm(rl, q, def);
+
+  console.clear();
+  console.log();
+  console.log(`  ${bold("🔥 Welcome to infernoflow")}`);
+  console.log(`  ${gray("This wizard walks you through everything in about 5 minutes.")}`);
+  console.log(`  ${gray("You'll understand what infernoflow does and how it fits your workflow.")}`);
+  console.log();
+
+  if (!autoYes) {
+    const ready = await ask_confirm("Ready to start?", true);
+    if (!ready) { console.log("\n  See you next time!\n"); rl.close(); return; }
+  }
+
+  // ── Step 1: What is infernoflow? ───────────────────────────────────────────
+  step(1, TOTAL, "What is infernoflow?");
+  explain([
+    "infernoflow keeps a living record of your project's capabilities",
+    "— the features your code actually provides — and makes sure that",
+    "record never drifts out of sync as you build.",
+    "",
+    "It works invisibly in the background:",
+    "  • Claude auto-tracks capability changes as you code",
+    "  • Git hooks update the changelog on every commit",
+    "  • PRs get automatic capability drift analysis",
+    "  • Version bumps are recommended automatically (major/minor/patch)",
+    "",
+    "You write code. infernoflow handles the bookkeeping.",
+  ]);
+
+  await ask_confirm("Got it — continue?", true);
+
+  // ── Step 2: Detect your project ────────────────────────────────────────────
+  step(2, TOTAL, "Detecting your project");
+  const stack = detectStack(cwd);
+  const isGitRepo = !!capture("git rev-parse --git-dir", cwd);
+  const alreadySetup = fs.existsSync(infernoDir);
+
+  console.log(`  Project:    ${bold(stack.name)}`);
+  console.log(`  Framework:  ${bold(stack.framework)}`);
+  console.log(`  Language:   ${bold(stack.language)}`);
+  console.log(`  Git repo:   ${isGitRepo ? green("yes") : red("no — git init first")}`);
+  console.log(`  infernoflow: ${alreadySetup ? green("already set up") : yellow("not set up yet")}`);
+  console.log();
+
+  if (!isGitRepo) {
+    warn("This directory is not a git repository.");
+    warn("Run: git init && git add . && git commit -m 'init'");
+    warn("Then run: infernoflow onboard");
+    if (rl) rl.close();
+    process.exit(1);
+  }
+
+  await ask_confirm("Continue?", true);
+
+  // ── Step 3: Run infernoflow setup ──────────────────────────────────────────
+  step(3, TOTAL, "Setting up infernoflow");
+  if (alreadySetup) {
+    ok("infernoflow is already set up in this project");
+    explain(["The inferno/ folder exists — skipping init."]);
+  } else {
+    explain([
+      "infernoflow setup will:",
+      "  1. Scan your codebase and infer capabilities automatically",
+      "  2. Create the inferno/ folder with contract.json",
+      "  3. Install the MCP server (for Claude Code integration)",
+      "  4. Write CLAUDE.md (makes Claude auto-track capabilities)",
+      "  5. Install git hooks (auto changelog + drift check)",
+    ]);
+
+    const go = await ask_confirm("Run infernoflow setup now?", true);
+    if (go) {
+      console.log();
+      try {
+        execSync("npx infernoflow setup --yes", {
+          cwd,
+          stdio: "inherit",
+          timeout: 120_000,
+        });
+      } catch (err) {
+        warn("Setup encountered an issue — you can re-run it manually:");
+        warn("  infernoflow setup");
+      }
+    } else {
+      info("Skipped — run: infernoflow setup");
+    }
+  }
+
+  await ask_confirm("Continue?", true);
+
+  // ── Step 4: Your capability contract ──────────────────────────────────────
+  step(4, TOTAL, "Your capability contract");
+  explain([
+    "The inferno/contract.json is the heart of infernoflow.",
+    "It lists every capability your project has — the things users can DO.",
+    "",
+    "Think of it as a living API contract, but for features, not endpoints.",
+  ]);
+
+  const contractPath = path.join(infernoDir, "contract.json");
+  if (fs.existsSync(contractPath)) {
+    try {
+      const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"));
+      const caps = contract.capabilities || [];
+      console.log(`  ${bold(String(caps.length))} capabilities tracked:\n`);
+      for (const c of caps.slice(0, 8)) {
+        const cap = typeof c === "string" ? { id: c, title: c } : c;
+        console.log(`    ${green("✔")} ${bold(cap.id)}  ${gray(cap.title || "")}`);
+      }
+      if (caps.length > 8) console.log(`    ${gray(`… and ${caps.length - 8} more`)}`);
+      console.log();
+    } catch {
+      warn("Could not read contract.json");
+    }
+  } else {
+    warn("No contract.json yet — run: infernoflow setup");
+  }
+
+  await ask_confirm("Continue?", true);
+
+  // ── Step 5: Your daily workflow ────────────────────────────────────────────
+  step(5, TOTAL, "Your daily workflow");
+  explain([
+    "Here's exactly how infernoflow fits into your git workflow:",
+    "",
+    "  1. git checkout -b feature/my-feature",
+    "     (branch from main as usual)",
+    "",
+    "  2. Write code in Claude / Cursor / VS Code",
+    "     infernoflow tracks capability changes automatically via CLAUDE.md",
+    "",
+    "  3. git commit -m 'add my feature'",
+    "     post-commit hook silently updates the changelog",
+    "",
+    "  4. git push && open PR",
+    "     GitHub Actions posts a capability drift analysis comment on the PR",
+    "     pre-push hook warns if drift is HIGH",
+    "",
+    "  5. infernoflow version",
+    "     see what semver bump is recommended (major/minor/patch)",
+    "",
+    "You never run infernoflow manually in day-to-day work.",
+    "It runs itself.",
+  ]);
+
+  await ask_confirm("Got it — continue?", true);
+
+  // ── Step 6: Key commands to know ──────────────────────────────────────────
+  step(6, TOTAL, "Key commands");
+  const commands = [
+    ["infernoflow status",          "Quick health check of the contract"],
+    ["infernoflow diff",            "What changed since the last release"],
+    ["infernoflow version",         "What semver bump to use"],
+    ["infernoflow version --apply", "Write the bump to package.json"],
+    ["infernoflow changelog ai",    "Generate a human-readable changelog"],
+    ["infernoflow dashboard",       "Open the live web dashboard"],
+    ["infernoflow team-sync status","See if your team is in sync"],
+    ["infernoflow suggest 'what I built'", "Manually update the contract"],
+  ];
+
+  const maxLen = Math.max(...commands.map(([c]) => c.length));
+  for (const [cmd, desc] of commands) {
+    console.log(`  ${cyan(cmd.padEnd(maxLen + 2))}${gray(desc)}`);
+  }
+  console.log();
+
+  await ask_confirm("Continue?", true);
+
+  // ── Step 7: Live test ─────────────────────────────────────────────────────
+  step(7, TOTAL, "Quick live test");
+  explain(["Let's run infernoflow status to confirm everything is working."]);
+
+  const runTest = await ask_confirm("Run infernoflow status now?", true);
+  if (runTest) {
+    console.log();
+    try {
+      execSync("npx infernoflow status", { cwd, stdio: "inherit", timeout: 30_000 });
+    } catch {
+      warn("Status check failed — try: infernoflow setup");
+    }
+  }
+
+  // ── Done ──────────────────────────────────────────────────────────────────
+  console.log();
+  console.log(`  ${bold("🎉 You're all set!")}`);
+  console.log();
+  console.log(`  ${green("✔")} infernoflow is installed and running`);
+  console.log(`  ${green("✔")} Claude will auto-track capabilities as you code`);
+  console.log(`  ${green("✔")} Git hooks handle changelog and drift automatically`);
+  console.log(`  ${green("✔")} PRs will get automatic capability analysis`);
+  console.log();
+  console.log(`  ${gray("Share this with teammates:")}  ${cyan("infernoflow onboard")}`);
+  console.log(`  ${gray("Questions?")}  ${cyan("infernoflow --help")}`);
+  console.log();
+
+  if (rl) rl.close();
+}

package/package.json

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