@codewithjuber/forgekit 0.8.0

package/src/embed.js

@@ -0,0 +1,244 @@
+// forge embed — the OPTIONAL embeddings tier (ROADMAP "Next", ADR-0005). MinHash is
+// weak on very short specs (a few words hash to too few shingles — the documented
+// honest limit); a configured embedding provider replaces the lexical `rel` term in
+// Eq. 3 retrieval and the reuse cache's near-match with semantic cosine similarity.
+//
+// ADR-0005 compliance, condition by condition:
+//  1. Core stays stdlib — this file is node stdlib only (spawnSync + the provider's
+//     own process); ledger.js never imports it. MinHash remains the reference path.
+//  2. Graceful absence — no FORGE_EMBED, a crashed provider, a timeout, or garbage
+//     output all yield `null`, and every caller keeps the MinHash path unchanged.
+//  3. Named tiers — `dependencies` stays empty; the provider is an opt-in env config
+//     (`FORGE_EMBED`), not a package at all.
+//  4. Vetting — no third-party code runs unless the USER points FORGE_EMBED at it.
+//
+// Providers (FORGE_EMBED):
+//   cmd:<shell-command>  spawn it, write {"texts":[..]} to stdin, read
+//                        {"vectors":[[..]]} from stdout. The universal escape hatch:
+//                        any local model, any script, any language.
+//   http:<url>           OpenAI-compatible POST {input, model: $FORGE_EMBED_MODEL}
+//                        with Authorization: Bearer $FORGE_EMBED_KEY. The fetch runs
+//                        in a spawned node child (global fetch, node ≥20 stdlib) so
+//                        this module stays synchronous like every other forge stage.
+//                        The key travels only via the child's environment — it is
+//                        never logged, never put in argv.
+import { spawnSync } from "node:child_process";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { contentHash } from "./util.js";
+
+/** Hard ceilings — a misbehaving provider must never hang or flood a forge command. */
+const DEFAULT_TIMEOUT_MS = 15000;
+const MAX_TEXT_CHARS = 4000; // specs/claim texts are short; embed a stable prefix
+const MAX_INPUT_BYTES = 2 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+/** Cache cap — see appendCache for the truncate-oldest policy. */
+export const CACHE_MAX_BYTES = 4 * 1024 * 1024;
+
+export const embedCachePath = (root = process.cwd()) => join(root, ".forge", "embed-cache.jsonl");
+
+// Memoized per env value (not per process) so tests and long-lived callers that flip
+// FORGE_EMBED re-resolve, while hot paths pay the parse once.
+let memo = { env: /** @type {string|undefined} */ (undefined), provider: null };
+
+/**
+ * Resolve the provider from FORGE_EMBED. Unset/unknown scheme → null (callers keep
+ * MinHash — the always-working default).
+ * @returns {{kind:"cmd", cmd:string}|{kind:"http", url:string}|null}
+ */
+export function getProvider() {
+  const env = process.env.FORGE_EMBED ?? "";
+  if (memo.env === env) return memo.provider;
+  /** @type {any} */
+  let provider = null;
+  if (env.startsWith("cmd:") && env.length > 4) provider = { kind: "cmd", cmd: env.slice(4) };
+  else if (/^https?:\/\//.test(env)) provider = { kind: "http", url: env };
+  else if (env.startsWith("http:") && env.length > 5)
+    provider = { kind: "http", url: env.slice(5) };
+  memo = { env, provider };
+  return provider;
+}
+
+/** Cosine similarity in [-1,1]; zero-norm or empty vectors → 0 (never NaN). */
+export function cosine(a, b) {
+  const n = Math.min(a?.length ?? 0, b?.length ?? 0);
+  if (!n) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < n; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}
+
+const isVec = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => Number.isFinite(x));
+
+/** Cache keys include the provider identity + model — switching backends must never
+ *  serve another model's vectors. */
+const providerId = (p) =>
+  `${p.kind}:${p.kind === "cmd" ? p.cmd : p.url}:${process.env.FORGE_EMBED_MODEL ?? ""}`;
+
+/** Corrupt-line-tolerant cache reader (same discipline as metrics.js — a bad line is
+ *  skipped, never fatal). @returns {Map<string, number[]>} */
+function readCache(root) {
+  const out = new Map();
+  const path = embedCachePath(root);
+  if (!existsSync(path)) return out;
+  try {
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line);
+        if (typeof e.k === "string" && isVec(e.v)) out.set(e.k, e.v);
+      } catch {}
+    }
+  } catch {}
+  return out;
+}
+
+/** Append new vectors; when the file outgrows CACHE_MAX_BYTES, rewrite it keeping the
+ *  NEWEST lines that fit in half the cap (truncate-oldest — embeddings are
+ *  re-derivable, so losing an old entry only costs one re-embed, never correctness).
+ *  Best-effort: a cache write failure must never fail the query it was accelerating. */
+function appendCache(root, entries) {
+  if (!entries.length) return;
+  const path = embedCachePath(root);
+  try {
+    mkdirSync(join(root, ".forge"), { recursive: true });
+    appendFileSync(path, `${entries.map((e) => JSON.stringify(e)).join("\n")}\n`);
+    if (statSync(path).size > CACHE_MAX_BYTES) {
+      const lines = readFileSync(path, "utf8").split("\n").filter(Boolean);
+      const keep = [];
+      let bytes = 0;
+      for (let i = lines.length - 1; i >= 0; i--) {
+        bytes += lines[i].length + 1;
+        if (bytes > CACHE_MAX_BYTES / 2) break;
+        keep.unshift(lines[i]);
+      }
+      writeFileSync(path, keep.length ? `${keep.join("\n")}\n` : "");
+    }
+  } catch {}
+}
+
+// Runs in a spawned node child: reads {url, model, texts} from stdin, POSTs the
+// OpenAI-compatible payload, prints {vectors}. The Authorization header is built from
+// the CHILD's env — the key never appears in argv, logs, or error output.
+const HTTP_CHILD = `let raw="";process.stdin.on("data",(d)=>{raw+=d;});process.stdin.on("end",async()=>{try{const{url,model,texts}=JSON.parse(raw);const headers={"content-type":"application/json"};if(process.env.FORGE_EMBED_KEY)headers.authorization="Bearer "+process.env.FORGE_EMBED_KEY;const res=await fetch(url,{method:"POST",headers,body:JSON.stringify(model?{input:texts,model}:{input:texts})});if(!res.ok){console.error("embed: http "+res.status);process.exit(1);}const data=await res.json();process.stdout.write(JSON.stringify({vectors:(data.data??[]).map((d)=>d.embedding)}));}catch(e){console.error("embed: request failed");process.exit(1);}});`;
+
+/** One provider round-trip. Any failure (spawn error, non-zero exit, timeout, bad
+ *  JSON, wrong count, malformed vectors) → null. Never throws, never logs the key. */
+function callProvider(provider, texts) {
+  const timeout = Number(process.env.FORGE_EMBED_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+  const input =
+    provider.kind === "cmd"
+      ? JSON.stringify({ texts })
+      : JSON.stringify({ url: provider.url, model: process.env.FORGE_EMBED_MODEL, texts });
+  if (input.length > MAX_INPUT_BYTES) return null;
+  try {
+    const r =
+      provider.kind === "cmd"
+        ? spawnSync(provider.cmd, {
+            shell: true,
+            input,
+            encoding: "utf8",
+            timeout,
+            maxBuffer: MAX_OUTPUT_BYTES,
+          })
+        : spawnSync(process.execPath, ["-e", HTTP_CHILD], {
+            input,
+            encoding: "utf8",
+            timeout,
+            maxBuffer: MAX_OUTPUT_BYTES,
+          });
+    if (r.error || r.status !== 0 || !r.stdout) return null;
+    const vectors = JSON.parse(r.stdout).vectors;
+    if (!Array.isArray(vectors) || vectors.length !== texts.length) return null;
+    return vectors.map((v) => (isVec(v) ? v : null));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Embed texts through the configured provider, via the content-hash-keyed disk cache
+ * (`.forge/embed-cache.jsonl` under `root`) so repeated retrieval doesn't re-pay the
+ * provider. Returns an array aligned with `texts` where an entry may be null (that
+ * one text couldn't be embedded — per-candidate MinHash fallback), or null overall
+ * when no provider is configured / nothing could be embedded.
+ * @param {string[]} texts
+ * @param {{root?: string}} [opts]
+ * @returns {(number[]|null)[]|null}
+ */
+export function embed(texts, { root = process.cwd() } = {}) {
+  const provider = getProvider();
+  if (!provider || !Array.isArray(texts) || !texts.length) return null;
+  const pid = providerId(provider);
+  const trimmed = texts.map((t) => String(t).slice(0, MAX_TEXT_CHARS));
+  const keys = trimmed.map((t) => contentHash(`${pid}\n${t}`));
+  const cache = readCache(root);
+  const out = keys.map((k) => cache.get(k) ?? null);
+
+  const missIdx = out.flatMap((v, i) => (v === null ? [i] : []));
+  if (missIdx.length) {
+    const missTexts = [...new Set(missIdx.map((i) => trimmed[i]))];
+    const vecs = callProvider(provider, missTexts);
+    if (vecs) {
+      const byText = new Map(missTexts.map((t, i) => [t, vecs[i]]));
+      const fresh = new Map();
+      for (const i of missIdx) {
+        const v = byText.get(trimmed[i]) ?? null;
+        out[i] = v;
+        if (v) fresh.set(keys[i], v);
+      }
+      appendCache(
+        root,
+        [...fresh].map(([k, v]) => ({ k, v })),
+      );
+    }
+  }
+  return out.some(Boolean) ? out : null;
+}
+
+/**
+ * Build the optional `sim` function callers inject into ledger.retrieve/score and
+ * reuse.lookup (those cores stay embed-free). Query + every candidate text go through
+ * ONE embed() call (cache-deduped); the returned sim maps a claim to
+ * cosine(query, claim) or null when that claim's vector is missing (per-candidate
+ * MinHash fallback). Returns null when no provider is configured, the candidate list
+ * is empty, or the query itself couldn't be embedded — the caller's MinHash path is
+ * then byte-for-byte unchanged.
+ * @param {string} root repo root (hosts the disk cache)
+ * @param {string} query
+ * @param {any[]} claims
+ * @param {(claim:any)=>string} textOf
+ * @returns {((query:any, claim:any)=>number|null)|null}
+ */
+export function claimSim(root, query, claims, textOf) {
+  if (!getProvider() || !claims.length) return null;
+  const texts = [String(query), ...claims.map((c) => String(textOf(c)))];
+  const vectors = embed(texts, { root });
+  const qv = vectors?.[0];
+  if (!qv) return null;
+  const byText = new Map();
+  for (let i = 1; i < texts.length; i++) if (vectors[i]) byText.set(texts[i], vectors[i]);
+  return (_query, claim) => {
+    const v = byText.get(String(textOf(claim)));
+    return v ? cosine(qv, v) : null;
+  };
+}
+
+/** The explainability line every query prints: which similarity backend served it. */
+export function simLabel(sim) {
+  const p = getProvider();
+  return sim && p ? `embed(${p.kind})` : "minhash";
+}

package/src/emit/_shared.js

@@ -0,0 +1,39 @@
+// Shared helpers for emitters. Every generated file carries a `forge:sync:<hash>`
+// marker so re-running is idempotent (skip identical content) and drift is
+// detectable (forge doctor compares the marker to the current source hash).
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const MARKER = "forge:sync";
+
+export const hashContent = (str) => createHash("sha256").update(str).digest("hex").slice(0, 12);
+
+export const markerString = (hash) => `${MARKER}:${hash}`;
+
+export const mdHeader = (hash) =>
+  `<!-- GENERATED by \`forge sync\` — edit source/rules.json, not this file. ${markerString(hash)} -->`;
+
+export const yamlHeader = (hash) =>
+  `# GENERATED by \`forge sync\` — edit source/rules.json, not this file. ${markerString(hash)}`;
+
+export const readIfExists = (p) => (existsSync(p) ? readFileSync(p, "utf8") : null);
+
+export const isManaged = (text) => typeof text === "string" && text.includes(`${MARKER}:`);
+
+export function extractHash(text) {
+  const m = typeof text === "string" && text.match(new RegExp(`${MARKER}:([a-f0-9]{12})`));
+  return m ? m[1] : null;
+}
+
+// Write only when the content's marker differs from what's on disk.
+export function writeIfChanged(absPath, content) {
+  const existing = readIfExists(absPath);
+  if (existing !== null && extractHash(existing) === extractHash(content)) return "unchanged";
+  mkdirSync(dirname(absPath), { recursive: true });
+  writeFileSync(absPath, content);
+  return "written";
+}
+
+export const writeManaged = (absPath, header, body) =>
+  writeIfChanged(absPath, `${header}\n${body}\n`);

package/src/emit/aider.js

@@ -0,0 +1,22 @@
+// Aider loads extra context only via `read:` in .aider.conf.yml. Emit a managed
+// conf that reads AGENTS.md; never clobber a user's own unmanaged conf.
+import { join } from "node:path";
+
+export default {
+  tool: "Aider",
+  emit(ctx) {
+    const path = join(ctx.targetRoot, ".aider.conf.yml");
+    const existing = ctx.shared.readIfExists(path);
+    if (existing !== null && !ctx.shared.isManaged(existing)) {
+      return {
+        tool: this.tool,
+        target: ".aider.conf.yml",
+        action: "skipped",
+        note: "existing conf — add `read: AGENTS.md` yourself",
+      };
+    }
+    const body = ["read:", "  - AGENTS.md"].join("\n");
+    const action = ctx.shared.writeManaged(path, ctx.shared.yamlHeader(ctx.hash), body);
+    return { tool: this.tool, target: ".aider.conf.yml", action, note: "read: AGENTS.md" };
+  },
+};

package/src/emit/claude.js

@@ -0,0 +1,44 @@
+// Claude Code reads CLAUDE.md, not AGENTS.md. Emit a thin CLAUDE.md that imports
+// the shared source via @AGENTS.md (first line, Windows-safe). If the repo already has its OWN
+// CLAUDE.md, ADOPT it rather than skip: prepend the one-line @AGENTS.md import (idempotent) so
+// Forge's shared rules actually reach Claude Code, while preserving every line the user wrote.
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const IMPORTS_AGENTS = /^\s*@AGENTS\.md\b/m;
+
+export default {
+  tool: "Claude Code",
+  emit(ctx) {
+    const path = join(ctx.targetRoot, "CLAUDE.md");
+    const existing = ctx.shared.readIfExists(path);
+    // A user's own (unmanaged) CLAUDE.md: adopt it by wiring in the shared import, non-destructively.
+    if (existing !== null && !ctx.shared.isManaged(existing)) {
+      if (IMPORTS_AGENTS.test(existing)) {
+        return {
+          tool: this.tool,
+          target: "CLAUDE.md",
+          action: "unchanged",
+          note: "your CLAUDE.md already imports @AGENTS.md",
+        };
+      }
+      writeFileSync(path, `@AGENTS.md\n\n${existing.replace(/^/, "")}`);
+      return {
+        tool: this.tool,
+        target: "CLAUDE.md",
+        action: "adopted",
+        note: "prepended @AGENTS.md import to your existing CLAUDE.md (content preserved)",
+      };
+    }
+    const content = [
+      "@AGENTS.md",
+      "",
+      ctx.shared.mdHeader(ctx.hash),
+      "",
+      "> Claude reads the shared rules via the import above. Add Claude-only or repo-specific notes below.",
+      "",
+    ].join("\n");
+    const action = ctx.shared.writeIfChanged(path, content);
+    return { tool: this.tool, target: "CLAUDE.md", action, note: "@AGENTS.md import" };
+  },
+};

package/src/emit/codex.js

@@ -0,0 +1,17 @@
+// Codex reads AGENTS.md natively but hard-truncates past 32 KiB (project_doc_max_bytes).
+const CAP = 32 * 1024;
+
+export default {
+  tool: "Codex",
+  emit(ctx) {
+    const over = ctx.bytes > CAP;
+    return {
+      tool: this.tool,
+      target: "AGENTS.md",
+      action: over ? "warn" : "relies-on-agents",
+      note: over
+        ? `${ctx.bytes} B exceeds 32 KiB cap — will truncate`
+        : `native (${ctx.bytes}/${CAP} B)`,
+    };
+  },
+};

package/src/emit/continue.js

@@ -0,0 +1,28 @@
+// Continue does NOT read AGENTS.md — it loads .continue/rules/*.md (verified 2026-07).
+// So emit the canonical rules there, so Continue gets the same single source as
+// every other tool. Never clobber a user's own unmanaged rules file.
+import { join } from "node:path";
+
+export default {
+  tool: "Continue",
+  emit(ctx) {
+    const rel = ".continue/rules/00-forge.md";
+    const path = join(ctx.targetRoot, ".continue", "rules", "00-forge.md");
+    const existing = ctx.shared.readIfExists(path);
+    if (existing !== null && !ctx.shared.isManaged(existing)) {
+      return {
+        tool: this.tool,
+        target: rel,
+        action: "skipped",
+        note: "existing unmanaged rules file",
+      };
+    }
+    const action = ctx.shared.writeManaged(path, ctx.shared.mdHeader(ctx.hash), ctx.canonical);
+    return {
+      tool: this.tool,
+      target: rel,
+      action,
+      note: ".continue/rules/ (no AGENTS.md)",
+    };
+  },
+};

package/src/emit/copilot.js

@@ -0,0 +1,12 @@
+// GitHub Copilot's coding agent reads the root AGENTS.md natively (since 2025-08-28).
+export default {
+  tool: "Copilot",
+  emit(ctx) {
+    return {
+      tool: this.tool,
+      target: "AGENTS.md",
+      action: "relies-on-agents",
+      note: "coding agent reads root AGENTS.md",
+    };
+  },
+};

package/src/emit/cursor.js

@@ -0,0 +1,23 @@
+// Cursor reads AGENTS.md natively; a legacy root .cursorrules can shadow it.
+import { join } from "node:path";
+
+export default {
+  tool: "Cursor",
+  emit(ctx) {
+    const legacy = join(ctx.targetRoot, ".cursorrules");
+    if (ctx.shared.readIfExists(legacy) !== null) {
+      return {
+        tool: this.tool,
+        target: "AGENTS.md",
+        action: "warn",
+        note: "legacy .cursorrules present — remove it so AGENTS.md wins",
+      };
+    }
+    return {
+      tool: this.tool,
+      target: "AGENTS.md",
+      action: "relies-on-agents",
+      note: "native (+ .cursor/rules/*.mdc for scoping)",
+    };
+  },
+};

package/src/emit/gemini.js

@@ -0,0 +1,40 @@
+// Gemini CLI reads GEMINI.md by default and only reads AGENTS.md when
+// settings.json context.fileName lists it. Merge that opt-in without a 2nd copy.
+import { join } from "node:path";
+
+export default {
+  tool: "Gemini CLI",
+  emit(ctx) {
+    const path = join(ctx.targetRoot, ".gemini/settings.json");
+    let settings = {};
+    const existing = ctx.shared.readIfExists(path);
+    if (existing) {
+      try {
+        settings = JSON.parse(existing);
+      } catch {
+        return {
+          tool: this.tool,
+          target: ".gemini/settings.json",
+          action: "skipped",
+          note: "existing settings.json is invalid JSON — left as-is",
+        };
+      }
+    }
+    const context = settings.context || (settings.context = {});
+    const current = Array.isArray(context.fileName)
+      ? context.fileName
+      : context.fileName
+        ? [context.fileName]
+        : [];
+    const had = current.includes("AGENTS.md");
+    context.fileName = [...new Set([...current, "AGENTS.md"])];
+    settings._forge = ctx.shared.markerString(ctx.hash);
+    const action = ctx.shared.writeIfChanged(path, JSON.stringify(settings, null, 2) + "\n");
+    return {
+      tool: this.tool,
+      target: ".gemini/settings.json",
+      action,
+      note: had ? "AGENTS.md already in context.fileName" : "added AGENTS.md to context.fileName",
+    };
+  },
+};

package/src/emit/mcp.js

@@ -0,0 +1,94 @@
+// Emit the canonical MCP server set (source/mcp.json) into each tool's MCP config,
+// in that tool's REAL format (all verified 2026-07). Always MERGE — never clobber a
+// user's own servers. JSON tools differ only by their top-level key; Codex is TOML and
+// Continue is a YAML block file. (Windsurf is global-only — no per-repo file to emit.)
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const JSON_TARGETS = [
+  { tool: "Claude Code", file: ".mcp.json", key: "mcpServers" },
+  { tool: "Cursor", file: ".cursor/mcp.json", key: "mcpServers" },
+  { tool: "Gemini CLI", file: ".gemini/settings.json", key: "mcpServers" },
+  { tool: "Roo Code", file: ".roo/mcp.json", key: "mcpServers" },
+  { tool: "Zed", file: ".zed/settings.json", key: "context_servers" },
+  { tool: "VS Code / Copilot", file: ".vscode/mcp.json", key: "servers" },
+];
+
+function mergeJson(path, key, servers) {
+  let obj = {};
+  if (existsSync(path)) {
+    try {
+      obj = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      return { action: "skipped", note: "invalid JSON — left as-is" };
+    }
+  }
+  const bucket = obj[key] || (obj[key] = {});
+  let added = 0;
+  for (const [name, def] of Object.entries(servers)) {
+    if (!bucket[name]) {
+      bucket[name] = def;
+      added += 1;
+    }
+  }
+  if (!added) return { action: "unchanged", note: "present" };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(obj, null, 2) + "\n");
+  return { action: "written", note: `+${added} server(s)` };
+}
+
+function emitCodexToml(path, servers) {
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  let blocks = "";
+  for (const [name, def] of Object.entries(servers)) {
+    if (existing.includes(`[mcp_servers.${name}]`)) continue;
+    const args = (def.args || []).map((a) => JSON.stringify(a)).join(", ");
+    blocks += `\n[mcp_servers.${name}]\ncommand = ${JSON.stringify(def.command)}\nargs = [${args}]\n`;
+  }
+  if (!blocks) return { action: "unchanged", note: "present" };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, existing + blocks);
+  return { action: "written", note: "TOML block appended" };
+}
+
+function emitContinueYaml(dir, servers) {
+  const path = join(dir, "forge-mcp.yaml");
+  const lines = ["name: Forge MCP", "version: 0.0.1", "schema: v1", "mcpServers:"];
+  for (const [name, def] of Object.entries(servers)) {
+    lines.push(`  - name: ${name}`, "    type: stdio", `    command: ${def.command}`, "    args:");
+    for (const a of def.args || []) lines.push(`      - ${JSON.stringify(a)}`);
+  }
+  const content = lines.join("\n") + "\n";
+  if (existsSync(path) && readFileSync(path, "utf8") === content)
+    return { action: "unchanged", note: "present" };
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path, content);
+  return { action: "written", note: "YAML block file" };
+}
+
+export function emitMcp({ targetRoot, servers }) {
+  const rows = JSON_TARGETS.map((t) => {
+    const r = mergeJson(join(targetRoot, t.file), t.key, servers);
+    return {
+      tool: `${t.tool} MCP`,
+      target: t.file,
+      action: r.action,
+      note: r.note,
+    };
+  });
+  const codex = emitCodexToml(join(targetRoot, ".codex", "config.toml"), servers);
+  rows.push({
+    tool: "Codex MCP",
+    target: ".codex/config.toml",
+    action: codex.action,
+    note: codex.note,
+  });
+  const cont = emitContinueYaml(join(targetRoot, ".continue", "mcpServers"), servers);
+  rows.push({
+    tool: "Continue MCP",
+    target: ".continue/mcpServers/forge-mcp.yaml",
+    action: cont.action,
+    note: cont.note,
+  });
+  return rows;
+}

package/src/emit/windsurf.js

@@ -0,0 +1,22 @@
+// Windsurf/Devin auto-discovers AGENTS.md but caps combined rules at ~12k chars.
+// The rules dir is mid-rebrand (.windsurf -> .devin); detect which exists.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const CHAR_CAP = 12 * 1024;
+
+export default {
+  tool: "Windsurf/Devin",
+  emit(ctx) {
+    const dir = existsSync(join(ctx.targetRoot, ".devin")) ? ".devin" : ".windsurf";
+    const over = ctx.chars > CHAR_CAP;
+    return {
+      tool: this.tool,
+      target: "AGENTS.md",
+      action: over ? "warn" : "relies-on-agents",
+      note: over
+        ? `${ctx.chars} chars exceeds ~12k cap — trim rules`
+        : `native (${dir}; ${ctx.chars} chars)`,
+    };
+  },
+};

package/src/emit/zed.js

@@ -0,0 +1,34 @@
+// Zed uses the FIRST match of a precedence list; several legacy files outrank
+// AGENTS.md. Warn if any of them exist so AGENTS.md actually wins.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const EARLIER = [
+  ".rules",
+  ".cursorrules",
+  ".windsurfrules",
+  ".clinerules",
+  ".github/copilot-instructions.md",
+  "AGENT.md",
+];
+
+export default {
+  tool: "Zed",
+  emit(ctx) {
+    const shadow = EARLIER.filter((f) => existsSync(join(ctx.targetRoot, f)));
+    if (shadow.length) {
+      return {
+        tool: this.tool,
+        target: "AGENTS.md",
+        action: "warn",
+        note: `shadowed by ${shadow.join(", ")} (Zed uses first match)`,
+      };
+    }
+    return {
+      tool: this.tool,
+      target: "AGENTS.md",
+      action: "relies-on-agents",
+      note: "AGENTS.md wins precedence",
+    };
+  },
+};

package/src/eval.js

@@ -0,0 +1,47 @@
+// forge eval — a small, honest evaluation harness for the impact oracle. The Python prototype
+// used mutation testing against a real suite; this ships the deterministic core of that idea so
+// the atlas/impact quality claim is CHECKABLE in CI: for a set of {target → files that truly
+// depend on it} cases, score the oracle's precision/recall/F1 and compare it to the naive
+// "edited-file-only" baseline the paper measured against. Pure; no repo/network.
+import { impact } from "./atlas.js";
+
+/** Pure: precision/recall/F1 of a predicted set against ground truth. */
+export function score(predicted, groundTruth) {
+  const P = new Set(predicted);
+  const G = new Set(groundTruth);
+  let tp = 0;
+  for (const g of G) if (P.has(g)) tp += 1;
+  const precision = P.size ? tp / P.size : G.size ? 0 : 1;
+  const recall = G.size ? tp / G.size : 1;
+  const f1 = precision + recall ? (2 * precision * recall) / (precision + recall) : 0;
+  return { precision, recall, f1, tp, predicted: P.size, groundTruth: G.size };
+}
+
+const mean = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0);
+
+/**
+ * Evaluate the impact oracle over labeled cases and against the edited-file-only baseline.
+ * @param {object} atlas
+ * @param {{target:string, expected:string[], editedFile?:string}[]} cases
+ * @returns {{oracle:{precision:number,recall:number,f1:number}, baseline:{recall:number}, n:number, perCase:object[]}}
+ */
+export function evalImpact(atlas, cases, opts = {}) {
+  const perCase = cases.map((c) => {
+    const predicted = impact(atlas, c.target, opts).impactedFiles;
+    const oracle = score(predicted, c.expected);
+    // Baseline: an agent that only "knows" the file it edited breaks nothing else it can see.
+    const baselineHits = c.editedFile && c.expected.includes(c.editedFile) ? [c.editedFile] : [];
+    const baseline = score(baselineHits, c.expected);
+    return { target: c.target, oracle, baseline };
+  });
+  return {
+    n: cases.length,
+    oracle: {
+      precision: mean(perCase.map((p) => p.oracle.precision)),
+      recall: mean(perCase.map((p) => p.oracle.recall)),
+      f1: mean(perCase.map((p) => p.oracle.f1)),
+    },
+    baseline: { recall: mean(perCase.map((p) => p.baseline.recall)) },
+    perCase,
+  };
+}