@harness-engineering/cli 1.26.0 → 1.27.0

package/dist/{chunk-VV2PJT4K.js → chunk-GAIOIINV.js}

@@ -19,22 +19,26 @@ import * as fs3 from "fs/promises";
 import * as path4 from "path";
 import * as fs4 from "fs/promises";
 import * as path5 from "path";
-import * as fs9 from "fs/promises";
-import * as path10 from "path";
 import * as fs5 from "fs/promises";
 import * as path6 from "path";
+import * as fs11 from "fs/promises";
+import * as path12 from "path";
 import * as fs6 from "fs/promises";
 import * as path7 from "path";
 import * as fs7 from "fs/promises";
 import * as path8 from "path";
 import * as fs8 from "fs/promises";
 import * as path9 from "path";
+import * as fs9 from "fs/promises";
+import * as path10 from "path";
 import * as fs10 from "fs/promises";
 import * as path11 from "path";
+import * as fs12 from "fs/promises";
+import * as path13 from "path";
 import { minimatch } from "minimatch";
 import { relative as relative5 } from "path";
-import * as fs11 from "fs/promises";
-import * as path12 from "path";
+import * as fs13 from "fs/promises";
+import * as path14 from "path";
 function streamGraphJson(filePath, nodes, edges) {
   return new Promise((resolve, reject) => {
     const stream = createWriteStream(filePath, { encoding: "utf-8" });
@@ -50,7 +54,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) {
@@ -73,15 +77,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) };
 }
 function safeMerge(target, source) {
   for (const key of Object.keys(source)) {
@@ -363,13 +371,280 @@ function detectEarsPattern(text) {
   if (/^the\s+\w+\s+shall\b/.test(lower)) return "ubiquitous";
   return void 0;
 }
-function emptyMermaidResult(diagramType = "unknown") {
+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 }
+  };
+}
+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 });
+  }
+  state.braceDepth++;
+}
+function processTopLevelLine(stripped, state) {
+  const conn = parseConnection(stripped);
+  if (conn) {
+    state.relationships.push(conn);
+    return;
+  }
+  const shape = parseSimpleShape(stripped);
+  if (shape && !state.entities.has(shape.id)) {
+    state.entities.set(shape.id, { id: shape.id, label: shape.label });
+  }
+}
+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);
+}
+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
+  );
+}
 function applyReactionBoost(candidate, nodeType, metadata) {
   if (nodeType !== "conversation" || !metadata.reactions) return;
   const reactions = metadata.reactions;
@@ -379,11 +654,11 @@ function applyReactionBoost(candidate, nodeType, metadata) {
   }
 }
 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];
 }
 function createExtractionRunner() {
@@ -421,6 +696,77 @@ function classifyConflict(a, b) {
     return "temporal_conflict";
   return "status_divergence";
 }
+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);
+      }
+    }
+  }
+}
+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);
+        }
+      }
+    }
+  }
+}
 function toGrade(score) {
   if (score >= 80) return "A";
   if (score >= 60) return "B";
@@ -428,6 +774,64 @@ 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)
+  };
+}
 function withRetry(client, options) {
   const maxRetries = options?.maxRetries ?? 3;
   const baseDelayMs = options?.baseDelayMs ?? 1e3;
@@ -469,7 +873,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;
@@ -582,7 +986,7 @@ function missingApiKeyResult(envVar, start) {
     durationMs: Date.now() - start
   };
 }
-function emptyResult2(errors, start) {
+function emptyResult5(errors, start) {
   return {
     nodesAdded: 0,
     nodesUpdated: 0,
@@ -641,6 +1045,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,
@@ -651,6 +1063,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 };
+}
 function stripHtml(html) {
   return html.replace(/<[^>]*>/g, "");
 }
@@ -664,6 +1094,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}` } };
+}
 function isSkippableWord(cleaned, allConsumed) {
   if (allConsumed.has(cleaned)) return true;
   const lower = cleaned.toLowerCase();
@@ -891,7 +1361,7 @@ function isDTCGToken(obj) {
 }
 async function readFileOrNull(filePath) {
   try {
-    return await fs11.readFile(filePath, "utf-8");
+    return await fs13.readFile(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -973,7 +1443,7 @@ function parseAntiPatterns(content) {
   }
   return patterns;
 }
-var NODE_TYPES, EDGE_TYPES, OBSERVABILITY_TYPES, CURRENT_SCHEMA_VERSION, NODE_STABILITY, GraphNodeSchema, GraphEdgeSchema, POISONED_KEYS, GraphStore, VectorStore, DEFAULT_TTL_MS, PackedSummaryCache, ContextQL, TEST_TYPES, DOC_TYPES, CODE_TYPES, SKIP_METHOD_NAMES, FUNCTION_PATTERNS, CLASS_PATTERNS, INTERFACE_PATTERNS, METHOD_PATTERNS, GO_METHOD_PATTERN, VARIABLE_PATTERNS, SUPPORTED_EXTENSIONS, SKIP_EXTENSIONS, CodeIngestor, execFileAsync, GitIngestor, TopologicalLinker, CODE_NODE_TYPES, KnowledgeIngestor, BUSINESS_KNOWLEDGE_TYPES, GOVERNS_SOURCE_TYPES, CODE_NODE_TYPES2, MEASURABLE_TYPES, BusinessKnowledgeIngestor, REQUIREMENT_SECTIONS, SECTION_HEADING_RE, NUMBERED_ITEM_RE, CODE_NODE_TYPES3, RequirementIngestor, MermaidParser, D2Parser, PlantUmlParser, DIAGRAM_EXTENSIONS, DiagramParser, HEURISTIC_PATTERNS, SCANNABLE_TYPES, KnowledgeLinker, StructuralDriftDetector, KnowledgeStagingAggregator, SKIP_DIRS, EXT_TO_LANGUAGE, SKIP_EXTENSIONS2, EXTRACTOR_EDGE_TYPE, ExtractionRunner, PATTERNS, TestDescriptionExtractor, EnumConstantExtractor, ValidationRuleExtractor, ApiPathExtractor, ALL_EXTRACTORS, ImageAnalysisExtractor, KNOWLEDGE_NODE_TYPES, SIMILARITY_THRESHOLD, ContradictionDetector, KNOWLEDGE_TYPES, CODE_TYPES2, KNOWLEDGE_EDGE_TYPES, CoverageScorer, BUSINESS_NODE_TYPES, SNAPSHOT_NODE_TYPES, KnowledgePipelineRunner, CODE_NODE_TYPES4, RETRYABLE_STATUSES, SANITIZE_RULES, SyncManager, SUMMARIZE_PROMPT, JiraConnector, SlackConnector, ConfluenceConnector, CIConnector, CONSTRAINT_KEYWORDS, FigmaConnector, MIN_CONTENT_LENGTH, CONCEPT_ITEM_TYPES, MiroConnector, STOP_WORDS, FusionLayer, CODE_NODE_TYPES5, GraphEntropyAdapter, GraphComplexityAdapter, GraphCouplingAdapter, DEFAULT_THRESHOLD, DEFAULT_METRICS, RECOGNIZED_METRICS, GraphAnomalyAdapter, INTENTS, SIGNAL_WEIGHTS, INTENT_SIGNALS, IntentClassifier, INTENT_KEYWORDS, STOP_WORDS2, PASCAL_OR_CAMEL_RE, FILE_PATH_RE, QUOTED_RE, EntityExtractor, EntityResolver, ResponseFormatter, CompositeProbabilityStrategy, DEFAULT_PROBABILITY_FLOOR, DEFAULT_MAX_DEPTH, CascadeSimulator, ENTITY_REQUIRED_INTENTS, classifier, extractor, formatter, PHASE_NODE_TYPES, CODE_NODE_TYPES6, Assembler, GraphConstraintAdapter, DesignIngestor, DesignConstraintAdapter, GraphFeedbackAdapter, DEFAULT_EDGE_TYPES, TaskIndependenceAnalyzer, ConflictPredictor, VERSION;
+var NODE_TYPES, EDGE_TYPES, OBSERVABILITY_TYPES, CURRENT_SCHEMA_VERSION, NODE_STABILITY, GraphNodeSchema, GraphEdgeSchema, POISONED_KEYS, GraphStore, VectorStore, DEFAULT_TTL_MS, PackedSummaryCache, ContextQL, TEST_TYPES, DOC_TYPES, CODE_TYPES, SKIP_METHOD_NAMES, FUNCTION_PATTERNS, CLASS_PATTERNS, INTERFACE_PATTERNS, METHOD_PATTERNS, GO_METHOD_PATTERN, VARIABLE_PATTERNS, SUPPORTED_EXTENSIONS, SKIP_EXTENSIONS, CodeIngestor, execFileAsync, GitIngestor, TopologicalLinker, CODE_NODE_TYPES, KnowledgeIngestor, BUSINESS_KNOWLEDGE_TYPES, GOVERNS_SOURCE_TYPES, CODE_NODE_TYPES2, MEASURABLE_TYPES, BusinessKnowledgeIngestor, CODE_NODE_TYPES3, DecisionIngestor, REQUIREMENT_SECTIONS, SECTION_HEADING_RE, NUMBERED_ITEM_RE, CODE_NODE_TYPES4, RequirementIngestor, MermaidParser, D2Parser, PlantUmlParser, DIAGRAM_EXTENSIONS, SKIP_DIRS, DiagramParser, HEURISTIC_PATTERNS, SCANNABLE_TYPES, KnowledgeLinker, StructuralDriftDetector, BUSINESS_NODE_TYPES, KnowledgeStagingAggregator, SKIP_DIRS2, EXT_TO_LANGUAGE, SKIP_EXTENSIONS2, EXTRACTOR_EDGE_TYPE, ExtractionRunner, PATTERNS, TestDescriptionExtractor, EnumConstantExtractor, ValidationRuleExtractor, ApiPathExtractor, ALL_EXTRACTORS, ImageAnalysisExtractor, KNOWLEDGE_NODE_TYPES, SIMILARITY_THRESHOLD, SEVERITY_MAP, ContradictionDetector, KNOWLEDGE_TYPES, CODE_TYPES2, KNOWLEDGE_EDGE_TYPES, CoverageScorer, VALID_BUSINESS_TYPES, DEFAULT_MAX_DOCS, MAX_COLLISION_SUFFIX, KnowledgeDocMaterializer, BUSINESS_NODE_TYPES2, SNAPSHOT_NODE_TYPES, KnowledgePipelineRunner, CODE_NODE_TYPES5, RETRYABLE_STATUSES, SANITIZE_RULES, SyncManager, SUMMARIZE_PROMPT, JiraConnector, SlackConnector, ConfluenceConnector, CIConnector, CONSTRAINT_KEYWORDS, FigmaConnector, MIN_CONTENT_LENGTH, CONCEPT_ITEM_TYPES, MiroConnector, STOP_WORDS, FusionLayer, CODE_NODE_TYPES6, GraphEntropyAdapter, GraphComplexityAdapter, GraphCouplingAdapter, DEFAULT_THRESHOLD, DEFAULT_METRICS, RECOGNIZED_METRICS, GraphAnomalyAdapter, INTENTS, SIGNAL_WEIGHTS, INTENT_SIGNALS, IntentClassifier, INTENT_KEYWORDS, STOP_WORDS2, PASCAL_OR_CAMEL_RE, FILE_PATH_RE, QUOTED_RE, EntityExtractor, EntityResolver, ResponseFormatter, CompositeProbabilityStrategy, DEFAULT_PROBABILITY_FLOOR, DEFAULT_MAX_DEPTH, CascadeSimulator, ENTITY_REQUIRED_INTENTS, classifier, extractor, formatter, PHASE_NODE_TYPES, CODE_NODE_TYPES7, Assembler, GraphConstraintAdapter, DesignIngestor, DesignConstraintAdapter, GraphFeedbackAdapter, DEFAULT_EDGE_TYPES, TaskIndependenceAnalyzer, ConflictPredictor, VERSION;
 var init_dist = __esm({
   "../graph/dist/index.mjs"() {
     NODE_TYPES = [
@@ -1000,7 +1470,7 @@ var init_dist = __esm({
       "build",
       "test_result",
       "execution_outcome",
-      // Observability (future)
+      // Observability — reserved for future tracing/metrics integration
       "span",
       "metric",
       "log",
@@ -1047,7 +1517,7 @@ var init_dist = __esm({
       "triggered_by",
       "failed_in",
       "outcome_of",
-      // Execution relationships (future)
+      // Execution relationships — reserved for future observability integration
       "executed_by",
       "measured_by",
       // Design relationships
@@ -1238,8 +1708,15 @@ var init_dist = __esm({
         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 });
@@ -1552,9 +2029,10 @@ var init_dist = __esm({
         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) {
@@ -1564,7 +2042,8 @@ var init_dist = __esm({
         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);
@@ -1575,7 +2054,8 @@ var init_dist = __esm({
         }
         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 {
           }
@@ -1589,11 +2069,12 @@ var init_dist = __esm({
           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 = {
@@ -2631,6 +3112,112 @@ var init_dist = __esm({
         return results;
       }
     };
+    CODE_NODE_TYPES3 = [
+      "file",
+      "function",
+      "class",
+      "method",
+      "interface",
+      "variable"
+    ];
+    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));
+      }
+    };
     REQUIREMENT_SECTIONS = [
       "Observable Truths",
       "Success Criteria",
@@ -2638,7 +3225,7 @@ var init_dist = __esm({
     ];
     SECTION_HEADING_RE = /^#{2,3}\s+(.+)$/;
     NUMBERED_ITEM_RE = /^\s*(\d+)\.\s+(.+)$/;
-    CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
+    CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
     RequirementIngestor = class {
       constructor(store) {
         this.store = store;
@@ -2656,8 +3243,8 @@ var init_dist = __esm({
         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);
         }
@@ -2676,11 +3263,11 @@ var init_dist = __esm({
         };
       }
       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 };
         }
@@ -2697,7 +3284,7 @@ var init_dist = __esm({
         this.store.addNode({
           id: specNodeId,
           type: "document",
-          name: path5.basename(specPath),
+          name: path6.basename(specPath),
           path: specPath,
           metadata: { featureName }
         });
@@ -2812,9 +3399,9 @@ var init_dist = __esm({
         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,
@@ -2843,7 +3430,7 @@ var init_dist = __esm({
        */
       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;
@@ -2872,269 +3459,63 @@ var init_dist = __esm({
       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";
+    };
+    D2Parser = class {
+      canParse(_content, ext) {
+        return ext === ".d2";
       }
-      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 }
+      parse(content, _filePath) {
+        const trimmed = content.trim();
+        if (!trimmed) return emptyResult3();
+        const state = {
+          entities: /* @__PURE__ */ new Map(),
+          relationships: [],
+          braceDepth: 0
         };
-      }
-      isDecisionNode(content, nodeId) {
-        const decisionRegex = new RegExp(`${nodeId}\\s*\\{`);
-        return decisionRegex.test(content);
-      }
-      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);
+        for (const line of trimmed.split("\n")) {
+          processD2Line(line.trim(), state);
         }
         return {
-          entities,
-          relationships,
-          metadata: { format: "mermaid", diagramType }
+          entities: Array.from(state.entities.values()),
+          relationships: state.relationships,
+          metadata: { format: "d2", diagramType: "architecture" }
         };
       }
     };
-    D2Parser = class {
+    PlantUmlParser = class {
       canParse(_content, ext) {
-        return ext === ".d2";
+        return ext === ".puml" || ext === ".plantuml";
       }
       parse(content, _filePath) {
         const trimmed = content.trim();
-        if (!trimmed) {
-          return {
-            entities: [],
-            relationships: [],
-            metadata: { format: "d2", diagramType: "architecture" }
-          };
-        }
+        if (!trimmed) return emptyResult4();
+        const diagramType = detectDiagramType2(trimmed);
         const entities = /* @__PURE__ */ new Map();
-        const relationships = [];
-        let 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 });
-            }
-          }
-        }
-        return {
-          entities: Array.from(entities.values()),
-          relationships,
-          metadata: { format: "d2", diagramType: "architecture" }
-        };
-      }
-    };
-    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);
-        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";
-      }
     };
     DIAGRAM_EXTENSIONS = /* @__PURE__ */ new Set([".mmd", ".mermaid", ".d2", ".puml", ".plantuml"]);
+    SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".harness"]);
     DiagramParser = class {
       constructor(store) {
         this.store = store;
@@ -3146,7 +3527,7 @@ var init_dist = __esm({
         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);
@@ -3166,41 +3547,13 @@ var init_dist = __esm({
         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)}`
@@ -3216,25 +3569,64 @@ var init_dist = __esm({
           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));
               }
             }
           }
@@ -3381,8 +3773,10 @@ var init_dist = __esm({
         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;
       }
@@ -3416,8 +3810,8 @@ var init_dist = __esm({
        */
       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,
@@ -3430,16 +3824,16 @@ var init_dist = __esm({
             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,
@@ -3452,7 +3846,7 @@ var init_dist = __esm({
             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.
@@ -3554,6 +3948,14 @@ var init_dist = __esm({
         return { findings, driftScore, summary };
       }
     };
+    BUSINESS_NODE_TYPES = [
+      "business_concept",
+      "business_rule",
+      "business_process",
+      "business_term",
+      "business_metric",
+      "business_fact"
+    ];
     KnowledgeStagingAggregator = class {
       constructor(projectDir) {
         this.projectDir = projectDir;
@@ -3572,55 +3974,153 @@ var init_dist = __esm({
         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");
       }
     };
-    SKIP_DIRS = /* @__PURE__ */ new Set([
+    SKIP_DIRS2 = /* @__PURE__ */ new Set([
       "node_modules",
       "dist",
       "target",
@@ -3679,7 +4179,7 @@ var init_dist = __esm({
         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) {
@@ -3688,17 +4188,17 @@ var init_dist = __esm({
         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 {
@@ -3735,9 +4235,9 @@ var init_dist = __esm({
       }
       /** 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) {
@@ -3809,13 +4309,13 @@ var init_dist = __esm({
         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);
@@ -4926,57 +5426,9 @@ var init_dist = __esm({
         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)}`
@@ -4992,6 +5444,68 @@ var init_dist = __esm({
           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;
+      }
     };
     KNOWLEDGE_NODE_TYPES = [
       "business_fact",
@@ -5000,89 +5514,35 @@ var init_dist = __esm({
       "business_term",
       "business_concept",
       "business_metric",
+      "decision",
       "design_token",
       "design_constraint",
       "aesthetic_intent",
       "image_annotation"
     ];
     SIMILARITY_THRESHOLD = 0.8;
+    SEVERITY_MAP = {
+      value_mismatch: "critical",
+      definition_conflict: "high",
+      status_divergence: "medium",
+      temporal_conflict: "medium"
+    };
     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}`
-          });
+        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
         };
-        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);
-            }
-          }
-        }
-        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);
-              }
-            }
-          }
-        }
-        return { contradictions, sourcePairCounts, totalChecked: nodes.length };
       }
     };
     KNOWLEDGE_TYPES = KNOWLEDGE_NODE_TYPES;
@@ -5107,61 +5567,15 @@ var init_dist = __esm({
     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 {
@@ -5181,7 +5595,161 @@ var init_dist = __esm({
         return parts[0] ?? "unclassified";
       }
     };
-    BUSINESS_NODE_TYPES = [
+    VALID_BUSINESS_TYPES = /* @__PURE__ */ new Set([
+      "business_rule",
+      "business_process",
+      "business_concept",
+      "business_term",
+      "business_metric"
+    ]);
+    DEFAULT_MAX_DOCS = 50;
+    MAX_COLLISION_SUFFIX = 10;
+    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";
+      }
+    };
+    BUSINESS_NODE_TYPES2 = [
       "business_concept",
       "business_rule",
       "business_process",
@@ -5190,7 +5758,8 @@ var init_dist = __esm({
       "business_fact"
     ];
     SNAPSHOT_NODE_TYPES = [
-      ...BUSINESS_NODE_TYPES,
+      ...BUSINESS_NODE_TYPES2,
+      "decision",
       "design_token",
       "design_constraint",
       "aesthetic_intent",
@@ -5202,51 +5771,98 @@ var init_dist = __esm({
       }
       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);
@@ -5260,7 +5876,7 @@ var init_dist = __esm({
           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 {
@@ -5275,6 +5891,21 @@ var init_dist = __esm({
             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 {
@@ -5282,6 +5913,7 @@ var init_dist = __esm({
           diagrams: diagramResult.nodesAdded,
           linkerFacts: linkResult.factsCreated,
           businessKnowledge: bkResult.nodesAdded,
+          decisions: decisionResult.nodesAdded,
           images: imageCount
         };
       }
@@ -5308,14 +5940,14 @@ var init_dist = __esm({
       }
       // ── 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":
@@ -5333,6 +5965,22 @@ var init_dist = __esm({
               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");
@@ -5365,7 +6013,7 @@ var init_dist = __esm({
         return "fail";
       }
     };
-    CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
+    CODE_NODE_TYPES5 = ["file", "function", "class", "method", "interface", "variable"];
     RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
     SANITIZE_RULES = [
       // Strip XML/HTML-like instruction tags that could be interpreted as system prompts
@@ -5392,7 +6040,7 @@ var init_dist = __esm({
     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();
@@ -5457,15 +6105,15 @@ var init_dist = __esm({
       }
       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");
       }
     };
     SUMMARIZE_PROMPT = `Summarize the following content to fit within the specified length.
@@ -5503,6 +6151,14 @@ Content to summarize:
             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 {
@@ -5756,6 +6412,14 @@ ${replyLines.join("\n")}`;
         }
         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,
@@ -5860,7 +6524,7 @@ ${replyLines.join("\n")}`;
         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
           );
@@ -5927,35 +6591,9 @@ ${replyLines.join("\n")}`;
       }
       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;
@@ -5975,6 +6613,17 @@ ${replyLines.join("\n")}`;
         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`;
@@ -5982,90 +6631,112 @@ ${replyLines.join("\n")}`;
         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 };
+      }
     };
     MIN_CONTENT_LENGTH = 10;
     CONCEPT_ITEM_TYPES = /* @__PURE__ */ new Set(["sticky_note", "text"]);
@@ -6078,36 +6749,9 @@ ${replyLines.join("\n")}`;
       }
       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 = [];
@@ -6307,7 +6951,7 @@ ${replyLines.join("\n")}`;
         return 0;
       }
     };
-    CODE_NODE_TYPES5 = ["file", "function", "class", "method", "interface", "variable"];
+    CODE_NODE_TYPES6 = ["file", "function", "class", "method", "interface", "variable"];
     GraphEntropyAdapter = class {
       constructor(store) {
         this.store = store;
@@ -6387,7 +7031,7 @@ ${replyLines.join("\n")}`;
       }
       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";
@@ -6423,7 +7067,7 @@ ${replyLines.join("\n")}`;
       }
       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)) {
@@ -7240,9 +7884,9 @@ ${replyLines.join("\n")}`;
       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;
       }
@@ -7312,8 +7956,8 @@ ${replyLines.join("\n")}`;
           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)) {
@@ -7390,13 +8034,13 @@ ${replyLines.join("\n")}`;
         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;
@@ -7666,7 +8310,7 @@ ${replyLines.join("\n")}`;
       debug: ["failure", "learning", "function", "method"],
       plan: ["adr", "document", "module", "layer"]
     };
-    CODE_NODE_TYPES6 = /* @__PURE__ */ new Set([
+    CODE_NODE_TYPES7 = /* @__PURE__ */ new Set([
       "file",
       "function",
       "class",
@@ -7876,7 +8520,7 @@ ${replyLines.join("\n")}`;
        */
       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 = [];
@@ -8021,8 +8665,8 @@ ${replyLines.join("\n")}`;
       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 };
@@ -8252,10 +8896,10 @@ ${replyLines.join("\n")}`;
             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);
               }
             }
           }
@@ -8628,7 +9272,7 @@ ${replyLines.join("\n")}`;
         return parts.join(" ");
       }
     };
-    VERSION = "0.4.3";
+    VERSION = "0.6.0";
   }
 });
 
@@ -8655,6 +9299,7 @@ export {
   TopologicalLinker,
   KnowledgeIngestor,
   BusinessKnowledgeIngestor,
+  DecisionIngestor,
   RequirementIngestor,
   MermaidParser,
   D2Parser,
@@ -8673,6 +9318,7 @@ export {
   ImageAnalysisExtractor,
   ContradictionDetector,
   CoverageScorer,
+  KnowledgeDocMaterializer,
   KnowledgePipelineRunner,
   linkToCode,
   SyncManager,