@chappibunny/repolens 0.6.4 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 0.7.0
+
+### ✨ New Features
+- **Interactive Init Wizard**: `repolens init --interactive` — step-by-step configuration wizard with scan presets (Next.js, Express, generic), publisher selection, AI provider setup, and branch filtering
+- **Watch Mode**: `repolens watch` — watches source directories for changes and regenerates Markdown docs with 500ms debounce (no API calls)
+- **Enhanced Error Messages**: Centralized error catalog with actionable guidance — every error now shows what went wrong, why, and how to fix it
+- **Performance Monitoring**: Scan, render, and publish timing summary printed after every `publish` run
+- **Coverage Scoring Improvements**: New section completeness metric (12 document types tracked), updated health score weights, and `metrics.json` snapshots saved to `.repolens/`
+
 ## 0.6.4
 
 ### 🔧 Maintenance

package/README.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="Avatar.png" alt="RepoLens" width="120" />
-</p>
-
 ```
     ██████╗ ███████╗██████╗  ██████╗ ██╗     ███████╗███╗   ██╗███████╗
     ██╔══██╗██╔════╝██╔══██╗██╔═══██╗██║     ██╔════╝████╗  ██║██╔════╝
@@ -9,7 +5,7 @@
     ██╔══██╗██╔══╝  ██╔═══╝ ██║   ██║██║     ██╔══╝  ██║╚██╗██║╚════██║
     ██║  ██║███████╗██║     ╚██████╔╝███████╗███████╗██║ ╚████║███████║
     ╚═╝  ╚═╝╚══════╝╚═╝      ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═══╝╚══════╝
-                        🔍 Repository Intelligence CLI 📊
+                        Repository Intelligence CLI
 ```
 
 [![Tests](https://img.shields.io/badge/tests-90%20passing-brightgreen)](https://github.com/CHAPIBUNNY/repolens/actions)
@@ -20,7 +16,7 @@
 
 AI-assisted documentation intelligence system that generates architecture docs for engineers AND readable system docs for stakeholders
 
-**Current Status**: v0.6.4 — User Feedback & Team Features
+**Current Status**: v0.7.0 — Polish & Reliability
 
 RepoLens automatically generates and maintains living architecture documentation by analyzing your repository structure, extracting meaningful insights from your package.json, and creating visual dependency graphs. Run it once, or let it auto-update on every push.
 
@@ -132,7 +128,11 @@ RepoLens automatically detects:
 ✅ **Branch-Aware** - Prevent doc conflicts across branches  
 ✅ **GitHub Actions** - Autonomous operation on every push  
 ✅ **Team Notifications** - Discord integration with rich embeds (NEW in v0.6.0)  
-✅ **Health Score Tracking** - Monitor documentation quality over time (NEW in v0.6.0)  
+✅ **Health Score Tracking** - Monitor documentation quality over time  
+✅ **Watch Mode** - Auto-regenerate docs on file changes (NEW in v0.7.0)  
+✅ **Interactive Setup** - Step-by-step configuration wizard (NEW in v0.7.0)  
+✅ **Performance Metrics** - Timing breakdown for scan/render/publish (NEW in v0.7.0)  
+✅ **Actionable Errors** - Enhanced error messages with fix guidance (NEW in v0.7.0)  
 
 ---
 
@@ -224,7 +224,7 @@ npm link
 Install from a specific version:
 
 ```bash
-npm install https://github.com/CHAPIBUNNY/repolens/releases/download/v0.6.4/chappibunny-repolens-0.6.4.tgz
+npm install https://github.com/CHAPIBUNNY/repolens/releases/download/v0.7.0/chappibunny-repolens-0.7.0.tgz
 ```
 </details>
 
@@ -1077,7 +1077,7 @@ Simulates the full user installation experience:
 npm pack
 
 # Install globally from tarball
-npm install -g chappibunny-repolens-0.6.4.tgz
+npm install -g chappibunny-repolens-0.7.0.tgz
 
 # Verify
 repolens --version
@@ -1091,9 +1091,10 @@ repolens/
 │   └── repolens.js          # CLI executable wrapper
 ├── src/
 │   ├── cli.js               # Command orchestration + banner
-│   ├── init.js              # Scaffolding command
+│   ├── init.js              # Scaffolding command (+ interactive wizard)
 │   ├── doctor.js            # Validation command
 │   ├── migrate.js           # Workflow migration (legacy → current)
+│   ├── watch.js             # Watch mode for local development
 │   ├── core/
 │   │   ├── config.js        # Config loading + validation
 │   │   ├── config-schema.js # Schema version tracking
@@ -1133,7 +1134,8 @@ repolens/
 │       ├── metrics.js       # Documentation coverage & health scoring
 │       ├── rate-limit.js    # Token bucket rate limiter for APIs
 │       ├── secrets.js       # Secret detection & sanitization
-│       ├── telemetry.js     # Opt-in error tracking (Sentry)
+│       ├── telemetry.js     # Opt-in error tracking + performance timers
+│       ├── errors.js        # Enhanced error messages with guidance
 │       └── update-check.js  # Version update notifications
 ├── tests/                   # Vitest test suite (90 tests across 11 files)
 ├── .repolens.yml            # Dogfooding config
@@ -1152,13 +1154,13 @@ RepoLens uses automated GitHub Actions releases.
 ### Creating a Release
 
 ```bash
-# Patch version (0.6.4 → 0.6.5) - Bug fixes
+# Patch version (0.7.0 → 0.7.1) - Bug fixes
 npm run release:patch
 
-# Minor version (0.6.4 → 0.7.0) - New features
+# Minor version (0.7.0 → 0.8.0) - New features
 npm run release:minor
 
-# Major version (0.6.4 → 1.0.0) - Breaking changes
+# Major version (0.7.0 → 1.0.0) - Breaking changes
 npm run release:major
 
 # Push the tag to trigger workflow
@@ -1190,11 +1192,11 @@ RepoLens is currently in early access. v1.0 will open for community contribution
 
 ## 🗺️ Roadmap to v1.0
 
-**Current Status:** v0.6.4 — User Feedback & Team Features
+**Current Status:** v0.7.0 — Polish & Reliability
 
 ### Completed ✅
 
-- [x] CLI commands: `init`, `doctor`, `publish`, `migrate`, `feedback`, `version`, `help`
+- [x] CLI commands: `init`, `doctor`, `publish`, `migrate`, `watch`, `feedback`, `version`, `help`
 - [x] Config schema v1 with validation
 - [x] Auto-discovery of `.repolens.yml`
 - [x] Publishers: Notion + Confluence + Markdown
@@ -1214,14 +1216,17 @@ RepoLens is currently in early access. v1.0 will open for community contribution
 - [x] npm registry publication (`@chappibunny/repolens`)
 - [x] Automated npm releases via GitHub Actions
 - [x] Workflow migration command (`repolens migrate`)
+- [x] Interactive configuration wizard (`repolens init --interactive`)
+- [x] Watch mode for local development (`repolens watch`)
+- [x] Enhanced error messages with actionable guidance
+- [x] Performance monitoring (scan/render/publish timing)
+- [x] Improved documentation coverage scoring
 
 ### Planned for v1.0 🎯
 
 - [ ] Plugin system for custom renderers
 - [ ] GraphQL schema detection
 - [ ] TypeScript type graph analysis
-- [ ] Interactive configuration wizard
-- [ ] Watch mode for local development
 - [ ] Additional publishers (GitHub Wiki, Obsidian)
 
 See [ROADMAP.md](./ROADMAP.md) for detailed planning.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",

package/src/cli.js

@@ -20,7 +20,9 @@ import { publishDocs } from "./publishers/index.js";
 import { upsertPrComment } from "./delivery/comment.js";
 import { runInit } from "./init.js";
 import { runMigrate } from "./migrate.js";
+import { runWatch } from "./watch.js";
 import { info, error } from "./utils/logger.js";
+import { formatError } from "./utils/errors.js";
 import { checkForUpdates } from "./utils/update-check.js";
 import { generateDocumentSet } from "./docs/generate-doc-set.js";
 import { writeDocumentSet } from "./docs/write-doc-set.js";
@@ -32,10 +34,34 @@ import {
   trackUsage,
   startTimer,
   stopTimer,
-  sendFeedback
+  sendFeedback,
+  getTimings
 } from "./utils/telemetry.js";
 import { createInterface } from "node:readline";
 
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function printPerformanceSummary() {
+  const timings = getTimings();
+  if (timings.length === 0) return;
+
+  console.log("\n" + "─".repeat(40));
+  console.log("  Phase          Duration");
+  console.log("  " + "─".repeat(30));
+  let total = 0;
+  for (const { operation, duration } of timings) {
+    const label = operation.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase());
+    console.log(`  ${label.padEnd(16)} ${formatDuration(duration)}`);
+    total += duration;
+  }
+  console.log("  " + "─".repeat(30));
+  console.log(`  ${"Total".padEnd(16)} ${formatDuration(total)}`);
+  console.log("─".repeat(40));
+}
+
 async function getPackageVersion() {
   const __filename = fileURLToPath(import.meta.url);
   const __dirname = path.dirname(__filename);
@@ -93,8 +119,7 @@ async function findConfig(startDir = process.cwd()) {
     return rootConfigPath;
   } catch {
     throw new Error(
-      "RepoLens config not found (.repolens.yml)\n" +
-      "Run 'repolens init' to create one, or use --config to specify a path."
+      formatError("CONFIG_NOT_FOUND")
     );
   }
 }
@@ -111,25 +136,30 @@ Commands:
   doctor      Validate your RepoLens setup
   migrate     Upgrade workflow files to v0.4.0 format
   publish     Scan, render, and publish documentation
+  watch       Watch for file changes and regenerate docs
   feedback    Send feedback to the RepoLens team
   version     Print the current RepoLens version
 
 Options:
-  --config     Path to .repolens.yml (auto-discovered if not provided)
-  --target     Target repository path for init/doctor/migrate
-  --dry-run    Preview migration changes without applying them
-  --force      Skip interactive confirmation for migration
-  --verbose    Enable verbose logging
-  --version    Print version
-  --help       Show this help message
+  --config        Path to .repolens.yml (auto-discovered if not provided)
+  --target        Target repository path for init/doctor/migrate
+  --interactive   Run init with step-by-step configuration wizard
+  --dry-run       Preview migration changes without applying them
+  --force         Skip interactive confirmation for migration
+  --verbose       Enable verbose logging
+  --version       Print version
+  --help          Show this help message
 
 Examples:
+  repolens init                                 # Quick setup with auto-detection
+  repolens init --interactive                   # Step-by-step wizard
   repolens init --target /tmp/my-repo
   repolens doctor --target /tmp/my-repo
   repolens migrate                              # Migrate workflows in current directory
   repolens migrate --dry-run                    # Preview changes without applying
   repolens publish                              # Auto-discovers .repolens.yml
   repolens publish --config /path/.repolens.yml # Explicit config path
+  repolens watch                                # Watch mode (Markdown only)
   repolens --version
 `);
 }
@@ -163,11 +193,12 @@ async function main() {
   if (command === "init") {
     await printBanner();
     const targetDir = getArg("--target") || process.cwd();
+    const interactive = process.argv.includes("--interactive");
     info(`Initializing RepoLens in: ${targetDir}`);
     
     const timer = startTimer("init");
     try {
-      await runInit(targetDir);
+      await runInit(targetDir, { interactive });
       const duration = stopTimer(timer);
       info("✓ RepoLens initialized successfully");
       
@@ -239,6 +270,20 @@ async function main() {
     return;
   }
 
+  if (command === "watch") {
+    await printBanner();
+    let configPath;
+    try {
+      configPath = getArg("--config") || await findConfig();
+      info(`Using config: ${configPath}`);
+    } catch (err) {
+      error(err.message);
+      process.exit(2);
+    }
+    await runWatch(configPath);
+    return;
+  }
+
   if (command === "publish" || !command || command.startsWith("--")) {
     await printBanner();
     
@@ -263,8 +308,7 @@ async function main() {
       stopTimer(commandTimer);
       captureError(err, { command: "publish", step: "load-config", configPath });
       trackUsage("publish", "failure", { step: "config-load" });
-      error("Failed to load configuration:");
-      error(err.message);
+      error(formatError("CONFIG_VALIDATION_FAILED", err));
       await closeTelemetry();
       process.exit(2);
     }
@@ -279,8 +323,9 @@ async function main() {
       stopTimer(commandTimer);
       captureError(err, { command: "publish", step: "scan", patterns: cfg.scan?.patterns });
       trackUsage("publish", "failure", { step: "scan" });
-      error("Failed to scan repository:");
-      error(err.message);
+      const code = err.message?.includes("No files") ? "SCAN_NO_FILES" 
+                 : err.message?.includes("limit") ? "SCAN_TOO_MANY_FILES" : null;
+      error(code ? formatError(code, err) : `Failed to scan repository:\n  ${err.message}`);
       await closeTelemetry();
       process.exit(1);
     }
@@ -316,6 +361,8 @@ async function main() {
       
       const totalDuration = stopTimer(commandTimer);
       
+      printPerformanceSummary();
+      
       // Track successful publish with comprehensive metrics
       const publishers = [];
       if (cfg.publishers?.notion?.enabled !== false) publishers.push("notion");
@@ -388,7 +435,7 @@ async function main() {
   }
 
   error(`Unknown command: ${command}`);
-  error("Available commands: init, doctor, migrate, publish, feedback, version, help");
+  error("Available commands: init, doctor, migrate, publish, watch, feedback, version, help");
   process.exit(1);
 }
 
@@ -402,11 +449,9 @@ main().catch(async (err) => {
   console.error("\n❌ RepoLens encountered an unexpected error:\n");
   
   if (err.code === "ENOENT") {
-    error(`File not found: ${err.path}`);
-    error("Check that all required files exist and paths are correct.");
+    error(formatError("FILE_NOT_FOUND", err.path));
   } else if (err.code === "EACCES") {
-    error(`Permission denied: ${err.path}`);
-    error("Check file permissions and try again.");
+    error(formatError("FILE_PERMISSION_DENIED", err.path));
   } else if (err.message) {
     error(err.message);
   } else {

package/src/init.js

@@ -3,6 +3,39 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { info, warn } from "./utils/logger.js";
 
+const PUBLISHER_CHOICES = ["markdown", "notion", "confluence"];
+const AI_PROVIDERS = ["openai", "anthropic", "azure", "ollama"];
+const SCAN_PRESETS = {
+  nextjs: {
+    include: [
+      "src/**/*.{ts,tsx,js,jsx}",
+      "app/**/*.{ts,tsx,js,jsx}",
+      "pages/**/*.{ts,tsx,js,jsx}",
+      "lib/**/*.{ts,tsx,js,jsx}",
+      "components/**/*.{ts,tsx,js,jsx}",
+    ],
+    roots: ["src", "app", "pages", "lib", "components"],
+  },
+  express: {
+    include: [
+      "src/**/*.{ts,js}",
+      "routes/**/*.{ts,js}",
+      "controllers/**/*.{ts,js}",
+      "models/**/*.{ts,js}",
+      "middleware/**/*.{ts,js}",
+    ],
+    roots: ["src", "routes", "controllers", "models"],
+  },
+  generic: {
+    include: [
+      "src/**/*.{ts,tsx,js,jsx,md}",
+      "app/**/*.{ts,tsx,js,jsx,md}",
+      "lib/**/*.{ts,tsx,js,jsx,md}",
+    ],
+    roots: ["src", "app", "lib"],
+  },
+};
+
 const DETECTABLE_ROOTS = [
   "app",
   "src/app",
@@ -465,14 +498,183 @@ async function ensureEnvInGitignore(repoRoot) {
   }
 }
 
-export async function runInit(targetDir = process.cwd()) {
+/**
+ * Run a fully interactive configuration wizard.
+ * Returns a structured config that replaces the auto-detected defaults.
+ */
+async function runInteractiveWizard(repoRoot) {
+  const isCI = process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI ||
+               process.env.CIRCLECI || process.env.JENKINS_HOME || process.env.CODEBUILD_BUILD_ID;
+  const isTest = process.env.NODE_ENV === "test" || process.env.VITEST;
+  if (isCI || isTest) return null;
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => rl.question(q);
+
+  try {
+    info("\n🧙 Interactive Configuration Wizard\n");
+
+    // 1. Project name
+    const defaultName = path.basename(repoRoot) || "my-project";
+    const projectName = (await ask(`Project name (${defaultName}): `)).trim() || defaultName;
+
+    // 2. Publishers
+    info("\nSelect publishers (comma-separated numbers):");
+    PUBLISHER_CHOICES.forEach((p, i) => info(`  ${i + 1}. ${p}`));
+    const pubInput = (await ask(`Publishers [1,2,3] (default: 1): `)).trim() || "1";
+    const publishers = pubInput
+      .split(",")
+      .map((n) => parseInt(n.trim(), 10))
+      .filter((n) => n >= 1 && n <= PUBLISHER_CHOICES.length)
+      .map((n) => PUBLISHER_CHOICES[n - 1]);
+    if (publishers.length === 0) publishers.push("markdown");
+
+    // 3. AI
+    const enableAi = (await ask("\nEnable AI-enhanced documentation? (y/N): ")).trim().toLowerCase() === "y";
+    let aiProvider = null;
+    if (enableAi) {
+      info("Select AI provider:");
+      AI_PROVIDERS.forEach((p, i) => info(`  ${i + 1}. ${p}`));
+      const aiInput = (await ask(`Provider [1] (default: 1 openai): `)).trim() || "1";
+      const idx = parseInt(aiInput, 10);
+      aiProvider = AI_PROVIDERS[(idx >= 1 && idx <= AI_PROVIDERS.length) ? idx - 1 : 0];
+    }
+
+    // 4. Scan preset
+    info("\nScan preset:");
+    const presetKeys = Object.keys(SCAN_PRESETS);
+    presetKeys.forEach((p, i) => info(`  ${i + 1}. ${p}`));
+    const presetInput = (await ask(`Preset [3] (default: 3 generic): `)).trim() || "3";
+    const presetIdx = parseInt(presetInput, 10);
+    const presetKey = presetKeys[(presetIdx >= 1 && presetIdx <= presetKeys.length) ? presetIdx - 1 : 2];
+    const preset = SCAN_PRESETS[presetKey];
+
+    // 5. Branch filtering
+    const branchInput = (await ask("\nBranches allowed to publish to Notion/Confluence (comma-separated, default: main): ")).trim() || "main";
+    const branches = branchInput.split(",").map((b) => b.trim()).filter(Boolean);
+
+    // 6. Discord
+    const enableDiscord = (await ask("\nEnable Discord notifications? (y/N): ")).trim().toLowerCase() === "y";
+
+    info("\n✓ Wizard complete. Generating config...\n");
+    return { projectName, publishers, enableAi, aiProvider, preset, branches, enableDiscord };
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Build a .repolens.yml from wizard answers.
+ */
+function buildWizardConfig(answers) {
+  const lines = [
+    `configVersion: 1`,
+    ``,
+    `project:`,
+    `  name: "${answers.projectName}"`,
+    `  docs_title_prefix: "RepoLens"`,
+    ``,
+    `publishers:`,
+  ];
+  for (const p of answers.publishers) {
+    lines.push(`  - ${p}`);
+  }
+
+  if (answers.publishers.includes("notion") && answers.branches.length) {
+    lines.push(``);
+    lines.push(`notion:`);
+    lines.push(`  branches:`);
+    for (const b of answers.branches) lines.push(`    - ${b}`);
+    lines.push(`  includeBranchInTitle: false`);
+  }
+  if (answers.publishers.includes("confluence") && answers.branches.length) {
+    lines.push(``);
+    lines.push(`confluence:`);
+    lines.push(`  branches:`);
+    for (const b of answers.branches) lines.push(`    - ${b}`);
+  }
+
+  if (answers.enableDiscord) {
+    lines.push(``);
+    lines.push(`discord:`);
+    lines.push(`  enabled: true`);
+    lines.push(`  notifyOn: significant`);
+    lines.push(`  significantThreshold: 10`);
+  }
+
+  if (answers.enableAi) {
+    lines.push(``);
+    lines.push(`ai:`);
+    lines.push(`  enabled: true`);
+    lines.push(`  mode: hybrid`);
+    lines.push(`  temperature: 0.3`);
+    lines.push(``);
+    lines.push(`features:`);
+    lines.push(`  executive_summary: true`);
+    lines.push(`  business_domains: true`);
+    lines.push(`  architecture_overview: true`);
+    lines.push(`  data_flows: true`);
+    lines.push(`  developer_onboarding: true`);
+    lines.push(`  change_impact: true`);
+  }
+
+  lines.push(``);
+  lines.push(`scan:`);
+  lines.push(`  include:`);
+  for (const p of answers.preset.include) lines.push(`    - "${p}"`);
+  lines.push(``);
+  lines.push(`  ignore:`);
+  for (const p of buildIgnorePatterns()) lines.push(`    - "${p}"`);
+
+  lines.push(``);
+  lines.push(`module_roots:`);
+  for (const r of answers.preset.roots) lines.push(`  - "${r}"`);
+
+  lines.push(``);
+  lines.push(`outputs:`);
+  lines.push(`  pages:`);
+  lines.push(`    - key: "system_overview"`);
+  lines.push(`      title: "System Overview"`);
+  lines.push(`      description: "High-level snapshot of the repo and what RepoLens detected."`);
+  lines.push(``);
+  lines.push(`    - key: "module_catalog"`);
+  lines.push(`      title: "Module Catalog"`);
+  lines.push(`      description: "Auto-detected modules with file counts."`);
+  lines.push(``);
+  lines.push(`    - key: "api_surface"`);
+  lines.push(`      title: "API Surface"`);
+  lines.push(`      description: "Auto-detected API routes/endpoints."`);
+  lines.push(``);
+  lines.push(`    - key: "arch_diff"`);
+  lines.push(`      title: "Architecture Diff"`);
+  lines.push(`      description: "Reserved for PR/merge change summaries."`);
+  lines.push(``);
+  lines.push(`    - key: "route_map"`);
+  lines.push(`      title: "Route Map"`);
+  lines.push(`      description: "Detected app routes and API routes."`);
+  lines.push(``);
+  lines.push(`    - key: "system_map"`);
+  lines.push(`      title: "System Map"`);
+  lines.push(`      description: "Unicode architecture diagram of detected modules."`);
+  lines.push(``);
+
+  return lines.join("\n");
+}
+
+export async function runInit(targetDir = process.cwd(), options = {}) {
   const repoRoot = path.resolve(targetDir);
 
   // Ensure target directory exists
   await fs.mkdir(repoRoot, { recursive: true });
 
-  // Prompt for Notion credentials interactively
-  const notionCredentials = await promptNotionCredentials();
+  // Interactive wizard if --interactive flag is set
+  let wizardAnswers = null;
+  if (options.interactive) {
+    wizardAnswers = await runInteractiveWizard(repoRoot);
+  }
+
+  // Prompt for Notion credentials interactively (only in non-wizard mode)
+  const notionCredentials = wizardAnswers ? null : await promptNotionCredentials();
 
   const repolensConfigPath = path.join(repoRoot, ".repolens.yml");
   const workflowDir = path.join(repoRoot, ".github", "workflows");
@@ -489,9 +691,11 @@ export async function runInit(targetDir = process.cwd()) {
   const envExists = await fileExists(envPath);
   const readmeExists = await fileExists(readmePath);
 
-  const projectName = detectProjectName(repoRoot);
-  const detectedRoots = await detectRepoStructure(repoRoot);
-  const configContent = buildRepoLensConfig(projectName, detectedRoots);
+  const projectName = wizardAnswers?.projectName || detectProjectName(repoRoot);
+  const detectedRoots = wizardAnswers ? [] : await detectRepoStructure(repoRoot);
+  const configContent = wizardAnswers
+    ? buildWizardConfig(wizardAnswers)
+    : buildRepoLensConfig(projectName, detectedRoots);
 
   info(`Detected project name: ${projectName}`);
 

package/src/publishers/confluence.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { log, info, warn } from "../utils/logger.js";
 import { fetchWithRetry } from "../utils/retry.js";
 import { getCurrentBranch, getBranchQualifiedTitle } from "../utils/branch.js";
+import { createRepoLensError } from "../utils/errors.js";
 
 /**
  * Confluence Publisher for RepoLens
@@ -25,11 +26,7 @@ function confluenceHeaders() {
   const token = process.env.CONFLUENCE_API_TOKEN;
 
   if (!email || !token) {
-    throw new Error(
-      "Missing CONFLUENCE_EMAIL or CONFLUENCE_API_TOKEN. " +
-      "Set these environment variables or GitHub Actions secrets. " +
-      "Get your API token from: https://id.atlassian.com/manage-profile/security/api-tokens"
-    );
+    throw createRepoLensError("CONFLUENCE_SECRETS_MISSING");
   }
 
   // Basic Auth for Atlassian Cloud: base64(email:api_token)

package/src/publishers/notion.js

@@ -4,13 +4,14 @@ import path from "node:path";
 import { log } from "../utils/logger.js";
 import { fetchWithRetry } from "../utils/retry.js";
 import { executeNotionRequest } from "../utils/rate-limit.js";
+import { createRepoLensError } from "../utils/errors.js";
 
 function notionHeaders() {
   const token = process.env.NOTION_TOKEN;
   const version = process.env.NOTION_VERSION || "2022-06-28";
 
   if (!token) {
-    throw new Error("Missing NOTION_TOKEN in tools/repolens/.env or GitHub Actions secrets");
+    throw createRepoLensError("NOTION_TOKEN_MISSING");
   }
 
   return {

package/src/utils/errors.js

@@ -0,0 +1,132 @@
+/**
+ * Enhanced error messages with actionable guidance.
+ * Each error includes a description, likely cause, and fix.
+ */
+
+const ERROR_CATALOG = {
+  CONFIG_NOT_FOUND: {
+    message: "RepoLens config not found (.repolens.yml)",
+    cause: "No .repolens.yml file was found in the current directory or any parent directory.",
+    fix: "Run 'repolens init' to create one, or use --config to specify a path.",
+  },
+  CONFIG_PARSE_FAILED: {
+    message: "Failed to parse .repolens.yml",
+    cause: "The configuration file contains invalid YAML syntax.",
+    fix: "Check .repolens.yml for YAML syntax errors (incorrect indentation, missing colons, etc.).",
+  },
+  CONFIG_VALIDATION_FAILED: {
+    message: "Configuration validation failed",
+    cause: "The configuration file is missing required fields or contains invalid values.",
+    fix: "Run 'repolens doctor' to identify specific issues, or compare with .repolens.example.yml.",
+  },
+  NOTION_TOKEN_MISSING: {
+    message: "NOTION_TOKEN not set",
+    cause: "The Notion integration token is not configured.",
+    fix: "Add NOTION_TOKEN to your .env file or GitHub Actions secrets.\n  → Get a token at https://notion.so/my-integrations",
+  },
+  NOTION_PAGE_ID_MISSING: {
+    message: "NOTION_PARENT_PAGE_ID not set",
+    cause: "The Notion parent page ID is not configured.",
+    fix: "Add NOTION_PARENT_PAGE_ID to your .env file or GitHub Actions secrets.\n  → Open your Notion page, copy the 32-char ID from the URL.",
+  },
+  NOTION_API_ERROR: {
+    message: "Notion API request failed",
+    cause: "The Notion API returned an error. Common causes: invalid token, page not shared with integration, rate limit hit.",
+    fix: "1. Verify NOTION_TOKEN is correct\n  2. Ensure the parent page is shared with your RepoLens integration\n  3. Check https://status.notion.so for API outages",
+  },
+  CONFLUENCE_SECRETS_MISSING: {
+    message: "Confluence credentials not configured",
+    cause: "One or more required Confluence environment variables are missing.",
+    fix: "Set these environment variables: CONFLUENCE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN, CONFLUENCE_SPACE_KEY\n  → Generate a token at https://id.atlassian.com/manage-profile/security/api-tokens",
+  },
+  CONFLUENCE_API_ERROR: {
+    message: "Confluence API request failed",
+    cause: "The Confluence API returned an error. Common causes: invalid credentials, wrong space key, permission denied.",
+    fix: "1. Verify CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN are correct\n  2. Confirm the space key exists\n  3. Check that your account has write access to the space",
+  },
+  SCAN_NO_FILES: {
+    message: "No files matched scan patterns",
+    cause: "The scan.include patterns in .repolens.yml didn't match any files.",
+    fix: "1. Check that scan.include patterns match your project structure\n  2. Ensure scan.ignore isn't excluding everything\n  3. Run 'repolens doctor' to validate your config",
+  },
+  SCAN_TOO_MANY_FILES: {
+    message: "Repository exceeds file limit (50,000 files)",
+    cause: "The scan patterns matched too many files, which would cause performance issues.",
+    fix: "Narrow your scan.include patterns or add more entries to scan.ignore.",
+  },
+  AI_API_KEY_MISSING: {
+    message: "AI API key not set",
+    cause: "REPOLENS_AI_ENABLED is true but no API key is configured.",
+    fix: "Add REPOLENS_AI_API_KEY to your .env file, or disable AI with REPOLENS_AI_ENABLED=false",
+  },
+  AI_API_ERROR: {
+    message: "AI provider returned an error",
+    cause: "The AI API request failed. Common causes: invalid key, quota exceeded, model unavailable.",
+    fix: "1. Verify your API key is valid and has credits\n  2. Check that the model name is correct\n  3. AI docs will fall back to deterministic mode automatically",
+  },
+  DISCORD_WEBHOOK_INVALID: {
+    message: "Discord webhook URL is invalid",
+    cause: "The DISCORD_WEBHOOK_URL environment variable doesn't contain a valid Discord webhook URL.",
+    fix: "Set DISCORD_WEBHOOK_URL to a valid webhook URL from Discord (Server Settings → Integrations → Webhooks).",
+  },
+  FILE_PERMISSION_DENIED: {
+    message: "Permission denied",
+    cause: "RepoLens doesn't have permission to read or write the specified file.",
+    fix: "Check file permissions and ensure the current user has read/write access.",
+  },
+  FILE_NOT_FOUND: {
+    message: "File not found",
+    cause: "A required file doesn't exist at the expected path.",
+    fix: "Check that all required files exist. Run 'repolens init' to recreate missing files.",
+  },
+};
+
+/**
+ * Create an enhanced error with actionable guidance.
+ * @param {string} code - Error code from ERROR_CATALOG
+ * @param {string} [detail] - Additional detail/context
+ * @returns {Error}
+ */
+export function createRepoLensError(code, detail) {
+  const entry = ERROR_CATALOG[code];
+  if (!entry) {
+    const err = new Error(detail || code);
+    err.code = code;
+    return err;
+  }
+
+  const parts = [entry.message];
+  if (detail) parts.push(`  ${detail}`);
+  parts.push(`  → Cause: ${entry.cause}`);
+  parts.push(`  → Fix: ${entry.fix}`);
+
+  const err = new Error(parts.join("\n"));
+  err.code = code;
+  return err;
+}
+
+/**
+ * Format an error with guidance for display.
+ * Falls back to the raw message if the error code isn't recognized.
+ * @param {string} code - Error code from ERROR_CATALOG
+ * @param {Error|string} [originalError] - The original error or context
+ * @returns {string} Formatted error string
+ */
+export function formatError(code, originalError) {
+  const entry = ERROR_CATALOG[code];
+  if (!entry) {
+    return typeof originalError === "string" ? originalError : originalError?.message || code;
+  }
+
+  const detail = typeof originalError === "string"
+    ? originalError
+    : originalError?.message;
+
+  const lines = [`Error: ${entry.message}`];
+  if (detail) lines.push(`  ${detail}`);
+  lines.push(`  → Cause: ${entry.cause}`);
+  lines.push(`  → Fix: ${entry.fix}`);
+  return lines.join("\n");
+}
+
+export { ERROR_CATALOG };

package/src/utils/metrics.js

@@ -1,12 +1,28 @@
 /**
- * Metrics Collection for RepoLens Dashboard
- * Calculates coverage, health scores, staleness, and quality issues
+ * Metrics Collection for RepoLens
+ * Calculates coverage, health scores, staleness, section completeness, and quality issues
  */
 
 import fs from "node:fs/promises";
 import path from "node:path";
 import { info, warn } from "./logger.js";
 
+/** All possible document keys that RepoLens can generate */
+const ALL_DOCUMENT_KEYS = [
+  "system_overview",
+  "module_catalog",
+  "api_surface",
+  "route_map",
+  "system_map",
+  "arch_diff",
+  "executive_summary",
+  "business_domains",
+  "architecture_overview",
+  "data_flows",
+  "change_impact",
+  "developer_onboarding",
+];
+
 /**
  * Calculate documentation coverage
  * @param {object} scanResult - Repository scan result
@@ -59,22 +75,19 @@ export function calculateCoverage(scanResult, docs) {
 
 /**
  * Calculate health score (0-100)
+ * Weights: coverage 35%, freshness 25%, quality 25%, section completeness 15%
  * @param {object} metrics - All metrics data
  * @returns {number} - Health score
  */
 export function calculateHealthScore(metrics) {
-  const { coverage, freshness, quality } = metrics;
-
-  // Coverage weight: 40%
-  const coverageScore = coverage.overall * 0.4;
+  const { coverage, freshness, quality, sectionCompleteness } = metrics;
 
-  // Freshness weight: 30%
-  const freshnessScore = freshness.score * 0.3;
+  const coverageScore = coverage.overall * 0.35;
+  const freshnessScore = freshness.score * 0.25;
+  const qualityScore = quality.score * 0.25;
+  const completenessScore = (sectionCompleteness?.percentage || 0) * 0.15;
 
-  // Quality weight: 30%
-  const qualityScore = quality.score * 0.3;
-
-  const healthScore = coverageScore + freshnessScore + qualityScore;
+  const healthScore = coverageScore + freshnessScore + qualityScore + completenessScore;
 
   return Math.round(Math.min(100, Math.max(0, healthScore)));
 }
@@ -325,6 +338,27 @@ function calculateTrends(history) {
   };
 }
 
+/**
+ * Calculate section completeness — how many of the possible document types were generated.
+ * @param {object} docs - Rendered pages map (key → content)
+ * @returns {object} - Section completeness metrics
+ */
+export function calculateSectionCompleteness(docs) {
+  const generated = Object.keys(docs || {}).filter(
+    (k) => docs[k] && docs[k].trim().length > 0
+  );
+  const total = ALL_DOCUMENT_KEYS.length;
+  const present = generated.filter((k) => ALL_DOCUMENT_KEYS.includes(k)).length;
+  const missing = ALL_DOCUMENT_KEYS.filter((k) => !generated.includes(k));
+
+  return {
+    generated: present,
+    total,
+    percentage: total > 0 ? Math.round((present / total) * 100) : 0,
+    missing,
+  };
+}
+
 /**
  * Collect all metrics
  * @param {object} scanResult - Repository scan result
@@ -339,11 +373,13 @@ export async function collectMetrics(scanResult, docs, docsPath, historyPath) {
   const coverage = calculateCoverage(scanResult, docs);
   const freshness = await detectStaleness(docsPath);
   const quality = analyzeQuality(scanResult, docs);
+  const sectionCompleteness = calculateSectionCompleteness(docs);
 
   const metrics = {
     coverage,
     freshness,
     quality,
+    sectionCompleteness,
     timestamp: new Date().toISOString(),
   };
 
@@ -354,8 +390,25 @@ export async function collectMetrics(scanResult, docs, docsPath, historyPath) {
   metrics.history = history;
   metrics.trends = trends;
 
+  // Save latest metrics snapshot for external tooling
+  try {
+    const snapshotPath = path.join(docsPath, "metrics.json");
+    await fs.mkdir(docsPath, { recursive: true });
+    await fs.writeFile(snapshotPath, JSON.stringify({
+      healthScore: metrics.healthScore,
+      coverage: metrics.coverage,
+      sectionCompleteness: metrics.sectionCompleteness,
+      quality: { score: metrics.quality.score, summary: metrics.quality.summary },
+      freshness: { score: metrics.freshness.score, isStale: metrics.freshness.isStale, daysSinceUpdate: metrics.freshness.daysSinceUpdate },
+      timestamp: metrics.timestamp,
+    }, null, 2));
+  } catch (err) {
+    warn(`Failed to save metrics snapshot: ${err.message}`);
+  }
+
   info(`✓ Health Score: ${metrics.healthScore}/100`);
   info(`✓ Coverage: ${metrics.coverage.overall.toFixed(1)}%`);
+  info(`✓ Sections: ${sectionCompleteness.generated}/${sectionCompleteness.total} document types generated`);
 
   return metrics;
 }

package/src/utils/telemetry.js

@@ -175,15 +175,15 @@ export function isTelemetryEnabled() {
 // ============================================================
 
 const performanceTimers = new Map();
+const completedTimings = [];
 
 /**
- * Start a performance timer for an operation
+ * Start a performance timer for an operation.
+ * Timers always work locally (even without telemetry) so we can print a summary.
  * @param {string} operation - Operation name (e.g., "scan", "render", "publish")
  * @param {object} metadata - Additional context about the operation
  */
 export function startTimer(operation, metadata = {}) {
-  if (!enabled) return;
-  
   const key = `${operation}_${Date.now()}`;
   performanceTimers.set(key, {
     operation,
@@ -191,15 +191,16 @@ export function startTimer(operation, metadata = {}) {
     metadata,
   });
   
-  return key; // Return key so caller can stop this specific timer
+  return key;
 }
 
 /**
  * Stop a performance timer and record the metric
  * @param {string} timerKey - Key returned from startTimer()
+ * @returns {number|undefined} Duration in milliseconds
  */
 export function stopTimer(timerKey) {
-  if (!enabled || !timerKey) return;
+  if (!timerKey) return;
   
   const timer = performanceTimers.get(timerKey);
   if (!timer) return;
@@ -207,26 +208,46 @@ export function stopTimer(timerKey) {
   const duration = Date.now() - timer.startTime;
   performanceTimers.delete(timerKey);
   
-  // Send performance metric
-  try {
-    Sentry.metrics.distribution(
-      `operation.duration`,
-      duration,
-      {
-        unit: 'millisecond',
-        tags: {
-          operation: timer.operation,
-          ...timer.metadata,
-        },
-      }
-    );
-  } catch (e) {
-    // Silently fail
+  // Store locally for summary
+  completedTimings.push({ operation: timer.operation, duration });
+  
+  // Send to Sentry if enabled
+  if (enabled) {
+    try {
+      Sentry.metrics.distribution(
+        `operation.duration`,
+        duration,
+        {
+          unit: 'millisecond',
+          tags: {
+            operation: timer.operation,
+            ...timer.metadata,
+          },
+        }
+      );
+    } catch (e) {
+      // Silently fail
+    }
   }
   
   return duration;
 }
 
+/**
+ * Get all completed timings for summary display.
+ * @returns {Array<{operation: string, duration: number}>}
+ */
+export function getTimings() {
+  return [...completedTimings];
+}
+
+/**
+ * Clear stored timings (useful between runs).
+ */
+export function clearTimings() {
+  completedTimings.length = 0;
+}
+
 /**
  * Track a usage event (command execution)
  * @param {string} command - Command name (init, doctor, migrate, publish)

package/src/watch.js

@@ -0,0 +1,92 @@
+/**
+ * Watch mode for RepoLens — regenerates Markdown docs when source files change.
+ * Only publishes to Markdown (no API calls on every save).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./core/config.js";
+import { scanRepo } from "./core/scan.js";
+import { generateDocumentSet } from "./docs/generate-doc-set.js";
+import { writeDocumentSet } from "./docs/write-doc-set.js";
+import { getGitDiff } from "./core/diff.js";
+import { info, warn, error } from "./utils/logger.js";
+
+const DEBOUNCE_MS = 500;
+
+/**
+ * Run a single rebuild cycle (scan → render → write markdown).
+ */
+async function rebuild(configPath) {
+  const start = Date.now();
+  try {
+    const cfg = await loadConfig(configPath);
+    const scan = await scanRepo(cfg);
+    const rawDiff = getGitDiff("origin/main");
+    const docSet = await generateDocumentSet(scan, cfg, rawDiff);
+    const result = await writeDocumentSet(docSet, process.cwd());
+    const elapsed = Date.now() - start;
+    info(`✓ Regenerated ${result.documentCount} docs in ${elapsed}ms`);
+  } catch (err) {
+    error(`Rebuild failed: ${err.message}`);
+  }
+}
+
+/**
+ * Start watch mode.
+ * @param {string} configPath - Resolved path to .repolens.yml
+ */
+export async function runWatch(configPath) {
+  info("Starting watch mode (Markdown only)...");
+  info("Press Ctrl+C to stop.\n");
+
+  // Initial build
+  await rebuild(configPath);
+
+  // Determine directories to watch from config
+  const cfg = await loadConfig(configPath);
+  const repoRoot = cfg.__repoRoot || process.cwd();
+  const moduleRoots = cfg.module_roots || ["src", "app", "lib"];
+
+  let debounceTimer = null;
+
+  const onChange = () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => rebuild(configPath), DEBOUNCE_MS);
+  };
+
+  const watchers = [];
+  for (const root of moduleRoots) {
+    const dirPath = path.resolve(repoRoot, root);
+    try {
+      fs.accessSync(dirPath);
+      const watcher = fs.watch(dirPath, { recursive: true }, (eventType, filename) => {
+        if (filename && !filename.includes("node_modules")) {
+          info(`Change detected: ${root}/${filename}`);
+          onChange();
+        }
+      });
+      watchers.push(watcher);
+      info(`Watching: ${root}/`);
+    } catch {
+      // Directory doesn't exist, skip
+    }
+  }
+
+  if (watchers.length === 0) {
+    warn("No directories to watch. Check module_roots in .repolens.yml");
+    return;
+  }
+
+  info("\nWaiting for changes...\n");
+
+  // Keep process alive and clean up on exit
+  process.on("SIGINT", () => {
+    info("\nStopping watch mode...");
+    for (const w of watchers) w.close();
+    process.exit(0);
+  });
+
+  // Keep alive indefinitely
+  await new Promise(() => {});
+}