@chappibunny/repolens 1.5.3 → 1.6.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.6.0
+
+### ✨ Features
+
+- **Deterministic enrichment**: All 6 AI-enhanced document types now produce significantly richer output when running without AI integration. Fallback generators receive dependency graph stats, data flows, monorepo info, routes, drift results, and module type classifications.
+- **Executive Summary**: Now includes module composition breakdown, monorepo structure, codebase health metrics (cycles, orphans, hubs), data flow summaries, and test framework info.
+- **System Overview**: Now includes module architecture by type, route summary (pages + APIs), dependency graph stats with hub modules, and monorepo info.
+- **Business Domains**: Now maps routes to domains and shows cross-domain dependency hubs.
+- **Architecture Overview**: Now includes module layers by type, dependency health with strengths/concerns heuristics, hub modules, architecture drift summary, and monorepo architecture.
+- **Data Flows**: Now generates additional flows from dependency graph hub chains when heuristic flows are sparse, shows shared library and external service dependencies per flow, and includes import network summary.
+- **Developer Onboarding**: Now includes monorepo navigation, key routes to explore, data flow overview, integration point warnings, module type classification in the module table, and test framework quickstart.
+- **Activated dead code**: `identifyFlowDependencies()` from `flow-inference.js` is now imported and used in the data flows fallback to enrich each flow with shared library and external dependency context.
+
+### 🧪 Test Coverage
+
+- **Deterministic enrichment tests** (`tests/deterministic-enrichment.test.js`): 36 tests covering all 6 enriched fallback generators — module composition, monorepo sections, dependency health, route summaries, data flow generation from dep graph, backward compatibility.
+- **347 tests** passing across **22 test files** (up from 311/21).
+
 ## 1.5.3
 
 ### 🔧 Improvements

package/README.md

@@ -25,7 +25,7 @@ RepoLens scans your repository, generates living architecture documentation, and
 
 > **Try it now** — no installation required. Run `npx @chappibunny/repolens demo` on any repo for an instant local preview.
 
-[![RepoLens Demo](https://img.youtube.com/vi/hNd7xim_rTE/maxresdefault.jpg)](https://youtu.be/hNd7xim_rTE)
+[![RepoLens Demo](https://img.youtube.com/vi/Lpyg0dGsiws/maxresdefault.jpg)](https://youtu.be/Lpyg0dGsiws)
 
 ▶️ *Click to watch on YouTube*
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.5.3",
+  "version": "1.6.1",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",
@@ -64,10 +64,8 @@
     "js-yaml": "^4.1.0",
     "node-fetch": "^3.3.2"
   },
-  "optionalDependencies": {
-    "@mermaid-js/mermaid-cli": "^11.12.0"
-  },
   "devDependencies": {
+    "tinyexec": "1.0.2",
     "vitest": "^4.0.18"
   }
 }

package/src/ai/generate-sections.js

@@ -15,6 +15,7 @@ import {
   AI_SCHEMAS,
   renderStructuredToMarkdown,
 } from "./prompts.js";
+import { identifyFlowDependencies } from "../analyzers/flow-inference.js";
 import { info, warn } from "../utils/logger.js";
 
 /**
@@ -62,68 +63,70 @@ async function generateWithStructuredFallback(key, promptText, maxTokens, fallba
   return result.text;
 }
 
-export async function generateExecutiveSummary(context) {
+export async function generateExecutiveSummary(context, enrichment = {}) {
   return generateWithStructuredFallback(
     "executive_summary",
     createExecutiveSummaryPrompt(context),
     1500,
-    () => getFallbackExecutiveSummary(context),
+    () => getFallbackExecutiveSummary(context, enrichment),
   );
 }
 
-export async function generateSystemOverview(context) {
+export async function generateSystemOverview(context, enrichment = {}) {
   return generateWithStructuredFallback(
     "system_overview",
     createSystemOverviewPrompt(context),
     1200,
-    () => getFallbackSystemOverview(context),
+    () => getFallbackSystemOverview(context, enrichment),
   );
 }
 
-export async function generateBusinessDomains(context) {
+export async function generateBusinessDomains(context, enrichment = {}) {
   return generateWithStructuredFallback(
     "business_domains",
     createBusinessDomainsPrompt(context),
     2000,
-    () => getFallbackBusinessDomains(context),
+    () => getFallbackBusinessDomains(context, enrichment),
   );
 }
 
-export async function generateArchitectureOverview(context) {
+export async function generateArchitectureOverview(context, enrichment = {}) {
   return generateWithStructuredFallback(
     "architecture_overview",
     createArchitectureOverviewPrompt(context),
     1800,
-    () => getFallbackArchitectureOverview(context),
+    () => getFallbackArchitectureOverview(context, enrichment),
   );
 }
 
-export async function generateDataFlows(flows, context) {
+export async function generateDataFlows(flows, context, enrichment = {}) {
   return generateWithStructuredFallback(
     "data_flows",
     createDataFlowsPrompt(flows, context),
     1800,
-    () => getFallbackDataFlows(flows),
+    () => getFallbackDataFlows(flows, context, enrichment),
   );
 }
 
-export async function generateDeveloperOnboarding(context) {
+export async function generateDeveloperOnboarding(context, enrichment = {}) {
   return generateWithStructuredFallback(
     "developer_onboarding",
     createDeveloperOnboardingPrompt(context),
     2200,
-    () => getFallbackDeveloperOnboarding(context),
+    () => getFallbackDeveloperOnboarding(context, enrichment),
   );
 }
 
 // Fallback generators (deterministic, no AI)
 
-function getFallbackExecutiveSummary(context) {
+function getFallbackExecutiveSummary(context, enrichment = {}) {
+  const { depGraph, flows } = enrichment;
   const frameworkList = context.techStack.frameworks.join(", ") || "general-purpose";
   const languageList = context.techStack.languages.join(", ") || "multiple languages";
   const domainSummary = context.domains.slice(0, 5).map(d => d.name).join(", ");
+  const testFrameworks = context.techStack.testFrameworks || [];
 
-  return `# Executive Summary
+  let output = `# Executive Summary
 
 ## What This System Does
 
@@ -146,21 +149,72 @@ ${context.domains.map(d => `| ${d.name} | ${d.moduleCount} | ${d.description ||
 | Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
 | Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
 | Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
+${testFrameworks.length > 0 ? `| Test Frameworks | ${testFrameworks.join(", ")} |\n` : ""}`;
+
+  // Module type breakdown
+  const typeGroups = groupModulesByType(context.topModules);
+  if (Object.keys(typeGroups).length > 1) {
+    output += `\n## Module Composition\n\n`;
+    output += `| Layer | Modules | Examples |\n`;
+    output += `|-------|---------|----------|\n`;
+    for (const [type, mods] of Object.entries(typeGroups)) {
+      const examples = mods.slice(0, 3).map(m => `\`${m.key}\``).join(", ");
+      output += `| ${formatModuleType(type)} | ${mods.length} | ${examples} |\n`;
+    }
+  }
 
-## Key Observations
+  // Monorepo info
+  if (context.monorepo) {
+    output += `\n## Monorepo Structure\n\n`;
+    output += `This is a **${context.monorepo.tool}** monorepo containing **${context.monorepo.packageCount} package${context.monorepo.packageCount === 1 ? "" : "s"}**:\n\n`;
+    output += context.monorepo.packages.slice(0, 10).map(p => `- \`${p.name}\` (${p.path})`).join("\n");
+    output += "\n";
+  }
+
+  // Dependency health
+  if (depGraph?.stats) {
+    const stats = depGraph.stats;
+    output += `\n## Codebase Health\n\n`;
+    output += `| Metric | Value |\n`;
+    output += `|--------|-------|\n`;
+    output += `| Internal imports | ${stats.totalEdges} |\n`;
+    output += `| External dependencies | ${stats.externalDeps} |\n`;
+    output += `| Circular dependencies | ${stats.cycles} |\n`;
+    output += `| Orphan files | ${stats.orphanFiles} |\n`;
+    if (stats.cycles === 0) {
+      output += `\nThe dependency graph is **cycle-free**, indicating clean module boundaries.\n`;
+    } else {
+      output += `\n⚠️ **${stats.cycles} circular dependenc${stats.cycles === 1 ? "y" : "ies"}** detected — these may complicate refactoring and testing.\n`;
+    }
+  }
+
+  // Data flows
+  if (flows && flows.length > 0) {
+    output += `\n## Key Data Flows\n\n`;
+    output += `${flows.length} data flow${flows.length === 1 ? "" : "s"} identified:\n\n`;
+    for (const flow of flows) {
+      output += `- **${flow.name}**${flow.critical ? " (critical)" : ""} — ${flow.description}\n`;
+    }
+  }
+
+  output += `\n## Key Observations
 
 The codebase follows ${context.patterns.length > 0 ? context.patterns.join(", ") : "standard"} architectural patterns. ${domainSummary ? `The core functional areas — ${domainSummary} — account for the majority of the application logic.` : ""}
 
 ---
 
 *This summary is generated deterministically from repository structure. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language insights tailored to non-technical readers.*`;
+
+  return output;
 }
 
-function getFallbackSystemOverview(context) {
+function getFallbackSystemOverview(context, enrichment = {}) {
+  const { depGraph } = enrichment;
   const sizeLabel = context.project.modulesDetected > 50 ? "large-scale" :
                     context.project.modulesDetected > 20 ? "medium-sized" : "focused";
+  const testFrameworks = context.techStack.testFrameworks || [];
 
-  return `# System Overview
+  let output = `# System Overview
 
 ## Repository Snapshot
 
@@ -173,24 +227,102 @@ This is a ${sizeLabel} codebase organized into **${context.project.modulesDetect
 | Application pages | ${context.project.pagesDetected} |
 | API endpoints | ${context.project.apiRoutesDetected} |
 
+## Technology Stack
+
+| Category | Technologies |
+|----------|-------------|
+| Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
+| Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
+| Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
+${testFrameworks.length > 0 ? `| Test Frameworks | ${testFrameworks.join(", ")} |\n` : ""}
 ## Detected Patterns
 
 ${context.patterns.length > 0 ? context.patterns.map(p => `- ${p}`).join("\n") : "No specific architectural patterns were detected. This typically means the project uses a straightforward directory-based organization."}
+`;
+
+  // Module type breakdown
+  const typeGroups = groupModulesByType(context.topModules);
+  if (Object.keys(typeGroups).length > 1) {
+    output += `\n## Module Architecture\n\n`;
+    output += `The codebase is organized into the following module layers:\n\n`;
+    for (const [type, mods] of Object.entries(typeGroups)) {
+      const moduleList = mods.slice(0, 5).map(m => `\`${m.key}\` (${m.fileCount} files)`).join(", ");
+      output += `- **${formatModuleType(type)}** (${mods.length}): ${moduleList}\n`;
+    }
+  }
 
-## Dominant Domains
+  output += `\n## Dominant Domains
 
 The following domains represent the largest areas of the codebase by file count:
 
 | Rank | Domain | Files |
 |------|--------|-------|
 ${context.domains.slice(0, 5).map((d, i) => `| ${i + 1} | ${d.name} | ${d.fileCount} |`).join("\n")}
+`;
+
+  // Route highlights
+  const routes = context.routes || {};
+  const pages = routes.pages || [];
+  const apis = routes.apis || [];
+  if (pages.length > 0 || apis.length > 0) {
+    output += `\n## Route Summary\n\n`;
+    if (pages.length > 0) {
+      output += `**Application Pages** (${pages.length} total):\n\n`;
+      for (const p of pages.slice(0, 8)) {
+        output += `- \`${p.path}\`\n`;
+      }
+      if (pages.length > 8) output += `- … and ${pages.length - 8} more\n`;
+      output += "\n";
+    }
+    if (apis.length > 0) {
+      output += `**API Endpoints** (${apis.length} total):\n\n`;
+      for (const a of apis.slice(0, 8)) {
+        const methods = a.methods ? ` [${a.methods.join(", ")}]` : "";
+        output += `- \`${a.path}\`${methods}\n`;
+      }
+      if (apis.length > 8) output += `- … and ${apis.length - 8} more\n`;
+      output += "\n";
+    }
+  }
 
----
+  // Dependency graph highlights
+  if (depGraph?.stats) {
+    const stats = depGraph.stats;
+    output += `## Dependency Graph\n\n`;
+    output += `| Metric | Value |\n`;
+    output += `|--------|-------|\n`;
+    output += `| Internal imports | ${stats.totalEdges} |\n`;
+    output += `| External packages | ${stats.externalDeps} |\n`;
+    output += `| Circular dependencies | ${stats.cycles} |\n`;
+    output += `| Orphan files | ${stats.orphanFiles} |\n`;
+    if (stats.hubs && stats.hubs.length > 0) {
+      output += `\n**Hub modules** (most imported):\n\n`;
+      for (const hub of stats.hubs.slice(0, 5)) {
+        output += `- \`${hub.key}\` — imported by ${hub.importedBy} files\n`;
+      }
+    }
+    output += "\n";
+  }
+
+  // Monorepo
+  if (context.monorepo) {
+    output += `## Monorepo\n\n`;
+    output += `Managed by **${context.monorepo.tool}** with **${context.monorepo.packageCount} packages**.\n\n`;
+  }
+
+  output += `---
 
 *This overview is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for richer contextual explanations.*`;
+
+  return output;
 }
 
-function getFallbackBusinessDomains(context) {
+function getFallbackBusinessDomains(context, enrichment = {}) {
+  const { depGraph } = enrichment;
+  const routes = context.routes || {};
+  const pages = routes.pages || [];
+  const apis = routes.apis || [];
+
   let output = `# Business Domains\n\n`;
   output += `> This document maps the codebase into business-oriented functional areas. Each domain represents a distinct area of responsibility.\n\n`;
   output += `**Total domains identified:** ${context.domains.length}\n\n`;
@@ -206,6 +338,37 @@ function getFallbackBusinessDomains(context) {
     if (domain.topModules?.length > 0) {
       output += `**Key modules:** ${domain.topModules.slice(0, 5).map(m => `\`${m}\``).join(", ")}\n\n`;
     }
+
+    // Match routes to this domain by checking if any domain module paths appear in routes
+    const domainModules = domain.topModules || [];
+    const domainPages = pages.filter(p =>
+      domainModules.some(m => p.path.toLowerCase().includes(m.toLowerCase().split("/").pop()))
+    );
+    const domainApis = apis.filter(a =>
+      domainModules.some(m => a.path.toLowerCase().includes(m.toLowerCase().split("/").pop()))
+    );
+
+    if (domainPages.length > 0 || domainApis.length > 0) {
+      output += `**Routes in this domain:**\n\n`;
+      for (const p of domainPages.slice(0, 5)) {
+        output += `- 📄 \`${p.path}\`\n`;
+      }
+      for (const a of domainApis.slice(0, 5)) {
+        const methods = a.methods ? ` [${a.methods.join(", ")}]` : "";
+        output += `- 🔌 \`${a.path}\`${methods}\n`;
+      }
+      output += "\n";
+    }
+  }
+
+  // Cross-domain dependency insights
+  if (depGraph?.stats?.hubs && depGraph.stats.hubs.length > 0) {
+    output += `## Cross-Domain Dependencies\n\n`;
+    output += `The following modules are heavily imported across the codebase, likely serving as shared infrastructure:\n\n`;
+    for (const hub of depGraph.stats.hubs.slice(0, 5)) {
+      output += `- \`${hub.key}\` — imported by ${hub.importedBy} modules\n`;
+    }
+    output += "\n";
   }
   
   output += `---\n\n*Domain mapping is based on directory naming conventions. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language descriptions aimed at non-technical stakeholders.*`;
@@ -213,12 +376,13 @@ function getFallbackBusinessDomains(context) {
   return output;
 }
 
-function getFallbackArchitectureOverview(context) {
+function getFallbackArchitectureOverview(context, enrichment = {}) {
+  const { depGraph, driftResult } = enrichment;
   const patternDesc = context.patterns.length > 0
     ? `The detected architectural patterns are **${context.patterns.join(", ")}**. These patterns shape how data and control flow through the system.`
     : "No specific architectural patterns were detected. The project appears to follow a straightforward directory-based organization.";
 
-  return `# Architecture Overview
+  let output = `# Architecture Overview
 
 ## Architectural Style
 
@@ -231,8 +395,23 @@ The codebase is organized into ${context.domains.length} functional layers, each
 | Layer | Description |
 |-------|-------------|
 ${context.domains.slice(0, 8).map(d => `| **${d.name}** | ${d.description || "Handles a distinct functional concern"} |`).join("\n")}
+`;
+
+  // Module layer breakdown by type
+  const typeGroups = groupModulesByType(context.topModules);
+  if (Object.keys(typeGroups).length > 1) {
+    output += `\n## Module Layers\n\n`;
+    output += `Modules are classified into architectural layers based on their role:\n\n`;
+    for (const [type, mods] of Object.entries(typeGroups)) {
+      output += `### ${formatModuleType(type)}\n\n`;
+      for (const m of mods.slice(0, 5)) {
+        output += `- \`${m.key}\` (${m.fileCount} files)\n`;
+      }
+      output += "\n";
+    }
+  }
 
-## Technology Stack
+  output += `## Technology Stack
 
 | Category | Technologies |
 |----------|-------------|
@@ -243,25 +422,108 @@ ${context.domains.slice(0, 8).map(d => `| **${d.name}** | ${d.description || "Ha
 ## Scale & Complexity
 
 The repository comprises **${context.project.filesScanned} files** organized into **${context.project.modulesDetected} modules**. ${context.project.apiRoutesDetected > 0 ? `It exposes **${context.project.apiRoutesDetected} API endpoint${context.project.apiRoutesDetected === 1 ? "" : "s"}** and` : "It"} serves **${context.project.pagesDetected} application page${context.project.pagesDetected === 1 ? "" : "s"}**.
+`;
 
----
+  // Dependency graph health
+  if (depGraph?.stats) {
+    const stats = depGraph.stats;
+    output += `\n## Dependency Health\n\n`;
+    output += `| Metric | Value |\n`;
+    output += `|--------|-------|\n`;
+    output += `| Import edges | ${stats.totalEdges} |\n`;
+    output += `| External packages | ${stats.externalDeps} |\n`;
+    output += `| Circular dependencies | ${stats.cycles} |\n`;
+    output += `| Orphan files | ${stats.orphanFiles} |\n\n`;
+
+    // Strengths
+    const strengths = [];
+    const concerns = [];
+    if (stats.cycles === 0) strengths.push("No circular dependencies — clean module boundaries");
+    if (stats.orphanFiles === 0) strengths.push("No orphan files — all code is connected");
+    if (stats.hubs && stats.hubs.length > 0 && stats.hubs[0].importedBy < stats.totalFiles * 0.3)
+      strengths.push("No excessively coupled hubs");
+
+    if (stats.cycles > 0) concerns.push(`${stats.cycles} circular dependenc${stats.cycles === 1 ? "y" : "ies"} — may hinder testing and refactoring`);
+    if (stats.orphanFiles > stats.totalFiles * 0.2)
+      concerns.push(`High orphan file ratio (${stats.orphanFiles}/${stats.totalFiles}) — possible dead code`);
+    if (stats.hubs && stats.hubs.length > 0 && stats.hubs[0].importedBy >= stats.totalFiles * 0.3)
+      concerns.push(`\`${stats.hubs[0].key}\` is imported by ${stats.hubs[0].importedBy} files — high coupling risk`);
+
+    if (strengths.length > 0) {
+      output += `**Strengths:**\n\n`;
+      for (const s of strengths) output += `- ✅ ${s}\n`;
+      output += "\n";
+    }
+    if (concerns.length > 0) {
+      output += `**Concerns:**\n\n`;
+      for (const c of concerns) output += `- ⚠️ ${c}\n`;
+      output += "\n";
+    }
+
+    if (stats.hubs && stats.hubs.length > 0) {
+      output += `**Hub modules** (most imported):\n\n`;
+      for (const hub of stats.hubs.slice(0, 5)) {
+        output += `- \`${hub.key}\` — imported by ${hub.importedBy} files\n`;
+      }
+      output += "\n";
+    }
+  }
+
+  // Drift summary
+  if (driftResult?.drifts && driftResult.drifts.length > 0) {
+    output += `## Architecture Drift\n\n`;
+    output += `${driftResult.drifts.length} drift${driftResult.drifts.length === 1 ? "" : "s"} detected since last baseline:\n\n`;
+    for (const drift of driftResult.drifts.slice(0, 5)) {
+      output += `- **${drift.type}**: ${drift.description || drift.message || "Change detected"}\n`;
+    }
+    output += "\n";
+  }
+
+  // Monorepo
+  if (context.monorepo) {
+    output += `## Monorepo Architecture\n\n`;
+    output += `This project is a **${context.monorepo.tool}** monorepo with **${context.monorepo.packageCount} packages**:\n\n`;
+    for (const pkg of context.monorepo.packages.slice(0, 10)) {
+      output += `- \`${pkg.name}\` — ${pkg.path}\n`;
+    }
+    output += "\n";
+  }
+
+  output += `---
 
 *This architecture overview is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for deeper architectural narratives.*`;
+
+  return output;
 }
 
-function getFallbackDataFlows(flows) {
+function getFallbackDataFlows(flows, context, enrichment = {}) {
+  const { depGraph, scanResult } = enrichment;
+
   let output = `# Data Flows\n\n`;
   output += `> Data flows describe how information moves through the system — from external inputs through processing layers to storage or presentation.\n\n`;
 
-  if (!flows || flows.length === 0) {
+  // Combine heuristic flows with dep-graph-derived flows
+  const allFlows = [...(flows || [])];
+
+  // Generate additional flows from dependency graph hub chains
+  if (depGraph?.nodes && depGraph.nodes.length > 0 && allFlows.length < 3) {
+    const hubFlows = inferFlowsFromDepGraph(depGraph);
+    for (const hf of hubFlows) {
+      if (!allFlows.some(f => f.name === hf.name)) {
+        allFlows.push(hf);
+      }
+    }
+  }
+
+  if (allFlows.length === 0) {
     output += `No data flows were detected. This typically means the system uses straightforward request–response patterns without distinct multi-step pipelines.\n\n`;
     output += `---\n\n*Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for heuristic-based flow descriptions.*`;
     return output;
   }
 
-  output += `**${flows.length} flow${flows.length === 1 ? "" : "s"} detected** in the codebase.\n\n---\n\n`;
+  output += `**${allFlows.length} flow${allFlows.length === 1 ? "" : "s"} detected** in the codebase.\n\n---\n\n`;
   
-  for (const flow of flows) {
+  for (const flow of allFlows) {
     output += `## ${flow.name}\n\n`;
     output += `${flow.description}\n\n`;
     if (flow.steps && flow.steps.length > 0) {
@@ -273,6 +535,30 @@ function getFallbackDataFlows(flows) {
     if (flow.modules && flow.modules.length > 0) {
       output += `**Involved modules:** ${flow.modules.map(m => `\`${m}\``).join(", ")}\n\n`;
     }
+
+    // Add dependency context if available
+    if (scanResult && flow.modules) {
+      const deps = identifyFlowDependencies(flow, scanResult);
+      if (deps.sharedLibraries.length > 0) {
+        output += `**Shared libraries used:** ${deps.sharedLibraries.map(m => `\`${m}\``).join(", ")}\n\n`;
+      }
+      if (deps.externalDependencies.length > 0) {
+        output += `**External services:** ${deps.externalDependencies.join(", ")}\n\n`;
+      }
+    }
+  }
+
+  // Import chain summary
+  if (depGraph?.stats) {
+    output += `## Import Network\n\n`;
+    output += `The system has **${depGraph.stats.totalEdges} internal import edges** connecting ${depGraph.stats.totalFiles} source files.\n\n`;
+    if (depGraph.stats.hubs && depGraph.stats.hubs.length > 0) {
+      output += `Key integration points (most referenced modules):\n\n`;
+      for (const hub of depGraph.stats.hubs.slice(0, 5)) {
+        output += `- \`${hub.key}\` — referenced by ${hub.importedBy} files\n`;
+      }
+      output += "\n";
+    }
   }
   
   output += `---\n\n*Flow detection is based on naming conventions and import patterns. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language flow narratives.*`;
@@ -280,11 +566,16 @@ function getFallbackDataFlows(flows) {
   return output;
 }
 
-function getFallbackDeveloperOnboarding(context) {
+function getFallbackDeveloperOnboarding(context, enrichment = {}) {
+  const { flows, depGraph } = enrichment;
   const frameworkList = context.techStack.frameworks.join(", ") || "general-purpose tools";
   const languageList = context.techStack.languages.join(", ") || "standard languages";
+  const testFrameworks = context.techStack.testFrameworks || [];
+  const routes = context.routes || {};
+  const pages = routes.pages || [];
+  const apis = routes.apis || [];
 
-  return `# Developer Onboarding
+  let output = `# Developer Onboarding
 
 ## Welcome
 
@@ -297,51 +588,179 @@ The top-level directory is organized as follows:
 | Directory | Purpose |
 |-----------|---------|
 ${context.repoRoots.map(root => `| \`${root}\` | ${describeRoot(root)} |`).join("\n")}
+`;
+
+  // Monorepo navigation
+  if (context.monorepo) {
+    output += `\n## Monorepo Navigation\n\n`;
+    output += `This is a **${context.monorepo.tool}** monorepo. Key packages:\n\n`;
+    for (const pkg of context.monorepo.packages.slice(0, 10)) {
+      output += `- \`${pkg.name}\` — \`${pkg.path}\`\n`;
+    }
+    output += "\n";
+  }
 
-## Technology Stack
+  output += `## Technology Stack
 
 | Category | Technologies |
 |----------|-------------|
 | Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
 | Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
 | Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
-
+${testFrameworks.length > 0 ? `| Test Frameworks | ${testFrameworks.join(", ")} |\n` : ""}
 ## Largest Modules
 
 These are the primary modules by file count — good starting points for understanding the system:
 
-| Module | Files | Description |
-|--------|-------|-------------|
-${context.topModules.slice(0, 10).map((m, i) => `| \`${m.key}\` | ${m.fileCount} | ${describeOnboardingModule(m.key)} |`).join("\n")}
+| Module | Files | Type |
+|--------|-------|------|
+${context.topModules.slice(0, 10).map(m => `| \`${m.key}\` | ${m.fileCount} | ${formatModuleType(m.type)} |`).join("\n")}
+`;
+
+  // Key routes to explore
+  if (pages.length > 0 || apis.length > 0) {
+    output += `\n## Key Routes\n\n`;
+    if (pages.length > 0) {
+      output += `**Pages to explore:**\n\n`;
+      for (const p of pages.slice(0, 5)) {
+        output += `- \`${p.path}\` — ${p.file}\n`;
+      }
+      output += "\n";
+    }
+    if (apis.length > 0) {
+      output += `**API endpoints:**\n\n`;
+      for (const a of apis.slice(0, 5)) {
+        const methods = a.methods ? ` [${a.methods.join(", ")}]` : "";
+        output += `- \`${a.path}\`${methods} — ${a.file}\n`;
+      }
+      output += "\n";
+    }
+  }
 
-## Getting Started
+  // Data flows overview
+  if (flows && flows.length > 0) {
+    output += `## How Data Flows\n\n`;
+    output += `Understanding these flows will help you see how the system works end-to-end:\n\n`;
+    for (const flow of flows) {
+      output += `- **${flow.name}** — ${flow.description}\n`;
+    }
+    output += "\n";
+  }
+
+  // Dependency orientation
+  if (depGraph?.stats?.hubs && depGraph.stats.hubs.length > 0) {
+    output += `## Key Integration Points\n\n`;
+    output += `These modules are the most widely imported — changes to them may have broad impact:\n\n`;
+    for (const hub of depGraph.stats.hubs.slice(0, 5)) {
+      output += `- \`${hub.key}\` — imported by ${hub.importedBy} files\n`;
+    }
+    output += "\n";
+  }
+
+  output += `## Getting Started
 
 1. Clone the repository and install dependencies
 2. Review the top-level directories above to understand the project layout
 3. Start with the largest modules listed above — they contain the core functionality
-4. Check for a \`README.md\` or \`CONTRIBUTING.md\` file for project-specific setup instructions
+4. Check for a \`README.md\` or \`CONTRIBUTING.md\` file for project-specific setup instructions`;
 
----
+  // Test framework quickstart
+  if (testFrameworks.length > 0) {
+    output += `\n5. Run tests with your ${testFrameworks[0]} setup to verify everything works`;
+  }
+
+  output += `\n\n---
 
 *This onboarding guide is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for a narrative-style guide with tips and common pitfalls.*`;
+
+  return output;
+}
+
+// Helper: group top modules by their inferred type
+function groupModulesByType(topModules) {
+  const groups = {};
+  for (const m of topModules) {
+    const type = m.type || "other";
+    if (!groups[type]) groups[type] = [];
+    groups[type].push(m);
+  }
+  return groups;
+}
+
+// Helper: human-readable module type label
+function formatModuleType(type) {
+  const labels = {
+    api: "API Layer",
+    ui: "UI Components",
+    library: "Shared Libraries",
+    hooks: "React Hooks",
+    state: "State Management",
+    route: "Route/Page Modules",
+    app: "Application Core",
+    other: "Other Modules",
+  };
+  return labels[type] || type;
+}
+
+// Helper: derive flows from dependency graph hub chains
+function inferFlowsFromDepGraph(depGraph) {
+  const flows = [];
+  if (!depGraph?.nodes || depGraph.nodes.length === 0) return flows;
+
+  // Find hub nodes – modules imported by many others
+  const hubThreshold = Math.max(3, Math.floor(depGraph.nodes.length * 0.05));
+  const hubs = depGraph.nodes
+    .filter(n => n.importedBy.length >= hubThreshold)
+    .sort((a, b) => b.importedBy.length - a.importedBy.length)
+    .slice(0, 3);
+
+  for (const hub of hubs) {
+    const importers = hub.importedBy.slice(0, 5);
+    const downstream = hub.imports.slice(0, 3);
+    const shortName = hub.key.split("/").pop();
+
+    flows.push({
+      name: `${shortName} Integration Flow`,
+      description: `\`${hub.key}\` is a central module imported by ${hub.importedBy.length} files, acting as an integration point for data and logic`,
+      steps: [
+        ...importers.map(i => `\`${i.split("/").pop()}\` imports \`${shortName}\``),
+        ...(downstream.length > 0 ? [`\`${shortName}\` depends on ${downstream.map(d => `\`${d.split("/").pop()}\``).join(", ")}`] : []),
+      ],
+      modules: [hub.key, ...importers.slice(0, 3)],
+      critical: hub.importedBy.length >= hubThreshold * 2,
+    });
+  }
+
+  return flows;
 }
 
 function describeRoot(root) {
   const lower = root.toLowerCase().replace(/\/$/, "");
+  // Check the last segment for nested paths like src/core, src/analyzers
+  const lastSeg = lower.split("/").pop();
   if (/^src$|^lib$/.test(lower)) return "Application source code";
-  if (/^test|^__test|^spec/.test(lower)) return "Test suites";
-  if (/^doc/.test(lower)) return "Documentation";
-  if (/^bin$|^scripts?$/.test(lower)) return "CLI entry points and scripts";
-  if (/^config/.test(lower)) return "Configuration files";
-  if (/^public$|^static$|^assets$/.test(lower)) return "Static assets";
-  if (/^dist$|^build$|^out$/.test(lower)) return "Build output";
-  if (/^\.github$/.test(lower)) return "GitHub Actions and workflows";
-  if (/^api$/.test(lower)) return "API definitions";
-  if (/^components?$/.test(lower)) return "Shared UI components";
-  if (/^pages?$|^views?$|^screens?$/.test(lower)) return "Application pages/views";
-  if (/^utils?$|^helpers?$/.test(lower)) return "Utility functions";
-  if (/^services?$/.test(lower)) return "Service layer";
-  if (/^hooks?$/.test(lower)) return "Custom hooks";
+  if (/^test|^__test|^spec/.test(lastSeg)) return "Test suites";
+  if (/^doc/.test(lastSeg)) return "Documentation";
+  if (/^bin$|^scripts?$/.test(lastSeg)) return "CLI entry points and scripts";
+  if (/^config/.test(lastSeg)) return "Configuration files";
+  if (/^public$|^static$|^assets$/.test(lastSeg)) return "Static assets";
+  if (/^dist$|^build$|^out$/.test(lastSeg)) return "Build output";
+  if (/^\.github$/.test(lastSeg)) return "GitHub Actions and workflows";
+  if (/^api$|^endpoint/.test(lastSeg)) return "API definitions";
+  if (/^components?$|^ui$/.test(lastSeg)) return "Shared UI components";
+  if (/^pages?$|^views?$|^screens?$/.test(lastSeg)) return "Application pages/views";
+  if (/^utils?$|^helpers?$/.test(lastSeg)) return "Utility functions";
+  if (/^services?$/.test(lastSeg)) return "Service layer";
+  if (/^hooks?$/.test(lastSeg)) return "Custom hooks";
+  if (/^core$|^kernel$|^engine$/.test(lastSeg)) return "Core logic and foundations";
+  if (/^analyz/.test(lastSeg)) return "Code analysis and detection";
+  if (/^render/.test(lastSeg)) return "Rendering and output formatting";
+  if (/^publish/.test(lastSeg)) return "Publishing and distribution";
+  if (/^deliver/.test(lastSeg)) return "Content delivery";
+  if (/^integrat/.test(lastSeg)) return "Third-party integrations";
+  if (/^plugin/.test(lastSeg)) return "Plugin and extension system";
+  if (/^ai$|^ml$|^llm$/.test(lastSeg)) return "AI/ML features and providers";
+  if (/^middleware/.test(lastSeg)) return "Middleware pipeline";
   return "Project files";
 }
 

package/src/analyzers/context-builder.js

@@ -97,12 +97,28 @@ export function buildAIContext(scanResult, config) {
 function inferModuleType(modulePath) {
   const lower = modulePath.toLowerCase();
   
-  if (lower.includes("api")) return "api";
-  if (lower.includes("component")) return "ui";
-  if (lower.includes("lib") || lower.includes("util")) return "library";
+  if (lower.includes("test") || lower.includes("spec") || lower.includes("__test")) return "test";
+  if (lower.includes("api") || lower.includes("endpoint")) return "api";
+  if (lower.includes("component") || lower.includes("widget")) return "ui";
+  if (lower.includes("lib") || lower.includes("util") || lower.includes("helper") || lower.includes("common") || lower.includes("shared")) return "library";
   if (lower.includes("hook")) return "hooks";
-  if (lower.includes("store") || lower.includes("state")) return "state";
-  if (lower.includes("page") || lower.includes("route")) return "route";
+  if (lower.includes("store") || lower.includes("state") || lower.includes("redux") || lower.includes("zustand")) return "state";
+  if (lower.includes("page") || lower.includes("route") || lower.includes("view")) return "route";
+  if (lower.includes("config") || lower.includes("setting") || lower.includes("env")) return "config";
+  if (lower.includes("core") || lower.includes("kernel") || lower.includes("foundation")) return "core";
+  if (lower.includes("render") || lower.includes("template") || lower.includes("format")) return "renderer";
+  if (lower.includes("publish") || lower.includes("output") || lower.includes("export")) return "publisher";
+  if (lower.includes("analyz") || lower.includes("inspect") || lower.includes("detect")) return "analyzer";
+  if (lower.includes("plugin") || lower.includes("extension") || lower.includes("addon")) return "plugin";
+  if (lower.includes("deliver") || lower.includes("dispatch") || lower.includes("send")) return "delivery";
+  if (lower.includes("doc") || lower.includes("generate")) return "documentation";
+  if (lower.includes("integrat") || lower.includes("connect") || lower.includes("adapter")) return "integration";
+  if (lower.includes("cli") || lower.includes("command") || lower.includes("bin")) return "cli";
+  if (lower.includes("ai") || lower.includes("ml") || lower.includes("model") || lower.includes("prompt")) return "ai";
+  if (lower.includes("auth") || lower.includes("login") || lower.includes("session")) return "auth";
+  if (lower.includes("data") || lower.includes("db") || lower.includes("model") || lower.includes("schema")) return "data";
+  if (lower.includes("middleware")) return "middleware";
+  if (lower.includes("service")) return "service";
   if (lower.includes("app")) return "app";
   
   return "other";
@@ -110,21 +126,31 @@ function inferModuleType(modulePath) {
 
 function inferArchitecturalPatterns(modules) {
   const patterns = [];
+  const keys = modules.map(m => m.key.toLowerCase());
   
-  const hasAppRouter = modules.some(m => m.key.includes("app/"));
-  const hasPagesRouter = modules.some(m => m.key.includes("pages/"));
-  const hasComponents = modules.some(m => m.key.includes("component"));
-  const hasLib = modules.some(m => m.key.includes("lib"));
-  const hasHooks = modules.some(m => m.key.includes("hook"));
-  const hasStore = modules.some(m => m.key.includes("store") || m.key.includes("state"));
-  const hasApi = modules.some(m => m.key.includes("api"));
-  
-  if (hasAppRouter) patterns.push("Next.js App Router");
-  if (hasPagesRouter) patterns.push("Next.js Pages Router");
-  if (hasComponents && hasLib) patterns.push("Layered component architecture");
-  if (hasHooks) patterns.push("React hooks pattern");
-  if (hasStore) patterns.push("Centralized state management");
-  if (hasApi) patterns.push("API route pattern");
+  const has = (keyword) => keys.some(k => k.includes(keyword));
+  
+  // Web framework patterns
+  if (has("app/")) patterns.push("Next.js App Router");
+  if (has("pages/")) patterns.push("Next.js Pages Router");
+  if (has("component") && has("lib")) patterns.push("Layered component architecture");
+  if (has("hook")) patterns.push("React hooks pattern");
+  if (has("store") || has("state") || has("redux") || has("zustand")) patterns.push("Centralized state management");
+  
+  // General patterns
+  if (has("api") || has("endpoint")) patterns.push("API route pattern");
+  if (has("core") || has("kernel")) patterns.push("Core/kernel architecture");
+  if (has("plugin") || has("extension")) patterns.push("Plugin system");
+  if (has("middleware")) patterns.push("Middleware pipeline");
+  if (has("render") || has("template")) patterns.push("Renderer pipeline");
+  if (has("publish") || has("output")) patterns.push("Multi-output publishing");
+  if (has("analyz") || has("detect") || has("inspect")) patterns.push("Analysis pipeline");
+  if (has("cli") || has("command") || has("bin")) patterns.push("CLI tool architecture");
+  if (has("util") || has("helper") || has("lib")) patterns.push("Shared utility layer");
+  if (has("integrat") || has("adapter") || has("connect")) patterns.push("Integration adapters");
+  if (has("ai") || has("prompt") || has("provider")) patterns.push("AI/LLM integration");
+  if (has("deliver") || has("dispatch")) patterns.push("Delivery pipeline");
+  if (has("test") || has("spec")) patterns.push("Dedicated test infrastructure");
   
   return patterns;
 }

package/src/analyzers/domain-inference.js

@@ -32,7 +32,7 @@ const DEFAULT_DOMAIN_HINTS = [
     description: "Payment processing and subscription management"
   },
   { 
-    match: ["api", "endpoint", "route", "handler", "controller", "middleware"], 
+    match: ["api", "endpoint", "handler", "controller", "middleware"], 
     domain: "API Layer",
     description: "Backend API endpoints and request handling"
   },
@@ -75,6 +75,61 @@ const DEFAULT_DOMAIN_HINTS = [
     match: ["job", "queue", "worker", "cron", "task", "scheduler", "background"],
     domain: "Background Jobs",
     description: "Background processing, job queues, and scheduled tasks"
+  },
+  {
+    match: ["core", "kernel", "foundation", "engine"],
+    domain: "Core Engine",
+    description: "Core business logic and foundational modules"
+  },
+  {
+    match: ["render", "template", "format", "output"],
+    domain: "Rendering & Output",
+    description: "Content rendering, formatting, and output generation"
+  },
+  {
+    match: ["publish", "deploy", "release", "distribute"],
+    domain: "Publishing & Delivery",
+    description: "Content and artifact publishing, deployment, and distribution"
+  },
+  {
+    match: ["analyz", "inspect", "detect", "lint", "scan", "parse"],
+    domain: "Analysis & Detection",
+    description: "Code analysis, pattern detection, and static inspection"
+  },
+  {
+    match: ["plugin", "extension", "addon", "module"],
+    domain: "Plugin System",
+    description: "Extensibility framework, plugins, and add-ons"
+  },
+  {
+    match: ["deliver", "dispatch", "send", "transport"],
+    domain: "Delivery",
+    description: "Content delivery and distribution channels"
+  },
+  {
+    match: ["doc", "generate", "markdown", "readme"],
+    domain: "Documentation",
+    description: "Documentation generation and management"
+  },
+  {
+    match: ["integrat", "connect", "adapter", "bridge", "gateway"],
+    domain: "Integrations",
+    description: "Third-party service integrations and adapters"
+  },
+  {
+    match: ["cli", "command", "bin", "terminal", "shell", "prompt"],
+    domain: "CLI & Commands",
+    description: "Command-line interface and terminal commands"
+  },
+  {
+    match: ["ai", "ml", "llm", "gpt", "openai", "anthropic", "gemini"],
+    domain: "AI & Machine Learning",
+    description: "AI/ML integration, LLM providers, and intelligent features"
+  },
+  {
+    match: ["service", "provider", "client", "sdk"],
+    domain: "Services",
+    description: "Service layer, providers, and external client SDKs"
   }
 ];
 

package/src/core/scan.js

@@ -29,13 +29,22 @@ function isExpressRoute(content) {
 }
 
 function isReactRouterFile(content) {
-  // Detect React Router patterns
-  return content.includes("<Route") || content.includes("createBrowserRouter") || content.includes("createRoutesFromElements");
+  // Detect React Router patterns — require import evidence, not just string mentions
+  const hasImport = /import\s+.*?from\s+['"]react-router/.test(content)
+    || /require\s*\(\s*['"]react-router/.test(content);
+  const hasJSX = /<Route\s/.test(content);
+  const hasFactory = /createBrowserRouter\s*\(/.test(content)
+    || /createRoutesFromElements\s*\(/.test(content);
+  return hasImport || hasJSX || hasFactory;
 }
 
 function isVueRouterFile(content) {
-  // Detect Vue Router patterns  
-  return (content.includes("createRouter") || content.includes("VueRouter")) && content.includes("routes");
+  // Detect Vue Router patterns — require import evidence, not just string mentions
+  const hasImport = /import\s+.*?from\s+['"]vue-router/.test(content)
+    || /require\s*\(\s*['"]vue-router/.test(content);
+  const hasConstructor = /new\s+VueRouter\s*\(/.test(content);
+  const hasFactory = /createRouter\s*\(/.test(content) && hasImport;
+  return hasImport || hasConstructor || hasFactory;
 }
 
 function isNextPage(file) {
@@ -159,6 +168,10 @@ async function extractRepoMetadata(repoRoot) {
     if (allDeps["nestjs"] || allDeps["@nestjs/core"]) metadata.frameworks.push("NestJS");
     if (allDeps["svelte"]) metadata.frameworks.push("Svelte");
     if (allDeps["solid-js"]) metadata.frameworks.push("Solid");
+    if (allDeps["hono"]) metadata.frameworks.push("Hono");
+    if (allDeps["koa"]) metadata.frameworks.push("Koa");
+    if (allDeps["hapi"] || allDeps["@hapi/hapi"]) metadata.frameworks.push("Hapi");
+    if (allDeps["electron"]) metadata.frameworks.push("Electron");
 
     // Detect test frameworks
     if (allDeps["vitest"]) metadata.testFrameworks.push("Vitest");
@@ -166,6 +179,7 @@ async function extractRepoMetadata(repoRoot) {
     if (allDeps["mocha"]) metadata.testFrameworks.push("Mocha");
     if (allDeps["playwright"]) metadata.testFrameworks.push("Playwright");
     if (allDeps["cypress"]) metadata.testFrameworks.push("Cypress");
+    if (allDeps["ava"]) metadata.testFrameworks.push("Ava");
 
     // Detect build tools
     if (allDeps["vite"]) metadata.buildTools.push("Vite");
@@ -173,9 +187,25 @@ async function extractRepoMetadata(repoRoot) {
     if (allDeps["rollup"]) metadata.buildTools.push("Rollup");
     if (allDeps["esbuild"]) metadata.buildTools.push("esbuild");
     if (allDeps["turbo"]) metadata.buildTools.push("Turborepo");
+    if (allDeps["tsup"]) metadata.buildTools.push("tsup");
+    if (allDeps["swc"] || allDeps["@swc/core"]) metadata.buildTools.push("SWC");
+    if (allDeps["parcel"]) metadata.buildTools.push("Parcel");
 
-    // Detect TypeScript
+    // Detect languages
     if (allDeps["typescript"]) metadata.languages.add("TypeScript");
+
+    // Infer JavaScript if package.json exists (any npm project uses JS/Node)
+    metadata.languages.add("JavaScript");
+
+    // Detect Node.js runtime indicators
+    const hasNodeEngines = pkg.engines && pkg.engines.node;
+    const hasBin = pkg.bin != null;
+    const hasNodeDeps = allDeps["node-fetch"] || allDeps["fs-extra"] || allDeps["dotenv"]
+      || allDeps["commander"] || allDeps["yargs"] || allDeps["chalk"]
+      || allDeps["inquirer"] || allDeps["ora"] || allDeps["execa"];
+    if (hasNodeEngines || hasBin || hasNodeDeps || pkg.type === "module") {
+      metadata.languages.add("Node.js");
+    }
   } catch {
     // No package.json or invalid JSON
   }
@@ -241,30 +271,29 @@ function extractExpressRoutes(content) {
 
 function extractReactRoutes(content, file) {
   const routes = [];
+  const lines = content.split("\n");
   
   // Match <Route path="..." />
   const routePattern = /<Route\s+[^>]*path\s*=\s*['"`]([^'"`]+)['"`][^>]*\/?>/gi;
   let match;
 
   while ((match = routePattern.exec(content)) !== null) {
-    const [, path] = match;
-    routes.push({
-      file,
-      path,
-      framework: "React Router"
-    });
+    const [, routePath] = match;
+    if (isValidRoutePath(routePath)) {
+      routes.push({ file, path: routePath, framework: "React Router" });
+    }
   }
 
-  // Match path: "..." in route objects  
-  const objectPattern = /path\s*:\s*['"`]([^'"`]+)['"`]/gi;
-  while ((match = objectPattern.exec(content)) !== null) {
-    const [, path] = match;
-    if (!routes.some(r => r.path === path)) {
-      routes.push({
-        file,
-        path,
-        framework: "React Router"
-      });
+  // Match path: "..." in route objects (skip comment lines)
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) continue;
+    const objectMatch = /path\s*:\s*['"`]([^'"`]+)['"`]/i.exec(trimmed);
+    if (objectMatch) {
+      const routePath = objectMatch[1];
+      if (isValidRoutePath(routePath) && !routes.some(r => r.path === routePath)) {
+        routes.push({ file, path: routePath, framework: "React Router" });
+      }
     }
   }
 
@@ -273,23 +302,31 @@ function extractReactRoutes(content, file) {
 
 function extractVueRoutes(content, file) {
   const routes = [];
-  
-  // Match path: '...' or path: "..." in Vue router definitions
-  const pathPattern = /path\s*:\s*['"`]([^'"`]+)['"`]/gi;
-  let match;
-
-  while ((match = pathPattern.exec(content)) !== null) {
-    const [, path] = match;
-    routes.push({
-      file,
-      path,
-      framework: "Vue Router"
-    });
+  const lines = content.split("\n");
+
+  // Match path: '...' or path: "..." in Vue router definitions (skip comment lines)
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) continue;
+    const match = /path\s*:\s*['"`]([^'"`]+)['"`]/i.exec(trimmed);
+    if (match) {
+      const routePath = match[1];
+      if (isValidRoutePath(routePath) && !routes.some(r => r.path === routePath)) {
+        routes.push({ file, path: routePath, framework: "Vue Router" });
+      }
+    }
   }
 
   return routes;
 }
 
+function isValidRoutePath(p) {
+  // Filter out placeholder/documentation strings and non-path values
+  if (!p || p === "..." || p === "*" || p.length > 200) return false;
+  // Must look like a URL path (starts with / or is a relative segment)
+  return p.startsWith("/") || /^[a-zA-Z0-9]/.test(p);
+}
+
 export async function scanRepo(cfg) {
   const repoRoot = cfg.__repoRoot;
 

package/src/docs/generate-doc-set.js

@@ -184,16 +184,16 @@ async function generateDocument(docPlan, context) {
   
   switch (key) {
     case "executive_summary":
-      return await generateExecutiveSummary(aiContext);
+      return await generateExecutiveSummary(aiContext, { depGraph, flows });
       
     case "system_overview":
-      return await generateSystemOverview(aiContext);
+      return await generateSystemOverview(aiContext, { depGraph });
       
     case "business_domains":
-      return await generateBusinessDomains(aiContext);
+      return await generateBusinessDomains(aiContext, { depGraph });
       
     case "architecture_overview":
-      return await generateArchitectureOverview(aiContext);
+      return await generateArchitectureOverview(aiContext, { depGraph, driftResult });
       
     case "module_catalog":
       // Hybrid: deterministic skeleton + ownership info
@@ -208,7 +208,7 @@ async function generateDocument(docPlan, context) {
       return renderApiSurfaceOriginal(config, scanResult);
       
     case "data_flows":
-      return await generateDataFlows(flows, aiContext);
+      return await generateDataFlows(flows, aiContext, { depGraph, scanResult });
       
     case "arch_diff":
       if (!diffData) {
@@ -221,7 +221,7 @@ async function generateDocument(docPlan, context) {
       return renderSystemMap(scanResult, config, depGraph);
       
     case "developer_onboarding":
-      return await generateDeveloperOnboarding(aiContext);
+      return await generateDeveloperOnboarding(aiContext, { flows, depGraph });
       
     case "graphql_schema":
       return renderGraphQLSchema(graphqlResult);

package/src/renderers/renderMap.js

@@ -90,15 +90,23 @@ function buildModuleGraph(modules, depGraph) {
 
 /**
  * Find which module a file belongs to.
+ * Edge keys from the dep graph are extensionless (e.g. "src/core/config")
+ * while module keys may include extensions (e.g. "src/core/config.js").
+ * We try both direct match and extension-stripped match.
  */
 function findModuleForFile(fileKey, modules) {
   const normalized = fileKey.replace(/\\/g, "/");
-  // Find the most specific (longest) matching module key
   let bestMatch = null;
   for (const mod of modules) {
-    if (normalized.startsWith(mod.key) || normalized.startsWith(mod.key + "/")) {
-      if (!bestMatch || mod.key.length > bestMatch.length) {
-        bestMatch = mod.key;
+    const modKey = mod.key;
+    // Direct match (with or without extension)
+    if (normalized === modKey || normalized === modKey.replace(/\.[^/.]+$/, "")) {
+      return modKey;
+    }
+    // Prefix match: file is inside this module
+    if (normalized.startsWith(modKey + "/") || normalized.startsWith(modKey.replace(/\.[^/.]+$/, "") + "/")) {
+      if (!bestMatch || modKey.length > bestMatch.length) {
+        bestMatch = modKey;
       }
     }
   }
@@ -107,13 +115,25 @@ function findModuleForFile(fileKey, modules) {
 
 function categorizeModule(key) {
   const normalized = key.toLowerCase();
-  if (normalized.includes("core")) return "core";
-  if (normalized.includes("publisher")) return "integration";
-  if (normalized.includes("renderer")) return "business";
-  if (normalized.includes("delivery")) return "integration";
-  if (normalized.includes("util")) return "util";
-  if (normalized.includes("test")) return "test";
-  if (normalized.includes("bin")) return "cli";
+  if (normalized.includes("test") || normalized.includes("spec")) return "test";
+  if (normalized.includes("core") || normalized.includes("kernel")) return "core";
+  if (normalized.includes("analyz") || normalized.includes("detect") || normalized.includes("inspect")) return "analyzer";
+  if (normalized.includes("render") || normalized.includes("format") || normalized.includes("template")) return "renderer";
+  if (normalized.includes("publish") || normalized.includes("output")) return "publisher";
+  if (normalized.includes("deliver") || normalized.includes("dispatch")) return "delivery";
+  if (normalized.includes("integrat") || normalized.includes("connect") || normalized.includes("adapter")) return "integration";
+  if (normalized.includes("util") || normalized.includes("helper") || normalized.includes("lib") || normalized.includes("common")) return "util";
+  if (normalized.includes("ai") || normalized.includes("llm") || normalized.includes("prompt")) return "ai";
+  if (normalized.includes("doc") || normalized.includes("generate")) return "docs";
+  if (normalized.includes("plugin") || normalized.includes("extension")) return "plugin";
+  if (normalized.includes("config") || normalized.includes("setting")) return "config";
+  if (normalized.includes("cli") || normalized.includes("bin") || normalized.includes("command")) return "cli";
+  if (normalized.includes("api") || normalized.includes("endpoint")) return "api";
+  if (normalized.includes("component") || normalized.includes("ui")) return "ui";
+  if (normalized.includes("page") || normalized.includes("route") || normalized.includes("view")) return "page";
+  if (normalized.includes("store") || normalized.includes("state")) return "state";
+  if (normalized.includes("middleware")) return "middleware";
+  if (normalized.includes("service")) return "service";
   return "other";
 }
 
@@ -122,8 +142,21 @@ function generateUnicodeArchitectureDiagram(nodes, relationships) {
   const categories = {
     cli: { icon: "🎯", label: "CLI Entry", nodes: [] },
     core: { icon: "⚙️", label: "Core Logic", nodes: [] },
-    business: { icon: "📋", label: "Business Logic", nodes: [] },
+    config: { icon: "🔧", label: "Configuration", nodes: [] },
+    analyzer: { icon: "🔍", label: "Analysis", nodes: [] },
+    ai: { icon: "🤖", label: "AI / ML", nodes: [] },
+    docs: { icon: "📝", label: "Documentation", nodes: [] },
+    renderer: { icon: "📋", label: "Rendering", nodes: [] },
+    publisher: { icon: "📤", label: "Publishing", nodes: [] },
+    delivery: { icon: "📬", label: "Delivery", nodes: [] },
     integration: { icon: "🔌", label: "Integration", nodes: [] },
+    plugin: { icon: "🧩", label: "Plugins", nodes: [] },
+    api: { icon: "🌐", label: "API Layer", nodes: [] },
+    ui: { icon: "🖼️", label: "UI Components", nodes: [] },
+    page: { icon: "📄", label: "Pages / Routes", nodes: [] },
+    state: { icon: "💾", label: "State Management", nodes: [] },
+    middleware: { icon: "🔀", label: "Middleware", nodes: [] },
+    service: { icon: "⚡", label: "Services", nodes: [] },
     util: { icon: "🛠️", label: "Utilities", nodes: [] },
     test: { icon: "✅", label: "Testing", nodes: [] },
     other: { icon: "📦", label: "Other", nodes: [] }
@@ -235,5 +268,53 @@ export function renderSystemMap(scan, config, depGraph) {
     ""
   ];
 
+  // Add key connections summary when we have relationships
+  if (relationships.length > 0) {
+    lines.push("---", "", "## Key Connections", "");
+
+    // Find most-depended-on modules (highest in-degree)
+    const inDegree = new Map();
+    const outDegree = new Map();
+    for (const rel of relationships) {
+      inDegree.set(rel.to, (inDegree.get(rel.to) || 0) + (rel.weight || 1));
+      outDegree.set(rel.from, (outDegree.get(rel.from) || 0) + (rel.weight || 1));
+    }
+
+    const topDeps = [...inDegree.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+
+    if (topDeps.length > 0) {
+      lines.push("**Most depended-on modules** (highest import count):", "");
+      lines.push("| Module | Imported by |");
+      lines.push("|--------|------------|");
+      for (const [nodeId, count] of topDeps) {
+        const node = nodes.find(n => n.id === nodeId);
+        if (node) {
+          lines.push(`| \`${node.label}\` | ${count} module${count !== 1 ? "s" : ""} |`);
+        }
+      }
+      lines.push("");
+    }
+
+    // Find modules with highest out-degree (most dependencies)
+    const topConsumers = [...outDegree.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5);
+
+    if (topConsumers.length > 0) {
+      lines.push("**Most dependent modules** (highest dependency count):", "");
+      lines.push("| Module | Depends on |");
+      lines.push("|--------|-----------|");
+      for (const [nodeId, count] of topConsumers) {
+        const node = nodes.find(n => n.id === nodeId);
+        if (node) {
+          lines.push(`| \`${node.label}\` | ${count} module${count !== 1 ? "s" : ""} |`);
+        }
+      }
+      lines.push("");
+    }
+  }
+
   return lines.join("\n");
 }