graphifyy 0.3.17 → 0.3.28

package/dist/skill-runtime.js

@@ -7,14 +7,13 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 
 // src/skill-runtime.ts
 import { Command } from "commander";
-import Graph3 from "graphology";
 import {
-  existsSync as existsSync7,
-  mkdirSync as mkdirSync4,
+  existsSync as existsSync8,
+  mkdirSync as mkdirSync5,
   readFileSync as readFileSync5,
-  writeFileSync as writeFileSync5
+  writeFileSync as writeFileSync6
 } from "fs";
-import { dirname as dirname2, join as join4, resolve as resolve5 } from "path";
+import { dirname as dirname4, join as join5, resolve as resolve7 } from "path";
 import { fileURLToPath } from "url";
 
 // src/analyze.ts
@@ -36,10 +35,75 @@ function toNumericMap(value) {
 
 // src/cluster.ts
 import louvain from "graphology-communities-louvain";
+
+// src/graph.ts
+import Graph from "graphology";
+function createGraph(directed = false) {
+  return new Graph({ type: directed ? "directed" : "undirected", multi: false });
+}
+function isDirectedGraph(G) {
+  return G.type === "directed";
+}
+function loadGraphFromData(raw) {
+  const G = createGraph(raw.directed === true);
+  for (const [key, value] of Object.entries(raw.graph ?? {})) {
+    G.setAttribute(key, value);
+  }
+  for (const node of raw.nodes ?? []) {
+    const { id, ...attrs } = node;
+    G.mergeNode(id, attrs);
+  }
+  for (const link of raw.links ?? raw.edges ?? []) {
+    const { source, target, ...attrs } = link;
+    if (!G.hasNode(source) || !G.hasNode(target)) continue;
+    try {
+      G.mergeEdge(source, target, attrs);
+    } catch {
+    }
+  }
+  if (raw.hyperedges && raw.hyperedges.length > 0) {
+    G.setAttribute("hyperedges", raw.hyperedges);
+  }
+  return G;
+}
+function toUndirectedGraph(G) {
+  if (!isDirectedGraph(G)) return G.copy();
+  const copy = createGraph(false);
+  for (const [key, value] of Object.entries(G.getAttributes())) {
+    copy.setAttribute(key, value);
+  }
+  G.forEachNode((nodeId, attrs) => {
+    copy.mergeNode(nodeId, attrs);
+  });
+  G.forEachEdge((_edge, attrs, source, target) => {
+    if (!copy.hasNode(source) || !copy.hasNode(target)) return;
+    try {
+      copy.mergeEdge(source, target, attrs);
+    } catch {
+    }
+  });
+  return copy;
+}
+function forEachTraversalNeighbor(G, node, callback) {
+  if (isDirectedGraph(G)) {
+    G.forEachOutboundNeighbor(node, callback);
+    return;
+  }
+  G.forEachNeighbor(node, callback);
+}
+function traversalNeighbors(G, node) {
+  const neighbors = [];
+  forEachTraversalNeighbor(G, node, (neighbor) => {
+    neighbors.push(neighbor);
+  });
+  return neighbors;
+}
+
+// src/cluster.ts
 var MAX_COMMUNITY_FRACTION = 0.25;
 var MIN_SPLIT_SIZE = 10;
 function partition(G) {
-  const result = louvain(G);
+  const result = louvain(G.type === "directed" ? toUndirectedGraph(G) : G);
   const map = /* @__PURE__ */ new Map();
   for (const [node, cid] of Object.entries(result)) {
     map.set(node, cid);
@@ -142,93 +206,435 @@ function scoreAll(G, communities) {
   return result;
 }
 
-// src/analyze.ts
-function nodeCommunityMap(communities) {
-  const communityMap = toNumericMap(communities);
-  const result = /* @__PURE__ */ new Map();
-  for (const [cid, nodes] of communityMap) {
-    for (const n of nodes) result.set(n, cid);
+// src/detect.ts
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  statSync,
+  existsSync,
+  mkdirSync,
+  lstatSync
+} from "fs";
+import { join, resolve, extname, basename, relative, sep, dirname } from "path";
+import { createHash } from "crypto";
+var MANIFEST_PATH = "graphify-out/manifest.json";
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".py",
+  ".ts",
+  ".js",
+  ".jsx",
+  ".tsx",
+  ".go",
+  ".rs",
+  ".java",
+  ".cpp",
+  ".cc",
+  ".cxx",
+  ".c",
+  ".h",
+  ".hpp",
+  ".rb",
+  ".swift",
+  ".kt",
+  ".kts",
+  ".cs",
+  ".scala",
+  ".php",
+  ".lua",
+  ".toc",
+  ".zig",
+  ".ps1",
+  ".ex",
+  ".exs",
+  ".m",
+  ".mm",
+  ".jl"
+]);
+var DOC_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".txt", ".rst"]);
+var PAPER_EXTENSIONS = /* @__PURE__ */ new Set([".pdf"]);
+var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"]);
+var OFFICE_EXTENSIONS = /* @__PURE__ */ new Set([".docx", ".xlsx"]);
+var VIDEO_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".mp4",
+  ".mov",
+  ".webm",
+  ".mkv",
+  ".avi",
+  ".m4v",
+  ".mp3",
+  ".wav",
+  ".m4a",
+  ".ogg"
+]);
+var CORPUS_WARN_THRESHOLD = 5e4;
+var CORPUS_UPPER_THRESHOLD = 5e5;
+var FILE_COUNT_UPPER = 200;
+var SENSITIVE_PATTERNS = [
+  /(^|[\\/])\.(env|envrc)(\.|$)/i,
+  /\.(pem|key|p12|pfx|cert|crt|der|p8)$/i,
+  /(credential|secret|passwd|password|token|private_key)/i,
+  /(id_rsa|id_dsa|id_ecdsa|id_ed25519)(\.pub)?$/,
+  /(\.netrc|\.pgpass|\.htpasswd)$/i,
+  /(aws_credentials|gcloud_credentials|service.account)/i
+];
+var PAPER_SIGNALS = [
+  /\barxiv\b/i,
+  /\bdoi\s*:/i,
+  /\babstract\b/i,
+  /\bproceedings\b/i,
+  /\bjournal\b/i,
+  /\bpreprint\b/i,
+  /\\cite\{/,
+  /\[\d+\]/,
+  /\[\n\d+\n\]/,
+  /eq\.\s*\d+|equation\s+\d+/i,
+  /\d{4}\.\d{4,5}/,
+  /\bwe propose\b/i,
+  /\bliterature\b/i
+];
+var PAPER_SIGNAL_THRESHOLD = 3;
+function isSensitive(filePath) {
+  const name = basename(filePath);
+  return SENSITIVE_PATTERNS.some((p) => p.test(name) || p.test(filePath));
+}
+function looksLikePaper(filePath) {
+  try {
+    const text = readFileSync(filePath, "utf-8").slice(0, 3e3);
+    const hits = PAPER_SIGNALS.filter((p) => p.test(text)).length;
+    return hits >= PAPER_SIGNAL_THRESHOLD;
+  } catch {
+    return false;
   }
-  return result;
 }
-function isFileNode(G, nodeId) {
-  const attrs = G.getNodeAttributes(nodeId);
-  const label = attrs.label ?? "";
-  if (!label) return false;
-  const sourceFile = attrs.source_file ?? "";
-  if (sourceFile) {
-    const fileName = sourceFile.split("/").pop() ?? "";
-    if (label === fileName) return true;
+var ASSET_DIR_MARKERS = /* @__PURE__ */ new Set([".imageset", ".xcassets", ".appiconset", ".colorset", ".launchimage"]);
+function classifyFile(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if (CODE_EXTENSIONS.has(ext)) return "code" /* CODE */;
+  if (PAPER_EXTENSIONS.has(ext)) {
+    const parts = filePath.split(sep);
+    if (parts.some((p) => [...ASSET_DIR_MARKERS].some((m) => p.endsWith(m)))) return null;
+    return "paper" /* PAPER */;
   }
-  if (label.startsWith(".") && label.endsWith("()")) return true;
-  if (label.endsWith("()") && G.degree(nodeId) <= 1) return true;
-  return false;
+  if (IMAGE_EXTENSIONS.has(ext)) return "image" /* IMAGE */;
+  if (VIDEO_EXTENSIONS.has(ext)) return "video" /* VIDEO */;
+  if (DOC_EXTENSIONS.has(ext)) {
+    if (looksLikePaper(filePath)) return "paper" /* PAPER */;
+    return "document" /* DOCUMENT */;
+  }
+  if (OFFICE_EXTENSIONS.has(ext)) return "document" /* DOCUMENT */;
+  return null;
 }
-function isConceptNode(G, nodeId) {
-  const data = G.getNodeAttributes(nodeId);
-  const source = data.source_file ?? "";
-  if (!source) return true;
-  const lastPart = source.split("/").pop() ?? "";
-  if (!lastPart.includes(".")) return true;
-  return false;
+function countWords(filePath) {
+  try {
+    const text = readFileSync(filePath, "utf-8");
+    return text.split(/\s+/).filter(Boolean).length;
+  } catch {
+    return 0;
+  }
 }
-var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
-  "py",
-  "ts",
-  "tsx",
-  "js",
-  "go",
-  "rs",
-  "java",
-  "rb",
-  "cpp",
-  "c",
-  "h",
-  "cs",
-  "kt",
-  "scala",
-  "php"
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  "venv",
+  ".venv",
+  "env",
+  ".env",
+  "node_modules",
+  "__pycache__",
+  ".git",
+  "dist",
+  "build",
+  "target",
+  "out",
+  "site-packages",
+  "lib64",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".ruff_cache",
+  ".tox",
+  ".eggs"
 ]);
-var PAPER_EXTENSIONS = /* @__PURE__ */ new Set(["pdf"]);
-var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set(["png", "jpg", "jpeg", "webp", "gif", "svg"]);
-function fileCategory(path) {
-  const ext = path.includes(".") ? path.split(".").pop()?.toLowerCase() ?? "" : "";
-  if (CODE_EXTENSIONS.has(ext)) return "code";
-  if (PAPER_EXTENSIONS.has(ext)) return "paper";
-  if (IMAGE_EXTENSIONS.has(ext)) return "image";
-  return "doc";
-}
-function topLevelDir(path) {
-  return path.includes("/") ? path.split("/")[0] : path;
+function isNoiseDir(part) {
+  if (SKIP_DIRS.has(part)) return true;
+  if (part.endsWith("_venv") || part.endsWith("_env")) return true;
+  if (part.endsWith(".egg-info")) return true;
+  return false;
 }
-function surpriseScore(G, u, v, data, nodeCommunity, uSource, vSource) {
-  let score = 0;
-  const reasons = [];
-  const conf = data.confidence ?? "EXTRACTED";
-  const confBonus = { AMBIGUOUS: 3, INFERRED: 2, EXTRACTED: 1 };
-  score += confBonus[conf] ?? 1;
-  if (conf === "AMBIGUOUS" || conf === "INFERRED") {
-    reasons.push(`${conf.toLowerCase()} connection - not explicitly stated in source`);
-  }
-  const catU = fileCategory(uSource);
-  const catV = fileCategory(vSource);
-  if (catU !== catV) {
-    score += 2;
-    reasons.push(`crosses file types (${catU} \u2194 ${catV})`);
+function loadGraphifyignore(root) {
+  const patterns = [];
+  let current = resolve(root);
+  while (true) {
+    const ignoreFile = join(current, ".graphifyignore");
+    if (existsSync(ignoreFile)) {
+      for (let line of readFileSync(ignoreFile, "utf-8").split("\n")) {
+        line = line.trim();
+        if (line && !line.startsWith("#")) {
+          patterns.push(line);
+        }
+      }
+    }
+    if (existsSync(join(current, ".git"))) {
+      break;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
   }
-  if (topLevelDir(uSource) !== topLevelDir(vSource)) {
-    score += 2;
-    reasons.push("connects across different repos/directories");
+  return patterns;
+}
+function matchGlob(text, pattern) {
+  const regex = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${regex}$`).test(text);
+}
+function isIgnored(filePath, root, patterns) {
+  if (patterns.length === 0) return false;
+  let rel;
+  try {
+    rel = relative(root, filePath).replace(/\\/g, "/");
+  } catch {
+    return false;
   }
-  const cidU = nodeCommunity.get(u);
-  const cidV = nodeCommunity.get(v);
-  if (cidU !== void 0 && cidV !== void 0 && cidU !== cidV) {
-    score += 1;
-    reasons.push("bridges separate communities");
+  const parts = rel.split("/");
+  for (const pattern of patterns) {
+    const p = pattern.replace(/^\/+|\/+$/g, "");
+    if (!p) continue;
+    if (matchGlob(rel, p)) return true;
+    if (matchGlob(basename(filePath), p)) return true;
+    for (let i = 0; i < parts.length; i++) {
+      if (matchGlob(parts[i], p)) return true;
+      if (matchGlob(parts.slice(0, i + 1).join("/"), p)) return true;
+    }
   }
-  if (data.relation === "semantically_similar_to") {
-    score = Math.floor(score * 1.5);
-    reasons.push("semantically similar concepts with no structural link");
+  return false;
+}
+function walkDir(dir, root, ignorePatterns, followSymlinks, skipPrune) {
+  const result = [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return result;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    let stat;
+    try {
+      stat = followSymlinks ? statSync(full) : lstatSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      if (!skipPrune) {
+        if (entry.startsWith(".")) continue;
+        if (isNoiseDir(entry)) continue;
+        if (isIgnored(full, root, ignorePatterns)) continue;
+      }
+      result.push(...walkDir(full, root, ignorePatterns, followSymlinks, skipPrune));
+    } else if (stat.isFile()) {
+      result.push(full);
+    }
+  }
+  return result;
+}
+function detect(root, options) {
+  const followSymlinks = options?.followSymlinks ?? false;
+  const rootResolved = resolve(root);
+  const ignorePatterns = loadGraphifyignore(rootResolved);
+  const convertedDir = join(rootResolved, "graphify-out", "converted");
+  const memoryDir = join(rootResolved, "graphify-out", "memory");
+  const files = {
+    code: [],
+    document: [],
+    paper: [],
+    image: [],
+    video: []
+  };
+  let totalWords = 0;
+  const skippedSensitive = [];
+  const allFiles = walkDir(rootResolved, rootResolved, ignorePatterns, followSymlinks, false);
+  if (existsSync(memoryDir)) {
+    allFiles.push(...walkDir(memoryDir, rootResolved, ignorePatterns, followSymlinks, true));
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of allFiles) {
+    if (seen.has(p)) continue;
+    seen.add(p);
+    const inMemory = existsSync(memoryDir) && p.startsWith(memoryDir);
+    if (!inMemory) {
+      if (basename(p).startsWith(".")) continue;
+      if (p.startsWith(convertedDir)) continue;
+    }
+    if (isIgnored(p, rootResolved, ignorePatterns)) continue;
+    if (isSensitive(p)) {
+      skippedSensitive.push(p);
+      continue;
+    }
+    const ftype = classifyFile(p);
+    if (!ftype) continue;
+    if (OFFICE_EXTENSIONS.has(extname(p).toLowerCase())) {
+      skippedSensitive.push(p + " [office conversion requires async - use pipeline]");
+      continue;
+    }
+    files[ftype].push(p);
+    if (ftype !== "video" /* VIDEO */) {
+      totalWords += countWords(p);
+    }
+  }
+  const totalFiles = Object.values(files).reduce((s, v) => s + v.length, 0);
+  const needsGraph = totalWords >= CORPUS_WARN_THRESHOLD;
+  let warning = null;
+  if (!needsGraph) {
+    warning = `Corpus is ~${totalWords.toLocaleString()} words - fits in a single context window. You may not need a graph.`;
+  } else if (totalWords >= CORPUS_UPPER_THRESHOLD || totalFiles >= FILE_COUNT_UPPER) {
+    warning = `Large corpus: ${totalFiles} files \xB7 ~${totalWords.toLocaleString()} words. Semantic extraction will be expensive (many Claude tokens). Consider running on a subfolder, or use --no-semantic to run AST-only.`;
+  }
+  return {
+    files,
+    total_files: totalFiles,
+    total_words: totalWords,
+    needs_graph: needsGraph,
+    warning,
+    skipped_sensitive: skippedSensitive,
+    graphifyignore_patterns: ignorePatterns.length
+  };
+}
+function loadManifest(manifestPath = MANIFEST_PATH) {
+  try {
+    return JSON.parse(readFileSync(manifestPath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function saveManifest(files, manifestPath = MANIFEST_PATH) {
+  const manifest = {};
+  for (const fileList of Object.values(files)) {
+    for (const f of fileList) {
+      try {
+        manifest[f] = statSync(f).mtimeMs;
+      } catch {
+      }
+    }
+  }
+  const dir = join(manifestPath, "..");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}
+function detectIncremental(root, manifestPath = MANIFEST_PATH) {
+  const full = detect(root);
+  const manifest = loadManifest(manifestPath);
+  if (Object.keys(manifest).length === 0) {
+    return {
+      ...full,
+      incremental: true,
+      new_files: full.files,
+      unchanged_files: Object.fromEntries(Object.keys(full.files).map((k) => [k, []])),
+      new_total: full.total_files
+    };
+  }
+  const newFiles = {};
+  const unchangedFiles = {};
+  for (const k of Object.keys(full.files)) {
+    newFiles[k] = [];
+    unchangedFiles[k] = [];
+  }
+  for (const [ftype, fileList] of Object.entries(full.files)) {
+    for (const f of fileList) {
+      const storedMtime = manifest[f];
+      let currentMtime = 0;
+      try {
+        currentMtime = statSync(f).mtimeMs;
+      } catch {
+      }
+      if (storedMtime === void 0 || currentMtime > storedMtime) {
+        newFiles[ftype].push(f);
+      } else {
+        unchangedFiles[ftype].push(f);
+      }
+    }
+  }
+  const currentFiles = new Set(Object.values(full.files).flat());
+  const deletedFiles = Object.keys(manifest).filter((f) => !currentFiles.has(f));
+  const newTotal = Object.values(newFiles).reduce((s, v) => s + v.length, 0);
+  return {
+    ...full,
+    incremental: true,
+    new_files: newFiles,
+    unchanged_files: unchangedFiles,
+    new_total: newTotal,
+    deleted_files: deletedFiles
+  };
+}
+
+// src/analyze.ts
+function nodeCommunityMap(communities) {
+  const communityMap = toNumericMap(communities);
+  const result = /* @__PURE__ */ new Map();
+  for (const [cid, nodes] of communityMap) {
+    for (const n of nodes) result.set(n, cid);
+  }
+  return result;
+}
+function isFileNode(G, nodeId) {
+  const attrs = G.getNodeAttributes(nodeId);
+  const label = attrs.label ?? "";
+  if (!label) return false;
+  const sourceFile = attrs.source_file ?? "";
+  if (sourceFile) {
+    const fileName = sourceFile.split("/").pop() ?? "";
+    if (label === fileName) return true;
+  }
+  if (label.startsWith(".") && label.endsWith("()")) return true;
+  if (label.endsWith("()") && G.degree(nodeId) <= 1) return true;
+  return false;
+}
+function isConceptNode(G, nodeId) {
+  const data = G.getNodeAttributes(nodeId);
+  const source = data.source_file ?? "";
+  if (!source) return true;
+  const lastPart = source.split("/").pop() ?? "";
+  if (!lastPart.includes(".")) return true;
+  return false;
+}
+function fileCategory(path) {
+  const ext = path.includes(".") ? `.${path.split(".").pop()?.toLowerCase() ?? ""}` : "";
+  if (CODE_EXTENSIONS.has(ext)) return "code";
+  if (PAPER_EXTENSIONS.has(ext)) return "paper";
+  if (IMAGE_EXTENSIONS.has(ext)) return "image";
+  if (DOC_EXTENSIONS.has(ext)) return "doc";
+  return "doc";
+}
+function topLevelDir(path) {
+  return path.includes("/") ? path.split("/")[0] : path;
+}
+function surpriseScore(G, u, v, data, nodeCommunity, uSource, vSource) {
+  let score = 0;
+  const reasons = [];
+  const conf = data.confidence ?? "EXTRACTED";
+  const confBonus = { AMBIGUOUS: 3, INFERRED: 2, EXTRACTED: 1 };
+  score += confBonus[conf] ?? 1;
+  if (conf === "AMBIGUOUS" || conf === "INFERRED") {
+    reasons.push(`${conf.toLowerCase()} connection - not explicitly stated in source`);
+  }
+  const catU = fileCategory(uSource);
+  const catV = fileCategory(vSource);
+  if (catU !== catV) {
+    score += 2;
+    reasons.push(`crosses file types (${catU} \u2194 ${catV})`);
+  }
+  if (topLevelDir(uSource) !== topLevelDir(vSource)) {
+    score += 2;
+    reasons.push("connects across different repos/directories");
+  }
+  const cidU = nodeCommunity.get(u);
+  const cidV = nodeCommunity.get(v);
+  if (cidU !== void 0 && cidV !== void 0 && cidU !== cidV) {
+    score += 1;
+    reasons.push("bridges separate communities");
+  }
+  if (data.relation === "semantically_similar_to") {
+    score = Math.floor(score * 1.5);
+    reasons.push("semantically similar concepts with no structural link");
   }
   const degU = G.degree(u);
   const degV = G.degree(v);
@@ -389,10 +795,10 @@ function suggestQuestions(G, communities, communityLabels, topN = 7) {
       const cid = nodeCommunity.get(nodeId);
       const commLabel = cid !== void 0 ? labelMap.get(cid) ?? `Community ${cid}` : "unknown";
       const neighborComms = /* @__PURE__ */ new Set();
-      G.forEachNeighbor(nodeId, (n) => {
+      for (const n of traversalNeighbors(G, nodeId)) {
         const nc = nodeCommunity.get(n);
         if (nc !== void 0 && nc !== cid) neighborComms.add(nc);
-      });
+      }
       if (neighborComms.size > 0) {
         const otherLabels = [...neighborComms].map((c) => labelMap.get(c) ?? `Community ${c}`);
         questions.push({
@@ -523,8 +929,7 @@ function graphDiff(GOld, GNew) {
 }
 
 // src/benchmark.ts
-import { readFileSync, existsSync } from "fs";
-import Graph from "graphology";
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
 var CHARS_PER_TOKEN = 4;
 function estimateTokens(text) {
   return Math.max(1, Math.floor(text.length / CHARS_PER_TOKEN));
@@ -546,7 +951,7 @@ function querySubgraphTokens(G, question, depth = 3) {
   for (let d = 0; d < depth; d++) {
     const nextFrontier = /* @__PURE__ */ new Set();
     for (const n of frontier) {
-      G.forEachNeighbor(n, (neighbor) => {
+      forEachTraversalNeighbor(G, n, (neighbor) => {
         if (!visited.has(neighbor)) {
           nextFrontier.add(neighbor);
           edgesSeen.push([n, neighbor]);
@@ -580,26 +985,12 @@ var SAMPLE_QUESTIONS = [
   "what are the core abstractions"
 ];
 function loadGraph(graphPath) {
-  const raw = JSON.parse(readFileSync(graphPath, "utf-8"));
-  const G = new Graph({ type: "undirected" });
-  for (const node of raw.nodes ?? []) {
-    const { id, ...attrs } = node;
-    G.mergeNode(id, attrs);
-  }
-  for (const link of raw.links ?? []) {
-    const { source, target, ...attrs } = link;
-    if (G.hasNode(source) && G.hasNode(target)) {
-      try {
-        G.mergeEdge(source, target, attrs);
-      } catch {
-      }
-    }
-  }
-  return G;
+  const raw = JSON.parse(readFileSync2(graphPath, "utf-8"));
+  return loadGraphFromData(raw);
 }
 function runBenchmark(graphPath = "graphify-out/graph.json", corpusWordsOrOptions, questions) {
   const options = typeof corpusWordsOrOptions === "number" ? { corpusWords: corpusWordsOrOptions, questions } : corpusWordsOrOptions ?? {};
-  if (!existsSync(graphPath)) {
+  if (!existsSync2(graphPath)) {
     return { error: `Graph file not found: ${graphPath}. Build the graph first.` };
   }
   const G = loadGraph(graphPath);
@@ -658,21 +1049,33 @@ graphify token reduction benchmark`);
 }
 
 // src/cache.ts
-import { createHash } from "crypto";
-import { readFileSync as readFileSync2, writeFileSync, mkdirSync, readdirSync, unlinkSync, renameSync, existsSync as existsSync2 } from "fs";
-import { join, resolve } from "path";
+import { createHash as createHash2 } from "crypto";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, readdirSync as readdirSync2, unlinkSync, renameSync, existsSync as existsSync3 } from "fs";
+import { extname as extname2, join as join2, resolve as resolve2 } from "path";
+function bodyContent(content) {
+  const text = content.toString("utf-8");
+  if (!text.startsWith("---")) {
+    return content;
+  }
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) {
+    return content;
+  }
+  return Buffer.from(text.slice(end + 4), "utf-8");
+}
 function fileHash(filePath) {
-  const content = readFileSync2(filePath);
-  const resolved = resolve(filePath);
-  const h = createHash("sha256");
+  const raw = readFileSync3(filePath);
+  const content = extname2(filePath).toLowerCase() === ".md" ? bodyContent(raw) : raw;
+  const resolved = resolve2(filePath);
+  const h = createHash2("sha256");
   h.update(content);
   h.update("\0");
   h.update(resolved);
   return h.digest("hex");
 }
 function cacheDir(root = ".") {
-  const d = join(root, "graphify-out", "cache");
-  mkdirSync(d, { recursive: true });
+  const d = join2(root, "graphify-out", "cache");
+  mkdirSync2(d, { recursive: true });
   return d;
 }
 function loadCached(filePath, root = ".") {
@@ -682,20 +1085,20 @@ function loadCached(filePath, root = ".") {
   } catch {
     return null;
   }
-  const entry = join(cacheDir(root), `${h}.json`);
-  if (!existsSync2(entry)) return null;
+  const entry = join2(cacheDir(root), `${h}.json`);
+  if (!existsSync3(entry)) return null;
   try {
-    return JSON.parse(readFileSync2(entry, "utf-8"));
+    return JSON.parse(readFileSync3(entry, "utf-8"));
   } catch {
     return null;
   }
 }
 function saveCached(filePath, result, root = ".") {
   const h = fileHash(filePath);
-  const entry = join(cacheDir(root), `${h}.json`);
+  const entry = join2(cacheDir(root), `${h}.json`);
   const tmp = entry + ".tmp";
   try {
-    writeFileSync(tmp, JSON.stringify(result));
+    writeFileSync2(tmp, JSON.stringify(result));
     renameSync(tmp, entry);
   } catch {
     try {
@@ -745,8 +1148,8 @@ function saveSemanticCache(nodes, edges, hyperedges = null, root = ".") {
   }
   let saved = 0;
   for (const [fpath, result] of byFile) {
-    const p = resolve(root, fpath);
-    if (existsSync2(p)) {
+    const p = resolve2(root, fpath);
+    if (existsSync3(p)) {
       saveCached(p, result, root);
       saved++;
     }
@@ -754,9 +1157,6 @@ function saveSemanticCache(nodes, edges, hyperedges = null, root = ".") {
   return saved;
 }
 
-// src/build.ts
-import Graph2 from "graphology";
-
 // src/validate.ts
 var VALID_FILE_TYPES = /* @__PURE__ */ new Set(["code", "document", "paper", "image", "rationale"]);
 var VALID_CONFIDENCES = /* @__PURE__ */ new Set(["EXTRACTED", "INFERRED", "AMBIGUOUS"]);
@@ -784,417 +1184,85 @@ function validateExtraction(data) {
           errors.push(
             `Node ${i} (id=${JSON.stringify(node.id ?? "?")}) missing required field '${field}'`
           );
-        }
-      }
-      if ("file_type" in node && !VALID_FILE_TYPES.has(node.file_type)) {
-        errors.push(
-          `Node ${i} (id=${JSON.stringify(node.id ?? "?")}) has invalid file_type '${node.file_type}' - must be one of ${JSON.stringify([...VALID_FILE_TYPES].sort())}`
-        );
-      }
-    }
-  }
-  if (!("edges" in d)) {
-    errors.push("Missing required key 'edges'");
-  } else if (!Array.isArray(d.edges)) {
-    errors.push("'edges' must be a list");
-  } else {
-    const nodeIds = /* @__PURE__ */ new Set();
-    if (Array.isArray(d.nodes)) {
-      for (const n of d.nodes) {
-        if (typeof n === "object" && n !== null && "id" in n) {
-          nodeIds.add(n.id);
-        }
-      }
-    }
-    for (let i = 0; i < d.edges.length; i++) {
-      const edge = d.edges[i];
-      if (typeof edge !== "object" || edge === null || Array.isArray(edge)) {
-        errors.push(`Edge ${i} must be an object`);
-        continue;
-      }
-      for (const field of REQUIRED_EDGE_FIELDS) {
-        if (!(field in edge)) {
-          errors.push(`Edge ${i} missing required field '${field}'`);
-        }
-      }
-      if ("confidence" in edge && !VALID_CONFIDENCES.has(edge.confidence)) {
-        errors.push(
-          `Edge ${i} has invalid confidence '${edge.confidence}' - must be one of ${JSON.stringify([...VALID_CONFIDENCES].sort())}`
-        );
-      }
-      if ("source" in edge && nodeIds.size > 0 && !nodeIds.has(edge.source)) {
-        errors.push(`Edge ${i} source '${edge.source}' does not match any node id`);
-      }
-      if ("target" in edge && nodeIds.size > 0 && !nodeIds.has(edge.target)) {
-        errors.push(`Edge ${i} target '${edge.target}' does not match any node id`);
-      }
-    }
-  }
-  return errors;
-}
-
-// src/build.ts
-function buildFromJson(extraction) {
-  const errors = validateExtraction(extraction);
-  const realErrors = errors.filter((e) => !e.includes("does not match any node id"));
-  if (realErrors.length > 0) {
-    console.error(
-      `[graphify] Extraction warning (${realErrors.length} issues): ${realErrors[0]}`
-    );
-  }
-  const G = new Graph2({ type: "undirected", multi: false });
-  for (const node of extraction.nodes ?? []) {
-    const { id, ...attrs } = node;
-    G.mergeNode(id, attrs);
-  }
-  const nodeSet = new Set(G.nodes());
-  for (const edge of extraction.edges ?? []) {
-    const { source, target, ...attrs } = edge;
-    if (!nodeSet.has(source) || !nodeSet.has(target)) continue;
-    attrs._src = source;
-    attrs._tgt = target;
-    try {
-      G.mergeEdge(source, target, attrs);
-    } catch {
-    }
-  }
-  const hyperedges = extraction.hyperedges ?? [];
-  if (hyperedges.length > 0) {
-    G.setAttribute("hyperedges", hyperedges);
-  }
-  return G;
-}
-
-// src/detect.ts
-import {
-  readdirSync as readdirSync2,
-  readFileSync as readFileSync3,
-  writeFileSync as writeFileSync2,
-  statSync,
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync2,
-  lstatSync
-} from "fs";
-import { join as join2, resolve as resolve2, extname, basename, relative, sep } from "path";
-import { createHash as createHash2 } from "crypto";
-var MANIFEST_PATH = "graphify-out/manifest.json";
-var CODE_EXTENSIONS2 = /* @__PURE__ */ new Set([
-  ".py",
-  ".ts",
-  ".js",
-  ".jsx",
-  ".tsx",
-  ".go",
-  ".rs",
-  ".java",
-  ".cpp",
-  ".cc",
-  ".cxx",
-  ".c",
-  ".h",
-  ".hpp",
-  ".rb",
-  ".swift",
-  ".kt",
-  ".kts",
-  ".cs",
-  ".scala",
-  ".php",
-  ".lua",
-  ".toc",
-  ".zig",
-  ".ps1",
-  ".ex",
-  ".exs",
-  ".m",
-  ".mm",
-  ".jl"
-]);
-var DOC_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".txt", ".rst"]);
-var PAPER_EXTENSIONS2 = /* @__PURE__ */ new Set([".pdf"]);
-var IMAGE_EXTENSIONS2 = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"]);
-var OFFICE_EXTENSIONS = /* @__PURE__ */ new Set([".docx", ".xlsx"]);
-var CORPUS_WARN_THRESHOLD = 5e4;
-var CORPUS_UPPER_THRESHOLD = 5e5;
-var FILE_COUNT_UPPER = 200;
-var SENSITIVE_PATTERNS = [
-  /(^|[\\/])\.(env|envrc)(\.|$)/i,
-  /\.(pem|key|p12|pfx|cert|crt|der|p8)$/i,
-  /(credential|secret|passwd|password|token|private_key)/i,
-  /(id_rsa|id_dsa|id_ecdsa|id_ed25519)(\.pub)?$/,
-  /(\.netrc|\.pgpass|\.htpasswd)$/i,
-  /(aws_credentials|gcloud_credentials|service.account)/i
-];
-var PAPER_SIGNALS = [
-  /\barxiv\b/i,
-  /\bdoi\s*:/i,
-  /\babstract\b/i,
-  /\bproceedings\b/i,
-  /\bjournal\b/i,
-  /\bpreprint\b/i,
-  /\\cite\{/,
-  /\[\d+\]/,
-  /\[\n\d+\n\]/,
-  /eq\.\s*\d+|equation\s+\d+/i,
-  /\d{4}\.\d{4,5}/,
-  /\bwe propose\b/i,
-  /\bliterature\b/i
-];
-var PAPER_SIGNAL_THRESHOLD = 3;
-function isSensitive(filePath) {
-  const name = basename(filePath);
-  return SENSITIVE_PATTERNS.some((p) => p.test(name) || p.test(filePath));
-}
-function looksLikePaper(filePath) {
-  try {
-    const text = readFileSync3(filePath, "utf-8").slice(0, 3e3);
-    const hits = PAPER_SIGNALS.filter((p) => p.test(text)).length;
-    return hits >= PAPER_SIGNAL_THRESHOLD;
-  } catch {
-    return false;
-  }
-}
-var ASSET_DIR_MARKERS = /* @__PURE__ */ new Set([".imageset", ".xcassets", ".appiconset", ".colorset", ".launchimage"]);
-function classifyFile(filePath) {
-  const ext = extname(filePath).toLowerCase();
-  if (CODE_EXTENSIONS2.has(ext)) return "code" /* CODE */;
-  if (PAPER_EXTENSIONS2.has(ext)) {
-    const parts = filePath.split(sep);
-    if (parts.some((p) => [...ASSET_DIR_MARKERS].some((m) => p.endsWith(m)))) return null;
-    return "paper" /* PAPER */;
-  }
-  if (IMAGE_EXTENSIONS2.has(ext)) return "image" /* IMAGE */;
-  if (DOC_EXTENSIONS.has(ext)) {
-    if (looksLikePaper(filePath)) return "paper" /* PAPER */;
-    return "document" /* DOCUMENT */;
-  }
-  if (OFFICE_EXTENSIONS.has(ext)) return "document" /* DOCUMENT */;
-  return null;
-}
-function countWords(filePath) {
-  try {
-    const text = readFileSync3(filePath, "utf-8");
-    return text.split(/\s+/).filter(Boolean).length;
-  } catch {
-    return 0;
-  }
-}
-var SKIP_DIRS = /* @__PURE__ */ new Set([
-  "venv",
-  ".venv",
-  "env",
-  ".env",
-  "node_modules",
-  "__pycache__",
-  ".git",
-  "dist",
-  "build",
-  "target",
-  "out",
-  "site-packages",
-  "lib64",
-  ".pytest_cache",
-  ".mypy_cache",
-  ".ruff_cache",
-  ".tox",
-  ".eggs"
-]);
-function isNoiseDir(part) {
-  if (SKIP_DIRS.has(part)) return true;
-  if (part.endsWith("_venv") || part.endsWith("_env")) return true;
-  if (part.endsWith(".egg-info")) return true;
-  return false;
-}
-function loadGraphifyignore(root) {
-  const ignoreFile = join2(root, ".graphifyignore");
-  if (!existsSync3(ignoreFile)) return [];
-  const patterns = [];
-  for (let line of readFileSync3(ignoreFile, "utf-8").split("\n")) {
-    line = line.trim();
-    if (line && !line.startsWith("#")) {
-      patterns.push(line);
-    }
-  }
-  return patterns;
-}
-function matchGlob(text, pattern) {
-  const regex = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
-  return new RegExp(`^${regex}$`).test(text);
-}
-function isIgnored(filePath, root, patterns) {
-  if (patterns.length === 0) return false;
-  let rel;
-  try {
-    rel = relative(root, filePath).replace(/\\/g, "/");
-  } catch {
-    return false;
-  }
-  const parts = rel.split("/");
-  for (const pattern of patterns) {
-    const p = pattern.replace(/^\/+|\/+$/g, "");
-    if (!p) continue;
-    if (matchGlob(rel, p)) return true;
-    if (matchGlob(basename(filePath), p)) return true;
-    for (let i = 0; i < parts.length; i++) {
-      if (matchGlob(parts[i], p)) return true;
-      if (matchGlob(parts.slice(0, i + 1).join("/"), p)) return true;
-    }
-  }
-  return false;
-}
-function walkDir(dir, root, ignorePatterns, followSymlinks, skipPrune) {
-  const result = [];
-  let entries;
-  try {
-    entries = readdirSync2(dir);
-  } catch {
-    return result;
-  }
-  for (const entry of entries) {
-    const full = join2(dir, entry);
-    let stat;
-    try {
-      stat = followSymlinks ? statSync(full) : lstatSync(full);
-    } catch {
-      continue;
-    }
-    if (stat.isDirectory()) {
-      if (!skipPrune) {
-        if (entry.startsWith(".")) continue;
-        if (isNoiseDir(entry)) continue;
-        if (isIgnored(full, root, ignorePatterns)) continue;
-      }
-      result.push(...walkDir(full, root, ignorePatterns, followSymlinks, skipPrune));
-    } else if (stat.isFile()) {
-      result.push(full);
-    }
-  }
-  return result;
-}
-function detect(root, options) {
-  const followSymlinks = options?.followSymlinks ?? false;
-  const rootResolved = resolve2(root);
-  const ignorePatterns = loadGraphifyignore(rootResolved);
-  const convertedDir = join2(rootResolved, "graphify-out", "converted");
-  const memoryDir = join2(rootResolved, "graphify-out", "memory");
-  const files = {
-    code: [],
-    document: [],
-    paper: [],
-    image: []
-  };
-  let totalWords = 0;
-  const skippedSensitive = [];
-  const allFiles = walkDir(rootResolved, rootResolved, ignorePatterns, followSymlinks, false);
-  if (existsSync3(memoryDir)) {
-    allFiles.push(...walkDir(memoryDir, rootResolved, ignorePatterns, followSymlinks, true));
-  }
-  const seen = /* @__PURE__ */ new Set();
-  for (const p of allFiles) {
-    if (seen.has(p)) continue;
-    seen.add(p);
-    const inMemory = existsSync3(memoryDir) && p.startsWith(memoryDir);
-    if (!inMemory) {
-      if (basename(p).startsWith(".")) continue;
-      if (p.startsWith(convertedDir)) continue;
-    }
-    if (isIgnored(p, rootResolved, ignorePatterns)) continue;
-    if (isSensitive(p)) {
-      skippedSensitive.push(p);
-      continue;
-    }
-    const ftype = classifyFile(p);
-    if (!ftype) continue;
-    if (OFFICE_EXTENSIONS.has(extname(p).toLowerCase())) {
-      skippedSensitive.push(p + " [office conversion requires async - use pipeline]");
-      continue;
-    }
-    files[ftype].push(p);
-    totalWords += countWords(p);
-  }
-  const totalFiles = Object.values(files).reduce((s, v) => s + v.length, 0);
-  const needsGraph = totalWords >= CORPUS_WARN_THRESHOLD;
-  let warning = null;
-  if (!needsGraph) {
-    warning = `Corpus is ~${totalWords.toLocaleString()} words - fits in a single context window. You may not need a graph.`;
-  } else if (totalWords >= CORPUS_UPPER_THRESHOLD || totalFiles >= FILE_COUNT_UPPER) {
-    warning = `Large corpus: ${totalFiles} files \xB7 ~${totalWords.toLocaleString()} words. Semantic extraction will be expensive (many Claude tokens). Consider running on a subfolder, or use --no-semantic to run AST-only.`;
-  }
-  return {
-    files,
-    total_files: totalFiles,
-    total_words: totalWords,
-    needs_graph: needsGraph,
-    warning,
-    skipped_sensitive: skippedSensitive,
-    graphifyignore_patterns: ignorePatterns.length
-  };
-}
-function loadManifest(manifestPath = MANIFEST_PATH) {
-  try {
-    return JSON.parse(readFileSync3(manifestPath, "utf-8"));
-  } catch {
-    return {};
+        }
+      }
+      if ("file_type" in node && !VALID_FILE_TYPES.has(node.file_type)) {
+        errors.push(
+          `Node ${i} (id=${JSON.stringify(node.id ?? "?")}) has invalid file_type '${node.file_type}' - must be one of ${JSON.stringify([...VALID_FILE_TYPES].sort())}`
+        );
+      }
+    }
   }
-}
-function saveManifest(files, manifestPath = MANIFEST_PATH) {
-  const manifest = {};
-  for (const fileList of Object.values(files)) {
-    for (const f of fileList) {
-      try {
-        manifest[f] = statSync(f).mtimeMs;
-      } catch {
+  if (!("edges" in d)) {
+    errors.push("Missing required key 'edges'");
+  } else if (!Array.isArray(d.edges)) {
+    errors.push("'edges' must be a list");
+  } else {
+    const nodeIds = /* @__PURE__ */ new Set();
+    if (Array.isArray(d.nodes)) {
+      for (const n of d.nodes) {
+        if (typeof n === "object" && n !== null && "id" in n) {
+          nodeIds.add(n.id);
+        }
+      }
+    }
+    for (let i = 0; i < d.edges.length; i++) {
+      const edge = d.edges[i];
+      if (typeof edge !== "object" || edge === null || Array.isArray(edge)) {
+        errors.push(`Edge ${i} must be an object`);
+        continue;
+      }
+      for (const field of REQUIRED_EDGE_FIELDS) {
+        if (!(field in edge)) {
+          errors.push(`Edge ${i} missing required field '${field}'`);
+        }
+      }
+      if ("confidence" in edge && !VALID_CONFIDENCES.has(edge.confidence)) {
+        errors.push(
+          `Edge ${i} has invalid confidence '${edge.confidence}' - must be one of ${JSON.stringify([...VALID_CONFIDENCES].sort())}`
+        );
+      }
+      if ("source" in edge && nodeIds.size > 0 && !nodeIds.has(edge.source)) {
+        errors.push(`Edge ${i} source '${edge.source}' does not match any node id`);
+      }
+      if ("target" in edge && nodeIds.size > 0 && !nodeIds.has(edge.target)) {
+        errors.push(`Edge ${i} target '${edge.target}' does not match any node id`);
       }
     }
   }
-  const dir = join2(manifestPath, "..");
-  mkdirSync2(dir, { recursive: true });
-  writeFileSync2(manifestPath, JSON.stringify(manifest, null, 2));
+  return errors;
 }
-function detectIncremental(root, manifestPath = MANIFEST_PATH) {
-  const full = detect(root);
-  const manifest = loadManifest(manifestPath);
-  if (Object.keys(manifest).length === 0) {
-    return {
-      ...full,
-      incremental: true,
-      new_files: full.files,
-      unchanged_files: Object.fromEntries(Object.keys(full.files).map((k) => [k, []])),
-      new_total: full.total_files
-    };
+
+// src/build.ts
+function buildFromJson(extraction, options) {
+  const errors = validateExtraction(extraction);
+  const realErrors = errors.filter((e) => !e.includes("does not match any node id"));
+  if (realErrors.length > 0) {
+    console.error(
+      `[graphify] Extraction warning (${realErrors.length} issues): ${realErrors[0]}`
+    );
   }
-  const newFiles = {};
-  const unchangedFiles = {};
-  for (const k of Object.keys(full.files)) {
-    newFiles[k] = [];
-    unchangedFiles[k] = [];
+  const G = createGraph(options?.directed === true);
+  for (const node of extraction.nodes ?? []) {
+    const { id, ...attrs } = node;
+    G.mergeNode(id, attrs);
   }
-  for (const [ftype, fileList] of Object.entries(full.files)) {
-    for (const f of fileList) {
-      const storedMtime = manifest[f];
-      let currentMtime = 0;
-      try {
-        currentMtime = statSync(f).mtimeMs;
-      } catch {
-      }
-      if (storedMtime === void 0 || currentMtime > storedMtime) {
-        newFiles[ftype].push(f);
-      } else {
-        unchangedFiles[ftype].push(f);
-      }
+  const nodeSet = new Set(G.nodes());
+  for (const edge of extraction.edges ?? []) {
+    const { source, target, ...attrs } = edge;
+    if (!nodeSet.has(source) || !nodeSet.has(target)) continue;
+    attrs._src = source;
+    attrs._tgt = target;
+    try {
+      G.mergeEdge(source, target, attrs);
+    } catch {
     }
   }
-  const currentFiles = new Set(Object.values(full.files).flat());
-  const deletedFiles = Object.keys(manifest).filter((f) => !currentFiles.has(f));
-  const newTotal = Object.values(newFiles).reduce((s, v) => s + v.length, 0);
-  return {
-    ...full,
-    incremental: true,
-    new_files: newFiles,
-    unchanged_files: unchangedFiles,
-    new_total: newTotal,
-    deleted_files: deletedFiles
-  };
+  const hyperedges = extraction.hyperedges ?? [];
+  if (hyperedges.length > 0) {
+    G.setAttribute("hyperedges", hyperedges);
+  }
+  return G;
 }
 
 // src/export.ts
@@ -1360,14 +1428,17 @@ function normalizeCommunityLabels(labelsOrOptions) {
   }
   return toNumericMap(labelsOrOptions.communityLabels);
 }
-function toJson(G, communities, outputPath) {
+function toJson(G, communities, outputPath, communityLabelsOrOptions) {
   const nodeComm = nodeCommunityMap2(communities);
+  const communityLabels = normalizeCommunityLabels(communityLabelsOrOptions);
   const nodes = [];
   G.forEachNode((nodeId, attrs) => {
+    const communityId = nodeComm.get(nodeId) ?? null;
     nodes.push({
       id: nodeId,
       ...attrs,
-      community: nodeComm.get(nodeId) ?? null
+      community: communityId,
+      community_name: communityId !== null ? sanitizeLabel(communityLabels?.get(communityId) ?? `Community ${communityId}`) : null
     });
   });
   const links = [];
@@ -1384,10 +1455,15 @@ function toJson(G, communities, outputPath) {
     links.push(link);
   });
   const hyperedges = G.getAttribute("hyperedges") ?? [];
+  const communityLabelsObject = communityLabels ? Object.fromEntries(
+    [...communityLabels.entries()].sort((a, b) => a[0] - b[0]).map(([cid, label]) => [String(cid), sanitizeLabel(label)])
+  ) : {};
   const output = {
-    directed: false,
+    directed: isDirectedGraph(G),
     multigraph: false,
-    graph: {},
+    graph: {
+      community_labels: communityLabelsObject
+    },
     nodes,
     links,
     hyperedges
@@ -1653,9 +1729,24 @@ function focusNode(nodeId) {
   showInfo(nodeId);
 }
 
+let hoveredNodeId = null;
+network.on('hoverNode', params => {
+  hoveredNodeId = params.node;
+  container.style.cursor = 'pointer';
+});
+network.on('blurNode', () => {
+  hoveredNodeId = null;
+  container.style.cursor = 'default';
+});
+container.addEventListener('click', () => {
+  if (hoveredNodeId !== null) {
+    showInfo(hoveredNodeId);
+    network.selectNodes([hoveredNodeId]);
+  }
+});
 network.on('click', params => {
   if (params.nodes.length > 0) showInfo(params.nodes[0]);
-  else document.getElementById('info-content').innerHTML = '<span class="empty">Click a node to inspect it</span>';
+  else if (hoveredNodeId === null) document.getElementById('info-content').innerHTML = '<span class="empty">Click a node to inspect it</span>';
 });
 
 const searchInput = document.getElementById('search');
@@ -1826,7 +1917,7 @@ function toGraphml(G, communities, outputPath) {
   lines.push('  <key id="community" for="node" attr.name="community" attr.type="int"/>');
   lines.push('  <key id="relation" for="edge" attr.name="relation" attr.type="string"/>');
   lines.push('  <key id="confidence" for="edge" attr.name="confidence" attr.type="string"/>');
-  lines.push('  <graph id="G" edgedefault="undirected">');
+  lines.push(`  <graph id="G" edgedefault="${isDirectedGraph(G) ? "directed" : "undirected"}">`);
   G.forEachNode((nodeId, data) => {
     lines.push(`    <node id="${xmlEsc(nodeId)}">`);
     lines.push(`      <data key="label">${xmlEsc(data.label ?? nodeId)}</data>`);
@@ -1921,7 +2012,7 @@ function toSvg(G, communities, outputPath, communityLabelsOrOptions, figsize = [
 
 // src/extract.ts
 import { readFileSync as readFileSync4, readdirSync as readdirSync3, lstatSync as lstatSync2, realpathSync, existsSync as existsSync5 } from "fs";
-import { resolve as resolve3, basename as basename2, extname as extname2, dirname, join as join3, sep as sep2 } from "path";
+import { resolve as resolve3, basename as basename2, extname as extname3, dirname as dirname2, join as join3, sep as sep2 } from "path";
 import { createRequire } from "module";
 import * as TreeSitter from "web-tree-sitter";
 var Parser2 = TreeSitter.Parser ?? TreeSitter.default;
@@ -2562,7 +2653,7 @@ async function _extractGeneric(filePath, config) {
     return { nodes: [], edges: [], error: String(e) };
   }
   const root = tree.rootNode;
-  const stem = basename2(filePath, extname2(filePath));
+  const stem = basename2(filePath, extname3(filePath));
   const strPath = filePath;
   const nodes = [];
   const edges = [];
@@ -2931,10 +3022,10 @@ async function _extractGeneric(filePath, config) {
               source: callerNid,
               target: tgtNid,
               relation: "calls",
-              confidence: "INFERRED",
+              confidence: "EXTRACTED",
               source_file: strPath,
               source_location: `L${line}`,
-              weight: 0.8
+              weight: 1
             });
           }
         }
@@ -2979,7 +3070,7 @@ async function _extractPythonRationale(filePath, result) {
   } catch {
     return;
   }
-  const stem = basename2(filePath, extname2(filePath));
+  const stem = basename2(filePath, extname3(filePath));
   const strPath = filePath;
   const { nodes, edges } = result;
   const seenIds = new Set(nodes.map((n) => n.id));
@@ -3075,7 +3166,7 @@ async function extractPython(filePath) {
   return result;
 }
 async function extractJs(filePath) {
-  const ext = extname2(filePath);
+  const ext = extname3(filePath);
   const config = ext === ".ts" || ext === ".tsx" ? _TS_CONFIG : _JS_CONFIG;
   return _extractGeneric(filePath, config);
 }
@@ -3126,7 +3217,7 @@ async function extractJulia(filePath) {
     return { nodes: [], edges: [], error: String(e) };
   }
   const root = tree.rootNode;
-  const stem = basename2(filePath, extname2(filePath));
+  const stem = basename2(filePath, extname3(filePath));
   const strPath = filePath;
   const nodes = [];
   const edges = [];
@@ -3322,8 +3413,8 @@ async function extractGo(filePath) {
     return { nodes: [], edges: [], error: String(e) };
   }
   const root = tree.rootNode;
-  const stem = basename2(filePath, extname2(filePath));
-  const pkgScope = dirname(filePath).split(sep2).pop() || stem;
+  const stem = basename2(filePath, extname3(filePath));
+  const pkgScope = dirname2(filePath).split(sep2).pop() || stem;
   const strPath = filePath;
   const nodes = [];
   const edges = [];
@@ -3466,10 +3557,10 @@ async function extractGo(filePath) {
               source: callerNid,
               target: tgtNid,
               relation: "calls",
-              confidence: "INFERRED",
+              confidence: "EXTRACTED",
               source_file: strPath,
               source_location: `L${line}`,
-              weight: 0.8
+              weight: 1
             });
           }
         }
@@ -3504,7 +3595,7 @@ async function extractRust(filePath) {
     return { nodes: [], edges: [], error: String(e) };
   }
   const root = tree.rootNode;
-  const stem = basename2(filePath, extname2(filePath));
+  const stem = basename2(filePath, extname3(filePath));
   const strPath = filePath;
   const nodes = [];
   const edges = [];
@@ -3621,10 +3712,10 @@ async function extractRust(filePath) {
               source: callerNid,
               target: tgtNid,
               relation: "calls",
-              confidence: "INFERRED",
+              confidence: "EXTRACTED",
               source_file: strPath,
               source_location: `L${line}`,
-              weight: 0.8
+              weight: 1
             });
           }
         }
@@ -3659,7 +3750,7 @@ async function extractZig(filePath) {
     return { nodes: [], edges: [], error: String(e) };
   }
   const root = tree.rootNode;
-  const stem = basename2(filePath, extname2(filePath));
+  const stem = basename2(filePath, extname3(filePath));
   const strPath = filePath;
   const nodes = [];
   const edges = [];
@@ -3783,7 +3874,7 @@ async function extractZig(filePath) {
           const pair = `${callerNid}|${tgtNid}`;
           if (!seenCallPairs.has(pair)) {
             seenCallPairs.add(pair);
-            addEdge(callerNid, tgtNid, "calls", node.startPosition.row + 1, "INFERRED", 0.8);
+            addEdge(callerNid, tgtNid, "calls", node.startPosition.row + 1, "EXTRACTED", 1);
           }
         }
       }
@@ -3817,7 +3908,7 @@ async function extractPowershell(filePath) {
     return { nodes: [], edges: [], error: String(e) };
   }
   const root = tree.rootNode;
-  const stem = basename2(filePath, extname2(filePath));
+  const stem = basename2(filePath, extname3(filePath));
   const strPath = filePath;
   const nodes = [];
   const edges = [];
@@ -3966,7 +4057,7 @@ async function extractPowershell(filePath) {
             const pair = `${callerNid}|${tgtNid}`;
             if (!seenCallPairs.has(pair)) {
               seenCallPairs.add(pair);
-              addEdge(callerNid, tgtNid, "calls", node.startPosition.row + 1, "INFERRED", 0.8);
+              addEdge(callerNid, tgtNid, "calls", node.startPosition.row + 1, "EXTRACTED", 1);
             }
           }
         }
@@ -4001,7 +4092,7 @@ async function extractObjc(filePath) {
     return { nodes: [], edges: [], error: String(e) };
   }
   const root = tree.rootNode;
-  const stem = basename2(filePath, extname2(filePath));
+  const stem = basename2(filePath, extname3(filePath));
   const strPath = filePath;
   const nodes = [];
   const edges = [];
@@ -4172,7 +4263,7 @@ async function extractObjc(filePath) {
                 const pair = `${callerNid}|${candidate}`;
                 if (!seenCalls.has(pair) && callerNid !== candidate) {
                   seenCalls.add(pair);
-                  addEdge(callerNid, candidate, "calls", bodyNode.startPosition.row + 1, "INFERRED", 0.8);
+                  addEdge(callerNid, candidate, "calls", bodyNode.startPosition.row + 1, "EXTRACTED", 1);
                 }
               }
             }
@@ -4204,7 +4295,7 @@ async function extractElixir(filePath) {
     return { nodes: [], edges: [], error: String(e) };
   }
   const root = tree.rootNode;
-  const stem = basename2(filePath, extname2(filePath));
+  const stem = basename2(filePath, extname3(filePath));
   const strPath = filePath;
   const nodes = [];
   const edges = [];
@@ -4363,7 +4454,7 @@ async function extractElixir(filePath) {
         const pair = `${callerNid}|${tgtNid}`;
         if (!seenCallPairs.has(pair)) {
           seenCallPairs.add(pair);
-          addEdge(callerNid, tgtNid, "calls", node.startPosition.row + 1, "INFERRED", 0.8);
+          addEdge(callerNid, tgtNid, "calls", node.startPosition.row + 1, "EXTRACTED", 1);
         }
       }
     }
@@ -4390,7 +4481,7 @@ async function _resolveCrossFileImports(perFile, paths) {
     for (const node of fileResult.nodes ?? []) {
       const src = node.source_file ?? "";
       if (!src) continue;
-      const fileStem = basename2(src, extname2(src));
+      const fileStem = basename2(src, extname3(src));
       const label = node.label ?? "";
       const nid = node.id ?? "";
       if (label && !label.endsWith(")") && !label.endsWith(".py") && !label.startsWith("_")) {
@@ -4402,7 +4493,7 @@ async function _resolveCrossFileImports(perFile, paths) {
   const newEdges = [];
   const stemToPath = /* @__PURE__ */ new Map();
   for (const p of paths) {
-    stemToPath.set(basename2(p, extname2(p)), p);
+    stemToPath.set(basename2(p, extname3(p)), p);
   }
   for (let idx = 0; idx < perFile.length; idx++) {
     let walkImports = function(node) {
@@ -4466,7 +4557,7 @@ async function _resolveCrossFileImports(perFile, paths) {
     };
     const fileResult = perFile[idx];
     const filePath = paths[idx];
-    const fileStem = basename2(filePath, extname2(filePath));
+    const fileStem = basename2(filePath, extname3(filePath));
     const strPath = filePath;
     const localClasses = fileResult.nodes.filter(
       (n) => n.source_file === strPath && !n.label.endsWith(")") && !n.label.endsWith(".py") && n.id !== _makeId(fileStem)
@@ -4524,7 +4615,7 @@ async function extractWithDiagnostics(paths) {
     if (paths.length === 0) {
       root = ".";
     } else if (paths.length === 1) {
-      root = dirname(paths[0]);
+      root = dirname2(paths[0]);
     } else {
       const parts = paths.map((p) => p.split(sep2));
       const minLen = Math.min(...parts.map((p) => p.length));
@@ -4547,7 +4638,7 @@ async function extractWithDiagnostics(paths) {
 `);
     }
     const filePath = paths[i];
-    const ext = extname2(filePath);
+    const ext = extname3(filePath);
     const extractor = _DISPATCH[ext];
     if (!extractor) continue;
     const cached = loadCached(filePath, root);
@@ -4573,9 +4664,9 @@ async function extractWithDiagnostics(paths) {
     allNodes.push(...result.nodes ?? []);
     allEdges.push(...result.edges ?? []);
   }
-  const pyPaths = paths.filter((p) => extname2(p) === ".py");
+  const pyPaths = paths.filter((p) => extname3(p) === ".py");
   if (pyPaths.length > 0) {
-    const pyResults = perFile.filter((_r, i) => extname2(paths[i]) === ".py");
+    const pyResults = perFile.filter((_r, i) => extname3(paths[i]) === ".py");
     try {
       const crossFileEdges = await _resolveCrossFileImports(pyResults, pyPaths);
       allEdges.push(...crossFileEdges);
@@ -4594,8 +4685,404 @@ async function extractWithDiagnostics(paths) {
 }
 
 // src/ingest.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
-import { resolve as pathResolve2, basename as basename3, extname as extname3 } from "path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "fs";
+import { resolve as pathResolve2, basename as basename4, extname as extname5 } from "path";
+
+// src/transcribe.ts
+import * as childProcess from "child_process";
+import { createHash as createHash3 } from "crypto";
+import {
+  cpSync,
+  createWriteStream,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync3,
+  mkdtempSync,
+  readdirSync as readdirSync4,
+  renameSync as renameSync2,
+  rmSync,
+  writeFileSync as writeFileSync4
+} from "fs";
+import { homedir, platform, tmpdir } from "os";
+import { basename as basename3, dirname as dirname3, extname as extname4, join as join4, resolve as resolve5 } from "path";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+var URL_PREFIXES = ["http://", "https://", "www."];
+var CACHED_AUDIO_EXTENSIONS = [".m4a", ".opus", ".mp3", ".ogg", ".wav", ".webm"];
+var DEFAULT_MODEL = "base";
+var TRANSCRIPTS_DIR = "graphify-out/transcripts";
+var FALLBACK_PROMPT = "Use proper punctuation and paragraph breaks.";
+var SHERPA_RELEASE_BASE = "https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models";
+var AUDIO_SAMPLE_RATE = 16e3;
+var SUPPORTED_MODELS = /* @__PURE__ */ new Set([
+  "tiny",
+  "tiny.en",
+  "base",
+  "base.en",
+  "small",
+  "small.en",
+  "medium",
+  "medium.en",
+  "large-v1",
+  "large-v2",
+  "large-v3",
+  "turbo",
+  "distil-small.en",
+  "distil-medium.en",
+  "distil-large-v2",
+  "distil-large-v3",
+  "distil-large-v3.5"
+]);
+var MODEL_ALIASES = {
+  large: "large-v3"
+};
+var recognizerCache = /* @__PURE__ */ new Map();
+var sherpaModulePromise = null;
+function runCommand(command, args, options) {
+  const result = childProcess.spawnSync(command, args, {
+    encoding: "utf-8",
+    ...options
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.trim() || result.stdout?.trim() || `${command} failed`);
+  }
+  return result;
+}
+function defaultWhisperCacheDir() {
+  if (process.env.GRAPHIFY_WHISPER_CACHE_DIR) {
+    return resolve5(process.env.GRAPHIFY_WHISPER_CACHE_DIR);
+  }
+  if (platform() === "win32") {
+    return join4(
+      process.env.LOCALAPPDATA ?? join4(homedir(), "AppData", "Local"),
+      "graphify",
+      "whisper"
+    );
+  }
+  return join4(process.env.XDG_CACHE_HOME ?? join4(homedir(), ".cache"), "graphify", "whisper");
+}
+function ffmpegBinary() {
+  return process.env.GRAPHIFY_FFMPEG_BIN ?? "ffmpeg";
+}
+function tarBinary() {
+  return process.env.GRAPHIFY_TAR_BIN ?? "tar";
+}
+function resolveRequestedModel(modelName) {
+  const requested = modelName ?? process.env.GRAPHIFY_WHISPER_MODEL ?? DEFAULT_MODEL;
+  const resolved = MODEL_ALIASES[requested] ?? requested;
+  if (!SUPPORTED_MODELS.has(resolved)) {
+    throw new Error(
+      `Unsupported GRAPHIFY_WHISPER_MODEL "${requested}". Supported local TS models: ${[...SUPPORTED_MODELS].sort().join(", ")}`
+    );
+  }
+  return { requested, resolved };
+}
+function walkFiles(dir) {
+  if (!existsSync6(dir)) return [];
+  const files = [];
+  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
+    const fullPath = join4(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkFiles(fullPath));
+    } else {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function findArtifactsIn(dir) {
+  const files = walkFiles(dir);
+  const encoderPath = files.find((path) => path.endsWith("-encoder.int8.onnx")) ?? files.find((path) => path.endsWith("-encoder.onnx"));
+  const decoderPath = files.find((path) => path.endsWith("-decoder.int8.onnx")) ?? files.find((path) => path.endsWith("-decoder.onnx"));
+  const tokensPath = files.find((path) => path.endsWith("-tokens.txt"));
+  if (!encoderPath || !decoderPath || !tokensPath) {
+    return null;
+  }
+  return {
+    modelDir: dir,
+    encoderPath,
+    decoderPath,
+    tokensPath
+  };
+}
+function normalizeModelError(detail) {
+  if (detail.includes("404")) {
+    return `${detail}. The local sherpa-onnx release asset was not found for this Whisper model name.`;
+  }
+  return detail;
+}
+async function writeResponseToFile(response, destination) {
+  if (!response.ok || !response.body) {
+    throw new Error(`HTTP ${response.status} while downloading ${response.url}`);
+  }
+  await pipeline(Readable.fromWeb(response.body), createWriteStream(destination));
+}
+async function ensureWhisperArtifacts(modelName) {
+  const { requested, resolved } = resolveRequestedModel(modelName);
+  const cacheRoot = defaultWhisperCacheDir();
+  mkdirSync3(cacheRoot, { recursive: true });
+  const modelDir = join4(cacheRoot, `sherpa-onnx-whisper-${resolved}`);
+  const cached = findArtifactsIn(modelDir);
+  if (cached) {
+    return { requestedModel: requested, resolvedModel: resolved, ...cached };
+  }
+  const tempDir = mkdtempSync(join4(tmpdir(), "graphify-whisper-model-"));
+  const extractDir = join4(tempDir, "extract");
+  const archiveName = `sherpa-onnx-whisper-${resolved}.tar.bz2`;
+  const archivePath = join4(tempDir, archiveName);
+  mkdirSync3(extractDir, { recursive: true });
+  try {
+    const url = `${SHERPA_RELEASE_BASE}/${archiveName}`;
+    console.log(`  downloading whisper model: ${resolved}`);
+    const response = await fetch(url);
+    await writeResponseToFile(response, archivePath);
+    runCommand(tarBinary(), ["-xjf", archivePath, "-C", extractDir]);
+    const extractedRoot = walkFiles(extractDir).map((path) => dirname3(path)).find((path) => findArtifactsIn(path) !== null);
+    const sourceDir = extractedRoot ?? readdirSync4(extractDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join4(extractDir, entry.name)).find((path) => findArtifactsIn(path) !== null);
+    if (!sourceDir) {
+      throw new Error(`Downloaded archive for ${resolved} but could not locate Whisper model files`);
+    }
+    if (existsSync6(modelDir)) {
+      rmSync(modelDir, { recursive: true, force: true });
+    }
+    try {
+      renameSync2(sourceDir, modelDir);
+    } catch {
+      cpSync(sourceDir, modelDir, { recursive: true });
+    }
+    const artifacts = findArtifactsIn(modelDir);
+    if (!artifacts) {
+      throw new Error(`Model cache for ${resolved} is incomplete after extraction`);
+    }
+    return { requestedModel: requested, resolvedModel: resolved, ...artifacts };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(normalizeModelError(detail));
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+async function loadSherpaModule() {
+  if (!sherpaModulePromise) {
+    sherpaModulePromise = import("sherpa-onnx-node").then((imported) => Reflect.has(imported, "default") ? Reflect.get(imported, "default") : imported).catch((error) => {
+      sherpaModulePromise = null;
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Video transcription requires the optional dependency sherpa-onnx-node. Install it locally, then retry. ${detail}`
+      );
+    });
+  }
+  return sherpaModulePromise;
+}
+async function getRecognizer(modelName, sherpa) {
+  const artifacts = await ensureWhisperArtifacts(modelName);
+  const cacheKey = artifacts.modelDir;
+  const existing = recognizerCache.get(cacheKey);
+  if (existing) {
+    return { recognizer: await existing, artifacts };
+  }
+  const createRecognizer = (async () => {
+    const runtime = sherpa ?? await loadSherpaModule();
+    return runtime.OfflineRecognizer.createAsync({
+      featConfig: {
+        sampleRate: AUDIO_SAMPLE_RATE,
+        featureDim: 80
+      },
+      modelConfig: {
+        whisper: {
+          encoder: artifacts.encoderPath,
+          decoder: artifacts.decoderPath,
+          task: "transcribe"
+        },
+        tokens: artifacts.tokensPath,
+        numThreads: 1,
+        provider: "cpu",
+        debug: 0
+      }
+    });
+  })();
+  recognizerCache.set(
+    cacheKey,
+    createRecognizer.catch((error) => {
+      recognizerCache.delete(cacheKey);
+      throw error;
+    })
+  );
+  return { recognizer: await recognizerCache.get(cacheKey), artifacts };
+}
+function normalizeToWave(audioPath, workingDir) {
+  const wavPath = join4(workingDir, `${basename3(audioPath, extname4(audioPath))}.wav`);
+  try {
+    runCommand(ffmpegBinary(), [
+      "-y",
+      "-i",
+      audioPath,
+      "-vn",
+      "-ac",
+      "1",
+      "-ar",
+      String(AUDIO_SAMPLE_RATE),
+      "-c:a",
+      "pcm_s16le",
+      wavPath
+    ]);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Video transcription requires ffmpeg in PATH. Install ffmpeg locally, then retry. ${detail}`
+    );
+  }
+  return wavPath;
+}
+function extractTranscriptText(result) {
+  return String(result.text ?? "").trim();
+}
+function isUrl(pathLike) {
+  return URL_PREFIXES.some((prefix) => pathLike.startsWith(prefix));
+}
+function downloadAudio(url, outputDir) {
+  mkdirSync3(outputDir, { recursive: true });
+  const urlHash = createHash3("sha1").update(url).digest("hex").slice(0, 12);
+  for (const ext of CACHED_AUDIO_EXTENSIONS) {
+    const candidate = join4(outputDir, `yt_${urlHash}${ext}`);
+    if (existsSync6(candidate)) {
+      console.log(`  cached audio: ${basename3(candidate)}`);
+      return candidate;
+    }
+  }
+  const outTemplate = join4(outputDir, `yt_${urlHash}.%(ext)s`);
+  try {
+    console.log(`  downloading audio: ${url.slice(0, 80)} ...`);
+    runCommand("yt-dlp", [
+      "-f",
+      "bestaudio[ext=m4a]/bestaudio/best",
+      "-o",
+      outTemplate,
+      "--quiet",
+      "--no-warnings",
+      "--no-playlist",
+      url
+    ]);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `YouTube/URL download requires yt-dlp. Install yt-dlp to enable video ingestion. ${detail}`
+    );
+  }
+  for (const entry of readdirSync4(outputDir)) {
+    if (entry.startsWith(`yt_${urlHash}.`)) {
+      return join4(outputDir, entry);
+    }
+  }
+  throw new Error(`yt-dlp finished without producing an audio file for ${url}`);
+}
+function buildWhisperPrompt(godNodes2) {
+  const override = process.env.GRAPHIFY_WHISPER_PROMPT;
+  if (override) return override;
+  const labels = godNodes2.map((node) => node.label ?? "").filter((label) => Boolean(label)).slice(0, 5);
+  if (labels.length === 0) {
+    return FALLBACK_PROMPT;
+  }
+  return `Technical discussion about ${labels.join(", ")}. ${FALLBACK_PROMPT}`;
+}
+async function transcribe(videoPath, outputDir = TRANSCRIPTS_DIR, initialPrompt, force = false) {
+  const outDir = resolve5(outputDir);
+  mkdirSync3(outDir, { recursive: true });
+  const audioPath = isUrl(videoPath) ? downloadAudio(videoPath, join4(outDir, "downloads")) : resolve5(videoPath);
+  const transcriptPath = join4(outDir, `${basename3(audioPath, extname4(audioPath))}.txt`);
+  if (existsSync6(transcriptPath) && !force) {
+    return transcriptPath;
+  }
+  const prompt = initialPrompt ?? process.env.GRAPHIFY_WHISPER_PROMPT ?? FALLBACK_PROMPT;
+  const requestedModel = process.env.GRAPHIFY_WHISPER_MODEL ?? DEFAULT_MODEL;
+  const tempDir = mkdtempSync(join4(tmpdir(), "graphify-transcribe-"));
+  try {
+    console.log(`  transcribing ${basename3(audioPath)} (model=${requestedModel}) ...`);
+    const wavPath = normalizeToWave(audioPath, tempDir);
+    const sherpa = await loadSherpaModule();
+    const { recognizer, artifacts } = await getRecognizer(requestedModel, sherpa);
+    const wave = sherpa.readWave(wavPath);
+    const stream = recognizer.createStream();
+    if (prompt && typeof stream.setOption === "function") {
+      try {
+        stream.setOption("prompt", prompt);
+      } catch {
+      }
+    }
+    stream.acceptWaveform({ samples: wave.samples, sampleRate: wave.sampleRate });
+    const result = await recognizer.decodeAsync(stream);
+    const transcript = extractTranscriptText(result);
+    writeFileSync4(transcriptPath, transcript, "utf-8");
+    if (artifacts.requestedModel !== artifacts.resolvedModel) {
+      console.log(`  model alias: ${artifacts.requestedModel} -> ${artifacts.resolvedModel}`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Unsupported GRAPHIFY_WHISPER_MODEL")) {
+      throw error;
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Video transcription requires the local TypeScript toolchain: sherpa-onnx-node + ffmpeg. Retry after installing them. ${detail}`
+    );
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+  return transcriptPath;
+}
+async function transcribeAll(videoFiles, outputDir, initialPrompt, force = false) {
+  if (videoFiles.length === 0) {
+    return [];
+  }
+  const transcriptPaths = [];
+  for (const videoFile of videoFiles) {
+    try {
+      transcriptPaths.push(await transcribe(videoFile, outputDir, initialPrompt, force));
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      console.log(`  warning: could not transcribe ${videoFile}: ${detail}`);
+    }
+  }
+  return transcriptPaths;
+}
+function cloneDetection(detection) {
+  return JSON.parse(JSON.stringify(detection));
+}
+async function augmentDetectionWithTranscripts(detection, options) {
+  const nextDetection = cloneDetection(detection);
+  const source = options?.incremental && nextDetection.new_files ? nextDetection.new_files : nextDetection.files;
+  const videoFiles = [...source.video ?? []];
+  const prompt = options?.initialPrompt ?? buildWhisperPrompt(options?.godNodes ?? []);
+  if (videoFiles.length === 0) {
+    return { detection: nextDetection, transcriptPaths: [], prompt };
+  }
+  const previousModel = process.env.GRAPHIFY_WHISPER_MODEL;
+  if (options?.whisperModel) {
+    process.env.GRAPHIFY_WHISPER_MODEL = options.whisperModel;
+  }
+  try {
+    const transcriptPaths = await transcribeAll(
+      videoFiles,
+      options?.outputDir,
+      prompt,
+      options?.incremental === true
+    );
+    const existingDocuments = source.document ?? [];
+    source.document = [...existingDocuments, ...transcriptPaths];
+    return { detection: nextDetection, transcriptPaths, prompt };
+  } finally {
+    if (options?.whisperModel) {
+      if (previousModel === void 0) {
+        delete process.env.GRAPHIFY_WHISPER_MODEL;
+      } else {
+        process.env.GRAPHIFY_WHISPER_MODEL = previousModel;
+      }
+    }
+  }
+}
+
+// src/ingest.ts
 function yamlStr(s) {
   return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, " ").replace(/\r/g, " ");
 }
@@ -4763,7 +5250,7 @@ async function downloadBinary(url, suffix, targetDir) {
   const filename = safeFilename(url, suffix);
   const outPath = pathResolve2(targetDir, filename);
   const data = await safeFetch(url);
-  writeFileSync4(outPath, data);
+  writeFileSync5(outPath, data);
   return outPath;
 }
 function normalizeIngestOptions(authorOrOptions, contributor) {
@@ -4779,7 +5266,7 @@ function normalizeIngestOptions(authorOrOptions, contributor) {
   };
 }
 async function ingest(url, targetDir, authorOrOptions = null, contributor = null) {
-  mkdirSync3(targetDir, { recursive: true });
+  mkdirSync4(targetDir, { recursive: true });
   const urlType = detectUrlType(url);
   const { author, contributor: normalizedContributor } = normalizeIngestOptions(
     authorOrOptions,
@@ -4790,7 +5277,7 @@ async function ingest(url, targetDir, authorOrOptions = null, contributor = null
   let filename;
   if (urlType === "pdf") {
     const out = await downloadBinary(url, ".pdf", targetDir);
-    console.log(`Downloaded PDF: ${basename3(out)}`);
+    console.log(`Downloaded PDF: ${basename4(out)}`);
     return out;
   }
   if (urlType === "image") {
@@ -4800,9 +5287,14 @@ async function ingest(url, targetDir, authorOrOptions = null, contributor = null
     } catch {
       throw new Error(`Invalid URL: ${url}`);
     }
-    const suffix = extname3(parsed.pathname) || ".jpg";
+    const suffix = extname5(parsed.pathname) || ".jpg";
     const out = await downloadBinary(url, suffix, targetDir);
-    console.log(`Downloaded image: ${basename3(out)}`);
+    console.log(`Downloaded image: ${basename4(out)}`);
+    return out;
+  }
+  if (urlType === "youtube") {
+    const out = downloadAudio(url, targetDir);
+    console.log(`Downloaded audio: ${basename4(out)}`);
     return out;
   }
   if (urlType === "tweet") {
@@ -4814,13 +5306,13 @@ async function ingest(url, targetDir, authorOrOptions = null, contributor = null
   }
   let outPath = pathResolve2(targetDir, filename);
   let counter = 1;
-  while (existsSync6(outPath)) {
+  while (existsSync7(outPath)) {
     const stem = filename.replace(/\.md$/, "");
     outPath = pathResolve2(targetDir, `${stem}_${counter}.md`);
     counter++;
   }
-  writeFileSync4(outPath, content, "utf-8");
-  console.log(`Saved ${urlType}: ${basename3(outPath)}`);
+  writeFileSync5(outPath, content, "utf-8");
+  console.log(`Saved ${urlType}: ${basename4(outPath)}`);
   return outPath;
 }
 function saveQueryResult(questionOrOptions, answer, memoryDir, queryType = "query", sourceNodes = null) {
@@ -4840,7 +5332,7 @@ function saveQueryResult(questionOrOptions, answer, memoryDir, queryType = "quer
   if (!payload.question) throw new Error("saveQueryResult requires a question");
   if (!payload.memoryDir) throw new Error("saveQueryResult requires a memoryDir");
   const effectiveAnswer = payload.answer ?? "";
-  mkdirSync3(payload.memoryDir, { recursive: true });
+  mkdirSync4(payload.memoryDir, { recursive: true });
   const now = /* @__PURE__ */ new Date();
   const slug = payload.question.toLowerCase().replace(/[^\w]/g, "_").slice(0, 50).replace(/_+$/, "");
   const ts = now.toISOString().replace(/[-:]/g, "").replace("T", "_").slice(0, 15);
@@ -4873,10 +5365,10 @@ function saveQueryResult(questionOrOptions, answer, memoryDir, queryType = "quer
   }
   const content = [...frontmatterLines, ...bodyLines].join("\n");
   const outPath = pathResolve2(payload.memoryDir, filename);
-  writeFileSync4(outPath, content, "utf-8");
+  writeFileSync5(outPath, content, "utf-8");
   return outPath;
 }
-var isDirectExecution = typeof process !== "undefined" && typeof process.argv[1] === "string" && /^ingest\.(?:js|mjs|cjs|ts)$/.test(basename3(process.argv[1]));
+var isDirectExecution = typeof process !== "undefined" && typeof process.argv[1] === "string" && /^ingest\.(?:js|mjs|cjs|ts)$/.test(basename4(process.argv[1]));
 if (isDirectExecution) {
   const url = process.argv[2];
   const targetDir = process.argv[3] ?? "./raw";
@@ -5047,18 +5539,18 @@ function generate(G, communities, cohesionScores, communityLabels, godNodeList,
 
 // src/skill-runtime.ts
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname2(__filename);
+var __dirname = dirname4(__filename);
 function readJson(path) {
-  return JSON.parse(readFileSync5(resolve5(path), "utf-8"));
+  return JSON.parse(readFileSync5(resolve7(path), "utf-8"));
 }
 function writeJson(path, value) {
-  const resolved = resolve5(path);
-  mkdirSync4(dirname2(resolved), { recursive: true });
-  writeFileSync5(resolved, JSON.stringify(value, null, 2), "utf-8");
+  const resolved = resolve7(path);
+  mkdirSync5(dirname4(resolved), { recursive: true });
+  writeFileSync6(resolved, JSON.stringify(value, null, 2), "utf-8");
 }
 function getVersion() {
   try {
-    const pkg = JSON.parse(readFileSync5(join4(__dirname, "..", "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync5(join5(__dirname, "..", "package.json"), "utf-8"));
     return pkg.version ?? "unknown";
   } catch {
     return "unknown";
@@ -5094,23 +5586,10 @@ function ensureExtractionShape(value) {
 }
 function loadGraph2(graphPath) {
   const raw = readJson(graphPath);
-  const G = new Graph3({ type: "undirected" });
-  for (const node of raw.nodes ?? []) {
-    const { id, ...attrs } = node;
-    G.mergeNode(id, attrs);
-  }
-  for (const link of raw.links ?? []) {
-    const { source, target, ...attrs } = link;
-    if (!G.hasNode(source) || !G.hasNode(target)) continue;
-    try {
-      G.mergeEdge(source, target, attrs);
-    } catch {
-    }
-  }
-  if (raw.hyperedges && raw.hyperedges.length > 0) {
-    G.setAttribute("hyperedges", raw.hyperedges);
-  }
-  return G;
+  return loadGraphFromData(raw);
+}
+function shouldBuildDirected(opts, existingGraph) {
+  return opts.directed === true || (existingGraph ? isDirectedGraph(existingGraph) : false);
 }
 function mergeHyperedges(existing = [], incoming = []) {
   const seen = /* @__PURE__ */ new Set();
@@ -5182,11 +5661,11 @@ function analyzeGraph(G, detection, root, tokenCost, labelsOverride) {
 }
 function placeholderDetection(root = ".") {
   return {
-    files: { code: [], document: [], paper: [], image: [] },
+    files: { code: [], document: [], paper: [], image: [], video: [] },
     total_files: 0,
     total_words: 0,
     needs_graph: true,
-    warning: `Reused existing graph at ${resolve5(root)} without re-running corpus detection.`,
+    warning: `Reused existing graph at ${resolve7(root)} without re-running corpus detection.`,
     skipped_sensitive: [],
     graphifyignore_patterns: 0
   };
@@ -5234,8 +5713,8 @@ function updateCostFile(extractionInput, detection, outPath) {
     total_input_tokens: 0,
     total_output_tokens: 0
   };
-  const resolved = resolve5(outPath);
-  if (existsSync7(resolved)) {
+  const resolved = resolve7(outPath);
+  if (existsSync8(resolved)) {
     cost = readJson(resolved);
   }
   const input = extraction.input_tokens ?? 0;
@@ -5270,8 +5749,8 @@ function runtimeInfo() {
     version: getVersion(),
     node: process.execPath,
     script: __filename,
-    module: join4(__dirname, "index.js"),
-    cli: join4(__dirname, "cli.js")
+    module: join5(__dirname, "index.js"),
+    cli: join5(__dirname, "cli.js")
   };
 }
 async function main() {
@@ -5281,23 +5760,37 @@ async function main() {
     console.log(JSON.stringify(runtimeInfo(), null, 2));
   });
   program.command("detect").argument("<inputPath>").option("--out <path>").action((inputPath, opts) => {
-    const result = detect(resolve5(inputPath));
+    const result = detect(resolve7(inputPath));
     if (opts.out) {
       writeJson(opts.out, result);
-      console.log(`Detected ${result.total_files} files in ${resolve5(inputPath)}`);
+      console.log(`Detected ${result.total_files} files in ${resolve7(inputPath)}`);
     } else {
       console.log(JSON.stringify(result, null, 2));
     }
   });
   program.command("detect-incremental").argument("<inputPath>").option("--manifest <path>", "Path to manifest.json", "graphify-out/manifest.json").option("--out <path>").action((inputPath, opts) => {
-    const result = detectIncremental(resolve5(inputPath), resolve5(opts.manifest));
+    const result = detectIncremental(resolve7(inputPath), resolve7(opts.manifest));
     if (opts.out) {
       writeJson(opts.out, result);
-      console.log(`${result.new_total ?? 0} new/changed file(s) under ${resolve5(inputPath)}`);
+      console.log(`${result.new_total ?? 0} new/changed file(s) under ${resolve7(inputPath)}`);
     } else {
       console.log(JSON.stringify(result, null, 2));
     }
   });
+  program.command("prepare-semantic-detect").requiredOption("--detect <path>", "Path to the base detection JSON").requiredOption("--out <path>", "Path to the augmented semantic detection JSON").requiredOption("--transcripts-out <path>", "Path to the transcript path list JSON").option("--analysis <path>", "Optional analysis JSON from a previous run").option("--incremental", "Use detection.new_files.video and force retranscription").option("--whisper-model <name>", "Whisper model override for local transcription").action(async (opts) => {
+    const detection = readJson(opts.detect);
+    const analysis = opts.analysis && existsSync8(resolve7(opts.analysis)) ? readJson(opts.analysis) : null;
+    const transcriptsDir = join5(dirname4(resolve7(opts.out)), "transcripts");
+    const { detection: semanticDetection, transcriptPaths } = await augmentDetectionWithTranscripts(detection, {
+      outputDir: transcriptsDir,
+      godNodes: analysis?.gods,
+      incremental: opts.incremental,
+      whisperModel: opts.whisperModel
+    });
+    writeJson(opts.out, semanticDetection);
+    writeJson(opts.transcriptsOut, transcriptPaths);
+    console.log(`Transcribed ${transcriptPaths.length} video file(s) -> treating as docs`);
+  });
   program.command("extract-ast").requiredOption("--detect <path>", "Path to detection JSON").requiredOption("--out <path>", "Path to AST extraction JSON").option("--incremental", "Use detection.new_files.code instead of detection.files.code").action(async (opts) => {
     const detection = readJson(opts.detect);
     const codeFiles = opts.incremental ? detection.new_files?.code ?? [] : detection.files.code ?? [];
@@ -5325,15 +5818,15 @@ async function main() {
     ];
     const [cachedNodes, cachedEdges, cachedHyperedges, uncached] = checkSemanticCache(
       allFiles,
-      resolve5(opts.root)
+      resolve7(opts.root)
     );
     writeJson(opts.cachedOut, {
       nodes: cachedNodes,
       edges: cachedEdges,
       hyperedges: cachedHyperedges
     });
-    mkdirSync4(dirname2(resolve5(opts.uncachedOut)), { recursive: true });
-    writeFileSync5(resolve5(opts.uncachedOut), uncached.join("\n"), "utf-8");
+    mkdirSync5(dirname4(resolve7(opts.uncachedOut)), { recursive: true });
+    writeFileSync6(resolve7(opts.uncachedOut), uncached.join("\n"), "utf-8");
     console.log(`Cache: ${allFiles.length - uncached.length} files hit, ${uncached.length} files need extraction`);
   });
   program.command("save-semantic-cache").requiredOption("--input <path>", "Path to semantic extraction JSON").option("--root <path>", "Graph root for cache resolution", ".").action((opts) => {
@@ -5342,7 +5835,7 @@ async function main() {
       extraction.nodes,
       extraction.edges,
       extraction.hyperedges ?? [],
-      resolve5(opts.root)
+      resolve7(opts.root)
     );
     console.log(`Cached ${saved} files`);
   });
@@ -5390,11 +5883,11 @@ async function main() {
       `Merged: ${merged.nodes.length} nodes, ${merged.edges.length} edges (${ast.nodes.length} AST + ${semantic.nodes.length} semantic)`
     );
   });
-  program.command("finalize-build").requiredOption("--detect <path>").requiredOption("--ast <path>").requiredOption("--root <path>").requiredOption("--graph-out <path>").requiredOption("--report-out <path>").requiredOption("--analysis-out <path>").requiredOption("--cost-out <path>").option("--cached <path>", "Optional cached semantic JSON").option("--semantic-new <path>", "Optional fresh semantic JSON").option("--html-out <path>", "Optional graph.html output path").action((opts) => {
+  program.command("finalize-build").requiredOption("--detect <path>").requiredOption("--ast <path>").requiredOption("--root <path>").requiredOption("--graph-out <path>").requiredOption("--report-out <path>").requiredOption("--analysis-out <path>").requiredOption("--cost-out <path>").option("--directed", "Build a directed graph (preserves source->target)").option("--cached <path>", "Optional cached semantic JSON").option("--semantic-new <path>", "Optional fresh semantic JSON").option("--html-out <path>", "Optional graph.html output path").action((opts) => {
     const detection = readJson(opts.detect);
     const ast = ensureExtractionShape(readJson(opts.ast));
-    const cached = opts.cached && existsSync7(resolve5(opts.cached)) ? readJson(opts.cached) : null;
-    const semanticNew = opts.semanticNew && existsSync7(resolve5(opts.semanticNew)) ? readJson(opts.semanticNew) : null;
+    const cached = opts.cached && existsSync8(resolve7(opts.cached)) ? readJson(opts.cached) : null;
+    const semanticNew = opts.semanticNew && existsSync8(resolve7(opts.semanticNew)) ? readJson(opts.semanticNew) : null;
     if (semanticNew) {
       saveSemanticCache(
         semanticNew.nodes,
@@ -5405,35 +5898,37 @@ async function main() {
     }
     const semantic = mergeSemanticArtifacts(cached, semanticNew);
     const extraction = mergeAstAndSemantic(ast, semantic);
-    const G = buildFromJson(extraction);
+    const G = buildFromJson(extraction, { directed: shouldBuildDirected(opts) });
     if (G.order === 0) {
       throw new Error("Graph is empty - extraction produced no nodes.");
     }
     const analyzed = analyzeGraph(
       G,
       detection,
-      resolve5(opts.root),
+      resolve7(opts.root),
       { input: extraction.input_tokens ?? 0, output: extraction.output_tokens ?? 0 }
     );
-    toJson(G, analyzed.communities, resolve5(opts.graphOut));
-    writeFileSync5(resolve5(opts.reportOut), analyzed.report, "utf-8");
+    toJson(G, analyzed.communities, resolve7(opts.graphOut), {
+      communityLabels: analyzed.labels
+    });
+    writeFileSync6(resolve7(opts.reportOut), analyzed.report, "utf-8");
     writeJson(opts.analysisOut, analyzed.analysis);
     if (opts.htmlOut) {
-      toHtml(G, analyzed.communities, resolve5(opts.htmlOut), {
+      toHtml(G, analyzed.communities, resolve7(opts.htmlOut), {
         communityLabels: analyzed.labels
       });
     }
-    saveManifest(detection.files, join4(dirname2(resolve5(opts.graphOut)), "manifest.json"));
+    saveManifest(detection.files, join5(dirname4(resolve7(opts.graphOut)), "manifest.json"));
     const cost = updateCostFile(extraction, detection, opts.costOut);
     console.log(`Graph: ${G.order} nodes, ${G.size} edges, ${analyzed.communities.size} communities`);
     console.log(`This run: ${(extraction.input_tokens ?? 0).toLocaleString()} input tokens, ${(extraction.output_tokens ?? 0).toLocaleString()} output tokens`);
     console.log(`All time: ${cost.total_input_tokens.toLocaleString()} input, ${cost.total_output_tokens.toLocaleString()} output (${cost.runs.length} runs)`);
   });
-  program.command("finalize-update").requiredOption("--detect <path>").requiredOption("--ast <path>").requiredOption("--existing-graph <path>").requiredOption("--root <path>").requiredOption("--graph-out <path>").requiredOption("--report-out <path>").requiredOption("--analysis-out <path>").requiredOption("--cost-out <path>").option("--cached <path>", "Optional cached semantic JSON").option("--semantic-new <path>", "Optional fresh semantic JSON").option("--html-out <path>", "Optional graph.html output path").action((opts) => {
+  program.command("finalize-update").requiredOption("--detect <path>").requiredOption("--ast <path>").requiredOption("--existing-graph <path>").requiredOption("--root <path>").requiredOption("--graph-out <path>").requiredOption("--report-out <path>").requiredOption("--analysis-out <path>").requiredOption("--cost-out <path>").option("--directed", "Build a directed graph (preserves source->target)").option("--cached <path>", "Optional cached semantic JSON").option("--semantic-new <path>", "Optional fresh semantic JSON").option("--html-out <path>", "Optional graph.html output path").action((opts) => {
     const detection = readJson(opts.detect);
     const ast = ensureExtractionShape(readJson(opts.ast));
-    const cached = opts.cached && existsSync7(resolve5(opts.cached)) ? readJson(opts.cached) : null;
-    const semanticNew = opts.semanticNew && existsSync7(resolve5(opts.semanticNew)) ? readJson(opts.semanticNew) : null;
+    const cached = opts.cached && existsSync8(resolve7(opts.cached)) ? readJson(opts.cached) : null;
+    const semanticNew = opts.semanticNew && existsSync8(resolve7(opts.semanticNew)) ? readJson(opts.semanticNew) : null;
     if (semanticNew) {
       saveSemanticCache(
         semanticNew.nodes,
@@ -5446,35 +5941,39 @@ async function main() {
     const extraction = mergeAstAndSemantic(ast, semantic);
     const oldGraph = loadGraph2(opts.existingGraph);
     const mergedGraph = loadGraph2(opts.existingGraph);
-    const newGraph = buildFromJson(extraction);
+    const newGraph = buildFromJson(extraction, {
+      directed: shouldBuildDirected(opts, oldGraph)
+    });
     mergeGraphs(mergedGraph, newGraph);
     const analyzed = analyzeGraph(
       mergedGraph,
       detection,
-      resolve5(opts.root),
+      resolve7(opts.root),
       { input: extraction.input_tokens ?? 0, output: extraction.output_tokens ?? 0 }
     );
     analyzed.analysis.diff = graphDiff(oldGraph, mergedGraph);
-    toJson(mergedGraph, analyzed.communities, resolve5(opts.graphOut));
-    writeFileSync5(resolve5(opts.reportOut), analyzed.report, "utf-8");
+    toJson(mergedGraph, analyzed.communities, resolve7(opts.graphOut), {
+      communityLabels: analyzed.labels
+    });
+    writeFileSync6(resolve7(opts.reportOut), analyzed.report, "utf-8");
     writeJson(opts.analysisOut, analyzed.analysis);
     if (opts.htmlOut) {
-      toHtml(mergedGraph, analyzed.communities, resolve5(opts.htmlOut), {
+      toHtml(mergedGraph, analyzed.communities, resolve7(opts.htmlOut), {
         communityLabels: analyzed.labels
       });
     }
-    saveManifest(detection.files, join4(dirname2(resolve5(opts.graphOut)), "manifest.json"));
+    saveManifest(detection.files, join5(dirname4(resolve7(opts.graphOut)), "manifest.json"));
     const cost = updateCostFile(extraction, detection, opts.costOut);
     console.log(`Merged: ${mergedGraph.order} nodes, ${mergedGraph.size} edges`);
     console.log(analyzed.analysis.diff.summary);
     console.log(`This run: ${(extraction.input_tokens ?? 0).toLocaleString()} input tokens, ${(extraction.output_tokens ?? 0).toLocaleString()} output tokens`);
     console.log(`All time: ${cost.total_input_tokens.toLocaleString()} input, ${cost.total_output_tokens.toLocaleString()} output (${cost.runs.length} runs)`);
   });
-  program.command("analyze-build").requiredOption("--extract <path>").requiredOption("--detect <path>").requiredOption("--root <path>").requiredOption("--graph-out <path>").requiredOption("--report-out <path>").requiredOption("--analysis-out <path>").action((opts) => {
+  program.command("analyze-build").requiredOption("--extract <path>").requiredOption("--detect <path>").requiredOption("--root <path>").requiredOption("--graph-out <path>").requiredOption("--report-out <path>").requiredOption("--analysis-out <path>").option("--directed", "Build a directed graph (preserves source->target)").action((opts) => {
     const extraction = ensureExtractionShape(readJson(opts.extract));
     const detection = readJson(opts.detect);
-    const root = resolve5(opts.root);
-    const G = buildFromJson(extraction);
+    const root = resolve7(opts.root);
+    const G = buildFromJson(extraction, { directed: shouldBuildDirected(opts) });
     if (G.order === 0) {
       throw new Error("Graph is empty - extraction produced no nodes.");
     }
@@ -5484,20 +5983,22 @@ async function main() {
       root,
       { input: extraction.input_tokens ?? 0, output: extraction.output_tokens ?? 0 }
     );
-    mkdirSync4(dirname2(resolve5(opts.graphOut)), { recursive: true });
-    toJson(G, analyzed.communities, resolve5(opts.graphOut));
-    writeFileSync5(resolve5(opts.reportOut), analyzed.report, "utf-8");
+    mkdirSync5(dirname4(resolve7(opts.graphOut)), { recursive: true });
+    toJson(G, analyzed.communities, resolve7(opts.graphOut), {
+      communityLabels: analyzed.labels
+    });
+    writeFileSync6(resolve7(opts.reportOut), analyzed.report, "utf-8");
     writeJson(opts.analysisOut, analyzed.analysis);
-    saveManifest(detection.files, join4(dirname2(resolve5(opts.graphOut)), "manifest.json"));
+    saveManifest(detection.files, join5(dirname4(resolve7(opts.graphOut)), "manifest.json"));
     console.log(`Graph: ${G.order} nodes, ${G.size} edges, ${analyzed.communities.size} communities`);
   });
-  program.command("write-labeled-report").requiredOption("--extract <path>").requiredOption("--detect <path>").requiredOption("--analysis <path>").requiredOption("--labels <path>").requiredOption("--root <path>").requiredOption("--report-out <path>").action((opts) => {
+  program.command("write-labeled-report").requiredOption("--extract <path>").requiredOption("--detect <path>").requiredOption("--analysis <path>").requiredOption("--labels <path>").requiredOption("--root <path>").requiredOption("--report-out <path>").option("--directed", "Build a directed graph (preserves source->target)").option("--graph-out <path>").option("--html-out <path>").action((opts) => {
     const extraction = ensureExtractionShape(readJson(opts.extract));
     const detection = readJson(opts.detect);
     const analysis = readJson(opts.analysis);
     const labelObject = readJson(opts.labels);
     const labels = objectToStringMap(labelObject);
-    const G = buildFromJson(extraction);
+    const G = buildFromJson(extraction, { directed: shouldBuildDirected(opts) });
     const communities = new Map(
       Object.entries(analysis.communities).map(([key, value]) => [Number.parseInt(key, 10), value])
     );
@@ -5514,57 +6015,63 @@ async function main() {
       analysis.surprises,
       detection,
       { input: extraction.input_tokens ?? 0, output: extraction.output_tokens ?? 0 },
-      resolve5(opts.root),
+      resolve7(opts.root),
       questions
     );
     analysis.questions = questions;
     analysis.labels = mapToObject(labels);
-    writeFileSync5(resolve5(opts.reportOut), report, "utf-8");
+    writeFileSync6(resolve7(opts.reportOut), report, "utf-8");
+    if (opts.graphOut) {
+      toJson(G, communities, resolve7(opts.graphOut), { communityLabels: labels });
+    }
+    if (opts.htmlOut) {
+      toHtml(G, communities, resolve7(opts.htmlOut), { communityLabels: labels });
+    }
     writeJson(opts.analysis, analysis);
-    console.log("Report updated with community labels");
+    console.log("Labeled artifacts updated");
   });
-  program.command("export-html").requiredOption("--extract <path>").requiredOption("--analysis <path>").option("--labels <path>").requiredOption("--out <path>").action((opts) => {
+  program.command("export-html").requiredOption("--extract <path>").requiredOption("--analysis <path>").option("--labels <path>").requiredOption("--out <path>").option("--directed", "Build a directed graph (preserves source->target)").action((opts) => {
     const extraction = ensureExtractionShape(readJson(opts.extract));
     const analysis = readJson(opts.analysis);
     const labels = opts.labels ? objectToStringMap(readJson(opts.labels)) : objectToStringMap(analysis.labels);
     const communities = new Map(
       Object.entries(analysis.communities).map(([key, value]) => [Number.parseInt(key, 10), value])
     );
-    const G = buildFromJson(extraction);
-    toHtml(G, communities, resolve5(opts.out), { communityLabels: labels });
+    const G = buildFromJson(extraction, { directed: shouldBuildDirected(opts) });
+    toHtml(G, communities, resolve7(opts.out), { communityLabels: labels });
     console.log("graph.html written - open in any browser, no server needed");
   });
-  program.command("export-svg").requiredOption("--extract <path>").requiredOption("--analysis <path>").option("--labels <path>").requiredOption("--out <path>").action((opts) => {
+  program.command("export-svg").requiredOption("--extract <path>").requiredOption("--analysis <path>").option("--labels <path>").requiredOption("--out <path>").option("--directed", "Build a directed graph (preserves source->target)").action((opts) => {
     const extraction = ensureExtractionShape(readJson(opts.extract));
     const analysis = readJson(opts.analysis);
     const labels = opts.labels ? objectToStringMap(readJson(opts.labels)) : objectToStringMap(analysis.labels);
     const communities = new Map(
       Object.entries(analysis.communities).map(([key, value]) => [Number.parseInt(key, 10), value])
     );
-    const G = buildFromJson(extraction);
-    toSvg(G, communities, resolve5(opts.out), labels);
+    const G = buildFromJson(extraction, { directed: shouldBuildDirected(opts) });
+    toSvg(G, communities, resolve7(opts.out), labels);
     console.log("graph.svg written - embeds in Obsidian, Notion, GitHub READMEs");
   });
-  program.command("export-graphml").requiredOption("--extract <path>").requiredOption("--analysis <path>").requiredOption("--out <path>").action((opts) => {
+  program.command("export-graphml").requiredOption("--extract <path>").requiredOption("--analysis <path>").requiredOption("--out <path>").option("--directed", "Build a directed graph (preserves source->target)").action((opts) => {
     const extraction = ensureExtractionShape(readJson(opts.extract));
     const analysis = readJson(opts.analysis);
     const communities = new Map(
       Object.entries(analysis.communities).map(([key, value]) => [Number.parseInt(key, 10), value])
     );
-    const G = buildFromJson(extraction);
-    toGraphml(G, communities, resolve5(opts.out));
+    const G = buildFromJson(extraction, { directed: shouldBuildDirected(opts) });
+    toGraphml(G, communities, resolve7(opts.out));
     console.log("graph.graphml written - open in Gephi, yEd, or any GraphML tool");
   });
-  program.command("export-cypher").requiredOption("--extract <path>").requiredOption("--out <path>").action((opts) => {
+  program.command("export-cypher").requiredOption("--extract <path>").requiredOption("--out <path>").option("--directed", "Build a directed graph (preserves source->target)").action((opts) => {
     const extraction = ensureExtractionShape(readJson(opts.extract));
-    const G = buildFromJson(extraction);
-    toCypher(G, resolve5(opts.out));
+    const G = buildFromJson(extraction, { directed: shouldBuildDirected(opts) });
+    toCypher(G, resolve7(opts.out));
     console.log("cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt");
   });
-  program.command("push-neo4j").requiredOption("--extract <path>").requiredOption("--analysis <path>").requiredOption("--uri <uri>").requiredOption("--user <user>").requiredOption("--password <password>").action(async (opts) => {
+  program.command("push-neo4j").requiredOption("--extract <path>").requiredOption("--analysis <path>").requiredOption("--uri <uri>").requiredOption("--user <user>").requiredOption("--password <password>").option("--directed", "Build a directed graph (preserves source->target)").action(async (opts) => {
     const extraction = ensureExtractionShape(readJson(opts.extract));
     const analysis = readJson(opts.analysis);
-    const G = buildFromJson(extraction);
+    const G = buildFromJson(extraction, { directed: shouldBuildDirected(opts) });
     const communities = new Map(
       Object.entries(analysis.communities).map(([key, value]) => [Number.parseInt(key, 10), value])
     );
@@ -5578,19 +6085,19 @@ async function main() {
   });
   program.command("benchmark").requiredOption("--graph <path>").option("--corpus-words <n>").action((opts) => {
     const corpusWords = opts.corpusWords ? Number.parseInt(opts.corpusWords, 10) : void 0;
-    const result = runBenchmark(resolve5(opts.graph), corpusWords);
+    const result = runBenchmark(resolve7(opts.graph), corpusWords);
     printBenchmark(result);
   });
   program.command("update-cost").requiredOption("--extract <path>").requiredOption("--detect <path>").requiredOption("--out <path>").action((opts) => {
     const extraction = ensureExtractionShape(readJson(opts.extract));
     const detection = readJson(opts.detect);
-    const outPath = resolve5(opts.out);
+    const outPath = resolve7(opts.out);
     let cost = {
       runs: [],
       total_input_tokens: 0,
       total_output_tokens: 0
     };
-    if (existsSync7(outPath)) {
+    if (existsSync8(outPath)) {
       cost = readJson(outPath);
     }
     const input = extraction.input_tokens ?? 0;
@@ -5609,24 +6116,28 @@ async function main() {
       `All time: ${cost.total_input_tokens.toLocaleString()} input, ${cost.total_output_tokens.toLocaleString()} output (${cost.runs.length} runs)`
     );
   });
-  program.command("merge-update").requiredOption("--existing-graph <path>").requiredOption("--extract <path>").requiredOption("--detect <path>").requiredOption("--root <path>").requiredOption("--graph-out <path>").requiredOption("--report-out <path>").requiredOption("--analysis-out <path>").action((opts) => {
+  program.command("merge-update").requiredOption("--existing-graph <path>").requiredOption("--extract <path>").requiredOption("--detect <path>").requiredOption("--root <path>").requiredOption("--graph-out <path>").requiredOption("--report-out <path>").requiredOption("--analysis-out <path>").option("--directed", "Build a directed graph (preserves source->target)").action((opts) => {
     const oldGraph = loadGraph2(opts.existingGraph);
     const mergedGraph = loadGraph2(opts.existingGraph);
     const extraction = ensureExtractionShape(readJson(opts.extract));
     const detection = readJson(opts.detect);
-    const newGraph = buildFromJson(extraction);
+    const newGraph = buildFromJson(extraction, {
+      directed: shouldBuildDirected(opts, oldGraph)
+    });
     mergeGraphs(mergedGraph, newGraph);
     const analyzed = analyzeGraph(
       mergedGraph,
       detection,
-      resolve5(opts.root),
+      resolve7(opts.root),
       { input: extraction.input_tokens ?? 0, output: extraction.output_tokens ?? 0 }
     );
     analyzed.analysis.diff = graphDiff(oldGraph, mergedGraph);
-    toJson(mergedGraph, analyzed.communities, resolve5(opts.graphOut));
-    writeFileSync5(resolve5(opts.reportOut), analyzed.report, "utf-8");
+    toJson(mergedGraph, analyzed.communities, resolve7(opts.graphOut), {
+      communityLabels: analyzed.labels
+    });
+    writeFileSync6(resolve7(opts.reportOut), analyzed.report, "utf-8");
     writeJson(opts.analysisOut, analyzed.analysis);
-    saveManifest(detection.files, join4(dirname2(resolve5(opts.graphOut)), "manifest.json"));
+    saveManifest(detection.files, join5(dirname4(resolve7(opts.graphOut)), "manifest.json"));
     console.log(`Merged: ${mergedGraph.order} nodes, ${mergedGraph.size} edges`);
     console.log(analyzed.analysis.diff.summary);
   });
@@ -5635,11 +6146,13 @@ async function main() {
     const analyzed = analyzeGraph(
       G,
       placeholderDetection(opts.root),
-      resolve5(opts.root),
+      resolve7(opts.root),
       { input: 0, output: 0 }
     );
-    toJson(G, analyzed.communities, resolve5(opts.graphOut));
-    writeFileSync5(resolve5(opts.reportOut), analyzed.report, "utf-8");
+    toJson(G, analyzed.communities, resolve7(opts.graphOut), {
+      communityLabels: analyzed.labels
+    });
+    writeFileSync6(resolve7(opts.reportOut), analyzed.report, "utf-8");
     writeJson(opts.analysisOut, analyzed.analysis);
     console.log(`Re-clustered: ${analyzed.communities.size} communities`);
   });
@@ -5690,7 +6203,7 @@ async function main() {
     console.log(`  degree: ${G.degree(nodeId)}`);
     console.log("");
     console.log("CONNECTIONS:");
-    G.forEachNeighbor(nodeId, (neighbor) => {
+    forEachTraversalNeighbor(G, nodeId, (neighbor) => {
       const edgeId = G.edge(nodeId, neighbor);
       const edge = edgeId ? G.getEdgeAttributes(edgeId) : {};
       const label = G.getNodeAttribute(neighbor, "label") ?? neighbor;
@@ -5699,7 +6212,7 @@ async function main() {
     });
   });
   program.command("ingest").argument("<url>").option("--target-dir <path>", "Directory to save fetched content", "./raw").option("--author <name>").option("--contributor <name>").action(async (url, opts) => {
-    const outPath = await ingest(url, resolve5(opts.targetDir), {
+    const outPath = await ingest(url, resolve7(opts.targetDir), {
       author: opts.author ?? null,
       contributor: opts.contributor ?? null
     });
@@ -5709,7 +6222,7 @@ async function main() {
     const outPath = saveQueryResult({
       question: opts.question,
       answer: opts.answer,
-      memoryDir: resolve5(opts.memoryDir),
+      memoryDir: resolve7(opts.memoryDir),
       queryType: opts.queryType,
       sourceNodes: JSON.parse(opts.sourceNodesJson)
     });