@swarmvaultai/engine 3.5.0 → 3.7.0

package/dist/index.js

@@ -23,6 +23,7 @@ import {
   buildOutputPage,
   buildRedactor,
   buildSchemaPrompt,
+  checkTrackedRepoChanges,
   compileVault,
   composeVaultSchema,
   computeDecayScore,
@@ -91,6 +92,7 @@ import {
   readWatchStatusArtifact,
   rebuildRetrievalIndex,
   recordSession,
+  refreshGraphClusters,
   refreshVaultAfterOutputSave,
   rejectApproval,
   removeManifestBySourceId,
@@ -123,9 +125,10 @@ import {
   writeGuidedSourceSession,
   writeRetrievalManifest,
   writeWatchStatusArtifact
-} from "./chunk-HKU2T5JX.js";
+} from "./chunk-S2E65WRI.js";
 import {
   LocalWhisperProviderAdapter,
+  SWARMVAULT_OUT_ENV,
   appendJsonLine,
   assertProviderCapability,
   createProvider,
@@ -140,6 +143,7 @@ import {
   loadVaultConfig,
   normalizeWhitespace,
   readJsonFile,
+  resolveArtifactRootDir,
   resolvePaths,
   sha256,
   slugify,
@@ -147,7 +151,7 @@ import {
   truncate,
   uniqueBy,
   writeJsonFile
-} from "./chunk-7QHDATCQ.js";
+} from "./chunk-7O2HJSWQ.js";
 import {
   estimatePageTokens,
   estimateTokens,
@@ -559,6 +563,7 @@ import chokidar from "chokidar";
 var MAX_BACKOFF_MS = 3e4;
 var BACKOFF_THRESHOLD = 3;
 var CRITICAL_THRESHOLD = 10;
+var DEFAULT_MAX_GRAPH_SHRINK_RATIO = 0.25;
 var REPO_WATCH_IGNORES = /* @__PURE__ */ new Set([".git", ".venv"]);
 var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".ts",
@@ -598,7 +603,12 @@ var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".psm1",
   ".ex",
   ".exs",
+  ".svelte",
   ".jl",
+  ".v",
+  ".vh",
+  ".sv",
+  ".svh",
   ".r",
   ".R"
 ]);
@@ -634,6 +644,35 @@ function collectNonCodePaths(reasons) {
   }
   return result;
 }
+function shrinkDimension(before, after) {
+  const dropped = Math.max(0, before - after);
+  return {
+    before,
+    after,
+    dropped,
+    dropRatio: before > 0 ? dropped / before : 0
+  };
+}
+function evaluateGraphShrinkGuard(previousGraph, nextGraph, options = {}) {
+  const threshold = options.threshold ?? DEFAULT_MAX_GRAPH_SHRINK_RATIO;
+  const nodes = shrinkDimension(previousGraph?.nodes.length ?? 0, nextGraph?.nodes.length ?? 0);
+  const edges = shrinkDimension(previousGraph?.edges.length ?? 0, nextGraph?.edges.length ?? 0);
+  const blocked = nodes.dropRatio > threshold || edges.dropRatio > threshold;
+  return {
+    blocked,
+    threshold,
+    nodes,
+    edges,
+    message: blocked ? `Graph update aborted: node count changed ${nodes.before} -> ${nodes.after} (${Math.round(
+      nodes.dropRatio * 100
+    )}% drop) and edge count changed ${edges.before} -> ${edges.after} (${Math.round(
+      edges.dropRatio * 100
+    )}% drop). Re-run with --force or SWARMVAULT_FORCE_UPDATE=1 if this shrink is expected.` : void 0
+  };
+}
+function forceGraphUpdateEnabled(options) {
+  return options.force === true || process2.env.SWARMVAULT_FORCE_UPDATE === "1" || process2.env.SWARMVAULT_FORCE_UPDATE === "true";
+}
 function hasIgnoredRepoSegment(baseDir, targetPath) {
   const relativePath = path2.relative(baseDir, targetPath);
   if (!relativePath || relativePath.startsWith("..")) {
@@ -770,6 +809,7 @@ async function performWatchCycle(rootDir, paths, options, codeOnly = false) {
 }
 async function runWatchCycle(rootDir, options = {}) {
   const { paths } = await initWorkspace(rootDir);
+  const previousGraph = await readJsonFile(paths.graphPath);
   const startedAt = /* @__PURE__ */ new Date();
   let success = true;
   let error;
@@ -788,6 +828,12 @@ async function runWatchCycle(rootDir, options = {}) {
   };
   try {
     result = await performWatchCycle(rootDir, paths, options, options.codeOnly ?? false);
+    const nextGraph = await readJsonFile(paths.graphPath);
+    const guard = evaluateGraphShrinkGuard(previousGraph, nextGraph, { threshold: options.maxGraphShrinkRatio });
+    if (previousGraph && nextGraph && guard.blocked && !forceGraphUpdateEnabled(options)) {
+      await writeJsonFile(paths.graphPath, previousGraph);
+      throw new Error(guard.message ?? "Graph update aborted because the graph shrank unexpectedly.");
+    }
     return result;
   } catch (caught) {
     success = false;
@@ -3706,9 +3752,350 @@ Community: ${communityLabel}`,
   return { format: "canvas", outputPath: resolvedPath };
 }
 
-// src/graph-push.ts
+// src/graph-merge.ts
 import fs5 from "fs/promises";
 import path5 from "path";
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isSwarmVaultGraph(value) {
+  return isRecord(value) && Array.isArray(value.nodes) && Array.isArray(value.edges) && Array.isArray(value.sources) && Array.isArray(value.pages);
+}
+function stringField(record, ...fields) {
+  for (const field of fields) {
+    const value = record[field];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return String(value);
+    }
+  }
+  return void 0;
+}
+function arrayStringField(record, field) {
+  const value = record[field];
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
+}
+function numberField(record, field, fallback) {
+  const value = record[field];
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function safePrefix(inputPath, index) {
+  return slugify(path5.basename(inputPath, path5.extname(inputPath)) || `graph-${index + 1}`);
+}
+function prefixed(prefix, id) {
+  return `${prefix}:${id}`;
+}
+function ensureUniquePrefix(base, used) {
+  let candidate = base || "graph";
+  let suffix = 2;
+  while (used.has(candidate)) {
+    candidate = `${base}-${suffix}`;
+    suffix += 1;
+  }
+  used.add(candidate);
+  return candidate;
+}
+function mapEvidenceClass(value) {
+  const normalized = typeof value === "string" ? value.toLowerCase() : "";
+  if (normalized === "extracted") return "extracted";
+  if (normalized === "ambiguous") return "ambiguous";
+  return "inferred";
+}
+function mapNodeType(value) {
+  const normalized = typeof value === "string" ? value.toLowerCase() : "";
+  if (["source", "file", "document", "paper", "image", "video"].includes(normalized)) return "source";
+  if (["module", "code"].includes(normalized)) return "module";
+  if (["function", "class", "symbol", "method", "component"].includes(normalized)) return "symbol";
+  if (["entity", "person", "org", "organization"].includes(normalized)) return "entity";
+  if (["rationale", "comment", "docstring", "why"].includes(normalized)) return "rationale";
+  if (["decision", "adr"].includes(normalized)) return "decision";
+  return "concept";
+}
+function remapSwarmVaultGraph(inputPath, graph, prefix) {
+  const sourceMap = new Map(graph.sources.map((source) => [source.sourceId, prefixed(prefix, source.sourceId)]));
+  const pageMap = new Map(graph.pages.map((page) => [page.id, prefixed(prefix, page.id)]));
+  const nodeMap = new Map(graph.nodes.map((node) => [node.id, prefixed(prefix, node.id)]));
+  const communityMap = new Map((graph.communities ?? []).map((community) => [community.id, prefixed(prefix, community.id)]));
+  const sources = graph.sources.map((source) => ({
+    ...source,
+    sourceId: sourceMap.get(source.sourceId) ?? prefixed(prefix, source.sourceId),
+    title: `[${prefix}] ${source.title}`,
+    sourceGroupId: source.sourceGroupId ? prefixed(prefix, source.sourceGroupId) : void 0,
+    details: {
+      ...source.details ?? {},
+      mergedInput: inputPath,
+      mergedPrefix: prefix
+    }
+  }));
+  const pages = graph.pages.map((page) => ({
+    ...page,
+    id: pageMap.get(page.id) ?? prefixed(prefix, page.id),
+    path: toPosix(path5.posix.join("merged", prefix, page.path)),
+    sourceIds: page.sourceIds.map((sourceId) => sourceMap.get(sourceId) ?? prefixed(prefix, sourceId)),
+    nodeIds: page.nodeIds.map((nodeId) => nodeMap.get(nodeId) ?? prefixed(prefix, nodeId)),
+    relatedPageIds: page.relatedPageIds.map((pageId) => pageMap.get(pageId) ?? prefixed(prefix, pageId)),
+    relatedNodeIds: page.relatedNodeIds.map((nodeId) => nodeMap.get(nodeId) ?? prefixed(prefix, nodeId)),
+    relatedSourceIds: page.relatedSourceIds.map((sourceId) => sourceMap.get(sourceId) ?? prefixed(prefix, sourceId)),
+    backlinks: page.backlinks.map((pageId) => pageMap.get(pageId) ?? prefixed(prefix, pageId)),
+    supersededBy: page.supersededBy ? pageMap.get(page.supersededBy) ?? prefixed(prefix, page.supersededBy) : void 0
+  }));
+  const nodes = graph.nodes.map((node) => ({
+    ...node,
+    id: nodeMap.get(node.id) ?? prefixed(prefix, node.id),
+    pageId: node.pageId ? pageMap.get(node.pageId) ?? prefixed(prefix, node.pageId) : void 0,
+    sourceIds: node.sourceIds.map((sourceId) => sourceMap.get(sourceId) ?? prefixed(prefix, sourceId)),
+    moduleId: node.moduleId ? nodeMap.get(node.moduleId) ?? prefixed(prefix, node.moduleId) : void 0,
+    communityId: node.communityId ? communityMap.get(node.communityId) ?? prefixed(prefix, node.communityId) : void 0
+  }));
+  const edges = graph.edges.map((edge) => ({
+    ...edge,
+    id: prefixed(prefix, edge.id),
+    source: nodeMap.get(edge.source) ?? prefixed(prefix, edge.source),
+    target: nodeMap.get(edge.target) ?? prefixed(prefix, edge.target),
+    provenance: edge.provenance.map((id) => nodeMap.get(id) ?? pageMap.get(id) ?? sourceMap.get(id) ?? prefixed(prefix, id))
+  }));
+  const hyperedges = graph.hyperedges.map((hyperedge) => ({
+    ...hyperedge,
+    id: prefixed(prefix, hyperedge.id),
+    nodeIds: hyperedge.nodeIds.map((nodeId) => nodeMap.get(nodeId) ?? prefixed(prefix, nodeId)),
+    sourcePageIds: hyperedge.sourcePageIds.map((pageId) => pageMap.get(pageId) ?? prefixed(prefix, pageId))
+  }));
+  return {
+    generatedAt: graph.generatedAt,
+    nodes,
+    edges,
+    hyperedges,
+    communities: (graph.communities ?? []).map((community) => ({
+      ...community,
+      id: communityMap.get(community.id) ?? prefixed(prefix, community.id),
+      label: `[${prefix}] ${community.label}`,
+      nodeIds: community.nodeIds.map((nodeId) => nodeMap.get(nodeId) ?? prefixed(prefix, nodeId))
+    })),
+    sources,
+    pages
+  };
+}
+function nodeLinkArrays(raw) {
+  const nodes = raw.nodes;
+  const edges = Array.isArray(raw.links) ? raw.links : raw.edges;
+  if (!Array.isArray(nodes) || !Array.isArray(edges)) {
+    return null;
+  }
+  return {
+    nodes,
+    edges: edges.filter(isRecord)
+  };
+}
+function nodeLinkNodeId(node, index) {
+  if (typeof node === "string" || typeof node === "number") {
+    return String(node);
+  }
+  return stringField(node, "id", "key", "name", "label") ?? `node-${index + 1}`;
+}
+function endpointId(value) {
+  if (typeof value === "string" || typeof value === "number") {
+    return String(value);
+  }
+  if (isRecord(value)) {
+    return stringField(value, "id", "key", "name", "label");
+  }
+  return void 0;
+}
+function remapNodeLinkGraph(inputPath, raw, prefix, now) {
+  const arrays = nodeLinkArrays(raw);
+  if (!arrays) {
+    throw new Error(`${inputPath} is not a SwarmVault graph or node-link graph.`);
+  }
+  const syntheticSourceId = prefixed(prefix, "source");
+  const source = {
+    sourceId: syntheticSourceId,
+    title: `${prefix} merged graph`,
+    originType: "file",
+    sourceKind: "data",
+    sourceClass: "generated",
+    originalPath: inputPath,
+    storedPath: inputPath,
+    mimeType: "application/json",
+    contentHash: `sha256:${sha256(JSON.stringify(raw)).slice(0, 24)}`,
+    semanticHash: `sha256:${sha256(`${inputPath}:${arrays.nodes.length}:${arrays.edges.length}`).slice(0, 24)}`,
+    details: {
+      mergedInput: inputPath,
+      mergedFormat: "node-link"
+    },
+    createdAt: now,
+    updatedAt: now
+  };
+  const idMap = /* @__PURE__ */ new Map();
+  const nodes = arrays.nodes.map((node, index) => {
+    const originalId = nodeLinkNodeId(node, index);
+    const mappedId = prefixed(prefix, originalId);
+    idMap.set(originalId, mappedId);
+    const record = isRecord(node) ? node : {};
+    const label = stringField(record, "label", "name", "title", "path", "id") ?? originalId;
+    const type = mapNodeType(record.type ?? record.file_type ?? record.kind ?? record.category);
+    return {
+      id: mappedId,
+      type,
+      label,
+      sourceIds: [syntheticSourceId],
+      projectIds: [],
+      sourceClass: "generated",
+      confidence: numberField(record, "confidence", numberField(record, "confidence_score", 1)),
+      tags: arrayStringField(record, "tags")
+    };
+  });
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  const edges = arrays.edges.flatMap((edge, index) => {
+    const source2 = endpointId(edge.source ?? edge.from);
+    const target = endpointId(edge.target ?? edge.to);
+    if (!source2 || !target) {
+      return [];
+    }
+    const mappedSource = idMap.get(source2) ?? prefixed(prefix, source2);
+    const mappedTarget = idMap.get(target) ?? prefixed(prefix, target);
+    if (!nodeIds.has(mappedSource) || !nodeIds.has(mappedTarget)) {
+      return [];
+    }
+    const evidenceClass = mapEvidenceClass(edge.evidenceClass ?? edge.evidence_class ?? edge.status ?? edge.confidence);
+    return [
+      {
+        id: prefixed(prefix, stringField(edge, "id", "key") ?? `edge-${index + 1}`),
+        source: mappedSource,
+        target: mappedTarget,
+        relation: stringField(edge, "relation", "type", "label") ?? "related_to",
+        status: evidenceClass === "extracted" ? "extracted" : "inferred",
+        evidenceClass,
+        confidence: numberField(edge, "confidence", numberField(edge, "confidence_score", evidenceClass === "ambiguous" ? 0.5 : 0.75)),
+        provenance: [syntheticSourceId]
+      }
+    ];
+  });
+  const page = {
+    id: prefixed(prefix, "page"),
+    path: toPosix(path5.posix.join("merged", prefix, "index.md")),
+    title: `${prefix} merged graph`,
+    kind: "source",
+    sourceClass: "generated",
+    sourceIds: [syntheticSourceId],
+    projectIds: [],
+    nodeIds: nodes.map((node) => node.id),
+    freshness: "fresh",
+    status: "active",
+    confidence: 1,
+    backlinks: [],
+    schemaHash: "merged-node-link",
+    sourceHashes: { [syntheticSourceId]: source.contentHash },
+    sourceSemanticHashes: { [syntheticSourceId]: source.semanticHash },
+    relatedPageIds: [],
+    relatedNodeIds: nodes.map((node) => node.id),
+    relatedSourceIds: [syntheticSourceId],
+    createdAt: now,
+    updatedAt: now,
+    compiledFrom: [inputPath],
+    managedBy: "system"
+  };
+  return {
+    generatedAt: now,
+    nodes,
+    edges,
+    hyperedges: [],
+    communities: [],
+    sources: [source],
+    pages: [page]
+  };
+}
+function mergeGraphs(graphs, now) {
+  return {
+    generatedAt: now,
+    nodes: uniqueBy(
+      graphs.flatMap((graph) => graph.nodes),
+      (node) => node.id
+    ),
+    edges: uniqueBy(
+      graphs.flatMap((graph) => graph.edges),
+      (edge) => edge.id
+    ),
+    hyperedges: uniqueBy(
+      graphs.flatMap((graph) => graph.hyperedges),
+      (hyperedge) => hyperedge.id
+    ),
+    communities: uniqueBy(
+      graphs.flatMap((graph) => graph.communities ?? []),
+      (community) => community.id
+    ),
+    sources: uniqueBy(
+      graphs.flatMap((graph) => graph.sources),
+      (source) => source.sourceId
+    ),
+    pages: uniqueBy(
+      graphs.flatMap((graph) => graph.pages),
+      (page) => page.id
+    )
+  };
+}
+async function mergeGraphFiles(inputPaths, outputPath, options = {}) {
+  if (inputPaths.length === 0) {
+    throw new Error("At least one graph JSON path is required.");
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const usedPrefixes = /* @__PURE__ */ new Set();
+  const graphs = [];
+  const inputGraphs = [];
+  const warnings = [];
+  for (const [index, inputPath] of inputPaths.entries()) {
+    const resolvedInputPath = path5.resolve(inputPath);
+    const raw = JSON.parse(await fs5.readFile(resolvedInputPath, "utf8"));
+    const prefix = ensureUniquePrefix(
+      inputPaths.length === 1 && options.label ? slugify(options.label) : safePrefix(resolvedInputPath, index),
+      usedPrefixes
+    );
+    if (isSwarmVaultGraph(raw)) {
+      const graph2 = remapSwarmVaultGraph(resolvedInputPath, raw, prefix);
+      graphs.push(graph2);
+      inputGraphs.push({
+        path: resolvedInputPath,
+        label: prefix,
+        format: "swarmvault",
+        nodeCount: raw.nodes.length,
+        edgeCount: raw.edges.length
+      });
+      continue;
+    }
+    if (isRecord(raw) && nodeLinkArrays(raw)) {
+      const graph2 = remapNodeLinkGraph(resolvedInputPath, raw, prefix, now);
+      graphs.push(graph2);
+      inputGraphs.push({
+        path: resolvedInputPath,
+        label: prefix,
+        format: "node-link",
+        nodeCount: graph2.nodes.length,
+        edgeCount: graph2.edges.length
+      });
+      continue;
+    }
+    warnings.push(`${resolvedInputPath} was skipped because it is not a supported graph JSON shape.`);
+  }
+  if (graphs.length === 0) {
+    throw new Error("No supported graph inputs were found.");
+  }
+  const graph = mergeGraphs(graphs, now);
+  const resolvedOutputPath = path5.resolve(outputPath);
+  await ensureDir(path5.dirname(resolvedOutputPath));
+  await fs5.writeFile(resolvedOutputPath, `${JSON.stringify(graph, null, 2)}
+`, "utf8");
+  return {
+    outputPath: resolvedOutputPath,
+    graph,
+    inputGraphs,
+    warnings
+  };
+}
+
+// src/graph-push.ts
+import fs6 from "fs/promises";
+import path6 from "path";
 import neo4j from "neo4j-driver";
 var DEFAULT_NEO4J_BATCH_SIZE = 500;
 var DEFAULT_NEO4J_DATABASE = "neo4j";
@@ -3719,8 +4106,8 @@ function requireConfigValue(value, name) {
   throw new Error(`Neo4j push requires ${name}. Configure \`graphSinks.neo4j.${name}\` or pass the matching CLI flag.`);
 }
 async function deriveVaultId(rootDir) {
-  const realRoot = await fs5.realpath(rootDir).catch(() => path5.resolve(rootDir));
-  const label = slugify(path5.basename(realRoot));
+  const realRoot = await fs6.realpath(rootDir).catch(() => path6.resolve(rootDir));
+  const label = slugify(path6.basename(realRoot));
   return `${label}-${sha256(realRoot).slice(0, 12)}`;
 }
 async function resolveNeo4jPushConfig(rootDir, options) {
@@ -3750,7 +4137,7 @@ function normalizeBatchSize(value) {
 }
 async function loadGraph2(rootDir) {
   const { paths } = await loadVaultConfig(rootDir);
-  const raw = JSON.parse(await fs5.readFile(paths.graphPath, "utf8"));
+  const raw = JSON.parse(await fs6.readFile(paths.graphPath, "utf8"));
   return raw;
 }
 function buildResult(input) {
@@ -3835,7 +4222,7 @@ async function writeSyncNode(session, input) {
       ].join("\n"),
       {
         vaultId: input.vaultId,
-        rootDir: path5.resolve(input.rootDir),
+        rootDir: path6.resolve(input.rootDir),
         graphGeneratedAt: input.graph.generatedAt,
         graphHash: graphHash(input.graph),
         pushedAt: input.pushedAt,
@@ -3920,27 +4307,319 @@ async function pushGraphNeo4j(rootDir, options = {}) {
   }
 }
 
+// src/graph-status.ts
+import path7 from "path";
+function recommendedCommand(input) {
+  if (!input.graphExists || !input.reportExists) {
+    return "swarmvault compile";
+  }
+  if (input.semanticChangeCount > 0 || input.pendingSemanticRefreshCount > 0) {
+    return "swarmvault compile";
+  }
+  if (input.codeChangeCount > 0) {
+    return "swarmvault graph update";
+  }
+  return null;
+}
+async function getGraphStatus(rootDir, options = {}) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const graphPath = paths.graphPath;
+  const reportPath = path7.join(paths.wikiDir, "graph", "report.md");
+  const resolvedOverrideRoots = options.repoRoots?.map((repoRoot) => path7.resolve(rootDir, repoRoot));
+  const [graphExists, reportExists, trackedRepoRoots, changes, pendingSemanticRefresh] = await Promise.all([
+    fileExists(graphPath),
+    fileExists(reportPath),
+    resolvedOverrideRoots ? Promise.resolve([...new Set(resolvedOverrideRoots)].sort((left, right) => left.localeCompare(right))) : listTrackedRepoRoots(rootDir),
+    checkTrackedRepoChanges(rootDir, resolvedOverrideRoots),
+    readJsonFile(paths.pendingSemanticRefreshPath).then((entries) => Array.isArray(entries) ? entries : [])
+  ]);
+  const codeChangeCount = changes.filter((change) => change.refreshType === "code").length;
+  const semanticChangeCount = changes.filter((change) => change.refreshType === "semantic").length;
+  const command = recommendedCommand({
+    graphExists,
+    reportExists,
+    codeChangeCount,
+    semanticChangeCount,
+    pendingSemanticRefreshCount: pendingSemanticRefresh.length
+  });
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    graphExists,
+    graphPath,
+    reportExists,
+    reportPath,
+    trackedRepoRoots,
+    codeChangeCount,
+    semanticChangeCount,
+    pendingSemanticRefresh,
+    stale: Boolean(command),
+    recommendedCommand: command,
+    changes
+  };
+}
+
+// src/graph-tree.ts
+import path8 from "path";
+var DEFAULT_MAX_CHILDREN = 250;
+function compareTreeNodes(left, right) {
+  const kindOrder = /* @__PURE__ */ new Map([
+    ["directory", 0],
+    ["source", 1],
+    ["module", 2],
+    ["symbol", 3],
+    ["rationale", 4],
+    ["node", 5],
+    ["more", 6],
+    ["root", 7]
+  ]);
+  const leftKind = kindOrder.get(left.kind) ?? 99;
+  const rightKind = kindOrder.get(right.kind) ?? 99;
+  return leftKind - rightKind || left.label.localeCompare(right.label) || left.id.localeCompare(right.id);
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+function normalizeSourcePath(rootDir, source) {
+  const candidate = source.repoRelativePath ?? source.originalPath ?? source.storedPath ?? source.title;
+  if (source.repoRelativePath) {
+    return toPosix(source.repoRelativePath);
+  }
+  if (rootDir && path8.isAbsolute(candidate) && isPathWithin(rootDir, candidate)) {
+    return toPosix(path8.relative(rootDir, candidate));
+  }
+  if (path8.isAbsolute(candidate)) {
+    return toPosix(path8.basename(candidate));
+  }
+  return toPosix(candidate).replace(/^\/+/, "") || source.title || source.sourceId;
+}
+function makeDirectoryNode(parentId, segment) {
+  return {
+    id: `${parentId}/${segment}`,
+    label: segment,
+    kind: "directory",
+    count: 0,
+    children: []
+  };
+}
+function ensureDirectory(parent, segment) {
+  const existing = parent.children.find((child) => child.kind === "directory" && child.label === segment);
+  if (existing) {
+    existing.count += 1;
+    return existing;
+  }
+  const created = makeDirectoryNode(parent.id, segment);
+  created.count = 1;
+  parent.children.push(created);
+  return created;
+}
+function nodeChildrenForSource(sourceId, nodes) {
+  const sourceNodes = nodes.filter((node) => node.sourceIds.includes(sourceId));
+  const modules = sourceNodes.filter((node) => node.type === "module").sort((left, right) => left.label.localeCompare(right.label));
+  const moduleIds = new Set(modules.map((node) => node.id));
+  const symbols = sourceNodes.filter((node) => node.type === "symbol");
+  const rationales = sourceNodes.filter((node) => node.type === "rationale");
+  const children = [];
+  for (const moduleNode of modules) {
+    const moduleChildren = symbols.filter((symbol) => symbol.moduleId === moduleNode.id).sort((left, right) => left.label.localeCompare(right.label)).map((symbol) => graphNodeToTreeNode(symbol, "symbol"));
+    children.push({
+      id: `tree:${moduleNode.id}`,
+      label: moduleNode.label,
+      kind: "module",
+      count: moduleChildren.length,
+      children: moduleChildren,
+      nodeId: moduleNode.id,
+      sourceId,
+      language: moduleNode.language
+    });
+  }
+  for (const symbol of symbols.filter((node) => !node.moduleId || !moduleIds.has(node.moduleId))) {
+    children.push(graphNodeToTreeNode(symbol, "symbol"));
+  }
+  for (const rationale of rationales) {
+    children.push(graphNodeToTreeNode(rationale, "rationale"));
+  }
+  return children.sort(compareTreeNodes);
+}
+function graphNodeToTreeNode(node, kind) {
+  return {
+    id: `tree:${node.id}`,
+    label: node.label,
+    kind,
+    count: 0,
+    children: [],
+    nodeId: node.id,
+    language: node.language,
+    symbolKind: node.symbolKind
+  };
+}
+function sortAndCapTree(node, maxChildren) {
+  const sortedChildren = node.children.map((child) => sortAndCapTree(child, maxChildren)).sort(compareTreeNodes);
+  if (sortedChildren.length <= maxChildren) {
+    return { ...node, children: sortedChildren };
+  }
+  const visible = sortedChildren.slice(0, maxChildren);
+  const hidden = sortedChildren.length - visible.length;
+  return {
+    ...node,
+    hiddenChildren: hidden,
+    children: [
+      ...visible,
+      {
+        id: `${node.id}:more`,
+        label: `+${hidden} more`,
+        kind: "more",
+        count: hidden,
+        children: []
+      }
+    ]
+  };
+}
+function buildGraphTree(graph, options = {}) {
+  const root = {
+    id: "tree:root",
+    label: options.label ?? "SwarmVault Graph Tree",
+    kind: "root",
+    count: graph.sources.length,
+    children: []
+  };
+  const nodes = [...graph.nodes];
+  for (const source of [...graph.sources].sort(
+    (left, right) => normalizeSourcePath(options.rootDir, left).localeCompare(normalizeSourcePath(options.rootDir, right))
+  )) {
+    const normalizedPath = normalizeSourcePath(options.rootDir, source);
+    const segments = normalizedPath.split("/").filter(Boolean);
+    const fileLabel = segments.pop() ?? source.title ?? source.sourceId;
+    let parent = root;
+    for (const segment of segments) {
+      parent = ensureDirectory(parent, segment);
+    }
+    const children = nodeChildrenForSource(source.sourceId, nodes);
+    parent.children.push({
+      id: `tree:source:${source.sourceId}`,
+      label: fileLabel,
+      kind: "source",
+      count: children.length,
+      children,
+      path: normalizedPath,
+      sourceId: source.sourceId,
+      language: source.language
+    });
+  }
+  return sortAndCapTree(root, Math.max(1, options.maxChildren ?? DEFAULT_MAX_CHILDREN));
+}
+function renderNode(node) {
+  const meta = [
+    node.kind,
+    node.language,
+    node.symbolKind,
+    node.path,
+    node.nodeId,
+    node.sourceId,
+    node.count ? `${node.count} item${node.count === 1 ? "" : "s"}` : void 0
+  ].filter(Boolean);
+  const content = [
+    `<span class="label">${escapeHtml(node.label)}</span>`,
+    meta.length ? `<span class="meta">${escapeHtml(meta.join(" \xB7 "))}</span>` : ""
+  ].join("");
+  if (node.children.length === 0) {
+    return `<li class="tree-node kind-${escapeHtml(node.kind)}">${content}</li>`;
+  }
+  return `<li class="tree-node kind-${escapeHtml(node.kind)}"><details open><summary>${content}</summary><ul>${node.children.map(renderNode).join("")}</ul></details></li>`;
+}
+function renderGraphTreeHtml(tree, graph) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(tree.label)}</title>
+<style>
+:root { color-scheme: light dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+body { margin: 0; background: #f7f7f5; color: #171717; }
+main { max-width: 1120px; margin: 0 auto; padding: 32px 20px 56px; }
+h1 { font-size: 28px; line-height: 1.2; margin: 0 0 8px; }
+.subtitle { color: #5d5d5d; margin: 0 0 20px; }
+.toolbar { display: flex; gap: 12px; align-items: center; margin: 0 0 18px; }
+input { flex: 1; min-width: 0; border: 1px solid #c9c9c9; border-radius: 6px; padding: 10px 12px; font: inherit; background: #fff; color: inherit; }
+.tree { background: #fff; border: 1px solid #deded9; border-radius: 8px; padding: 16px 18px; }
+ul { list-style: none; margin: 0; padding-left: 20px; }
+.tree > ul { padding-left: 0; }
+li { margin: 4px 0; }
+summary { cursor: pointer; }
+.label { font-weight: 600; }
+.meta { color: #666; font-size: 12px; margin-left: 8px; }
+.kind-directory > details > summary .label { color: #245b78; }
+.kind-source > details > summary .label, .kind-source > .label { color: #22543d; }
+.kind-module > details > summary .label { color: #6b3f12; }
+.kind-rationale > .label { color: #6d2f46; }
+.hidden { display: none !important; }
+@media (prefers-color-scheme: dark) {
+  body { background: #161616; color: #efefef; }
+  .subtitle, .meta { color: #ababab; }
+  input, .tree { background: #202020; border-color: #3a3a3a; }
+}
+</style>
+</head>
+<body>
+<main>
+<h1>${escapeHtml(tree.label)}</h1>
+<p class="subtitle">${graph.sources.length} sources \xB7 ${graph.nodes.length} nodes \xB7 ${graph.edges.length} edges \xB7 generated ${escapeHtml(graph.generatedAt)}</p>
+<div class="toolbar"><input id="filter" type="search" placeholder="Filter files, modules, symbols, or ids" aria-label="Filter graph tree"></div>
+<section class="tree"><ul>${renderNode(tree)}</ul></section>
+</main>
+<script>
+const input = document.getElementById('filter');
+input.addEventListener('input', () => {
+  const query = input.value.trim().toLowerCase();
+  for (const node of document.querySelectorAll('.tree-node')) {
+    const text = node.textContent.toLowerCase();
+    node.classList.toggle('hidden', query.length > 0 && !text.includes(query));
+  }
+});
+</script>
+</body>
+</html>
+`;
+}
+async function exportGraphTree(rootDir, outputPath, options = {}) {
+  const { paths } = await loadVaultConfig(rootDir);
+  const graph = await readJsonFile(paths.graphPath);
+  if (!graph) {
+    throw new Error(`Graph artifact not found at ${paths.graphPath}. Run swarmvault compile first.`);
+  }
+  const tree = buildGraphTree(graph, { ...options, rootDir });
+  const resolvedOutputPath = path8.resolve(rootDir, outputPath ?? path8.join(paths.wikiDir, "graph", "tree.html"));
+  await ensureDir(path8.dirname(resolvedOutputPath));
+  await import("fs/promises").then((fs13) => fs13.writeFile(resolvedOutputPath, renderGraphTreeHtml(tree, graph), "utf8"));
+  return {
+    outputPath: resolvedOutputPath,
+    sourceCount: graph.sources.length,
+    nodeCount: graph.nodes.length,
+    tree
+  };
+}
+
 // src/hooks.ts
-import fs6 from "fs/promises";
-import path6 from "path";
+import fs7 from "fs/promises";
+import path9 from "path";
 import process3 from "process";
 var hookStart = "# >>> swarmvault hook >>>";
 var hookEnd = "# <<< swarmvault hook <<<";
 async function findNearestGitRoot(startPath) {
-  let current = path6.resolve(startPath);
+  let current = path9.resolve(startPath);
   try {
-    const stat = await fs6.stat(current);
+    const stat = await fs7.stat(current);
     if (!stat.isDirectory()) {
-      current = path6.dirname(current);
+      current = path9.dirname(current);
     }
   } catch {
-    current = path6.dirname(current);
+    current = path9.dirname(current);
   }
   while (true) {
-    if (await fileExists(path6.join(current, ".git"))) {
+    if (await fileExists(path9.join(current, ".git"))) {
       return current;
     }
-    const parent = path6.dirname(current);
+    const parent = path9.dirname(current);
     if (parent === current) {
       return null;
     }
@@ -3952,8 +4631,8 @@ function shellQuote(value) {
 }
 function resolveSwarmvaultExecutableCandidate() {
   const argvPath = process3.argv[1];
-  if (typeof argvPath === "string" && argvPath.trim() && (argvPath.includes(`${path6.sep}@swarmvaultai${path6.sep}cli${path6.sep}`) || argvPath.includes(`${path6.sep}packages${path6.sep}cli${path6.sep}`))) {
-    return path6.resolve(argvPath);
+  if (typeof argvPath === "string" && argvPath.trim() && (argvPath.includes(`${path9.sep}@swarmvaultai${path9.sep}cli${path9.sep}`) || argvPath.includes(`${path9.sep}packages${path9.sep}cli${path9.sep}`))) {
+    return path9.resolve(argvPath);
   }
   return "swarmvault";
 }
@@ -3972,17 +4651,17 @@ function managedHookBlock(vaultRoot) {
   ].join("\n");
 }
 function hookPath(repoRoot, hookName) {
-  return path6.join(repoRoot, ".git", "hooks", hookName);
+  return path9.join(repoRoot, ".git", "hooks", hookName);
 }
 async function readHookStatus(filePath) {
   if (!await fileExists(filePath)) {
     return "not_installed";
   }
-  const content = await fs6.readFile(filePath, "utf8");
+  const content = await fs7.readFile(filePath, "utf8");
   return content.includes(hookStart) && content.includes(hookEnd) ? "installed" : "other_content";
 }
 async function upsertHookFile(filePath, block) {
-  const existing = await fileExists(filePath) ? await fs6.readFile(filePath, "utf8") : "";
+  const existing = await fileExists(filePath) ? await fs7.readFile(filePath, "utf8") : "";
   let next;
   const startIndex = existing.indexOf(hookStart);
   const endIndex = existing.indexOf(hookEnd);
@@ -3996,16 +4675,16 @@ ${block}`.trimEnd();
     next = `#!/bin/sh
 ${block}`.trimEnd();
   }
-  await ensureDir(path6.dirname(filePath));
-  await fs6.writeFile(filePath, `${next}
+  await ensureDir(path9.dirname(filePath));
+  await fs7.writeFile(filePath, `${next}
 `, { mode: 493, encoding: "utf8" });
-  await fs6.chmod(filePath, 493);
+  await fs7.chmod(filePath, 493);
 }
 async function removeHookBlock(filePath) {
   if (!await fileExists(filePath)) {
     return;
   }
-  const existing = await fs6.readFile(filePath, "utf8");
+  const existing = await fs7.readFile(filePath, "utf8");
   const startIndex = existing.indexOf(hookStart);
   const endIndex = existing.indexOf(hookEnd);
   if (startIndex === -1 || endIndex === -1) {
@@ -4013,10 +4692,10 @@ async function removeHookBlock(filePath) {
   }
   const next = `${existing.slice(0, startIndex)}${existing.slice(endIndex + hookEnd.length)}`.trim();
   if (!next || next === "#!/bin/sh") {
-    await fs6.rm(filePath, { force: true });
+    await fs7.rm(filePath, { force: true });
     return;
   }
-  await fs6.writeFile(filePath, `${next}
+  await fs7.writeFile(filePath, `${next}
 `, "utf8");
 }
 async function getGitHookStatus(rootDir) {
@@ -4039,7 +4718,7 @@ async function installGitHooks(rootDir) {
   if (!repoRoot) {
     throw new Error("No git repository found above the current vault.");
   }
-  const block = managedHookBlock(path6.resolve(rootDir));
+  const block = managedHookBlock(path9.resolve(rootDir));
   await upsertHookFile(hookPath(repoRoot, "post-commit"), block);
   await upsertHookFile(hookPath(repoRoot, "post-checkout"), block);
   return getGitHookStatus(rootDir);
@@ -4059,12 +4738,12 @@ async function uninstallGitHooks(rootDir) {
 }
 
 // src/mcp.ts
-import fs7 from "fs/promises";
-import path7 from "path";
+import fs8 from "fs/promises";
+import path10 from "path";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-var SERVER_VERSION = "3.5.0";
+var SERVER_VERSION = "3.7.0";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -4202,6 +4881,18 @@ async function createMcpServer(rootDir) {
       return asToolText(await graphStatsVault(rootDir));
     })
   );
+  server.registerTool(
+    "cluster_graph",
+    {
+      description: "Recompute graph communities, node degrees, god-node flags, and graph report artifacts from the existing compiled graph.",
+      inputSchema: {
+        resolution: z.number().positive().optional().describe("Optional Louvain community resolution override")
+      }
+    },
+    safeHandler(async ({ resolution }) => {
+      return asToolText(await refreshGraphClusters(rootDir, { resolution }));
+    })
+  );
   server.registerTool(
     "get_node",
     {
@@ -4760,7 +5451,7 @@ async function createMcpServer(rootDir) {
     },
     async () => {
       const { paths } = await loadVaultConfig(rootDir);
-      const files = (await listFilesRecursive(paths.sessionsDir)).filter((filePath) => filePath.endsWith(".md")).map((filePath) => toPosix(path7.relative(paths.sessionsDir, filePath))).sort();
+      const files = (await listFilesRecursive(paths.sessionsDir)).filter((filePath) => filePath.endsWith(".md")).map((filePath) => toPosix(path10.relative(paths.sessionsDir, filePath))).sort();
       return asTextResource("swarmvault://sessions", JSON.stringify(files, null, 2));
     }
   );
@@ -4829,8 +5520,8 @@ async function createMcpServer(rootDir) {
         return asTextResource(`swarmvault://pages/${encodedPath}`, `Page not found: ${relativePath}`);
       }
       const { paths } = await loadVaultConfig(rootDir);
-      const absolutePath = path7.resolve(paths.wikiDir, relativePath);
-      return asTextResource(`swarmvault://pages/${encodedPath}`, await fs7.readFile(absolutePath, "utf8"));
+      const absolutePath = path10.resolve(paths.wikiDir, relativePath);
+      return asTextResource(`swarmvault://pages/${encodedPath}`, await fs8.readFile(absolutePath, "utf8"));
     }
   );
   server.registerResource(
@@ -4838,11 +5529,11 @@ async function createMcpServer(rootDir) {
     new ResourceTemplate("swarmvault://sessions/{path}", {
       list: async () => {
         const { paths } = await loadVaultConfig(rootDir);
-        const files = (await listFilesRecursive(paths.sessionsDir)).filter((filePath) => filePath.endsWith(".md")).map((filePath) => toPosix(path7.relative(paths.sessionsDir, filePath))).sort();
+        const files = (await listFilesRecursive(paths.sessionsDir)).filter((filePath) => filePath.endsWith(".md")).map((filePath) => toPosix(path10.relative(paths.sessionsDir, filePath))).sort();
         return {
           resources: files.map((relativePath) => ({
             uri: `swarmvault://sessions/${encodeURIComponent(relativePath)}`,
-            name: path7.basename(relativePath, ".md"),
+            name: path10.basename(relativePath, ".md"),
             title: relativePath,
             description: "SwarmVault session artifact",
             mimeType: "text/markdown"
@@ -4859,11 +5550,11 @@ async function createMcpServer(rootDir) {
       const { paths } = await loadVaultConfig(rootDir);
       const encodedPath = typeof variables.path === "string" ? variables.path : "";
       const relativePath = decodeURIComponent(encodedPath);
-      const absolutePath = path7.resolve(paths.sessionsDir, relativePath);
+      const absolutePath = path10.resolve(paths.sessionsDir, relativePath);
       if (!isPathWithin(paths.sessionsDir, absolutePath) || !await fileExists(absolutePath)) {
         return asTextResource(`swarmvault://sessions/${encodedPath}`, `Session not found: ${relativePath}`);
       }
-      return asTextResource(`swarmvault://sessions/${encodedPath}`, await fs7.readFile(absolutePath, "utf8"));
+      return asTextResource(`swarmvault://sessions/${encodedPath}`, await fs8.readFile(absolutePath, "utf8"));
     }
   );
   return server;
@@ -4923,9 +5614,9 @@ function asTextResource(uri, text) {
 
 // src/providers/local-whisper-setup.ts
 import { createWriteStream, constants as fsConstants } from "fs";
-import fs8 from "fs/promises";
+import fs9 from "fs/promises";
 import os from "os";
-import path8 from "path";
+import path11 from "path";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 var BINARY_CANDIDATES = ["whisper-cli", "whisper-cpp", "whisper"];
@@ -4953,10 +5644,10 @@ async function discoverLocalWhisperBinary(options = {}) {
   }
   const pathValue = env.PATH ?? "";
   const candidates = [];
-  for (const dir of pathValue.split(path8.delimiter)) {
+  for (const dir of pathValue.split(path11.delimiter)) {
     if (!dir) continue;
     for (const name of BINARY_CANDIDATES) {
-      const full = path8.join(dir, name);
+      const full = path11.join(dir, name);
       candidates.push(full);
       if (await isExecutable(full)) {
         return { binaryPath: full, candidates, source: "path" };
@@ -4967,14 +5658,14 @@ async function discoverLocalWhisperBinary(options = {}) {
 }
 function expectedModelPath(modelName, homeDir) {
   const home = homeDir ?? os.homedir();
-  return path8.join(home, ".swarmvault", "models", `ggml-${modelName}.bin`);
+  return path11.join(home, ".swarmvault", "models", `ggml-${modelName}.bin`);
 }
 function modelDownloadUrl(modelName) {
   return `${HUGGINGFACE_BASE}/ggml-${modelName}.bin`;
 }
 async function downloadWhisperModel(options) {
   const destPath = expectedModelPath(options.modelName, options.homeDir);
-  await ensureDir(path8.dirname(destPath));
+  await ensureDir(path11.dirname(destPath));
   const doFetch = options.fetchImpl ?? fetch;
   const url = modelDownloadUrl(options.modelName);
   const response = await doFetch(url);
@@ -4995,8 +5686,8 @@ async function downloadWhisperModel(options) {
   });
   const tmpPath = `${destPath}.part`;
   await pipeline(source, createWriteStream(tmpPath));
-  await fs8.rename(tmpPath, destPath);
-  const stat = await fs8.stat(destPath);
+  await fs9.rename(tmpPath, destPath);
+  const stat = await fs9.stat(destPath);
   return { path: destPath, bytes: stat.size };
 }
 async function registerLocalWhisperProvider(options) {
@@ -5063,7 +5754,7 @@ async function summarizeLocalWhisperSetup(options) {
 }
 async function isExecutable(p) {
   try {
-    await fs8.access(p, fsConstants.X_OK);
+    await fs9.access(p, fsConstants.X_OK);
     return true;
   } catch {
     return false;
@@ -5133,13 +5824,13 @@ async function withCapabilityFallback(provider, capability, run, fallback) {
 }
 
 // src/schedule.ts
-import fs9 from "fs/promises";
-import path9 from "path";
+import fs10 from "fs/promises";
+import path12 from "path";
 function scheduleStatePath(schedulesDir, jobId) {
-  return path9.join(schedulesDir, `${encodeURIComponent(jobId)}.json`);
+  return path12.join(schedulesDir, `${encodeURIComponent(jobId)}.json`);
 }
 function scheduleLockPath(schedulesDir, jobId) {
-  return path9.join(schedulesDir, `${encodeURIComponent(jobId)}.lock`);
+  return path12.join(schedulesDir, `${encodeURIComponent(jobId)}.lock`);
 }
 function parseEveryDuration(value) {
   const match = value.trim().match(/^(\d+)(m|h|d)$/i);
@@ -5242,13 +5933,13 @@ async function acquireJobLease(rootDir, jobId) {
   const { paths } = await loadVaultConfig(rootDir);
   const leasePath = scheduleLockPath(paths.schedulesDir, jobId);
   await ensureDir(paths.schedulesDir);
-  const handle = await fs9.open(leasePath, "wx");
+  const handle = await fs10.open(leasePath, "wx");
   await handle.writeFile(`${process.pid}
 ${(/* @__PURE__ */ new Date()).toISOString()}
 `);
   await handle.close();
   return async () => {
-    await fs9.rm(leasePath, { force: true });
+    await fs10.rm(leasePath, { force: true });
   };
 }
 async function listSchedules(rootDir) {
@@ -5407,8 +6098,8 @@ async function serveSchedules(rootDir, pollMs = 3e4) {
 
 // src/sources.ts
 import { spawn } from "child_process";
-import fs10 from "fs/promises";
-import path10 from "path";
+import fs11 from "fs/promises";
+import path13 from "path";
 import matter3 from "gray-matter";
 import { JSDOM } from "jsdom";
 var DEFAULT_CRAWL_MAX_PAGES = 12;
@@ -5454,24 +6145,24 @@ function emptyManagedSourceSyncCounts() {
   };
 }
 function withinRoot(rootPath, targetPath) {
-  const relative = path10.relative(rootPath, targetPath);
-  return relative === "" || !relative.startsWith("..") && !path10.isAbsolute(relative);
+  const relative = path13.relative(rootPath, targetPath);
+  return relative === "" || !relative.startsWith("..") && !path13.isAbsolute(relative);
 }
 async function findNearestGitRoot2(startPath) {
-  let current = path10.resolve(startPath);
+  let current = path13.resolve(startPath);
   try {
-    const stat = await fs10.stat(current);
+    const stat = await fs11.stat(current);
     if (!stat.isDirectory()) {
-      current = path10.dirname(current);
+      current = path13.dirname(current);
     }
   } catch {
-    current = path10.dirname(current);
+    current = path13.dirname(current);
   }
   while (true) {
-    if (await fileExists(path10.join(current, ".git"))) {
+    if (await fileExists(path13.join(current, ".git"))) {
       return current;
     }
-    const parent = path10.dirname(current);
+    const parent = path13.dirname(current);
     if (parent === current) {
       return null;
     }
@@ -5545,7 +6236,7 @@ function isAllowedDocsCandidate(candidate, startUrl) {
   if (candidate.origin !== startUrl.origin) {
     return false;
   }
-  const extension = path10.extname(candidate.pathname).toLowerCase();
+  const extension = path13.extname(candidate.pathname).toLowerCase();
   if (extension && extension !== ".html" && extension !== ".htm" && extension !== ".md") {
     return false;
   }
@@ -5634,14 +6325,40 @@ function matchesManagedSourceSpec(existing, input) {
     return false;
   }
   if (input.kind === "directory" || input.kind === "file") {
-    return path10.resolve(existing.path ?? "") === path10.resolve(input.path);
+    return path13.resolve(existing.path ?? "") === path13.resolve(input.path);
+  }
+  if (input.kind === "github_repo") {
+    return (existing.url ?? "") === input.url && (existing.branch ?? "") === (input.branch ?? "") && (existing.ref ?? "") === (input.ref ?? "");
   }
   return (existing.url ?? "") === input.url;
 }
-async function resolveManagedSourceInput(rootDir, input) {
-  const absoluteInput = path10.resolve(rootDir, input);
+function normalizeGitSelector(value, label) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  if (trimmed.startsWith("-")) {
+    throw new Error(`Git ${label} must not start with "-".`);
+  }
+  if (/[\s\0]/.test(trimmed)) {
+    throw new Error(`Git ${label} must not contain whitespace or NUL bytes.`);
+  }
+  return trimmed;
+}
+function normalizeCheckoutDir(rootDir, value) {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  return path13.isAbsolute(trimmed) ? path13.resolve(trimmed) : path13.resolve(rootDir, trimmed);
+}
+async function resolveManagedSourceInput(rootDir, input, options = {}) {
+  const absoluteInput = path13.resolve(rootDir, input);
   if (!(input.startsWith("http://") || input.startsWith("https://"))) {
-    const stat = await fs10.stat(absoluteInput).catch(() => null);
+    if (options.branch || options.ref || options.checkoutDir) {
+      throw new Error("Git branch/ref/checkout options are only supported for public GitHub repo root URLs.");
+    }
+    const stat = await fs11.stat(absoluteInput).catch(() => null);
     if (!stat) {
       throw new Error(`Source not found: ${input}`);
     }
@@ -5649,7 +6366,7 @@ async function resolveManagedSourceInput(rootDir, input) {
       return {
         kind: "file",
         path: absoluteInput,
-        title: path10.basename(absoluteInput, path10.extname(absoluteInput)) || absoluteInput
+        title: path13.basename(absoluteInput, path13.extname(absoluteInput)) || absoluteInput
       };
     }
     if (!stat.isDirectory()) {
@@ -5661,16 +6378,22 @@ async function resolveManagedSourceInput(rootDir, input) {
       kind: "directory",
       path: absoluteInput,
       repoRoot,
-      title: path10.basename(absoluteInput) || absoluteInput
+      title: path13.basename(absoluteInput) || absoluteInput
     };
   }
   const github = normalizeGitHubRepoRootUrl(input);
   if (github) {
     return {
       kind: "github_repo",
-      ...github
+      ...github,
+      branch: normalizeGitSelector(options.branch, "branch"),
+      ref: normalizeGitSelector(options.ref, "ref"),
+      checkoutDir: normalizeCheckoutDir(rootDir, options.checkoutDir)
     };
   }
+  if (options.branch || options.ref || options.checkoutDir) {
+    throw new Error("Git branch/ref/checkout options are only supported for public GitHub repo root URLs.");
+  }
   const parsed = new URL(input);
   if (parsed.hostname.toLowerCase().includes("github.com")) {
     throw new Error(
@@ -5684,16 +6407,16 @@ async function resolveManagedSourceInput(rootDir, input) {
   };
 }
 function directorySourceIdsFor(manifests, inputPath) {
-  return manifests.filter((manifest) => manifest.originalPath && withinRoot(path10.resolve(inputPath), path10.resolve(manifest.originalPath))).map((manifest) => manifest.sourceId).sort((left, right) => left.localeCompare(right));
+  return manifests.filter((manifest) => manifest.originalPath && withinRoot(path13.resolve(inputPath), path13.resolve(manifest.originalPath))).map((manifest) => manifest.sourceId).sort((left, right) => left.localeCompare(right));
 }
 function fileSourceIdsFor(manifests, inputPath) {
-  const absoluteInput = path10.resolve(inputPath);
-  return manifests.filter((manifest) => manifest.originalPath && path10.resolve(manifest.originalPath) === absoluteInput).map((manifest) => manifest.sourceId).sort((left, right) => left.localeCompare(right));
+  const absoluteInput = path13.resolve(inputPath);
+  return manifests.filter((manifest) => manifest.originalPath && path13.resolve(manifest.originalPath) === absoluteInput).map((manifest) => manifest.sourceId).sort((left, right) => left.localeCompare(right));
 }
 async function syncDirectorySource(rootDir, inputPath, repoRoot) {
   const manifestsBefore = await listManifests(rootDir);
   const previousInScope = manifestsBefore.filter(
-    (manifest) => manifest.originalPath && withinRoot(path10.resolve(inputPath), path10.resolve(manifest.originalPath))
+    (manifest) => manifest.originalPath && withinRoot(path13.resolve(inputPath), path13.resolve(manifest.originalPath))
   );
   const result = await ingestDirectory(rootDir, inputPath, { repoRoot });
   const removed = [];
@@ -5701,7 +6424,7 @@ async function syncDirectorySource(rootDir, inputPath, repoRoot) {
     if (!manifest.originalPath) {
       continue;
     }
-    if (await fileExists(path10.resolve(manifest.originalPath))) {
+    if (await fileExists(path13.resolve(manifest.originalPath))) {
       continue;
     }
     const removedManifest = await removeManifestBySourceId(rootDir, manifest.sourceId);
@@ -5711,7 +6434,7 @@ async function syncDirectorySource(rootDir, inputPath, repoRoot) {
   }
   const manifestsAfter = await listManifests(rootDir);
   return {
-    title: path10.basename(inputPath) || inputPath,
+    title: path13.basename(inputPath) || inputPath,
     sourceIds: directorySourceIdsFor(manifestsAfter, inputPath),
     counts: {
       scannedCount: result.scannedCount,
@@ -5727,7 +6450,7 @@ async function syncFileSource(rootDir, inputPath) {
   const result = await ingestInputDetailed(rootDir, inputPath);
   const manifestsAfter = await listManifests(rootDir);
   return {
-    title: path10.basename(inputPath, path10.extname(inputPath)) || inputPath,
+    title: path13.basename(inputPath, path13.extname(inputPath)) || inputPath,
     sourceIds: fileSourceIdsFor(manifestsAfter, inputPath),
     counts: {
       scannedCount: result.scannedCount,
@@ -5761,8 +6484,11 @@ async function runGitCommand(cwd, args) {
 }
 async function syncGitHubRepoSource(rootDir, entry) {
   const workingDir = await managedSourceWorkingDir(rootDir, entry.id);
-  const checkoutDir = path10.join(workingDir, "checkout");
-  await fs10.rm(checkoutDir, { recursive: true, force: true });
+  const externalCheckoutDir = entry.checkoutDir ? path13.resolve(entry.checkoutDir) : void 0;
+  const checkoutDir = externalCheckoutDir ?? path13.join(workingDir, "checkout");
+  if (!externalCheckoutDir) {
+    await fs11.rm(checkoutDir, { recursive: true, force: true });
+  }
   await ensureDir(workingDir);
   if (!entry.url) {
     throw new Error(`Managed source ${entry.id} is missing its repository URL.`);
@@ -5771,7 +6497,35 @@ async function syncGitHubRepoSource(rootDir, entry) {
   if (!github) {
     throw new Error(`Managed source ${entry.id} has an invalid GitHub repo URL.`);
   }
-  await runGitCommand(workingDir, ["clone", "--depth", "1", github.cloneUrl, "checkout"]);
+  const branch = normalizeGitSelector(entry.branch, "branch");
+  const ref = normalizeGitSelector(entry.ref, "ref");
+  const cloneArgs = ["clone", "--depth", "1"];
+  if (branch) {
+    cloneArgs.push("--branch", branch);
+  }
+  cloneArgs.push(github.cloneUrl, checkoutDir);
+  if (await fileExists(path13.join(checkoutDir, ".git"))) {
+    await runGitCommand(checkoutDir, ["remote", "set-url", "origin", github.cloneUrl]);
+    if (branch) {
+      await runGitCommand(checkoutDir, ["fetch", "--depth", "1", "origin", branch]);
+    } else {
+      await runGitCommand(checkoutDir, ["fetch", "--depth", "1", "origin"]);
+    }
+    if (!ref) {
+      await runGitCommand(checkoutDir, ["checkout", "--detach", "FETCH_HEAD"]);
+    }
+  } else {
+    const existingEntries = await fs11.readdir(checkoutDir).catch(() => []);
+    if (externalCheckoutDir && existingEntries.length > 0) {
+      throw new Error(`Checkout directory exists but is not a Git repository: ${checkoutDir}`);
+    }
+    await ensureDir(path13.dirname(checkoutDir));
+    await runGitCommand(workingDir, cloneArgs);
+  }
+  if (ref) {
+    await runGitCommand(checkoutDir, ["fetch", "--depth", "1", "origin", ref]);
+    await runGitCommand(checkoutDir, ["checkout", "--detach", "FETCH_HEAD"]);
+  }
   return await syncDirectorySource(rootDir, checkoutDir, checkoutDir);
 }
 async function syncCrawlSource(rootDir, entry, options) {
@@ -5892,7 +6646,7 @@ function scopedNodeIds(graph, sourceIds) {
 async function loadSourceAnalyses(rootDir, sourceIds) {
   const { paths } = await loadVaultConfig(rootDir);
   const analyses = await Promise.all(
-    sourceIds.map(async (sourceId) => await readJsonFile(path10.join(paths.analysesDir, `${sourceId}.json`)))
+    sourceIds.map(async (sourceId) => await readJsonFile(path13.join(paths.analysesDir, `${sourceId}.json`)))
   );
   return analyses.filter((analysis) => Boolean(analysis?.sourceId));
 }
@@ -6053,9 +6807,9 @@ async function writeSourceBriefForScope(rootDir, source) {
       confidence: 0.82
     }
   });
-  const absolutePath = path10.join(paths.wikiDir, output.page.path);
-  await ensureDir(path10.dirname(absolutePath));
-  await fs10.writeFile(absolutePath, output.content, "utf8");
+  const absolutePath = path13.join(paths.wikiDir, output.page.path);
+  await ensureDir(path13.dirname(absolutePath));
+  await fs11.writeFile(absolutePath, output.content, "utf8");
   return absolutePath;
 }
 async function writeSourceBrief(rootDir, source) {
@@ -6343,7 +7097,7 @@ function selectGuidedTargetPages(scope, sourcePages, questions) {
   return (matchedTargets.length ? matchedTargets : canonicalPages).slice(0, 6);
 }
 function insightRelativePathForTarget(page, scope) {
-  const basename = path10.basename(page.path);
+  const basename = path13.basename(page.path);
   if (page.kind === "concept") {
     return `insights/concepts/${basename}`;
   }
@@ -6570,7 +7324,7 @@ async function stageSourceReviewForScope(rootDir, scope) {
   return {
     sourceId: scope.id,
     pageId: output.page.id,
-    reviewPath: path10.join(approval.approvalDir, "wiki", output.page.path),
+    reviewPath: path13.join(approval.approvalDir, "wiki", output.page.path),
     staged: true,
     approvalId: approval.approvalId,
     approvalDir: approval.approvalDir
@@ -6637,7 +7391,7 @@ async function buildSourceSessionSavedPage(rootDir, scope, session) {
   const evidenceState = contradictions.length > 0 ? "conflicting" : session.targetedPagePaths.some(
     (targetPath) => sourcePages.some((page) => page.path === targetPath && page.sourceIds.some((sourceId) => !scope.sourceIds.includes(sourceId)))
   ) ? "reinforcing" : session.targetedPagePaths.length ? "new" : "needs_judgment";
-  const relativeBriefPath = session.briefPath && path10.isAbsolute(session.briefPath) ? path10.relative(paths.wikiDir, session.briefPath) : session.briefPath;
+  const relativeBriefPath = session.briefPath && path13.isAbsolute(session.briefPath) ? path13.relative(paths.wikiDir, session.briefPath) : session.briefPath;
   const sessionMarkdown = [
     `# Guided Session: ${scope.title}`,
     "",
@@ -6720,9 +7474,9 @@ async function buildSourceSessionSavedPage(rootDir, scope, session) {
 async function persistSourceSessionPage(rootDir, scope, session) {
   const { paths } = await loadVaultConfig(rootDir);
   const output = await buildSourceSessionSavedPage(rootDir, scope, session);
-  const absolutePath = path10.join(paths.wikiDir, output.page.path);
-  await ensureDir(path10.dirname(absolutePath));
-  await fs10.writeFile(absolutePath, output.content, "utf8");
+  const absolutePath = path13.join(paths.wikiDir, output.page.path);
+  await ensureDir(path13.dirname(absolutePath));
+  await fs11.writeFile(absolutePath, output.content, "utf8");
   return { pageId: output.page.id, sessionPath: absolutePath };
 }
 async function buildGuidedUpdatePages(rootDir, scope, session) {
@@ -6750,8 +7504,8 @@ async function buildGuidedUpdatePages(rootDir, scope, session) {
     targetPages.map(async (targetPage) => {
       const evidenceState = classifyGuidedEvidenceState(scope, targetPage, contradictions);
       const relativePath = useCanonicalTargets && targetPage ? targetPage.path : targetPage ? insightRelativePathForTarget(targetPage, scope) : `insights/topics/${slugify(scope.title)}.md`;
-      const absolutePath = path10.join(paths.wikiDir, relativePath);
-      const existingContent = await fileExists(absolutePath) ? await fs10.readFile(absolutePath, "utf8") : "";
+      const absolutePath = path13.join(paths.wikiDir, relativePath);
+      const existingContent = await fileExists(absolutePath) ? await fs11.readFile(absolutePath, "utf8") : "";
       const parsed = existingContent ? matter3(existingContent) : { data: {}, content: "" };
       const existingData = parsed.data;
       const existingSourceIds = Array.isArray(existingData.source_ids) ? existingData.source_ids.filter((value) => typeof value === "string") : [];
@@ -6922,8 +7676,8 @@ async function stageSourceGuideForScope(rootDir, scope, options = {}) {
     }
   );
   session.status = "staged";
-  session.reviewPath = path10.join(approval.approvalDir, "wiki", reviewOutput.page.path);
-  session.guidePath = path10.join(approval.approvalDir, "wiki", guideOutput.page.path);
+  session.reviewPath = path13.join(approval.approvalDir, "wiki", reviewOutput.page.path);
+  session.guidePath = path13.join(approval.approvalDir, "wiki", guideOutput.page.path);
   session.approvalId = approval.approvalId;
   session.approvalDir = approval.approvalDir;
   const persisted = await persistSourceSessionPage(rootDir, scope, session);
@@ -7057,16 +7811,28 @@ async function addManagedSource(rootDir, input, options = {}) {
   const briefRequested = guideRequested ? true : options.brief ?? true;
   const reviewRequested = guideRequested ? false : options.review ?? false;
   const sources = await loadManagedSources(rootDir);
-  const resolved = await resolveManagedSourceInput(rootDir, input);
+  const resolved = await resolveManagedSourceInput(rootDir, input, options);
   const existing = sources.find((candidate) => matchesManagedSourceSpec(candidate, resolved));
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const source = existing ?? {
-    id: resolved.kind === "directory" || resolved.kind === "file" ? stableManagedSourceId(resolved.kind, path10.resolve(resolved.path), resolved.title) : stableManagedSourceId(resolved.kind, resolved.url, resolved.title),
+  const source = existing ? {
+    ...existing,
+    branch: resolved.kind === "github_repo" ? resolved.branch : existing.branch,
+    ref: resolved.kind === "github_repo" ? resolved.ref : existing.ref,
+    checkoutDir: resolved.kind === "github_repo" ? resolved.checkoutDir ?? existing.checkoutDir : existing.checkoutDir
+  } : {
+    id: resolved.kind === "directory" || resolved.kind === "file" ? stableManagedSourceId(resolved.kind, path13.resolve(resolved.path), resolved.title) : stableManagedSourceId(
+      resolved.kind,
+      resolved.kind === "github_repo" ? `${resolved.url}#branch=${resolved.branch ?? ""}#ref=${resolved.ref ?? ""}` : resolved.url,
+      resolved.title
+    ),
     kind: resolved.kind,
     title: resolved.title,
     path: resolved.kind === "directory" || resolved.kind === "file" ? resolved.path : void 0,
     repoRoot: resolved.kind === "directory" ? resolved.repoRoot : void 0,
     url: resolved.kind === "directory" || resolved.kind === "file" ? void 0 : resolved.url,
+    branch: resolved.kind === "github_repo" ? resolved.branch : void 0,
+    ref: resolved.kind === "github_repo" ? resolved.ref : void 0,
+    checkoutDir: resolved.kind === "github_repo" ? resolved.checkoutDir : void 0,
     createdAt: now,
     updatedAt: now,
     status: "ready",
@@ -7189,7 +7955,7 @@ async function deleteManagedSource(rootDir, id) {
     sources.filter((source) => source.id !== id)
   );
   const workingDir = await managedSourceWorkingDir(rootDir, id);
-  await fs10.rm(workingDir, { recursive: true, force: true });
+  await fs11.rm(workingDir, { recursive: true, force: true });
   return { removed: target };
 }
 
@@ -7197,9 +7963,9 @@ async function deleteManagedSource(rootDir, id) {
 import { execFile as execFile2 } from "child_process";
 import { randomUUID } from "crypto";
 import { EventEmitter } from "events";
-import fs11 from "fs/promises";
+import fs12 from "fs/promises";
 import http from "http";
-import path11 from "path";
+import path14 from "path";
 import { promisify as promisify2 } from "util";
 import matter4 from "gray-matter";
 import mime from "mime-types";
@@ -7353,7 +8119,7 @@ function toViewerLintFindings(findings) {
 var execFileAsync2 = promisify2(execFile2);
 async function isReadableFile(absolutePath) {
   try {
-    const stats = await fs11.stat(absolutePath);
+    const stats = await fs12.stat(absolutePath);
     return stats.isFile();
   } catch {
     return false;
@@ -7364,15 +8130,15 @@ async function readViewerPage(rootDir, relativePath) {
     return null;
   }
   const { paths } = await loadVaultConfig(rootDir);
-  const absolutePath = path11.resolve(paths.wikiDir, relativePath);
+  const absolutePath = path14.resolve(paths.wikiDir, relativePath);
   if (!isPathWithin(paths.wikiDir, absolutePath) || !await isReadableFile(absolutePath)) {
     return null;
   }
-  const raw = await fs11.readFile(absolutePath, "utf8");
+  const raw = await fs12.readFile(absolutePath, "utf8");
   const parsed = matter4(raw);
   return {
     path: relativePath,
-    title: typeof parsed.data.title === "string" ? parsed.data.title : path11.basename(relativePath, path11.extname(relativePath)),
+    title: typeof parsed.data.title === "string" ? parsed.data.title : path14.basename(relativePath, path14.extname(relativePath)),
     frontmatter: parsed.data,
     content: parsed.content,
     assets: normalizeOutputAssets(parsed.data.output_assets)
@@ -7383,12 +8149,12 @@ async function readViewerAsset(rootDir, relativePath) {
     return null;
   }
   const { paths } = await loadVaultConfig(rootDir);
-  const absolutePath = path11.resolve(paths.wikiDir, relativePath);
+  const absolutePath = path14.resolve(paths.wikiDir, relativePath);
   if (!isPathWithin(paths.wikiDir, absolutePath) || !await isReadableFile(absolutePath)) {
     return null;
   }
   return {
-    buffer: await fs11.readFile(absolutePath),
+    buffer: await fs12.readFile(absolutePath),
     mimeType: mime.lookup(absolutePath) || "application/octet-stream"
   };
 }
@@ -7424,8 +8190,8 @@ async function writeInboxClip(rootDir, body) {
   const tags = Array.isArray(body.tags) ? body.tags.filter((tag) => typeof tag === "string" && tag.trim().length > 0) : [];
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const fileName = `${now.replace(/[:.]/g, "-")}-${slugForClip(title)}.md`;
-  const inboxPath = path11.join(paths.inboxDir, fileName);
-  await fs11.mkdir(paths.inboxDir, { recursive: true });
+  const inboxPath = path14.join(paths.inboxDir, fileName);
+  await fs12.mkdir(paths.inboxDir, { recursive: true });
   const lines = [
     "---",
     `title: ${JSON.stringify(title)}`,
@@ -7442,17 +8208,17 @@ async function writeInboxClip(rootDir, body) {
     selectionHtml && !markdown ? ["", "## Original HTML", "", "```html", selectionHtml, "```"].join("\n") : void 0,
     ""
   ].filter((line) => line !== void 0);
-  await fs11.writeFile(inboxPath, lines.join("\n"), "utf8");
+  await fs12.writeFile(inboxPath, lines.join("\n"), "utf8");
   const result = await importInbox(rootDir, paths.inboxDir);
   return { mode: "inbox", inboxPath, result };
 }
 async function ensureViewerDist(viewerDistDir) {
-  const indexPath = path11.join(viewerDistDir, "index.html");
+  const indexPath = path14.join(viewerDistDir, "index.html");
   if (await fileExists(indexPath)) {
     return;
   }
-  const viewerProjectDir = path11.dirname(viewerDistDir);
-  if (await fileExists(path11.join(viewerProjectDir, "package.json"))) {
+  const viewerProjectDir = path14.dirname(viewerDistDir);
+  if (await fileExists(path14.join(viewerProjectDir, "package.json"))) {
     await execFileAsync2("pnpm", ["build"], { cwd: viewerProjectDir });
   }
 }
@@ -7475,7 +8241,7 @@ async function startGraphServer(rootDir, port, options = {}) {
           response.end(JSON.stringify({ error: "Graph artifact not found. Run `swarmvault compile` first." }));
           return;
         }
-        const reportPath = path11.join(paths.wikiDir, "graph", "report.json");
+        const reportPath = path14.join(paths.wikiDir, "graph", "report.json");
         const report = await readJsonFile(reportPath) ?? null;
         response.writeHead(200, { "content-type": "application/json" });
         response.end(JSON.stringify(buildViewerGraphArtifact(graph, { report, full: options.full ?? false })));
@@ -7539,13 +8305,13 @@ async function startGraphServer(rootDir, port, options = {}) {
         return;
       }
       if (url.pathname === "/api/graph-report") {
-        const reportPath = path11.join(paths.wikiDir, "graph", "report.json");
+        const reportPath = path14.join(paths.wikiDir, "graph", "report.json");
         if (!await fileExists(reportPath)) {
           response.writeHead(404, { "content-type": "application/json" });
           response.end(JSON.stringify({ error: "Graph report artifact not found. Run `swarmvault compile` first." }));
           return;
         }
-        const body = await fs11.readFile(reportPath, "utf8");
+        const body = await fs12.readFile(reportPath, "utf8");
         response.writeHead(200, { "content-type": "application/json" });
         response.end(body);
         return;
@@ -7783,7 +8549,7 @@ async function startGraphServer(rootDir, port, options = {}) {
         return;
       }
       if (url.pathname === "/api/workspace") {
-        const reportPath = path11.join(paths.wikiDir, "graph", "report.json");
+        const reportPath = path14.join(paths.wikiDir, "graph", "report.json");
         const [graphRaw, reportRaw, approvalsRaw, candidatesRaw, memoryTasksRaw, watchStatusRaw, lintRaw, doctorRaw] = await Promise.all([
           readJsonFile(paths.graphPath).catch(() => null),
           readJsonFile(reportPath).catch(() => null),
@@ -7908,15 +8674,15 @@ async function startGraphServer(rootDir, port, options = {}) {
         return;
       }
       const relativePath = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
-      const target = path11.join(paths.viewerDistDir, relativePath);
-      const fallback = path11.join(paths.viewerDistDir, "index.html");
+      const target = path14.join(paths.viewerDistDir, relativePath);
+      const fallback = path14.join(paths.viewerDistDir, "index.html");
       const filePath = await fileExists(target) ? target : fallback;
       if (!await fileExists(filePath)) {
         response.writeHead(503, { "content-type": "text/plain" });
         response.end("Viewer build not found. Run `pnpm build` first.");
         return;
       }
-      const staticBody = await fs11.readFile(filePath);
+      const staticBody = await fs12.readFile(filePath);
       response.writeHead(200, { "content-type": mime.lookup(filePath) || "text/plain" });
       response.end(staticBody);
     } catch (error) {
@@ -7956,7 +8722,7 @@ async function exportGraphHtml(rootDir, outputPath, options = {}) {
     throw new Error("Graph artifact not found. Run `swarmvault compile` first.");
   }
   await ensureViewerDist(paths.viewerDistDir);
-  const indexPath = path11.join(paths.viewerDistDir, "index.html");
+  const indexPath = path14.join(paths.viewerDistDir, "index.html");
   if (!await fileExists(indexPath)) {
     throw new Error("Viewer build not found. Run `pnpm build` first.");
   }
@@ -7982,17 +8748,17 @@ async function exportGraphHtml(rootDir, outputPath, options = {}) {
       } : null;
     })
   );
-  const rawHtml = await fs11.readFile(indexPath, "utf8");
+  const rawHtml = await fs12.readFile(indexPath, "utf8");
   const scriptMatch = rawHtml.match(/<script type="module" crossorigin src="([^"]+)"><\/script>/);
   const styleMatch = rawHtml.match(/<link rel="stylesheet" crossorigin href="([^"]+)">/);
-  const scriptPath = scriptMatch?.[1] ? path11.join(paths.viewerDistDir, scriptMatch[1].replace(/^\//, "")) : null;
-  const stylePath = styleMatch?.[1] ? path11.join(paths.viewerDistDir, styleMatch[1].replace(/^\//, "")) : null;
+  const scriptPath = scriptMatch?.[1] ? path14.join(paths.viewerDistDir, scriptMatch[1].replace(/^\//, "")) : null;
+  const stylePath = styleMatch?.[1] ? path14.join(paths.viewerDistDir, styleMatch[1].replace(/^\//, "")) : null;
   if (!scriptPath || !await fileExists(scriptPath)) {
     throw new Error("Viewer script bundle not found. Run `pnpm build` first.");
   }
-  const script = await fs11.readFile(scriptPath, "utf8");
-  const style = stylePath && await fileExists(stylePath) ? await fs11.readFile(stylePath, "utf8") : "";
-  const report = await readJsonFile(path11.join(paths.wikiDir, "graph", "report.json"));
+  const script = await fs12.readFile(scriptPath, "utf8");
+  const style = stylePath && await fileExists(stylePath) ? await fs12.readFile(stylePath, "utf8") : "";
+  const report = await readJsonFile(path14.join(paths.wikiDir, "graph", "report.json"));
   const embeddedData = JSON.stringify(
     { graph: buildViewerGraphArtifact(graph, { report, full: options.full ?? false }), pages: pages.filter(Boolean), report },
     null,
@@ -8015,9 +8781,9 @@ async function exportGraphHtml(rootDir, outputPath, options = {}) {
     "</html>",
     ""
   ].filter(Boolean).join("\n");
-  await fs11.mkdir(path11.dirname(outputPath), { recursive: true });
-  await fs11.writeFile(outputPath, html, "utf8");
-  return path11.resolve(outputPath);
+  await fs12.mkdir(path14.dirname(outputPath), { recursive: true });
+  await fs12.writeFile(outputPath, html, "utf8");
+  return path14.resolve(outputPath);
 }
 export {
   ALL_MIGRATIONS,
@@ -8031,6 +8797,7 @@ export {
   LOCAL_WHISPER_MODEL_SIZES,
   LocalWhisperProviderAdapter,
   OPENAI_COMPATIBLE_CAPABILITY_MATRIX,
+  SWARMVAULT_OUT_ENV,
   acceptApproval,
   addInput,
   addManagedSource,
@@ -8046,8 +8813,10 @@ export {
   buildConfiguredRedactor,
   buildContextPack,
   buildGraphShareArtifact,
+  buildGraphTree,
   buildMemoryGraphElements,
   buildRedactor,
+  checkTrackedRepoChanges,
   compileVault,
   computeDecayScore,
   consolidateVault,
@@ -8068,17 +8837,20 @@ export {
   estimatePageTokens,
   estimateTokens,
   evaluateCandidateForPromotion,
+  evaluateGraphShrinkGuard,
   expectedModelPath,
   explainGraphVault,
   exploreVault,
   exportGraphFormat,
   exportGraphHtml,
   exportGraphReportHtml,
+  exportGraphTree,
   exportObsidianCanvas,
   exportObsidianVault,
   finishMemoryTask,
   getGitHookStatus,
   getGraphCommunityVault,
+  getGraphStatus,
   getProviderForTask,
   getRetrievalStatus,
   getWatchStatus,
@@ -8117,6 +8889,7 @@ export {
   lookupPresetCapabilities,
   markSuperseded,
   memoryTaskHashes,
+  mergeGraphFiles,
   modelDownloadUrl,
   pathGraphVault,
   persistDecayFrontmatter,
@@ -8133,6 +8906,7 @@ export {
   readMemoryTask,
   readPage,
   rebuildRetrievalIndex,
+  refreshGraphClusters,
   registerLocalWhisperProvider,
   rejectApproval,
   reloadManagedSources,
@@ -8143,8 +8917,10 @@ export {
   renderGraphShareMarkdown,
   renderGraphSharePreviewHtml,
   renderGraphShareSvg,
+  renderGraphTreeHtml,
   renderMemoryTaskMarkdown,
   resetDecay,
+  resolveArtifactRootDir,
   resolveConsolidationConfig,
   resolveDecayConfig,
   resolveLargeRepoDefaults,