docguard-cli 0.7.3 → 0.8.2

package/cli/docguard.mjs

@@ -22,7 +22,7 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
 const VERSION = PKG.version;
-import { runAudit } from './commands/audit.mjs';
+// audit is now an alias for guard (old audit.mjs deleted — guard does everything it did + more)
 import { runInit } from './commands/init.mjs';
 import { runGuard } from './commands/guard.mjs';
 import { runScore } from './commands/score.mjs';
@@ -38,66 +38,9 @@ import { runDiagnose } from './commands/diagnose.mjs';
 import { runPublish } from './commands/publish.mjs';
 import { runTrace } from './commands/trace.mjs';
 
-// ── Colors (ANSI escape codes, zero deps) ──────────────────────────────────
-export const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-  white: '\x1b[37m',
-  bgRed: '\x1b[41m',
-  bgGreen: '\x1b[42m',
-  bgYellow: '\x1b[43m',
-};
-// ── Compliance Profiles ───────────────────────────────────────────────────
-// Profiles layer between defaults and user config — they're preset bundles
-// that adjust what docs are required and which validators run.
-const PROFILES = {
-  starter: {
-    description: 'Minimal CDD — just architecture + changelog. For side projects and prototypes.',
-    requiredFiles: {
-      canonical: [
-        'docs-canonical/ARCHITECTURE.md',
-      ],
-      agentFile: ['AGENTS.md', 'CLAUDE.md'],
-      changelog: 'CHANGELOG.md',
-      driftLog: 'DRIFT-LOG.md',
-    },
-    validators: {
-      structure: true,
-      docsSync: true,
-      drift: false,
-      changelog: true,
-      architecture: false,
-      testSpec: false,
-      security: false,
-      environment: false,
-      freshness: false,
-    },
-  },
-  standard: {
-    description: 'Full CDD — all 5 canonical docs. For team projects.',
-    // Uses the defaults — no overrides needed
-  },
-  enterprise: {
-    description: 'Strict CDD — all docs, all validators, freshness enforced. For regulated/enterprise projects.',
-    validators: {
-      structure: true,
-      docsSync: true,
-      drift: true,
-      changelog: true,
-      architecture: true,
-      testSpec: true,
-      security: true,
-      environment: true,
-      freshness: true,
-    },
-  },
-};
+// ── Shared constants (imported to break circular dependencies) ──────────
+import { c, PROFILES } from './shared.mjs';
+export { c, PROFILES };
 
 // ── Config Loading ─────────────────────────────────────────────────────────
 export function loadConfig(projectDir) {
@@ -195,8 +138,7 @@ export function loadConfig(projectDir) {
   return defaults;
 }
 
-// Export profiles for use by other commands (init --profile)
-export { PROFILES };
+// PROFILES is exported from shared.mjs (re-exported at line 43)
 
 /**
  * Auto-detect project type from package.json and file structure.
@@ -273,22 +215,31 @@ function printHelp() {
   console.log(`${c.bold}Usage:${c.reset}
   docguard <command> [options]
 
-${c.bold}Commands:${c.reset}
-  ${c.green}audit${c.reset}      Scan project, report what CDD docs exist or are missing
-  ${c.green}init${c.reset}       Initialize CDD documentation from templates
-  ${c.green}guard${c.reset}      Validate project against its canonical documentation
-  ${c.green}score${c.reset}      Calculate CDD maturity score (0-100)
-  ${c.green}diagnose${c.reset}   AI orchestrator — chains guard→fix in one command
-  ${c.green}diff${c.reset}       Show gaps between canonical docs and code
-  ${c.green}agents${c.reset}     Generate agent-specific config files from AGENTS.md
+${c.bold}Getting Started:${c.reset}
+  ${c.green}init${c.reset}       Initialize CDD docs (interactive setup)
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code
-  ${c.green}hooks${c.reset}      Install git hooks (pre-commit, pre-push, commit-msg)
+
+${c.bold}Enforcement:${c.reset}
+  ${c.green}guard${c.reset}      Validate project against canonical docs (51+ checks)
+  ${c.green}diagnose${c.reset}   AI orchestrator — guard → fix in one command
+
+${c.bold}Analysis:${c.reset}
+  ${c.green}score${c.reset}      CDD maturity score (0-100)
+  ${c.green}trace${c.reset}      Requirements traceability matrix
+  ${c.green}diff${c.reset}       Show gaps between docs and code (detailed view)
+
+${c.bold}CI/CD & Automation:${c.reset}
+  ${c.green}ci${c.reset}         Pipeline gate (guard + score, exit codes)
+  ${c.green}hooks${c.reset}      Install/manage git hooks
+  ${c.green}watch${c.reset}      Watch for changes, re-run guard
+
+${c.bold}Utilities:${c.reset}
+  ${c.green}fix${c.reset}        Generate AI fix instructions for specific docs
+  ${c.green}agents${c.reset}     Generate agent config files (AGENTS.md, CLAUDE.md)
   ${c.green}badge${c.reset}      Generate CDD score badges for README
-  ${c.green}ci${c.reset}         Single command for CI/CD pipelines (guard + score)
-  ${c.green}fix${c.reset}        Find issues and generate AI fix instructions
-  ${c.green}watch${c.reset}      Watch for file changes and re-run guard automatically
-  ${c.green}publish${c.reset}    Scaffold external docs (Mintlify, Docusaurus)
-  ${c.green}trace${c.reset}      Generate requirements traceability matrix
+
+${c.bold}Experimental:${c.reset}
+  ${c.dim}publish${c.reset}    Scaffold external doc sites (Mintlify)
 
 ${c.bold}Options:${c.reset}
   --dir <path>    Project directory (default: current directory)
@@ -305,7 +256,6 @@ ${c.bold}Options:${c.reset}
   --auto          Auto-fix what's possible (used with fix command)
   --doc <name>    Generate AI prompt for specific doc (architecture, security, etc.)
   --profile <p>   Compliance profile: starter, standard, enterprise (init command)
-  --platform <p>  Doc platform: mintlify (publish command)
   --tax           Show estimated documentation maintenance cost (with score)
   --help          Show this help message
   --version       Show version
@@ -319,12 +269,12 @@ ${c.bold}Examples:${c.reset}
   ${c.dim}# AI auto-diagnose and fix${c.reset}
   docguard diagnose
 
-  ${c.dim}# Quick start for a side project${c.reset}
-  docguard init --profile starter
-
-  ${c.dim}# Full CDD init (default)${c.reset}
+  ${c.dim}# Interactive setup (asks which docs you need)${c.reset}
   docguard init
 
+  ${c.dim}# Quick start for a side project${c.reset}
+  docguard init --profile starter --skip-prompts
+
   ${c.dim}# See documentation tax estimate${c.reset}
   docguard score --tax
 
@@ -339,7 +289,7 @@ ${c.bold}Learn more:${c.reset}
 }
 
 // ── Main ───────────────────────────────────────────────────────────────────
-function main() {
+async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
@@ -425,10 +375,11 @@ function main() {
 
   switch (command) {
     case 'audit':
-      runAudit(projectDir, config, flags);
+      // audit is an alias for guard — guard does everything the old audit did + 50 more checks
+      runGuard(projectDir, config, flags);
       break;
     case 'init':
-      runInit(projectDir, config, flags);
+      await runInit(projectDir, config, flags);
       break;
     case 'guard':
       runGuard(projectDir, config, flags);

package/cli/shared.mjs

@@ -0,0 +1,106 @@
+/**
+ * Shared constants for DocGuard CLI — colors, profiles, version.
+ * Extracted from docguard.mjs to break circular dependencies.
+ * All commands import from here instead of docguard.mjs.
+ */
+
+// ── Colors (ANSI escape codes, zero deps) ──────────────────────────────────
+export const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+};
+
+// ── Compliance Profiles ───────────────────────────────────────────────────
+export const PROFILES = {
+  starter: {
+    description: 'Minimal CDD — just architecture + changelog. For side projects and prototypes.',
+    requiredFiles: {
+      canonical: [
+        'docs-canonical/ARCHITECTURE.md',
+      ],
+      agentFile: ['AGENTS.md', 'CLAUDE.md'],
+      changelog: 'CHANGELOG.md',
+      driftLog: 'DRIFT-LOG.md',
+    },
+    validators: {
+      structure: true,
+      docsSync: true,
+      drift: false,
+      changelog: true,
+      architecture: false,
+      testSpec: false,
+      security: false,
+      environment: false,
+      freshness: false,
+    },
+  },
+  standard: {
+    description: 'Full CDD — all 5 canonical docs. For team projects.',
+    // Uses the defaults — no overrides needed
+  },
+  enterprise: {
+    description: 'Strict CDD — all docs, all validators, freshness enforced. For regulated/enterprise projects.',
+    validators: {
+      structure: true,
+      docsSync: true,
+      drift: true,
+      changelog: true,
+      architecture: true,
+      testSpec: true,
+      security: true,
+      environment: true,
+      freshness: true,
+    },
+  },
+};
+
+// ── .docguardignore Support ───────────────────────────────────────────────
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+
+/**
+ * Load ignore patterns from .docguardignore (like .gitignore).
+ * Returns a function that checks if a relative path should be ignored.
+ *
+ * Format: one pattern per line, # comments, blank lines skipped.
+ * Supports simple glob: * (any chars), ** (any path segments).
+ *
+ * @param {string} projectDir - Project root
+ * @returns {(relPath: string) => boolean} - Returns true if file should be ignored
+ */
+export function loadIgnorePatterns(projectDir) {
+  const ignorePath = resolve(projectDir, '.docguardignore');
+  if (!existsSync(ignorePath)) return () => false;
+
+  let content;
+  try { content = readFileSync(ignorePath, 'utf-8'); } catch { return () => false; }
+
+  const patterns = content
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#'))
+    .map(pattern => {
+      // Convert glob to regex:
+      // ** → match any path segments
+      // * → match any chars except /
+      // . → literal dot
+      const escaped = pattern
+        .replace(/\./g, '\\.')
+        .replace(/\*\*/g, '§§')     // temp placeholder
+        .replace(/\*/g, '[^/]*')
+        .replace(/§§/g, '.*');
+      return new RegExp(`^${escaped}$|/${escaped}$|^${escaped}/|/${escaped}/`);
+    });
+
+  return (relPath) => patterns.some(regex => regex.test(relPath));
+}

package/cli/validators/docs-coverage.mjs

@@ -0,0 +1,387 @@
+/**
+ * Docs-Coverage Validator — Detects code features not referenced in docs.
+ *
+ * Generic validator for ANY project type. Scans the project for
+ * "documentable artifacts" and checks if at least one canonical doc
+ * or README references them.
+ *
+ * What it catches:
+ *  - Config/dotfiles at root not mentioned in docs
+ *  - Config filenames referenced in source code (resolve/readFile calls) but not documented
+ *  - package.json bin entries not documented
+ *  - Source directories not referenced in ARCHITECTURE.md
+ *  - README.md missing standard sections (inspired by Standard README spec)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative, basename, extname } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+]);
+
+// Dotfiles that are universally common and don't need documentation
+const COMMON_DOTFILES = new Set([
+  '.gitignore', '.gitattributes', '.git', '.DS_Store',
+  '.editorconfig', '.prettierrc', '.prettierignore',
+  '.eslintrc', '.eslintrc.js', '.eslintrc.json', '.eslintrc.cjs',
+  '.eslintignore', '.nvmrc', '.node-version', '.npmrc', '.npmignore',
+  '.env', '.env.local', '.env.development', '.env.production',
+  '.vscode', '.idea', '.github', '.husky',
+  '.babelrc', '.browserslistrc', '.stylelintrc',
+]);
+
+/**
+ * Validate that code artifacts are referenced in documentation.
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - DocGuard config
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateDocsCoverage(projectDir, config) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  // Collect all doc content for searching
+  const allDocContent = collectDocContent(projectDir);
+  if (!allDocContent) {
+    return { errors: [], warnings, passed: 0, total: 0 };
+  }
+
+  // ── Check 1: Project-specific config/dotfiles referenced in docs ──
+  const configChecks = checkConfigFiles(projectDir, allDocContent);
+  total += configChecks.total;
+  passed += configChecks.passed;
+  warnings.push(...configChecks.warnings);
+
+  // ── Check 2: package.json bin entries documented ──
+  const binChecks = checkPackageBins(projectDir, allDocContent);
+  total += binChecks.total;
+  passed += binChecks.passed;
+  warnings.push(...binChecks.warnings);
+
+  // ── Check 3: Source directory structure matches ARCHITECTURE.md ──
+  const dirChecks = checkSourceDirs(projectDir, allDocContent);
+  total += dirChecks.total;
+  passed += dirChecks.passed;
+  warnings.push(...dirChecks.warnings);
+
+  // ── Check 4: Config filenames referenced in source code but not documented ──
+  const codeConfigChecks = checkCodeReferencedConfigs(projectDir, allDocContent);
+  total += codeConfigChecks.total;
+  passed += codeConfigChecks.passed;
+  warnings.push(...codeConfigChecks.warnings);
+
+  // ── Check 5: README section completeness (Standard README spec) ──
+  const readmeChecks = checkReadmeSections(projectDir);
+  total += readmeChecks.total;
+  passed += readmeChecks.passed;
+  warnings.push(...readmeChecks.warnings);
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Check Functions ─────────────────────────────────────────────────────────
+
+/**
+ * Check 1: Project-specific config/dotfiles are mentioned in docs.
+ * Skips universally common files (.gitignore, .eslintrc, etc.).
+ */
+function checkConfigFiles(projectDir, allDocContent) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  let entries;
+  try { entries = readdirSync(projectDir); } catch { return { warnings, passed, total }; }
+
+  const lowerDocContent = allDocContent.toLowerCase();
+
+  for (const entry of entries) {
+    const isDotFile = entry.startsWith('.');
+    const isProjectConfig = entry.endsWith('.config.js') ||
+      entry.endsWith('.config.ts') ||
+      entry.endsWith('.config.mjs') ||
+      entry.endsWith('.config.cjs') ||
+      entry.endsWith('.json') && !['package.json', 'package-lock.json', 'tsconfig.json'].includes(entry);
+
+    if (!isDotFile && !isProjectConfig) continue;
+    if (COMMON_DOTFILES.has(entry)) continue;
+    if (entry === 'tsconfig.json' || entry === 'package-lock.json') continue;
+
+    total++;
+    if (lowerDocContent.includes(entry.toLowerCase())) {
+      passed++;
+    } else {
+      warnings.push(
+        `Config file "${entry}" exists but is not mentioned in any documentation. Document its purpose in ARCHITECTURE.md or README.md`
+      );
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+/**
+ * Check 2: package.json bin entries (CLI commands users run) are documented.
+ */
+function checkPackageBins(projectDir, allDocContent) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) return { warnings, passed, total };
+
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { return { warnings, passed, total }; }
+
+  const bins = typeof pkg.bin === 'string'
+    ? { [pkg.name]: pkg.bin }
+    : (pkg.bin || {});
+
+  const lowerDocContent = allDocContent.toLowerCase();
+
+  for (const [binName] of Object.entries(bins)) {
+    total++;
+    if (lowerDocContent.includes(binName.toLowerCase())) {
+      passed++;
+    } else {
+      warnings.push(
+        `package.json defines CLI command "${binName}" but it's not mentioned in any documentation`
+      );
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+/**
+ * Check 3: Source directories are referenced in ARCHITECTURE.md.
+ */
+function checkSourceDirs(projectDir, allDocContent) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const archPath = resolve(projectDir, 'docs-canonical/ARCHITECTURE.md');
+  if (!existsSync(archPath)) return { warnings, passed, total };
+
+  let archContent;
+  try { archContent = readFileSync(archPath, 'utf-8'); } catch { return { warnings, passed, total }; }
+
+  const lowerArchContent = archContent.toLowerCase();
+  const sourceRoots = ['src', 'lib', 'app', 'cli', 'server', 'api'];
+
+  for (const root of sourceRoots) {
+    const rootDir = resolve(projectDir, root);
+    if (!existsSync(rootDir)) continue;
+
+    let entries;
+    try { entries = readdirSync(rootDir); } catch { continue; }
+
+    for (const entry of entries) {
+      const fullPath = join(rootDir, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (!stat.isDirectory()) continue;
+      } catch { continue; }
+
+      if (IGNORE_DIRS.has(entry) || entry.startsWith('.') || entry === '__tests__' || entry === '__test__') continue;
+
+      total++;
+      const searchName = entry.toLowerCase();
+      if (lowerArchContent.includes(searchName) || lowerArchContent.includes(root + '/' + entry)) {
+        passed++;
+      } else {
+        warnings.push(
+          `Source directory "${root}/${entry}/" is not referenced in ARCHITECTURE.md`
+        );
+      }
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+/**
+ * Check 4: Config files that code actually READS are documented.
+ *
+ * Scans source code for resolve(dir, '.configname') and existsSync('.configname')
+ * patterns — these are configs the project USES. Avoids matching config names
+ * sitting in arrays (scan patterns for detecting other projects' configs).
+ */
+function checkCodeReferencedConfigs(projectDir, allDocContent) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const lowerDocContent = allDocContent.toLowerCase();
+  const foundConfigs = new Set();
+
+  // Only match config filenames inside function calls that actually USE the file:
+  // resolve(dir, '.docguardignore'), existsSync('.env.example'), readFileSync('vitest.config.ts')
+  const usageRegex = /(?:resolve|join|existsSync|readFileSync|accessSync|writeFileSync)\s*\([^)]*['"`]([^'"`\n]{2,})['"`]/g;
+
+  const sourceRoots = ['src', 'lib', 'cli', 'bin', 'server', 'api', 'app'];
+
+  const scanFile = (filePath) => {
+    const ext = extname(filePath);
+    if (!['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) return;
+    let content;
+    try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
+
+    usageRegex.lastIndex = 0;
+    let match;
+    while ((match = usageRegex.exec(content)) !== null) {
+      const name = match[1];
+      // Must be a dotfile (.something) or *.config.* — not a path
+      if (name.includes('/') || name.startsWith('..')) continue;
+      const isDotConfig = name.startsWith('.') && name.length > 2;
+      const isNamedConfig = /^[\w-]+\.config\.\w+$/.test(name);
+      if (!isDotConfig && !isNamedConfig) continue;
+      // Skip bare extensions
+      if (/^\.[a-z]{1,4}$/i.test(name)) continue;
+      foundConfigs.add(name);
+    }
+  };
+
+  for (const root of sourceRoots) {
+    const rootDir = resolve(projectDir, root);
+    if (!existsSync(rootDir)) continue;
+    walkFiles(rootDir, scanFile);
+  }
+
+  for (const configName of foundConfigs) {
+    if (COMMON_DOTFILES.has(configName)) continue;
+    total++;
+    if (lowerDocContent.includes(configName.toLowerCase())) {
+      passed++;
+    } else {
+      warnings.push(
+        `Code references config file "${configName}" but no documentation mentions it. Add it to README.md or ARCHITECTURE.md`
+      );
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+/**
+ * Check 5: README section completeness.
+ * Inspired by Standard README (https://github.com/RichardLitt/standard-readme)
+ * and Make a README (https://www.makeareadme.com/).
+ */
+function checkReadmeSections(projectDir) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const readmePath = resolve(projectDir, 'README.md');
+  if (!existsSync(readmePath)) return { warnings, passed, total };
+
+  let content;
+  try { content = readFileSync(readmePath, 'utf-8'); } catch { return { warnings, passed, total }; }
+
+  const lowerContent = content.toLowerCase();
+
+  // Required sections — every well-documented project should have these
+  const requiredSections = [
+    { name: 'Installation', patterns: ['install', 'getting started', 'setup', 'quickstart', 'quick start'] },
+    { name: 'Usage', patterns: ['usage', 'how to use', 'examples', 'getting started'] },
+    { name: 'License', patterns: ['license', 'licence'] },
+  ];
+
+  // Recommended — count toward score but don't warn
+  const recommendedSections = [
+    { name: 'Contributing', patterns: ['contributing', 'contribution', 'how to contribute'] },
+    { name: 'Description', patterns: ['## what', '## about', '## description', '## overview'] },
+  ];
+
+  for (const section of requiredSections) {
+    total++;
+    if (section.patterns.some(p => lowerContent.includes(p))) {
+      passed++;
+    } else {
+      warnings.push(`README.md is missing a "${section.name}" section (Standard README spec)`);
+    }
+  }
+
+  for (const section of recommendedSections) {
+    total++;
+    if (section.patterns.some(p => lowerContent.includes(p))) {
+      passed++;
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Collect all documentation content into a single searchable string.
+ */
+function collectDocContent(projectDir) {
+  const docPaths = [];
+
+  const rootDocs = ['README.md', 'AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md', 'STANDARD.md'];
+  for (const doc of rootDocs) {
+    const p = resolve(projectDir, doc);
+    if (existsSync(p)) docPaths.push(p);
+  }
+
+  const canonDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonDir)) {
+    try {
+      for (const entry of readdirSync(canonDir)) {
+        if (entry.endsWith('.md')) docPaths.push(resolve(canonDir, entry));
+      }
+    } catch { /* skip */ }
+  }
+
+  const extDir = resolve(projectDir, 'extensions');
+  if (existsSync(extDir)) {
+    walkFiles(extDir, (f) => {
+      if (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml')) {
+        docPaths.push(f);
+      }
+    });
+  }
+
+  for (const docsDir of ['docs', 'docs-implementation']) {
+    const d = resolve(projectDir, docsDir);
+    if (existsSync(d)) {
+      walkFiles(d, (f) => {
+        if (f.endsWith('.md')) docPaths.push(f);
+      });
+    }
+  }
+
+  if (docPaths.length === 0) return null;
+  const parts = [];
+  for (const p of docPaths) {
+    try { parts.push(readFileSync(p, 'utf-8')); } catch { /* skip */ }
+  }
+  return parts.join('\n');
+}
+
+function walkFiles(dir, callback) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
+    const fullPath = join(dir, entry);
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        walkFiles(fullPath, callback);
+      } else if (stat.isFile()) {
+        callback(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+}