@harness-engineering/graph 0.5.0 → 0.6.0

package/dist/index.mjs

@@ -24,7 +24,7 @@ var NODE_TYPES = [
   "build",
   "test_result",
   "execution_outcome",
-  // Observability (future)
+  // Observability — reserved for future tracing/metrics integration
   "span",
   "metric",
   "log",
@@ -71,7 +71,7 @@ var EDGE_TYPES = [
   "triggered_by",
   "failed_in",
   "outcome_of",
-  // Execution relationships (future)
+  // Execution relationships — reserved for future observability integration
   "executed_by",
   "measured_by",
   // Design relationships
@@ -146,7 +146,7 @@ function streamGraphJson(filePath, nodes, edges) {
       stream.write(JSON.stringify(edges[i]));
     }
     stream.write("]}");
-    stream.end(resolve);
+    stream.end(() => resolve());
   });
 }
 async function saveGraph(dirPath, nodes, edges) {
@@ -169,15 +169,19 @@ async function loadGraph(dirPath) {
     await access(metaPath);
     await access(graphPath);
   } catch {
-    return null;
+    return { status: "not_found" };
   }
   const metaContent = await readFile(metaPath, "utf-8");
   const metadata = JSON.parse(metaContent);
   if (metadata.schemaVersion !== CURRENT_SCHEMA_VERSION) {
-    return null;
+    return {
+      status: "schema_mismatch",
+      found: metadata.schemaVersion,
+      expected: CURRENT_SCHEMA_VERSION
+    };
   }
   const graphContent = await readFile(graphPath, "utf-8");
-  return JSON.parse(graphContent);
+  return { status: "loaded", graph: JSON.parse(graphContent) };
 }
 
 // src/store/GraphStore.ts
@@ -352,8 +356,15 @@ var GraphStore = class {
     await saveGraph(dirPath, allNodes, allEdges);
   }
   async load(dirPath) {
-    const data = await loadGraph(dirPath);
-    if (!data) return false;
+    const result = await loadGraph(dirPath);
+    if (result.status === "not_found") return false;
+    if (result.status === "schema_mismatch") {
+      console.warn(
+        `[graph] Schema version mismatch: graph was saved with v${result.found} but current is v${result.expected}. Graph will be rebuilt from scratch. Run \`harness graph scan\` to repopulate.`
+      );
+      return false;
+    }
+    const data = result.graph;
     this.clear();
     for (const node of data.nodes) {
       this.nodeMap.set(node.id, { ...node });
@@ -797,9 +808,10 @@ var CodeIngestor = class {
     let edgesAdded = 0;
     const files = await this.findSourceFiles(rootDir);
     const nameToFiles = /* @__PURE__ */ new Map();
+    const contentCache = /* @__PURE__ */ new Map();
     for (const filePath of files) {
       try {
-        const result = await this.processFile(filePath, rootDir, nameToFiles);
+        const result = await this.processFile(filePath, rootDir, nameToFiles, contentCache);
         nodesAdded += result.nodesAdded;
         edgesAdded += result.edgesAdded;
       } catch (err) {
@@ -809,7 +821,8 @@ var CodeIngestor = class {
     for (const filePath of files) {
       try {
         const relativePath = path.relative(rootDir, filePath).replace(/\\/g, "/");
-        const content = await fs.readFile(filePath, "utf-8");
+        const content = contentCache.get(filePath);
+        if (content === void 0) continue;
         const callsEdges = this.extractCallsEdgesForFile(relativePath, content, nameToFiles);
         for (const edge of callsEdges) {
           this.store.addEdge(edge);
@@ -820,7 +833,8 @@ var CodeIngestor = class {
     }
     for (const filePath of files) {
       try {
-        const content = await fs.readFile(filePath, "utf-8");
+        const content = contentCache.get(filePath);
+        if (content === void 0) continue;
         edgesAdded += this.extractReqAnnotationsForFile(filePath, content, rootDir);
       } catch {
       }
@@ -834,11 +848,12 @@ var CodeIngestor = class {
       durationMs: Date.now() - start
     };
   }
-  async processFile(filePath, rootDir, nameToFiles) {
+  async processFile(filePath, rootDir, nameToFiles, contentCache) {
     let nodesAdded = 0;
     let edgesAdded = 0;
     const relativePath = path.relative(rootDir, filePath).replace(/\\/g, "/");
     const content = await fs.readFile(filePath, "utf-8");
+    contentCache.set(filePath, content);
     const stat2 = await fs.stat(filePath);
     const fileId = `file:${relativePath}`;
     const fileNode = {
@@ -2016,9 +2031,119 @@ function parseFrontmatter(raw) {
   };
 }
 
-// src/ingest/RequirementIngestor.ts
+// src/ingest/DecisionIngestor.ts
 import * as fs4 from "fs/promises";
 import * as path5 from "path";
+var CODE_NODE_TYPES3 = [
+  "file",
+  "function",
+  "class",
+  "method",
+  "interface",
+  "variable"
+];
+var DecisionIngestor = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async ingest(decisionsDir) {
+    const start = Date.now();
+    const errors = [];
+    let files;
+    try {
+      files = await this.findDecisionFiles(decisionsDir);
+    } catch {
+      return emptyResult(Date.now() - start);
+    }
+    let nodesAdded = 0;
+    let edgesAdded = 0;
+    for (const filePath of files) {
+      try {
+        const raw = await fs4.readFile(filePath, "utf-8");
+        const parsed = this.parseFrontmatter(raw);
+        if (!parsed) continue;
+        const { frontmatter, body } = parsed;
+        if (!frontmatter.number || !frontmatter.title) continue;
+        const filename = path5.basename(filePath, ".md");
+        const nodeId = `decision:${filename}`;
+        const node = {
+          id: nodeId,
+          type: "decision",
+          name: frontmatter.title,
+          path: filePath,
+          content: body.trim(),
+          metadata: {
+            number: frontmatter.number,
+            ...frontmatter.date && { date: frontmatter.date },
+            ...frontmatter.status && { status: frontmatter.status },
+            ...frontmatter.tier && { tier: frontmatter.tier },
+            ...frontmatter.source && { source: frontmatter.source },
+            ...frontmatter.supersedes && { supersedes: frontmatter.supersedes }
+          }
+        };
+        this.store.addNode(node);
+        nodesAdded++;
+        edgesAdded += this.linkToCode(body, nodeId);
+      } catch (err) {
+        errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    return {
+      nodesAdded,
+      nodesUpdated: 0,
+      edgesAdded,
+      edgesUpdated: 0,
+      errors,
+      durationMs: Date.now() - start
+    };
+  }
+  parseFrontmatter(raw) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!match) return null;
+    const yamlBlock = match[1];
+    const body = match[2];
+    const frontmatter = {};
+    for (const line of yamlBlock.split("\n")) {
+      const kvMatch = line.match(/^(\w+):\s*(.+)$/);
+      if (!kvMatch) continue;
+      frontmatter[kvMatch[1]] = kvMatch[2].trim();
+    }
+    if (!frontmatter.number || !frontmatter.title) return null;
+    return {
+      frontmatter,
+      body
+    };
+  }
+  linkToCode(content, sourceNodeId) {
+    let count = 0;
+    for (const nodeType of CODE_NODE_TYPES3) {
+      const codeNodes = this.store.findNodes({ type: nodeType });
+      for (const node of codeNodes) {
+        if (node.name.length < 3) continue;
+        const escaped = node.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const namePattern = new RegExp(`\\b${escaped}\\b`, "i");
+        if (namePattern.test(content)) {
+          this.store.addEdge({
+            from: sourceNodeId,
+            to: node.id,
+            type: "decided"
+          });
+          count++;
+        }
+      }
+    }
+    return count;
+  }
+  async findDecisionFiles(dir) {
+    const entries = await fs4.readdir(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isFile() && e.name.endsWith(".md") && e.name !== "README.md").map((e) => path5.join(dir, e.name));
+  }
+};
+
+// src/ingest/RequirementIngestor.ts
+import * as fs5 from "fs/promises";
+import * as path6 from "path";
 var REQUIREMENT_SECTIONS = [
   "Observable Truths",
   "Success Criteria",
@@ -2035,7 +2160,7 @@ function detectEarsPattern(text) {
   if (/^the\s+\w+\s+shall\b/.test(lower)) return "ubiquitous";
   return void 0;
 }
-var CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
+var CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
 var RequirementIngestor = class {
   constructor(store) {
     this.store = store;
@@ -2053,8 +2178,8 @@ var RequirementIngestor = class {
     let edgesAdded = 0;
     let featureDirs;
     try {
-      const entries = await fs4.readdir(specsDir, { withFileTypes: true });
-      featureDirs = entries.filter((e) => e.isDirectory()).map((e) => path5.join(specsDir, e.name));
+      const entries = await fs5.readdir(specsDir, { withFileTypes: true });
+      featureDirs = entries.filter((e) => e.isDirectory()).map((e) => path6.join(specsDir, e.name));
     } catch {
       return emptyResult(Date.now() - start);
     }
@@ -2073,11 +2198,11 @@ var RequirementIngestor = class {
     };
   }
   async ingestFeatureDir(featureDir, errors) {
-    const featureName = path5.basename(featureDir);
-    const specPath = path5.join(featureDir, "proposal.md").replaceAll("\\", "/");
+    const featureName = path6.basename(featureDir);
+    const specPath = path6.join(featureDir, "proposal.md").replaceAll("\\", "/");
     let content;
     try {
-      content = await fs4.readFile(specPath, "utf-8");
+      content = await fs5.readFile(specPath, "utf-8");
     } catch {
       return { nodesAdded: 0, edgesAdded: 0 };
     }
@@ -2094,7 +2219,7 @@ var RequirementIngestor = class {
     this.store.addNode({
       id: specNodeId,
       type: "document",
-      name: path5.basename(specPath),
+      name: path6.basename(specPath),
       path: specPath,
       metadata: { featureName }
     });
@@ -2209,9 +2334,9 @@ var RequirementIngestor = class {
     for (const node of fileNodes) {
       if (!node.path) continue;
       const normalizedPath = node.path.replace(/\\/g, "/");
-      const isCodeMatch = normalizedPath.includes("packages/") && path5.basename(normalizedPath).includes(featureName);
+      const isCodeMatch = normalizedPath.includes("packages/") && path6.basename(normalizedPath).includes(featureName);
       const isTestMatch = normalizedPath.includes("/tests/") && // platform-safe
-      path5.basename(normalizedPath).includes(featureName);
+      path6.basename(normalizedPath).includes(featureName);
       if (isCodeMatch && !isTestMatch) {
         this.store.addEdge({
           from: reqId,
@@ -2240,7 +2365,7 @@ var RequirementIngestor = class {
    */
   linkByKeywordOverlap(reqId, reqText) {
     let count = 0;
-    for (const nodeType of CODE_NODE_TYPES3) {
+    for (const nodeType of CODE_NODE_TYPES4) {
       const codeNodes = this.store.findNodes({ type: nodeType });
       for (const node of codeNodes) {
         if (node.name.length < 3) continue;
@@ -2264,19 +2389,158 @@ var RequirementIngestor = class {
 };
 
 // src/ingest/KnowledgePipelineRunner.ts
-import * as fs9 from "fs/promises";
-import * as path10 from "path";
+import * as fs11 from "fs/promises";
+import * as path12 from "path";
 
 // src/ingest/DiagramParser.ts
-import * as fs5 from "fs/promises";
-import * as path6 from "path";
-function emptyMermaidResult(diagramType = "unknown") {
+import * as fs6 from "fs/promises";
+import * as path7 from "path";
+
+// src/ingest/parsers/mermaid.ts
+function emptyResult2(diagramType = "unknown") {
   return {
     entities: [],
     relationships: [],
     metadata: { format: "mermaid", diagramType }
   };
 }
+function detectDiagramType(content) {
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (/^(?:graph|flowchart)\b/i.test(trimmed)) return "flowchart";
+    if (/^sequenceDiagram\b/.test(trimmed)) return "sequence";
+    if (/^classDiagram\b/.test(trimmed)) return "class";
+    if (/^erDiagram\b/.test(trimmed)) return "er";
+    break;
+  }
+  return "unknown";
+}
+function isDecisionNode(content, nodeId) {
+  const decisionRegex = new RegExp(`${nodeId}\\s*\\{`);
+  return decisionRegex.test(content);
+}
+function buildFlowchartEntity(content, match) {
+  const id = match[1] ?? "";
+  const label = (match[2] ?? "").trim();
+  if (!id) return null;
+  const decision = isDecisionNode(content, id);
+  const entity = {
+    id,
+    label,
+    ...decision ? { type: "decision" } : {}
+  };
+  return { id, entity };
+}
+function extractFlowchartNodes(content) {
+  const entities = /* @__PURE__ */ new Map();
+  const nodeRegex = /([A-Za-z0-9_]+)\s*[[({]([^\])}]+)[\])}]/g;
+  let match = nodeRegex.exec(content);
+  while (match !== null) {
+    const parsed = buildFlowchartEntity(content, match);
+    if (parsed && !entities.has(parsed.id)) {
+      entities.set(parsed.id, parsed.entity);
+    }
+    match = nodeRegex.exec(content);
+  }
+  return entities;
+}
+function parseLabeledEdgeMatch(match) {
+  const from = match[1] ?? "";
+  const label = (match[2] ?? "").trim();
+  const to = match[3] ?? "";
+  if (!from || !to) return null;
+  return { key: `${from}->${to}:${label}`, rel: { from, to, label } };
+}
+function extractLabeledEdges(stripped, edgeKeys) {
+  const relationships = [];
+  const labeledEdgeRegex = /([A-Za-z0-9_]+)\s*--+>?\|([^|]+)\|\s*([A-Za-z0-9_]+)/g;
+  let match = labeledEdgeRegex.exec(stripped);
+  while (match !== null) {
+    const parsed = parseLabeledEdgeMatch(match);
+    if (parsed && !edgeKeys.has(parsed.key)) {
+      edgeKeys.add(parsed.key);
+      relationships.push(parsed.rel);
+    }
+    match = labeledEdgeRegex.exec(stripped);
+  }
+  return relationships;
+}
+function hasLabeledEdgeBetween(labeledEdges, from, to) {
+  return labeledEdges.some((r) => r.from === from && r.to === to);
+}
+function extractUnlabeledEdges(stripped, edgeKeys, labeledEdges) {
+  const relationships = [];
+  const unlabeledEdgeRegex = /([A-Za-z0-9_]+)\s*--+>?\s+([A-Za-z0-9_]+)/g;
+  let match = unlabeledEdgeRegex.exec(stripped);
+  while (match !== null) {
+    const from = match[1] ?? "";
+    const to = match[2] ?? "";
+    const key = `${from}->${to}`;
+    if (from && to && !hasLabeledEdgeBetween(labeledEdges, from, to) && !edgeKeys.has(key)) {
+      edgeKeys.add(key);
+      relationships.push({ from, to });
+    }
+    match = unlabeledEdgeRegex.exec(stripped);
+  }
+  return relationships;
+}
+function parseFlowchart(content, diagramType) {
+  const entities = extractFlowchartNodes(content);
+  const stripped = content.replace(/[[({][^\])}]*[\])}]/g, "");
+  const edgeKeys = /* @__PURE__ */ new Set();
+  const labeledEdges = extractLabeledEdges(stripped, edgeKeys);
+  const unlabeledEdges = extractUnlabeledEdges(stripped, edgeKeys, labeledEdges);
+  return {
+    entities: Array.from(entities.values()),
+    relationships: [...labeledEdges, ...unlabeledEdges],
+    metadata: { format: "mermaid", diagramType }
+  };
+}
+function extractParticipants(content) {
+  const entities = [];
+  const seenParticipants = /* @__PURE__ */ new Set();
+  const participantRegex = /participant\s+(\w+)(?:\s+as\s+(.+))?/g;
+  let match = participantRegex.exec(content);
+  while (match !== null) {
+    const id = match[1] ?? "";
+    const label = match[2]?.trim() || id;
+    if (id && !seenParticipants.has(id)) {
+      seenParticipants.add(id);
+      entities.push({ id, label });
+    }
+    match = participantRegex.exec(content);
+  }
+  return entities;
+}
+function relationshipFromMatch(match) {
+  const from = match[1] ?? "";
+  const to = match[2] ?? "";
+  const label = (match[3] ?? "").trim();
+  return from && to ? { from, to, label } : null;
+}
+function collectMessageMatches(content, regex) {
+  const results = [];
+  let match = regex.exec(content);
+  while (match !== null) {
+    const rel = relationshipFromMatch(match);
+    if (rel) results.push(rel);
+    match = regex.exec(content);
+  }
+  return results;
+}
+function extractMessages(content) {
+  const forward = collectMessageMatches(content, /(\w+)\s*->>?\+?\s*(\w+)\s*:\s*(.+)/g);
+  const returns = collectMessageMatches(content, /(\w+)\s*-->>?-?\s*(\w+)\s*:\s*(.+)/g);
+  return [...forward, ...returns];
+}
+function parseSequence(content, diagramType) {
+  return {
+    entities: extractParticipants(content),
+    relationships: extractMessages(content),
+    metadata: { format: "mermaid", diagramType }
+  };
+}
 var MermaidParser = class {
   canParse(_content, ext) {
     return ext === ".mmd" || ext === ".mermaid";
@@ -2284,269 +2548,199 @@ var MermaidParser = class {
   parse(content, _filePath) {
     const trimmed = content.trim();
     if (!trimmed) {
-      return emptyMermaidResult();
+      return emptyResult2();
     }
-    const diagramType = this.detectDiagramType(trimmed);
+    const diagramType = detectDiagramType(trimmed);
     switch (diagramType) {
       case "flowchart":
-        return this.parseFlowchart(trimmed, diagramType);
+        return parseFlowchart(trimmed, diagramType);
       case "sequence":
-        return this.parseSequence(trimmed, diagramType);
+        return parseSequence(trimmed, diagramType);
       default:
-        return emptyMermaidResult(diagramType);
+        return emptyResult2(diagramType);
     }
   }
-  detectDiagramType(content) {
-    const lines = content.split("\n");
-    for (const line of lines) {
-      const trimmedLine = line.trim();
-      if (!trimmedLine) continue;
-      if (/^(?:graph|flowchart)\b/i.test(trimmedLine)) return "flowchart";
-      if (/^sequenceDiagram\b/.test(trimmedLine)) return "sequence";
-      if (/^classDiagram\b/.test(trimmedLine)) return "class";
-      if (/^erDiagram\b/.test(trimmedLine)) return "er";
-      break;
-    }
-    return "unknown";
+};
+
+// src/ingest/parsers/d2.ts
+function emptyResult3() {
+  return {
+    entities: [],
+    relationships: [],
+    metadata: { format: "d2", diagramType: "architecture" }
+  };
+}
+function parseBlockShape(stripped) {
+  const match = stripped.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.+?)\s*\{$/);
+  if (match) {
+    const id = match[1];
+    const label = match[2];
+    if (id && label) return { id, label };
+  }
+  return null;
+}
+function parseConnection(stripped) {
+  const match = stripped.match(/^([a-zA-Z0-9_.-]+)\s*->\s*([a-zA-Z0-9_.-]+)(?:\s*:\s*(.+?))?$/);
+  if (match) {
+    const from = match[1] ?? "";
+    const to = match[2] ?? "";
+    const label = match[3]?.trim();
+    if (from && to) return { from, to, ...label ? { label } : {} };
+  }
+  return null;
+}
+function parseSimpleShape(stripped) {
+  const match = stripped.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.+)$/);
+  if (match) {
+    const id = match[1];
+    const label = (match[2] ?? "").trim();
+    if (id && label) return { id, label };
+  }
+  return null;
+}
+function handleBlockOpen(stripped, state) {
+  if (state.braceDepth === 0) {
+    const shape = parseBlockShape(stripped);
+    if (shape) state.entities.set(shape.id, { id: shape.id, label: shape.label });
   }
-  parseFlowchart(content, diagramType) {
-    const entities = /* @__PURE__ */ new Map();
-    const relationships = [];
-    const nodeRegex = /([A-Za-z0-9_]+)\s*[[({]([^\])}]+)[\])}]/g;
-    let match;
-    match = nodeRegex.exec(content);
-    while (match !== null) {
-      const id = match[1] ?? "";
-      const label = (match[2] ?? "").trim();
-      if (id && !entities.has(id)) {
-        const isDecision = this.isDecisionNode(content, id);
-        entities.set(id, {
-          id,
-          label,
-          ...isDecision ? { type: "decision" } : {}
-        });
-      }
-      match = nodeRegex.exec(content);
-    }
-    const stripped = content.replace(/[[({][^\])}]*[\])}]/g, "");
-    const labeledEdgeRegex = /([A-Za-z0-9_]+)\s*--+>?\|([^|]+)\|\s*([A-Za-z0-9_]+)/g;
-    const unlabeledEdgeRegex = /([A-Za-z0-9_]+)\s*--+>?\s+([A-Za-z0-9_]+)/g;
-    const edgeKeys = /* @__PURE__ */ new Set();
-    match = labeledEdgeRegex.exec(stripped);
-    while (match !== null) {
-      const from = match[1] ?? "";
-      const label = (match[2] ?? "").trim();
-      const to = match[3] ?? "";
-      if (from && to) {
-        const key = `${from}->${to}:${label}`;
-        if (!edgeKeys.has(key)) {
-          edgeKeys.add(key);
-          relationships.push({ from, to, label });
-        }
-      }
-      match = labeledEdgeRegex.exec(stripped);
-    }
-    match = unlabeledEdgeRegex.exec(stripped);
-    while (match !== null) {
-      const from = match[1] ?? "";
-      const to = match[2] ?? "";
-      if (from && to) {
-        const hasLabeled = relationships.some((r) => r.from === from && r.to === to);
-        if (!hasLabeled) {
-          const key = `${from}->${to}`;
-          if (!edgeKeys.has(key)) {
-            edgeKeys.add(key);
-            relationships.push({ from, to });
-          }
-        }
-      }
-      match = unlabeledEdgeRegex.exec(stripped);
-    }
-    return {
-      entities: Array.from(entities.values()),
-      relationships,
-      metadata: { format: "mermaid", diagramType }
-    };
+  state.braceDepth++;
+}
+function processTopLevelLine(stripped, state) {
+  const conn = parseConnection(stripped);
+  if (conn) {
+    state.relationships.push(conn);
+    return;
   }
-  isDecisionNode(content, nodeId) {
-    const decisionRegex = new RegExp(`${nodeId}\\s*\\{`);
-    return decisionRegex.test(content);
+  const shape = parseSimpleShape(stripped);
+  if (shape && !state.entities.has(shape.id)) {
+    state.entities.set(shape.id, { id: shape.id, label: shape.label });
   }
-  parseSequence(content, diagramType) {
-    const entities = [];
-    const relationships = [];
-    const seenParticipants = /* @__PURE__ */ new Set();
-    const participantRegex = /participant\s+(\w+)(?:\s+as\s+(.+))?/g;
-    let match;
-    match = participantRegex.exec(content);
-    while (match !== null) {
-      const id = match[1] ?? "";
-      const label = match[2]?.trim() || id;
-      if (id && !seenParticipants.has(id)) {
-        seenParticipants.add(id);
-        entities.push({ id, label });
-      }
-      match = participantRegex.exec(content);
-    }
-    const forwardMsgRegex = /(\w+)\s*->>?\+?\s*(\w+)\s*:\s*(.+)/g;
-    match = forwardMsgRegex.exec(content);
-    while (match !== null) {
-      const from = match[1] ?? "";
-      const to = match[2] ?? "";
-      const label = (match[3] ?? "").trim();
-      if (from && to) {
-        relationships.push({ from, to, label });
-      }
-      match = forwardMsgRegex.exec(content);
-    }
-    const returnMsgRegex = /(\w+)\s*-->>?-?\s*(\w+)\s*:\s*(.+)/g;
-    match = returnMsgRegex.exec(content);
-    while (match !== null) {
-      const from = match[1] ?? "";
-      const to = match[2] ?? "";
-      const label = (match[3] ?? "").trim();
-      if (from && to) {
-        relationships.push({ from, to, label });
-      }
-      match = returnMsgRegex.exec(content);
-    }
-    return {
-      entities,
-      relationships,
-      metadata: { format: "mermaid", diagramType }
-    };
+}
+function processD2Line(stripped, state) {
+  if (!stripped || stripped.startsWith("#")) return;
+  if (stripped.endsWith("{")) {
+    handleBlockOpen(stripped, state);
+    return;
   }
-};
+  if (stripped === "}") {
+    state.braceDepth = Math.max(0, state.braceDepth - 1);
+    return;
+  }
+  if (state.braceDepth > 0) return;
+  processTopLevelLine(stripped, state);
+}
 var D2Parser = class {
   canParse(_content, ext) {
     return ext === ".d2";
   }
   parse(content, _filePath) {
     const trimmed = content.trim();
-    if (!trimmed) {
-      return {
-        entities: [],
-        relationships: [],
-        metadata: { format: "d2", diagramType: "architecture" }
-      };
-    }
-    const entities = /* @__PURE__ */ new Map();
-    const relationships = [];
-    let braceDepth = 0;
+    if (!trimmed) return emptyResult3();
+    const state = {
+      entities: /* @__PURE__ */ new Map(),
+      relationships: [],
+      braceDepth: 0
+    };
     for (const line of trimmed.split("\n")) {
-      const stripped = line.trim();
-      if (!stripped || stripped.startsWith("#")) continue;
-      if (stripped.endsWith("{")) {
-        if (braceDepth === 0) {
-          const shapeMatch = stripped.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.+?)\s*\{$/);
-          if (shapeMatch) {
-            const id = shapeMatch[1];
-            const label = shapeMatch[2];
-            if (id && label) {
-              entities.set(id, { id, label });
-            }
-          }
-        }
-        braceDepth++;
-        continue;
-      }
-      if (stripped === "}") {
-        braceDepth = Math.max(0, braceDepth - 1);
-        continue;
-      }
-      if (braceDepth > 0) continue;
-      const connMatch = stripped.match(
-        /^([a-zA-Z0-9_.-]+)\s*->\s*([a-zA-Z0-9_.-]+)(?:\s*:\s*(.+?))?$/
-      );
-      if (connMatch) {
-        const from = connMatch[1] ?? "";
-        const to = connMatch[2] ?? "";
-        const label = connMatch[3]?.trim();
-        if (from && to) {
-          relationships.push({ from, to, ...label ? { label } : {} });
-        }
-        continue;
-      }
-      const simpleMatch = stripped.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.+)$/);
-      if (simpleMatch) {
-        const id = simpleMatch[1];
-        const label = (simpleMatch[2] ?? "").trim();
-        if (id && label && !entities.has(id)) {
-          entities.set(id, { id, label });
-        }
-      }
+      processD2Line(line.trim(), state);
     }
     return {
-      entities: Array.from(entities.values()),
-      relationships,
+      entities: Array.from(state.entities.values()),
+      relationships: state.relationships,
       metadata: { format: "d2", diagramType: "architecture" }
     };
   }
 };
+
+// src/ingest/parsers/plantuml.ts
+function emptyResult4() {
+  return {
+    entities: [],
+    relationships: [],
+    metadata: { format: "plantuml", diagramType: "unknown" }
+  };
+}
+function detectDiagramType2(content) {
+  if (/class\s+\w+/.test(content)) return "class";
+  if (/\[.+\]/.test(content) || /component\s+/.test(content)) return "component";
+  if (/participant\s+/.test(content) || /actor\s+/.test(content)) return "sequence";
+  return "unknown";
+}
+function stripWrappers(content) {
+  return content.replace(/@startuml\b.*\n?/, "").replace(/@enduml\b.*/, "").trim();
+}
+function extractClasses(body, entities) {
+  const classRegex = /class\s+(\w+)/g;
+  let match = classRegex.exec(body);
+  while (match !== null) {
+    const id = match[1] ?? "";
+    if (id && !entities.has(id)) {
+      entities.set(id, { id, label: id });
+    }
+    match = classRegex.exec(body);
+  }
+}
+function extractComponents(body, entities) {
+  const componentRegex = /\[([^\]]+)\]/g;
+  let match = componentRegex.exec(body);
+  while (match !== null) {
+    const label = (match[1] ?? "").trim();
+    if (label) {
+      const id = label.replace(/\s+/g, "_");
+      if (!entities.has(id)) {
+        entities.set(id, { id, label });
+      }
+    }
+    match = componentRegex.exec(body);
+  }
+}
+function parseRelationshipMatch(match) {
+  const from = match[1] ?? "";
+  const to = match[2] ?? "";
+  if (!from || !to) return null;
+  const label = match[3]?.trim();
+  return { from, to, ...label ? { label } : {} };
+}
+function collectRelationshipMatches(body, regex) {
+  const results = [];
+  let match = regex.exec(body);
+  while (match !== null) {
+    const rel = parseRelationshipMatch(match);
+    if (rel) results.push(rel);
+    match = regex.exec(body);
+  }
+  return results;
+}
+function extractRelationships(body) {
+  return collectRelationshipMatches(
+    body,
+    /(\w+)\s*(?:-->|->|<--|<-|\.\.>|--)\s*(\w+)(?:\s*:\s*(.+))?/g
+  );
+}
 var PlantUmlParser = class {
   canParse(_content, ext) {
     return ext === ".puml" || ext === ".plantuml";
   }
   parse(content, _filePath) {
     const trimmed = content.trim();
-    if (!trimmed) {
-      return {
-        entities: [],
-        relationships: [],
-        metadata: { format: "plantuml", diagramType: "unknown" }
-      };
-    }
-    const diagramType = this.detectDiagramType(trimmed);
+    if (!trimmed) return emptyResult4();
+    const diagramType = detectDiagramType2(trimmed);
     const entities = /* @__PURE__ */ new Map();
-    const relationships = [];
-    const body = trimmed.replace(/@startuml\b.*\n?/, "").replace(/@enduml\b.*/, "").trim();
-    const classRegex = /class\s+(\w+)/g;
-    let match;
-    match = classRegex.exec(body);
-    while (match !== null) {
-      const id = match[1] ?? "";
-      if (id && !entities.has(id)) {
-        entities.set(id, { id, label: id });
-      }
-      match = classRegex.exec(body);
-    }
-    const componentRegex1 = /\[([^\]]+)\]/g;
-    match = componentRegex1.exec(body);
-    while (match !== null) {
-      const label = (match[1] ?? "").trim();
-      if (label) {
-        const id = label.replace(/\s+/g, "_");
-        if (!entities.has(id)) {
-          entities.set(id, { id, label });
-        }
-      }
-      match = componentRegex1.exec(body);
-    }
-    const relRegex = /(\w+)\s*(?:-->|->|<--|<-|\.\.>|--)\s*(\w+)(?:\s*:\s*(.+))?/g;
-    match = relRegex.exec(body);
-    while (match !== null) {
-      const from = match[1] ?? "";
-      const to = match[2] ?? "";
-      const label = match[3]?.trim();
-      if (from && to) {
-        relationships.push({ from, to, ...label ? { label } : {} });
-      }
-      match = relRegex.exec(body);
-    }
+    const body = stripWrappers(trimmed);
+    extractClasses(body, entities);
+    extractComponents(body, entities);
+    const relationships = extractRelationships(body);
     return {
       entities: Array.from(entities.values()),
       relationships,
       metadata: { format: "plantuml", diagramType }
     };
   }
-  detectDiagramType(content) {
-    if (/class\s+\w+/.test(content)) return "class";
-    if (/\[.+\]/.test(content) || /component\s+/.test(content)) return "component";
-    if (/participant\s+/.test(content) || /actor\s+/.test(content)) return "sequence";
-    return "unknown";
-  }
 };
+
+// src/ingest/DiagramParser.ts
 var DIAGRAM_EXTENSIONS = /* @__PURE__ */ new Set([".mmd", ".mermaid", ".d2", ".puml", ".plantuml"]);
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".harness"]);
 var DiagramParser = class {
   constructor(store) {
     this.store = store;
@@ -2558,7 +2752,7 @@ var DiagramParser = class {
     new PlantUmlParser()
   ];
   parse(content, filePath) {
-    const ext = path6.extname(filePath).toLowerCase();
+    const ext = path7.extname(filePath).toLowerCase();
     for (const parser of this.parsers) {
       if (parser.canParse(content, ext)) {
         return parser.parse(content, filePath);
@@ -2578,41 +2772,13 @@ var DiagramParser = class {
     const diagramFiles = await this.findDiagramFiles(projectDir);
     for (const filePath of diagramFiles) {
       try {
-        const content = await fs5.readFile(filePath, "utf-8");
-        const relPath = path6.relative(projectDir, filePath).replaceAll("\\", "/");
+        const content = await fs6.readFile(filePath, "utf-8");
+        const relPath = path7.relative(projectDir, filePath).replaceAll("\\", "/");
         const result = this.parse(content, filePath);
         if (result.entities.length === 0) continue;
         const pathHash = hash(relPath);
-        for (const entity of result.entities) {
-          const nodeId = `diagram:${pathHash}:${entity.id}`;
-          this.store.addNode({
-            id: nodeId,
-            type: "business_concept",
-            name: entity.label,
-            path: relPath,
-            metadata: {
-              source: "diagram",
-              format: result.metadata.format,
-              diagramType: result.metadata.diagramType,
-              confidence: 0.85,
-              ...entity.type ? { entityType: entity.type } : {}
-            }
-          });
-          nodesAdded++;
-        }
-        for (const rel of result.relationships) {
-          const fromId = `diagram:${pathHash}:${rel.from}`;
-          const toId = `diagram:${pathHash}:${rel.to}`;
-          this.store.addEdge({
-            from: fromId,
-            to: toId,
-            type: "references",
-            metadata: {
-              ...rel.label ? { label: rel.label } : {}
-            }
-          });
-          edgesAdded++;
-        }
+        nodesAdded += this.addEntityNodes(result, relPath, pathHash);
+        edgesAdded += this.addRelationshipEdges(result, pathHash);
       } catch (err) {
         errors.push(
           `Failed to parse ${filePath}: ${err instanceof Error ? err.message : String(err)}`
@@ -2628,25 +2794,64 @@ var DiagramParser = class {
       durationMs: Date.now() - start
     };
   }
+  /** Map diagram entities to business_concept graph nodes. */
+  addEntityNodes(result, relPath, pathHash) {
+    let count = 0;
+    for (const entity of result.entities) {
+      const nodeId = `diagram:${pathHash}:${entity.id}`;
+      this.store.addNode({
+        id: nodeId,
+        type: "business_concept",
+        name: entity.label,
+        path: relPath,
+        metadata: {
+          source: "diagram",
+          format: result.metadata.format,
+          diagramType: result.metadata.diagramType,
+          confidence: 0.85,
+          ...entity.type ? { entityType: entity.type } : {}
+        }
+      });
+      count++;
+    }
+    return count;
+  }
+  /** Map diagram relationships to references graph edges. */
+  addRelationshipEdges(result, pathHash) {
+    let count = 0;
+    for (const rel of result.relationships) {
+      const fromId = `diagram:${pathHash}:${rel.from}`;
+      const toId = `diagram:${pathHash}:${rel.to}`;
+      this.store.addEdge({
+        from: fromId,
+        to: toId,
+        type: "references",
+        metadata: {
+          ...rel.label ? { label: rel.label } : {}
+        }
+      });
+      count++;
+    }
+    return count;
+  }
   async findDiagramFiles(dir) {
     const files = [];
-    const SKIP_DIRS2 = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".harness"]);
     const walk = async (currentDir) => {
       let entries;
       try {
-        entries = await fs5.readdir(currentDir, { withFileTypes: true });
+        entries = await fs6.readdir(currentDir, { withFileTypes: true });
       } catch {
         return;
       }
       for (const entry of entries) {
         if (entry.isDirectory()) {
-          if (!SKIP_DIRS2.has(entry.name)) {
-            await walk(path6.join(currentDir, entry.name));
+          if (!SKIP_DIRS.has(entry.name)) {
+            await walk(path7.join(currentDir, entry.name));
           }
         } else if (entry.isFile()) {
-          const ext = path6.extname(entry.name).toLowerCase();
+          const ext = path7.extname(entry.name).toLowerCase();
           if (DIAGRAM_EXTENSIONS.has(ext)) {
-            files.push(path6.join(currentDir, entry.name));
+            files.push(path7.join(currentDir, entry.name));
           }
         }
       }
@@ -2657,8 +2862,8 @@ var DiagramParser = class {
 };
 
 // src/ingest/KnowledgeLinker.ts
-import * as fs6 from "fs/promises";
-import * as path7 from "path";
+import * as fs7 from "fs/promises";
+import * as path8 from "path";
 var HEURISTIC_PATTERNS = [
   {
     name: "business-rule-imperative",
@@ -2805,8 +3010,10 @@ var KnowledgeLinker = class {
     if (!duplicate) return false;
     const existingSources = duplicate.metadata.sources ?? [];
     if (!existingSources.includes(candidate.sourceNodeId)) {
-      existingSources.push(candidate.sourceNodeId);
-      duplicate.metadata.sources = existingSources;
+      this.store.addNode({
+        ...duplicate,
+        metadata: { ...duplicate.metadata, sources: [...existingSources, candidate.sourceNodeId] }
+      });
     }
     return true;
   }
@@ -2840,8 +3047,8 @@ var KnowledgeLinker = class {
    */
   async writeJsonl(candidates) {
     if (!this.outputDir) return;
-    await fs6.mkdir(this.outputDir, { recursive: true });
-    const filePath = path7.join(this.outputDir, "linker.jsonl");
+    await fs7.mkdir(this.outputDir, { recursive: true });
+    const filePath = path8.join(this.outputDir, "linker.jsonl");
     const lines = candidates.map(
       (c) => JSON.stringify({
         id: c.id,
@@ -2854,16 +3061,16 @@ var KnowledgeLinker = class {
         nodeType: c.nodeType
       })
     );
-    await fs6.writeFile(filePath, lines.join("\n") + (lines.length > 0 ? "\n" : ""));
+    await fs7.writeFile(filePath, lines.join("\n") + (lines.length > 0 ? "\n" : ""));
   }
   /**
    * Write medium-confidence candidates to staged JSONL for human review.
    */
   async writeStagedJsonl(candidates) {
     if (!this.outputDir || candidates.length === 0) return;
-    const stagedDir = path7.join(this.outputDir, "staged");
-    await fs6.mkdir(stagedDir, { recursive: true });
-    const filePath = path7.join(stagedDir, "linker-staged.jsonl");
+    const stagedDir = path8.join(this.outputDir, "staged");
+    await fs7.mkdir(stagedDir, { recursive: true });
+    const filePath = path8.join(stagedDir, "linker-staged.jsonl");
     const lines = candidates.map(
       (c) => JSON.stringify({
         id: c.id,
@@ -2876,7 +3083,7 @@ var KnowledgeLinker = class {
         nodeType: c.nodeType
       })
     );
-    await fs6.writeFile(filePath, lines.join("\n") + "\n");
+    await fs7.writeFile(filePath, lines.join("\n") + "\n");
   }
   /**
    * Apply heuristic patterns to content and return candidate extractions.
@@ -2982,8 +3189,16 @@ var StructuralDriftDetector = class {
 };
 
 // src/ingest/KnowledgeStagingAggregator.ts
-import * as fs7 from "fs/promises";
-import * as path8 from "path";
+import * as fs8 from "fs/promises";
+import * as path9 from "path";
+var BUSINESS_NODE_TYPES = [
+  "business_concept",
+  "business_rule",
+  "business_process",
+  "business_term",
+  "business_metric",
+  "business_fact"
+];
 var KnowledgeStagingAggregator = class {
   constructor(projectDir) {
     this.projectDir = projectDir;
@@ -3002,59 +3217,157 @@ var KnowledgeStagingAggregator = class {
     if (deduplicated.length === 0) {
       return { staged: 0 };
     }
-    const stagedDir = path8.join(this.projectDir, ".harness", "knowledge", "staged");
-    await fs7.mkdir(stagedDir, { recursive: true });
+    const stagedDir = path9.join(this.projectDir, ".harness", "knowledge", "staged");
+    await fs8.mkdir(stagedDir, { recursive: true });
     const jsonl = deduplicated.map((entry) => JSON.stringify(entry)).join("\n") + "\n";
-    await fs7.writeFile(path8.join(stagedDir, "pipeline-staged.jsonl"), jsonl, "utf-8");
+    await fs8.writeFile(path9.join(stagedDir, "pipeline-staged.jsonl"), jsonl, "utf-8");
     return { staged: deduplicated.length };
   }
-  async generateGapReport(knowledgeDir) {
-    const domains = [];
+  async extractDocName(filePath) {
+    const raw = await fs8.readFile(filePath, "utf-8");
+    const fmMatch = raw.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+    const body = fmMatch ? fmMatch[1] : raw;
+    const titleMatch = body.match(/^#\s+(.+)$/m);
+    return titleMatch ? titleMatch[1].trim() : path9.basename(filePath, ".md");
+  }
+  async generateGapReport(knowledgeDir, store) {
+    const domainDocNames = /* @__PURE__ */ new Map();
+    const domainEntryCounts = /* @__PURE__ */ new Map();
     let totalEntries = 0;
     try {
-      const entries = await fs7.readdir(knowledgeDir, { withFileTypes: true });
+      const entries = await fs8.readdir(knowledgeDir, { withFileTypes: true });
       const domainDirs = entries.filter((e) => e.isDirectory());
       for (const dir of domainDirs) {
-        const domainPath = path8.join(knowledgeDir, dir.name);
-        const files = await fs7.readdir(domainPath);
+        const domainPath = path9.join(knowledgeDir, dir.name);
+        const files = await fs8.readdir(domainPath);
         const mdFiles = files.filter((f) => f.endsWith(".md"));
         const entryCount = mdFiles.length;
         totalEntries += entryCount;
-        domains.push({ domain: dir.name, entryCount });
+        domainEntryCounts.set(dir.name, entryCount);
+        if (store) {
+          const names = [];
+          for (const file of mdFiles) {
+            const name = await this.extractDocName(path9.join(domainPath, file));
+            names.push(name.toLowerCase().trim());
+          }
+          domainDocNames.set(dir.name, names);
+        }
       }
     } catch {
     }
+    if (!store) {
+      const domains2 = [];
+      for (const [domain, entryCount] of domainEntryCounts) {
+        domains2.push({ domain, entryCount, extractedCount: 0, gapCount: 0, gapEntries: [] });
+      }
+      return {
+        domains: domains2,
+        totalEntries,
+        totalExtracted: 0,
+        totalGaps: 0,
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+    const extractedByDomain = /* @__PURE__ */ new Map();
+    for (const nodeType of BUSINESS_NODE_TYPES) {
+      const nodes = store.findNodes({ type: nodeType });
+      for (const node of nodes) {
+        const domain = node.metadata?.domain ?? "unknown";
+        const list = extractedByDomain.get(domain) ?? [];
+        list.push(node);
+        extractedByDomain.set(domain, list);
+      }
+    }
+    for (const [domain, nodes] of extractedByDomain) {
+      const seen = /* @__PURE__ */ new Set();
+      const deduped = nodes.filter((n) => {
+        const key = n.name.toLowerCase().trim();
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+      extractedByDomain.set(domain, deduped);
+    }
+    const allDomains = /* @__PURE__ */ new Set([...domainEntryCounts.keys(), ...extractedByDomain.keys()]);
+    const domains = [];
+    let totalExtracted = 0;
+    let totalGaps = 0;
+    for (const domain of allDomains) {
+      const entryCount = domainEntryCounts.get(domain) ?? 0;
+      const extractedNodes = extractedByDomain.get(domain) ?? [];
+      const extractedCount = extractedNodes.length;
+      totalExtracted += extractedCount;
+      const docNames = domainDocNames.get(domain) ?? [];
+      const gapEntries = [];
+      for (const node of extractedNodes) {
+        const normalizedName = node.name.toLowerCase().trim();
+        if (!docNames.includes(normalizedName)) {
+          gapEntries.push({
+            nodeId: node.id,
+            name: node.name,
+            nodeType: node.type,
+            source: node.metadata?.source ?? "unknown",
+            hasContent: Boolean(node.content && node.content.trim().length >= 10)
+          });
+        }
+      }
+      totalGaps += gapEntries.length;
+      domains.push({ domain, entryCount, extractedCount, gapCount: gapEntries.length, gapEntries });
+    }
     return {
       domains,
       totalEntries,
+      totalExtracted,
+      totalGaps,
       generatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   }
   async writeGapReport(report) {
-    const gapsDir = path8.join(this.projectDir, ".harness", "knowledge");
-    await fs7.mkdir(gapsDir, { recursive: true });
+    const gapsDir = path9.join(this.projectDir, ".harness", "knowledge");
+    await fs8.mkdir(gapsDir, { recursive: true });
+    const hasDifferential = report.totalExtracted > 0;
     const lines = [
       "# Knowledge Gaps Report",
       "",
       `Generated: ${report.generatedAt}`,
       "",
       "## Coverage by Domain",
-      "",
-      "| Domain | Entries |",
-      "| ------ | ------- |"
+      ""
     ];
-    for (const domain of report.domains) {
-      lines.push(`| ${domain.domain} | ${domain.entryCount} |`);
+    if (hasDifferential) {
+      lines.push(
+        "| Domain | Documented | Extracted | Gaps |",
+        "| ------ | ---------- | --------- | ---- |"
+      );
+      for (const domain of report.domains) {
+        lines.push(
+          `| ${domain.domain} | ${domain.entryCount} | ${domain.extractedCount} | ${domain.gapCount} |`
+        );
+      }
+      lines.push(
+        "",
+        `## Summary`,
+        "",
+        `- **Total Documented:** ${report.totalEntries}`,
+        `- **Total Extracted:** ${report.totalExtracted}`,
+        `- **Total Gaps:** ${report.totalGaps}`,
+        ""
+      );
+    } else {
+      lines.push("| Domain | Entries |", "| ------ | ------- |");
+      for (const domain of report.domains) {
+        lines.push(`| ${domain.domain} | ${domain.entryCount} |`);
+      }
+      lines.push("", `## Total Entries: ${report.totalEntries}`, "");
     }
-    lines.push("", `## Total Entries: ${report.totalEntries}`, "");
-    await fs7.writeFile(path8.join(gapsDir, "gaps.md"), lines.join("\n"), "utf-8");
+    await fs8.writeFile(path9.join(gapsDir, "gaps.md"), lines.join("\n"), "utf-8");
   }
 };
 
 // src/ingest/extractors/ExtractionRunner.ts
-import * as fs8 from "fs/promises";
-import * as path9 from "path";
-var SKIP_DIRS = /* @__PURE__ */ new Set([
+import * as fs9 from "fs/promises";
+import * as path10 from "path";
+var SKIP_DIRS2 = /* @__PURE__ */ new Set([
   "node_modules",
   "dist",
   "target",
@@ -3091,11 +3404,11 @@ var EXT_TO_LANGUAGE = {
 };
 var SKIP_EXTENSIONS2 = /* @__PURE__ */ new Set([".d.ts"]);
 function detectLanguage(filePath) {
-  const name = path9.basename(filePath);
+  const name = path10.basename(filePath);
   for (const skip of SKIP_EXTENSIONS2) {
     if (name.endsWith(skip)) return void 0;
   }
-  const ext = path9.extname(filePath);
+  const ext = path10.extname(filePath);
   return EXT_TO_LANGUAGE[ext];
 }
 var EXTRACTOR_EDGE_TYPE = {
@@ -3121,7 +3434,7 @@ var ExtractionRunner = class {
     let nodesAdded = 0;
     let nodesUpdated = 0;
     let edgesAdded = 0;
-    await fs8.mkdir(outputDir, { recursive: true });
+    await fs9.mkdir(outputDir, { recursive: true });
     const files = await this.findSourceFiles(projectDir);
     const recordsByExtractor = /* @__PURE__ */ new Map();
     for (const ext of this.extractors) {
@@ -3130,17 +3443,17 @@ var ExtractionRunner = class {
     for (const filePath of files) {
       const language = detectLanguage(filePath);
       if (!language) continue;
-      const ext = path9.extname(filePath);
+      const ext = path10.extname(filePath);
       let content;
       try {
-        content = await fs8.readFile(filePath, "utf-8");
+        content = await fs9.readFile(filePath, "utf-8");
       } catch (err) {
         errors.push(
           `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`
         );
         continue;
       }
-      const relativePath = path9.relative(projectDir, filePath).replaceAll("\\", "/");
+      const relativePath = path10.relative(projectDir, filePath).replaceAll("\\", "/");
       for (const extractor2 of this.extractors) {
         if (!extractor2.supportedExtensions.includes(ext)) continue;
         try {
@@ -3177,9 +3490,9 @@ var ExtractionRunner = class {
   }
   /** Write extraction records to JSONL file. */
   async writeJsonl(records, outputDir, extractorName) {
-    const filePath = path9.join(outputDir, `${extractorName}.jsonl`);
+    const filePath = path10.join(outputDir, `${extractorName}.jsonl`);
     const lines = records.map((r) => JSON.stringify(r));
-    await fs8.writeFile(filePath, lines.join("\n") + (lines.length > 0 ? "\n" : ""));
+    await fs9.writeFile(filePath, lines.join("\n") + (lines.length > 0 ? "\n" : ""));
   }
   /** Create or update a graph node from an extraction record. */
   persistRecord(record, store) {
@@ -3251,13 +3564,13 @@ var ExtractionRunner = class {
     const results = [];
     let entries;
     try {
-      entries = await fs8.readdir(dir, { withFileTypes: true });
+      entries = await fs9.readdir(dir, { withFileTypes: true });
     } catch {
       return results;
     }
     for (const entry of entries) {
-      const fullPath = path9.join(dir, entry.name);
-      if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      const fullPath = path10.join(dir, entry.name);
+      if (entry.isDirectory() && !SKIP_DIRS2.has(entry.name)) {
         results.push(...await this.findSourceFiles(fullPath));
       } else if (entry.isFile() && detectLanguage(fullPath) !== void 0) {
         results.push(fullPath);
@@ -4383,57 +4696,9 @@ var ImageAnalysisExtractor = class {
     const errors = [];
     for (const imagePath of imagePaths) {
       try {
-        const response = await this.provider.analyze({
-          prompt: "Analyze this image and provide a structured description of its visual contents.",
-          systemPrompt: "You are an image analysis assistant. Describe the image contents, detect UI elements, extract visible text, identify design patterns, and note accessibility concerns.",
-          responseSchema: {},
-          // Schema handled by provider
-          maxTokens: 1e3
-        });
-        const result = response.result;
-        const pathHash = hash(imagePath);
-        const annotationId = `img:${pathHash}`;
-        store.addNode({
-          id: annotationId,
-          type: "image_annotation",
-          name: result.description.slice(0, 200),
-          path: imagePath,
-          content: result.description,
-          hash: hash(result.description),
-          metadata: {
-            source: "image-analysis",
-            detectedElements: result.detectedElements,
-            extractedText: result.extractedText,
-            designPatterns: result.designPatterns,
-            accessibilityNotes: result.accessibilityNotes,
-            model: response.model
-          }
-        });
-        nodesAdded++;
-        const fileNodes = store.findNodes({ type: "file" });
-        const fileNode = fileNodes.find((n) => n.path === imagePath);
-        if (fileNode) {
-          store.addEdge({ from: annotationId, to: fileNode.id, type: "annotates" });
-          edgesAdded++;
-        }
-        for (const pattern of result.designPatterns) {
-          const conceptId = `img:concept:${hash(pattern + imagePath)}`;
-          store.addNode({
-            id: conceptId,
-            type: "business_concept",
-            name: pattern,
-            content: `Design pattern detected in ${imagePath}: ${pattern}`,
-            hash: hash(pattern),
-            metadata: {
-              source: "image-analysis",
-              sourceImage: imagePath,
-              domain: "design"
-            }
-          });
-          nodesAdded++;
-          store.addEdge({ from: annotationId, to: conceptId, type: "contains" });
-          edgesAdded++;
-        }
+        const counts = await this.processImage(store, imagePath);
+        nodesAdded += counts.nodes;
+        edgesAdded += counts.edges;
       } catch (err) {
         errors.push(
           `Image analysis failed for ${imagePath}: ${err instanceof Error ? err.message : String(err)}`
@@ -4449,6 +4714,68 @@ var ImageAnalysisExtractor = class {
       durationMs: Date.now() - start
     };
   }
+  /** Analyze a single image and add annotation + concept nodes to the store. */
+  async processImage(store, imagePath) {
+    const response = await this.provider.analyze({
+      prompt: "Analyze this image and provide a structured description of its visual contents.",
+      systemPrompt: "You are an image analysis assistant. Describe the image contents, detect UI elements, extract visible text, identify design patterns, and note accessibility concerns.",
+      responseSchema: {},
+      // Schema handled by provider
+      maxTokens: 1e3
+    });
+    const result = response.result;
+    const annotationId = `img:${hash(imagePath)}`;
+    let nodes = 0;
+    let edges = 0;
+    store.addNode({
+      id: annotationId,
+      type: "image_annotation",
+      name: result.description.slice(0, 200),
+      path: imagePath,
+      content: result.description,
+      hash: hash(result.description),
+      metadata: {
+        source: "image-analysis",
+        detectedElements: result.detectedElements,
+        extractedText: result.extractedText,
+        designPatterns: result.designPatterns,
+        accessibilityNotes: result.accessibilityNotes,
+        model: response.model
+      }
+    });
+    nodes++;
+    edges += this.linkToFileNode(store, annotationId, imagePath);
+    for (const pattern of result.designPatterns) {
+      edges += this.addDesignPatternConcept(store, annotationId, imagePath, pattern);
+      nodes++;
+    }
+    return { nodes, edges };
+  }
+  /** Link annotation to its source file node if it exists. Returns 1 if linked, 0 otherwise. */
+  linkToFileNode(store, annotationId, imagePath) {
+    const fileNode = store.findNodes({ type: "file" }).find((n) => n.path === imagePath);
+    if (!fileNode) return 0;
+    store.addEdge({ from: annotationId, to: fileNode.id, type: "annotates" });
+    return 1;
+  }
+  /** Create a business_concept node for a design pattern and link it. Returns edges added. */
+  addDesignPatternConcept(store, annotationId, imagePath, pattern) {
+    const conceptId = `img:concept:${hash(pattern + imagePath)}`;
+    store.addNode({
+      id: conceptId,
+      type: "business_concept",
+      name: pattern,
+      content: `Design pattern detected in ${imagePath}: ${pattern}`,
+      hash: hash(pattern),
+      metadata: {
+        source: "image-analysis",
+        sourceImage: imagePath,
+        domain: "design"
+      }
+    });
+    store.addEdge({ from: annotationId, to: conceptId, type: "contains" });
+    return 1;
+  }
 };
 
 // src/ingest/knowledgeTypes.ts
@@ -4459,6 +4786,7 @@ var KNOWLEDGE_NODE_TYPES = [
   "business_term",
   "business_concept",
   "business_metric",
+  "decision",
   "design_token",
   "design_constraint",
   "aesthetic_intent",
@@ -4499,83 +4827,99 @@ function classifyConflict(a, b) {
     return "temporal_conflict";
   return "status_divergence";
 }
-var ContradictionDetector = class {
-  detect(store) {
-    const nodes = KNOWLEDGE_NODE_TYPES.flatMap((t) => store.findNodes({ type: t }));
-    const byName = /* @__PURE__ */ new Map();
-    for (const node of nodes) {
-      const key = node.name.toLowerCase().trim();
-      const group = byName.get(key) ?? [];
-      group.push(node);
-      byName.set(key, group);
-    }
-    const contradictions = [];
-    const sourcePairCounts = {};
-    const seen = /* @__PURE__ */ new Set();
-    const addContradiction = (a, b, similarity) => {
-      const sourceA = a.metadata.source ?? "unknown";
-      const sourceB = b.metadata.source ?? "unknown";
-      if (sourceA === sourceB) return;
-      const hashA = a.hash ?? a.id;
-      const hashB = b.hash ?? b.id;
-      if (hashA === hashB) return;
-      const pairId = [a.id, b.id].sort().join(":");
-      if (seen.has(pairId)) return;
-      seen.add(pairId);
-      const conflictType = classifyConflict(a, b);
-      const severity = conflictType === "value_mismatch" ? "critical" : conflictType === "definition_conflict" ? "high" : "medium";
-      const pairKey = [sourceA, sourceB].sort().join("\u2194");
-      sourcePairCounts[pairKey] = (sourcePairCounts[pairKey] ?? 0) + 1;
-      contradictions.push({
-        id: `contradiction:${a.id}:${b.id}`,
-        entityA: {
-          nodeId: a.id,
-          source: sourceA,
-          name: a.name,
-          content: a.content ?? "",
-          lastModified: a.lastModified
-        },
-        entityB: {
-          nodeId: b.id,
-          source: sourceB,
-          name: b.name,
-          content: b.content ?? "",
-          lastModified: b.lastModified
-        },
-        similarity,
-        conflictType,
-        severity,
-        description: `"${a.name}" has conflicting definitions from ${sourceA} and ${sourceB}`
-      });
-    };
-    for (const [, group] of byName) {
-      if (group.length < 2) continue;
-      for (let i = 0; i < group.length; i++) {
-        for (let j = i + 1; j < group.length; j++) {
-          addContradiction(group[i], group[j], 1);
-        }
+var SEVERITY_MAP = {
+  value_mismatch: "critical",
+  definition_conflict: "high",
+  status_divergence: "medium",
+  temporal_conflict: "medium"
+};
+function buildEntry(node, source) {
+  return {
+    nodeId: node.id,
+    source,
+    name: node.name,
+    content: node.content ?? "",
+    lastModified: node.lastModified
+  };
+}
+function groupByName(nodes) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const key = node.name.toLowerCase().trim();
+    const group = byName.get(key) ?? [];
+    group.push(node);
+    byName.set(key, group);
+  }
+  return byName;
+}
+function tryAddContradiction(acc, a, b, similarity) {
+  const sourceA = a.metadata.source ?? "unknown";
+  const sourceB = b.metadata.source ?? "unknown";
+  if (sourceA === sourceB) return;
+  if ((a.hash ?? a.id) === (b.hash ?? b.id)) return;
+  const pairId = [a.id, b.id].sort().join(":");
+  if (acc.seen.has(pairId)) return;
+  acc.seen.add(pairId);
+  const conflictType = classifyConflict(a, b);
+  const pairKey = [sourceA, sourceB].sort().join("\u2194");
+  acc.sourcePairCounts[pairKey] = (acc.sourcePairCounts[pairKey] ?? 0) + 1;
+  acc.contradictions.push({
+    id: `contradiction:${a.id}:${b.id}`,
+    entityA: buildEntry(a, sourceA),
+    entityB: buildEntry(b, sourceB),
+    similarity,
+    conflictType,
+    severity: SEVERITY_MAP[conflictType],
+    description: `"${a.name}" has conflicting definitions from ${sourceA} and ${sourceB}`
+  });
+}
+function collectExactMatches(byName, acc) {
+  for (const [, group] of byName) {
+    if (group.length < 2) continue;
+    for (let i = 0; i < group.length; i++) {
+      for (let j = i + 1; j < group.length; j++) {
+        tryAddContradiction(acc, group[i], group[j], 1);
       }
     }
-    const keys = [...byName.keys()];
-    for (let i = 0; i < keys.length; i++) {
-      for (let j = i + 1; j < keys.length; j++) {
-        const keyA = keys[i];
-        const keyB = keys[j];
-        const maxLen = Math.max(keyA.length, keyB.length);
-        const minLen = Math.min(keyA.length, keyB.length);
-        if (minLen / maxLen < SIMILARITY_THRESHOLD) continue;
-        const ratio = levenshteinRatio(keyA, keyB);
-        if (ratio < SIMILARITY_THRESHOLD) continue;
-        const groupA = byName.get(keyA);
-        const groupB = byName.get(keyB);
-        for (const a of groupA) {
-          for (const b of groupB) {
-            addContradiction(a, b, ratio);
-          }
+  }
+}
+function collectFuzzyMatches(byName, acc) {
+  const keys = [...byName.keys()];
+  for (let i = 0; i < keys.length; i++) {
+    for (let j = i + 1; j < keys.length; j++) {
+      const keyA = keys[i];
+      const keyB = keys[j];
+      const maxLen = Math.max(keyA.length, keyB.length);
+      const minLen = Math.min(keyA.length, keyB.length);
+      if (minLen / maxLen < SIMILARITY_THRESHOLD) continue;
+      const ratio = levenshteinRatio(keyA, keyB);
+      if (ratio < SIMILARITY_THRESHOLD) continue;
+      const groupA = byName.get(keyA);
+      const groupB = byName.get(keyB);
+      for (const a of groupA) {
+        for (const b of groupB) {
+          tryAddContradiction(acc, a, b, ratio);
         }
       }
     }
-    return { contradictions, sourcePairCounts, totalChecked: nodes.length };
+  }
+}
+var ContradictionDetector = class {
+  detect(store) {
+    const nodes = KNOWLEDGE_NODE_TYPES.flatMap((t) => store.findNodes({ type: t }));
+    const byName = groupByName(nodes);
+    const acc = {
+      contradictions: [],
+      sourcePairCounts: {},
+      seen: /* @__PURE__ */ new Set()
+    };
+    collectExactMatches(byName, acc);
+    collectFuzzyMatches(byName, acc);
+    return {
+      contradictions: acc.contradictions,
+      sourcePairCounts: acc.sourcePairCounts,
+      totalChecked: nodes.length
+    };
   }
 };
 
@@ -4606,64 +4950,76 @@ function toGrade(score) {
   if (score >= 20) return "D";
   return "F";
 }
+function groupByDomain(nodes, fallback) {
+  const map = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const domain = node.metadata.domain ?? fallback(node);
+    const group = map.get(domain) ?? [];
+    group.push(node);
+    map.set(domain, group);
+  }
+  return map;
+}
+function countLinkedEntities(codeEntries, store) {
+  const linkedIds = /* @__PURE__ */ new Set();
+  for (const codeNode of codeEntries) {
+    if (hasKnowledgeEdge(codeNode.id, store)) {
+      linkedIds.add(codeNode.id);
+    }
+  }
+  return linkedIds;
+}
+function hasKnowledgeEdge(nodeId, store) {
+  for (const edgeType of KNOWLEDGE_EDGE_TYPES) {
+    if (store.getEdges({ to: nodeId, type: edgeType }).length > 0) return true;
+  }
+  return false;
+}
+function computeSourceBreakdown(knEntries) {
+  const breakdown = {};
+  for (const kn of knEntries) {
+    const src = kn.metadata.source ?? "unknown";
+    breakdown[src] = (breakdown[src] ?? 0) + 1;
+  }
+  return breakdown;
+}
+function computeDomainScore(knowledgeEntries, codeEntities, linkedEntities, uniqueSources) {
+  const codeCoverageComponent = codeEntities > 0 ? linkedEntities / codeEntities * 60 : 0;
+  const knowledgeDepthComponent = Math.min(knowledgeEntries / 10, 1) * 20;
+  const sourceDiversityComponent = Math.min(uniqueSources / 3, 1) * 20;
+  return Math.round(codeCoverageComponent + knowledgeDepthComponent + sourceDiversityComponent);
+}
+function scoreDomain(domain, knEntries, codeEntries, store) {
+  const linkedIds = countLinkedEntities(codeEntries, store);
+  const sourceBreakdown = computeSourceBreakdown(knEntries);
+  const codeEntities = codeEntries.length;
+  const linkedEntities = linkedIds.size;
+  const knowledgeEntries = knEntries.length;
+  const uniqueSources = Object.keys(sourceBreakdown).length;
+  const score = computeDomainScore(knowledgeEntries, codeEntities, linkedEntities, uniqueSources);
+  return {
+    domain,
+    score,
+    knowledgeEntries,
+    codeEntities,
+    linkedEntities,
+    unlinkedEntities: codeEntities - linkedEntities,
+    sourceBreakdown,
+    grade: toGrade(score)
+  };
+}
 var CoverageScorer = class {
   score(store) {
     const knowledgeNodes = KNOWLEDGE_TYPES.flatMap((t) => store.findNodes({ type: t }));
-    const domainMap = /* @__PURE__ */ new Map();
-    for (const node of knowledgeNodes) {
-      const domain = node.metadata.domain ?? "unclassified";
-      const group = domainMap.get(domain) ?? [];
-      group.push(node);
-      domainMap.set(domain, group);
-    }
+    const domainMap = groupByDomain(knowledgeNodes, () => "unclassified");
     const codeNodes = CODE_TYPES2.flatMap((t) => store.findNodes({ type: t }));
-    const codeDomains = /* @__PURE__ */ new Map();
-    for (const node of codeNodes) {
-      const domain = node.metadata.domain ?? this.domainFromPath(node.path);
-      const group = codeDomains.get(domain) ?? [];
-      group.push(node);
-      codeDomains.set(domain, group);
-    }
+    const codeDomains = groupByDomain(codeNodes, (n) => this.domainFromPath(n.path));
     const allDomains = /* @__PURE__ */ new Set([...domainMap.keys(), ...codeDomains.keys()]);
     const domains = [];
     for (const domain of allDomains) {
-      const knEntries = domainMap.get(domain) ?? [];
-      const codeEntries = codeDomains.get(domain) ?? [];
-      const linkedIds = /* @__PURE__ */ new Set();
-      for (const codeNode of codeEntries) {
-        for (const edgeType of KNOWLEDGE_EDGE_TYPES) {
-          const edges = store.getEdges({ to: codeNode.id, type: edgeType });
-          if (edges.length > 0) {
-            linkedIds.add(codeNode.id);
-            break;
-          }
-        }
-      }
-      const sourceBreakdown = {};
-      for (const kn of knEntries) {
-        const src = kn.metadata.source ?? "unknown";
-        sourceBreakdown[src] = (sourceBreakdown[src] ?? 0) + 1;
-      }
-      const codeEntities = codeEntries.length;
-      const linkedEntities = linkedIds.size;
-      const knowledgeEntries = knEntries.length;
-      const uniqueSources = Object.keys(sourceBreakdown).length;
-      const codeCoverageComponent = codeEntities > 0 ? linkedEntities / codeEntities * 60 : 0;
-      const knowledgeDepthComponent = Math.min(knowledgeEntries / 10, 1) * 20;
-      const sourceDiversityComponent = Math.min(uniqueSources / 3, 1) * 20;
-      const score = Math.round(
-        codeCoverageComponent + knowledgeDepthComponent + sourceDiversityComponent
+      domains.push(
+        scoreDomain(domain, domainMap.get(domain) ?? [], codeDomains.get(domain) ?? [], store)
       );
-      domains.push({
-        domain,
-        score,
-        knowledgeEntries,
-        codeEntities,
-        linkedEntities,
-        unlinkedEntities: codeEntities - linkedEntities,
-        sourceBreakdown,
-        grade: toGrade(score)
-      });
     }
     const overallScore = domains.length > 0 ? Math.round(domains.reduce((sum, d) => sum + d.score, 0) / domains.length) : 0;
     return {
@@ -4684,8 +5040,166 @@ var CoverageScorer = class {
   }
 };
 
+// src/ingest/KnowledgeDocMaterializer.ts
+import * as fs10 from "fs/promises";
+import * as path11 from "path";
+var VALID_BUSINESS_TYPES = /* @__PURE__ */ new Set([
+  "business_rule",
+  "business_process",
+  "business_concept",
+  "business_term",
+  "business_metric"
+]);
+var DEFAULT_MAX_DOCS = 50;
+var MAX_COLLISION_SUFFIX = 10;
+var KnowledgeDocMaterializer = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async materialize(gapEntries, options) {
+    const maxDocs = options.maxDocs ?? DEFAULT_MAX_DOCS;
+    const created = [];
+    const skipped = [];
+    const createdNames = /* @__PURE__ */ new Set();
+    for (const entry of gapEntries) {
+      const resolved = await this.resolveEntry(
+        entry,
+        created.length,
+        maxDocs,
+        createdNames,
+        options
+      );
+      if ("reason" in resolved) {
+        skipped.push(resolved);
+        continue;
+      }
+      const { node, domain, domainDir, nameKey } = resolved;
+      await fs10.mkdir(domainDir, { recursive: true });
+      const basename10 = this.generateFilename(entry.name);
+      const filename = await this.resolveCollision(domainDir, basename10);
+      const content = this.formatDoc(node, domain);
+      const filePath = ["docs", "knowledge", domain, filename].join("/");
+      await fs10.writeFile(path11.join(options.projectDir, filePath), content, "utf-8");
+      createdNames.add(nameKey);
+      created.push({ filePath, nodeId: entry.nodeId, domain, name: entry.name });
+    }
+    return { created, skipped };
+  }
+  async resolveEntry(entry, createdCount, maxDocs, createdNames, options) {
+    if (!entry.hasContent) {
+      return { nodeId: entry.nodeId, name: entry.name, reason: "no_content" };
+    }
+    const node = this.store.getNode(entry.nodeId);
+    if (!node || !node.content || node.content.trim().length < 10) {
+      return { nodeId: entry.nodeId, name: entry.name, reason: "no_content" };
+    }
+    const domain = this.inferDomain(node);
+    if (!domain || /[/\\]|\.\.|\0/.test(domain)) {
+      return { nodeId: entry.nodeId, name: entry.name, reason: "no_domain" };
+    }
+    if (createdCount >= maxDocs) {
+      return { nodeId: entry.nodeId, name: entry.name, reason: "cap_reached" };
+    }
+    const domainDir = path11.join(options.projectDir, "docs", "knowledge", domain);
+    const nameKey = `${domain}:${entry.name.toLowerCase().trim()}`;
+    if (!createdNames.has(nameKey) && await this.hasExistingDoc(domainDir, entry.name)) {
+      return { nodeId: entry.nodeId, name: entry.name, reason: "already_documented" };
+    }
+    if (options.dryRun) {
+      return { nodeId: entry.nodeId, name: entry.name, reason: "dry_run" };
+    }
+    return { node, domain, domainDir, nameKey };
+  }
+  inferDomain(node) {
+    if (node.metadata?.domain && typeof node.metadata.domain === "string") {
+      return node.metadata.domain;
+    }
+    if (node.path) {
+      const pkgMatch = node.path.match(/^packages\/([^/]+)/);
+      if (pkgMatch) return pkgMatch[1];
+      const srcMatch = node.path.match(/^src\/([^/]+)/);
+      if (srcMatch) return srcMatch[1];
+    }
+    if (node.metadata?.source === "knowledge-linker" || node.metadata?.source === "connector") {
+      const connector = node.metadata.connectorName;
+      if (typeof connector === "string") return connector;
+      return "general";
+    }
+    return null;
+  }
+  generateFilename(name) {
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
+    return `${slug}.md`;
+  }
+  async resolveCollision(dir, basename10) {
+    const ext = path11.extname(basename10);
+    const stem = path11.basename(basename10, ext);
+    try {
+      await fs10.access(path11.join(dir, basename10));
+    } catch {
+      return basename10;
+    }
+    for (let i = 2; i <= MAX_COLLISION_SUFFIX; i++) {
+      const candidate = `${stem}-${i}${ext}`;
+      try {
+        await fs10.access(path11.join(dir, candidate));
+      } catch {
+        return candidate;
+      }
+    }
+    throw new Error(
+      `Cannot resolve filename collision for "${basename10}" after ${MAX_COLLISION_SUFFIX} attempts`
+    );
+  }
+  formatDoc(node, domain) {
+    const mappedType = this.mapNodeType(node);
+    const sanitize = (s) => s.replace(/[\n\r]/g, " ").replace(/:/g, "-");
+    const lines = ["---", `type: ${sanitize(mappedType)}`, `domain: ${sanitize(domain)}`];
+    const tags = node.metadata?.tags;
+    if (Array.isArray(tags) && tags.length > 0) {
+      lines.push(`tags: [${tags.map((t) => sanitize(String(t))).join(", ")}]`);
+    }
+    const related = node.metadata?.related;
+    if (Array.isArray(related) && related.length > 0) {
+      lines.push(`related: [${related.map((r) => sanitize(String(r))).join(", ")}]`);
+    }
+    const title = (node.name ?? "").replace(/[\n\r]/g, " ");
+    lines.push("---", "", `# ${title}`, "", node.content ?? "", "");
+    return lines.join("\n");
+  }
+  /** Check if a doc with a matching title already exists in the domain directory. */
+  async hasExistingDoc(domainDir, name) {
+    const normalizedName = name.toLowerCase().trim();
+    try {
+      const files = await fs10.readdir(domainDir);
+      for (const file of files) {
+        if (!file.endsWith(".md")) continue;
+        const raw = await fs10.readFile(path11.join(domainDir, file), "utf-8");
+        const fmMatch = raw.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+        const body = fmMatch ? fmMatch[1] : raw;
+        const titleMatch = body.match(/^#\s+(.+)$/m);
+        if (titleMatch && titleMatch[1].trim().toLowerCase() === normalizedName) {
+          return true;
+        }
+      }
+    } catch {
+    }
+    return false;
+  }
+  mapNodeType(node) {
+    if (VALID_BUSINESS_TYPES.has(node.type)) {
+      return node.type;
+    }
+    if (node.type === "business_fact") {
+      return "business_rule";
+    }
+    return "business_concept";
+  }
+};
+
 // src/ingest/KnowledgePipelineRunner.ts
-var BUSINESS_NODE_TYPES = [
+var BUSINESS_NODE_TYPES2 = [
   "business_concept",
   "business_rule",
   "business_process",
@@ -4694,7 +5208,8 @@ var BUSINESS_NODE_TYPES = [
   "business_fact"
 ];
 var SNAPSHOT_NODE_TYPES = [
-  ...BUSINESS_NODE_TYPES,
+  ...BUSINESS_NODE_TYPES2,
+  "decision",
   "design_token",
   "design_constraint",
   "aesthetic_intent",
@@ -4706,51 +5221,98 @@ var KnowledgePipelineRunner = class {
   }
   store;
   async run(options) {
-    const maxIterations = options.maxIterations ?? 5;
     const remediations = [];
     const preSnapshot = this.buildSnapshot(options.domain);
     const extraction = await this.extract(options);
     const postSnapshot = this.buildSnapshot(options.domain);
     let driftResult = this.reconcile(preSnapshot, postSnapshot);
-    const contradictionDetector = new ContradictionDetector();
-    const contradictions = contradictionDetector.detect(this.store);
+    const contradictions = new ContradictionDetector().detect(this.store);
     let gapReport = await this.detect(options);
-    const coverageScorer = new CoverageScorer();
-    const coverage = coverageScorer.score(this.store);
+    const coverage = new CoverageScorer().score(this.store);
+    let materialization;
     let iterations = 1;
     if (options.fix) {
-      let previousFindingCount = driftResult.findings.length;
-      while (iterations < maxIterations) {
-        if (driftResult.findings.length === 0) break;
-        this.remediate(driftResult, remediations, options);
-        const rePreSnapshot = this.buildSnapshot(options.domain);
-        await this.extract(options);
-        const rePostSnapshot = this.buildSnapshot(options.domain);
-        driftResult = this.reconcile(rePreSnapshot, rePostSnapshot);
-        gapReport = await this.detect(options);
-        iterations++;
-        const newFindingCount = driftResult.findings.length;
-        if (newFindingCount >= previousFindingCount) break;
-        previousFindingCount = newFindingCount;
-      }
+      const loopResult = await this.runRemediationLoop(
+        options,
+        driftResult,
+        gapReport,
+        remediations
+      );
+      iterations = loopResult.iterations;
+      materialization = loopResult.materialization;
+    }
+    if (options.fix && iterations > 1) {
+      const finalSnapshot = this.buildSnapshot(options.domain);
+      driftResult = this.reconcile(preSnapshot, finalSnapshot);
+      gapReport = await this.detect(options);
     }
     await this.stageNewFindings(driftResult, options);
+    return this.buildResult(
+      driftResult,
+      iterations,
+      extraction,
+      gapReport,
+      remediations,
+      contradictions,
+      coverage,
+      materialization
+    );
+  }
+  /** Run the remediation convergence loop; returns iteration count and accumulated materialization. */
+  async runRemediationLoop(options, driftResult, gapReport, remediations) {
+    const maxIterations = options.maxIterations ?? 5;
+    let iterations = 1;
+    let currentDrift = driftResult;
+    let currentGapReport = gapReport;
+    let previousIssueCount = currentDrift.findings.length + currentGapReport.totalGaps;
+    let accumulatedMaterialization;
+    while (iterations < maxIterations) {
+      if (currentDrift.findings.length === 0 && currentGapReport.totalGaps === 0) break;
+      const matResult = await this.remediate(currentDrift, remediations, options, currentGapReport);
+      if (matResult) {
+        if (!accumulatedMaterialization) {
+          accumulatedMaterialization = matResult;
+        } else {
+          accumulatedMaterialization = {
+            created: [...accumulatedMaterialization.created, ...matResult.created],
+            skipped: [...accumulatedMaterialization.skipped, ...matResult.skipped]
+          };
+        }
+      }
+      const preSnapshot = this.buildSnapshot(options.domain);
+      await this.extract(options);
+      const postSnapshot = this.buildSnapshot(options.domain);
+      currentDrift = this.reconcile(preSnapshot, postSnapshot);
+      currentGapReport = await this.detect(options);
+      iterations++;
+      const currentIssueCount = currentDrift.findings.length + currentGapReport.totalGaps;
+      if (currentIssueCount >= previousIssueCount) break;
+      previousIssueCount = currentIssueCount;
+    }
+    return {
+      iterations,
+      ...accumulatedMaterialization ? { materialization: accumulatedMaterialization } : {}
+    };
+  }
+  /** Assemble the final pipeline result. */
+  buildResult(driftResult, iterations, extraction, gaps, remediations, contradictions, coverage, materialization) {
     return {
       verdict: this.computeVerdict(driftResult),
       driftScore: driftResult.driftScore,
       iterations,
       findings: driftResult.summary,
       extraction,
-      gaps: gapReport,
+      gaps,
       remediations,
       contradictions,
-      coverage
+      coverage,
+      ...materialization ? { materialization } : {}
     };
   }
   // ── Phase 1: EXTRACT ──────────────────────────────────────────────────────
   async extract(options) {
-    const extractedDir = path10.join(options.projectDir, ".harness", "knowledge", "extracted");
-    await fs9.mkdir(extractedDir, { recursive: true });
+    const extractedDir = path12.join(options.projectDir, ".harness", "knowledge", "extracted");
+    await fs11.mkdir(extractedDir, { recursive: true });
     const runner = createExtractionRunner();
     const extractionResult = await runner.run(options.projectDir, this.store, extractedDir);
     const diagramParser = new DiagramParser(this.store);
@@ -4764,7 +5326,7 @@ var KnowledgePipelineRunner = class {
       const imageResult = await imageExtractor.analyze(this.store, imagePaths);
       imageCount = imageResult.nodesAdded;
     }
-    const knowledgeDir = path10.join(options.projectDir, "docs", "knowledge");
+    const knowledgeDir = path12.join(options.projectDir, "docs", "knowledge");
     const bkIngestor = new BusinessKnowledgeIngestor(this.store);
     let bkResult;
     try {
@@ -4779,6 +5341,21 @@ var KnowledgePipelineRunner = class {
         durationMs: 0
       };
     }
+    const decisionsDir = path12.join(options.projectDir, "docs", "knowledge", "decisions");
+    const decisionIngestor = new DecisionIngestor(this.store);
+    let decisionResult;
+    try {
+      decisionResult = await decisionIngestor.ingest(decisionsDir);
+    } catch {
+      decisionResult = {
+        nodesAdded: 0,
+        nodesUpdated: 0,
+        edgesAdded: 0,
+        edgesUpdated: 0,
+        errors: [],
+        durationMs: 0
+      };
+    }
     const linker = new KnowledgeLinker(this.store, extractedDir);
     const linkResult = await linker.link();
     return {
@@ -4786,6 +5363,7 @@ var KnowledgePipelineRunner = class {
       diagrams: diagramResult.nodesAdded,
       linkerFacts: linkResult.factsCreated,
       businessKnowledge: bkResult.nodesAdded,
+      decisions: decisionResult.nodesAdded,
       images: imageCount
     };
   }
@@ -4812,14 +5390,14 @@ var KnowledgePipelineRunner = class {
   }
   // ── Phase 3: DETECT ───────────────────────────────────────────────────────
   async detect(options) {
-    const knowledgeDir = path10.join(options.projectDir, "docs", "knowledge");
+    const knowledgeDir = path12.join(options.projectDir, "docs", "knowledge");
     const aggregator = new KnowledgeStagingAggregator(options.projectDir);
-    const gapReport = await aggregator.generateGapReport(knowledgeDir);
+    const gapReport = await aggregator.generateGapReport(knowledgeDir, this.store);
     await aggregator.writeGapReport(gapReport);
     return gapReport;
   }
   // ── Phase 4: REMEDIATE ────────────────────────────────────────────────────
-  remediate(driftResult, remediations, options) {
+  async remediate(driftResult, remediations, options, gapReport) {
     for (const finding of driftResult.findings) {
       switch (finding.classification) {
         case "stale":
@@ -4837,6 +5415,22 @@ var KnowledgePipelineRunner = class {
           break;
       }
     }
+    if (!options.ci) {
+      const allGapEntries = gapReport.domains.flatMap((d) => d.gapEntries);
+      const materializable = allGapEntries.filter((e) => e.hasContent);
+      if (materializable.length > 0) {
+        const materializer = new KnowledgeDocMaterializer(this.store);
+        const matResult = await materializer.materialize(materializable, {
+          projectDir: options.projectDir,
+          dryRun: false
+        });
+        for (const doc of matResult.created) {
+          remediations.push(`created doc: ${doc.filePath}`);
+        }
+        return matResult;
+      }
+    }
+    return void 0;
   }
   async stageNewFindings(driftResult, options) {
     const newFindings = driftResult.findings.filter((f) => f.classification === "new");
@@ -4871,7 +5465,7 @@ var KnowledgePipelineRunner = class {
 };
 
 // src/ingest/connectors/ConnectorUtils.ts
-var CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
+var CODE_NODE_TYPES5 = ["file", "function", "class", "method", "interface", "variable"];
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 function withRetry(client, options) {
   const maxRetries = options?.maxRetries ?? 3;
@@ -4936,7 +5530,7 @@ function sanitizeExternalText(text, maxLength = 2e3) {
 }
 function linkToCode(store, content, sourceNodeId, edgeType, options) {
   let edgesCreated = 0;
-  for (const type of CODE_NODE_TYPES4) {
+  for (const type of CODE_NODE_TYPES5) {
     const nodes = store.findNodes({ type });
     for (const node of nodes) {
       if (node.name.length < 3) continue;
@@ -4956,12 +5550,12 @@ function linkToCode(store, content, sourceNodeId, edgeType, options) {
 }
 
 // src/ingest/connectors/SyncManager.ts
-import * as fs10 from "fs/promises";
-import * as path11 from "path";
+import * as fs12 from "fs/promises";
+import * as path13 from "path";
 var SyncManager = class {
   constructor(store, graphDir) {
     this.store = store;
-    this.metadataPath = path11.join(graphDir, "sync-metadata.json");
+    this.metadataPath = path13.join(graphDir, "sync-metadata.json");
   }
   store;
   registrations = /* @__PURE__ */ new Map();
@@ -5026,15 +5620,15 @@ var SyncManager = class {
   }
   async loadMetadata() {
     try {
-      const raw = await fs10.readFile(this.metadataPath, "utf-8");
+      const raw = await fs12.readFile(this.metadataPath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return { connectors: {} };
     }
   }
   async saveMetadata(metadata) {
-    await fs10.mkdir(path11.dirname(this.metadataPath), { recursive: true });
-    await fs10.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+    await fs12.mkdir(path13.dirname(this.metadataPath), { recursive: true });
+    await fs12.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
   }
 };
 
@@ -5139,6 +5733,14 @@ var JiraConnector = class {
         start
       );
     }
+    try {
+      const parsed = new URL(baseUrl);
+      if (parsed.protocol !== "https:" && parsed.hostname !== "localhost") {
+        return buildIngestResult(0, 0, [`${baseUrlEnv} must use HTTPS`], start);
+      }
+    } catch {
+      return buildIngestResult(0, 0, [`${baseUrlEnv} is not a valid URL`], start);
+    }
     const jql = buildJql(config);
     const headers = { Authorization: `Basic ${apiKey}`, "Content-Type": "application/json" };
     try {
@@ -5428,6 +6030,14 @@ var ConfluenceConnector = class {
     }
     const baseUrlEnv = config.baseUrlEnv ?? "CONFLUENCE_BASE_URL";
     const baseUrl = process.env[baseUrlEnv] ?? "";
+    try {
+      const parsed = new URL(baseUrl);
+      if (parsed.protocol !== "https:" && parsed.hostname !== "localhost") {
+        return missingApiKeyResult(`${baseUrlEnv} must use HTTPS`, start);
+      }
+    } catch {
+      return missingApiKeyResult(`${baseUrlEnv} is not a valid URL`, start);
+    }
     const spaceKey = config.spaceKey ?? "";
     const counts = await this.fetchAllPagesHandled(
       store,
@@ -5521,7 +6131,7 @@ var ConfluenceConnector = class {
 };
 
 // src/ingest/connectors/CIConnector.ts
-function emptyResult2(errors, start) {
+function emptyResult5(errors, start) {
   return {
     nodesAdded: 0,
     nodesUpdated: 0,
@@ -5589,7 +6199,7 @@ var CIConnector = class {
     const apiKeyEnv = config.apiKeyEnv ?? "GITHUB_TOKEN";
     const apiKey = process.env[apiKeyEnv];
     if (!apiKey) {
-      return emptyResult2(
+      return emptyResult5(
         [`Missing API key: environment variable "${apiKeyEnv}" is not set`],
         start
       );
@@ -5653,6 +6263,14 @@ function hasConstraintKeyword(text) {
   const lower = text.toLowerCase();
   return CONSTRAINT_KEYWORDS.some((kw) => lower.includes(kw));
 }
+function buildNodeMetadata(condensed, base) {
+  const metadata = { ...base };
+  if (condensed.method !== "passthrough") {
+    metadata.condensed = condensed.method;
+    metadata.originalLength = condensed.originalLength;
+  }
+  return metadata;
+}
 function buildIngestResult2(nodesAdded, edgesAdded, errors, start) {
   return {
     nodesAdded,
@@ -5663,6 +6281,24 @@ function buildIngestResult2(nodesAdded, edgesAdded, errors, start) {
     durationMs: Date.now() - start
   };
 }
+function validateFigmaConfig(config) {
+  const apiKeyEnv = config.apiKeyEnv ?? "FIGMA_API_KEY";
+  const apiKey = process.env[apiKeyEnv];
+  if (!apiKey) return { error: `Missing API key: environment variable "${apiKeyEnv}" is not set` };
+  const baseUrlEnv = config.baseUrlEnv ?? "FIGMA_BASE_URL";
+  const baseUrl = process.env[baseUrlEnv] ?? "https://api.figma.com";
+  try {
+    const parsed = new URL(baseUrl);
+    if (parsed.protocol !== "https:" || !parsed.hostname.endsWith("api.figma.com")) {
+      return { error: `Invalid ${baseUrlEnv}: must be an HTTPS URL on api.figma.com` };
+    }
+  } catch {
+    return { error: `Invalid ${baseUrlEnv}: not a valid URL` };
+  }
+  const fileIds = config.fileIds;
+  if (!fileIds || fileIds.length === 0) return { error: "No fileIds provided in connector config" };
+  return { apiKey, baseUrl, fileIds };
+}
 var FigmaConnector = class {
   name = "figma";
   source = "figma";
@@ -5672,35 +6308,9 @@ var FigmaConnector = class {
   }
   async ingest(store, config) {
     const start = Date.now();
-    const apiKeyEnv = config.apiKeyEnv ?? "FIGMA_API_KEY";
-    const apiKey = process.env[apiKeyEnv];
-    if (!apiKey) {
-      return buildIngestResult2(
-        0,
-        0,
-        [`Missing API key: environment variable "${apiKeyEnv}" is not set`],
-        start
-      );
-    }
-    const baseUrlEnv = config.baseUrlEnv ?? "FIGMA_BASE_URL";
-    const baseUrl = process.env[baseUrlEnv] ?? "https://api.figma.com";
-    try {
-      const parsed = new URL(baseUrl);
-      if (parsed.protocol !== "https:" || !parsed.hostname.endsWith("api.figma.com")) {
-        return buildIngestResult2(
-          0,
-          0,
-          [`Invalid ${baseUrlEnv}: must be an HTTPS URL on api.figma.com`],
-          start
-        );
-      }
-    } catch {
-      return buildIngestResult2(0, 0, [`Invalid ${baseUrlEnv}: not a valid URL`], start);
-    }
-    const fileIds = config.fileIds;
-    if (!fileIds || fileIds.length === 0) {
-      return buildIngestResult2(0, 0, ["No fileIds provided in connector config"], start);
-    }
+    const validated = validateFigmaConfig(config);
+    if ("error" in validated) return buildIngestResult2(0, 0, [validated.error], start);
+    const { apiKey, baseUrl, fileIds } = validated;
     const headers = { "X-FIGMA-TOKEN": apiKey };
     const maxLen = config.maxContentLength ?? 4e3;
     let nodesAdded = 0;
@@ -5720,6 +6330,17 @@ var FigmaConnector = class {
     return buildIngestResult2(nodesAdded, edgesAdded, errors, start);
   }
   async processFile(store, baseUrl, fileId, headers, maxLen) {
+    let nodesAdded = 0;
+    let edgesAdded = 0;
+    const styleCounts = await this.ingestStyles(store, baseUrl, fileId, headers, maxLen);
+    nodesAdded += styleCounts.nodesAdded;
+    edgesAdded += styleCounts.edgesAdded;
+    const componentCounts = await this.ingestComponents(store, baseUrl, fileId, headers, maxLen);
+    nodesAdded += componentCounts.nodesAdded;
+    edgesAdded += componentCounts.edgesAdded;
+    return { nodesAdded, edgesAdded };
+  }
+  async ingestStyles(store, baseUrl, fileId, headers, maxLen) {
     let nodesAdded = 0;
     let edgesAdded = 0;
     const stylesUrl = `${baseUrl}/v1/files/${fileId}/styles`;
@@ -5727,90 +6348,112 @@ var FigmaConnector = class {
     if (!stylesResponse.ok) throw new Error(`Styles request failed for file ${fileId}`);
     const stylesData = await stylesResponse.json();
     for (const style of stylesData.meta.styles) {
-      const nodeId = `figma:token:${style.key}`;
-      const condensed = await condenseContent(sanitizeExternalText(style.description || "", 2e3), {
-        maxLength: maxLen
-      });
-      const metadata = {
-        source: "figma",
-        key: style.key,
-        styleType: style.style_type,
-        fileId
-      };
-      if (condensed.method !== "passthrough") {
-        metadata.condensed = condensed.method;
-        metadata.originalLength = condensed.originalLength;
-      }
-      store.addNode({
-        id: nodeId,
-        type: "design_token",
-        name: sanitizeExternalText(style.name, 500),
-        content: condensed.content,
-        metadata
-      });
-      nodesAdded++;
-      const searchText = sanitizeExternalText([style.name, style.description].join(" "));
-      edgesAdded += linkToCode(store, searchText, nodeId, "references");
+      const counts = await this.processStyle(store, style, fileId, maxLen);
+      nodesAdded += counts.nodesAdded;
+      edgesAdded += counts.edgesAdded;
     }
+    return { nodesAdded, edgesAdded };
+  }
+  async processStyle(store, style, fileId, maxLen) {
+    const nodeId = `figma:token:${style.key}`;
+    const condensed = await condenseContent(sanitizeExternalText(style.description || "", 2e3), {
+      maxLength: maxLen
+    });
+    const metadata = buildNodeMetadata(condensed, {
+      source: "figma",
+      key: style.key,
+      styleType: style.style_type,
+      fileId
+    });
+    store.addNode({
+      id: nodeId,
+      type: "design_token",
+      name: sanitizeExternalText(style.name, 500),
+      content: condensed.content,
+      metadata
+    });
+    const searchText = sanitizeExternalText([style.name, style.description].join(" "));
+    const edgesAdded = linkToCode(store, searchText, nodeId, "references");
+    return { nodesAdded: 1, edgesAdded };
+  }
+  async ingestComponents(store, baseUrl, fileId, headers, maxLen) {
+    let nodesAdded = 0;
+    let edgesAdded = 0;
     const componentsUrl = `${baseUrl}/v1/files/${fileId}/components`;
     const componentsResponse = await this.httpClient(componentsUrl, { headers });
     if (!componentsResponse.ok) throw new Error(`Components request failed for file ${fileId}`);
     const componentsData = await componentsResponse.json();
     for (const component of componentsData.meta.components) {
-      const description = component.description || "";
-      if (description) {
-        const intentId = `figma:intent:${component.key}`;
-        const condensed = await condenseContent(sanitizeExternalText(description, 2e3), {
-          maxLength: maxLen
-        });
-        const metadata = {
-          source: "figma",
-          key: component.key,
-          fileId
-        };
-        if (condensed.method !== "passthrough") {
-          metadata.condensed = condensed.method;
-          metadata.originalLength = condensed.originalLength;
-        }
-        store.addNode({
-          id: intentId,
-          type: "aesthetic_intent",
-          name: sanitizeExternalText(component.name, 500),
-          content: condensed.content,
-          metadata
-        });
-        nodesAdded++;
-        const searchText = sanitizeExternalText([component.name, description].join(" "));
-        edgesAdded += linkToCode(store, searchText, intentId, "references");
-      }
-      if (description && hasConstraintKeyword(description)) {
-        const constraintId = `figma:constraint:${component.key}`;
-        const condensed = await condenseContent(sanitizeExternalText(description, 2e3), {
-          maxLength: maxLen
-        });
-        const metadata = {
-          source: "figma",
-          key: component.key,
-          fileId
-        };
-        if (condensed.method !== "passthrough") {
-          metadata.condensed = condensed.method;
-          metadata.originalLength = condensed.originalLength;
-        }
-        store.addNode({
-          id: constraintId,
-          type: "design_constraint",
-          name: sanitizeExternalText(component.name, 500),
-          content: condensed.content,
-          metadata
-        });
-        nodesAdded++;
-        const searchText = sanitizeExternalText([component.name, description].join(" "));
-        edgesAdded += linkToCode(store, searchText, constraintId, "references");
-      }
+      const counts = await this.processComponent(store, component, fileId, maxLen);
+      nodesAdded += counts.nodesAdded;
+      edgesAdded += counts.edgesAdded;
     }
     return { nodesAdded, edgesAdded };
   }
+  async processComponent(store, component, fileId, maxLen) {
+    let nodesAdded = 0;
+    let edgesAdded = 0;
+    const description = component.description || "";
+    if (description) {
+      const counts = await this.addComponentIntent(store, component, description, fileId, maxLen);
+      nodesAdded += counts.nodesAdded;
+      edgesAdded += counts.edgesAdded;
+    }
+    if (description && hasConstraintKeyword(description)) {
+      const counts = await this.addComponentConstraint(
+        store,
+        component,
+        description,
+        fileId,
+        maxLen
+      );
+      nodesAdded += counts.nodesAdded;
+      edgesAdded += counts.edgesAdded;
+    }
+    return { nodesAdded, edgesAdded };
+  }
+  async addComponentIntent(store, component, description, fileId, maxLen) {
+    const intentId = `figma:intent:${component.key}`;
+    const condensed = await condenseContent(sanitizeExternalText(description, 2e3), {
+      maxLength: maxLen
+    });
+    const metadata = buildNodeMetadata(condensed, {
+      source: "figma",
+      key: component.key,
+      fileId
+    });
+    store.addNode({
+      id: intentId,
+      type: "aesthetic_intent",
+      name: sanitizeExternalText(component.name, 500),
+      content: condensed.content,
+      metadata
+    });
+    const searchText = sanitizeExternalText([component.name, description].join(" "));
+    const edgesAdded = linkToCode(store, searchText, intentId, "references");
+    return { nodesAdded: 1, edgesAdded };
+  }
+  async addComponentConstraint(store, component, description, fileId, maxLen) {
+    const constraintId = `figma:constraint:${component.key}`;
+    const condensed = await condenseContent(sanitizeExternalText(description, 2e3), {
+      maxLength: maxLen
+    });
+    const metadata = buildNodeMetadata(condensed, {
+      source: "figma",
+      key: component.key,
+      fileId
+    });
+    store.addNode({
+      id: constraintId,
+      type: "design_constraint",
+      name: sanitizeExternalText(component.name, 500),
+      content: condensed.content,
+      metadata
+    });
+    const searchText = sanitizeExternalText([component.name, description].join(" "));
+    const edgesAdded = linkToCode(store, searchText, constraintId, "references");
+    return { nodesAdded: 1, edgesAdded };
+  }
 };
 
 // src/ingest/connectors/MiroConnector.ts
@@ -5829,6 +6472,46 @@ function buildIngestResult3(nodesAdded, edgesAdded, errors, start) {
     durationMs: Date.now() - start
   };
 }
+function validateBaseUrl(baseUrl, baseUrlEnv) {
+  try {
+    const parsed = new URL(baseUrl);
+    if (parsed.protocol !== "https:" || parsed.hostname !== "api.miro.com") {
+      return `Invalid ${baseUrlEnv}: must be an HTTPS URL on api.miro.com`;
+    }
+  } catch {
+    return `Invalid ${baseUrlEnv}: not a valid URL`;
+  }
+  return null;
+}
+function resolveConfig(config, start) {
+  const apiKeyEnv = config.apiKeyEnv ?? "MIRO_API_KEY";
+  const apiKey = process.env[apiKeyEnv];
+  if (!apiKey) {
+    return {
+      ok: false,
+      result: buildIngestResult3(
+        0,
+        0,
+        [`Missing API key: environment variable "${apiKeyEnv}" is not set`],
+        start
+      )
+    };
+  }
+  const baseUrlEnv = config.baseUrlEnv ?? "MIRO_BASE_URL";
+  const baseUrl = process.env[baseUrlEnv] ?? "https://api.miro.com";
+  const urlError = validateBaseUrl(baseUrl, baseUrlEnv);
+  if (urlError) {
+    return { ok: false, result: buildIngestResult3(0, 0, [urlError], start) };
+  }
+  const boardIds = config.boardIds;
+  if (!boardIds || boardIds.length === 0) {
+    return {
+      ok: false,
+      result: buildIngestResult3(0, 0, ["No boardIds provided in config"], start)
+    };
+  }
+  return { ok: true, apiKey, baseUrl, boardIds, headers: { Authorization: `Bearer ${apiKey}` } };
+}
 var MiroConnector = class {
   name = "miro";
   source = "miro";
@@ -5838,36 +6521,9 @@ var MiroConnector = class {
   }
   async ingest(store, config) {
     const start = Date.now();
-    const apiKeyEnv = config.apiKeyEnv ?? "MIRO_API_KEY";
-    const apiKey = process.env[apiKeyEnv];
-    if (!apiKey) {
-      return buildIngestResult3(
-        0,
-        0,
-        [`Missing API key: environment variable "${apiKeyEnv}" is not set`],
-        start
-      );
-    }
-    const baseUrlEnv = config.baseUrlEnv ?? "MIRO_BASE_URL";
-    const baseUrl = process.env[baseUrlEnv] ?? "https://api.miro.com";
-    try {
-      const parsed = new URL(baseUrl);
-      if (parsed.protocol !== "https:" || parsed.hostname !== "api.miro.com") {
-        return buildIngestResult3(
-          0,
-          0,
-          [`Invalid ${baseUrlEnv}: must be an HTTPS URL on api.miro.com`],
-          start
-        );
-      }
-    } catch {
-      return buildIngestResult3(0, 0, [`Invalid ${baseUrlEnv}: not a valid URL`], start);
-    }
-    const boardIds = config.boardIds;
-    if (!boardIds || boardIds.length === 0) {
-      return buildIngestResult3(0, 0, ["No boardIds provided in config"], start);
-    }
-    const headers = { Authorization: `Bearer ${apiKey}` };
+    const resolved = resolveConfig(config, start);
+    if (!resolved.ok) return resolved.result;
+    const { baseUrl, boardIds, headers } = resolved;
     let totalNodesAdded = 0;
     let totalEdgesAdded = 0;
     const errors = [];
@@ -6071,7 +6727,7 @@ var FusionLayer = class {
 };
 
 // src/entropy/GraphEntropyAdapter.ts
-var CODE_NODE_TYPES5 = ["file", "function", "class", "method", "interface", "variable"];
+var CODE_NODE_TYPES6 = ["file", "function", "class", "method", "interface", "variable"];
 var GraphEntropyAdapter = class {
   constructor(store) {
     this.store = store;
@@ -6151,7 +6807,7 @@ var GraphEntropyAdapter = class {
   }
   findEntryPoints() {
     const entryPoints = [];
-    for (const nodeType of CODE_NODE_TYPES5) {
+    for (const nodeType of CODE_NODE_TYPES6) {
       const nodes = this.store.findNodes({ type: nodeType });
       for (const node of nodes) {
         const isIndexFile = nodeType === "file" && node.name === "index.ts";
@@ -6187,7 +6843,7 @@ var GraphEntropyAdapter = class {
   }
   collectUnreachableNodes(visited) {
     const unreachableNodes = [];
-    for (const nodeType of CODE_NODE_TYPES5) {
+    for (const nodeType of CODE_NODE_TYPES6) {
       const nodes = this.store.findNodes({ type: nodeType });
       for (const node of nodes) {
         if (!visited.has(node.id)) {
@@ -7033,9 +7689,9 @@ var EntityExtractor = class {
   extractPaths(trimmed, add) {
     const consumed = /* @__PURE__ */ new Set();
     for (const match of trimmed.matchAll(FILE_PATH_RE)) {
-      const path13 = match[0];
-      add(path13);
-      consumed.add(path13);
+      const path15 = match[0];
+      add(path15);
+      consumed.add(path15);
     }
     return consumed;
   }
@@ -7107,8 +7763,8 @@ var EntityResolver = class {
       if (isPathLike && node.path.includes(raw)) {
         return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
       }
-      const basename7 = node.path.split("/").pop() ?? "";
-      if (basename7.includes(raw)) {
+      const basename10 = node.path.split("/").pop() ?? "";
+      if (basename10.includes(raw)) {
         return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
       }
       if (raw.length >= 4 && node.path.includes(raw)) {
@@ -7187,13 +7843,13 @@ var ResponseFormatter = class {
     const context = Array.isArray(d?.context) ? d.context : [];
     const firstEntity = entities[0];
     const nodeType = firstEntity?.node.type ?? "node";
-    const path13 = firstEntity?.node.path ?? "unknown";
+    const path15 = firstEntity?.node.path ?? "unknown";
     let neighborCount = 0;
     const firstContext = context[0];
     if (firstContext && Array.isArray(firstContext.nodes)) {
       neighborCount = firstContext.nodes.length;
     }
-    return `**${entityName}** is a ${nodeType} at \`${path13}\`. Connected to ${neighborCount} nodes.`;
+    return `**${entityName}** is a ${nodeType} at \`${path15}\`. Connected to ${neighborCount} nodes.`;
   }
   formatAnomaly(data) {
     const d = data;
@@ -7576,7 +8232,7 @@ var PHASE_NODE_TYPES = {
   debug: ["failure", "learning", "function", "method"],
   plan: ["adr", "document", "module", "layer"]
 };
-var CODE_NODE_TYPES6 = /* @__PURE__ */ new Set([
+var CODE_NODE_TYPES7 = /* @__PURE__ */ new Set([
   "file",
   "function",
   "class",
@@ -7795,7 +8451,7 @@ var Assembler = class {
    */
   checkCoverage() {
     const codeNodes = [];
-    for (const type of CODE_NODE_TYPES6) {
+    for (const type of CODE_NODE_TYPES7) {
       codeNodes.push(...this.store.findNodes({ type }));
     }
     const documented = [];
@@ -7975,14 +8631,14 @@ var GraphConstraintAdapter = class {
 };
 
 // src/ingest/DesignIngestor.ts
-import * as fs11 from "fs/promises";
-import * as path12 from "path";
+import * as fs13 from "fs/promises";
+import * as path14 from "path";
 function isDTCGToken(obj) {
   return typeof obj === "object" && obj !== null && "$value" in obj && "$type" in obj;
 }
 async function readFileOrNull(filePath) {
   try {
-    return await fs11.readFile(filePath, "utf-8");
+    return await fs13.readFile(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -8128,8 +8784,8 @@ var DesignIngestor = class {
   async ingestAll(designDir) {
     const start = Date.now();
     const [tokensResult, intentResult] = await Promise.all([
-      this.ingestTokens(path12.join(designDir, "tokens.json")),
-      this.ingestDesignIntent(path12.join(designDir, "DESIGN.md"))
+      this.ingestTokens(path14.join(designDir, "tokens.json")),
+      this.ingestDesignIntent(path14.join(designDir, "DESIGN.md"))
     ]);
     const merged = mergeResults(tokensResult, intentResult);
     return { ...merged, durationMs: Date.now() - start };
@@ -8365,10 +9021,10 @@ var TaskIndependenceAnalyzer = class {
         includeTypes: ["file"]
       });
       for (const n of queryResult.nodes) {
-        const path13 = n.path ?? n.id.replace(/^file:/, "");
-        if (!fileSet.has(path13)) {
-          if (!result.has(path13)) {
-            result.set(path13, file);
+        const path15 = n.path ?? n.id.replace(/^file:/, "");
+        if (!fileSet.has(path15)) {
+          if (!result.has(path15)) {
+            result.set(path15, file);
           }
         }
       }
@@ -8745,7 +9401,7 @@ var ConflictPredictor = class {
 };
 
 // src/index.ts
-var VERSION = "0.4.3";
+var VERSION = "0.6.0";
 export {
   ALL_EXTRACTORS,
   ApiPathExtractor,
@@ -8762,6 +9418,7 @@ export {
   ContradictionDetector,
   CoverageScorer,
   D2Parser,
+  DecisionIngestor,
   DesignConstraintAdapter,
   DesignIngestor,
   DiagramParser,
@@ -8786,6 +9443,7 @@ export {
   ImageAnalysisExtractor,
   IntentClassifier,
   JiraConnector,
+  KnowledgeDocMaterializer,
   KnowledgeIngestor,
   KnowledgePipelineRunner,
   KnowledgeStagingAggregator,