@ctxo/cli 0.7.2 → 0.8.0

package/dist/{cli-router-T3VZZJD6.js → cli-router-GZA44VOV.js}

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import {
   ArchitecturalOverlay,
+  BoundaryViolationDetector,
+  CommunitySnapshotWriter,
   DeadCodeDetector,
+  DriftDetector,
   PageRankCalculator,
   RevertDetector,
   SessionRecorderAdapter,
@@ -9,28 +12,32 @@ import {
   SqliteStorageAdapter,
   SymbolGraph,
   aggregateCoChanges,
-  createLogger,
   detectWorkspace,
   indexIgnorePatterns,
   indexIgnoreProjectPatterns,
   loadConfig,
-  makeGlobMatcher
-} from "./chunk-4M4V5V36.js";
+  makeGlobMatcher,
+  watchSnapshotMinFileChanges
+} from "./chunk-HXEPS2XY.js";
+import {
+  atomicWrite,
+  createLogger
+} from "./chunk-6EKERTJ7.js";
 import {
   JsonIndexReader
-} from "./chunk-WXA2JJLH.js";
+} from "./chunk-2TVHKCCU.js";
 import {
   StalenessDetector
 } from "./chunk-PSKDDLSF.js";
 
 // src/cli/cli-router.ts
-import { readFileSync as readFileSync13, existsSync as existsSync21 } from "fs";
-import { dirname as dirname8, join as join23 } from "path";
+import { readFileSync as readFileSync14, existsSync as existsSync22 } from "fs";
+import { dirname as dirname8, join as join24 } from "path";
 
 // src/cli/index-command.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { readFileSync as readFileSync5, writeFileSync as writeFileSync3, existsSync as existsSync8, statSync, readdirSync as readdirSync2 } from "fs";
-import { join as join7, relative, extname as extname3 } from "path";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync2, existsSync as existsSync9, statSync, readdirSync as readdirSync2 } from "fs";
+import { join as join8, relative, extname as extname3 } from "path";
 import { createRequire as createRequire2 } from "module";
 
 // src/core/staleness/content-hasher.ts
@@ -603,15 +610,15 @@ function isLockedCI(env) {
   return true;
 }
 function spawnInstall(command, args, cwd) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = spawn(command, [...args], { cwd, stdio: "inherit", shell: process.platform === "win32" });
-    child.on("exit", (code) => resolve3(code ?? 0));
+    child.on("exit", (code) => resolve4(code ?? 0));
     child.on("error", (err) => reject(err));
   });
 }
 
 // src/adapters/storage/json-index-writer.ts
-import { writeFileSync, renameSync, mkdirSync, unlinkSync, existsSync as existsSync6 } from "fs";
+import { mkdirSync, unlinkSync, existsSync as existsSync6 } from "fs";
 import { dirname as dirname4, join as join5, resolve as resolve2, sep } from "path";
 var JsonIndexWriter = class {
   indexDir;
@@ -634,9 +641,7 @@ var JsonIndexWriter = class {
     this.atomicWrite(targetPath, JSON.stringify(matrix, null, 2));
   }
   atomicWrite(targetPath, content) {
-    const tmpPath = `${targetPath}.${process.pid}.tmp`;
-    writeFileSync(tmpPath, content, "utf-8");
-    renameSync(tmpPath, targetPath);
+    atomicWrite(targetPath, content);
   }
   delete(relativePath) {
     const targetPath = this.resolveIndexPath(relativePath);
@@ -668,7 +673,7 @@ var JsonIndexWriter = class {
 };
 
 // src/adapters/storage/schema-manager.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync7, mkdirSync as mkdirSync2 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync, existsSync as existsSync7, mkdirSync as mkdirSync2 } from "fs";
 import { join as join6, dirname as dirname5 } from "path";
 var CURRENT_SCHEMA_VERSION = "1.0.0";
 var SchemaManager = class {
@@ -687,7 +692,7 @@ var SchemaManager = class {
   }
   writeVersion() {
     mkdirSync2(dirname5(this.versionFilePath), { recursive: true });
-    writeFileSync2(this.versionFilePath, CURRENT_SCHEMA_VERSION, "utf-8");
+    writeFileSync(this.versionFilePath, CURRENT_SCHEMA_VERSION, "utf-8");
   }
   isCompatible() {
     const stored = this.readStoredVersion();
@@ -696,6 +701,340 @@ var SchemaManager = class {
   }
 };
 
+// src/adapters/storage/architecture-artifacts-writer.ts
+import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync5 } from "fs";
+import { join as join7, resolve as resolve3 } from "path";
+import { tmpdir } from "os";
+var log3 = createLogger("ctxo:architecture-artifacts");
+var DRIFT_FILE_NAME = "drift-events.json";
+var VIOLATIONS_FILE_NAME = "boundary-violations.json";
+var ArchitectureArtifactsWriter = class {
+  indexDir;
+  constructor(ctxoRoot, options = {}) {
+    this.indexDir = join7(ctxoRoot, "index");
+    assertSafeWritePath(ctxoRoot, options.allowProductionPath ?? false);
+  }
+  writeDriftEvents(artifact) {
+    mkdirSync3(this.indexDir, { recursive: true });
+    atomicWrite(join7(this.indexDir, DRIFT_FILE_NAME), JSON.stringify(artifact, null, 2));
+  }
+  writeBoundaryViolations(artifact) {
+    mkdirSync3(this.indexDir, { recursive: true });
+    atomicWrite(join7(this.indexDir, VIOLATIONS_FILE_NAME), JSON.stringify(artifact, null, 2));
+  }
+  readDriftEvents() {
+    const path = join7(this.indexDir, DRIFT_FILE_NAME);
+    if (!existsSync8(path)) return void 0;
+    try {
+      return JSON.parse(readFileSync5(path, "utf-8"));
+    } catch (err) {
+      log3.warn(`failed to parse ${DRIFT_FILE_NAME}: ${err.message}`);
+      return void 0;
+    }
+  }
+  readBoundaryViolations() {
+    const path = join7(this.indexDir, VIOLATIONS_FILE_NAME);
+    if (!existsSync8(path)) return void 0;
+    try {
+      return JSON.parse(readFileSync5(path, "utf-8"));
+    } catch (err) {
+      log3.warn(`failed to parse ${VIOLATIONS_FILE_NAME}: ${err.message}`);
+      return void 0;
+    }
+  }
+};
+function assertSafeWritePath(ctxoRoot, allowProductionPath) {
+  const resolvedRoot = resolve3(ctxoRoot);
+  const resolvedTmp = resolve3(tmpdir());
+  if (resolvedRoot.startsWith(resolvedTmp)) return;
+  if (allowProductionPath) return;
+  throw new Error(
+    `ArchitectureArtifactsWriter: refusing to write to non-tmp path ${resolvedRoot}. Pass { allowProductionPath: true } for production CLI writes, or target a tmpdir-based path in tests.`
+  );
+}
+
+// src/core/overlay/community-detector.ts
+import { UndirectedGraph } from "graphology";
+import louvainModule from "graphology-communities-louvain";
+
+// src/core/overlay/community-labeler.ts
+var MIN_PREFIX_SEGMENTS = 1;
+var PATH_SEPARATOR = "/";
+function labelCommunities(membersByCommunity, pagerank) {
+  const labels = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set();
+  for (const [communityId, members] of membersByCommunity) {
+    const label = pickLabel(members, pagerank, used);
+    labels.set(communityId, label);
+    used.add(label);
+  }
+  return labels;
+}
+function pickLabel(members, pagerank, used) {
+  const files = members.map(extractFilePath).filter((file) => Boolean(file));
+  const prefixLabel = longestCommonPathPrefix(files);
+  if (prefixLabel && !used.has(prefixLabel)) {
+    return prefixLabel;
+  }
+  const topSymbol = pickTopByPagerank(members, pagerank);
+  if (topSymbol) {
+    const name = extractSymbolName(topSymbol);
+    if (name) {
+      const candidate = `${name} area`;
+      if (!used.has(candidate)) return candidate;
+    }
+  }
+  if (prefixLabel) {
+    return disambiguate(prefixLabel, used);
+  }
+  return disambiguate("cluster", used);
+}
+function extractFilePath(symbolId) {
+  const parts = symbolId.split("::");
+  return parts.length === 3 ? parts[0] : void 0;
+}
+function extractSymbolName(symbolId) {
+  const parts = symbolId.split("::");
+  return parts.length === 3 ? parts[1] : void 0;
+}
+function longestCommonPathPrefix(files) {
+  if (files.length === 0) return void 0;
+  const normalized = files.map((file) => file.replace(/\\/g, PATH_SEPARATOR));
+  const segments = normalized.map((file) => file.split(PATH_SEPARATOR));
+  const first = segments[0];
+  let matchLength = first.length;
+  for (let i = 1; i < segments.length; i++) {
+    const current = segments[i];
+    matchLength = Math.min(matchLength, current.length);
+    for (let j = 0; j < matchLength; j++) {
+      if (current[j] !== first[j]) {
+        matchLength = j;
+        break;
+      }
+    }
+    if (matchLength === 0) break;
+  }
+  const fullMatch = matchLength === first.length && files.length === 1;
+  const keep = fullMatch ? matchLength - 1 : matchLength;
+  if (keep < MIN_PREFIX_SEGMENTS) return void 0;
+  const prefix = first.slice(0, keep).join(PATH_SEPARATOR);
+  return prefix.length > 0 ? prefix : void 0;
+}
+function pickTopByPagerank(members, pagerank) {
+  let best;
+  let bestScore = -1;
+  for (const symbolId of members) {
+    const score = pagerank.get(symbolId) ?? 0;
+    if (score > bestScore || score === bestScore && best !== void 0 && symbolId < best) {
+      bestScore = score;
+      best = symbolId;
+    }
+  }
+  return best ?? members[0];
+}
+function disambiguate(base, used) {
+  if (!used.has(base)) return base;
+  let suffix = 2;
+  while (used.has(`${base} (${suffix})`)) suffix++;
+  return `${base} (${suffix})`;
+}
+
+// src/core/overlay/community-detector.ts
+var louvain = louvainModule.default ?? louvainModule;
+var DEFAULT_RESOLUTION = 1;
+var DEFAULT_GOD_NODE_MIN_BRIDGED = 3;
+var DEFAULT_GOD_NODE_MAX_RESULTS = 25;
+var CommunityDetector = class {
+  resolution;
+  godNodeMinBridged;
+  godNodeMaxResults;
+  constructor(options = {}) {
+    this.resolution = options.resolution ?? DEFAULT_RESOLUTION;
+    this.godNodeMinBridged = options.godNodeMinBridged ?? DEFAULT_GOD_NODE_MIN_BRIDGED;
+    this.godNodeMaxResults = options.godNodeMaxResults ?? DEFAULT_GOD_NODE_MAX_RESULTS;
+  }
+  detect(graph, pagerank, edgeQuality = "full") {
+    const nodes = graph.allNodes();
+    if (nodes.length === 0) {
+      return {
+        communities: [],
+        godNodes: [],
+        modularity: 0,
+        crossClusterEdges: 0,
+        edgeQuality
+      };
+    }
+    const sortedNodes = [...nodes].sort(
+      (a, b) => a.symbolId < b.symbolId ? -1 : a.symbolId > b.symbolId ? 1 : 0
+    );
+    const gph = new UndirectedGraph();
+    for (const node of sortedNodes) {
+      gph.addNode(node.symbolId);
+    }
+    const weightByPair = /* @__PURE__ */ new Map();
+    for (const edge of graph.allEdges()) {
+      if (edge.from === edge.to) continue;
+      if (!gph.hasNode(edge.from) || !gph.hasNode(edge.to)) continue;
+      const [a, b] = edge.from < edge.to ? [edge.from, edge.to] : [edge.to, edge.from];
+      const key = `${a}|${b}`;
+      weightByPair.set(key, (weightByPair.get(key) ?? 0) + 1);
+    }
+    for (const [key, weight] of weightByPair) {
+      const [from, to] = key.split("|");
+      gph.addEdge(from, to, { weight });
+    }
+    if (gph.size === 0) {
+      return {
+        communities: this.singletonCommunities(sortedNodes),
+        godNodes: [],
+        modularity: 0,
+        crossClusterEdges: 0,
+        edgeQuality
+      };
+    }
+    const result = louvain.detailed(gph, {
+      resolution: this.resolution,
+      randomWalk: false,
+      fastLocalMoves: true,
+      getEdgeWeight: "weight"
+    });
+    const rawAssignments = result.communities;
+    const splitAssignments = this.splitDisconnectedCommunities(gph, rawAssignments);
+    const normalizedAssignments = this.normalizeCommunityIds(splitAssignments, sortedNodes);
+    const memberIndex = this.buildMemberIndex(normalizedAssignments);
+    const labels = labelCommunities(memberIndex, pagerank);
+    const communities = sortedNodes.map((node) => {
+      const communityId = normalizedAssignments.get(node.symbolId) ?? 0;
+      return {
+        symbolId: node.symbolId,
+        communityId,
+        communityLabel: labels.get(communityId) ?? `community-${communityId}`
+      };
+    });
+    const crossClusterEdges = this.countCrossClusterEdges(graph, normalizedAssignments);
+    const godNodes = this.detectGodNodes(graph, normalizedAssignments, pagerank);
+    return {
+      communities,
+      godNodes,
+      modularity: result.modularity,
+      crossClusterEdges,
+      edgeQuality
+    };
+  }
+  singletonCommunities(nodes) {
+    return nodes.map((node, i) => ({
+      symbolId: node.symbolId,
+      communityId: i,
+      communityLabel: `isolated-${i}`
+    }));
+  }
+  splitDisconnectedCommunities(gph, assignments) {
+    const result = /* @__PURE__ */ new Map();
+    const membersByCommunity = /* @__PURE__ */ new Map();
+    for (const [node, communityId] of Object.entries(assignments)) {
+      const list = membersByCommunity.get(communityId) ?? [];
+      list.push(node);
+      membersByCommunity.set(communityId, list);
+    }
+    let nextCommunityId = 0;
+    const sortedCommunities = [...membersByCommunity.entries()].sort(([a], [b]) => a - b);
+    for (const [, members] of sortedCommunities) {
+      const visited = /* @__PURE__ */ new Set();
+      for (const start of [...members].sort()) {
+        if (visited.has(start)) continue;
+        const componentId = nextCommunityId++;
+        const queue = [start];
+        visited.add(start);
+        while (queue.length > 0) {
+          const node = queue.shift();
+          result.set(node, componentId);
+          for (const neighbor of gph.neighbors(node)) {
+            if (visited.has(neighbor)) continue;
+            if (!members.includes(neighbor)) continue;
+            visited.add(neighbor);
+            queue.push(neighbor);
+          }
+        }
+      }
+    }
+    return result;
+  }
+  normalizeCommunityIds(assignments, sortedNodes) {
+    const remap = /* @__PURE__ */ new Map();
+    const result = /* @__PURE__ */ new Map();
+    let nextId = 0;
+    for (const node of sortedNodes) {
+      const raw = assignments.get(node.symbolId);
+      if (raw === void 0) {
+        result.set(node.symbolId, nextId);
+        remap.set(nextId, nextId);
+        nextId++;
+        continue;
+      }
+      let normalized = remap.get(raw);
+      if (normalized === void 0) {
+        normalized = nextId++;
+        remap.set(raw, normalized);
+      }
+      result.set(node.symbolId, normalized);
+    }
+    return result;
+  }
+  buildMemberIndex(assignments) {
+    const index = /* @__PURE__ */ new Map();
+    for (const [symbolId, communityId] of assignments) {
+      const list = index.get(communityId) ?? [];
+      list.push(symbolId);
+      index.set(communityId, list);
+    }
+    for (const list of index.values()) list.sort();
+    return index;
+  }
+  countCrossClusterEdges(graph, assignments) {
+    let count = 0;
+    for (const edge of graph.allEdges()) {
+      const from = assignments.get(edge.from);
+      const to = assignments.get(edge.to);
+      if (from === void 0 || to === void 0) continue;
+      if (from !== to) count++;
+    }
+    return count;
+  }
+  detectGodNodes(graph, assignments, pagerank) {
+    const candidates = [];
+    for (const node of graph.allNodes()) {
+      const ownCommunity = assignments.get(node.symbolId);
+      if (ownCommunity === void 0) continue;
+      const bridged = /* @__PURE__ */ new Set();
+      const forward = graph.getForwardEdges(node.symbolId);
+      const reverse = graph.getReverseEdges(node.symbolId);
+      for (const edge of forward) {
+        const other = assignments.get(edge.to);
+        if (other !== void 0 && other !== ownCommunity) bridged.add(other);
+      }
+      for (const edge of reverse) {
+        const other = assignments.get(edge.from);
+        if (other !== void 0 && other !== ownCommunity) bridged.add(other);
+      }
+      if (bridged.size >= this.godNodeMinBridged) {
+        const pr = pagerank.get(node.symbolId) ?? 0;
+        candidates.push({
+          symbolId: node.symbolId,
+          bridgedCommunities: [...bridged].sort((a, b) => a - b),
+          centralityScore: bridged.size * (pr > 0 ? pr : 1 / graph.nodeCount)
+        });
+      }
+    }
+    candidates.sort((a, b) => {
+      if (b.centralityScore !== a.centralityScore) {
+        return b.centralityScore - a.centralityScore;
+      }
+      return a.symbolId.localeCompare(b.symbolId);
+    });
+    return candidates.slice(0, this.godNodeMaxResults);
+  }
+};
+
 // src/cli/index-command.ts
 var requireCjs = createRequire2(import.meta.url);
 var IndexCommand = class {
@@ -704,7 +1043,7 @@ var IndexCommand = class {
   supportedExtensions;
   constructor(projectRoot, ctxoRoot) {
     this.projectRoot = projectRoot;
-    this.ctxoRoot = ctxoRoot ?? join7(projectRoot, ".ctxo");
+    this.ctxoRoot = ctxoRoot ?? join8(projectRoot, ".ctxo");
     this.supportedExtensions = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".go", ".cs"]);
   }
   loadIgnoreConfig() {
@@ -742,7 +1081,7 @@ var IndexCommand = class {
     const revertDetector = new RevertDetector();
     let files;
     if (options.file) {
-      const fullPath = join7(this.projectRoot, options.file);
+      const fullPath = join8(this.projectRoot, options.file);
       files = [fullPath];
       console.error(`[ctxo] Incremental re-index: ${options.file}`);
     } else {
@@ -754,6 +1093,14 @@ var IndexCommand = class {
       }
       console.error(`[ctxo] Building codebase index... Found ${files.length} source files`);
     }
+    try {
+      const { sweepStaleTmpFiles } = await import("./atomic-write-AQNYJFAG.js");
+      const swept = sweepStaleTmpFiles(join8(this.ctxoRoot, "index"));
+      if (swept > 0) {
+        console.error(`[ctxo] Cleaned ${swept} orphan .tmp file(s) from previous interrupted run`);
+      }
+    } catch {
+    }
     if (roslynAdapter?.isReady()) {
       const hasCsFiles = files.some((f) => f.endsWith(".cs"));
       if (hasCsFiles) {
@@ -768,7 +1115,7 @@ var IndexCommand = class {
       if (!adapter) continue;
       const relativePath = relative(this.projectRoot, filePath).replace(/\\/g, "/");
       try {
-        const source = readFileSync5(filePath, "utf-8");
+        const source = readFileSync6(filePath, "utf-8");
         const lastModified = Math.floor(Date.now() / 1e3);
         const symbols = await adapter.extractSymbols(relativePath, source);
         const complexity = await adapter.extractComplexity(relativePath, source);
@@ -833,19 +1180,52 @@ var IndexCommand = class {
       writer.writeCoChanges(coChangeMatrix);
       console.error(`[ctxo] Co-change analysis: ${coChangeMatrix.entries.length} file pairs detected`);
     }
+    let communitySnapshot;
+    if (options.skipCommunity && pendingIndices.length > 0) {
+      if (existsSync9(join8(this.ctxoRoot, "index", "communities.json"))) {
+        console.error(
+          `[ctxo] WARN stale communities.json present \u2014 --skip-community preserved existing snapshot. Run \`ctxo index\` (full) to refresh.`
+        );
+      }
+    } else if (pendingIndices.length > 0) {
+      try {
+        const graphIndices = this.buildGraphInputIndices(pendingIndices);
+        communitySnapshot = this.buildCommunitySnapshot(
+          graphIndices,
+          {
+            csharpTier,
+            goTier,
+            tsCount: graphIndices.filter((idx) => /\.(ts|tsx|js|jsx)$/.test(idx.file)).length
+          },
+          gitAdapter
+        );
+        const scope = options.file ? " (incremental, full-graph recompute)" : "";
+        console.error(
+          `[ctxo] Community detection${scope}: ${countCommunities(communitySnapshot)} clusters (modularity ${communitySnapshot.modularity.toFixed(3)})`
+        );
+      } catch (err) {
+        console.error(`[ctxo] Community detection skipped: ${err.message}`);
+      }
+    }
     const indices = [];
     for (const { fileIndex } of pendingIndices) {
       writer.write(fileIndex);
       indices.push(fileIndex);
     }
     schemaManager.writeVersion();
-    const storage = new SqliteStorageAdapter(this.ctxoRoot);
+    const storage = new SqliteStorageAdapter(this.ctxoRoot, { allowProductionPath: true });
     try {
       await storage.initEmpty();
       storage.bulkWrite(indices);
+      if (communitySnapshot) {
+        storage.writeCommunities(communitySnapshot);
+      }
     } finally {
       storage.close();
     }
+    if (communitySnapshot) {
+      this.writeArchitectureArtifacts(indices, communitySnapshot);
+    }
     if (!options.skipSideEffects) {
       this.ensureGitignore();
     }
@@ -927,36 +1307,36 @@ var IndexCommand = class {
         encoding: "utf-8",
         maxBuffer: 10 * 1024 * 1024
       });
-      return output.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).filter((line) => this.isSupportedExtension(line)).map((line) => join7(root, line)).filter((abs) => {
+      return output.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).filter((line) => this.isSupportedExtension(line)).map((line) => join8(root, line)).filter((abs) => {
         const rel = relative(this.projectRoot, abs).replace(/\\/g, "/");
         return !ignoreFile(rel);
-      });
+      }).filter((abs) => existsSync9(abs));
     } catch {
       console.error(`[ctxo] git ls-files failed for ${root}`);
       return [];
     }
   }
   discoverWorkspaces(ignoreProject = () => false) {
-    const pkgPath = join7(this.projectRoot, "package.json");
-    if (!existsSync8(pkgPath)) return [this.projectRoot];
+    const pkgPath = join8(this.projectRoot, "package.json");
+    if (!existsSync9(pkgPath)) return [this.projectRoot];
     try {
-      const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync6(pkgPath, "utf-8"));
       const workspaces = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces?.packages;
       if (!workspaces || workspaces.length === 0) return [this.projectRoot];
       const resolved = [];
       for (const ws of workspaces) {
         if (ws.endsWith("/*") || ws.endsWith("\\*")) {
-          const parentDir = join7(this.projectRoot, ws.slice(0, -2));
-          if (existsSync8(parentDir)) {
+          const parentDir = join8(this.projectRoot, ws.slice(0, -2));
+          if (existsSync9(parentDir)) {
             for (const entry of readdirSync2(parentDir, { withFileTypes: true })) {
               if (entry.isDirectory()) {
-                resolved.push(join7(parentDir, entry.name));
+                resolved.push(join8(parentDir, entry.name));
               }
             }
           }
         } else {
-          const wsPath = join7(this.projectRoot, ws);
-          if (existsSync8(wsPath)) {
+          const wsPath = join8(this.projectRoot, ws);
+          if (existsSync9(wsPath)) {
             resolved.push(wsPath);
           }
         }
@@ -989,7 +1369,7 @@ var IndexCommand = class {
     if (_roslyn) await _roslyn.dispose();
     const hasher = new ContentHasher();
     const files = this.discoverFilesIn(this.projectRoot);
-    const reader = new (await import("./json-index-reader-LME4EDA5.js")).JsonIndexReader(this.ctxoRoot);
+    const reader = new (await import("./json-index-reader-XOEE6VMD.js")).JsonIndexReader(this.ctxoRoot);
     const indices = reader.readAll();
     const indexedMap = new Map(indices.map((i) => [i.file, i]));
     let staleCount = 0;
@@ -1002,7 +1382,7 @@ var IndexCommand = class {
         staleCount++;
         continue;
       }
-      if (!existsSync8(filePath)) {
+      if (!existsSync9(filePath)) {
         console.error(`[ctxo] DELETED: ${relativePath}`);
         staleCount++;
         continue;
@@ -1010,11 +1390,15 @@ var IndexCommand = class {
       const mtime = Math.floor(statSync(filePath).mtimeMs / 1e3);
       if (mtime <= indexed.lastModified) continue;
       if (indexed.contentHash) {
-        const source = readFileSync5(filePath, "utf-8");
+        const source = readFileSync6(filePath, "utf-8");
         const currentHash = hasher.hash(source);
         if (currentHash === indexed.contentHash) continue;
+        console.error(`[ctxo] STALE: ${relativePath} (content hash differs)`);
+      } else {
+        console.error(
+          `[ctxo] STALE: ${relativePath} (index predates contentHash \u2014 run \`ctxo index\` once to enable mtime-tolerant checks)`
+        );
       }
-      console.error(`[ctxo] STALE: ${relativePath}`);
       staleCount++;
     }
     if (staleCount > 0) {
@@ -1024,29 +1408,166 @@ var IndexCommand = class {
     console.error("[ctxo] Index is up to date");
   }
   ensureGitignore() {
-    const gitignorePath = join7(this.projectRoot, ".gitignore");
+    const gitignorePath = join8(this.projectRoot, ".gitignore");
     const cachePattern = ".ctxo/.cache/";
     const suffix = `
 # Ctxo local cache (never committed)
 ${cachePattern}
 `;
-    const existing = existsSync8(gitignorePath) ? readFileSync5(gitignorePath, "utf-8") : "";
+    const existing = existsSync9(gitignorePath) ? readFileSync6(gitignorePath, "utf-8") : "";
     if (existing.includes(cachePattern)) return;
-    writeFileSync3(gitignorePath, existing + suffix, "utf-8");
+    writeFileSync2(gitignorePath, existing + suffix, "utf-8");
     console.error("[ctxo] Added .ctxo/.cache/ to .gitignore");
   }
+  /**
+   * Produce the FileIndex list used as input to community detection.
+   *
+   * Full index run: returns pendingIndices as-is — they already cover every file.
+   * Incremental `--file` run: pendingIndices holds only the just-updated file(s). We load the
+   * rest of the committed JSON index from disk and splice in the fresh in-memory indices so
+   * Louvain sees the COMPLETE project graph. Without this, Louvain would run on a 1-file
+   * subgraph and emit a meaningless modularity-0 snapshot.
+   */
+  buildGraphInputIndices(pendingIndices) {
+    const pendingByPath = /* @__PURE__ */ new Map();
+    for (const { fileIndex } of pendingIndices) {
+      pendingByPath.set(fileIndex.file, fileIndex);
+    }
+    const reader = new JsonIndexReader(this.ctxoRoot);
+    const committed = reader.readAll();
+    const merged = [];
+    for (const idx of committed) {
+      const override = pendingByPath.get(idx.file);
+      if (override) {
+        merged.push(override);
+        pendingByPath.delete(idx.file);
+      } else {
+        merged.push(idx);
+      }
+    }
+    for (const remaining of pendingByPath.values()) merged.push(remaining);
+    return merged;
+  }
+  buildCommunitySnapshot(indices, tiers, gitAdapter) {
+    const graph = new SymbolGraph();
+    for (const fileIndex of indices) {
+      for (const symbol of fileIndex.symbols) graph.addNode(symbol);
+    }
+    for (const fileIndex of indices) {
+      for (const edge of fileIndex.edges) graph.addEdge(edge);
+    }
+    const pagerank = new PageRankCalculator().calculate(graph, { limit: graph.nodeCount });
+    const pagerankMap = /* @__PURE__ */ new Map();
+    for (const entry of pagerank.rankings) pagerankMap.set(entry.symbolId, entry.score);
+    const detector = new CommunityDetector();
+    const edgeQuality = pickEdgeQuality(tiers);
+    const detectResult = detector.detect(graph, pagerankMap, edgeQuality);
+    return {
+      version: 1,
+      computedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      commitSha: safeHeadSha(gitAdapter),
+      modularity: detectResult.modularity,
+      communities: detectResult.communities,
+      godNodes: detectResult.godNodes,
+      edgeQuality: detectResult.edgeQuality,
+      crossClusterEdges: detectResult.crossClusterEdges
+    };
+  }
+  /**
+   * Writes drift-events.json and boundary-violations.json next to
+   * communities.json. Must be called AFTER storage.writeCommunities so the
+   * prior snapshot has already been archived into communities.history/ and
+   * can serve as history[0] for the detectors.
+   */
+  writeArchitectureArtifacts(indices, snapshot) {
+    try {
+      const snapshotWriter = new CommunitySnapshotWriter(this.ctxoRoot, {
+        allowProductionPath: true
+      });
+      const history = snapshotWriter.listHistory();
+      const graph = new SymbolGraph();
+      for (const fileIndex of indices) {
+        for (const symbol of fileIndex.symbols) graph.addNode(symbol);
+      }
+      for (const fileIndex of indices) {
+        for (const edge of fileIndex.edges) graph.addEdge(edge);
+      }
+      const driftResult = new DriftDetector().detect(snapshot, history);
+      const violationsResult = new BoundaryViolationDetector().detect(
+        graph,
+        snapshot,
+        history
+      );
+      const computedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const driftArtifact = {
+        version: 1,
+        computedAt,
+        commitSha: snapshot.commitSha,
+        confidence: driftResult.confidence,
+        snapshotsAvailable: driftResult.snapshotsAvailable,
+        ...driftResult.hint ? { hint: driftResult.hint } : {},
+        events: driftResult.events
+      };
+      const violationsArtifact = {
+        version: 1,
+        computedAt,
+        commitSha: snapshot.commitSha,
+        confidence: violationsResult.confidence,
+        snapshotsAvailable: violationsResult.snapshotsAvailable,
+        ...violationsResult.hint ? { hint: violationsResult.hint } : {},
+        violations: violationsResult.violations
+      };
+      const writer = new ArchitectureArtifactsWriter(this.ctxoRoot, {
+        allowProductionPath: true
+      });
+      writer.writeDriftEvents(driftArtifact);
+      writer.writeBoundaryViolations(violationsArtifact);
+      console.error(
+        `[ctxo] Architecture artifacts: ${driftResult.events.length} drift events, ${violationsResult.violations.length} boundary violations (confidence: drift=${driftResult.confidence}, violations=${violationsResult.confidence})`
+      );
+    } catch (err) {
+      console.error(
+        `[ctxo] Architecture artifacts skipped: ${err.message}`
+      );
+    }
+  }
 };
+function pickEdgeQuality(tiers) {
+  const hasSyntaxOnly = tiers.csharpTier === "syntax" || tiers.goTier === "syntax";
+  const hasFull = tiers.tsCount > 0 || tiers.csharpTier === "full" || tiers.goTier === "full";
+  if (hasSyntaxOnly && hasFull) return "mixed";
+  if (hasSyntaxOnly) return "syntax-only";
+  return "full";
+}
+function safeHeadSha(gitAdapter) {
+  try {
+    const maybeSha = gitAdapter.getHeadSha?.();
+    if (maybeSha) return maybeSha.slice(0, 8);
+  } catch {
+  }
+  try {
+    const out = execFileSync2("git", ["rev-parse", "--short", "HEAD"], { encoding: "utf-8" });
+    return out.trim();
+  } catch {
+    return "nocommit";
+  }
+}
+function countCommunities(snapshot) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const entry of snapshot.communities) ids.add(entry.communityId);
+  return ids.size;
+}
 
 // src/cli/sync-command.ts
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 var SyncCommand = class {
   ctxoRoot;
   constructor(projectRoot) {
-    this.ctxoRoot = join8(projectRoot, ".ctxo");
+    this.ctxoRoot = join9(projectRoot, ".ctxo");
   }
   async run() {
     console.error("[ctxo] Rebuilding SQLite cache from committed JSON index...");
-    const storage = new SqliteStorageAdapter(this.ctxoRoot);
+    const storage = new SqliteStorageAdapter(this.ctxoRoot, { allowProductionPath: true });
     try {
       await storage.init();
     } finally {
@@ -1057,19 +1578,19 @@ var SyncCommand = class {
 };
 
 // src/cli/status-command.ts
-import { join as join9 } from "path";
-import { existsSync as existsSync9 } from "fs";
+import { join as join10 } from "path";
+import { existsSync as existsSync10 } from "fs";
 import { execFileSync as execFileSync3 } from "child_process";
 var StatusCommand = class {
   projectRoot;
   ctxoRoot;
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.ctxoRoot = join9(projectRoot, ".ctxo");
+    this.ctxoRoot = join10(projectRoot, ".ctxo");
   }
   run() {
-    const indexDir = join9(this.ctxoRoot, "index");
-    if (!existsSync9(indexDir)) {
+    const indexDir = join10(this.ctxoRoot, "index");
+    if (!existsSync10(indexDir)) {
       console.error('[ctxo] No index found. Run "ctxo index" first.');
       return;
     }
@@ -1084,7 +1605,7 @@ var StatusCommand = class {
     console.error(`  Indexed files:  ${indices.length}`);
     console.error(`  Total symbols:  ${totalSymbols}`);
     console.error(`  Total edges:    ${totalEdges}`);
-    const cacheExists = existsSync9(join9(this.ctxoRoot, ".cache", "symbols.db"));
+    const cacheExists = existsSync10(join10(this.ctxoRoot, ".cache", "symbols.db"));
     console.error(`  SQLite cache:   ${cacheExists ? "present" : "missing (run ctxo sync)"}`);
     if (indices.length > 0) {
       console.error("");
@@ -1113,8 +1634,8 @@ var StatusCommand = class {
 
 // src/cli/verify-command.ts
 import { mkdtempSync, rmSync } from "fs";
-import { join as join10 } from "path";
-import { tmpdir } from "os";
+import { join as join11 } from "path";
+import { tmpdir as tmpdir2 } from "os";
 var VerifyCommand = class {
   projectRoot;
   constructor(projectRoot) {
@@ -1122,12 +1643,12 @@ var VerifyCommand = class {
   }
   async run() {
     console.error("[ctxo] Verifying index freshness...");
-    const tempDir = mkdtempSync(join10(tmpdir(), "ctxo-verify-"));
+    const tempDir = mkdtempSync(join11(tmpdir2(), "ctxo-verify-"));
     try {
-      const tempCtxo = join10(tempDir, ".ctxo");
+      const tempCtxo = join11(tempDir, ".ctxo");
       const indexCmd = new IndexCommand(this.projectRoot, tempCtxo);
       await indexCmd.run({ skipSideEffects: true });
-      const committedReader = new JsonIndexReader(join10(this.projectRoot, ".ctxo"));
+      const committedReader = new JsonIndexReader(join11(this.projectRoot, ".ctxo"));
       const freshReader = new JsonIndexReader(tempCtxo);
       const committedIndices = committedReader.readAll();
       const freshIndices = freshReader.readAll();
@@ -1160,13 +1681,13 @@ var VerifyCommand = class {
 };
 
 // src/cli/init-command.ts
-import { join as join12 } from "path";
-import { existsSync as existsSync11, readFileSync as readFileSync7, writeFileSync as writeFileSync5, mkdirSync as mkdirSync4, chmodSync } from "fs";
+import { join as join13 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync8, writeFileSync as writeFileSync4, mkdirSync as mkdirSync5, chmodSync } from "fs";
 import { createRequire as createRequire3 } from "module";
 
 // src/cli/ai-rules.ts
-import { existsSync as existsSync10, readFileSync as readFileSync6, writeFileSync as writeFileSync4, mkdirSync as mkdirSync3 } from "fs";
-import { join as join11, dirname as dirname6 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync7, writeFileSync as writeFileSync3, mkdirSync as mkdirSync4 } from "fs";
+import { join as join12, dirname as dirname6 } from "path";
 var PLATFORMS = [
   { id: "claude-code", name: "Claude Code", file: "CLAUDE.md", mode: "append", detectPaths: ["CLAUDE.md", ".claude"], starred: true },
   { id: "cursor", name: "Cursor", file: ".cursor/rules/ctxo.mdc", mode: "create", detectPaths: [".cursor", ".cursorrules"], starred: false },
@@ -1179,7 +1700,7 @@ var PLATFORMS = [
 function detectPlatforms(projectRoot) {
   const detected = /* @__PURE__ */ new Set();
   for (const p of PLATFORMS) {
-    if (p.detectPaths.some((d) => existsSync10(join11(projectRoot, d)))) {
+    if (p.detectPaths.some((d) => existsSync11(join12(projectRoot, d)))) {
       detected.add(p.id);
     }
   }
@@ -1241,31 +1762,31 @@ function generateRules(platformId) {
 function installRules(projectRoot, platformId) {
   const platform = PLATFORMS.find((p) => p.id === platformId);
   if (!platform) throw new Error(`Unknown platform: ${platformId}`);
-  const filePath = join11(projectRoot, platform.file);
+  const filePath = join12(projectRoot, platform.file);
   const content = generateRules(platformId);
   const dir = dirname6(filePath);
-  if (!existsSync10(dir)) mkdirSync3(dir, { recursive: true });
+  if (!existsSync11(dir)) mkdirSync4(dir, { recursive: true });
   if (platform.mode === "create") {
-    writeFileSync4(filePath, content, "utf-8");
-    return { file: platform.file, action: existsSync10(filePath) ? "updated" : "created" };
+    writeFileSync3(filePath, content, "utf-8");
+    return { file: platform.file, action: existsSync11(filePath) ? "updated" : "created" };
   }
-  if (!existsSync10(filePath)) {
-    writeFileSync4(filePath, content, "utf-8");
+  if (!existsSync11(filePath)) {
+    writeFileSync3(filePath, content, "utf-8");
     return { file: platform.file, action: "created" };
   }
-  const existing = readFileSync6(filePath, "utf-8");
+  const existing = readFileSync7(filePath, "utf-8");
   if (existing.includes(SECTION_START)) {
     const re = new RegExp(`${escapeRegExp(SECTION_START)}[\\s\\S]*?${escapeRegExp(SECTION_END)}`, "m");
     const updated2 = existing.replace(re, `${SECTION_START}
 ${content}${SECTION_END}`);
-    writeFileSync4(filePath, updated2, "utf-8");
+    writeFileSync3(filePath, updated2, "utf-8");
     return { file: platform.file, action: "updated" };
   }
   const separator = existing.endsWith("\n") ? "\n" : "\n\n";
   const updated = existing + separator + `${SECTION_START}
 ${content}${SECTION_END}
 `;
-  writeFileSync4(filePath, updated, "utf-8");
+  writeFileSync3(filePath, updated, "utf-8");
   return { file: platform.file, action: "updated" };
 }
 function escapeRegExp(s) {
@@ -1273,14 +1794,14 @@ function escapeRegExp(s) {
 }
 var GITIGNORE_ENTRY = ".ctxo/.cache/";
 function ensureGitignore(projectRoot) {
-  const filePath = join11(projectRoot, ".gitignore");
-  if (!existsSync10(filePath)) {
-    writeFileSync4(filePath, `# Ctxo local cache (auto-rebuilt, never committed)
+  const filePath = join12(projectRoot, ".gitignore");
+  if (!existsSync11(filePath)) {
+    writeFileSync3(filePath, `# Ctxo local cache (auto-rebuilt, never committed)
 ${GITIGNORE_ENTRY}
 `, "utf-8");
     return { file: ".gitignore", action: "created" };
   }
-  const existing = readFileSync6(filePath, "utf-8");
+  const existing = readFileSync7(filePath, "utf-8");
   if (existing.includes(GITIGNORE_ENTRY)) {
     return { file: ".gitignore", action: "skipped" };
   }
@@ -1288,7 +1809,7 @@ ${GITIGNORE_ENTRY}
   const updated = existing + `${separator}# Ctxo local cache (auto-rebuilt, never committed)
 ${GITIGNORE_ENTRY}
 `;
-  writeFileSync4(filePath, updated, "utf-8");
+  writeFileSync3(filePath, updated, "utf-8");
   return { file: ".gitignore", action: "updated" };
 }
 var DEFAULT_CONFIG = `# ctxo project configuration
@@ -1311,13 +1832,13 @@ index:
   # - "examples/*"
 `;
 function ensureConfig(projectRoot) {
-  const filePath = join11(projectRoot, ".ctxo", "config.yaml");
+  const filePath = join12(projectRoot, ".ctxo", "config.yaml");
   const dir = dirname6(filePath);
-  if (!existsSync10(dir)) mkdirSync3(dir, { recursive: true });
-  if (existsSync10(filePath)) {
+  if (!existsSync11(dir)) mkdirSync4(dir, { recursive: true });
+  if (existsSync11(filePath)) {
     return { file: ".ctxo/config.yaml", action: "skipped" };
   }
-  writeFileSync4(filePath, DEFAULT_CONFIG, "utf-8");
+  writeFileSync3(filePath, DEFAULT_CONFIG, "utf-8");
   return { file: ".ctxo/config.yaml", action: "created" };
 }
 var CTXO_MCP_ENTRY = { command: "npx", args: ["-y", "@ctxo/cli"] };
@@ -1343,21 +1864,21 @@ function getMcpConfigTargets(selectedPlatformIds) {
   return [...targets.values()];
 }
 function ensureMcpConfig(projectRoot, target) {
-  const filePath = join11(projectRoot, target.file);
+  const filePath = join12(projectRoot, target.file);
   const dir = dirname6(filePath);
-  if (!existsSync10(dir)) mkdirSync3(dir, { recursive: true });
+  if (!existsSync11(dir)) mkdirSync4(dir, { recursive: true });
   const entry = target.extraFields ? { ...target.extraFields, ...CTXO_MCP_ENTRY } : { ...CTXO_MCP_ENTRY };
-  if (!existsSync10(filePath)) {
+  if (!existsSync11(filePath)) {
     const config = { [target.serverKey]: { ctxo: entry } };
-    writeFileSync4(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    writeFileSync3(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
     return { file: target.file, action: "created" };
   }
   let existing;
   try {
-    existing = JSON.parse(readFileSync6(filePath, "utf-8"));
+    existing = JSON.parse(readFileSync7(filePath, "utf-8"));
   } catch {
     const config = { [target.serverKey]: { ctxo: entry } };
-    writeFileSync4(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    writeFileSync3(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
     return { file: target.file, action: "updated" };
   }
   const servers = existing[target.serverKey] ?? {};
@@ -1366,7 +1887,7 @@ function ensureMcpConfig(projectRoot, target) {
   }
   servers["ctxo"] = entry;
   existing[target.serverKey] = servers;
-  writeFileSync4(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+  writeFileSync3(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
   return { file: target.file, action: "updated" };
 }
 
@@ -1463,13 +1984,13 @@ var InitCommand = class {
     this.projectRoot = projectRoot;
   }
   installHooks() {
-    const hooksDir = join12(this.projectRoot, ".git", "hooks");
-    mkdirSync4(hooksDir, { recursive: true });
+    const hooksDir = join13(this.projectRoot, ".git", "hooks");
+    mkdirSync5(hooksDir, { recursive: true });
     this.installHook(hooksDir, "post-commit", POST_COMMIT_CONTENT);
     this.installHook(hooksDir, "post-merge", POST_MERGE_CONTENT);
   }
   async run(options = {}) {
-    if (!existsSync11(join12(this.projectRoot, ".git"))) {
+    if (!existsSync12(join13(this.projectRoot, ".git"))) {
       console.error('[ctxo] Not a git repository. Run "git init" first.');
       process.exit(1);
     }
@@ -1506,8 +2027,8 @@ var InitCommand = class {
         clack.cancel("Setup cancelled.");
         process.exit(0);
       }
-      const fullPath = join12(this.projectRoot, indexDir);
-      if (!existsSync11(fullPath)) mkdirSync4(fullPath, { recursive: true });
+      const fullPath = join13(this.projectRoot, indexDir);
+      if (!existsSync12(fullPath)) mkdirSync5(fullPath, { recursive: true });
       console.error("");
     }
     stepNum++;
@@ -1569,7 +2090,13 @@ var InitCommand = class {
     let installGitHooks = false;
     if (!options.rulesOnly) {
       stepNum++;
-      console.error(stepHeader(stepNum, totalSteps, `Git Hooks ${pc.yellow("recommended")}`, "Auto-updates index on every commit and pull.", pc));
+      console.error(stepHeader(
+        stepNum,
+        totalSteps,
+        `Git Hooks ${pc.yellow("recommended")}`,
+        "Auto-updates index and community snapshots on every commit and pull.\n  Without hooks, architectural drift & boundary violation signals stay empty\n  until you re-run `ctxo index` manually (or start `ctxo watch`).",
+        pc
+      ));
       console.error("");
       const hooks = await clack.confirm({
         message: pc.cyan("Install hooks?"),
@@ -1580,6 +2107,14 @@ var InitCommand = class {
         process.exit(0);
       }
       installGitHooks = hooks;
+      if (!installGitHooks) {
+        console.error("");
+        console.error(pc.yellow("  \u26A0 Drift & boundary-violation signals depend on repeated snapshots."));
+        console.error(pc.dim("    Options without hooks:"));
+        console.error(pc.dim("      \u2022 run `ctxo watch` during development"));
+        console.error(pc.dim("      \u2022 add `ctxo index --check` to CI"));
+        console.error(pc.dim("      \u2022 run `ctxo init` again to install hooks later"));
+      }
       console.error("");
     }
     const s = clack.spinner();
@@ -1650,8 +2185,8 @@ var InitCommand = class {
     const gitignoreResult = ensureGitignore(this.projectRoot);
     const configResult = ensureConfig(this.projectRoot);
     if (!options.rulesOnly) {
-      const indexDir = join12(this.projectRoot, ".ctxo", "index");
-      if (!existsSync11(indexDir)) mkdirSync4(indexDir, { recursive: true });
+      const indexDir = join13(this.projectRoot, ".ctxo", "index");
+      if (!existsSync12(indexDir)) mkdirSync5(indexDir, { recursive: true });
       console.error("[ctxo] \u2713 .ctxo/index/ ready");
     }
     if (configResult.action !== "skipped") {
@@ -1703,7 +2238,7 @@ var InitCommand = class {
     for (const id of toolIds) {
       const platform = PLATFORMS.find((p) => p.id === id);
       if (platform) {
-        const exists = existsSync11(join12(this.projectRoot, platform.file));
+        const exists = existsSync12(join13(this.projectRoot, platform.file));
         const action = platform.mode === "append" && exists ? "append section" : "create";
         console.error(`  ${platform.file.padEnd(42)} (${action})`);
       }
@@ -1718,9 +2253,9 @@ var InitCommand = class {
   /* ---------------------------------------------------------------- */
   async getVersion() {
     try {
-      const pkgPath = join12(this.projectRoot, "node_modules", "@ctxo", "cli", "package.json");
-      if (existsSync11(pkgPath)) {
-        return JSON.parse(readFileSync7(pkgPath, "utf-8")).version;
+      const pkgPath = join13(this.projectRoot, "node_modules", "@ctxo", "cli", "package.json");
+      if (existsSync12(pkgPath)) {
+        return JSON.parse(readFileSync8(pkgPath, "utf-8")).version;
       }
       const { createRequire: createRequire7 } = await import("module");
       const require4 = createRequire7(import.meta.url);
@@ -1730,23 +2265,23 @@ var InitCommand = class {
     }
   }
   installHook(hooksDir, hookName, hookContent) {
-    const hookPath = join12(hooksDir, hookName);
+    const hookPath = join13(hooksDir, hookName);
     let existing = "";
-    if (existsSync11(hookPath)) {
-      existing = readFileSync7(hookPath, "utf-8");
+    if (existsSync12(hookPath)) {
+      existing = readFileSync8(hookPath, "utf-8");
       if (existing.includes(CTXO_START)) return;
     } else {
       existing = "#!/bin/sh\n";
     }
     const updated = existing.endsWith("\n") ? existing + "\n" + hookContent + "\n" : existing + "\n\n" + hookContent + "\n";
-    writeFileSync5(hookPath, updated, "utf-8");
+    writeFileSync4(hookPath, updated, "utf-8");
     chmodSync(hookPath, 493);
   }
 };
 
 // src/cli/watch-command.ts
-import { join as join13, extname as extname4, relative as relative2 } from "path";
-import { readFileSync as readFileSync8 } from "fs";
+import { join as join14, extname as extname4, relative as relative2 } from "path";
+import { readFileSync as readFileSync9 } from "fs";
 
 // src/adapters/watcher/chokidar-watcher-adapter.ts
 import { watch } from "chokidar";
@@ -1787,13 +2322,15 @@ var ChokidarWatcherAdapter = class {
 };
 
 // src/cli/watch-command.ts
+import { execFileSync as execFileSync4 } from "child_process";
 var DEBOUNCE_MS = 300;
+var COMMUNITY_SNAPSHOT_DEBOUNCE_MS = 5e3;
 var WatchCommand = class {
   projectRoot;
   ctxoRoot;
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.ctxoRoot = join13(projectRoot, ".ctxo");
+    this.ctxoRoot = join14(projectRoot, ".ctxo");
   }
   async run() {
     console.error("[ctxo] Starting file watcher...");
@@ -1824,13 +2361,15 @@ var WatchCommand = class {
     }
     const supportedExtensions = registry.getSupportedExtensions();
     const writer = new JsonIndexWriter(this.ctxoRoot);
-    const storage = new SqliteStorageAdapter(this.ctxoRoot);
+    const storage = new SqliteStorageAdapter(this.ctxoRoot, { allowProductionPath: true });
     await storage.init();
     const hasher = new ContentHasher();
     const gitAdapter = new SimpleGitAdapter(this.projectRoot);
     const revertDetector = new RevertDetector();
     const watcher = new ChokidarWatcherAdapter(this.projectRoot);
     const pendingFiles = /* @__PURE__ */ new Map();
+    const snapshotThreshold = watchSnapshotMinFileChanges(loadConfig(this.ctxoRoot).config);
+    const pathsChangedSinceSnapshot = /* @__PURE__ */ new Set();
     const reindexFile = async (filePath) => {
       const adapter = registry.getAdapter(filePath);
       if (!adapter) return;
@@ -1847,7 +2386,7 @@ var WatchCommand = class {
               kind: "commit"
             }));
             const antiPatterns2 = revertDetector.detect(commits2);
-            const source2 = readFileSync8(filePath, "utf-8");
+            const source2 = readFileSync9(filePath, "utf-8");
             const fileIndex2 = {
               file: relativePath,
               lastModified: Math.floor(Date.now() / 1e3),
@@ -1877,7 +2416,7 @@ var WatchCommand = class {
             return;
           }
         }
-        const source = readFileSync8(filePath, "utf-8");
+        const source = readFileSync9(filePath, "utf-8");
         const lastModified = Math.floor(Date.now() / 1e3);
         const symbols = await adapter.extractSymbols(relativePath, source);
         const edges = await adapter.extractEdges(relativePath, source);
@@ -1907,14 +2446,38 @@ var WatchCommand = class {
         console.error(`[ctxo] Failed to re-index ${relativePath}: ${err.message}`);
       }
     };
+    let communitySnapshotTimer;
+    const scheduleCommunitySnapshot = () => {
+      if (pathsChangedSinceSnapshot.size < snapshotThreshold) return;
+      if (communitySnapshotTimer) clearTimeout(communitySnapshotTimer);
+      communitySnapshotTimer = setTimeout(() => {
+        communitySnapshotTimer = void 0;
+        if (pathsChangedSinceSnapshot.size < snapshotThreshold) return;
+        const changedCount = pathsChangedSinceSnapshot.size;
+        pathsChangedSinceSnapshot.clear();
+        try {
+          const snapshot = buildWatchCommunitySnapshot(storage);
+          if (snapshot) {
+            storage.writeCommunities(snapshot);
+            console.error(
+              `[ctxo] Community snapshot refreshed after ${changedCount} file change(s) (modularity ${snapshot.modularity.toFixed(3)})`
+            );
+          }
+        } catch (err) {
+          console.error(`[ctxo] Community snapshot skipped: ${err.message}`);
+        }
+      }, COMMUNITY_SNAPSHOT_DEBOUNCE_MS);
+    };
     const debouncedReindex = (filePath) => {
       const existing = pendingFiles.get(filePath);
       if (existing) clearTimeout(existing);
       pendingFiles.set(
         filePath,
-        setTimeout(() => {
+        setTimeout(async () => {
           pendingFiles.delete(filePath);
-          reindexFile(filePath);
+          await reindexFile(filePath);
+          pathsChangedSinceSnapshot.add(filePath);
+          scheduleCommunitySnapshot();
         }, DEBOUNCE_MS)
       );
     };
@@ -1936,6 +2499,7 @@ var WatchCommand = class {
       for (const timeout of pendingFiles.values()) {
         clearTimeout(timeout);
       }
+      if (communitySnapshotTimer) clearTimeout(communitySnapshotTimer);
       const roslynShutdown = roslynAdapter ? roslynAdapter.dispose() : Promise.resolve();
       roslynShutdown.then(() => {
         watcher.stop().then(() => {
@@ -1949,23 +2513,53 @@ var WatchCommand = class {
     process.on("SIGTERM", cleanup);
   }
 };
+function buildWatchCommunitySnapshot(storage) {
+  const symbols = storage.getAllSymbols();
+  if (symbols.length === 0) return void 0;
+  const edges = storage.getAllEdges();
+  const graph = new SymbolGraph();
+  for (const symbol of symbols) graph.addNode(symbol);
+  for (const edge of edges) graph.addEdge(edge);
+  const pagerank = new PageRankCalculator().calculate(graph, { limit: graph.nodeCount });
+  const pagerankMap = /* @__PURE__ */ new Map();
+  for (const entry of pagerank.rankings) pagerankMap.set(entry.symbolId, entry.score);
+  const detector = new CommunityDetector();
+  const detectResult = detector.detect(graph, pagerankMap, "full");
+  return {
+    version: 1,
+    computedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    commitSha: readHeadSha(),
+    modularity: detectResult.modularity,
+    communities: detectResult.communities,
+    godNodes: detectResult.godNodes,
+    edgeQuality: detectResult.edgeQuality,
+    crossClusterEdges: detectResult.crossClusterEdges
+  };
+}
+function readHeadSha() {
+  try {
+    return execFileSync4("git", ["rev-parse", "--short", "HEAD"], { encoding: "utf-8" }).trim();
+  } catch {
+    return "nocommit";
+  }
+}
 
 // src/cli/stats-command.ts
-import { join as join14 } from "path";
-import { existsSync as existsSync12, readFileSync as readFileSync9 } from "fs";
+import { join as join15 } from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync10 } from "fs";
 import initSqlJs from "sql.js";
 var StatsCommand = class {
   ctxoRoot;
   constructor(projectRoot) {
-    this.ctxoRoot = join14(projectRoot, ".ctxo");
+    this.ctxoRoot = join15(projectRoot, ".ctxo");
   }
   async run(options) {
     if (!this.isStatsEnabled()) {
       console.error("[ctxo] Stats collection is disabled in .ctxo/config.yaml");
       return;
     }
-    const dbPath = join14(this.ctxoRoot, ".cache", "symbols.db");
-    if (!existsSync12(dbPath)) {
+    const dbPath = join15(this.ctxoRoot, ".cache", "symbols.db");
+    if (!existsSync13(dbPath)) {
       if (options.json) {
         process.stdout.write(JSON.stringify(this.emptyReport(options.days)) + "\n");
       } else {
@@ -1974,15 +2568,15 @@ var StatsCommand = class {
       return;
     }
     const SQL = await initSqlJs();
-    const buffer = readFileSync9(dbPath);
+    const buffer = readFileSync10(dbPath);
     const db = new SQL.Database(buffer);
     const recorder = new SessionRecorderAdapter(db);
     try {
       if (options.clear) {
         recorder.clear();
         const data = db.export();
-        const { writeFileSync: writeFileSync7 } = await import("fs");
-        writeFileSync7(dbPath, Buffer.from(data));
+        const { writeFileSync: writeFileSync6 } = await import("fs");
+        writeFileSync6(dbPath, Buffer.from(data));
         console.error("[ctxo] Session data cleared.");
         return;
       }
@@ -2012,10 +2606,10 @@ var StatsCommand = class {
     }
   }
   isStatsEnabled() {
-    const configPath = join14(this.ctxoRoot, "config.yaml");
-    if (!existsSync12(configPath)) return true;
+    const configPath = join15(this.ctxoRoot, "config.yaml");
+    if (!existsSync13(configPath)) return true;
     try {
-      const raw = readFileSync9(configPath, "utf-8");
+      const raw = readFileSync10(configPath, "utf-8");
       const match = raw.match(/stats:\s*\n\s*enabled:\s*(true|false)/);
       if (match) return match[1] !== "false";
       return true;
@@ -2104,15 +2698,17 @@ var StatsCommand = class {
 };
 
 // src/cli/doctor-command.ts
-import { join as join21 } from "path";
-import { existsSync as existsSync19 } from "fs";
+import { join as join22 } from "path";
+import { existsSync as existsSync20 } from "fs";
 
 // src/adapters/diagnostics/health-checker.ts
-var log3 = createLogger("ctxo:doctor");
+var log4 = createLogger("ctxo:doctor");
 var HealthChecker = class {
   checks;
-  constructor(checks) {
+  quiet;
+  constructor(checks, options = {}) {
     this.checks = checks;
+    this.quiet = options.quiet ?? false;
   }
   async runAll(ctx) {
     const settled = await Promise.allSettled(
@@ -2122,11 +2718,13 @@ var HealthChecker = class {
       const check = this.checks[i];
       if (outcome.status === "fulfilled") {
         const r = outcome.value;
-        log3.info(`${r.id}: ${r.status.toUpperCase()} (${r.message})`);
+        if (!this.quiet) {
+          log4.info(`${r.id}: ${r.status.toUpperCase()} (${r.message})`);
+        }
         return r;
       }
       const message = outcome.reason?.message ?? "Unknown error";
-      log3.error(`${check.id}: FAIL (${message})`);
+      if (!this.quiet) log4.error(`${check.id}: FAIL (${message})`);
       return {
         id: check.id,
         title: check.title,
@@ -2437,15 +3035,15 @@ function pluginResolves(packageName) {
 }
 
 // src/adapters/diagnostics/checks/git-check.ts
-import { execFileSync as execFileSync4 } from "child_process";
-import { existsSync as existsSync13 } from "fs";
-import { join as join15 } from "path";
+import { execFileSync as execFileSync5 } from "child_process";
+import { existsSync as existsSync14 } from "fs";
+import { join as join16 } from "path";
 var GitBinaryCheck = class {
   id = "git_binary";
   title = "Git available";
   async run(_ctx) {
     try {
-      const version = execFileSync4("git", ["--version"], { encoding: "utf-8" }).trim();
+      const version = execFileSync5("git", ["--version"], { encoding: "utf-8" }).trim();
       return { id: this.id, title: this.title, status: "pass", message: version, value: version };
     } catch {
       return { id: this.id, title: this.title, status: "fail", message: "git not found in PATH", fix: "Install git and ensure it is in your PATH" };
@@ -2456,7 +3054,7 @@ var GitRepoCheck = class {
   id = "git_repo";
   title = "Git repository";
   async run(ctx) {
-    if (existsSync13(join15(ctx.projectRoot, ".git"))) {
+    if (existsSync14(join16(ctx.projectRoot, ".git"))) {
       return { id: this.id, title: this.title, status: "pass", message: ctx.projectRoot, value: ctx.projectRoot };
     }
     return { id: this.id, title: this.title, status: "fail", message: "Not a git repository", fix: 'Run "git init" or clone a repository' };
@@ -2464,9 +3062,9 @@ var GitRepoCheck = class {
 };
 
 // src/adapters/diagnostics/checks/index-check.ts
-import { existsSync as existsSync14 } from "fs";
-import { execFileSync as execFileSync5 } from "child_process";
-import { join as join16 } from "path";
+import { existsSync as existsSync15 } from "fs";
+import { execFileSync as execFileSync6 } from "child_process";
+import { join as join17 } from "path";
 function pass2(id, title, message, value) {
   return { id, title, status: "pass", message, value };
 }
@@ -2483,8 +3081,8 @@ var IndexDirectoryCheck = class {
   id = "index_directory";
   title = "Index directory";
   async run(ctx) {
-    const indexDir = join16(ctx.ctxoRoot, "index");
-    if (!existsSync14(indexDir)) {
+    const indexDir = join17(ctx.ctxoRoot, "index");
+    if (!existsSync15(indexDir)) {
       return fail(this.id, this.title, "No index directory", 'Run "ctxo index"');
     }
     const indices = getIndices(ctx);
@@ -2564,7 +3162,7 @@ var OrphanedFilesCheck = class {
   }
   getSourceFiles(projectRoot) {
     try {
-      const output = execFileSync5("git", ["ls-files", "--cached", "--others", "--exclude-standard"], {
+      const output = execFileSync6("git", ["ls-files", "--cached", "--others", "--exclude-standard"], {
         cwd: projectRoot,
         encoding: "utf-8"
       });
@@ -2578,8 +3176,8 @@ var CoChangesCacheCheck = class {
   id = "co_changes_cache";
   title = "Co-changes cache";
   async run(ctx) {
-    const coChangesPath = join16(ctx.ctxoRoot, "index", "co-changes.json");
-    if (existsSync14(coChangesPath)) {
+    const coChangesPath = join17(ctx.ctxoRoot, "index", "co-changes.json");
+    if (existsSync15(coChangesPath)) {
       return pass2(this.id, this.title, "present");
     }
     return warn2(this.id, this.title, "missing (co-change analysis disabled)", 'Run "ctxo index" with git history');
@@ -2603,20 +3201,20 @@ var SchemaVersionCheck = class {
 };
 
 // src/adapters/diagnostics/checks/storage-check.ts
-import { existsSync as existsSync15, readFileSync as readFileSync10 } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync16, readFileSync as readFileSync11 } from "fs";
+import { join as join18 } from "path";
 var SqliteCacheCheck = class {
   id = "sqlite_cache";
   title = "SQLite cache";
   async run(ctx) {
-    const dbPath = join17(ctx.ctxoRoot, ".cache", "symbols.db");
-    if (!existsSync15(dbPath)) {
+    const dbPath = join18(ctx.ctxoRoot, ".cache", "symbols.db");
+    if (!existsSync16(dbPath)) {
       return { id: this.id, title: this.title, status: "warn", message: "SQLite cache missing", fix: 'Run "ctxo sync" to rebuild' };
     }
     try {
       const { default: initSqlJs2 } = await import("sql.js");
       const SQL = await initSqlJs2();
-      const buffer = readFileSync10(dbPath);
+      const buffer = readFileSync11(dbPath);
       const db = new SQL.Database(new Uint8Array(buffer));
       const result = db.exec("PRAGMA integrity_check");
       db.close();
@@ -2632,18 +3230,18 @@ var SqliteCacheCheck = class {
 };
 
 // src/adapters/diagnostics/checks/config-check.ts
-import { existsSync as existsSync16, readFileSync as readFileSync11 } from "fs";
-import { join as join18 } from "path";
+import { existsSync as existsSync17, readFileSync as readFileSync12 } from "fs";
+import { join as join19 } from "path";
 var ConfigFileCheck = class {
   id = "config_file";
   title = "Config file";
   async run(ctx) {
-    const configPath = join18(ctx.ctxoRoot, "config.yaml");
-    if (!existsSync16(configPath)) {
+    const configPath = join19(ctx.ctxoRoot, "config.yaml");
+    if (!existsSync17(configPath)) {
       return { id: this.id, title: this.title, status: "warn", message: "No config.yaml (using defaults)" };
     }
     try {
-      const content = readFileSync11(configPath, "utf-8");
+      const content = readFileSync12(configPath, "utf-8");
       if (content.trim().length === 0) {
         return { id: this.id, title: this.title, status: "warn", message: "config.yaml is empty (using defaults)" };
       }
@@ -2677,8 +3275,8 @@ var ConfigFileCheck = class {
 };
 
 // src/adapters/diagnostics/checks/disk-check.ts
-import { existsSync as existsSync17, readdirSync as readdirSync3, statSync as statSync2 } from "fs";
-import { join as join19 } from "path";
+import { existsSync as existsSync18, readdirSync as readdirSync3, statSync as statSync2 } from "fs";
+import { join as join20 } from "path";
 var DEFAULT_THRESHOLDS = { warnMb: 100, failMb: 500 };
 var DiskUsageCheck = class {
   id = "disk_usage";
@@ -2688,7 +3286,7 @@ var DiskUsageCheck = class {
     this.thresholds = thresholds;
   }
   async run(ctx) {
-    if (!existsSync17(ctx.ctxoRoot)) {
+    if (!existsSync18(ctx.ctxoRoot)) {
       return { id: this.id, title: this.title, status: "pass", message: "no .ctxo/ directory", value: "0" };
     }
     const bytes = this.getDirSize(ctx.ctxoRoot);
@@ -2710,7 +3308,7 @@ var DiskUsageCheck = class {
         if (entry.isFile()) {
           try {
             const parent = entry.parentPath ?? entry.path ?? dirPath;
-            total += statSync2(join19(parent, entry.name)).size;
+            total += statSync2(join20(parent, entry.name)).size;
           } catch {
           }
         }
@@ -2722,10 +3320,10 @@ var DiskUsageCheck = class {
 };
 
 // src/cli/doctor-fix.ts
-import { execFileSync as execFileSync6 } from "child_process";
-import { appendFileSync, existsSync as existsSync18, mkdirSync as mkdirSync5, rmSync as rmSync2, unlinkSync as unlinkSync2 } from "fs";
+import { execFileSync as execFileSync7 } from "child_process";
+import { appendFileSync, existsSync as existsSync19, mkdirSync as mkdirSync6, rmSync as rmSync2, unlinkSync as unlinkSync2 } from "fs";
 import { createRequire as createRequire6 } from "module";
-import { dirname as dirname7, join as join20 } from "path";
+import { dirname as dirname7, join as join21 } from "path";
 async function applyFixes(report, options) {
   if (isCI(process.env) && !options.yes && !options.dryRun) {
     return {
@@ -2860,8 +3458,8 @@ async function fixIndex(projectRoot, dryRun) {
 }
 async function pruneOrphans(projectRoot, ctxoRoot, dryRun) {
   if (dryRun) return;
-  const indexDir = join20(ctxoRoot, "index");
-  if (!existsSync18(indexDir)) return;
+  const indexDir = join21(ctxoRoot, "index");
+  if (!existsSync19(indexDir)) return;
   const sourceFiles = listGitFiles2(projectRoot);
   if (sourceFiles.size === 0) return;
   const reader = new JsonIndexReader(ctxoRoot);
@@ -2869,9 +3467,9 @@ async function pruneOrphans(projectRoot, ctxoRoot, dryRun) {
   let removed = 0;
   for (const idx of indices) {
     if (sourceFiles.has(idx.file)) continue;
-    const jsonPath = join20(indexDir, `${idx.file}.json`);
+    const jsonPath = join21(indexDir, `${idx.file}.json`);
     try {
-      if (existsSync18(jsonPath)) {
+      if (existsSync19(jsonPath)) {
         unlinkSync2(jsonPath);
         removed += 1;
         pruneEmptyParents(jsonPath, indexDir);
@@ -2894,7 +3492,7 @@ function pruneEmptyParents(filePath, stopAt) {
 }
 function listGitFiles2(projectRoot) {
   try {
-    const out = execFileSync6(
+    const out = execFileSync7(
       "git",
       ["ls-files", "--cached", "--others", "--exclude-standard"],
       { cwd: projectRoot, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 }
@@ -2905,9 +3503,9 @@ function listGitFiles2(projectRoot) {
   }
 }
 async function fixSqliteCache(projectRoot, ctxoRoot, dryRun) {
-  const cacheDir = join20(ctxoRoot, ".cache");
+  const cacheDir = join21(ctxoRoot, ".cache");
   if (dryRun) return;
-  if (existsSync18(cacheDir)) rmSync2(cacheDir, { recursive: true, force: true });
+  if (existsSync19(cacheDir)) rmSync2(cacheDir, { recursive: true, force: true });
   await new SyncCommand(projectRoot).run();
 }
 var doctorRequire = createRequire6(import.meta.url);
@@ -2924,8 +3522,8 @@ function isCI(env) {
 }
 function writeLog(ctxoRoot, attempts, halted, reason) {
   try {
-    if (!existsSync18(ctxoRoot)) mkdirSync5(ctxoRoot, { recursive: true });
-    const path = join20(ctxoRoot, "doctor-fix.log");
+    if (!existsSync19(ctxoRoot)) mkdirSync6(ctxoRoot, { recursive: true });
+    const path = join21(ctxoRoot, "doctor-fix.log");
     const ts = (/* @__PURE__ */ new Date()).toISOString();
     const lines = [`# ${ts} doctor --fix${halted ? " (halted: " + reason + ")" : ""}`];
     for (const a of attempts) {
@@ -2958,10 +3556,10 @@ var DoctorCommand = class {
   ctxoRoot;
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.ctxoRoot = join21(projectRoot, ".ctxo");
+    this.ctxoRoot = join22(projectRoot, ".ctxo");
   }
   async run(options = {}) {
-    const { getVersion: getVersion2 } = await import("./cli-router-T3VZZJD6.js");
+    const { getVersion: getVersion2 } = await import("./cli-router-GZA44VOV.js");
     console.error(`ctxo v${getVersion2()} \u2014 health check
 `);
     const checks = [
@@ -2983,9 +3581,9 @@ var DoctorCommand = class {
       new CoChangesCacheCheck(),
       new SchemaVersionCheck()
     ];
-    const indexDir = join21(this.ctxoRoot, "index");
-    const indices = existsSync19(indexDir) ? new JsonIndexReader(this.ctxoRoot).readAll() : [];
-    const checker = new HealthChecker(checks);
+    const indexDir = join22(this.ctxoRoot, "index");
+    const indices = existsSync20(indexDir) ? new JsonIndexReader(this.ctxoRoot).readAll() : [];
+    const checker = new HealthChecker(checks, { quiet: Boolean(options.quiet) });
     const report = await checker.runAll({
       projectRoot: this.projectRoot,
       ctxoRoot: this.ctxoRoot,
@@ -3025,13 +3623,13 @@ var DoctorCommand = class {
 };
 
 // src/cli/visualize-command.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync6, existsSync as existsSync20 } from "fs";
-import { join as join22, basename } from "path";
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync5, existsSync as existsSync21 } from "fs";
+import { join as join23, basename } from "path";
 import { execFile } from "child_process";
 var VisualizeCommand = class {
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.ctxoRoot = join22(projectRoot, ".ctxo");
+    this.ctxoRoot = join23(projectRoot, ".ctxo");
   }
   projectRoot;
   ctxoRoot;
@@ -3091,10 +3689,37 @@ var VisualizeCommand = class {
         fileLayerMap.set(file, layer);
       }
     }
+    const communityWriter = new CommunitySnapshotWriter(this.ctxoRoot, {
+      allowProductionPath: true
+    });
+    const currentSnapshot = communityWriter.readCurrent();
+    const communityByIdForSymbol = /* @__PURE__ */ new Map();
+    if (currentSnapshot) {
+      for (const entry of currentSnapshot.communities) {
+        communityByIdForSymbol.set(entry.symbolId, {
+          id: entry.communityId,
+          label: entry.communityLabel
+        });
+      }
+    }
+    const architectureWriter = new ArchitectureArtifactsWriter(this.ctxoRoot, {
+      allowProductionPath: true
+    });
+    const violationsArtifact = architectureWriter.readBoundaryViolations();
+    const violationEdgeSeverity = /* @__PURE__ */ new Map();
+    if (violationsArtifact) {
+      for (const v of violationsArtifact.violations) {
+        violationEdgeSeverity.set(
+          `${v.from.symbolId}|${v.to.symbolId}`,
+          v.severity
+        );
+      }
+    }
     const totalSymbols = graph.nodeCount;
     let nodes = graph.allNodes().map((sym) => {
       const file = sym.symbolId.split("::")[0] ?? "";
       const dead = deadMap.get(sym.symbolId);
+      const community = communityByIdForSymbol.get(sym.symbolId);
       return {
         id: sym.symbolId,
         name: sym.name,
@@ -3108,7 +3733,9 @@ var VisualizeCommand = class {
         cyclomatic: complexityMap.get(sym.symbolId),
         hasAntiPattern: antiPatternFiles.has(file),
         inDegree: graph.getReverseEdges(sym.symbolId).length,
-        outDegree: graph.getForwardEdges(sym.symbolId).length
+        outDegree: graph.getForwardEdges(sym.symbolId).length,
+        communityId: community?.id ?? -1,
+        communityLabel: community?.label ?? "unassigned"
       };
     });
     if (options.maxNodes && nodes.length > options.maxNodes) {
@@ -3116,12 +3743,31 @@ var VisualizeCommand = class {
       nodes = nodes.slice(0, options.maxNodes);
     }
     const nodeIds = new Set(nodes.map((n) => n.id));
-    const edges = graph.allEdges().filter((e) => nodeIds.has(e.from) && nodeIds.has(e.to)).map((e) => ({ source: e.from, target: e.to, kind: e.kind }));
+    const edges = graph.allEdges().filter((e) => nodeIds.has(e.from) && nodeIds.has(e.to)).map((e) => {
+      const severity = violationEdgeSeverity.get(`${e.from}|${e.to}`);
+      return {
+        source: e.from,
+        target: e.to,
+        kind: e.kind,
+        ...severity ? { violationSeverity: severity } : {}
+      };
+    });
     const filesInfo = indices.filter((fi) => nodeIds.has(fi.symbols[0]?.symbolId ?? "___") || fi.symbols.some((s) => nodeIds.has(s.symbolId))).map((fi) => ({
       file: fi.file,
       intent: fi.intent.map((i) => ({ hash: i.hash, message: i.message, date: i.date })),
       antiPatterns: fi.antiPatterns.map((a) => ({ hash: a.hash, message: a.message, date: a.date }))
     }));
+    const legendCounts = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      if (node.communityId < 0) continue;
+      const entry = legendCounts.get(node.communityId);
+      if (entry) {
+        entry.count += 1;
+      } else {
+        legendCounts.set(node.communityId, { label: node.communityLabel, count: 1 });
+      }
+    }
+    const communities = [...legendCounts.entries()].map(([id, { label, count }]) => ({ id, label, memberCount: count })).sort((a, b) => b.memberCount - a.memberCount);
     const payload = {
       projectName: basename(this.projectRoot),
       generatedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
@@ -3130,13 +3776,16 @@ var VisualizeCommand = class {
       nodes,
       edges,
       layers: overlayResult.layers,
-      files: filesInfo
+      files: filesInfo,
+      communities,
+      modularity: currentSnapshot?.modularity ?? 0,
+      violationCount: violationsArtifact?.violations.length ?? 0
     };
     const templatePath = this.getTemplatePath();
-    const template = readFileSync12(templatePath, "utf-8");
+    const template = readFileSync13(templatePath, "utf-8");
     const html = template.replace("/*__CTXO_DATA__*/null", JSON.stringify(payload));
-    const outputPath = options.output ?? join22(this.ctxoRoot, "visualize.html");
-    writeFileSync6(outputPath, html, "utf-8");
+    const outputPath = options.output ?? join23(this.ctxoRoot, "visualize.html");
+    writeFileSync5(outputPath, html, "utf-8");
     console.error(`[ctxo] Wrote visualization to ${outputPath}`);
     console.error(`[ctxo] ${nodes.length} symbols, ${edges.length} edges, ${deadResult.deadSymbols.length} dead`);
     if (!options.noBrowser) {
@@ -3146,9 +3795,9 @@ var VisualizeCommand = class {
   getTemplatePath() {
     let dir = import.meta.dirname;
     for (let i = 0; i < 10; i++) {
-      const candidate = join22(dir, "pages", "visualize-template.html");
-      if (existsSync20(candidate)) return candidate;
-      const parent = join22(dir, "..");
+      const candidate = join23(dir, "pages", "visualize-template.html");
+      if (existsSync21(candidate)) return candidate;
+      const parent = join23(dir, "..");
       if (parent === dir) break;
       dir = parent;
     }
@@ -3175,16 +3824,16 @@ var VisualizeCommand = class {
 function getVersion() {
   let dir = import.meta.dirname;
   for (let i = 0; i < 10; i++) {
-    const pkg = join23(dir, "package.json");
-    if (existsSync21(pkg)) {
+    const pkg = join24(dir, "package.json");
+    if (existsSync22(pkg)) {
       try {
-        const json = JSON.parse(readFileSync13(pkg, "utf-8"));
+        const json = JSON.parse(readFileSync14(pkg, "utf-8"));
         return json.version ?? "unknown";
       } catch {
         break;
       }
     }
-    const parent = join23(dir, "..");
+    const parent = join24(dir, "..");
     if (parent === dir) break;
     dir = parent;
   }
@@ -3193,7 +3842,7 @@ function getVersion() {
 function locateGitRoot(startDir) {
   let dir = startDir;
   for (let i = 0; i < 12; i++) {
-    if (existsSync21(join23(dir, ".git"))) return dir;
+    if (existsSync22(join24(dir, ".git"))) return dir;
     const parent = dirname8(dir);
     if (parent === dir) break;
     dir = parent;
@@ -3237,6 +3886,7 @@ var CliRouter = class {
         }
         const checkArg = args.includes("--check");
         const skipHistory = args.includes("--skip-history");
+        const skipCommunity = args.includes("--skip-community");
         const installMissing = args.includes("--install-missing");
         const maxHistoryIdx = args.indexOf("--max-history");
         const maxHistoryArg = maxHistoryIdx !== -1 ? Number(args[maxHistoryIdx + 1]) : void 0;
@@ -3249,6 +3899,7 @@ var CliRouter = class {
           file: fileArg,
           check: checkArg,
           skipHistory,
+          skipCommunity,
           maxHistory: maxHistoryArg,
           installMissing
         });
@@ -3372,6 +4023,7 @@ ctxo v${v} \u2014 MCP server for dependency-aware codebase context
 Usage:
   ctxo                      Start MCP server (stdio transport)
   ctxo index                Build full codebase index (--max-history N, default 20)
+  ctxo index --skip-community    Skip Louvain community detection for faster indexing
   ctxo sync                 Rebuild SQLite cache from committed JSON index
   ctxo watch                Start file watcher for incremental re-indexing
   ctxo verify-index         CI gate: fail if index is stale
@@ -3403,4 +4055,4 @@ export {
   getVersion,
   locateGitRoot
 };
-//# sourceMappingURL=cli-router-T3VZZJD6.js.map
+//# sourceMappingURL=cli-router-GZA44VOV.js.map