@swarmvaultai/engine 0.1.18 → 0.1.19

package/dist/index.js

@@ -38,7 +38,7 @@ function buildManagedBlock(target) {
     "- Read `swarmvault.schema.md` before compile or query style work. It is the canonical schema path.",
     "- Treat `raw/` as immutable source input.",
     "- Treat `wiki/` as generated markdown owned by the agent and compiler workflow.",
-    "- Read `wiki/index.md` before broad file searching when answering SwarmVault questions.",
+    "- Read `wiki/graph/report.md` before broad file searching when it exists; otherwise start with `wiki/index.md`.",
     "- Preserve frontmatter fields including `page_id`, `source_ids`, `node_ids`, `freshness`, and `source_hashes`.",
     "- Save high-value answers back into `wiki/outputs/` instead of leaving them only in chat.",
     "- Prefer `swarmvault ingest`, `swarmvault compile`, `swarmvault query`, and `swarmvault lint` for SwarmVault maintenance tasks.",
@@ -148,6 +148,16 @@ import { createRequire } from "module";
 import path2 from "path";
 var require2 = createRequire(import.meta.url);
 var TREE_SITTER_PACKAGE_ROOT = path2.dirname(path2.dirname(require2.resolve("@vscode/tree-sitter-wasm")));
+var RATIONALE_MARKERS = ["NOTE:", "IMPORTANT:", "HACK:", "WHY:", "RATIONALE:"];
+function stripKnownCommentPrefix(line) {
+  let next = line.trim();
+  for (const prefix of ["/**", "/*", "*/", "//", "#", "--", "*"]) {
+    if (next.startsWith(prefix)) {
+      next = next.slice(prefix.length).trimStart();
+    }
+  }
+  return next;
+}
 var treeSitterModulePromise;
 var treeSitterInitPromise;
 var languageCache = /* @__PURE__ */ new Map();
@@ -279,9 +289,107 @@ function finalizeCodeAnalysis(manifest, language, imports, draftSymbols, exportL
     diagnostics
   };
 }
+function cleanCommentText(value) {
+  return normalizeWhitespace(
+    value.split(/\r?\n/).map((line) => stripKnownCommentPrefix(line)).join("\n").trim()
+  );
+}
+function normalizeRationaleText(value) {
+  let next = normalizeWhitespace(value.trim());
+  const upper = next.toUpperCase();
+  for (const marker of RATIONALE_MARKERS) {
+    if (upper.startsWith(marker)) {
+      next = next.slice(marker.length).trimStart();
+      break;
+    }
+  }
+  return next;
+}
+function rationaleKindFromText(text) {
+  const upper = text.toUpperCase();
+  return RATIONALE_MARKERS.some((marker) => upper.startsWith(marker)) ? "marker" : "comment";
+}
+function isLikelyRationaleText(value) {
+  if (value.length < 20) {
+    return false;
+  }
+  const upper = value.toUpperCase();
+  if (RATIONALE_MARKERS.some((marker) => upper.startsWith(marker))) {
+    return true;
+  }
+  const lower = value.toLowerCase();
+  return ["why", "because", "tradeoff", "important", "avoid", "workaround", "reason", "so that", "in order to"].some(
+    (needle) => lower.includes(needle)
+  );
+}
+function makeRationale(manifest, index, text, kind, symbolName) {
+  const normalized = normalizeRationaleText(cleanCommentText(text));
+  if (!isLikelyRationaleText(normalized)) {
+    return null;
+  }
+  return {
+    id: `rationale:${manifest.sourceId}:${index}`,
+    text: truncate(normalized, 280),
+    citation: manifest.sourceId,
+    kind,
+    symbolName
+  };
+}
 function nodeText(node) {
   return node?.text ?? "";
 }
+function moduleDocstringNode(rootNode) {
+  const first = rootNode.namedChildren[0];
+  if (!first || first.type !== "expression_statement") {
+    return null;
+  }
+  return first.namedChildren.find((child) => child?.type === "string" || child?.type === "concatenated_string") ?? null;
+}
+function bodyDocstringNode(node) {
+  const body = node?.childForFieldName("body");
+  if (!body) {
+    return null;
+  }
+  const first = body.namedChildren[0];
+  if (!first || first.type !== "expression_statement") {
+    return null;
+  }
+  return first.namedChildren.find((child) => child?.type === "string" || child?.type === "concatenated_string") ?? null;
+}
+function unquoteDocstringText(value) {
+  return value.trim().replace(/^("""|'''|"|')/, "").replace(/("""|'''|"|')$/, "");
+}
+function commentNodes(rootNode) {
+  return rootNode.descendantsOfType("comment").filter((node) => node !== null);
+}
+function extractTreeSitterRationales(manifest, language, rootNode) {
+  const results = [];
+  let index = 0;
+  const push = (text, kind, symbolName) => {
+    const rationale = makeRationale(manifest, index + 1, text, kind, symbolName);
+    if (rationale) {
+      results.push(rationale);
+      index += 1;
+    }
+  };
+  if (language === "python") {
+    const moduleDocstring = moduleDocstringNode(rootNode);
+    if (moduleDocstring) {
+      push(unquoteDocstringText(moduleDocstring.text), "docstring");
+    }
+    for (const node of rootNode.descendantsOfType(["class_definition", "function_definition"]).filter((item) => item !== null)) {
+      const name = extractIdentifier(node.childForFieldName("name"));
+      const docstring = bodyDocstringNode(node);
+      if (docstring) {
+        push(unquoteDocstringText(docstring.text), "docstring", name);
+      }
+    }
+  }
+  for (const commentNode of commentNodes(rootNode)) {
+    push(commentNode.text, rationaleKindFromText(commentNode.text));
+  }
+  return uniqueBy(results, (item) => `${item.symbolName ?? ""}:${item.text.toLowerCase()}`);
+}
 function findNamedChild(node, type) {
   return node?.namedChildren.find((child) => child?.type === type) ?? null;
 }
@@ -950,41 +1058,45 @@ async function analyzeTreeSitterCode(manifest, content, language) {
   parser.setLanguage(await loadLanguage(language));
   const tree = parser.parse(content);
   if (!tree) {
-    return finalizeCodeAnalysis(
-      manifest,
-      language,
-      [],
-      [],
-      [],
-      [
-        {
-          code: 9e3,
-          category: "error",
-          message: `Failed to parse ${language} source.`,
-          line: 1,
-          column: 1
-        }
-      ]
-    );
+    return {
+      code: finalizeCodeAnalysis(
+        manifest,
+        language,
+        [],
+        [],
+        [],
+        [
+          {
+            code: 9e3,
+            category: "error",
+            message: `Failed to parse ${language} source.`,
+            line: 1,
+            column: 1
+          }
+        ]
+      ),
+      rationales: []
+    };
   }
   try {
     const diagnostics = diagnosticsFromTree(tree.rootNode);
+    const rationales = extractTreeSitterRationales(manifest, language, tree.rootNode);
     switch (language) {
       case "python":
-        return pythonCodeAnalysis(manifest, tree.rootNode, diagnostics);
+        return { code: pythonCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "go":
-        return goCodeAnalysis(manifest, tree.rootNode, diagnostics);
+        return { code: goCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "rust":
-        return rustCodeAnalysis(manifest, tree.rootNode, diagnostics);
+        return { code: rustCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "java":
-        return javaCodeAnalysis(manifest, tree.rootNode, diagnostics);
+        return { code: javaCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "csharp":
-        return csharpCodeAnalysis(manifest, tree.rootNode, diagnostics);
+        return { code: csharpCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "php":
-        return phpCodeAnalysis(manifest, tree.rootNode, diagnostics);
+        return { code: phpCodeAnalysis(manifest, tree.rootNode, diagnostics), rationales };
       case "c":
       case "cpp":
-        return cFamilyCodeAnalysis(manifest, language, tree.rootNode, diagnostics);
+        return { code: cFamilyCodeAnalysis(manifest, language, tree.rootNode, diagnostics), rationales };
     }
   } finally {
     tree.delete();
@@ -1183,6 +1295,62 @@ function normalizeSymbolReference2(value) {
   const lastSegment = trimmed.split(/::|\./).filter(Boolean).at(-1) ?? trimmed;
   return lastSegment.replace(/[,:;]+$/g, "").trim();
 }
+var RATIONALE_MARKERS2 = ["NOTE:", "IMPORTANT:", "HACK:", "WHY:", "RATIONALE:"];
+function stripKnownCommentPrefix2(line) {
+  let next = line.trim();
+  for (const prefix of ["/**", "/*", "*/", "//", "#", "*"]) {
+    if (next.startsWith(prefix)) {
+      next = next.slice(prefix.length).trimStart();
+    }
+  }
+  return next;
+}
+function cleanCommentText2(value) {
+  return normalizeWhitespace(
+    value.split(/\r?\n/).map((line) => stripKnownCommentPrefix2(line)).join("\n").trim()
+  );
+}
+function rationaleKindFromText2(text) {
+  const upper = text.toUpperCase();
+  return RATIONALE_MARKERS2.some((marker) => upper.startsWith(marker)) ? "marker" : "comment";
+}
+function normalizeRationaleText2(value) {
+  let next = normalizeWhitespace(value.trim());
+  const upper = next.toUpperCase();
+  for (const marker of RATIONALE_MARKERS2) {
+    if (upper.startsWith(marker)) {
+      next = next.slice(marker.length).trimStart();
+      break;
+    }
+  }
+  return next;
+}
+function isLikelyRationaleText2(value) {
+  if (value.length < 20) {
+    return false;
+  }
+  const upper = value.toUpperCase();
+  if (RATIONALE_MARKERS2.some((marker) => upper.startsWith(marker))) {
+    return true;
+  }
+  const lower = value.toLowerCase();
+  return ["why", "because", "tradeoff", "important", "avoid", "workaround", "reason", "so that", "in order to"].some(
+    (needle) => lower.includes(needle)
+  );
+}
+function makeRationale2(manifest, index, text, kind, symbolName) {
+  const normalized = normalizeRationaleText2(cleanCommentText2(text));
+  if (!isLikelyRationaleText2(normalized)) {
+    return null;
+  }
+  return {
+    id: `rationale:${manifest.sourceId}:${index}`,
+    text: truncate(normalized, 280),
+    citation: manifest.sourceId,
+    kind,
+    symbolName
+  };
+}
 function stripCodeExtension2(filePath) {
   return filePath.replace(/\.(?:[cm]?jsx?|tsx?|mts|cts|py|go|rs|java|cs|php|c|cc|cpp|cxx|h|hh|hpp|hxx)$/i, "");
 }
@@ -1231,6 +1399,46 @@ function finalizeCodeAnalysis2(manifest, language, imports, draftSymbols, export
     diagnostics
   };
 }
+function statementRationaleSymbolName(statement) {
+  if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) || ts.isEnumDeclaration(statement)) && statement.name) {
+    return statement.name.text;
+  }
+  if (ts.isTypeAliasDeclaration(statement)) {
+    return statement.name.text;
+  }
+  if (ts.isVariableStatement(statement)) {
+    const first = statement.declarationList.declarations[0];
+    return first && ts.isIdentifier(first.name) ? first.name.text : void 0;
+  }
+  return void 0;
+}
+function extractTypeScriptRationales(manifest, content, sourceFile) {
+  const rationales = [];
+  let index = 0;
+  const pushRationale = (rawText, symbolName, kind) => {
+    const rationale = makeRationale2(manifest, index + 1, rawText, kind ?? rationaleKindFromText2(rawText), symbolName);
+    if (rationale) {
+      rationales.push(rationale);
+      index += 1;
+    }
+  };
+  const firstStatement = sourceFile.statements[0];
+  if (firstStatement) {
+    for (const range of ts.getLeadingCommentRanges(content, firstStatement.getFullStart()) ?? []) {
+      pushRationale(content.slice(range.pos, range.end));
+    }
+  }
+  for (const statement of sourceFile.statements) {
+    const symbolName = statementRationaleSymbolName(statement);
+    for (const jsDoc of statement.jsDoc ?? []) {
+      pushRationale(jsDoc.getText(sourceFile), symbolName, "docstring");
+    }
+    for (const range of ts.getLeadingCommentRanges(content, statement.getFullStart()) ?? []) {
+      pushRationale(content.slice(range.pos, range.end), symbolName);
+    }
+  }
+  return uniqueBy(rationales, (item) => `${item.symbolName ?? ""}:${item.text.toLowerCase()}`);
+}
 function analyzeTypeScriptLikeCode(manifest, content) {
   const language = manifest.language ?? inferCodeLanguage(manifest.originalPath ?? manifest.storedPath, manifest.mimeType) ?? "typescript";
   const sourceFile = ts.createSourceFile(
@@ -1443,7 +1651,10 @@ function analyzeTypeScriptLikeCode(manifest, content) {
       column: (position?.character ?? 0) + 1
     };
   });
-  return finalizeCodeAnalysis2(manifest, language, imports, draftSymbols, exportLabels, diagnostics);
+  return {
+    code: finalizeCodeAnalysis2(manifest, language, imports, draftSymbols, exportLabels, diagnostics),
+    rationales: extractTypeScriptRationales(manifest, content, sourceFile)
+  };
 }
 function inferCodeLanguage(filePath, mimeType = "") {
   const extension = path3.extname(filePath).toLowerCase();
@@ -1806,9 +2017,9 @@ function escapeRegExp2(value) {
 }
 async function analyzeCodeSource(manifest, extractedText, schemaHash) {
   const language = manifest.language ?? inferCodeLanguage(manifest.originalPath ?? manifest.storedPath, manifest.mimeType) ?? "typescript";
-  const code = language === "javascript" || language === "jsx" || language === "typescript" || language === "tsx" ? analyzeTypeScriptLikeCode(manifest, extractedText) : await analyzeTreeSitterCode(manifest, extractedText, language);
+  const { code, rationales } = language === "javascript" || language === "jsx" || language === "typescript" || language === "tsx" ? analyzeTypeScriptLikeCode(manifest, extractedText) : await analyzeTreeSitterCode(manifest, extractedText, language);
   return {
-    analysisVersion: 3,
+    analysisVersion: 4,
     sourceId: manifest.sourceId,
     sourceHash: manifest.contentHash,
     schemaHash,
@@ -1818,6 +2029,7 @@ async function analyzeCodeSource(manifest, extractedText, schemaHash) {
     entities: [],
     claims: codeClaims(manifest, code),
     questions: codeQuestions(manifest, code),
+    rationales,
     code,
     producedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
@@ -2871,7 +3083,7 @@ import { z as z6 } from "zod";
 // src/analysis.ts
 import path7 from "path";
 import { z } from "zod";
-var ANALYSIS_FORMAT_VERSION = 3;
+var ANALYSIS_FORMAT_VERSION = 4;
 var sourceAnalysisSchema = z.object({
   title: z.string().min(1),
   summary: z.string().min(1),
@@ -2989,6 +3201,7 @@ function heuristicAnalysis(manifest, text, schemaHash) {
       citation: manifest.sourceId
     })),
     questions: concepts.slice(0, 3).map((term) => `How does ${term.name} relate to ${manifest.title}?`),
+    rationales: [],
     producedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
@@ -3042,6 +3255,7 @@ ${truncate(text, 18e3)}`
       citation: claim.citation
     })),
     questions: parsed.questions,
+    rationales: [],
     producedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
@@ -3067,6 +3281,7 @@ async function analyzeSource(manifest, extractedText, provider, paths, schema) {
       entities: [],
       claims: [],
       questions: [],
+      rationales: [],
       producedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   } else if (provider.type === "heuristic") {
@@ -3695,6 +3910,309 @@ async function runDeepLint(rootDir, structuralFindings, options = {}) {
   );
 }
 
+// src/graph-tools.ts
+function normalizeTarget(value) {
+  return normalizeWhitespace(value).toLowerCase();
+}
+function nodeById(graph) {
+  return new Map(graph.nodes.map((node) => [node.id, node]));
+}
+function pageById(graph) {
+  return new Map(graph.pages.map((page) => [page.id, page]));
+}
+function scoreMatch(query, candidate) {
+  const normalizedQuery = normalizeTarget(query);
+  const normalizedCandidate = normalizeTarget(candidate);
+  if (!normalizedQuery || !normalizedCandidate) {
+    return 0;
+  }
+  if (normalizedCandidate === normalizedQuery) {
+    return 100;
+  }
+  if (normalizedCandidate.startsWith(normalizedQuery)) {
+    return 80;
+  }
+  if (normalizedCandidate.includes(normalizedQuery)) {
+    return 60;
+  }
+  const queryTokens = normalizedQuery.split(/\s+/).filter(Boolean);
+  const candidateTokens = new Set(normalizedCandidate.split(/\s+/).filter(Boolean));
+  const overlap = queryTokens.filter((token) => candidateTokens.has(token)).length;
+  return overlap ? overlap * 10 : 0;
+}
+function primaryNodeForPage(graph, page) {
+  const byId = nodeById(graph);
+  return page.nodeIds.map((nodeId) => byId.get(nodeId)).find((node) => Boolean(node));
+}
+function pageSearchMatches(graph, question, searchResults) {
+  const pages = pageById(graph);
+  return searchResults.map((result) => {
+    const page = pages.get(result.pageId);
+    const score = Math.max(scoreMatch(question, result.title), scoreMatch(question, result.path));
+    if (!page || score <= 0) {
+      return null;
+    }
+    return {
+      type: "page",
+      id: page.id,
+      label: page.title,
+      score
+    };
+  }).filter((match) => Boolean(match));
+}
+function nodeMatches(graph, query) {
+  return graph.nodes.map((node) => ({
+    type: "node",
+    id: node.id,
+    label: node.label,
+    score: Math.max(scoreMatch(query, node.label), scoreMatch(query, node.id))
+  })).filter((match) => match.score > 0).sort((left, right) => right.score - left.score || left.label.localeCompare(right.label));
+}
+function graphAdjacency(graph) {
+  const adjacency = /* @__PURE__ */ new Map();
+  const push = (nodeId, item) => {
+    if (!adjacency.has(nodeId)) {
+      adjacency.set(nodeId, []);
+    }
+    adjacency.get(nodeId)?.push(item);
+  };
+  for (const edge of graph.edges) {
+    push(edge.source, { edge, nodeId: edge.target, direction: "outgoing" });
+    push(edge.target, { edge, nodeId: edge.source, direction: "incoming" });
+  }
+  for (const [nodeId, items] of adjacency.entries()) {
+    items.sort((left, right) => right.edge.confidence - left.edge.confidence || left.edge.relation.localeCompare(right.edge.relation));
+    adjacency.set(nodeId, items);
+  }
+  return adjacency;
+}
+function resolveNode(graph, target) {
+  const normalized = normalizeTarget(target);
+  const byId = nodeById(graph);
+  if (byId.has(target)) {
+    return byId.get(target);
+  }
+  const exact = graph.nodes.find((node) => normalizeTarget(node.label) === normalized || normalizeTarget(node.id) === normalized);
+  if (exact) {
+    return exact;
+  }
+  const pages = graph.pages.map((page) => ({
+    page,
+    score: Math.max(scoreMatch(target, page.title), scoreMatch(target, page.path))
+  })).filter((item) => item.score > 0).sort((left, right) => right.score - left.score || left.page.title.localeCompare(right.page.title));
+  if (pages[0]) {
+    return primaryNodeForPage(graph, pages[0].page);
+  }
+  return graph.nodes.map((node) => ({ node, score: Math.max(scoreMatch(target, node.label), scoreMatch(target, node.id)) })).filter((item) => item.score > 0).sort((left, right) => right.score - left.score || left.node.label.localeCompare(right.node.label))[0]?.node;
+}
+function communityLabel(graph, communityId) {
+  if (!communityId) {
+    return void 0;
+  }
+  const community = graph.communities?.find((item) => item.id === communityId);
+  return community ? { id: community.id, label: community.label } : void 0;
+}
+function queryGraph(graph, question, searchResults, options) {
+  const traversal = options?.traversal ?? "bfs";
+  const budget = Math.max(3, Math.min(options?.budget ?? 12, 50));
+  const matches = uniqueBy(
+    [...pageSearchMatches(graph, question, searchResults), ...nodeMatches(graph, question)],
+    (match) => `${match.type}:${match.id}`
+  ).sort((left, right) => right.score - left.score || left.label.localeCompare(right.label)).slice(0, 12);
+  const pages = pageById(graph);
+  const seeds = uniqueBy(
+    [
+      ...searchResults.flatMap((result) => pages.get(result.pageId)?.nodeIds ?? []),
+      ...matches.filter((match) => match.type === "node").map((match) => match.id)
+    ],
+    (item) => item
+  ).filter(Boolean);
+  const adjacency = graphAdjacency(graph);
+  const visitedNodeIds = [];
+  const visitedEdgeIds = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Set();
+  const frontier = [...seeds];
+  while (frontier.length && visitedNodeIds.length < budget) {
+    const current = traversal === "dfs" ? frontier.pop() : frontier.shift();
+    if (!current || seen.has(current)) {
+      continue;
+    }
+    seen.add(current);
+    visitedNodeIds.push(current);
+    for (const neighbor of adjacency.get(current) ?? []) {
+      visitedEdgeIds.add(neighbor.edge.id);
+      if (!seen.has(neighbor.nodeId)) {
+        frontier.push(neighbor.nodeId);
+      }
+      if (visitedNodeIds.length + frontier.length >= budget * 2) {
+        break;
+      }
+    }
+  }
+  const nodes = nodeById(graph);
+  const pageIds = uniqueBy(
+    [
+      ...searchResults.map((result) => result.pageId),
+      ...visitedNodeIds.flatMap((nodeId) => {
+        const node = nodes.get(nodeId);
+        return node?.pageId ? [node.pageId] : [];
+      })
+    ],
+    (item) => item
+  );
+  const communities = uniqueBy(
+    visitedNodeIds.map((nodeId) => nodes.get(nodeId)?.communityId).filter((communityId) => Boolean(communityId)),
+    (item) => item
+  );
+  return {
+    question,
+    traversal,
+    seedNodeIds: seeds,
+    seedPageIds: uniqueBy(
+      searchResults.map((result) => result.pageId),
+      (item) => item
+    ),
+    visitedNodeIds,
+    visitedEdgeIds: [...visitedEdgeIds],
+    pageIds,
+    communities,
+    matches,
+    summary: [
+      `Seeds: ${seeds.join(", ") || "none"}`,
+      `Visited nodes: ${visitedNodeIds.length}`,
+      `Visited edges: ${visitedEdgeIds.size}`,
+      `Communities: ${communities.join(", ") || "none"}`,
+      `Pages: ${pageIds.join(", ") || "none"}`
+    ].join("\n")
+  };
+}
+function shortestGraphPath(graph, from, to) {
+  const start = resolveNode(graph, from);
+  const end = resolveNode(graph, to);
+  if (!start || !end) {
+    return {
+      from,
+      to,
+      resolvedFromNodeId: start?.id,
+      resolvedToNodeId: end?.id,
+      found: false,
+      nodeIds: [],
+      edgeIds: [],
+      pageIds: [],
+      summary: "Could not resolve one or both graph targets."
+    };
+  }
+  const adjacency = graphAdjacency(graph);
+  const queue = [start.id];
+  const visited = /* @__PURE__ */ new Set([start.id]);
+  const previous = /* @__PURE__ */ new Map();
+  while (queue.length) {
+    const current2 = queue.shift();
+    if (current2 === end.id) {
+      break;
+    }
+    for (const neighbor of adjacency.get(current2) ?? []) {
+      if (visited.has(neighbor.nodeId)) {
+        continue;
+      }
+      visited.add(neighbor.nodeId);
+      previous.set(neighbor.nodeId, { nodeId: current2, edgeId: neighbor.edge.id });
+      queue.push(neighbor.nodeId);
+    }
+  }
+  if (!visited.has(end.id)) {
+    return {
+      from,
+      to,
+      resolvedFromNodeId: start.id,
+      resolvedToNodeId: end.id,
+      found: false,
+      nodeIds: [],
+      edgeIds: [],
+      pageIds: [],
+      summary: `No path found between ${start.label} and ${end.label}.`
+    };
+  }
+  const nodeIds = [];
+  const edgeIds = [];
+  let current = end.id;
+  while (current !== start.id) {
+    nodeIds.push(current);
+    const prev = previous.get(current);
+    if (!prev) {
+      break;
+    }
+    edgeIds.push(prev.edgeId);
+    current = prev.nodeId;
+  }
+  nodeIds.push(start.id);
+  nodeIds.reverse();
+  edgeIds.reverse();
+  const nodes = nodeById(graph);
+  const pageIds = uniqueBy(
+    nodeIds.flatMap((nodeId) => {
+      const node = nodes.get(nodeId);
+      return node?.pageId ? [node.pageId] : [];
+    }),
+    (item) => item
+  );
+  return {
+    from,
+    to,
+    resolvedFromNodeId: start.id,
+    resolvedToNodeId: end.id,
+    found: true,
+    nodeIds,
+    edgeIds,
+    pageIds,
+    summary: nodeIds.map((nodeId) => nodes.get(nodeId)?.label ?? nodeId).join(" -> ")
+  };
+}
+function explainGraphTarget(graph, target) {
+  const node = resolveNode(graph, target);
+  if (!node) {
+    throw new Error(`Could not resolve graph target: ${target}`);
+  }
+  const pages = pageById(graph);
+  const page = node.pageId ? pages.get(node.pageId) : void 0;
+  const neighbors = [];
+  const nodes = nodeById(graph);
+  for (const neighbor of graphAdjacency(graph).get(node.id) ?? []) {
+    const targetNode = nodes.get(neighbor.nodeId);
+    if (!targetNode) {
+      continue;
+    }
+    neighbors.push({
+      nodeId: targetNode.id,
+      label: targetNode.label,
+      type: targetNode.type,
+      pageId: targetNode.pageId,
+      relation: neighbor.edge.relation,
+      direction: neighbor.direction,
+      confidence: neighbor.edge.confidence,
+      evidenceClass: neighbor.edge.evidenceClass
+    });
+  }
+  neighbors.sort((left, right) => right.confidence - left.confidence || left.label.localeCompare(right.label));
+  return {
+    target,
+    node,
+    page,
+    community: communityLabel(graph, node.communityId),
+    neighbors,
+    summary: [
+      `Node: ${node.label}`,
+      `Type: ${node.type}`,
+      `Community: ${node.communityId ?? "none"}`,
+      `Neighbors: ${neighbors.length}`,
+      `Page: ${page?.path ?? "none"}`
+    ].join("\n")
+  };
+}
+function topGodNodes(graph, limit = 10) {
+  return graph.nodes.filter((node) => node.isGodNode).sort((left, right) => (right.degree ?? 0) - (left.degree ?? 0)).slice(0, limit);
+}
+
 // src/markdown.ts
 import matter3 from "gray-matter";
 function uniqueStrings(values) {
@@ -3719,6 +4237,10 @@ function pagePathFor(kind, slug) {
       return `entities/${slug}.md`;
     case "output":
       return `outputs/${slug}.md`;
+    case "graph_report":
+      return "graph/report.md";
+    case "community_summary":
+      return `graph/communities/${slug}.md`;
     default:
       return `${slug}.md`;
   }
@@ -3729,6 +4251,10 @@ function candidatePagePathFor(kind, slug) {
 function pageLink(page) {
   return `[[${page.path.replace(/\.md$/, "")}|${page.title}]]`;
 }
+function graphNodeLink(node, pagesById) {
+  const page = node.pageId ? pagesById.get(node.pageId) : void 0;
+  return page ? pageLink(page) : `\`${node.label}\``;
+}
 function assetMarkdownPath(assetPath) {
   return `./${assetPath.replace(/^outputs\//, "")}`;
 }
@@ -4084,6 +4610,7 @@ function buildIndexPage(pages, schemaHash, metadata, projectPages = []) {
   const candidates = pages.filter((page) => page.status === "candidate");
   const outputs = pages.filter((page) => page.kind === "output");
   const insights = pages.filter((page) => page.kind === "insight");
+  const graphPages = pages.filter((page) => page.kind === "graph_report" || page.kind === "community_summary");
   return [
     "---",
     "page_id: index",
@@ -4128,6 +4655,10 @@ function buildIndexPage(pages, schemaHash, metadata, projectPages = []) {
     "",
     ...outputs.length ? outputs.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No saved outputs yet."],
     "",
+    "## Graph",
+    "",
+    ...graphPages.length ? graphPages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No graph reports yet."],
+    "",
     "## Projects",
     "",
     ...projectPages.length ? projectPages.map((page) => `- [[${page.path.replace(/\.md$/, "")}|${page.title}]]`) : ["- No projects configured."],
@@ -4167,6 +4698,215 @@ function buildSectionIndex(kind, pages, schemaHash, metadata, projectIds = []) {
     }
   );
 }
+function communityPagePath(communityId) {
+  return pagePathFor("community_summary", communityId.replace(/^community:/, ""));
+}
+function nodeSummary(node) {
+  const degree = typeof node.degree === "number" ? `degree=${node.degree}` : "";
+  const bridge = typeof node.bridgeScore === "number" ? `bridge=${node.bridgeScore}` : "";
+  return [node.type, degree, bridge].filter(Boolean).join(", ");
+}
+function crossCommunityEdges(graph) {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  return graph.edges.filter((edge) => {
+    const source = nodesById.get(edge.source);
+    const target = nodesById.get(edge.target);
+    return source?.communityId && target?.communityId && source.communityId !== target.communityId;
+  }).sort((left, right) => right.confidence - left.confidence || left.relation.localeCompare(right.relation));
+}
+function suggestedGraphQuestions(graph) {
+  const thinCommunities = (graph.communities ?? []).filter((community) => community.nodeIds.length <= 2);
+  const bridgeNodes = graph.nodes.filter((node) => (node.bridgeScore ?? 0) > 0).sort((left, right) => (right.bridgeScore ?? 0) - (left.bridgeScore ?? 0)).slice(0, 3);
+  return uniqueStrings([
+    ...thinCommunities.map((community) => `What sources would strengthen community ${community.label}?`),
+    ...bridgeNodes.map((node) => `Why does ${node.label} connect multiple communities in the vault?`)
+  ]).slice(0, 6);
+}
+function buildGraphReportPage(input) {
+  const pageId = "graph:report";
+  const pathValue = pagePathFor("graph_report", "report");
+  const pagesById = new Map(input.graph.pages.map((page) => [page.id, page]));
+  const nodesById = new Map(input.graph.nodes.map((node) => [node.id, node]));
+  const godNodes = input.graph.nodes.filter((node) => node.isGodNode).sort((left, right) => (right.degree ?? 0) - (left.degree ?? 0)).slice(0, 8);
+  const bridgeNodes = input.graph.nodes.filter((node) => (node.bridgeScore ?? 0) > 0).sort((left, right) => (right.bridgeScore ?? 0) - (left.bridgeScore ?? 0)).slice(0, 8);
+  const surprisingEdges = crossCommunityEdges(input.graph).slice(0, 8);
+  const thinCommunities = (input.graph.communities ?? []).filter((community) => community.nodeIds.length <= 2);
+  const relatedNodeIds = uniqueStrings([...godNodes, ...bridgeNodes].map((node) => node.id));
+  const relatedPageIds = uniqueStrings([
+    ...godNodes.map((node) => node.pageId ?? ""),
+    ...bridgeNodes.map((node) => node.pageId ?? ""),
+    ...input.communityPages.map((page) => page.id)
+  ]);
+  const relatedSourceIds = uniqueStrings(relatedNodeIds.flatMap((nodeId) => nodesById.get(nodeId)?.sourceIds ?? []));
+  const frontmatter = {
+    page_id: pageId,
+    kind: "graph_report",
+    title: "Graph Report",
+    tags: ["graph", "report"],
+    source_ids: relatedSourceIds,
+    project_ids: [],
+    node_ids: relatedNodeIds,
+    freshness: "fresh",
+    status: input.metadata.status,
+    confidence: input.metadata.confidence,
+    created_at: input.metadata.createdAt,
+    updated_at: input.metadata.updatedAt,
+    compiled_from: input.metadata.compiledFrom,
+    managed_by: input.metadata.managedBy,
+    backlinks: [],
+    schema_hash: input.schemaHash,
+    source_hashes: {},
+    related_page_ids: relatedPageIds,
+    related_node_ids: relatedNodeIds,
+    related_source_ids: relatedSourceIds
+  };
+  const body = [
+    "# Graph Report",
+    "",
+    "## Overview",
+    "",
+    `- Nodes: ${input.graph.nodes.length}`,
+    `- Edges: ${input.graph.edges.length}`,
+    `- Pages: ${input.graph.pages.length}`,
+    `- Communities: ${input.graph.communities?.length ?? 0}`,
+    "",
+    "## God Nodes",
+    "",
+    ...godNodes.length ? godNodes.map((node) => `- ${graphNodeLink(node, pagesById)} (${nodeSummary(node)})`) : ["- No high-connectivity nodes detected."],
+    "",
+    "## Bridge Nodes",
+    "",
+    ...bridgeNodes.length ? bridgeNodes.map((node) => `- ${graphNodeLink(node, pagesById)} (${nodeSummary(node)})`) : ["- No cross-community bridge nodes detected."],
+    "",
+    "## Communities",
+    "",
+    ...input.communityPages.length ? input.communityPages.map((page) => `- ${pageLink(page)}`) : ["- No community summaries generated yet."],
+    "",
+    "## Thin Communities",
+    "",
+    ...thinCommunities.length ? thinCommunities.map((community) => `- ${community.label} (${community.nodeIds.length} node(s))`) : ["- No thin communities detected."],
+    "",
+    "## Cross-Community Surprises",
+    "",
+    ...surprisingEdges.length ? surprisingEdges.map((edge) => {
+      const source = nodesById.get(edge.source);
+      const target = nodesById.get(edge.target);
+      return `- ${source ? graphNodeLink(source, pagesById) : `\`${edge.source}\``} ${edge.relation} ${target ? graphNodeLink(target, pagesById) : `\`${edge.target}\``} (${edge.evidenceClass}, ${edge.confidence.toFixed(2)})`;
+    }) : ["- No cross-community links detected."],
+    "",
+    "## Suggested Follow-Up Questions",
+    "",
+    ...suggestedGraphQuestions(input.graph).map((question) => `- ${question}`),
+    ""
+  ].join("\n");
+  return {
+    page: {
+      id: pageId,
+      path: pathValue,
+      title: "Graph Report",
+      kind: "graph_report",
+      sourceIds: relatedSourceIds,
+      projectIds: [],
+      nodeIds: relatedNodeIds,
+      freshness: "fresh",
+      status: input.metadata.status,
+      confidence: input.metadata.confidence,
+      backlinks: [],
+      schemaHash: input.schemaHash,
+      sourceHashes: {},
+      relatedPageIds,
+      relatedNodeIds,
+      relatedSourceIds,
+      createdAt: input.metadata.createdAt,
+      updatedAt: input.metadata.updatedAt,
+      compiledFrom: input.metadata.compiledFrom,
+      managedBy: input.metadata.managedBy
+    },
+    content: matter3.stringify(body, frontmatter)
+  };
+}
+function buildCommunitySummaryPage(input) {
+  const pageId = `graph:${input.community.id}`;
+  const pathValue = communityPagePath(input.community.id);
+  const nodesById = new Map(input.graph.nodes.map((node) => [node.id, node]));
+  const pagesById = new Map(input.graph.pages.map((page) => [page.id, page]));
+  const communityNodes = input.community.nodeIds.map((nodeId) => nodesById.get(nodeId)).filter((node) => Boolean(node));
+  const communityPageIds = uniqueStrings(communityNodes.map((node) => node.pageId ?? ""));
+  const communityPages = communityPageIds.map((id) => pagesById.get(id)).filter((page) => Boolean(page));
+  const externalEdges = input.graph.edges.filter((edge) => {
+    const source = nodesById.get(edge.source);
+    const target = nodesById.get(edge.target);
+    return source?.communityId === input.community.id && target?.communityId && target.communityId !== input.community.id;
+  }).slice(0, 8);
+  const relatedSourceIds = uniqueStrings(communityNodes.flatMap((node) => node.sourceIds));
+  const frontmatter = {
+    page_id: pageId,
+    kind: "community_summary",
+    title: `Community: ${input.community.label}`,
+    tags: ["graph", "community"],
+    source_ids: relatedSourceIds,
+    project_ids: [],
+    node_ids: input.community.nodeIds,
+    freshness: "fresh",
+    status: input.metadata.status,
+    confidence: input.metadata.confidence,
+    created_at: input.metadata.createdAt,
+    updated_at: input.metadata.updatedAt,
+    compiled_from: input.metadata.compiledFrom,
+    managed_by: input.metadata.managedBy,
+    backlinks: ["graph:report"],
+    schema_hash: input.schemaHash,
+    source_hashes: {},
+    related_page_ids: uniqueStrings(["graph:report", ...communityPageIds]),
+    related_node_ids: input.community.nodeIds,
+    related_source_ids: relatedSourceIds
+  };
+  const body = [
+    `# Community: ${input.community.label}`,
+    "",
+    "## Nodes",
+    "",
+    ...communityNodes.map((node) => `- ${graphNodeLink(node, pagesById)} (${nodeSummary(node)})`),
+    "",
+    "## Pages",
+    "",
+    ...communityPages.length ? communityPages.map((page) => `- ${pageLink(page)}`) : ["- No canonical pages linked."],
+    "",
+    "## External Links",
+    "",
+    ...externalEdges.length ? externalEdges.map((edge) => {
+      const source = nodesById.get(edge.source);
+      const target = nodesById.get(edge.target);
+      return `- ${source ? graphNodeLink(source, pagesById) : `\`${edge.source}\``} ${edge.relation} ${target ? graphNodeLink(target, pagesById) : `\`${edge.target}\``} (${edge.evidenceClass})`;
+    }) : ["- No external links detected."],
+    ""
+  ].join("\n");
+  return {
+    page: {
+      id: pageId,
+      path: pathValue,
+      title: `Community: ${input.community.label}`,
+      kind: "community_summary",
+      sourceIds: relatedSourceIds,
+      projectIds: [],
+      nodeIds: input.community.nodeIds,
+      freshness: "fresh",
+      status: input.metadata.status,
+      confidence: input.metadata.confidence,
+      backlinks: ["graph:report"],
+      schemaHash: input.schemaHash,
+      sourceHashes: {},
+      relatedPageIds: uniqueStrings(["graph:report", ...communityPageIds]),
+      relatedNodeIds: input.community.nodeIds,
+      relatedSourceIds,
+      createdAt: input.metadata.createdAt,
+      updatedAt: input.metadata.updatedAt,
+      compiledFrom: input.metadata.compiledFrom,
+      managedBy: input.metadata.managedBy
+    },
+    content: matter3.stringify(body, frontmatter)
+  };
+}
 function buildProjectsIndex(projectPages, schemaHash, metadata) {
   return matter3.stringify(
     [
@@ -5016,7 +5756,7 @@ function toFtsQuery(query) {
   return tokens.join(" OR ");
 }
 function normalizeKind(value) {
-  return value === "index" || value === "source" || value === "module" || value === "concept" || value === "entity" || value === "output" || value === "insight" ? value : void 0;
+  return value === "index" || value === "source" || value === "module" || value === "concept" || value === "entity" || value === "output" || value === "insight" || value === "graph_report" || value === "community_summary" ? value : void 0;
 }
 function normalizeStatus(value) {
   return value === "draft" || value === "candidate" || value === "active" || value === "archived" ? value : void 0;
@@ -5690,7 +6430,8 @@ function candidateActivePath(page) {
   return activeAggregatePath(page.kind, pageSlug(page));
 }
 function buildCommunityId(seed, index) {
-  return `community:${slugify(seed) || `cluster-${index + 1}`}`;
+  const slug = slugify(seed) || "cluster";
+  return `community:${slug}-${index + 1}`;
 }
 function pageHashes(pages) {
   return Object.fromEntries(pages.map((page) => [page.page.id, page.contentHash]));
@@ -5869,6 +6610,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
   const entityMap = /* @__PURE__ */ new Map();
   const moduleMap = /* @__PURE__ */ new Map();
   const symbolMap = /* @__PURE__ */ new Map();
+  const rationaleMap = /* @__PURE__ */ new Map();
   const edges = [];
   const edgesById = /* @__PURE__ */ new Set();
   const pushEdge = (edge) => {
@@ -5900,6 +6642,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
         target: concept.id,
         relation: "mentions",
         status: "extracted",
+        evidenceClass: "extracted",
         confidence: edgeConfidence(analysis.claims, concept.name),
         provenance: [analysis.sourceId]
       });
@@ -5923,6 +6666,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
         target: entity.id,
         relation: "mentions",
         status: "extracted",
+        evidenceClass: "extracted",
         confidence: edgeConfidence(analysis.claims, entity.name),
         provenance: [analysis.sourceId]
       });
@@ -5951,6 +6695,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
         target: moduleId,
         relation: "contains_code",
         status: "extracted",
+        evidenceClass: "extracted",
         confidence: 1,
         provenance: [analysis.sourceId]
       });
@@ -5974,6 +6719,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
           target: symbol.id,
           relation: "defines",
           status: "extracted",
+          evidenceClass: "extracted",
           confidence: 1,
           provenance: [analysis.sourceId]
         });
@@ -5984,12 +6730,39 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
             target: symbol.id,
             relation: "exports",
             status: "extracted",
+            evidenceClass: "extracted",
             confidence: 1,
             provenance: [analysis.sourceId]
           });
         }
       }
       const symbolIdsByName = new Map(analysis.code.symbols.map((symbol) => [symbol.name, symbol.id]));
+      for (const rationale of analysis.rationales) {
+        const targetSymbolId = rationale.symbolName ? symbolIdsByName.get(rationale.symbolName) : void 0;
+        const targetId = targetSymbolId ?? moduleId;
+        rationaleMap.set(rationale.id, {
+          id: rationale.id,
+          type: "rationale",
+          label: truncate(rationale.text, 80),
+          pageId: moduleId,
+          freshness: "fresh",
+          confidence: 1,
+          sourceIds: [analysis.sourceId],
+          projectIds: scopedProjectIdsFromSources([analysis.sourceId], sourceProjects),
+          language: analysis.code.language,
+          moduleId
+        });
+        pushEdge({
+          id: `${rationale.id}->${targetId}:rationale_for`,
+          source: rationale.id,
+          target: targetId,
+          relation: "rationale_for",
+          status: "extracted",
+          evidenceClass: "extracted",
+          confidence: 1,
+          provenance: [analysis.sourceId]
+        });
+      }
       const importedSymbolIdsByName = /* @__PURE__ */ new Map();
       for (const codeImport of analysis.code.imports.filter((item) => !item.isExternal)) {
         const targetSourceId = codeImport.resolvedSourceId;
@@ -6027,6 +6800,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
             target: targetId,
             relation: "calls",
             status: "extracted",
+            evidenceClass: "extracted",
             confidence: 1,
             provenance: [analysis.sourceId]
           });
@@ -6042,6 +6816,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
             target: targetId,
             relation: "extends",
             status: "extracted",
+            evidenceClass: "extracted",
             confidence: 1,
             provenance: [analysis.sourceId]
           });
@@ -6057,6 +6832,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
             target: targetId,
             relation: "implements",
             status: "extracted",
+            evidenceClass: "extracted",
             confidence: 1,
             provenance: [analysis.sourceId]
           });
@@ -6074,6 +6850,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
           target: targetModuleId,
           relation: codeImport.reExport ? "exports" : "imports",
           status: "extracted",
+          evidenceClass: "extracted",
           confidence: 1,
           provenance: [analysis.sourceId, targetSourceId]
         });
@@ -6113,13 +6890,21 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
           target: `source:${negativeClaim.sourceId}`,
           relation: "conflicted_with",
           status: "conflicted",
+          evidenceClass: "ambiguous",
           confidence: conflictConfidence(positiveClaim.claim, negativeClaim.claim),
           provenance: [positiveClaim.sourceId, negativeClaim.sourceId]
         });
       }
     }
   }
-  const graphNodes = [...sourceNodes, ...moduleMap.values(), ...symbolMap.values(), ...conceptMap.values(), ...entityMap.values()];
+  const graphNodes = [
+    ...sourceNodes,
+    ...moduleMap.values(),
+    ...symbolMap.values(),
+    ...rationaleMap.values(),
+    ...conceptMap.values(),
+    ...entityMap.values()
+  ];
   const metrics = deriveGraphMetrics(graphNodes, edges);
   return {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -6130,6 +6915,46 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
     pages
   };
 }
+async function buildGraphOrientationPages(graph, paths, schemaHash) {
+  const communityRecords = [];
+  for (const community of graph.communities ?? []) {
+    const absolutePath = path14.join(paths.wikiDir, "graph", "communities", `${community.id.replace(/^community:/, "")}.md`);
+    communityRecords.push(
+      await buildManagedGraphPage(
+        absolutePath,
+        {
+          managedBy: "system",
+          compiledFrom: uniqueStrings2(
+            community.nodeIds.flatMap((nodeId) => graph.nodes.find((node) => node.id === nodeId)?.sourceIds ?? [])
+          ),
+          confidence: 1
+        },
+        (metadata) => buildCommunitySummaryPage({
+          graph,
+          community,
+          schemaHash,
+          metadata
+        })
+      )
+    );
+  }
+  const reportAbsolutePath = path14.join(paths.wikiDir, "graph", "report.md");
+  const reportRecord = await buildManagedGraphPage(
+    reportAbsolutePath,
+    {
+      managedBy: "system",
+      compiledFrom: uniqueStrings2(graph.pages.flatMap((page) => page.sourceIds)),
+      confidence: 1
+    },
+    (metadata) => buildGraphReportPage({
+      graph,
+      schemaHash,
+      metadata,
+      communityPages: communityRecords.map((record) => record.page)
+    })
+  );
+  return [reportRecord, ...communityRecords];
+}
 async function writePage(wikiDir, relativePath, content, changedPages) {
   const absolutePath = path14.resolve(wikiDir, relativePath);
   const changed = await writeFileIfChanged(absolutePath, content);
@@ -6494,8 +7319,15 @@ async function syncVaultArtifacts(rootDir, input) {
     }
   }
   const compiledPages = records.map((record) => record.page);
-  const allPages = [...compiledPages, ...input.outputPages, ...input.insightPages];
-  const graph = buildGraph(input.manifests, input.analyses, allPages, input.sourceProjects, input.codeIndex);
+  const basePages = [...compiledPages, ...input.outputPages, ...input.insightPages];
+  const baseGraph = buildGraph(input.manifests, input.analyses, basePages, input.sourceProjects, input.codeIndex);
+  const graphOrientationRecords = await buildGraphOrientationPages(baseGraph, paths, globalSchemaHash);
+  records.push(...graphOrientationRecords);
+  const allPages = [...basePages, ...graphOrientationRecords.map((record) => record.page)];
+  const graph = {
+    ...baseGraph,
+    pages: allPages
+  };
   const activeConceptPages = allPages.filter((page) => page.kind === "concept" && page.status !== "candidate");
   const activeEntityPages = allPages.filter((page) => page.kind === "entity" && page.status !== "candidate");
   const modulePages = allPages.filter((page) => page.kind === "module");
@@ -6595,7 +7427,8 @@ async function syncVaultArtifacts(rootDir, input) {
     ["concepts/index.md", "concepts", activeConceptPages],
     ["entities/index.md", "entities", activeEntityPages],
     ["outputs/index.md", "outputs", allPages.filter((page) => page.kind === "output")],
-    ["candidates/index.md", "candidates", candidatePages]
+    ["candidates/index.md", "candidates", candidatePages],
+    ["graph/index.md", "graph", allPages.filter((page) => page.kind === "graph_report" || page.kind === "community_summary")]
   ]) {
     records.push({
       page: emptyGraphPage({
@@ -6690,6 +7523,23 @@ async function refreshIndexesAndSearch(rootDir, pages) {
   const { config, paths } = await loadVaultConfig(rootDir);
   const schemas = await loadVaultSchemas(rootDir);
   const globalSchemaHash = schemas.effective.global.hash;
+  const currentGraph = await readJsonFile(paths.graphPath);
+  const basePages = pages.filter((page) => page.kind !== "graph_report" && page.kind !== "community_summary");
+  const graphOrientationRecords = currentGraph ? await buildGraphOrientationPages(
+    {
+      ...currentGraph,
+      pages: basePages
+    },
+    paths,
+    globalSchemaHash
+  ) : [];
+  const pagesWithGraph = sortGraphPages([...basePages, ...graphOrientationRecords.map((record) => record.page)]);
+  if (currentGraph) {
+    await writeJsonFile(paths.graphPath, {
+      ...currentGraph,
+      pages: pagesWithGraph
+    });
+  }
   const configuredProjects = projectEntries(config);
   const projectIndexRefs = configuredProjects.map(
     (project) => emptyGraphPage({
@@ -6711,6 +7561,8 @@ async function refreshIndexesAndSearch(rootDir, pages) {
     ensureDir(path14.join(paths.wikiDir, "concepts")),
     ensureDir(path14.join(paths.wikiDir, "entities")),
     ensureDir(path14.join(paths.wikiDir, "outputs")),
+    ensureDir(path14.join(paths.wikiDir, "graph")),
+    ensureDir(path14.join(paths.wikiDir, "graph", "communities")),
     ensureDir(path14.join(paths.wikiDir, "projects")),
     ensureDir(path14.join(paths.wikiDir, "candidates"))
   ]);
@@ -6760,18 +7612,19 @@ async function refreshIndexesAndSearch(rootDir, pages) {
       rootIndexPath,
       {
         managedBy: "system",
-        compiledFrom: indexCompiledFrom(pages)
+        compiledFrom: indexCompiledFrom(pagesWithGraph)
       },
-      (metadata) => buildIndexPage(pages, globalSchemaHash, metadata, projectIndexRefs)
+      (metadata) => buildIndexPage(pagesWithGraph, globalSchemaHash, metadata, projectIndexRefs)
     )
   );
   for (const [relativePath, kind, sectionPages] of [
-    ["sources/index.md", "sources", pages.filter((page) => page.kind === "source")],
-    ["code/index.md", "code", pages.filter((page) => page.kind === "module")],
-    ["concepts/index.md", "concepts", pages.filter((page) => page.kind === "concept" && page.status !== "candidate")],
-    ["entities/index.md", "entities", pages.filter((page) => page.kind === "entity" && page.status !== "candidate")],
-    ["outputs/index.md", "outputs", pages.filter((page) => page.kind === "output")],
-    ["candidates/index.md", "candidates", pages.filter((page) => page.status === "candidate")]
+    ["sources/index.md", "sources", pagesWithGraph.filter((page) => page.kind === "source")],
+    ["code/index.md", "code", pagesWithGraph.filter((page) => page.kind === "module")],
+    ["concepts/index.md", "concepts", pagesWithGraph.filter((page) => page.kind === "concept" && page.status !== "candidate")],
+    ["entities/index.md", "entities", pagesWithGraph.filter((page) => page.kind === "entity" && page.status !== "candidate")],
+    ["outputs/index.md", "outputs", pagesWithGraph.filter((page) => page.kind === "output")],
+    ["candidates/index.md", "candidates", pagesWithGraph.filter((page) => page.status === "candidate")],
+    ["graph/index.md", "graph", pagesWithGraph.filter((page) => page.kind === "graph_report" || page.kind === "community_summary")]
   ]) {
     const absolutePath = path14.join(paths.wikiDir, relativePath);
     await writeFileIfChanged(
@@ -6786,6 +7639,9 @@ async function refreshIndexesAndSearch(rootDir, pages) {
       )
     );
   }
+  for (const record of graphOrientationRecords) {
+    await writeFileIfChanged(path14.join(paths.wikiDir, record.page.path), record.content);
+  }
   const existingProjectIndexPaths = (await listFilesRecursive(paths.projectsDir)).filter((absolutePath) => absolutePath.endsWith(".md")).map((absolutePath) => toPosix(path14.relative(paths.wikiDir, absolutePath)));
   const allowedProjectIndexPaths = /* @__PURE__ */ new Set([
     "projects/index.md",
@@ -6794,7 +7650,12 @@ async function refreshIndexesAndSearch(rootDir, pages) {
   await Promise.all(
     existingProjectIndexPaths.filter((relativePath) => !allowedProjectIndexPaths.has(relativePath)).map((relativePath) => fs11.rm(path14.join(paths.wikiDir, relativePath), { force: true }))
   );
-  await rebuildSearchIndex(paths.searchDbPath, pages, paths.wikiDir);
+  const existingGraphPages = (await listFilesRecursive(path14.join(paths.wikiDir, "graph").replace(/\/$/, "")).catch(() => [])).filter((absolutePath) => absolutePath.endsWith(".md")).map((absolutePath) => toPosix(path14.relative(paths.wikiDir, absolutePath)));
+  const allowedGraphPages = /* @__PURE__ */ new Set(["graph/index.md", ...graphOrientationRecords.map((record) => record.page.path)]);
+  await Promise.all(
+    existingGraphPages.filter((relativePath) => !allowedGraphPages.has(relativePath)).map((relativePath) => fs11.rm(path14.join(paths.wikiDir, relativePath), { force: true }))
+  );
+  await rebuildSearchIndex(paths.searchDbPath, pagesWithGraph, paths.wikiDir);
 }
 async function prepareOutputPageSave(rootDir, input) {
   const { paths } = await loadVaultConfig(rootDir);
@@ -8104,6 +8965,35 @@ async function searchVault(rootDir, query, limit = 5) {
   }
   return searchPages(paths.searchDbPath, query, limit);
 }
+async function ensureCompiledGraph(rootDir) {
+  const { paths } = await loadVaultConfig(rootDir);
+  if (!await fileExists(paths.searchDbPath) || !await fileExists(paths.graphPath)) {
+    await compileVault(rootDir, {});
+  }
+  const graph = await readJsonFile(paths.graphPath);
+  if (!graph) {
+    throw new Error("Graph artifact not found. Run `swarmvault compile` first.");
+  }
+  return graph;
+}
+async function queryGraphVault(rootDir, question, options = {}) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const graph = await ensureCompiledGraph(rootDir);
+  const searchResults = searchPages(paths.searchDbPath, question, { limit: Math.max(5, options.budget ?? 10) });
+  return queryGraph(graph, question, searchResults, options);
+}
+async function pathGraphVault(rootDir, from, to) {
+  const graph = await ensureCompiledGraph(rootDir);
+  return shortestGraphPath(graph, from, to);
+}
+async function explainGraphVault(rootDir, target) {
+  const graph = await ensureCompiledGraph(rootDir);
+  return explainGraphTarget(graph, target);
+}
+async function listGodNodes(rootDir, limit = 10) {
+  const graph = await ensureCompiledGraph(rootDir);
+  return topGodNodes(graph, limit);
+}
 async function listPages(rootDir) {
   const { paths } = await loadVaultConfig(rootDir);
   const graph = await readJsonFile(paths.graphPath);
@@ -8263,7 +9153,7 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "0.1.18";
+var SERVER_VERSION = "0.1.19";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -8323,6 +9213,74 @@ async function createMcpServer(rootDir) {
       return asToolText(limit ? manifests.slice(0, limit) : manifests);
     }
   );
+  server.registerTool(
+    "query_graph",
+    {
+      description: "Traverse the local graph from search seeds without calling a model provider.",
+      inputSchema: {
+        question: z7.string().min(1).describe("Question or graph search seed"),
+        traversal: z7.enum(["bfs", "dfs"]).optional().describe("Traversal strategy"),
+        budget: z7.number().int().min(3).max(50).optional().describe("Maximum nodes to summarize")
+      }
+    },
+    async ({ question, traversal, budget }) => {
+      const result = await queryGraphVault(rootDir, question, {
+        traversal,
+        budget
+      });
+      return asToolText(result);
+    }
+  );
+  server.registerTool(
+    "get_node",
+    {
+      description: "Explain a graph node, its page, community, and neighbors.",
+      inputSchema: {
+        target: z7.string().min(1).describe("Node or page label/id")
+      }
+    },
+    async ({ target }) => {
+      return asToolText(await explainGraphVault(rootDir, target));
+    }
+  );
+  server.registerTool(
+    "get_neighbors",
+    {
+      description: "Return the neighbors of a graph node or page target.",
+      inputSchema: {
+        target: z7.string().min(1).describe("Node or page label/id")
+      }
+    },
+    async ({ target }) => {
+      const explanation = await explainGraphVault(rootDir, target);
+      return asToolText(explanation.neighbors);
+    }
+  );
+  server.registerTool(
+    "shortest_path",
+    {
+      description: "Find the shortest graph path between two targets.",
+      inputSchema: {
+        from: z7.string().min(1).describe("Start node/page label or id"),
+        to: z7.string().min(1).describe("End node/page label or id")
+      }
+    },
+    async ({ from, to }) => {
+      return asToolText(await pathGraphVault(rootDir, from, to));
+    }
+  );
+  server.registerTool(
+    "god_nodes",
+    {
+      description: "List the highest-connectivity graph nodes.",
+      inputSchema: {
+        limit: z7.number().int().min(1).max(25).optional().describe("Maximum nodes to return")
+      }
+    },
+    async ({ limit }) => {
+      return asToolText(await listGodNodes(rootDir, limit ?? 10));
+    }
+  );
   server.registerTool(
     "query_vault",
     {
@@ -8900,6 +9858,34 @@ async function startGraphServer(rootDir, port) {
       response.end(await fs14.readFile(paths.graphPath, "utf8"));
       return;
     }
+    if (url.pathname === "/api/graph/query") {
+      const question = url.searchParams.get("q") ?? "";
+      const traversal = url.searchParams.get("traversal");
+      const budget = Number.parseInt(url.searchParams.get("budget") ?? "12", 10);
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(
+        JSON.stringify(
+          await queryGraphVault(rootDir, question, {
+            traversal: traversal === "dfs" ? "dfs" : "bfs",
+            budget: Number.isFinite(budget) ? budget : 12
+          })
+        )
+      );
+      return;
+    }
+    if (url.pathname === "/api/graph/path") {
+      const from = url.searchParams.get("from") ?? "";
+      const to = url.searchParams.get("to") ?? "";
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(JSON.stringify(await pathGraphVault(rootDir, from, to)));
+      return;
+    }
+    if (url.pathname === "/api/graph/explain") {
+      const target2 = url.searchParams.get("target") ?? "";
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(JSON.stringify(await explainGraphVault(rootDir, target2)));
+      return;
+    }
     if (url.pathname === "/api/search") {
       if (!await fileExists(paths.searchDbPath)) {
         response.writeHead(404, { "content-type": "application/json" });
@@ -9248,6 +10234,7 @@ export {
   createWebSearchAdapter,
   defaultVaultConfig,
   defaultVaultSchema,
+  explainGraphVault,
   exploreVault,
   exportGraphHtml,
   getProviderForTask,
@@ -9263,13 +10250,16 @@ export {
   lintVault,
   listApprovals,
   listCandidates,
+  listGodNodes,
   listManifests,
   listPages,
   listSchedules,
   loadVaultConfig,
   loadVaultSchema,
   loadVaultSchemas,
+  pathGraphVault,
   promoteCandidate,
+  queryGraphVault,
   queryVault,
   readApproval,
   readExtractedText,