depwire-cli 0.4.0 → 0.6.0

package/dist/{chunk-X2DOGIIG.js → chunk-AFJFZXCI.js}

@@ -2638,12 +2638,500 @@ async function updateFileInGraph(graph, projectRoot, relativeFilePath) {
   }
 }
 
+// src/health/metrics.ts
+import { dirname as dirname6 } from "path";
+function scoreToGrade(score) {
+  if (score >= 90) return "A";
+  if (score >= 80) return "B";
+  if (score >= 70) return "C";
+  if (score >= 60) return "D";
+  return "F";
+}
+function calculateCouplingScore(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  if (files.size === 0) {
+    return {
+      name: "Coupling",
+      score: 100,
+      weight: 0.25,
+      grade: "A",
+      details: "No files to analyze",
+      metrics: { avgConnections: 0, maxConnections: 0, crossDirCoupling: 0 }
+    };
+  }
+  const fileConnections = /* @__PURE__ */ new Map();
+  let crossDirEdges = 0;
+  let totalEdges = 0;
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      totalEdges++;
+      fileConnections.set(sourceAttrs.filePath, (fileConnections.get(sourceAttrs.filePath) || 0) + 1);
+      fileConnections.set(targetAttrs.filePath, (fileConnections.get(targetAttrs.filePath) || 0) + 1);
+      const sourceDir = dirname6(sourceAttrs.filePath).split("/")[0];
+      const targetDir = dirname6(targetAttrs.filePath).split("/")[0];
+      if (sourceDir !== targetDir) {
+        crossDirEdges++;
+      }
+    }
+  });
+  const avgConnections = totalEdges / files.size;
+  const maxConnections = Math.max(...Array.from(fileConnections.values()), 0);
+  const crossDirCoupling = totalEdges > 0 ? crossDirEdges / totalEdges : 0;
+  let score = 100;
+  if (avgConnections <= 3) {
+    score = 100;
+  } else if (avgConnections <= 6) {
+    score = 80;
+  } else if (avgConnections <= 10) {
+    score = 60;
+  } else if (avgConnections <= 15) {
+    score = 40;
+  } else {
+    score = 20;
+  }
+  if (maxConnections > avgConnections * 3) {
+    score -= 10;
+  }
+  if (crossDirCoupling > 0.7) {
+    score -= 10;
+  }
+  score = Math.max(0, Math.min(100, score));
+  return {
+    name: "Coupling",
+    score,
+    weight: 0.25,
+    grade: scoreToGrade(score),
+    details: `Average ${avgConnections.toFixed(1)} connections per file, max ${maxConnections}, ${(crossDirCoupling * 100).toFixed(0)}% cross-directory`,
+    metrics: {
+      avgConnections: parseFloat(avgConnections.toFixed(2)),
+      maxConnections,
+      crossDirCoupling: parseFloat((crossDirCoupling * 100).toFixed(1))
+    }
+  };
+}
+function calculateCohesionScore(graph) {
+  const dirEdges = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceDir = dirname6(sourceAttrs.filePath);
+      const targetDir = dirname6(targetAttrs.filePath);
+      if (!dirEdges.has(sourceDir)) {
+        dirEdges.set(sourceDir, { internal: 0, total: 0 });
+      }
+      const stats = dirEdges.get(sourceDir);
+      stats.total++;
+      if (sourceDir === targetDir) {
+        stats.internal++;
+      }
+    }
+  });
+  if (dirEdges.size === 0) {
+    return {
+      name: "Cohesion",
+      score: 100,
+      weight: 0.2,
+      grade: "A",
+      details: "No inter-file dependencies",
+      metrics: { avgInternalRatio: 1, directories: 0 }
+    };
+  }
+  let totalRatio = 0;
+  for (const stats of dirEdges.values()) {
+    if (stats.total > 0) {
+      totalRatio += stats.internal / stats.total;
+    }
+  }
+  const avgInternalRatio = totalRatio / dirEdges.size;
+  let score = 100;
+  if (avgInternalRatio >= 0.7) {
+    score = 100;
+  } else if (avgInternalRatio >= 0.5) {
+    score = 80;
+  } else if (avgInternalRatio >= 0.3) {
+    score = 60;
+  } else if (avgInternalRatio >= 0.1) {
+    score = 40;
+  } else {
+    score = 20;
+  }
+  return {
+    name: "Cohesion",
+    score,
+    weight: 0.2,
+    grade: scoreToGrade(score),
+    details: `Average ${(avgInternalRatio * 100).toFixed(0)}% internal dependencies per directory`,
+    metrics: {
+      avgInternalRatio: parseFloat((avgInternalRatio * 100).toFixed(1)),
+      directories: dirEdges.size
+    }
+  };
+}
+function calculateCircularDepsScore(graph) {
+  const fileGraph = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      if (!fileGraph.has(sourceFile)) {
+        fileGraph.set(sourceFile, /* @__PURE__ */ new Set());
+      }
+      fileGraph.get(sourceFile).add(targetFile);
+    }
+  });
+  const visited = /* @__PURE__ */ new Set();
+  const recStack = /* @__PURE__ */ new Set();
+  const cycles = [];
+  function dfs(node, path2) {
+    if (recStack.has(node)) {
+      const cycleStart = path2.indexOf(node);
+      if (cycleStart >= 0) {
+        cycles.push(path2.slice(cycleStart));
+      }
+      return;
+    }
+    if (visited.has(node)) {
+      return;
+    }
+    visited.add(node);
+    recStack.add(node);
+    path2.push(node);
+    const neighbors = fileGraph.get(node);
+    if (neighbors) {
+      for (const neighbor of neighbors) {
+        dfs(neighbor, [...path2]);
+      }
+    }
+    recStack.delete(node);
+  }
+  for (const node of fileGraph.keys()) {
+    if (!visited.has(node)) {
+      dfs(node, []);
+    }
+  }
+  const uniqueCycles = /* @__PURE__ */ new Set();
+  for (const cycle of cycles) {
+    const sorted = [...cycle].sort().join(",");
+    uniqueCycles.add(sorted);
+  }
+  const cycleCount = uniqueCycles.size;
+  let score = 100;
+  if (cycleCount === 0) {
+    score = 100;
+  } else if (cycleCount <= 2) {
+    score = 80;
+  } else if (cycleCount <= 5) {
+    score = 60;
+  } else if (cycleCount <= 10) {
+    score = 40;
+  } else {
+    score = 20;
+  }
+  return {
+    name: "Circular Dependencies",
+    score,
+    weight: 0.2,
+    grade: scoreToGrade(score),
+    details: cycleCount === 0 ? "No circular dependencies detected" : `${cycleCount} circular dependency cycle${cycleCount === 1 ? "" : "s"} detected`,
+    metrics: { cycles: cycleCount }
+  };
+}
+function calculateGodFilesScore(graph) {
+  const files = /* @__PURE__ */ new Set();
+  const fileConnections = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  if (files.size === 0) {
+    return {
+      name: "God Files",
+      score: 100,
+      weight: 0.15,
+      grade: "A",
+      details: "No files to analyze",
+      metrics: { godFiles: 0, threshold: 0 }
+    };
+  }
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      fileConnections.set(sourceFile, (fileConnections.get(sourceFile) || 0) + 1);
+      fileConnections.set(targetFile, (fileConnections.get(targetFile) || 0) + 1);
+    }
+  });
+  const connections = Array.from(fileConnections.values());
+  const avgConnections = connections.length > 0 ? connections.reduce((a, b) => a + b, 0) / connections.length : 0;
+  const godThreshold = avgConnections * 3;
+  const godFiles = connections.filter((c) => c > godThreshold).length;
+  let score = 100;
+  if (godFiles === 0) {
+    score = 100;
+  } else if (godFiles === 1) {
+    score = 80;
+  } else if (godFiles <= 3) {
+    score = 60;
+  } else if (godFiles <= 5) {
+    score = 40;
+  } else {
+    score = 20;
+  }
+  return {
+    name: "God Files",
+    score,
+    weight: 0.15,
+    grade: scoreToGrade(score),
+    details: godFiles === 0 ? "No god files detected" : `${godFiles} god file${godFiles === 1 ? "" : "s"} (>${godThreshold.toFixed(0)} connections)`,
+    metrics: { godFiles, threshold: parseFloat(godThreshold.toFixed(1)) }
+  };
+}
+function calculateOrphansScore(graph) {
+  const files = /* @__PURE__ */ new Set();
+  const connectedFiles = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      connectedFiles.add(sourceFile);
+      connectedFiles.add(targetFile);
+    }
+  });
+  const orphanCount = files.size - connectedFiles.size;
+  const orphanPercent = files.size > 0 ? orphanCount / files.size * 100 : 0;
+  let score = 100;
+  if (orphanPercent === 0) {
+    score = 100;
+  } else if (orphanPercent <= 5) {
+    score = 80;
+  } else if (orphanPercent <= 10) {
+    score = 60;
+  } else if (orphanPercent <= 20) {
+    score = 40;
+  } else {
+    score = 20;
+  }
+  return {
+    name: "Orphan Files",
+    score,
+    weight: 0.1,
+    grade: scoreToGrade(score),
+    details: orphanCount === 0 ? "No orphan files" : `${orphanCount} orphan file${orphanCount === 1 ? "" : "s"} (${orphanPercent.toFixed(0)}%)`,
+    metrics: { orphans: orphanCount, percentage: parseFloat(orphanPercent.toFixed(1)) }
+  };
+}
+function calculateDepthScore(graph) {
+  const fileGraph = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      if (!fileGraph.has(sourceFile)) {
+        fileGraph.set(sourceFile, /* @__PURE__ */ new Set());
+      }
+      fileGraph.get(sourceFile).add(targetFile);
+    }
+  });
+  function findLongestPath(start) {
+    const visited = /* @__PURE__ */ new Set();
+    let maxDepth2 = 0;
+    function dfs(node, depth) {
+      if (visited.has(node)) {
+        return;
+      }
+      visited.add(node);
+      maxDepth2 = Math.max(maxDepth2, depth);
+      const neighbors = fileGraph.get(node);
+      if (neighbors) {
+        for (const neighbor of neighbors) {
+          dfs(neighbor, depth + 1);
+        }
+      }
+      visited.delete(node);
+    }
+    dfs(start, 0);
+    return maxDepth2;
+  }
+  let maxDepth = 0;
+  for (const node of fileGraph.keys()) {
+    const depth = findLongestPath(node);
+    maxDepth = Math.max(maxDepth, depth);
+  }
+  let score = 100;
+  if (maxDepth <= 4) {
+    score = 100;
+  } else if (maxDepth <= 6) {
+    score = 80;
+  } else if (maxDepth <= 8) {
+    score = 60;
+  } else if (maxDepth <= 12) {
+    score = 40;
+  } else {
+    score = 20;
+  }
+  return {
+    name: "Dependency Depth",
+    score,
+    weight: 0.1,
+    grade: scoreToGrade(score),
+    details: `Maximum dependency chain: ${maxDepth} level${maxDepth === 1 ? "" : "s"}`,
+    metrics: { maxDepth }
+  };
+}
+
+// src/health/index.ts
+import { readFileSync as readFileSync4, writeFileSync, existsSync as existsSync6 } from "fs";
+import { join as join9 } from "path";
+function calculateHealthScore(graph, projectRoot) {
+  const coupling = calculateCouplingScore(graph);
+  const cohesion = calculateCohesionScore(graph);
+  const circular = calculateCircularDepsScore(graph);
+  const godFiles = calculateGodFilesScore(graph);
+  const orphans = calculateOrphansScore(graph);
+  const depth = calculateDepthScore(graph);
+  const dimensions = [coupling, cohesion, circular, godFiles, orphans, depth];
+  const overall = Math.round(
+    dimensions.reduce((sum, dim) => sum + dim.score * dim.weight, 0)
+  );
+  const files = /* @__PURE__ */ new Set();
+  const languages2 = {};
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+    const ext = attrs.filePath.toLowerCase();
+    let lang;
+    if (ext.endsWith(".ts") || ext.endsWith(".tsx")) {
+      lang = "TypeScript";
+    } else if (ext.endsWith(".js") || ext.endsWith(".jsx") || ext.endsWith(".mjs") || ext.endsWith(".cjs")) {
+      lang = "JavaScript";
+    } else if (ext.endsWith(".py")) {
+      lang = "Python";
+    } else if (ext.endsWith(".go")) {
+      lang = "Go";
+    } else {
+      lang = "Other";
+    }
+    languages2[lang] = (languages2[lang] || 0) + 1;
+  });
+  const grade = scoreToGrade(overall);
+  let summary = `Project health score is ${overall}/100 (Grade: ${grade}). `;
+  if (overall >= 90) {
+    summary += "Excellent architecture with minimal issues.";
+  } else if (overall >= 80) {
+    summary += "Good architecture with some areas for improvement.";
+  } else if (overall >= 70) {
+    summary += "Moderate architecture quality. Consider refactoring high-risk areas.";
+  } else if (overall >= 60) {
+    summary += "Architecture needs improvement. Multiple issues detected.";
+  } else {
+    summary += "Poor architecture quality. Significant refactoring recommended.";
+  }
+  const recommendations = [];
+  if (coupling.score < 70) {
+    recommendations.push(`High coupling detected: Average ${coupling.metrics.avgConnections} connections per file. Consider breaking down large modules.`);
+  }
+  if (cohesion.score < 70) {
+    recommendations.push(`Low cohesion: Only ${cohesion.metrics.avgInternalRatio}% internal dependencies. Reorganize files by feature or domain.`);
+  }
+  if (circular.score < 80 && typeof circular.metrics.cycles === "number" && circular.metrics.cycles > 0) {
+    recommendations.push(`${circular.metrics.cycles} circular dependency cycle${circular.metrics.cycles === 1 ? "" : "s"} detected. Break cycles by introducing interfaces or extracting shared code.`);
+  }
+  if (godFiles.score < 80 && typeof godFiles.metrics.godFiles === "number" && godFiles.metrics.godFiles > 0) {
+    recommendations.push(`${godFiles.metrics.godFiles} god file${godFiles.metrics.godFiles === 1 ? "" : "s"} detected with >${godFiles.metrics.threshold} connections. Split into smaller, focused modules.`);
+  }
+  if (orphans.score < 80 && typeof orphans.metrics.orphans === "number" && orphans.metrics.orphans > 0) {
+    recommendations.push(`${orphans.metrics.orphans} orphan file${orphans.metrics.orphans === 1 ? "" : "s"} detected. Verify they're needed or remove dead code.`);
+  }
+  if (depth.score < 80 && typeof depth.metrics.maxDepth === "number") {
+    recommendations.push(`Maximum dependency depth is ${depth.metrics.maxDepth} levels. Consider flattening the deepest chains.`);
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("No critical issues detected. Maintain current architecture quality.");
+  }
+  const report = {
+    overall,
+    grade,
+    dimensions,
+    summary,
+    recommendations,
+    projectStats: {
+      files: files.size,
+      symbols: graph.order,
+      edges: graph.size,
+      languages: languages2
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  saveHealthHistory(projectRoot, report);
+  return report;
+}
+function getHealthTrend(projectRoot, currentScore) {
+  const history = loadHealthHistory(projectRoot);
+  if (history.length < 2) {
+    return null;
+  }
+  const previous = history[history.length - 2];
+  const delta = currentScore - previous.score;
+  if (delta > 0) {
+    return `\u2191 +${delta}`;
+  } else if (delta < 0) {
+    return `\u2193 ${delta}`;
+  } else {
+    return "\u2192 0";
+  }
+}
+function saveHealthHistory(projectRoot, report) {
+  const historyFile = join9(projectRoot, ".depwire", "health-history.json");
+  const entry = {
+    timestamp: report.timestamp,
+    score: report.overall,
+    grade: report.grade,
+    dimensions: report.dimensions.map((d) => ({
+      name: d.name,
+      score: d.score,
+      grade: d.grade
+    }))
+  };
+  let history = [];
+  if (existsSync6(historyFile)) {
+    try {
+      const content = readFileSync4(historyFile, "utf-8");
+      history = JSON.parse(content);
+    } catch {
+    }
+  }
+  history.push(entry);
+  if (history.length > 50) {
+    history = history.slice(-50);
+  }
+  writeFileSync(historyFile, JSON.stringify(history, null, 2), "utf-8");
+}
+function loadHealthHistory(projectRoot) {
+  const historyFile = join9(projectRoot, ".depwire", "health-history.json");
+  if (!existsSync6(historyFile)) {
+    return [];
+  }
+  try {
+    const content = readFileSync4(historyFile, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return [];
+  }
+}
+
 // src/docs/generator.ts
-import { writeFileSync as writeFileSync2, mkdirSync, existsSync as existsSync7 } from "fs";
-import { join as join10 } from "path";
+import { writeFileSync as writeFileSync3, mkdirSync, existsSync as existsSync9 } from "fs";
+import { join as join12 } from "path";
 
 // src/docs/architecture.ts
-import { dirname as dirname6 } from "path";
+import { dirname as dirname7 } from "path";
 
 // src/docs/templates.ts
 function header(text, level = 1) {
@@ -2654,9 +3142,9 @@ function header(text, level = 1) {
 function code(text) {
   return `\`${text}\``;
 }
-function codeBlock(code2, lang = "") {
+function codeBlock(code3, lang = "") {
   return `\`\`\`${lang}
-${code2}
+${code3}
 \`\`\`
 
 `;
@@ -2794,7 +3282,7 @@ function generateModuleStructure(graph) {
 function getDirectoryStats(graph) {
   const dirMap = /* @__PURE__ */ new Map();
   graph.forEachNode((node, attrs) => {
-    const dir = dirname6(attrs.filePath);
+    const dir = dirname7(attrs.filePath);
     if (dir === ".") return;
     if (!dirMap.has(dir)) {
       dirMap.set(dir, {
@@ -2819,7 +3307,7 @@ function getDirectoryStats(graph) {
   });
   const filesPerDir = /* @__PURE__ */ new Map();
   graph.forEachNode((node, attrs) => {
-    const dir = dirname6(attrs.filePath);
+    const dir = dirname7(attrs.filePath);
     if (!filesPerDir.has(dir)) {
       filesPerDir.set(dir, /* @__PURE__ */ new Set());
     }
@@ -2834,8 +3322,8 @@ function getDirectoryStats(graph) {
   graph.forEachEdge((edge, attrs, source, target) => {
     const sourceAttrs = graph.getNodeAttributes(source);
     const targetAttrs = graph.getNodeAttributes(target);
-    const sourceDir = dirname6(sourceAttrs.filePath);
-    const targetDir = dirname6(targetAttrs.filePath);
+    const sourceDir = dirname7(sourceAttrs.filePath);
+    const targetDir = dirname7(targetAttrs.filePath);
     if (sourceDir !== targetDir) {
       if (!dirEdges.has(sourceDir)) {
         dirEdges.set(sourceDir, { in: 0, out: 0 });
@@ -3816,7 +4304,7 @@ function detectCyclesDetailed(graph) {
 }
 
 // src/docs/onboarding.ts
-import { dirname as dirname7 } from "path";
+import { dirname as dirname8 } from "path";
 function generateOnboarding(graph, projectRoot, version) {
   let output = "";
   const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
@@ -3875,7 +4363,7 @@ function generateQuickOrientation(graph) {
   const primaryLang = Object.entries(languages2).sort((a, b) => b[1] - a[1])[0];
   const dirs = /* @__PURE__ */ new Set();
   graph.forEachNode((node, attrs) => {
-    const dir = dirname7(attrs.filePath);
+    const dir = dirname8(attrs.filePath);
     if (dir !== ".") {
       const topLevel = dir.split("/")[0];
       dirs.add(topLevel);
@@ -3979,7 +4467,7 @@ function generateModuleMap(graph) {
 function getDirectoryStats2(graph) {
   const dirMap = /* @__PURE__ */ new Map();
   graph.forEachNode((node, attrs) => {
-    const dir = dirname7(attrs.filePath);
+    const dir = dirname8(attrs.filePath);
     if (dir === ".") return;
     if (!dirMap.has(dir)) {
       dirMap.set(dir, {
@@ -3994,7 +4482,7 @@ function getDirectoryStats2(graph) {
   });
   const filesPerDir = /* @__PURE__ */ new Map();
   graph.forEachNode((node, attrs) => {
-    const dir = dirname7(attrs.filePath);
+    const dir = dirname8(attrs.filePath);
     if (!filesPerDir.has(dir)) {
       filesPerDir.set(dir, /* @__PURE__ */ new Set());
     }
@@ -4009,8 +4497,8 @@ function getDirectoryStats2(graph) {
   graph.forEachEdge((edge, attrs, source, target) => {
     const sourceAttrs = graph.getNodeAttributes(source);
     const targetAttrs = graph.getNodeAttributes(target);
-    const sourceDir = dirname7(sourceAttrs.filePath);
-    const targetDir = dirname7(targetAttrs.filePath);
+    const sourceDir = dirname8(sourceAttrs.filePath);
+    const targetDir = dirname8(targetAttrs.filePath);
     if (sourceDir !== targetDir) {
       if (!dirEdges.has(sourceDir)) {
         dirEdges.set(sourceDir, { in: 0, out: 0 });
@@ -4091,7 +4579,7 @@ function detectClusters(graph) {
   const dirFiles = /* @__PURE__ */ new Map();
   const fileEdges = /* @__PURE__ */ new Map();
   graph.forEachNode((node, attrs) => {
-    const dir = dirname7(attrs.filePath);
+    const dir = dirname8(attrs.filePath);
     if (!dirFiles.has(dir)) {
       dirFiles.set(dir, /* @__PURE__ */ new Set());
     }
@@ -4145,8 +4633,8 @@ function inferClusterName(files) {
   if (sortedWords.length > 0 && sortedWords[0][1] > 1) {
     return capitalizeFirst2(sortedWords[0][0]);
   }
-  const commonDir = dirname7(files[0]);
-  if (files.every((f) => dirname7(f) === commonDir)) {
+  const commonDir = dirname8(files[0]);
+  if (files.every((f) => dirname8(f) === commonDir)) {
     return capitalizeFirst2(commonDir.split("/").pop() || "Core");
   }
   return "Core";
@@ -4203,84 +4691,2378 @@ function generateDepwireUsage(projectRoot) {
   return output;
 }
 
-// src/docs/metadata.ts
-import { existsSync as existsSync6, readFileSync as readFileSync4, writeFileSync } from "fs";
-import { join as join9 } from "path";
-function loadMetadata(outputDir) {
-  const metadataPath = join9(outputDir, "metadata.json");
-  if (!existsSync6(metadataPath)) {
-    return null;
-  }
-  try {
-    const content = readFileSync4(metadataPath, "utf-8");
-    return JSON.parse(content);
-  } catch (err) {
-    console.error("Failed to load metadata:", err);
-    return null;
-  }
-}
-function saveMetadata(outputDir, metadata) {
-  const metadataPath = join9(outputDir, "metadata.json");
-  writeFileSync(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+// src/docs/files.ts
+import { dirname as dirname9, basename as basename3 } from "path";
+function generateFiles(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount5(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("File Catalog");
+  output += "Complete catalog of every file in the project with key metrics.\n\n";
+  output += header("File Summary", 2);
+  output += generateFileSummaryTable(graph);
+  output += header("Directory Breakdown", 2);
+  output += generateDirectoryBreakdown(graph);
+  output += header("File Size Distribution", 2);
+  output += generateFileSizeDistribution(graph);
+  output += header("Orphan Files", 2);
+  output += generateOrphanFiles(graph);
+  output += header("Hub Files", 2);
+  output += generateHubFiles2(graph);
+  return output;
 }
-function createMetadata(version, projectPath, fileCount, symbolCount, edgeCount, docTypes) {
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const documents = {};
-  for (const docType of docTypes) {
-    const fileName = docType === "architecture" ? "ARCHITECTURE.md" : docType === "conventions" ? "CONVENTIONS.md" : docType === "dependencies" ? "DEPENDENCIES.md" : docType === "onboarding" ? "ONBOARDING.md" : `${docType.toUpperCase()}.md`;
-    documents[docType] = {
-      generated_at: now,
-      file: fileName
-    };
-  }
-  return {
-    version,
-    generated_at: now,
-    project_path: projectPath,
-    file_count: fileCount,
-    symbol_count: symbolCount,
-    edge_count: edgeCount,
-    documents
-  };
+function getFileCount5(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
 }
-function updateMetadata(existing, docTypes, fileCount, symbolCount, edgeCount) {
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  for (const docType of docTypes) {
-    if (existing.documents[docType]) {
-      existing.documents[docType].generated_at = now;
+function getFileStats2(graph) {
+  const fileMap = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (!fileMap.has(attrs.filePath)) {
+      fileMap.set(attrs.filePath, {
+        filePath: attrs.filePath,
+        language: getLanguageFromPath(attrs.filePath),
+        symbolCount: 0,
+        importCount: 0,
+        exportedSymbolCount: 0,
+        incomingConnections: 0,
+        outgoingConnections: 0,
+        totalConnections: 0,
+        maxLine: 0
+      });
     }
-  }
-  existing.file_count = fileCount;
-  existing.symbol_count = symbolCount;
-  existing.edge_count = edgeCount;
-  existing.generated_at = now;
-  return existing;
-}
-
-// src/docs/generator.ts
-async function generateDocs(graph, projectRoot, version, parseTime, options) {
-  const startTime = Date.now();
-  const generated = [];
-  const errors = [];
-  try {
-    if (!existsSync7(options.outputDir)) {
-      mkdirSync(options.outputDir, { recursive: true });
-      if (options.verbose) {
-        console.log(`Created output directory: ${options.outputDir}`);
-      }
+    const stats = fileMap.get(attrs.filePath);
+    stats.symbolCount++;
+    if (attrs.exported && attrs.name !== "default") {
+      stats.exportedSymbolCount++;
+    }
+    if (attrs.kind === "import") {
+      stats.importCount++;
+    }
+    if (attrs.endLine > stats.maxLine) {
+      stats.maxLine = attrs.endLine;
+    }
+  });
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceStats = fileMap.get(sourceAttrs.filePath);
+      const targetStats = fileMap.get(targetAttrs.filePath);
+      if (sourceStats) {
+        sourceStats.outgoingConnections++;
+      }
+      if (targetStats) {
+        targetStats.incomingConnections++;
+      }
+    }
+  });
+  fileMap.forEach((stats) => {
+    stats.totalConnections = stats.incomingConnections + stats.outgoingConnections;
+  });
+  return Array.from(fileMap.values());
+}
+function getLanguageFromPath(filePath) {
+  const ext = filePath.toLowerCase();
+  if (ext.endsWith(".ts") || ext.endsWith(".tsx")) return "TypeScript";
+  if (ext.endsWith(".js") || ext.endsWith(".jsx") || ext.endsWith(".mjs") || ext.endsWith(".cjs")) return "JavaScript";
+  if (ext.endsWith(".py")) return "Python";
+  if (ext.endsWith(".go")) return "Go";
+  return "Other";
+}
+function generateFileSummaryTable(graph) {
+  const fileStats = getFileStats2(graph);
+  if (fileStats.length === 0) {
+    return "No files detected.\n\n";
+  }
+  fileStats.sort((a, b) => a.filePath.localeCompare(b.filePath));
+  const headers = ["File", "Language", "Symbols", "Imports", "Exports", "Connections", "Lines"];
+  const rows = fileStats.map((f) => [
+    `\`${f.filePath}\``,
+    f.language,
+    formatNumber(f.symbolCount),
+    formatNumber(f.importCount),
+    formatNumber(f.exportedSymbolCount),
+    formatNumber(f.totalConnections),
+    formatNumber(f.maxLine)
+  ]);
+  return table(headers, rows);
+}
+function generateDirectoryBreakdown(graph) {
+  const fileStats = getFileStats2(graph);
+  const dirMap = /* @__PURE__ */ new Map();
+  for (const file of fileStats) {
+    const dir = dirname9(file.filePath);
+    const topDir = dir === "." ? "." : dir.split("/")[0];
+    if (!dirMap.has(topDir)) {
+      dirMap.set(topDir, {
+        fileCount: 0,
+        symbolCount: 0,
+        mostConnectedFile: "",
+        maxConnections: 0
+      });
+    }
+    const dirStats = dirMap.get(topDir);
+    dirStats.fileCount++;
+    dirStats.symbolCount += file.symbolCount;
+    if (file.totalConnections > dirStats.maxConnections) {
+      dirStats.maxConnections = file.totalConnections;
+      dirStats.mostConnectedFile = basename3(file.filePath);
+    }
+  }
+  if (dirMap.size === 0) {
+    return "No directories detected.\n\n";
+  }
+  let output = "";
+  const sortedDirs = Array.from(dirMap.entries()).sort((a, b) => b[1].fileCount - a[1].fileCount);
+  for (const [dir, stats] of sortedDirs) {
+    output += `**${dir === "." ? "Root" : dir}/**
+
+`;
+    output += `- **Files:** ${formatNumber(stats.fileCount)}
+`;
+    output += `- **Symbols:** ${formatNumber(stats.symbolCount)}
+`;
+    output += `- **Most Connected:** \`${stats.mostConnectedFile}\` (${formatNumber(stats.maxConnections)} connections)
+
+`;
+  }
+  return output;
+}
+function generateFileSizeDistribution(graph) {
+  const fileStats = getFileStats2(graph);
+  if (fileStats.length === 0) {
+    return "No files detected.\n\n";
+  }
+  const bySymbols = [...fileStats].sort((a, b) => b.symbolCount - a.symbolCount);
+  let output = "";
+  output += "**Largest Files (by symbol count):**\n\n";
+  const largest = bySymbols.slice(0, 10);
+  const headers1 = ["File", "Symbols", "Lines"];
+  const rows1 = largest.map((f) => [
+    `\`${f.filePath}\``,
+    formatNumber(f.symbolCount),
+    formatNumber(f.maxLine)
+  ]);
+  output += table(headers1, rows1);
+  if (bySymbols.length > 10) {
+    output += "**Smallest Files (by symbol count):**\n\n";
+    const smallest = bySymbols.slice(-10).reverse();
+    const headers2 = ["File", "Symbols", "Lines"];
+    const rows2 = smallest.map((f) => [
+      `\`${f.filePath}\``,
+      formatNumber(f.symbolCount),
+      formatNumber(f.maxLine)
+    ]);
+    output += table(headers2, rows2);
+  }
+  const avgSymbols = Math.round(fileStats.reduce((sum, f) => sum + f.symbolCount, 0) / fileStats.length);
+  const avgLines = Math.round(fileStats.reduce((sum, f) => sum + f.maxLine, 0) / fileStats.length);
+  output += `**Average File Size:**
+
+`;
+  output += `- Symbols per file: ${formatNumber(avgSymbols)}
+`;
+  output += `- Lines per file: ${formatNumber(avgLines)}
+
+`;
+  return output;
+}
+function generateOrphanFiles(graph) {
+  const fileStats = getFileStats2(graph);
+  const orphans = fileStats.filter((f) => f.totalConnections === 0);
+  if (orphans.length === 0) {
+    return "\u2705 No orphan files detected. All files are connected.\n\n";
+  }
+  let output = `Found ${orphans.length} file${orphans.length === 1 ? "" : "s"} with zero connections:
+
+`;
+  output += unorderedList(orphans.map((f) => `\`${f.filePath}\` (${f.symbolCount} symbols)`));
+  output += "These files may be entry points, standalone scripts, or dead code.\n\n";
+  return output;
+}
+function generateHubFiles2(graph) {
+  const fileStats = getFileStats2(graph);
+  const hubs = fileStats.filter((f) => f.totalConnections > 0).sort((a, b) => b.totalConnections - a.totalConnections).slice(0, 10);
+  if (hubs.length === 0) {
+    return "No hub files detected.\n\n";
+  }
+  let output = "Files with the most connections (changing these breaks the most things):\n\n";
+  const headers = ["File", "Total Connections", "Incoming", "Outgoing", "Symbols"];
+  const rows = hubs.map((f) => [
+    `\`${f.filePath}\``,
+    formatNumber(f.totalConnections),
+    formatNumber(f.incomingConnections),
+    formatNumber(f.outgoingConnections),
+    formatNumber(f.symbolCount)
+  ]);
+  output += table(headers, rows);
+  return output;
+}
+
+// src/docs/api-surface.ts
+function generateApiSurface(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount6(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("API Surface");
+  output += "Every exported symbol in the project \u2014 the public API.\n\n";
+  output += header("Exports by File", 2);
+  output += generateExportsByFile(graph);
+  output += header("Exports by Kind", 2);
+  output += generateExportsByKind(graph);
+  output += header("Most-Used Exports", 2);
+  output += generateMostUsedExports(graph);
+  output += header("Unused Exports", 2);
+  output += generateUnusedExports(graph);
+  output += header("Re-exports / Barrel Files", 2);
+  output += generateReExports(graph);
+  return output;
+}
+function getFileCount6(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function getExportedSymbols(graph) {
+  const exports = [];
+  graph.forEachNode((node, attrs) => {
+    if (attrs.exported && attrs.name !== "__file__") {
+      const dependentCount = graph.inDegree(node);
+      exports.push({
+        name: attrs.name,
+        kind: attrs.kind,
+        filePath: attrs.filePath,
+        line: attrs.startLine,
+        dependentCount
+      });
+    }
+  });
+  return exports;
+}
+function generateExportsByFile(graph) {
+  const exports = getExportedSymbols(graph);
+  if (exports.length === 0) {
+    return "No exported symbols detected.\n\n";
+  }
+  const fileExports = /* @__PURE__ */ new Map();
+  for (const exp of exports) {
+    if (!fileExports.has(exp.filePath)) {
+      fileExports.set(exp.filePath, []);
+    }
+    fileExports.get(exp.filePath).push(exp);
+  }
+  const sortedFiles = Array.from(fileExports.entries()).sort((a, b) => b[1].length - a[1].length);
+  let output = "";
+  for (const [filePath, fileExports2] of sortedFiles) {
+    output += header(filePath, 3);
+    const sorted = fileExports2.sort((a, b) => b.dependentCount - a.dependentCount);
+    const items = sorted.map((exp) => {
+      const depInfo = exp.dependentCount > 0 ? ` \u2014 ${formatNumber(exp.dependentCount)} dependents` : "";
+      return `${code(exp.name)} (${exp.kind}, line ${exp.line})${depInfo}`;
+    });
+    output += unorderedList(items);
+  }
+  return output;
+}
+function generateExportsByKind(graph) {
+  const exports = getExportedSymbols(graph);
+  if (exports.length === 0) {
+    return "No exported symbols detected.\n\n";
+  }
+  const kindGroups = /* @__PURE__ */ new Map();
+  for (const exp of exports) {
+    if (!kindGroups.has(exp.kind)) {
+      kindGroups.set(exp.kind, []);
+    }
+    kindGroups.get(exp.kind).push(exp);
+  }
+  let output = "";
+  const sortedKinds = Array.from(kindGroups.entries()).sort((a, b) => b[1].length - a[1].length);
+  for (const [kind, kindExports] of sortedKinds) {
+    if (kind === "import" || kind === "export") continue;
+    output += `**${capitalizeKind(kind)}s (${kindExports.length}):**
+
+`;
+    const sorted = kindExports.sort((a, b) => b.dependentCount - a.dependentCount).slice(0, 20);
+    const items = sorted.map((exp) => {
+      return `${code(exp.name)} \u2014 ${code(exp.filePath)}:${exp.line}`;
+    });
+    output += unorderedList(items);
+  }
+  return output;
+}
+function capitalizeKind(kind) {
+  const map = {
+    function: "Function",
+    class: "Class",
+    variable: "Variable",
+    constant: "Constant",
+    type_alias: "Type",
+    interface: "Interface",
+    enum: "Enum",
+    import: "Import",
+    export: "Export",
+    method: "Method",
+    property: "Property",
+    decorator: "Decorator",
+    module: "Module"
+  };
+  return map[kind] || kind;
+}
+function generateMostUsedExports(graph) {
+  const exports = getExportedSymbols(graph);
+  if (exports.length === 0) {
+    return "No exported symbols detected.\n\n";
+  }
+  const sorted = exports.filter((exp) => exp.dependentCount > 0).sort((a, b) => b.dependentCount - a.dependentCount).slice(0, 20);
+  if (sorted.length === 0) {
+    return "No exports with dependents detected.\n\n";
+  }
+  let output = "Top 20 exports by dependent count \u2014 these are the most critical symbols:\n\n";
+  const items = sorted.map((exp) => {
+    return `${code(exp.name)} (${exp.kind}) \u2014 ${formatNumber(exp.dependentCount)} dependents \u2014 ${code(exp.filePath)}:${exp.line}`;
+  });
+  output += unorderedList(items);
+  return output;
+}
+function generateUnusedExports(graph) {
+  const exports = getExportedSymbols(graph);
+  if (exports.length === 0) {
+    return "No exported symbols detected.\n\n";
+  }
+  const unused = exports.filter((exp) => exp.dependentCount === 0 && exp.kind !== "export");
+  if (unused.length === 0) {
+    return "\u2705 No unused exports detected. All exports are used.\n\n";
+  }
+  let output = `Found ${unused.length} exported symbol${unused.length === 1 ? "" : "s"} with zero dependents:
+
+`;
+  const fileGroups = /* @__PURE__ */ new Map();
+  for (const exp of unused) {
+    if (!fileGroups.has(exp.filePath)) {
+      fileGroups.set(exp.filePath, []);
+    }
+    fileGroups.get(exp.filePath).push(exp);
+  }
+  for (const [filePath, fileExports] of fileGroups.entries()) {
+    output += `**${filePath}:**
+
+`;
+    const items = fileExports.map((exp) => `${code(exp.name)} (${exp.kind}, line ${exp.line})`);
+    output += unorderedList(items);
+  }
+  output += "These symbols may be part of the intended public API but are not currently used, or they may be dead code.\n\n";
+  return output;
+}
+function generateReExports(graph) {
+  const fileStats = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (!fileStats.has(attrs.filePath)) {
+      fileStats.set(attrs.filePath, {
+        exportCount: 0,
+        reExportCount: 0,
+        reExportSources: /* @__PURE__ */ new Set()
+      });
+    }
+    const stats = fileStats.get(attrs.filePath);
+    if (attrs.exported) {
+      stats.exportCount++;
+    }
+    if (attrs.kind === "export") {
+      stats.reExportCount++;
+    }
+  });
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.kind === "export" && sourceAttrs.filePath !== targetAttrs.filePath) {
+      const stats = fileStats.get(sourceAttrs.filePath);
+      if (stats) {
+        stats.reExportSources.add(targetAttrs.filePath);
+      }
+    }
+  });
+  const barrels = [];
+  for (const [filePath, stats] of fileStats.entries()) {
+    if (stats.reExportCount > 0 && stats.reExportCount >= stats.exportCount * 0.5) {
+      barrels.push({
+        filePath,
+        exportCount: stats.exportCount,
+        reExportCount: stats.reExportCount,
+        sources: Array.from(stats.reExportSources)
+      });
+    }
+  }
+  if (barrels.length === 0) {
+    return "No barrel files detected.\n\n";
+  }
+  let output = `Found ${barrels.length} barrel file${barrels.length === 1 ? "" : "s"} (files that primarily re-export from other files):
+
+`;
+  for (const barrel of barrels) {
+    output += header(barrel.filePath, 3);
+    output += `- **Total exports:** ${formatNumber(barrel.exportCount)}
+`;
+    output += `- **Re-exports:** ${formatNumber(barrel.reExportCount)}
+`;
+    if (barrel.sources.length > 0) {
+      output += `- **Sources:**
+
+`;
+      output += unorderedList(barrel.sources.map((s) => code(s)));
+    } else {
+      output += "\n";
+    }
+  }
+  return output;
+}
+
+// src/docs/errors.ts
+function generateErrors(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount7(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Error Handling Analysis");
+  output += "Analysis of error handling patterns and error-prone areas in the codebase.\n\n";
+  output += header("Error-Related Symbols", 2);
+  output += generateErrorRelatedSymbols(graph);
+  output += header("Custom Error Classes", 2);
+  output += generateCustomErrorClasses(graph);
+  output += header("Error-Prone Files", 2);
+  output += generateErrorProneFiles(graph);
+  output += header("Detected Patterns", 2);
+  output += generateErrorHandlingPatterns(graph);
+  output += header("Recommendations", 2);
+  output += generateRecommendations(graph);
+  return output;
+}
+function getFileCount7(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function getErrorRelatedSymbols(graph) {
+  const errorKeywords = [
+    "error",
+    "err",
+    "exception",
+    "throw",
+    "fail",
+    "invalid",
+    "not_found",
+    "notfound",
+    "unauthorized",
+    "forbidden",
+    "timeout",
+    "retry",
+    "catch",
+    "try"
+  ];
+  const symbols = [];
+  graph.forEachNode((node, attrs) => {
+    if (attrs.name === "__file__") return;
+    const nameLower = attrs.name.toLowerCase();
+    for (const keyword of errorKeywords) {
+      if (nameLower.includes(keyword)) {
+        let category = "error_handling";
+        if (nameLower.includes("retry") || nameLower.includes("timeout")) {
+          category = "retry_timeout";
+        } else if (nameLower.includes("invalid") || nameLower.includes("validate")) {
+          category = "validation";
+        } else if (nameLower.includes("unauthorized") || nameLower.includes("forbidden")) {
+          category = "auth_error";
+        } else if (nameLower.includes("notfound") || nameLower.includes("not_found")) {
+          category = "not_found";
+        }
+        symbols.push({
+          name: attrs.name,
+          kind: attrs.kind,
+          filePath: attrs.filePath,
+          line: attrs.startLine,
+          category
+        });
+        break;
+      }
+    }
+  });
+  return symbols;
+}
+function generateErrorRelatedSymbols(graph) {
+  const symbols = getErrorRelatedSymbols(graph);
+  if (symbols.length === 0) {
+    return "No error-related symbols detected.\n\n";
+  }
+  let output = `Found ${symbols.length} error-related symbol${symbols.length === 1 ? "" : "s"}:
+
+`;
+  const categories = /* @__PURE__ */ new Map();
+  for (const sym of symbols) {
+    if (!categories.has(sym.category)) {
+      categories.set(sym.category, []);
+    }
+    categories.get(sym.category).push(sym);
+  }
+  for (const [category, syms] of categories.entries()) {
+    output += `**${formatCategory(category)} (${syms.length}):**
+
+`;
+    const items = syms.slice(0, 10).map((s) => {
+      return `${code(s.name)} (${s.kind}) \u2014 ${code(s.filePath)}:${s.line}`;
+    });
+    output += unorderedList(items);
+    if (syms.length > 10) {
+      output += `... and ${syms.length - 10} more.
+
+`;
+    }
+  }
+  return output;
+}
+function formatCategory(category) {
+  const map = {
+    "error_handling": "Error Handling",
+    "retry_timeout": "Retry / Timeout",
+    "validation": "Validation",
+    "auth_error": "Authentication Errors",
+    "not_found": "Not Found Errors"
+  };
+  return map[category] || category;
+}
+function generateCustomErrorClasses(graph) {
+  const errorClasses = [];
+  graph.forEachNode((node, attrs) => {
+    if (attrs.kind === "class") {
+      const nameLower = attrs.name.toLowerCase();
+      if (nameLower.includes("error") || nameLower.includes("exception")) {
+        errorClasses.push({
+          name: attrs.name,
+          filePath: attrs.filePath,
+          line: attrs.startLine
+        });
+      }
+    }
+  });
+  if (errorClasses.length === 0) {
+    return "No custom error classes detected.\n\n";
+  }
+  let output = `Found ${errorClasses.length} custom error class${errorClasses.length === 1 ? "" : "es"}:
+
+`;
+  const items = errorClasses.map((c) => {
+    return `${code(c.name)} \u2014 ${code(c.filePath)}:${c.line}`;
+  });
+  output += unorderedList(items);
+  return output;
+}
+function generateErrorProneFiles(graph) {
+  const fileStats = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (!fileStats.has(attrs.filePath)) {
+      fileStats.set(attrs.filePath, {
+        connectionCount: 0,
+        errorSymbolCount: 0,
+        symbolCount: 0
+      });
+    }
+    fileStats.get(attrs.filePath).symbolCount++;
+  });
+  const errorSymbols = getErrorRelatedSymbols(graph);
+  for (const sym of errorSymbols) {
+    const stats = fileStats.get(sym.filePath);
+    if (stats) {
+      stats.errorSymbolCount++;
+    }
+  }
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceStats = fileStats.get(sourceAttrs.filePath);
+      const targetStats = fileStats.get(targetAttrs.filePath);
+      if (sourceStats) sourceStats.connectionCount++;
+      if (targetStats) targetStats.connectionCount++;
+    }
+  });
+  const errorProneFiles = [];
+  for (const [filePath, stats] of fileStats.entries()) {
+    if (stats.connectionCount > 5) {
+      const riskScore = stats.connectionCount * (1 + stats.errorSymbolCount * 0.5);
+      errorProneFiles.push({
+        filePath,
+        connectionCount: stats.connectionCount,
+        errorSymbolCount: stats.errorSymbolCount,
+        riskScore
+      });
+    }
+  }
+  errorProneFiles.sort((a, b) => b.riskScore - a.riskScore);
+  if (errorProneFiles.length === 0) {
+    return "No high-risk files detected.\n\n";
+  }
+  let output = "Files with high complexity and error-related code (riskiest to modify):\n\n";
+  const headers = ["File", "Connections", "Error Symbols", "Risk Score"];
+  const rows = errorProneFiles.slice(0, 15).map((f) => [
+    `\`${f.filePath}\``,
+    formatNumber(f.connectionCount),
+    formatNumber(f.errorSymbolCount),
+    f.riskScore.toFixed(1)
+  ]);
+  output += table(headers, rows);
+  return output;
+}
+function generateErrorHandlingPatterns(graph) {
+  const patterns = {
+    custom_errors: 0,
+    retry: 0,
+    timeout: 0,
+    validation: 0,
+    guard: 0
+  };
+  graph.forEachNode((node, attrs) => {
+    const nameLower = attrs.name.toLowerCase();
+    if (attrs.kind === "class" && (nameLower.includes("error") || nameLower.includes("exception"))) {
+      patterns.custom_errors++;
+    }
+    if (nameLower.includes("retry") || nameLower.includes("attempt")) {
+      patterns.retry++;
+    }
+    if (nameLower.includes("timeout")) {
+      patterns.timeout++;
+    }
+    if (nameLower.includes("validate") || nameLower.includes("validator") || nameLower.includes("check")) {
+      patterns.validation++;
+    }
+    if (nameLower.includes("guard") || nameLower.startsWith("is") || nameLower.startsWith("has")) {
+      patterns.guard++;
+    }
+  });
+  const detectedPatterns = Object.entries(patterns).filter(([, count]) => count > 0);
+  if (detectedPatterns.length === 0) {
+    return "No error handling patterns detected.\n\n";
+  }
+  let output = "";
+  for (const [pattern, count] of detectedPatterns) {
+    const description = getPatternDescription2(pattern);
+    output += `- **${formatPatternName(pattern)}:** ${count} occurrences \u2014 ${description}
+`;
+  }
+  output += "\n";
+  return output;
+}
+function formatPatternName(pattern) {
+  const map = {
+    custom_errors: "Custom Error Hierarchy",
+    retry: "Retry Pattern",
+    timeout: "Timeout Handling",
+    validation: "Input Validation",
+    guard: "Guard Clauses"
+  };
+  return map[pattern] || pattern;
+}
+function getPatternDescription2(pattern) {
+  const map = {
+    custom_errors: "Custom error classes for domain-specific exceptions",
+    retry: "Retry logic for transient failures",
+    timeout: "Timeout handling for long-running operations",
+    validation: "Input validation to prevent errors",
+    guard: "Guard clauses to check preconditions"
+  };
+  return map[pattern] || "";
+}
+function generateRecommendations(graph) {
+  const recommendations = [];
+  const fileStats = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (!fileStats.has(attrs.filePath)) {
+      fileStats.set(attrs.filePath, {
+        connectionCount: 0,
+        errorSymbolCount: 0
+      });
+    }
+  });
+  const errorSymbols = getErrorRelatedSymbols(graph);
+  for (const sym of errorSymbols) {
+    const stats = fileStats.get(sym.filePath);
+    if (stats) {
+      stats.errorSymbolCount++;
+    }
+  }
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceStats = fileStats.get(sourceAttrs.filePath);
+      const targetStats = fileStats.get(targetAttrs.filePath);
+      if (sourceStats) sourceStats.connectionCount++;
+      if (targetStats) targetStats.connectionCount++;
+    }
+  });
+  const needsErrorHandling = [];
+  for (const [filePath, stats] of fileStats.entries()) {
+    if (stats.connectionCount > 10 && stats.errorSymbolCount === 0) {
+      needsErrorHandling.push(filePath);
+    }
+  }
+  if (needsErrorHandling.length > 0) {
+    recommendations.push(`**Add error handling to high-connection files:** ${needsErrorHandling.slice(0, 5).map((f) => code(f)).join(", ")}`);
+  }
+  const errorClasses = [];
+  graph.forEachNode((node, attrs) => {
+    if (attrs.kind === "class") {
+      const nameLower = attrs.name.toLowerCase();
+      if (nameLower.includes("error") || nameLower.includes("exception")) {
+        const dependents = graph.inDegree(node);
+        if (dependents === 0) {
+          errorClasses.push(attrs.name);
+        }
+      }
+    }
+  });
+  if (errorClasses.length > 0) {
+    recommendations.push(`**Unused error classes detected:** ${errorClasses.slice(0, 5).map((c) => code(c)).join(", ")} \u2014 Consider removing or documenting why they exist`);
+  }
+  if (recommendations.length === 0) {
+    return "\u2705 No specific recommendations. Error handling appears well-distributed.\n\n";
+  }
+  return unorderedList(recommendations);
+}
+
+// src/docs/tests.ts
+import { basename as basename4, dirname as dirname10 } from "path";
+function generateTests(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount8(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Test Analysis");
+  output += "Test file inventory and coverage mapping.\n\n";
+  output += header("Test File Inventory", 2);
+  output += generateTestFileInventory(graph);
+  output += header("Test-to-Source Mapping", 2);
+  output += generateTestToSourceMapping(graph);
+  output += header("Untested Files", 2);
+  output += generateUntestedFiles(graph);
+  output += header("Test Coverage Map", 2);
+  output += generateTestCoverageMap(graph);
+  output += header("Test Statistics", 2);
+  output += generateTestStatistics(graph);
+  return output;
+}
+function getFileCount8(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function isTestFile(filePath) {
+  const fileName = basename4(filePath).toLowerCase();
+  const dirPath = dirname10(filePath).toLowerCase();
+  if (dirPath.includes("test") || dirPath.includes("spec") || dirPath.includes("__tests__")) {
+    return true;
+  }
+  if (fileName.includes(".test.") || fileName.includes(".spec.") || fileName.includes("_test.") || fileName.includes("_spec.")) {
+    return true;
+  }
+  return false;
+}
+function getTestFiles(graph) {
+  const testFiles = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (isTestFile(attrs.filePath)) {
+      if (!testFiles.has(attrs.filePath)) {
+        testFiles.set(attrs.filePath, {
+          filePath: attrs.filePath,
+          language: getLanguageFromPath2(attrs.filePath),
+          symbolCount: 0,
+          functionCount: 0
+        });
+      }
+      const info = testFiles.get(attrs.filePath);
+      info.symbolCount++;
+      if (attrs.kind === "function" || attrs.kind === "method") {
+        info.functionCount++;
+      }
+    }
+  });
+  return Array.from(testFiles.values());
+}
+function getLanguageFromPath2(filePath) {
+  const ext = filePath.toLowerCase();
+  if (ext.endsWith(".ts") || ext.endsWith(".tsx")) return "TypeScript";
+  if (ext.endsWith(".js") || ext.endsWith(".jsx") || ext.endsWith(".mjs") || ext.endsWith(".cjs")) return "JavaScript";
+  if (ext.endsWith(".py")) return "Python";
+  if (ext.endsWith(".go")) return "Go";
+  return "Other";
+}
+function generateTestFileInventory(graph) {
+  const testFiles = getTestFiles(graph);
+  if (testFiles.length === 0) {
+    return "No test files detected.\n\n";
+  }
+  let output = `Found ${testFiles.length} test file${testFiles.length === 1 ? "" : "s"}:
+
+`;
+  testFiles.sort((a, b) => a.filePath.localeCompare(b.filePath));
+  const headers = ["Test File", "Language", "Symbols", "Functions"];
+  const rows = testFiles.map((t) => [
+    `\`${t.filePath}\``,
+    t.language,
+    formatNumber(t.symbolCount),
+    formatNumber(t.functionCount)
+  ]);
+  output += table(headers, rows);
+  return output;
+}
+function matchTestToSource(testFile) {
+  const testFileName = basename4(testFile);
+  const testDir = dirname10(testFile);
+  let sourceFileName = testFileName.replace(/\.test\./g, ".").replace(/\.spec\./g, ".").replace(/_test\./g, ".").replace(/_spec\./g, ".");
+  const possiblePaths = [];
+  possiblePaths.push(testDir + "/" + sourceFileName);
+  if (testDir.endsWith("/test") || testDir.endsWith("/tests") || testDir.endsWith("/__tests__")) {
+    const parentDir = dirname10(testDir);
+    possiblePaths.push(parentDir + "/" + sourceFileName);
+  }
+  if (testDir.includes("test")) {
+    const srcDir = testDir.replace(/test[s]?/g, "src");
+    possiblePaths.push(srcDir + "/" + sourceFileName);
+  }
+  for (const path2 of possiblePaths) {
+    if (!isTestFile(path2)) {
+      return path2;
+    }
+  }
+  return null;
+}
+function generateTestToSourceMapping(graph) {
+  const testFiles = getTestFiles(graph);
+  if (testFiles.length === 0) {
+    return "No test files detected.\n\n";
+  }
+  const allFiles = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    allFiles.add(attrs.filePath);
+  });
+  let output = "";
+  let mappedCount = 0;
+  const mappings = [];
+  for (const testFile of testFiles) {
+    const sourceFile = matchTestToSource(testFile.filePath);
+    const exists = sourceFile && allFiles.has(sourceFile);
+    mappings.push({
+      test: testFile.filePath,
+      source: exists ? sourceFile : null
+    });
+    if (exists) {
+      mappedCount++;
+    }
+  }
+  output += `Matched ${mappedCount} of ${testFiles.length} test files to source files:
+
+`;
+  for (const mapping of mappings) {
+    if (mapping.source) {
+      output += `- ${code(mapping.source)} \u2190 ${code(mapping.test)}
+`;
+    }
+  }
+  output += "\n";
+  const unmapped = mappings.filter((m) => !m.source);
+  if (unmapped.length > 0) {
+    output += `**Unmapped test files (${unmapped.length}):**
+
+`;
+    output += unorderedList(unmapped.map((m) => code(m.test)));
+  }
+  return output;
+}
+function generateUntestedFiles(graph) {
+  const testFiles = getTestFiles(graph);
+  const sourceFiles = [];
+  const allFiles = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    allFiles.add(attrs.filePath);
+  });
+  for (const file of allFiles) {
+    if (!isTestFile(file)) {
+      sourceFiles.push(file);
+    }
+  }
+  if (sourceFiles.length === 0) {
+    return "No source files detected.\n\n";
+  }
+  const testedFiles = /* @__PURE__ */ new Set();
+  for (const testFile of testFiles) {
+    const sourceFile = matchTestToSource(testFile.filePath);
+    if (sourceFile && allFiles.has(sourceFile)) {
+      testedFiles.add(sourceFile);
+    }
+  }
+  const untested = sourceFiles.filter((f) => !testedFiles.has(f));
+  if (untested.length === 0) {
+    return "\u2705 All source files have matching test files.\n\n";
+  }
+  const fileConnections = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      fileConnections.set(sourceAttrs.filePath, (fileConnections.get(sourceAttrs.filePath) || 0) + 1);
+      fileConnections.set(targetAttrs.filePath, (fileConnections.get(targetAttrs.filePath) || 0) + 1);
+    }
+  });
+  const untestedWithConnections = untested.map((f) => ({
+    filePath: f,
+    connections: fileConnections.get(f) || 0
+  })).sort((a, b) => b.connections - a.connections);
+  let output = `\u26A0\uFE0F Found ${untested.length} source file${untested.length === 1 ? "" : "s"} without matching test files:
+
+`;
+  const headers = ["File", "Connections", "Priority"];
+  const rows = untestedWithConnections.slice(0, 20).map((f) => {
+    const priority = f.connections > 10 ? "\u{1F534} High" : f.connections > 5 ? "\u{1F7E1} Medium" : "\u{1F7E2} Low";
+    return [
+      `\`${f.filePath}\``,
+      formatNumber(f.connections),
+      priority
+    ];
+  });
+  output += table(headers, rows);
+  if (untested.length > 20) {
+    output += `... and ${untested.length - 20} more.
+
+`;
+  }
+  return output;
+}
+function generateTestCoverageMap(graph) {
+  const testFiles = getTestFiles(graph);
+  const allFiles = /* @__PURE__ */ new Set();
+  const sourceFiles = [];
+  graph.forEachNode((node, attrs) => {
+    allFiles.add(attrs.filePath);
+  });
+  for (const file of allFiles) {
+    if (!isTestFile(file)) {
+      sourceFiles.push(file);
+    }
+  }
+  if (sourceFiles.length === 0) {
+    return "No source files detected.\n\n";
+  }
+  const mappings = [];
+  const testedFiles = /* @__PURE__ */ new Map();
+  for (const testFile of testFiles) {
+    const sourceFile = matchTestToSource(testFile.filePath);
+    if (sourceFile && allFiles.has(sourceFile)) {
+      testedFiles.set(sourceFile, testFile.filePath);
+    }
+  }
+  const fileSymbols = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    fileSymbols.set(attrs.filePath, (fileSymbols.get(attrs.filePath) || 0) + 1);
+  });
+  for (const sourceFile of sourceFiles) {
+    const testFile = testedFiles.get(sourceFile);
+    mappings.push({
+      sourceFile,
+      hasTest: !!testFile,
+      testFile: testFile || null,
+      symbolCount: fileSymbols.get(sourceFile) || 0
+    });
+  }
+  mappings.sort((a, b) => a.sourceFile.localeCompare(b.sourceFile));
+  const headers = ["Source File", "Has Test?", "Test File", "Symbols"];
+  const rows = mappings.slice(0, 30).map((m) => [
+    `\`${m.sourceFile}\``,
+    m.hasTest ? "\u2705" : "\u274C",
+    m.testFile ? `\`${basename4(m.testFile)}\`` : "-",
+    formatNumber(m.symbolCount)
+  ]);
+  let output = table(headers, rows);
+  if (mappings.length > 30) {
+    output += `... and ${mappings.length - 30} more files.
+
+`;
+  }
+  return output;
+}
+function generateTestStatistics(graph) {
+  const testFiles = getTestFiles(graph);
+  const allFiles = /* @__PURE__ */ new Set();
+  const sourceFiles = [];
+  graph.forEachNode((node, attrs) => {
+    allFiles.add(attrs.filePath);
+  });
+  for (const file of allFiles) {
+    if (!isTestFile(file)) {
+      sourceFiles.push(file);
+    }
+  }
+  const testedFiles = /* @__PURE__ */ new Set();
+  for (const testFile of testFiles) {
+    const sourceFile = matchTestToSource(testFile.filePath);
+    if (sourceFile && allFiles.has(sourceFile)) {
+      testedFiles.add(sourceFile);
+    }
+  }
+  let output = "";
+  output += `- **Total test files:** ${formatNumber(testFiles.length)}
+`;
+  output += `- **Total source files:** ${formatNumber(sourceFiles.length)}
+`;
+  output += `- **Source files with tests:** ${formatNumber(testedFiles.size)} (${formatPercent(testedFiles.size, sourceFiles.length)})
+`;
+  output += `- **Source files without tests:** ${formatNumber(sourceFiles.length - testedFiles.size)} (${formatPercent(sourceFiles.length - testedFiles.size, sourceFiles.length)})
+`;
+  const dirTestCoverage = /* @__PURE__ */ new Map();
+  for (const sourceFile of sourceFiles) {
+    const dir = dirname10(sourceFile).split("/")[0];
+    if (!dirTestCoverage.has(dir)) {
+      dirTestCoverage.set(dir, { total: 0, tested: 0 });
+    }
+    dirTestCoverage.get(dir).total++;
+    if (testedFiles.has(sourceFile)) {
+      dirTestCoverage.get(dir).tested++;
+    }
+  }
+  if (dirTestCoverage.size > 1) {
+    output += "\n**Coverage by directory:**\n\n";
+    const sortedDirs = Array.from(dirTestCoverage.entries()).sort((a, b) => b[1].total - a[1].total);
+    for (const [dir, coverage] of sortedDirs) {
+      const percent = formatPercent(coverage.tested, coverage.total);
+      output += `- **${dir}/**: ${coverage.tested}/${coverage.total} files (${percent})
+`;
+    }
+  }
+  output += "\n";
+  return output;
+}
+
+// src/docs/history.ts
+import { dirname as dirname11 } from "path";
+import { execSync } from "child_process";
+function generateHistory(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount9(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Development History");
+  output += "Git history combined with graph analysis showing feature evolution.\n\n";
+  const hasGit = isGitAvailable(projectRoot);
+  if (!hasGit) {
+    output += "\u26A0\uFE0F **Git history not available.** This project is not a git repository or git is not installed.\n\n";
+    output += "Showing graph-based analysis only:\n\n";
+  }
+  if (hasGit) {
+    output += header("Development Timeline", 2);
+    output += generateDevelopmentTimeline(projectRoot);
+  }
+  if (hasGit) {
+    output += header("File Change Frequency (Churn)", 2);
+    output += generateFileChurn(projectRoot, graph);
+  }
+  if (hasGit) {
+    output += header("Feature Timeline", 2);
+    output += generateFeatureTimeline(projectRoot);
+  }
+  if (hasGit) {
+    output += header("File Age Analysis", 2);
+    output += generateFileAgeAnalysis(projectRoot, graph);
+  }
+  if (hasGit) {
+    output += header("Contributors", 2);
+    output += generateContributors(projectRoot);
+  }
+  output += header("Feature Clusters (Graph-Based)", 2);
+  output += generateFeatureClusters(graph);
+  return output;
+}
+function getFileCount9(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function isGitAvailable(projectRoot) {
+  try {
+    execSync("git rev-parse --git-dir", {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      timeout: 5e3,
+      stdio: "pipe"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function executeGitCommand(projectRoot, command) {
+  try {
+    return execSync(command, {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      timeout: 1e4,
+      stdio: "pipe"
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+function generateDevelopmentTimeline(projectRoot) {
+  const log = executeGitCommand(projectRoot, 'git log --format="%ai" --all --no-merges');
+  if (!log) {
+    return "Unable to retrieve git log.\n\n";
+  }
+  const dates = log.split("\n").filter((d) => d.length > 0);
+  if (dates.length === 0) {
+    return "No commits found.\n\n";
+  }
+  const firstCommit = new Date(dates[dates.length - 1]);
+  const lastCommit = new Date(dates[0]);
+  const ageInDays = Math.floor((lastCommit.getTime() - firstCommit.getTime()) / (1e3 * 60 * 60 * 24));
+  const ageInMonths = Math.floor(ageInDays / 30);
+  let output = "";
+  output += `- **First commit:** ${firstCommit.toISOString().split("T")[0]}
+`;
+  output += `- **Last commit:** ${lastCommit.toISOString().split("T")[0]}
+`;
+  output += `- **Project age:** ${ageInMonths} months (${ageInDays} days)
+`;
+  output += `- **Total commits:** ${formatNumber(dates.length)}
+`;
+  const commitsPerMonth = ageInMonths > 0 ? (dates.length / ageInMonths).toFixed(1) : dates.length.toString();
+  output += `- **Average activity:** ${commitsPerMonth} commits/month
+`;
+  output += "\n";
+  return output;
+}
+function generateFileChurn(projectRoot, graph) {
+  const churnOutput = executeGitCommand(
+    projectRoot,
+    'git log --all --name-only --format="" | sort | uniq -c | sort -rn | head -20'
+  );
+  if (!churnOutput) {
+    return "Unable to retrieve file churn data.\n\n";
+  }
+  const lines = churnOutput.split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length === 0) {
+    return "No file churn data available.\n\n";
+  }
+  const churnData = [];
+  for (const line of lines) {
+    const match = line.trim().match(/^(\d+)\s+(.+)$/);
+    if (match) {
+      const changes = parseInt(match[1], 10);
+      const file = match[2].trim();
+      if (file && file.length > 0 && !file.startsWith(".")) {
+        churnData.push({ file, changes });
+      }
+    }
+  }
+  if (churnData.length === 0) {
+    return "No valid file churn data.\n\n";
+  }
+  const fileConnections = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      fileConnections.set(sourceAttrs.filePath, (fileConnections.get(sourceAttrs.filePath) || 0) + 1);
+      fileConnections.set(targetAttrs.filePath, (fileConnections.get(targetAttrs.filePath) || 0) + 1);
+    }
+  });
+  let output = "Top 20 most-changed files:\n\n";
+  const headers = ["File", "Changes", "Connections", "Risk"];
+  const rows = churnData.slice(0, 20).map((item) => {
+    const connections = fileConnections.get(item.file) || 0;
+    let risk = "\u{1F7E2} Low";
+    if (item.changes > 50 && connections > 10) {
+      risk = "\u{1F534} High";
+    } else if (item.changes > 20 && connections > 5) {
+      risk = "\u{1F7E1} Medium";
+    } else if (item.changes > 50 || connections > 10) {
+      risk = "\u{1F7E1} Medium";
+    }
+    return [
+      `\`${item.file}\``,
+      formatNumber(item.changes),
+      formatNumber(connections),
+      risk
+    ];
+  });
+  output += table(headers, rows);
+  output += "**Risk levels:**\n\n";
+  output += "- \u{1F534} High churn + high connections = risky hotspot (break often, affect many)\n";
+  output += "- \u{1F7E1} High churn + low connections = actively developed but isolated\n";
+  output += "- \u{1F7E2} Low churn + high connections = stable foundation\n\n";
+  return output;
+}
+function generateFeatureTimeline(projectRoot) {
+  const log = executeGitCommand(projectRoot, "git log --oneline --all --no-merges");
+  if (!log) {
+    return "Unable to retrieve commit log.\n\n";
+  }
+  const commits = log.split("\n").filter((c) => c.length > 0);
+  if (commits.length === 0) {
+    return "No commits found.\n\n";
+  }
+  const categories = {
+    features: 0,
+    fixes: 0,
+    refactors: 0,
+    other: 0
+  };
+  const featureKeywords = ["feat", "add", "new", "implement", "create"];
+  const fixKeywords = ["fix", "bug", "patch", "resolve"];
+  const refactorKeywords = ["refactor", "cleanup", "restructure", "improve"];
+  for (const commit of commits) {
+    const messageLower = commit.toLowerCase();
+    if (featureKeywords.some((kw) => messageLower.includes(kw))) {
+      categories.features++;
+    } else if (fixKeywords.some((kw) => messageLower.includes(kw))) {
+      categories.fixes++;
+    } else if (refactorKeywords.some((kw) => messageLower.includes(kw))) {
+      categories.refactors++;
+    } else {
+      categories.other++;
+    }
+  }
+  let output = "Commit breakdown by type:\n\n";
+  output += `- **Features:** ${formatNumber(categories.features)} commits (${(categories.features / commits.length * 100).toFixed(1)}%)
+`;
+  output += `- **Bug fixes:** ${formatNumber(categories.fixes)} commits (${(categories.fixes / commits.length * 100).toFixed(1)}%)
+`;
+  output += `- **Refactors:** ${formatNumber(categories.refactors)} commits (${(categories.refactors / commits.length * 100).toFixed(1)}%)
+`;
+  output += `- **Other:** ${formatNumber(categories.other)} commits (${(categories.other / commits.length * 100).toFixed(1)}%)
+`;
+  output += "\n";
+  return output;
+}
+function generateFileAgeAnalysis(projectRoot, graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  if (files.size === 0) {
+    return "No files to analyze.\n\n";
+  }
+  const fileAges = [];
+  const sampleFiles = Array.from(files).slice(0, 20);
+  for (const file of sampleFiles) {
+    const dateStr = executeGitCommand(
+      projectRoot,
+      `git log --format="%ai" --diff-filter=A -- "${file}" | tail -1`
+    );
+    if (dateStr) {
+      fileAges.push({
+        file,
+        date: new Date(dateStr)
+      });
+    }
+  }
+  if (fileAges.length === 0) {
+    return "Unable to determine file ages.\n\n";
+  }
+  fileAges.sort((a, b) => a.date.getTime() - b.date.getTime());
+  let output = "";
+  output += "**Oldest files (foundation):**\n\n";
+  const oldest = fileAges.slice(0, 5);
+  output += unorderedList(oldest.map((f) => {
+    return `${code(f.file)} \u2014 added ${f.date.toISOString().split("T")[0]}`;
+  }));
+  output += "**Newest files (recent features):**\n\n";
+  const newest = fileAges.slice(-5).reverse();
+  output += unorderedList(newest.map((f) => {
+    return `${code(f.file)} \u2014 added ${f.date.toISOString().split("T")[0]}`;
+  }));
+  return output;
+}
+function generateContributors(projectRoot) {
+  const contributors = executeGitCommand(projectRoot, "git shortlog -sn --all");
+  if (!contributors) {
+    return "Unable to retrieve contributor data.\n\n";
+  }
+  const lines = contributors.split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length === 0) {
+    return "No contributors found.\n\n";
+  }
+  let output = `Found ${lines.length} contributor${lines.length === 1 ? "" : "s"}:
+
+`;
+  const headers = ["Contributor", "Commits", "Percentage"];
+  const contributorData = [];
+  let totalCommits = 0;
+  for (const line of lines) {
+    const match = line.trim().match(/^(\d+)\s+(.+)$/);
+    if (match) {
+      const commits = parseInt(match[1], 10);
+      const name = match[2].trim();
+      contributorData.push({ name, commits });
+      totalCommits += commits;
+    }
+  }
+  const rows = contributorData.slice(0, 10).map((c) => [
+    c.name,
+    formatNumber(c.commits),
+    `${(c.commits / totalCommits * 100).toFixed(1)}%`
+  ]);
+  output += table(headers, rows);
+  if (contributorData.length > 10) {
+    output += `... and ${contributorData.length - 10} more contributors.
+
+`;
+  }
+  return output;
+}
+function generateFeatureClusters(graph) {
+  const dirFiles = /* @__PURE__ */ new Map();
+  const fileEdges = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    const dir = dirname11(attrs.filePath);
+    if (!dirFiles.has(dir)) {
+      dirFiles.set(dir, /* @__PURE__ */ new Set());
+    }
+    dirFiles.get(dir).add(attrs.filePath);
+  });
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceFile = graph.getNodeAttributes(source).filePath;
+    const targetFile = graph.getNodeAttributes(target).filePath;
+    if (sourceFile !== targetFile) {
+      if (!fileEdges.has(sourceFile)) {
+        fileEdges.set(sourceFile, /* @__PURE__ */ new Set());
+      }
+      fileEdges.get(sourceFile).add(targetFile);
+    }
+  });
+  const clusters = [];
+  for (const [dir, files] of dirFiles.entries()) {
+    if (dir === "." || files.size < 2) continue;
+    const fileArray = Array.from(files);
+    let internalEdgeCount = 0;
+    for (const file of fileArray) {
+      const targets = fileEdges.get(file);
+      if (targets) {
+        for (const target of targets) {
+          if (files.has(target)) {
+            internalEdgeCount++;
+          }
+        }
+      }
+    }
+    if (internalEdgeCount >= 2) {
+      const clusterName = inferClusterName2(fileArray, dir);
+      clusters.push({
+        name: clusterName,
+        files: fileArray,
+        internalEdges: internalEdgeCount
+      });
+    }
+  }
+  if (clusters.length === 0) {
+    return "No distinct feature clusters detected.\n\n";
+  }
+  clusters.sort((a, b) => b.internalEdges - a.internalEdges);
+  let output = `Detected ${clusters.length} feature cluster${clusters.length === 1 ? "" : "s"} (tightly-connected file groups):
+
+`;
+  for (const cluster of clusters.slice(0, 10)) {
+    output += `**${cluster.name}** (${cluster.files.length} files, ${cluster.internalEdges} internal connections):
+
+`;
+    const items = cluster.files.slice(0, 5).map((f) => code(f));
+    output += unorderedList(items);
+    if (cluster.files.length > 5) {
+      output += `... and ${cluster.files.length - 5} more files.
+
+`;
+    }
+  }
+  return output;
+}
+function inferClusterName2(files, dir) {
+  const words = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const fileName = file.toLowerCase();
+    const parts = fileName.split(/[\/\-\_\.]/).filter((p) => p.length > 3);
+    for (const part of parts) {
+      words.set(part, (words.get(part) || 0) + 1);
+    }
+  }
+  const sortedWords = Array.from(words.entries()).sort((a, b) => b[1] - a[1]);
+  if (sortedWords.length > 0 && sortedWords[0][1] > 1) {
+    return capitalizeFirst3(sortedWords[0][0]);
+  }
+  const dirName = dir.split("/").pop() || "Core";
+  return capitalizeFirst3(dirName);
+}
+function capitalizeFirst3(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+// src/docs/current.ts
+import { dirname as dirname12 } from "path";
+function generateCurrent(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount10(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Complete Codebase Snapshot");
+  output += "> **Note:** This is a complete snapshot of the entire codebase. For a high-level overview, see ARCHITECTURE.md.\n\n";
+  output += header("Project Overview", 2);
+  output += generateProjectOverview(graph);
+  output += header("Complete File Index", 2);
+  output += generateCompleteFileIndex(graph);
+  output += header("Complete Symbol Index", 2);
+  output += generateCompleteSymbolIndex(graph);
+  output += header("Complete Edge List", 2);
+  output += generateCompleteEdgeList(graph);
+  output += header("Connection Matrix", 2);
+  output += generateConnectionMatrix(graph);
+  return output;
+}
+function getFileCount10(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function getLanguageStats3(graph) {
+  const stats = {};
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    if (!files.has(attrs.filePath)) {
+      files.add(attrs.filePath);
+      const ext = attrs.filePath.toLowerCase();
+      let lang;
+      if (ext.endsWith(".ts") || ext.endsWith(".tsx")) {
+        lang = "TypeScript";
+      } else if (ext.endsWith(".py")) {
+        lang = "Python";
+      } else if (ext.endsWith(".js") || ext.endsWith(".jsx") || ext.endsWith(".mjs") || ext.endsWith(".cjs")) {
+        lang = "JavaScript";
+      } else if (ext.endsWith(".go")) {
+        lang = "Go";
+      } else {
+        lang = "Other";
+      }
+      stats[lang] = (stats[lang] || 0) + 1;
+    }
+  });
+  return stats;
+}
+function generateProjectOverview(graph) {
+  const fileCount = getFileCount10(graph);
+  const symbolCount = graph.order;
+  const edgeCount = graph.size;
+  const languages2 = getLanguageStats3(graph);
+  let output = "";
+  output += `- **Total files:** ${formatNumber(fileCount)}
+`;
+  output += `- **Total symbols:** ${formatNumber(symbolCount)}
+`;
+  output += `- **Total edges:** ${formatNumber(edgeCount)}
+`;
+  if (Object.keys(languages2).length > 0) {
+    output += "\n**Language breakdown:**\n\n";
+    for (const [lang, count] of Object.entries(languages2).sort((a, b) => b[1] - a[1])) {
+      output += `- ${lang}: ${count} files
+`;
+    }
+  }
+  output += "\n";
+  return output;
+}
+function getFileInfo(graph) {
+  const fileMap = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (!fileMap.has(attrs.filePath)) {
+      fileMap.set(attrs.filePath, {
+        filePath: attrs.filePath,
+        language: getLanguageFromPath3(attrs.filePath),
+        symbols: [],
+        importsFrom: [],
+        importedBy: [],
+        incomingEdges: 0,
+        outgoingEdges: 0
+      });
+    }
+    const info = fileMap.get(attrs.filePath);
+    if (attrs.name !== "__file__") {
+      info.symbols.push({
+        name: attrs.name,
+        kind: attrs.kind,
+        line: attrs.startLine
+      });
+    }
+  });
+  const fileEdges = /* @__PURE__ */ new Map();
+  const fileEdgesReverse = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      if (!fileEdges.has(sourceAttrs.filePath)) {
+        fileEdges.set(sourceAttrs.filePath, /* @__PURE__ */ new Set());
+      }
+      fileEdges.get(sourceAttrs.filePath).add(targetAttrs.filePath);
+      if (!fileEdgesReverse.has(targetAttrs.filePath)) {
+        fileEdgesReverse.set(targetAttrs.filePath, /* @__PURE__ */ new Set());
+      }
+      fileEdgesReverse.get(targetAttrs.filePath).add(sourceAttrs.filePath);
+    }
+  });
+  for (const [filePath, info] of fileMap.entries()) {
+    const importsFrom = fileEdges.get(filePath);
+    const importedBy = fileEdgesReverse.get(filePath);
+    info.importsFrom = importsFrom ? Array.from(importsFrom) : [];
+    info.importedBy = importedBy ? Array.from(importedBy) : [];
+    info.outgoingEdges = info.importsFrom.length;
+    info.incomingEdges = info.importedBy.length;
+  }
+  return Array.from(fileMap.values());
+}
+function getLanguageFromPath3(filePath) {
+  const ext = filePath.toLowerCase();
+  if (ext.endsWith(".ts") || ext.endsWith(".tsx")) return "TypeScript";
+  if (ext.endsWith(".js") || ext.endsWith(".jsx") || ext.endsWith(".mjs") || ext.endsWith(".cjs")) return "JavaScript";
+  if (ext.endsWith(".py")) return "Python";
+  if (ext.endsWith(".go")) return "Go";
+  return "Other";
+}
+function generateCompleteFileIndex(graph) {
+  const fileInfos = getFileInfo(graph);
+  if (fileInfos.length === 0) {
+    return "No files detected.\n\n";
+  }
+  fileInfos.sort((a, b) => a.filePath.localeCompare(b.filePath));
+  const dirGroups = /* @__PURE__ */ new Map();
+  for (const info of fileInfos) {
+    const dir = dirname12(info.filePath);
+    const topDir = dir === "." ? "root" : dir.split("/")[0];
+    if (!dirGroups.has(topDir)) {
+      dirGroups.set(topDir, []);
+    }
+    dirGroups.get(topDir).push(info);
+  }
+  let output = "";
+  for (const [dir, files] of Array.from(dirGroups.entries()).sort()) {
+    output += header(dir === "root" ? "Root Directory" : `${dir}/`, 3);
+    for (const file of files) {
+      output += header(file.filePath, 4);
+      output += `- **Language:** ${file.language}
+`;
+      output += `- **Symbols (${file.symbols.length}):** `;
+      if (file.symbols.length === 0) {
+        output += "None\n";
+      } else if (file.symbols.length <= 10) {
+        output += file.symbols.map((s) => s.name).join(", ") + "\n";
+      } else {
+        output += file.symbols.slice(0, 10).map((s) => s.name).join(", ");
+        output += `, ... and ${file.symbols.length - 10} more
+`;
+      }
+      if (file.importsFrom.length > 0) {
+        output += `- **Imports from (${file.importsFrom.length}):** `;
+        if (file.importsFrom.length <= 5) {
+          output += file.importsFrom.map((f) => code(f)).join(", ") + "\n";
+        } else {
+          output += file.importsFrom.slice(0, 5).map((f) => code(f)).join(", ");
+          output += `, ... and ${file.importsFrom.length - 5} more
+`;
+        }
+      }
+      if (file.importedBy.length > 0) {
+        output += `- **Imported by (${file.importedBy.length}):** `;
+        if (file.importedBy.length <= 5) {
+          output += file.importedBy.map((f) => code(f)).join(", ") + "\n";
+        } else {
+          output += file.importedBy.slice(0, 5).map((f) => code(f)).join(", ");
+          output += `, ... and ${file.importedBy.length - 5} more
+`;
+        }
+      }
+      output += `- **Connections:** ${file.incomingEdges} inbound, ${file.outgoingEdges} outbound
+
+`;
+    }
+  }
+  return output;
+}
+function generateCompleteSymbolIndex(graph) {
+  const symbolsByKind = /* @__PURE__ */ new Map();
+  graph.forEachNode((node, attrs) => {
+    if (attrs.name === "__file__") return;
+    if (!symbolsByKind.has(attrs.kind)) {
+      symbolsByKind.set(attrs.kind, []);
+    }
+    symbolsByKind.get(attrs.kind).push({
+      name: attrs.name,
+      filePath: attrs.filePath,
+      line: attrs.startLine
+    });
+  });
+  if (symbolsByKind.size === 0) {
+    return "No symbols detected.\n\n";
+  }
+  let output = "";
+  const sortedKinds = Array.from(symbolsByKind.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+  for (const [kind, symbols] of sortedKinds) {
+    output += header(`${capitalizeKind2(kind)}s (${symbols.length})`, 3);
+    const sorted = symbols.sort((a, b) => a.name.localeCompare(b.name));
+    const limit = 100;
+    const items = sorted.slice(0, limit).map((s) => {
+      return `${code(s.name)} \u2014 ${code(s.filePath)}:${s.line}`;
+    });
+    output += unorderedList(items);
+    if (symbols.length > limit) {
+      output += `... and ${symbols.length - limit} more.
+
+`;
+    }
+  }
+  return output;
+}
+function capitalizeKind2(kind) {
+  const map = {
+    function: "Function",
+    class: "Class",
+    variable: "Variable",
+    constant: "Constant",
+    type_alias: "Type",
+    interface: "Interface",
+    enum: "Enum",
+    import: "Import",
+    export: "Export",
+    method: "Method",
+    property: "Property",
+    decorator: "Decorator",
+    module: "Module"
+  };
+  return map[kind] || kind;
+}
+function generateCompleteEdgeList(graph) {
+  const fileEdges = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      if (!fileEdges.has(sourceAttrs.filePath)) {
+        fileEdges.set(sourceAttrs.filePath, []);
+      }
+      const edgeDesc = `${sourceAttrs.filePath} \u2192 ${targetAttrs.filePath}`;
+      if (!fileEdges.get(sourceAttrs.filePath).includes(edgeDesc)) {
+        fileEdges.get(sourceAttrs.filePath).push(edgeDesc);
+      }
+    }
+  });
+  if (fileEdges.size === 0) {
+    return "No cross-file edges detected.\n\n";
+  }
+  let output = `Total cross-file edges: ${graph.size}
+
+`;
+  const sortedEdges = Array.from(fileEdges.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+  const limit = 50;
+  for (const [sourceFile, edges] of sortedEdges.slice(0, limit)) {
+    output += header(sourceFile, 3);
+    output += unorderedList(edges.map((e) => e.replace(`${sourceFile} \u2192 `, "")));
+  }
+  if (sortedEdges.length > limit) {
+    output += `... and ${sortedEdges.length - limit} more source files with edges.
+
+`;
+  }
+  return output;
+}
+function generateConnectionMatrix(graph) {
+  const dirEdges = /* @__PURE__ */ new Map();
+  const allDirs = /* @__PURE__ */ new Set();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      const sourceDir = getTopLevelDir2(sourceAttrs.filePath);
+      const targetDir = getTopLevelDir2(targetAttrs.filePath);
+      if (sourceDir && targetDir) {
+        allDirs.add(sourceDir);
+        allDirs.add(targetDir);
+        if (!dirEdges.has(sourceDir)) {
+          dirEdges.set(sourceDir, /* @__PURE__ */ new Map());
+        }
+        const targetMap = dirEdges.get(sourceDir);
+        targetMap.set(targetDir, (targetMap.get(targetDir) || 0) + 1);
+      }
+    }
+  });
+  if (allDirs.size === 0) {
+    return "No directory structure detected.\n\n";
+  }
+  const sortedDirs = Array.from(allDirs).sort();
+  let output = "Compact matrix showing which directories depend on which:\n\n";
+  output += codeBlock(buildMatrixString(sortedDirs, dirEdges), "");
+  return output;
+}
+function buildMatrixString(dirs, edges) {
+  if (dirs.length === 0) return "No directories";
+  let result = "           ";
+  for (const dir of dirs) {
+    result += dir.padEnd(10, " ").substring(0, 10);
+  }
+  result += "\n";
+  for (const sourceDir of dirs) {
+    result += sourceDir.padEnd(10, " ").substring(0, 10) + " ";
+    for (const targetDir of dirs) {
+      if (sourceDir === targetDir) {
+        result += "-         ";
+      } else {
+        const count = edges.get(sourceDir)?.get(targetDir) || 0;
+        if (count > 0) {
+          result += "\u2192         ";
+        } else {
+          const reverseCount = edges.get(targetDir)?.get(sourceDir) || 0;
+          if (reverseCount > 0) {
+            result += "\u2190         ";
+          } else {
+            result += "          ";
+          }
+        }
+      }
+    }
+    result += "\n";
+  }
+  return result;
+}
+function getTopLevelDir2(filePath) {
+  const parts = filePath.split("/");
+  if (parts.length < 2) {
+    return null;
+  }
+  if (parts[0] === "src" && parts.length >= 2) {
+    return parts.length >= 3 ? `${parts[0]}/${parts[1]}` : parts[0];
+  }
+  const firstDir = parts[0];
+  if (firstDir.includes("test") || firstDir.includes("__tests__") || firstDir === "node_modules" || firstDir === "dist" || firstDir === "build") {
+    return null;
+  }
+  return parts[0];
+}
+
+// src/docs/status.ts
+import { readFileSync as readFileSync5, existsSync as existsSync7 } from "fs";
+import { join as join10 } from "path";
+function generateStatus(graph, projectRoot, version) {
+  let output = "";
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount11(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Project Status");
+  output += "TODO/FIXME/HACK inventory showing what's implemented vs pending.\n\n";
+  output += header("Status Summary", 2);
+  output += generateStatusSummary(projectRoot, graph);
+  output += header("TODOs by File", 2);
+  output += generateTodosByFile(projectRoot, graph);
+  output += header("FIXMEs (Urgent)", 2);
+  output += generateFixmes(projectRoot, graph);
+  output += header("HACKs (Technical Debt)", 2);
+  output += generateHacks(projectRoot, graph);
+  output += header("Priority Matrix", 2);
+  output += generatePriorityMatrix(projectRoot, graph);
+  output += header("Deprecated Items", 2);
+  output += generateDeprecated(projectRoot, graph);
+  output += header("Implementation Completeness", 2);
+  output += generateCompleteness(projectRoot, graph);
+  return output;
+}
+function getFileCount11(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function extractComments(projectRoot, filePath) {
+  const comments = [];
+  const fullPath = join10(projectRoot, filePath);
+  if (!existsSync7(fullPath)) {
+    return comments;
+  }
+  try {
+    const content = readFileSync5(fullPath, "utf-8");
+    const lines = content.split("\n");
+    const patterns = [
+      { type: "TODO", regex: /(?:\/\/|#|\/\*)\s*TODO:?\s*(.+)/i },
+      { type: "FIXME", regex: /(?:\/\/|#|\/\*)\s*FIXME:?\s*(.+)/i },
+      { type: "HACK", regex: /(?:\/\/|#|\/\*)\s*HACK:?\s*(.+)/i },
+      { type: "XXX", regex: /(?:\/\/|#|\/\*)\s*XXX:?\s*(.+)/i },
+      { type: "NOTE", regex: /(?:\/\/|#|\/\*)\s*NOTE:?\s*(.+)/i },
+      { type: "OPTIMIZE", regex: /(?:\/\/|#|\/\*)\s*OPTIMIZE:?\s*(.+)/i },
+      { type: "DEPRECATED", regex: /(?:\/\/|#|\/\*)\s*DEPRECATED:?\s*(.+)/i }
+    ];
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      for (const pattern of patterns) {
+        const match = line.match(pattern.regex);
+        if (match) {
+          comments.push({
+            type: pattern.type,
+            file: filePath,
+            line: i + 1,
+            text: match[1].trim().replace(/\*\/.*$/, "").trim()
+          });
+          break;
+        }
+      }
+    }
+  } catch (err) {
+    return comments;
+  }
+  return comments;
+}
+function getAllComments(projectRoot, graph) {
+  const allComments = [];
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  for (const file of files) {
+    const comments = extractComments(projectRoot, file);
+    allComments.push(...comments);
+  }
+  return allComments;
+}
+function generateStatusSummary(projectRoot, graph) {
+  const comments = getAllComments(projectRoot, graph);
+  const counts = {
+    TODO: 0,
+    FIXME: 0,
+    HACK: 0,
+    XXX: 0,
+    NOTE: 0,
+    OPTIMIZE: 0,
+    DEPRECATED: 0
+  };
+  for (const comment of comments) {
+    counts[comment.type]++;
+  }
+  let output = "";
+  output += `- **Total TODOs:** ${formatNumber(counts.TODO)}
+`;
+  output += `- **Total FIXMEs:** ${formatNumber(counts.FIXME)}
+`;
+  output += `- **Total HACKs:** ${formatNumber(counts.HACK)}
+`;
+  if (counts.XXX > 0) {
+    output += `- **Total XXXs:** ${formatNumber(counts.XXX)}
+`;
+  }
+  if (counts.NOTE > 0) {
+    output += `- **Total NOTEs:** ${formatNumber(counts.NOTE)}
+`;
+  }
+  if (counts.OPTIMIZE > 0) {
+    output += `- **Total OPTIMIZEs:** ${formatNumber(counts.OPTIMIZE)}
+`;
+  }
+  if (counts.DEPRECATED > 0) {
+    output += `- **Total DEPRECATEDs:** ${formatNumber(counts.DEPRECATED)}
+`;
+  }
+  output += "\n";
+  return output;
+}
+function generateTodosByFile(projectRoot, graph) {
+  const comments = getAllComments(projectRoot, graph);
+  const todos = comments.filter((c) => c.type === "TODO");
+  if (todos.length === 0) {
+    return "\u2705 No TODOs found.\n\n";
+  }
+  const fileGroups = /* @__PURE__ */ new Map();
+  for (const todo of todos) {
+    if (!fileGroups.has(todo.file)) {
+      fileGroups.set(todo.file, []);
+    }
+    fileGroups.get(todo.file).push(todo);
+  }
+  let output = `Found ${todos.length} TODO${todos.length === 1 ? "" : "s"} across ${fileGroups.size} file${fileGroups.size === 1 ? "" : "s"}:
+
+`;
+  const sortedFiles = Array.from(fileGroups.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+  for (const [file, fileTodos] of sortedFiles) {
+    output += header(file, 3);
+    const items = fileTodos.map((t) => `[ ] TODO: ${t.text} (line ${t.line})`);
+    output += unorderedList(items);
+  }
+  return output;
+}
+function generateFixmes(projectRoot, graph) {
+  const comments = getAllComments(projectRoot, graph);
+  const fixmes = comments.filter((c) => c.type === "FIXME");
+  if (fixmes.length === 0) {
+    return "\u2705 No FIXMEs found.\n\n";
+  }
+  let output = `\u26A0\uFE0F Found ${fixmes.length} FIXME${fixmes.length === 1 ? "" : "s"} (known broken or urgent issues):
+
+`;
+  fixmes.sort((a, b) => a.file.localeCompare(b.file));
+  const items = fixmes.map((f) => {
+    return `[ ] FIXME: ${f.text} (${code(f.file)}:${f.line})`;
+  });
+  output += unorderedList(items);
+  return output;
+}
+function generateHacks(projectRoot, graph) {
+  const comments = getAllComments(projectRoot, graph);
+  const hacks = comments.filter((c) => c.type === "HACK");
+  if (hacks.length === 0) {
+    return "\u2705 No HACKs found.\n\n";
+  }
+  let output = `Found ${hacks.length} HACK${hacks.length === 1 ? "" : "s"} (technical debt - works but needs proper implementation):
+
+`;
+  hacks.sort((a, b) => a.file.localeCompare(b.file));
+  const items = hacks.map((h) => {
+    return `[ ] HACK: ${h.text} (${code(h.file)}:${h.line})`;
+  });
+  output += unorderedList(items);
+  return output;
+}
+function generatePriorityMatrix(projectRoot, graph) {
+  const comments = getAllComments(projectRoot, graph);
+  const fileConnections = /* @__PURE__ */ new Map();
+  graph.forEachEdge((edge, attrs, source, target) => {
+    const sourceAttrs = graph.getNodeAttributes(source);
+    const targetAttrs = graph.getNodeAttributes(target);
+    if (sourceAttrs.filePath !== targetAttrs.filePath) {
+      fileConnections.set(sourceAttrs.filePath, (fileConnections.get(sourceAttrs.filePath) || 0) + 1);
+      fileConnections.set(targetAttrs.filePath, (fileConnections.get(targetAttrs.filePath) || 0) + 1);
+    }
+  });
+  const items = [];
+  for (const comment of comments) {
+    if (comment.type === "TODO" || comment.type === "FIXME" || comment.type === "HACK") {
+      const connections = fileConnections.get(comment.file) || 0;
+      let priority = "Low";
+      let priorityScore = 1;
+      if (comment.type === "FIXME") {
+        if (connections > 10) {
+          priority = "\u{1F534} Critical";
+          priorityScore = 4;
+        } else if (connections > 5) {
+          priority = "\u{1F7E1} High";
+          priorityScore = 3;
+        } else {
+          priority = "\u{1F7E2} Medium";
+          priorityScore = 2;
+        }
+      } else if (comment.type === "TODO") {
+        if (connections > 10) {
+          priority = "\u{1F7E1} High";
+          priorityScore = 3;
+        } else if (connections > 5) {
+          priority = "\u{1F7E2} Medium";
+          priorityScore = 2;
+        } else {
+          priority = "\u26AA Low";
+          priorityScore = 1;
+        }
+      } else if (comment.type === "HACK") {
+        if (connections > 10) {
+          priority = "\u{1F7E1} High";
+          priorityScore = 3;
+        } else {
+          priority = "\u{1F7E2} Medium";
+          priorityScore = 2;
+        }
+      }
+      items.push({
+        comment,
+        connections,
+        priority
+      });
+    }
+  }
+  if (items.length === 0) {
+    return "No items to prioritize.\n\n";
+  }
+  items.sort((a, b) => {
+    const priorityOrder = { "\u{1F534} Critical": 4, "\u{1F7E1} High": 3, "\u{1F7E2} Medium": 2, "\u26AA Low": 1 };
+    const aPriority = priorityOrder[a.priority] || 0;
+    const bPriority = priorityOrder[b.priority] || 0;
+    if (aPriority !== bPriority) {
+      return bPriority - aPriority;
+    }
+    return b.connections - a.connections;
+  });
+  let output = "Items prioritized by type and file connections:\n\n";
+  const headers = ["Type", "File", "Line", "Connections", "Priority"];
+  const rows = items.slice(0, 20).map((item) => [
+    item.comment.type,
+    `\`${item.comment.file}\``,
+    item.comment.line.toString(),
+    formatNumber(item.connections),
+    item.priority
+  ]);
+  output += table(headers, rows);
+  if (items.length > 20) {
+    output += `... and ${items.length - 20} more items.
+
+`;
+  }
+  return output;
+}
+function generateDeprecated(projectRoot, graph) {
+  const comments = getAllComments(projectRoot, graph);
+  const deprecated = comments.filter((c) => c.type === "DEPRECATED");
+  if (deprecated.length === 0) {
+    return "\u2705 No deprecated items found.\n\n";
+  }
+  let output = `Found ${deprecated.length} deprecated item${deprecated.length === 1 ? "" : "s"}:
+
+`;
+  deprecated.sort((a, b) => a.file.localeCompare(b.file));
+  const items = deprecated.map((d) => {
+    return `DEPRECATED: ${d.text} (${code(d.file)}:${d.line})`;
+  });
+  output += unorderedList(items);
+  return output;
+}
+function generateCompleteness(projectRoot, graph) {
+  const comments = getAllComments(projectRoot, graph);
+  const fileTodos = /* @__PURE__ */ new Map();
+  const fileSymbols = /* @__PURE__ */ new Map();
+  for (const comment of comments) {
+    if (comment.type === "TODO") {
+      fileTodos.set(comment.file, (fileTodos.get(comment.file) || 0) + 1);
+    }
+  }
+  graph.forEachNode((node, attrs) => {
+    fileSymbols.set(attrs.filePath, (fileSymbols.get(attrs.filePath) || 0) + 1);
+  });
+  const allFiles = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    allFiles.add(attrs.filePath);
+  });
+  const inProgress = [];
+  const complete = [];
+  for (const file of allFiles) {
+    const todoCount = fileTodos.get(file) || 0;
+    const symbolCount = fileSymbols.get(file) || 0;
+    if (symbolCount === 0) continue;
+    const todoRatio = todoCount / symbolCount;
+    if (todoRatio > 0.1) {
+      inProgress.push(file);
+    } else if (todoCount === 0) {
+      complete.push(file);
+    }
+  }
+  let output = "";
+  const totalFiles = allFiles.size;
+  const completePercent = totalFiles > 0 ? (complete.length / totalFiles * 100).toFixed(1) : "0.0";
+  output += `- **Complete files (no TODOs):** ${formatNumber(complete.length)} (${completePercent}%)
+`;
+  output += `- **In-progress files (many TODOs):** ${formatNumber(inProgress.length)}
+
+`;
+  if (inProgress.length > 0) {
+    output += "**Files in progress (high TODO ratio):**\n\n";
+    const items = inProgress.slice(0, 10).map((f) => {
+      const todoCount = fileTodos.get(f) || 0;
+      return `${code(f)} (${todoCount} TODOs)`;
+    });
+    output += unorderedList(items);
+    if (inProgress.length > 10) {
+      output += `... and ${inProgress.length - 10} more.
+
+`;
+    }
+  }
+  const dirTodos = /* @__PURE__ */ new Map();
+  const dirFiles = /* @__PURE__ */ new Map();
+  for (const file of allFiles) {
+    const dir = file.split("/")[0];
+    dirFiles.set(dir, (dirFiles.get(dir) || 0) + 1);
+    const todoCount = fileTodos.get(file) || 0;
+    if (todoCount > 0) {
+      dirTodos.set(dir, (dirTodos.get(dir) || 0) + 1);
+    }
+  }
+  if (dirFiles.size > 1) {
+    output += "**Completeness by directory:**\n\n";
+    const sortedDirs = Array.from(dirFiles.entries()).sort((a, b) => b[1] - a[1]);
+    for (const [dir, fileCount] of sortedDirs) {
+      const todosInDir = dirTodos.get(dir) || 0;
+      const completeInDir = fileCount - todosInDir;
+      const percent = (completeInDir / fileCount * 100).toFixed(1);
+      output += `- **${dir}/**: ${completeInDir}/${fileCount} files complete (${percent}%)
+`;
+    }
+    output += "\n";
+  }
+  return output;
+}
+
+// src/docs/health.ts
+function generateHealth(graph, projectRoot, version) {
+  let output = "";
+  const report = calculateHealthScore(graph, projectRoot);
+  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const fileCount = getFileCount12(graph);
+  output += timestamp(version, now, fileCount, graph.order);
+  output += header("Dependency Health Score");
+  output += "Analysis of dependency architecture quality across 6 dimensions.\n\n";
+  output += header("Overall Score", 2);
+  output += generateOverallScore(report);
+  output += header("Dimension Breakdown", 2);
+  output += generateDimensionsBreakdown(report.dimensions);
+  output += header("Recommendations", 2);
+  output += generateRecommendations2(report.recommendations);
+  output += header("Historical Trend", 2);
+  output += generateHistoricalTrend(projectRoot, report);
+  output += header("Detailed Metrics", 2);
+  output += generateDetailedMetrics(report.dimensions);
+  return output;
+}
+function getFileCount12(graph) {
+  const files = /* @__PURE__ */ new Set();
+  graph.forEachNode((node, attrs) => {
+    files.add(attrs.filePath);
+  });
+  return files.size;
+}
+function generateOverallScore(report) {
+  let output = "";
+  const gradeEmoji = {
+    "A": "\u{1F7E2}",
+    "B": "\u{1F535}",
+    "C": "\u{1F7E1}",
+    "D": "\u{1F7E0}",
+    "F": "\u{1F534}"
+  };
+  output += `**Score:** ${report.overall}/100
+
+`;
+  output += `**Grade:** ${gradeEmoji[report.grade]} ${report.grade}
+
+`;
+  output += `**Summary:** ${report.summary}
+
+`;
+  output += `**Project Statistics:**
+
+`;
+  output += `- Files: ${formatNumber(report.projectStats.files)}
+`;
+  output += `- Symbols: ${formatNumber(report.projectStats.symbols)}
+`;
+  output += `- Edges: ${formatNumber(report.projectStats.edges)}
+`;
+  const langs = Object.entries(report.projectStats.languages).sort((a, b) => b[1] - a[1]).map(([lang, count]) => `${lang} (${count})`).join(", ");
+  output += `- Languages: ${langs}
+
+`;
+  return output;
+}
+function generateDimensionsBreakdown(dimensions) {
+  let output = "";
+  const headers = ["Dimension", "Score", "Grade", "Weight", "Details"];
+  const rows = dimensions.map((d) => [
+    d.name,
+    `${d.score}/100`,
+    d.grade,
+    `${(d.weight * 100).toFixed(0)}%`,
+    d.details
+  ]);
+  output += table(headers, rows);
+  return output;
+}
+function generateRecommendations2(recommendations) {
+  if (recommendations.length === 0) {
+    return "\u2705 No critical issues detected.\n\n";
+  }
+  return unorderedList(recommendations);
+}
+function generateHistoricalTrend(projectRoot, currentReport) {
+  const history = loadHealthHistory(projectRoot);
+  if (history.length < 2) {
+    return "No historical data available. Run `depwire health` regularly to track trends.\n\n";
+  }
+  let output = `Showing last ${Math.min(history.length, 10)} health checks:
+
+`;
+  const headers = ["Date", "Score", "Grade", "Trend"];
+  const recent = history.slice(-10);
+  const rows = recent.map((entry, idx) => {
+    let trend = "\u2014";
+    if (idx > 0) {
+      const prev = recent[idx - 1];
+      const delta = entry.score - prev.score;
+      if (delta > 0) {
+        trend = `\u2191 +${delta}`;
+      } else if (delta < 0) {
+        trend = `\u2193 ${delta}`;
+      } else {
+        trend = "\u2192 0";
+      }
+    }
+    return [
+      entry.timestamp.split("T")[0],
+      entry.score.toString(),
+      entry.grade,
+      trend
+    ];
+  });
+  output += table(headers, rows);
+  const first = recent[0];
+  const last = recent[recent.length - 1];
+  const totalDelta = last.score - first.score;
+  output += `
+**Trend:** `;
+  if (totalDelta > 0) {
+    output += `\u{1F4C8} Improved by ${totalDelta} points over ${recent.length} checks
+
+`;
+  } else if (totalDelta < 0) {
+    output += `\u{1F4C9} Declined by ${Math.abs(totalDelta)} points over ${recent.length} checks
+
+`;
+  } else {
+    output += `\u{1F4CA} Stable at ${last.score} points over ${recent.length} checks
+
+`;
+  }
+  return output;
+}
+function generateDetailedMetrics(dimensions) {
+  let output = "";
+  for (const dim of dimensions) {
+    output += header(dim.name, 3);
+    output += `**Score:** ${dim.score}/100 (${dim.grade})
+
+`;
+    output += `**Details:** ${dim.details}
+
+`;
+    if (Object.keys(dim.metrics).length > 0) {
+      output += `**Metrics:**
+
+`;
+      for (const [key, value] of Object.entries(dim.metrics)) {
+        output += `- ${key}: ${typeof value === "number" ? formatNumber(value) : value}
+`;
+      }
+      output += "\n";
+    }
+  }
+  return output;
+}
+
+// src/docs/metadata.ts
+import { existsSync as existsSync8, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "fs";
+import { join as join11 } from "path";
+function loadMetadata(outputDir) {
+  const metadataPath = join11(outputDir, "metadata.json");
+  if (!existsSync8(metadataPath)) {
+    return null;
+  }
+  try {
+    const content = readFileSync6(metadataPath, "utf-8");
+    return JSON.parse(content);
+  } catch (err) {
+    console.error("Failed to load metadata:", err);
+    return null;
+  }
+}
+function saveMetadata(outputDir, metadata) {
+  const metadataPath = join11(outputDir, "metadata.json");
+  writeFileSync2(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+}
+function createMetadata(version, projectPath, fileCount, symbolCount, edgeCount, docTypes) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const documents = {};
+  for (const docType of docTypes) {
+    const fileName = docType === "architecture" ? "ARCHITECTURE.md" : docType === "conventions" ? "CONVENTIONS.md" : docType === "dependencies" ? "DEPENDENCIES.md" : docType === "onboarding" ? "ONBOARDING.md" : docType === "files" ? "FILES.md" : docType === "api_surface" ? "API_SURFACE.md" : docType === "errors" ? "ERRORS.md" : docType === "tests" ? "TESTS.md" : docType === "history" ? "HISTORY.md" : docType === "current" ? "CURRENT.md" : docType === "status" ? "STATUS.md" : docType === "health" ? "HEALTH.md" : `${docType.toUpperCase()}.md`;
+    documents[docType] = {
+      generated_at: now,
+      file: fileName
+    };
+  }
+  return {
+    version,
+    generated_at: now,
+    project_path: projectPath,
+    file_count: fileCount,
+    symbol_count: symbolCount,
+    edge_count: edgeCount,
+    documents
+  };
+}
+function updateMetadata(existing, docTypes, fileCount, symbolCount, edgeCount) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const docType of docTypes) {
+    if (existing.documents[docType]) {
+      existing.documents[docType].generated_at = now;
+    }
+  }
+  existing.file_count = fileCount;
+  existing.symbol_count = symbolCount;
+  existing.edge_count = edgeCount;
+  existing.generated_at = now;
+  return existing;
+}
+
+// src/docs/generator.ts
+async function generateDocs(graph, projectRoot, version, parseTime, options) {
+  const startTime = Date.now();
+  const generated = [];
+  const errors = [];
+  try {
+    if (!existsSync9(options.outputDir)) {
+      mkdirSync(options.outputDir, { recursive: true });
+      if (options.verbose) {
+        console.log(`Created output directory: ${options.outputDir}`);
+      }
     }
     let docsToGenerate = options.include;
     if (options.update && options.only) {
       docsToGenerate = options.only;
     }
     if (docsToGenerate.includes("all")) {
-      docsToGenerate = ["architecture", "conventions", "dependencies", "onboarding"];
+      docsToGenerate = [
+        "architecture",
+        "conventions",
+        "dependencies",
+        "onboarding",
+        "files",
+        "api_surface",
+        "errors",
+        "tests",
+        "history",
+        "current",
+        "status",
+        "health"
+      ];
     }
     let metadata = null;
     if (options.update) {
       metadata = loadMetadata(options.outputDir);
     }
-    const fileCount = getFileCount5(graph);
+    const fileCount = getFileCount13(graph);
     const symbolCount = graph.order;
     const edgeCount = graph.size;
     if (options.format === "markdown") {
@@ -4288,8 +7070,8 @@ async function generateDocs(graph, projectRoot, version, parseTime, options) {
         try {
           if (options.verbose) console.log("Generating ARCHITECTURE.md...");
           const content = generateArchitecture(graph, projectRoot, version, parseTime);
-          const filePath = join10(options.outputDir, "ARCHITECTURE.md");
-          writeFileSync2(filePath, content, "utf-8");
+          const filePath = join12(options.outputDir, "ARCHITECTURE.md");
+          writeFileSync3(filePath, content, "utf-8");
           generated.push("ARCHITECTURE.md");
         } catch (err) {
           errors.push(`Failed to generate ARCHITECTURE.md: ${err}`);
@@ -4299,8 +7081,8 @@ async function generateDocs(graph, projectRoot, version, parseTime, options) {
         try {
           if (options.verbose) console.log("Generating CONVENTIONS.md...");
           const content = generateConventions(graph, projectRoot, version);
-          const filePath = join10(options.outputDir, "CONVENTIONS.md");
-          writeFileSync2(filePath, content, "utf-8");
+          const filePath = join12(options.outputDir, "CONVENTIONS.md");
+          writeFileSync3(filePath, content, "utf-8");
           generated.push("CONVENTIONS.md");
         } catch (err) {
           errors.push(`Failed to generate CONVENTIONS.md: ${err}`);
@@ -4310,8 +7092,8 @@ async function generateDocs(graph, projectRoot, version, parseTime, options) {
         try {
           if (options.verbose) console.log("Generating DEPENDENCIES.md...");
           const content = generateDependencies(graph, projectRoot, version);
-          const filePath = join10(options.outputDir, "DEPENDENCIES.md");
-          writeFileSync2(filePath, content, "utf-8");
+          const filePath = join12(options.outputDir, "DEPENDENCIES.md");
+          writeFileSync3(filePath, content, "utf-8");
           generated.push("DEPENDENCIES.md");
         } catch (err) {
           errors.push(`Failed to generate DEPENDENCIES.md: ${err}`);
@@ -4321,13 +7103,101 @@ async function generateDocs(graph, projectRoot, version, parseTime, options) {
         try {
           if (options.verbose) console.log("Generating ONBOARDING.md...");
           const content = generateOnboarding(graph, projectRoot, version);
-          const filePath = join10(options.outputDir, "ONBOARDING.md");
-          writeFileSync2(filePath, content, "utf-8");
+          const filePath = join12(options.outputDir, "ONBOARDING.md");
+          writeFileSync3(filePath, content, "utf-8");
           generated.push("ONBOARDING.md");
         } catch (err) {
           errors.push(`Failed to generate ONBOARDING.md: ${err}`);
         }
       }
+      if (docsToGenerate.includes("files")) {
+        try {
+          if (options.verbose) console.log("Generating FILES.md...");
+          const content = generateFiles(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "FILES.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("FILES.md");
+        } catch (err) {
+          errors.push(`Failed to generate FILES.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("api_surface")) {
+        try {
+          if (options.verbose) console.log("Generating API_SURFACE.md...");
+          const content = generateApiSurface(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "API_SURFACE.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("API_SURFACE.md");
+        } catch (err) {
+          errors.push(`Failed to generate API_SURFACE.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("errors")) {
+        try {
+          if (options.verbose) console.log("Generating ERRORS.md...");
+          const content = generateErrors(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "ERRORS.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("ERRORS.md");
+        } catch (err) {
+          errors.push(`Failed to generate ERRORS.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("tests")) {
+        try {
+          if (options.verbose) console.log("Generating TESTS.md...");
+          const content = generateTests(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "TESTS.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("TESTS.md");
+        } catch (err) {
+          errors.push(`Failed to generate TESTS.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("history")) {
+        try {
+          if (options.verbose) console.log("Generating HISTORY.md...");
+          const content = generateHistory(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "HISTORY.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("HISTORY.md");
+        } catch (err) {
+          errors.push(`Failed to generate HISTORY.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("current")) {
+        try {
+          if (options.verbose) console.log("Generating CURRENT.md...");
+          const content = generateCurrent(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "CURRENT.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("CURRENT.md");
+        } catch (err) {
+          errors.push(`Failed to generate CURRENT.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("status")) {
+        try {
+          if (options.verbose) console.log("Generating STATUS.md...");
+          const content = generateStatus(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "STATUS.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("STATUS.md");
+        } catch (err) {
+          errors.push(`Failed to generate STATUS.md: ${err}`);
+        }
+      }
+      if (docsToGenerate.includes("health")) {
+        try {
+          if (options.verbose) console.log("Generating HEALTH.md...");
+          const content = generateHealth(graph, projectRoot, version);
+          const filePath = join12(options.outputDir, "HEALTH.md");
+          writeFileSync3(filePath, content, "utf-8");
+          generated.push("HEALTH.md");
+        } catch (err) {
+          errors.push(`Failed to generate HEALTH.md: ${err}`);
+        }
+      }
     } else if (options.format === "json") {
       errors.push("JSON format not yet supported");
     }
@@ -4356,7 +7226,7 @@ async function generateDocs(graph, projectRoot, version, parseTime, options) {
     };
   }
 }
-function getFileCount5(graph) {
+function getFileCount13(graph) {
   const files = /* @__PURE__ */ new Set();
   graph.forEachNode((node, attrs) => {
     files.add(attrs.filePath);
@@ -4369,13 +7239,13 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/mcp/tools.ts
-import { dirname as dirname8, join as join12 } from "path";
-import { existsSync as existsSync9, readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname13, join as join14 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync7 } from "fs";
 
 // src/mcp/connect.ts
 import simpleGit from "simple-git";
-import { existsSync as existsSync8 } from "fs";
-import { join as join11, basename as basename3, resolve as resolve2 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { join as join13, basename as basename5, resolve as resolve2 } from "path";
 import { tmpdir, homedir } from "os";
 function validateProjectPath(source) {
   const resolved = resolve2(source);
@@ -4388,11 +7258,11 @@ function validateProjectPath(source) {
     "/boot",
     "/proc",
     "/sys",
-    join11(homedir(), ".ssh"),
-    join11(homedir(), ".gnupg"),
-    join11(homedir(), ".aws"),
-    join11(homedir(), ".config"),
-    join11(homedir(), ".env")
+    join13(homedir(), ".ssh"),
+    join13(homedir(), ".gnupg"),
+    join13(homedir(), ".aws"),
+    join13(homedir(), ".config"),
+    join13(homedir(), ".env")
   ];
   for (const blocked of blockedPaths) {
     if (resolved.startsWith(blocked)) {
@@ -4415,11 +7285,11 @@ async function connectToRepo(source, subdirectory, state) {
         };
       }
       projectName = match[1];
-      const reposDir = join11(tmpdir(), "depwire-repos");
-      const cloneDir = join11(reposDir, projectName);
+      const reposDir = join13(tmpdir(), "depwire-repos");
+      const cloneDir = join13(reposDir, projectName);
       console.error(`Connecting to GitHub repo: ${source}`);
       const git = simpleGit();
-      if (existsSync8(cloneDir)) {
+      if (existsSync10(cloneDir)) {
         console.error(`Repo already cloned at ${cloneDir}, pulling latest changes...`);
         try {
           await git.cwd(cloneDir).pull();
@@ -4437,7 +7307,7 @@ async function connectToRepo(source, subdirectory, state) {
           };
         }
       }
-      projectRoot = subdirectory ? join11(cloneDir, subdirectory) : cloneDir;
+      projectRoot = subdirectory ? join13(cloneDir, subdirectory) : cloneDir;
     } else {
       const validation2 = validateProjectPath(source);
       if (!validation2.valid) {
@@ -4446,14 +7316,14 @@ async function connectToRepo(source, subdirectory, state) {
           message: validation2.error
         };
       }
-      if (!existsSync8(source)) {
+      if (!existsSync10(source)) {
         return {
           error: "Directory not found",
           message: `Directory does not exist: ${source}`
         };
       }
-      projectRoot = subdirectory ? join11(source, subdirectory) : source;
-      projectName = basename3(projectRoot);
+      projectRoot = subdirectory ? join13(source, subdirectory) : source;
+      projectName = basename5(projectRoot);
     }
     const validation = validateProjectPath(projectRoot);
     if (!validation.valid) {
@@ -4462,7 +7332,7 @@ async function connectToRepo(source, subdirectory, state) {
         message: validation.error
       };
     }
-    if (!existsSync8(projectRoot)) {
+    if (!existsSync10(projectRoot)) {
       return {
         error: "Project root not found",
         message: `Directory does not exist: ${projectRoot}`
@@ -4736,6 +7606,14 @@ function getToolsList() {
           }
         }
       }
+    },
+    {
+      name: "get_health_score",
+      description: "Get a 0-100 health score for the project's dependency architecture. Scores coupling, cohesion, circular dependencies, god files, orphan files, and dependency depth. Returns overall score, per-dimension breakdown, and actionable recommendations.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      }
     }
   ];
 }
@@ -4780,6 +7658,15 @@ async function handleToolCall(name, args, state) {
       } else {
         result = await handleUpdateProjectDocs(args.doc_type || "all", state);
       }
+    } else if (name === "get_health_score") {
+      if (!isProjectLoaded(state)) {
+        result = {
+          error: "No project loaded",
+          message: "Use connect_repo to connect to a codebase first"
+        };
+      } else {
+        result = handleGetHealthScore(state);
+      }
     } else {
       if (!isProjectLoaded(state)) {
         result = {
@@ -5117,7 +8004,7 @@ function handleGetArchitectureSummary(graph) {
   const dirMap = /* @__PURE__ */ new Map();
   const languageBreakdown = {};
   fileSummary.forEach((f) => {
-    const dir = f.filePath.includes("/") ? dirname8(f.filePath) : ".";
+    const dir = f.filePath.includes("/") ? dirname13(f.filePath) : ".";
     if (!dirMap.has(dir)) {
       dirMap.set(dir, { fileCount: 0, symbolCount: 0 });
     }
@@ -5204,8 +8091,8 @@ The server will keep running until you end the MCP session or press Ctrl+C.`;
   };
 }
 async function handleGetProjectDocs(docType, state) {
-  const docsDir = join12(state.projectRoot, ".depwire");
-  if (!existsSync9(docsDir)) {
+  const docsDir = join14(state.projectRoot, ".depwire");
+  if (!existsSync11(docsDir)) {
     const errorMessage = `Project documentation has not been generated yet.
 
 Run \`depwire docs ${state.projectRoot}\` to generate codebase documentation.
@@ -5235,12 +8122,12 @@ Available document types:
       missing.push(doc);
       continue;
     }
-    const filePath = join12(docsDir, metadata.documents[doc].file);
-    if (!existsSync9(filePath)) {
+    const filePath = join14(docsDir, metadata.documents[doc].file);
+    if (!existsSync11(filePath)) {
       missing.push(doc);
       continue;
     }
-    const content = readFileSync5(filePath, "utf-8");
+    const content = readFileSync7(filePath, "utf-8");
     if (docsToReturn.length > 1) {
       output += `
 
@@ -5265,16 +8152,16 @@ Available document types:
 }
 async function handleUpdateProjectDocs(docType, state) {
   const startTime = Date.now();
-  const docsDir = join12(state.projectRoot, ".depwire");
+  const docsDir = join14(state.projectRoot, ".depwire");
   console.error("Regenerating project documentation...");
   const parsedFiles = await parseProject(state.projectRoot);
   const graph = buildGraph(parsedFiles);
   const parseTime = (Date.now() - startTime) / 1e3;
   state.graph = graph;
-  const packageJsonPath = join12(__dirname, "../../package.json");
-  const packageJson = JSON.parse(readFileSync5(packageJsonPath, "utf-8"));
+  const packageJsonPath = join14(__dirname, "../../package.json");
+  const packageJson = JSON.parse(readFileSync7(packageJsonPath, "utf-8"));
   const docsToGenerate = docType === "all" ? ["architecture", "conventions", "dependencies", "onboarding"] : [docType];
-  const docsExist = existsSync9(docsDir);
+  const docsExist = existsSync11(docsDir);
   const result = await generateDocs(graph, state.projectRoot, packageJson.version, parseTime, {
     outputDir: docsDir,
     format: "markdown",
@@ -5309,6 +8196,12 @@ async function handleUpdateProjectDocs(docType, state) {
     };
   }
 }
+function handleGetHealthScore(state) {
+  const graph = state.graph;
+  const projectRoot = state.projectRoot;
+  const report = calculateHealthScore(graph, projectRoot);
+  return report;
+}
 
 // src/mcp/server.ts
 async function startMcpServer(state) {
@@ -5354,6 +8247,8 @@ export {
   startVizServer,
   createEmptyState,
   updateFileInGraph,
+  calculateHealthScore,
+  getHealthTrend,
   generateDocs,
   startMcpServer
 };