docguard-cli 0.5.1

package/cli/commands/guard.mjs

@@ -0,0 +1,158 @@
+/**
+ * Guard Command — Validate project against its canonical documentation
+ * Runs all enabled validators and reports results.
+ *
+ * Two modes:
+ *   runGuard()         → prints to console, exits with code
+ *   runGuardInternal() → returns data, no side effects (for diagnose, ci)
+ */
+
+import { c } from '../docguard.mjs';
+import { validateStructure, validateDocSections } from '../validators/structure.mjs';
+import { validateDrift } from '../validators/drift.mjs';
+import { validateChangelog } from '../validators/changelog.mjs';
+import { validateTestSpec } from '../validators/test-spec.mjs';
+import { validateEnvironment } from '../validators/environment.mjs';
+import { validateSecurity } from '../validators/security.mjs';
+import { validateDocsSync } from '../validators/docs-sync.mjs';
+import { validateArchitecture } from '../validators/architecture.mjs';
+import { validateFreshness } from '../validators/freshness.mjs';
+
+/**
+ * Internal guard — returns structured data, no console output, no process.exit.
+ * Used by diagnose, ci, and guard --format json.
+ */
+export function runGuardInternal(projectDir, config) {
+  const validators = config.validators || {};
+  const results = [];
+
+  const validatorMap = [
+    { key: 'structure', name: 'Structure', fn: () => validateStructure(projectDir, config) },
+    { key: 'structure', name: 'Doc Sections', fn: () => validateDocSections(projectDir, config) },
+    { key: 'docsSync', name: 'Docs-Sync', fn: () => validateDocsSync(projectDir, config) },
+    { key: 'drift', name: 'Drift', fn: () => validateDrift(projectDir, config) },
+    { key: 'changelog', name: 'Changelog', fn: () => validateChangelog(projectDir, config) },
+    { key: 'testSpec', name: 'Test-Spec', fn: () => validateTestSpec(projectDir, config) },
+    { key: 'environment', name: 'Environment', fn: () => validateEnvironment(projectDir, config) },
+    { key: 'security', name: 'Security', fn: () => validateSecurity(projectDir, config) },
+    { key: 'architecture', name: 'Architecture', fn: () => validateArchitecture(projectDir, config) },
+    { key: 'freshness', name: 'Freshness', fn: () => {
+      const freshnessResults = validateFreshness(projectDir, config);
+      const errors = [];
+      const warnings = [];
+      let passed = 0;
+      for (const r of freshnessResults) {
+        if (r.status === 'pass') passed++;
+        else if (r.status === 'warn') warnings.push(r.message);
+        else if (r.status === 'fail') errors.push(r.message);
+      }
+      return { errors, warnings, passed, total: passed + warnings.length + errors.length };
+    }},
+  ];
+
+  for (const { key, name, fn } of validatorMap) {
+    if (validators[key] === false) {
+      results.push({ name, key, status: 'skipped', errors: [], warnings: [], passed: 0, total: 0 });
+      continue;
+    }
+
+    try {
+      const result = fn();
+      const hasErrors = result.errors.length > 0;
+      const hasWarnings = result.warnings.length > 0;
+      const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
+      results.push({ ...result, name, key, status });
+    } catch (err) {
+      results.push({ name, key, status: 'fail', errors: [err.message], warnings: [], passed: 0, total: 1 });
+    }
+  }
+
+  const activeResults = results.filter(r => r.status !== 'skipped');
+  const totalErrors = activeResults.reduce((sum, r) => sum + r.errors.length, 0);
+  const totalWarnings = activeResults.reduce((sum, r) => sum + r.warnings.length, 0);
+  const totalPassed = activeResults.reduce((sum, r) => sum + r.passed, 0);
+  const totalChecks = activeResults.reduce((sum, r) => sum + r.total, 0);
+
+  const overallStatus = totalErrors > 0 ? 'FAIL' : totalWarnings > 0 ? 'WARN' : 'PASS';
+
+  return {
+    project: config.projectName,
+    profile: config.profile || 'standard',
+    status: overallStatus,
+    passed: totalPassed,
+    total: totalChecks,
+    errors: totalErrors,
+    warnings: totalWarnings,
+    validators: results,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Public guard — prints results and exits.
+ */
+export function runGuard(projectDir, config, flags) {
+  const data = runGuardInternal(projectDir, config);
+
+  // ── JSON output ──
+  if (flags.format === 'json') {
+    console.log(JSON.stringify(data, null, 2));
+    if (data.errors > 0) process.exit(1);
+    if (data.warnings > 0) process.exit(2);
+    process.exit(0);
+  }
+
+  // ── Text output ──
+  console.log(`${c.bold}🛡️  DocGuard Guard — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+
+  for (const v of data.validators) {
+    if (v.status === 'skipped') {
+      if (flags.verbose) {
+        console.log(`  ${c.dim}⏭️  ${v.name} (disabled)${c.reset}`);
+      }
+      continue;
+    }
+
+    if (v.status === 'pass') {
+      console.log(`  ${c.green}✅ ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+    } else if (v.status === 'fail') {
+      console.log(`  ${c.red}❌ ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+    } else {
+      console.log(`  ${c.yellow}⚠️  ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+    }
+
+    if (flags.verbose || v.status === 'fail') {
+      for (const err of v.errors) {
+        console.log(`     ${c.red}✗ ${err}${c.reset}`);
+      }
+    }
+    if (flags.verbose || v.status === 'warn') {
+      for (const warn of v.warnings) {
+        console.log(`     ${c.yellow}⚠ ${warn}${c.reset}`);
+      }
+    }
+  }
+
+  // Summary
+  console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
+
+  if (data.status === 'PASS') {
+    console.log(`  ${c.green}${c.bold}✅ PASS${c.reset} ${c.green}— All ${data.total} checks passed${c.reset}`);
+  } else if (data.status === 'WARN') {
+    console.log(`  ${c.yellow}${c.bold}⚠️  WARN${c.reset} ${c.yellow}— ${data.passed}/${data.total} passed, ${data.warnings} warning(s)${c.reset}`);
+  } else {
+    console.log(`  ${c.red}${c.bold}❌ FAIL${c.reset} ${c.red}— ${data.passed}/${data.total} passed, ${data.errors} error(s), ${data.warnings} warning(s)${c.reset}`);
+  }
+
+  // Next step hint — always point to diagnose when issues exist
+  if (data.status !== 'PASS') {
+    console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to get AI fix prompts.${c.reset}`);
+  }
+
+  console.log('');
+
+  if (data.errors > 0) process.exit(1);
+  if (data.warnings > 0) process.exit(2);
+  process.exit(0);
+}

package/cli/commands/hooks.mjs

@@ -0,0 +1,227 @@
+/**
+ * Hooks Command — Generate pre-commit/pre-push hooks for DocGuard
+ * Creates git hooks that run guard/score before commits.
+ */
+
+import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { c } from '../docguard.mjs';
+
+const HOOKS = {
+  'pre-commit': {
+    description: 'Run docguard guard before every commit',
+    content: `#!/bin/sh
+# DocGuard pre-commit hook
+# Validates CDD compliance before allowing commits
+# Install: docguard hooks --type pre-commit
+# Remove: rm .git/hooks/pre-commit
+
+echo "🛡️  Running DocGuard guard..."
+
+# Check if docguard is available
+if command -v npx &> /dev/null; then
+  npx docguard guard
+  EXIT_CODE=$?
+elif command -v docguard &> /dev/null; then
+  docguard guard
+  EXIT_CODE=$?
+else
+  echo "⚠️  DocGuard not found. Skipping guard check."
+  echo "   Install: npm install -g docguard"
+  exit 0
+fi
+
+if [ $EXIT_CODE -eq 1 ]; then
+  echo ""
+  echo "❌ DocGuard guard FAILED — commit blocked"
+  echo "   Fix the errors above, then try again."
+  echo "   To skip: git commit --no-verify"
+  exit 1
+elif [ $EXIT_CODE -eq 2 ]; then
+  echo ""
+  echo "⚠️  DocGuard guard found warnings — commit allowed"
+fi
+
+exit 0
+`,
+  },
+
+  'pre-push': {
+    description: 'Run docguard score check before push (enforce minimum score)',
+    content: `#!/bin/sh
+# DocGuard pre-push hook
+# Enforces minimum CDD score before allowing push
+# Install: docguard hooks --type pre-push
+# Remove: rm .git/hooks/pre-push
+
+MIN_SCORE=60
+
+echo "📊 Running DocGuard score check (minimum: $MIN_SCORE)..."
+
+# Get score as JSON
+if command -v npx &> /dev/null; then
+  RESULT=$(npx docguard score --format json 2>/dev/null)
+elif command -v docguard &> /dev/null; then
+  RESULT=$(docguard score --format json 2>/dev/null)
+else
+  echo "⚠️  DocGuard not found. Skipping score check."
+  exit 0
+fi
+
+# Parse score from JSON
+SCORE=$(echo "$RESULT" | grep -o '"score":[0-9]*' | head -1 | cut -d: -f2)
+
+if [ -z "$SCORE" ]; then
+  echo "⚠️  Could not determine CDD score. Push allowed."
+  exit 0
+fi
+
+echo "   CDD Score: $SCORE/100"
+
+if [ "$SCORE" -lt "$MIN_SCORE" ]; then
+  echo ""
+  echo "❌ CDD score $SCORE is below minimum $MIN_SCORE — push blocked"
+  echo "   Run: docguard score  (for details)"
+  echo "   To skip: git push --no-verify"
+  exit 1
+fi
+
+echo "   ✅ Score meets minimum threshold"
+exit 0
+`,
+  },
+
+  'commit-msg': {
+    description: 'Validate commit message format (conventional commits)',
+    content: `#!/bin/sh
+# DocGuard commit-msg hook
+# Validates conventional commit message format
+# Install: docguard hooks --type commit-msg
+# Remove: rm .git/hooks/commit-msg
+
+COMMIT_MSG_FILE=$1
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+# Conventional commit regex
+PATTERN="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|release)(\\(.+\\))?: .{1,72}"
+
+if ! echo "$COMMIT_MSG" | head -1 | grep -qE "$PATTERN"; then
+  echo ""
+  echo "❌ Commit message does not follow Conventional Commits format"
+  echo ""
+  echo "   Expected: type(scope): description"
+  echo "   Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, release"
+  echo ""
+  echo "   Examples:"
+  echo "     feat: add user authentication"
+  echo "     fix(api): resolve timeout on large requests"
+  echo "     docs: update ARCHITECTURE.md layer boundaries"
+  echo ""
+  echo "   Your message: $(head -1 "$COMMIT_MSG_FILE")"
+  echo ""
+  echo "   To skip: git commit --no-verify"
+  exit 1
+fi
+
+exit 0
+`,
+  },
+};
+
+export function runHooks(projectDir, config, flags) {
+  console.log(`${c.bold}🪝 DocGuard Hooks — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+
+  // Check if .git exists
+  const gitDir = resolve(projectDir, '.git');
+  if (!existsSync(gitDir)) {
+    console.log(`  ${c.red}❌ Not a git repository. Run ${c.cyan}git init${c.red} first.${c.reset}\n`);
+    process.exit(1);
+  }
+
+  const hooksDir = resolve(gitDir, 'hooks');
+  if (!existsSync(hooksDir)) {
+    mkdirSync(hooksDir, { recursive: true });
+  }
+
+  // Determine which hooks to install
+  let hookTypes = Object.keys(HOOKS);
+  if (flags.type) {
+    if (!HOOKS[flags.type]) {
+      console.log(`  ${c.red}Unknown hook type: ${flags.type}${c.reset}`);
+      console.log(`  Available: ${Object.keys(HOOKS).join(', ')}\n`);
+      process.exit(1);
+    }
+    hookTypes = [flags.type];
+  }
+
+  // List mode
+  if (flags.list) {
+    console.log(`  ${c.bold}Available hooks:${c.reset}\n`);
+    for (const [name, hook] of Object.entries(HOOKS)) {
+      const installed = existsSync(resolve(hooksDir, name));
+      const status = installed ? `${c.green}✅ installed${c.reset}` : `${c.dim}not installed${c.reset}`;
+      console.log(`    ${c.cyan}${name}${c.reset}: ${hook.description} [${status}]`);
+    }
+    console.log(`\n  ${c.dim}Install: docguard hooks --type <name>${c.reset}`);
+    console.log(`  ${c.dim}Install all: docguard hooks${c.reset}\n`);
+    return;
+  }
+
+  // Remove mode
+  if (flags.remove) {
+    let removed = 0;
+    for (const name of hookTypes) {
+      const hookPath = resolve(hooksDir, name);
+      if (existsSync(hookPath)) {
+        const content = readFileSync(hookPath, 'utf-8');
+        if (content.includes('DocGuard')) {
+          unlinkSync(hookPath);
+          console.log(`  ${c.yellow}🗑️  Removed: ${name}${c.reset}`);
+          removed++;
+        } else {
+          console.log(`  ${c.dim}⏭️  ${name}: not a DocGuard hook (skipped)${c.reset}`);
+        }
+      }
+    }
+    console.log(`\n  Removed: ${removed}\n`);
+    return;
+  }
+
+  // Install mode
+  let installed = 0;
+  let skipped = 0;
+
+  for (const name of hookTypes) {
+    const hookPath = resolve(hooksDir, name);
+
+    if (existsSync(hookPath) && !flags.force) {
+      // Check if it's already a DocGuard hook
+      const existing = readFileSync(hookPath, 'utf-8');
+      if (existing.includes('DocGuard')) {
+        console.log(`  ${c.dim}⏭️  ${name} (DocGuard hook already installed)${c.reset}`);
+        skipped++;
+        continue;
+      }
+      console.log(`  ${c.yellow}⚠️  ${name}: existing hook found (use --force to overwrite)${c.reset}`);
+      skipped++;
+      continue;
+    }
+
+    writeFileSync(hookPath, HOOKS[name].content, 'utf-8');
+    chmodSync(hookPath, 0o755); // Make executable
+    console.log(`  ${c.green}✅ ${name}${c.reset}: ${HOOKS[name].description}`);
+    installed++;
+  }
+
+  console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
+  console.log(`  Installed: ${installed}  Skipped: ${skipped}`);
+
+  if (installed > 0) {
+    console.log(`\n  ${c.dim}Hooks run automatically on git operations.${c.reset}`);
+    console.log(`  ${c.dim}Skip with: git commit --no-verify${c.reset}`);
+    console.log(`  ${c.dim}Remove with: docguard hooks --remove${c.reset}`);
+  }
+
+  console.log('');
+}

package/cli/commands/init.mjs

@@ -0,0 +1,249 @@
+/**
+ * Init Command — Initialize CDD documentation from templates
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { c, PROFILES } from '../docguard.mjs';
+
+function detectProjectType(dir) {
+  const pkgPath = resolve(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      if (pkg.bin) return 'cli';
+      if (allDeps.next || allDeps.react || allDeps.vue || allDeps['@angular/core'] ||
+          allDeps.svelte || allDeps.nuxt) return 'webapp';
+      if (allDeps.express || allDeps.fastify || allDeps.hono || allDeps.koa) return 'api';
+      if (pkg.main || pkg.exports || pkg.module) return 'library';
+    } catch { /* fall through */ }
+  }
+  if (existsSync(resolve(dir, 'manage.py'))) return 'webapp';
+  if (existsSync(resolve(dir, 'setup.py')) || existsSync(resolve(dir, 'pyproject.toml'))) return 'library';
+  return 'unknown';
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = resolve(__dirname, '../../templates');
+
+export function runInit(projectDir, config, flags) {
+  const profileName = flags.profile || 'standard';
+  const profile = PROFILES[profileName];
+
+  if (!profile) {
+    console.error(`${c.red}Unknown profile: ${profileName}${c.reset}`);
+    console.log(`Available profiles: ${Object.keys(PROFILES).join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`${c.bold}🏗️  DocGuard Init — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
+  console.log(`${c.dim}   Profile:   ${profileName} — ${profile.description}${c.reset}\n`);
+
+  const created = [];
+  const skipped = [];
+
+  // Map template files to their destinations
+  const allMappings = [
+    { template: 'ARCHITECTURE.md.template', dest: 'docs-canonical/ARCHITECTURE.md' },
+    { template: 'DATA-MODEL.md.template', dest: 'docs-canonical/DATA-MODEL.md' },
+    { template: 'SECURITY.md.template', dest: 'docs-canonical/SECURITY.md' },
+    { template: 'TEST-SPEC.md.template', dest: 'docs-canonical/TEST-SPEC.md' },
+    { template: 'ENVIRONMENT.md.template', dest: 'docs-canonical/ENVIRONMENT.md' },
+    { template: 'AGENTS.md.template', dest: 'AGENTS.md' },
+    { template: 'CHANGELOG.md.template', dest: 'CHANGELOG.md' },
+    { template: 'DRIFT-LOG.md.template', dest: 'DRIFT-LOG.md' },
+  ];
+
+  // Filter based on profile — starter only gets required files
+  const profileRequiredFiles = profile.requiredFiles
+    ? new Set([...profile.requiredFiles.canonical, profile.requiredFiles.changelog, profile.requiredFiles.driftLog, ...profile.requiredFiles.agentFile])
+    : null;
+
+  const fileMappings = profileRequiredFiles
+    ? allMappings.filter(m => profileRequiredFiles.has(m.dest))
+    : allMappings;
+
+  for (const mapping of fileMappings) {
+    const destPath = resolve(projectDir, mapping.dest);
+    const templatePath = resolve(TEMPLATES_DIR, mapping.template);
+
+    if (existsSync(destPath)) {
+      skipped.push(mapping.dest);
+      console.log(`  ${c.yellow}⏭️${c.reset}  ${mapping.dest} ${c.dim}(already exists)${c.reset}`);
+      continue;
+    }
+
+    // Ensure directory exists
+    const destDir = dirname(destPath);
+    if (!existsSync(destDir)) {
+      mkdirSync(destDir, { recursive: true });
+    }
+
+    // Read template and write
+    if (existsSync(templatePath)) {
+      const content = readFileSync(templatePath, 'utf-8');
+      // Replace template date placeholder with today's date
+      const today = new Date().toISOString().split('T')[0];
+      const processed = content.replace(/YYYY-MM-DD/g, today);
+      writeFileSync(destPath, processed, 'utf-8');
+      created.push(mapping.dest);
+      console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}${mapping.dest}${c.reset}`);
+    } else {
+      console.log(
+        `  ${c.red}❌${c.reset} Template not found: ${mapping.template}`
+      );
+    }
+  }
+
+  // Create .docguard.json if it doesn't exist — auto-detect project type
+  const configPath = resolve(projectDir, '.docguard.json');
+  if (!existsSync(configPath)) {
+    // Detect project type from package.json
+    const detectedType = detectProjectType(projectDir);
+
+    // Get appropriate defaults for this project type
+    const typeDefaults = {
+      cli:     { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false },
+      library: { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false },
+      webapp:  { needsEnvVars: true,  needsEnvExample: true,  needsE2E: true,  needsDatabase: true },
+      api:     { needsEnvVars: true,  needsEnvExample: true,  needsE2E: false, needsDatabase: true },
+      unknown: { needsEnvVars: true,  needsEnvExample: true,  needsE2E: false, needsDatabase: true },
+    };
+
+    const ptc = typeDefaults[detectedType] || typeDefaults.unknown;
+
+    const defaultConfig = {
+      projectName: config.projectName,
+      version: '0.4',
+      profile: profileName,
+      projectType: detectedType,
+      projectTypeConfig: ptc,
+      validators: profile.validators || {
+        structure: true,
+        docsSync: true,
+        drift: true,
+        changelog: true,
+        architecture: false,
+        testSpec: true,
+        security: false,
+        environment: true,
+        freshness: true,
+      },
+    };
+
+    writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf-8');
+    created.push('.docguard.json');
+    console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}.docguard.json${c.reset} ${c.dim}(auto-detected: ${detectedType})${c.reset}`);
+  } else {
+    skipped.push('.docguard.json');
+    console.log(`  ${c.yellow}⏭️${c.reset}  .docguard.json ${c.dim}(already exists)${c.reset}`);
+  }
+
+  // Install slash commands for AI agents — detect which agents are in use
+  const commandsSourceDir = resolve(TEMPLATES_DIR, 'commands');
+  if (existsSync(commandsSourceDir)) {
+    const commandFiles = readdirSync(commandsSourceDir).filter(f => f.endsWith('.md'));
+
+    // Detect which AI agent directories exist in the project
+    const agentDirs = [
+      { name: 'GitHub Copilot', path: '.github/commands' },
+      { name: 'Cursor', path: '.cursor/rules' },
+      { name: 'Google Gemini', path: '.gemini/commands' },
+      { name: 'Claude Code', path: '.claude/commands' },
+      { name: 'Antigravity', path: '.agents/workflows' },
+    ];
+
+    // Find which agent dirs already exist in the project
+    const detected = agentDirs.filter(a =>
+      existsSync(resolve(projectDir, a.path.split('/')[0])) // check parent dir exists
+    );
+
+    // If none detected, default to .github/commands (most universal)
+    const targets = detected.length > 0
+      ? detected
+      : [{ name: 'GitHub (default)', path: '.github/commands' }];
+
+    let totalCreated = 0;
+    const installedLocations = [];
+
+    for (const target of targets) {
+      const destDir = resolve(projectDir, target.path);
+      if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
+      }
+
+      let dirCreated = 0;
+      for (const file of commandFiles) {
+        const destPath = resolve(destDir, file);
+        if (!existsSync(destPath)) {
+          const content = readFileSync(resolve(commandsSourceDir, file), 'utf-8');
+          writeFileSync(destPath, content, 'utf-8');
+          dirCreated++;
+        }
+      }
+
+      if (dirCreated > 0) {
+        totalCreated += dirCreated;
+        installedLocations.push(`${target.path}/ (${target.name})`);
+      }
+    }
+
+    if (totalCreated > 0) {
+      created.push(`slash commands (${installedLocations.length} location(s))`);
+      console.log(`  ${c.green}✅${c.reset} Installed ${c.cyan}slash commands${c.reset} for AI agents:`);
+      for (const loc of installedLocations) {
+        console.log(`     ${c.dim}→ ${loc}${c.reset}`);
+      }
+    } else {
+      console.log(`  ${c.yellow}⏭️${c.reset}  Slash commands ${c.dim}(already installed)${c.reset}`);
+    }
+  }
+
+  // Summary
+  console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
+  console.log(`  ${c.green}Created:${c.reset} ${created.length} files`);
+  if (skipped.length > 0) {
+    console.log(`  ${c.yellow}Skipped:${c.reset} ${skipped.length} files (already exist)`);
+  }
+
+  if (flags.skipPrompts) {
+    // Simple instructions, no AI prompts
+    console.log(`\n  ${c.bold}Next steps:${c.reset}`);
+    console.log(`  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to get AI prompts for filling docs.${c.reset}`);
+    console.log(`  ${c.dim}Then verify:${c.reset} ${c.cyan}docguard guard${c.reset}\n`);
+  } else {
+    // Auto-populate: output AI research prompts for each created canonical doc
+    const createdDocs = created.filter(f => f.startsWith('docs-canonical/'));
+
+    if (createdDocs.length > 0) {
+      console.log(`\n  ${c.bold}🤖 AI Auto-Populate${c.reset}`);
+      console.log(`  ${c.dim}The files above are skeleton templates. Your AI agent should fill them.${c.reset}`);
+      console.log(`  ${c.dim}Run this single command to get a full remediation plan:${c.reset}\n`);
+      console.log(`  ${c.cyan}${c.bold}docguard diagnose${c.reset}\n`);
+      console.log(`  ${c.dim}Or generate prompts for individual docs:${c.reset}`);
+
+      const docNameMap = {
+        'docs-canonical/ARCHITECTURE.md': 'architecture',
+        'docs-canonical/DATA-MODEL.md': 'data-model',
+        'docs-canonical/SECURITY.md': 'security',
+        'docs-canonical/TEST-SPEC.md': 'test-spec',
+        'docs-canonical/ENVIRONMENT.md': 'environment',
+      };
+
+      for (const doc of createdDocs) {
+        const target = docNameMap[doc];
+        if (target) {
+          console.log(`  ${c.cyan}docguard fix --doc ${target}${c.reset}`);
+        }
+      }
+      console.log(`\n  ${c.dim}Then verify:${c.reset} ${c.cyan}docguard guard${c.reset}\n`);
+    } else {
+      console.log(`\n  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to check for issues.${c.reset}\n`);
+    }
+  }
+}
+