docguard-cli 0.9.5 → 0.9.7

package/cli/commands/init.mjs

@@ -8,6 +8,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { c, PROFILES } from '../shared.mjs';
+import { ensureSkills } from '../ensure-skills.mjs';
 
 function detectProjectType(dir) {
   const pkgPath = resolve(dir, 'package.json');
@@ -285,4 +286,7 @@ export async function runInit(projectDir, config, flags) {
   } else {
     console.log(`\n  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to check for issues.${c.reset}\n`);
   }
+
+  // Auto-install skills and commands
+  ensureSkills(projectDir, flags);
 }

package/cli/commands/setup.mjs

@@ -0,0 +1,455 @@
+/**
+ * Setup Command — Interactive onboarding wizard for DocGuard
+ *
+ * Walks through 7 steps to ensure DocGuard is fully configured:
+ *   1. Project detection & config
+ *   2. Canonical docs
+ *   3. AI skills
+ *   4. Slash commands
+ *   5. Agent configs
+ *   6. External integrations (spec-kit, understanding)
+ *   7. Git hooks
+ *
+ * Each step shows current status (✅/⚠️) and offers to fix what's missing.
+ * Supports --skip-prompts for non-interactive CI mode.
+ *
+ * Zero dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { execSync } from 'node:child_process';
+import { c } from '../shared.mjs';
+import { ensureSkills } from '../ensure-skills.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = resolve(__dirname, '../../templates');
+const SKILLS_SOURCE = resolve(__dirname, '../../extensions/spec-kit-docguard/skills');
+const COMMANDS_SOURCE = resolve(__dirname, '../../commands');
+
+// ── Readline Helper ─────────────────────────────────────────────────────
+
+function askQuestion(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(res => {
+    rl.question(prompt, answer => {
+      rl.close();
+      res(answer.trim().toLowerCase());
+    });
+  });
+}
+
+async function askYesNo(prompt, defaultYes = true) {
+  const label = defaultYes ? 'Y/n' : 'y/N';
+  const answer = await askQuestion(`${prompt} [${label}]: `);
+  if (answer === '') return defaultYes;
+  return answer === 'y' || answer === 'yes';
+}
+
+// ── Project Type Detection ──────────────────────────────────────────────
+
+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';
+}
+
+// ── CLI Detection ───────────────────────────────────────────────────────
+
+function isCliAvailable(name) {
+  try {
+    const cmd = process.platform === 'win32' ? `where ${name}` : `which ${name}`;
+    execSync(`${cmd} 2>/dev/null`, { encoding: 'utf-8', timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectAgentDirs(projectDir) {
+  const agentDirs = [
+    { name: 'GitHub Copilot', dir: '.github', commandsPath: '.github/commands' },
+    { name: 'Cursor', dir: '.cursor', commandsPath: '.cursor/rules' },
+    { name: 'Google Gemini', dir: '.gemini', commandsPath: '.gemini/commands' },
+    { name: 'Claude Code', dir: '.claude', commandsPath: '.claude/commands' },
+    { name: 'Antigravity', dir: '.agents', commandsPath: '.agents/workflows' },
+  ];
+
+  return agentDirs.filter(a => existsSync(resolve(projectDir, a.dir)));
+}
+
+// ── Main Setup Wizard ───────────────────────────────────────────────────
+
+export async function runSetup(projectDir, config, flags) {
+  console.log(`${c.bold}🧙 DocGuard Setup Wizard${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+
+  const interactive = !flags.skipPrompts;
+  let configured = 0;
+  let alreadyGood = 0;
+
+  // ── Step 1: Project Detection & Config ──────────────────────────────
+
+  console.log(`  ${c.bold}Step 1/7: Project Detection${c.reset}`);
+
+  const detectedType = detectProjectType(projectDir);
+  console.log(`  ${c.green}✅${c.reset} Project type: ${c.cyan}${detectedType}${c.reset}`);
+
+  const configPath = resolve(projectDir, '.docguard.json');
+  if (existsSync(configPath)) {
+    const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+    console.log(`  ${c.green}✅${c.reset} .docguard.json exists (profile: ${c.cyan}${cfg.profile || 'standard'}${c.reset})`);
+    alreadyGood++;
+  } else {
+    console.log(`  ${c.yellow}⚠️${c.reset}  .docguard.json missing`);
+    const create = interactive
+      ? await askYesNo(`     → Create config file?`)
+      : true;
+
+    if (create) {
+      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 defaultConfig = {
+        projectName: config.projectName,
+        version: '0.4',
+        profile: 'standard',
+        projectType: detectedType,
+        projectTypeConfig: typeDefaults[detectedType] || typeDefaults.unknown,
+      };
+
+      writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf-8');
+      console.log(`     ${c.green}✅ Created .docguard.json${c.reset}`);
+      configured++;
+    }
+  }
+
+  console.log('');
+
+  // ── Step 2: Canonical Docs ──────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 2/7: Canonical Docs${c.reset}`);
+
+  const canonicalDocs = [
+    { file: 'docs-canonical/ARCHITECTURE.md', template: 'ARCHITECTURE.md.template', label: 'Architecture',     defaultYes: true },
+    { file: 'docs-canonical/DATA-MODEL.md',   template: 'DATA-MODEL.md.template',   label: 'Data Model',      defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { file: 'docs-canonical/SECURITY.md',     template: 'SECURITY.md.template',     label: 'Security',        defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { file: 'docs-canonical/TEST-SPEC.md',    template: 'TEST-SPEC.md.template',    label: 'Test Spec',       defaultYes: true },
+    { file: 'docs-canonical/ENVIRONMENT.md',  template: 'ENVIRONMENT.md.template',  label: 'Environment',     defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { file: 'docs-canonical/REQUIREMENTS.md', template: 'REQUIREMENTS.md.template', label: 'Requirements',    defaultYes: true },
+  ];
+
+  const trackingFiles = [
+    { file: 'AGENTS.md',     template: 'AGENTS.md.template',     label: 'Agent Instructions' },
+    { file: 'CHANGELOG.md',  template: 'CHANGELOG.md.template',  label: 'Changelog' },
+    { file: 'DRIFT-LOG.md',  template: 'DRIFT-LOG.md.template',  label: 'Drift Log' },
+  ];
+
+  let missingDocs = [];
+
+  // Check canonical docs
+  for (const doc of [...canonicalDocs, ...trackingFiles]) {
+    const fullPath = resolve(projectDir, doc.file);
+    if (existsSync(fullPath)) {
+      console.log(`  ${c.green}✅${c.reset} ${doc.file}`);
+      alreadyGood++;
+    } else {
+      console.log(`  ${c.yellow}⚠️${c.reset}  ${doc.file} ${c.dim}(missing)${c.reset}`);
+      missingDocs.push(doc);
+    }
+  }
+
+  if (missingDocs.length > 0) {
+    const create = interactive
+      ? await askYesNo(`     → Create ${missingDocs.length} missing doc(s) from templates?`)
+      : true;
+
+    if (create) {
+      const today = new Date().toISOString().split('T')[0];
+      for (const doc of missingDocs) {
+        const destPath = resolve(projectDir, doc.file);
+        const templatePath = resolve(TEMPLATES_DIR, doc.template);
+
+        const destDir = dirname(destPath);
+        if (!existsSync(destDir)) {
+          mkdirSync(destDir, { recursive: true });
+        }
+
+        if (existsSync(templatePath)) {
+          const content = readFileSync(templatePath, 'utf-8').replace(/YYYY-MM-DD/g, today);
+          writeFileSync(destPath, content, 'utf-8');
+          console.log(`     ${c.green}✅ Created ${doc.file}${c.reset}`);
+          configured++;
+        }
+      }
+    }
+  }
+
+  console.log('');
+
+  // ── Step 3: AI Skills ──────────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 3/7: AI Skills${c.reset}`);
+
+  const skillNames = ['docguard-guard', 'docguard-fix', 'docguard-review', 'docguard-score'];
+  const skillsDest = resolve(projectDir, '.agent/skills');
+  let missingSkills = [];
+
+  for (const skill of skillNames) {
+    const skillPath = resolve(skillsDest, skill, 'SKILL.md');
+    if (existsSync(skillPath)) {
+      console.log(`  ${c.green}✅${c.reset} ${skill}`);
+      alreadyGood++;
+    } else {
+      console.log(`  ${c.yellow}⚠️${c.reset}  ${skill} ${c.dim}(not installed)${c.reset}`);
+      missingSkills.push(skill);
+    }
+  }
+
+  if (missingSkills.length > 0) {
+    const install = interactive
+      ? await askYesNo(`     → Install ${missingSkills.length} AI skill(s) to .agent/skills/?`)
+      : true;
+
+    if (install) {
+      for (const skill of missingSkills) {
+        const srcSkill = resolve(SKILLS_SOURCE, skill, 'SKILL.md');
+        const destDir = resolve(skillsDest, skill);
+        if (existsSync(srcSkill)) {
+          if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+          writeFileSync(resolve(destDir, 'SKILL.md'), readFileSync(srcSkill, 'utf-8'), 'utf-8');
+          console.log(`     ${c.green}✅ Installed ${skill}${c.reset}`);
+          configured++;
+        }
+      }
+    }
+  }
+
+  console.log('');
+
+  // ── Step 4: Slash Commands ─────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 4/7: Slash Commands${c.reset}`);
+
+  // Check root commands/ dir
+  const rootCommandsDir = resolve(projectDir, 'commands');
+  const rootCommandsExist = existsSync(resolve(rootCommandsDir, 'docguard.guard.md'));
+
+  if (rootCommandsExist) {
+    console.log(`  ${c.green}✅${c.reset} commands/ ${c.dim}(root)${c.reset}`);
+    alreadyGood++;
+  } else {
+    console.log(`  ${c.yellow}⚠️${c.reset}  commands/ ${c.dim}(not installed)${c.reset}`);
+  }
+
+  // Detect agent directories and sync commands
+  const detectedAgents = detectAgentDirs(projectDir);
+  let unsyncedAgents = [];
+
+  for (const agent of detectedAgents) {
+    const agentCommandCheck = resolve(projectDir, agent.commandsPath, 'docguard.guard.md');
+    if (existsSync(agentCommandCheck)) {
+      console.log(`  ${c.green}✅${c.reset} ${agent.commandsPath}/ ${c.dim}(${agent.name})${c.reset}`);
+      alreadyGood++;
+    } else {
+      console.log(`  ${c.yellow}⚠️${c.reset}  ${agent.commandsPath}/ ${c.dim}(${agent.name} — not synced)${c.reset}`);
+      unsyncedAgents.push(agent);
+    }
+  }
+
+  const needsCommands = !rootCommandsExist || unsyncedAgents.length > 0;
+
+  if (needsCommands && existsSync(COMMANDS_SOURCE)) {
+    const install = interactive
+      ? await askYesNo(`     → Install/sync slash commands?`)
+      : true;
+
+    if (install) {
+      const commandFiles = readdirSync(COMMANDS_SOURCE).filter(f => f.endsWith('.md'));
+
+      // Install to root commands/
+      if (!rootCommandsExist) {
+        if (!existsSync(rootCommandsDir)) mkdirSync(rootCommandsDir, { recursive: true });
+        for (const file of commandFiles) {
+          const destPath = resolve(rootCommandsDir, file);
+          if (!existsSync(destPath)) {
+            writeFileSync(destPath, readFileSync(resolve(COMMANDS_SOURCE, file), 'utf-8'), 'utf-8');
+          }
+        }
+        console.log(`     ${c.green}✅ Installed to commands/${c.reset}`);
+        configured++;
+      }
+
+      // Sync to agent-specific dirs
+      for (const agent of unsyncedAgents) {
+        const destDir = resolve(projectDir, agent.commandsPath);
+        if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+        for (const file of commandFiles) {
+          const destPath = resolve(destDir, file);
+          if (!existsSync(destPath)) {
+            writeFileSync(destPath, readFileSync(resolve(COMMANDS_SOURCE, file), 'utf-8'), 'utf-8');
+          }
+        }
+        console.log(`     ${c.green}✅ Synced to ${agent.commandsPath}/ (${agent.name})${c.reset}`);
+        configured++;
+      }
+    }
+  }
+
+  console.log('');
+
+  // ── Step 5: Agent Configs ──────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 5/7: Agent Configs${c.reset}`);
+
+  const agentConfigs = [
+    { file: 'AGENTS.md',  label: 'Agent Instructions' },
+    { file: 'CLAUDE.md',  label: 'Claude Code' },
+    { file: '.cursor/rules/cdd.mdc', label: 'Cursor' },
+    { file: '.github/copilot-instructions.md', label: 'GitHub Copilot' },
+  ];
+
+  let missingConfigs = [];
+  for (const cfg of agentConfigs) {
+    const fullPath = resolve(projectDir, cfg.file);
+    if (existsSync(fullPath)) {
+      console.log(`  ${c.green}✅${c.reset} ${cfg.file} ${c.dim}(${cfg.label})${c.reset}`);
+      alreadyGood++;
+    } else {
+      // AGENTS.md is handled in step 2, skip it here
+      if (cfg.file !== 'AGENTS.md') {
+        console.log(`  ${c.dim}──${c.reset}  ${cfg.file} ${c.dim}(${cfg.label} — not generated)${c.reset}`);
+        missingConfigs.push(cfg);
+      }
+    }
+  }
+
+  if (missingConfigs.length > 0) {
+    console.log(`  ${c.dim}   Run ${c.cyan}docguard agents${c.dim} to generate agent-specific configs${c.reset}`);
+  }
+
+  console.log('');
+
+  // ── Step 6: Integrations ───────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 6/7: Integrations${c.reset}`);
+
+  // Check spec-kit framework
+  const speckitDir = resolve(projectDir, '.speckit');
+  const hasSpeckit = existsSync(speckitDir) || existsSync(resolve(projectDir, 'spec.md'));
+  if (hasSpeckit) {
+    console.log(`  ${c.green}✅${c.reset} spec-kit ${c.dim}(spec-driven development configured)${c.reset}`);
+    alreadyGood++;
+  } else {
+    console.log(`  ${c.dim}──${c.reset}  spec-kit ${c.dim}(not configured — optional)${c.reset}`);
+    console.log(`  ${c.dim}     Spec Kit enables spec-driven development with AI agents${c.reset}`);
+    console.log(`  ${c.dim}     See: ${c.cyan}https://github.com/github/spec-kit${c.reset}`);
+  }
+
+  // Check for spec-kit extensions
+  const extensionsDir = resolve(projectDir, 'extensions');
+  
+  // DocGuard extension (this project IS DocGuard, so check if extension is bundled)
+  const docguardExt = resolve(extensionsDir, 'spec-kit-docguard', 'extension.yml');
+  if (existsSync(docguardExt)) {
+    console.log(`  ${c.green}✅${c.reset} docguard extension ${c.dim}(spec-kit CDD enforcement)${c.reset}`);
+    alreadyGood++;
+  } else {
+    // DocGuard is installed as a CLI, not necessarily as a spec-kit extension
+    console.log(`  ${c.green}✅${c.reset} docguard CLI ${c.dim}(standalone — 19 validators + 31 quality metrics)${c.reset}`);
+    alreadyGood++;
+  }
+
+  // Understanding extension (spec-kit community extension)
+  const understandingExt = resolve(extensionsDir, 'spec-kit-understanding', 'extension.yml');
+  if (existsSync(understandingExt)) {
+    console.log(`  ${c.green}✅${c.reset} understanding ${c.dim}(spec-kit deep doc analysis)${c.reset}`);
+    alreadyGood++;
+  } else {
+    console.log(`  ${c.dim}──${c.reset}  understanding ${c.dim}(spec-kit extension — optional)${c.reset}`);
+    console.log(`  ${c.dim}     Install via spec-kit: ${c.cyan}https://github.com/github/spec-kit/tree/main/extensions${c.reset}`);
+  }
+
+  console.log('');
+
+  // ── Step 7: Git Hooks ──────────────────────────────────────────────
+
+  console.log(`  ${c.bold}Step 7/7: Git Hooks${c.reset}`);
+
+  const gitDir = resolve(projectDir, '.git');
+  if (!existsSync(gitDir)) {
+    console.log(`  ${c.dim}──${c.reset}  No .git directory ${c.dim}(not a git repo)${c.reset}`);
+  } else {
+    const preCommitHook = resolve(gitDir, 'hooks', 'pre-commit');
+    let hasDocguardHook = false;
+
+    if (existsSync(preCommitHook)) {
+      const content = readFileSync(preCommitHook, 'utf-8');
+      hasDocguardHook = content.includes('docguard');
+    }
+
+    if (hasDocguardHook) {
+      console.log(`  ${c.green}✅${c.reset} pre-commit hook ${c.dim}(docguard guard)${c.reset}`);
+      alreadyGood++;
+    } else {
+      console.log(`  ${c.dim}──${c.reset}  pre-commit hook ${c.dim}(not installed)${c.reset}`);
+      if (interactive) {
+        const install = await askYesNo(`     → Install docguard guard as pre-commit hook?`, false);
+        if (install) {
+          try {
+            const hooksDir = resolve(gitDir, 'hooks');
+            if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+
+            const hookContent = existsSync(preCommitHook)
+              ? readFileSync(preCommitHook, 'utf-8') + '\n\n# DocGuard CDD validation\nnpx docguard guard --fail-on-warning\n'
+              : '#!/bin/sh\n\n# DocGuard CDD validation\nnpx docguard guard --fail-on-warning\n';
+
+            writeFileSync(preCommitHook, hookContent, { mode: 0o755 });
+            console.log(`     ${c.green}✅ Pre-commit hook installed${c.reset}`);
+            configured++;
+          } catch (e) {
+            console.log(`     ${c.yellow}⚠️  Failed to install hook: ${e.message}${c.reset}`);
+          }
+        }
+      }
+    }
+  }
+
+  // ── Summary ────────────────────────────────────────────────────────
+
+  console.log(`\n  ${c.bold}─────────────────────────────────────${c.reset}`);
+
+  if (configured > 0) {
+    console.log(`  ${c.green}✅ Setup complete!${c.reset} ${configured} item(s) configured, ${alreadyGood} already good.`);
+  } else if (alreadyGood > 0) {
+    console.log(`  ${c.green}✅ Everything is set up!${c.reset} ${alreadyGood} item(s) verified.`);
+  } else {
+    console.log(`  ${c.dim}No changes made.${c.reset}`);
+  }
+
+  console.log(`\n  ${c.bold}Next steps:${c.reset}`);
+  console.log(`  ${c.dim}Fill docs:${c.reset}      ${c.cyan}docguard diagnose${c.reset}`);
+  console.log(`  ${c.dim}Validate:${c.reset}       ${c.cyan}docguard guard${c.reset}`);
+  console.log(`  ${c.dim}Check score:${c.reset}    ${c.cyan}docguard score${c.reset}`);
+  console.log('');
+}

package/cli/docguard.mjs

@@ -38,6 +38,8 @@ import { runDiagnose } from './commands/diagnose.mjs';
 import { runPublish } from './commands/publish.mjs';
 import { runTrace } from './commands/trace.mjs';
 import { runLlms } from './commands/llms.mjs';
+import { runSetup } from './commands/setup.mjs';
+import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
 import { c, PROFILES } from './shared.mjs';
@@ -218,6 +220,7 @@ function printHelp() {
 
 ${c.bold}Getting Started:${c.reset}
   ${c.green}init${c.reset}       Initialize CDD docs (interactive setup)
+  ${c.green}setup${c.reset}      Full onboarding wizard (skills, integrations, hooks)
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code
 
 ${c.bold}Enforcement:${c.reset}
@@ -376,6 +379,11 @@ async function main() {
 
   const config = loadConfig(projectDir);
 
+  // Silent auto-check: install skills/commands if missing
+  if (command !== 'setup' && command !== 'init') {
+    ensureSkills(projectDir, flags);
+  }
+
   switch (command) {
     case 'audit':
       // audit is an alias for guard — guard does everything the old audit did + 50 more checks
@@ -384,6 +392,10 @@ async function main() {
     case 'init':
       await runInit(projectDir, config, flags);
       break;
+    case 'setup':
+    case 'onboard':
+      await runSetup(projectDir, config, flags);
+      break;
     case 'guard':
       runGuard(projectDir, config, flags);
       break;

package/cli/ensure-skills.mjs

@@ -0,0 +1,96 @@
+/**
+ * Ensure Skills — Silent auto-check for DocGuard AI skills and commands
+ *
+ * Called before every command execution. If skills or commands are missing,
+ * copies them from the package's bundled assets into the project directory.
+ *
+ * Zero dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, cpSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { c } from './shared.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Source locations in the npm package
+const SKILLS_SOURCE = resolve(__dirname, '..', 'extensions', 'spec-kit-docguard', 'skills');
+const COMMANDS_SOURCE = resolve(__dirname, '..', 'commands');
+
+// Destination in the user's project
+const SKILLS_DEST = '.agent/skills';
+const COMMANDS_DEST = 'commands';
+
+/**
+ * Silently ensure skills and commands are installed in the project.
+ *
+ * @param {string} projectDir - The project root directory
+ * @param {object} flags - CLI flags (format, etc.)
+ * @returns {{ skillsInstalled: boolean, commandsInstalled: boolean }}
+ */
+export function ensureSkills(projectDir, flags = {}) {
+  const result = { skillsInstalled: false, commandsInstalled: false };
+  const silent = flags.format === 'json';
+
+  // ── Skills ────────────────────────────────────────────────────────────
+  const skillsCheck = resolve(projectDir, SKILLS_DEST, 'docguard-guard', 'SKILL.md');
+  if (!existsSync(skillsCheck) && existsSync(SKILLS_SOURCE)) {
+    try {
+      const skillDirs = readdirSync(SKILLS_SOURCE).filter(d =>
+        existsSync(resolve(SKILLS_SOURCE, d, 'SKILL.md'))
+      );
+
+      for (const skillDir of skillDirs) {
+        const destDir = resolve(projectDir, SKILLS_DEST, skillDir);
+        if (!existsSync(destDir)) {
+          mkdirSync(destDir, { recursive: true });
+        }
+        const srcSkill = resolve(SKILLS_SOURCE, skillDir, 'SKILL.md');
+        const destSkill = resolve(destDir, 'SKILL.md');
+        if (!existsSync(destSkill)) {
+          writeFileSync(destSkill, readFileSync(srcSkill, 'utf-8'), 'utf-8');
+        }
+      }
+
+      result.skillsInstalled = true;
+      if (!silent) {
+        console.log(`  ${c.cyan}✨ DocGuard AI skills installed → ${SKILLS_DEST}/${c.reset}`);
+      }
+    } catch {
+      // Silent failure — skills are optional enhancement
+    }
+  }
+
+  // ── Slash Commands ────────────────────────────────────────────────────
+  const commandsCheck = resolve(projectDir, COMMANDS_DEST, 'docguard.guard.md');
+  if (!existsSync(commandsCheck) && existsSync(COMMANDS_SOURCE)) {
+    try {
+      const commandFiles = readdirSync(COMMANDS_SOURCE).filter(f => f.endsWith('.md'));
+
+      if (commandFiles.length > 0) {
+        const destDir = resolve(projectDir, COMMANDS_DEST);
+        if (!existsSync(destDir)) {
+          mkdirSync(destDir, { recursive: true });
+        }
+
+        for (const file of commandFiles) {
+          const destPath = resolve(destDir, file);
+          if (!existsSync(destPath)) {
+            writeFileSync(destPath, readFileSync(resolve(COMMANDS_SOURCE, file), 'utf-8'), 'utf-8');
+          }
+        }
+
+        result.commandsInstalled = true;
+        if (!silent) {
+          console.log(`  ${c.cyan}✨ DocGuard slash commands installed → ${COMMANDS_DEST}/${c.reset}`);
+        }
+      }
+    } catch {
+      // Silent failure — commands are optional enhancement
+    }
+  }
+
+  return result;
+}

package/cli/validators/doc-quality.mjs

@@ -33,8 +33,8 @@ const THRESHOLDS = {
   passiveVoiceRatio:     { warn: 0.25, label: 'Passive voice ratio' },       // >25% passive = warn
   ambiguousPronounRatio: { warn: 0.15, label: 'Ambiguous pronoun ratio' },   // >15% ambiguous pronouns = warn
   atomicityScore:        { warn: 0.35, label: 'Non-atomic sentence ratio' }, // >35% compound sentences = warn
-  fleschReadingEase:     { warn: 15,   label: 'Flesch reading ease' },       // <15 = truly unreadable prose
-  fleschKincaidGrade:    { warn: 18,   label: 'Flesch-Kincaid grade' },      // >18 = graduate level+
+  fleschReadingEase:     { warn: 5,    label: 'Flesch reading ease' },       // <5 = truly unreadable prose (tech docs typically score 10-30)
+  fleschKincaidGrade:    { warn: 22,   label: 'Flesch-Kincaid grade' },      // >22 = PhD level+ (tech docs typically 14-20)
   avgSentenceLength:     { warn: 30,   label: 'Avg sentence length' },       // >30 words = too long
   negationLoad:          { warn: 0.20, label: 'Negation load' },             // >20% sentences with negation = warn
   conditionalLoad:       { warn: 0.30, label: 'Conditional load' },          // >30% sentences conditional = warn

package/cli/validators/docs-sync.mjs

@@ -118,18 +118,53 @@ export function validateDocsSync(projectDir, config) {
         if (!['.ts', '.js', '.mjs'].includes(ext)) continue;
 
         // Skip index/middleware files
-        const name = basename(file, ext).toLowerCase();
-        if (name === 'index' || name === 'middleware' || name.startsWith('_')) continue;
+        const rawName = basename(file, ext).toLowerCase();
+        if (rawName === 'index' || rawName === 'middleware' || rawName.startsWith('_')) continue;
 
         results.total++;
 
-        // Check if a likely route path exists in the OpenAPI spec
-        // Route file "users.ts" → check for "/users" in spec
-        if (openapiContent.includes(`/${name}`) || openapiContent.includes(`"${name}"`)) {
+        // Strategy 1: Parse the route file for actual route paths
+        // Look for router.get('/path'), app.post('/path'), etc.
+        let routeFileContent = '';
+        try { routeFileContent = readFileSync(file, 'utf-8').toLowerCase(); } catch { /* skip */ }
+
+        const actualRoutes = [];
+        const routeDefRegex = /(?:router|app|route)\s*\.\s*(?:get|post|put|delete|patch|all|use)\s*\(\s*['"`](\/[^'"`]*)['"`]/gi;
+        let routeMatch;
+        while ((routeMatch = routeDefRegex.exec(routeFileContent)) !== null) {
+          actualRoutes.push(routeMatch[1]);
+        }
+
+        let matched = false;
+
+        if (actualRoutes.length > 0) {
+          // Check if ANY of the actual route paths appear in the OpenAPI spec
+          matched = actualRoutes.some(route => {
+            // Normalize: /api/conversations/:id → /api/conversations
+            const basePath = route.replace(/\/:[^/]+/g, '').replace(/\/{[^}]+}/g, '');
+            return openapiContent.includes(basePath) || openapiContent.includes(route);
+          });
+        } else {
+          // Strategy 2 (fallback): Strip common suffixes and check filename
+          // userRoutes.ts → 'user', conversationRoutes.ts → 'conversation'
+          const cleanName = rawName
+            .replace(/routes?$/i, '')
+            .replace(/controllers?$/i, '')
+            .replace(/handlers?$/i, '')
+            .replace(/router$/i, '');
+
+          if (cleanName.length > 0) {
+            matched = openapiContent.includes(`/${cleanName}`) ||
+                      openapiContent.includes(`"${cleanName}"`) ||
+                      openapiContent.includes(`'${cleanName}'`);
+          }
+        }
+
+        if (matched) {
           results.passed++;
         } else {
           results.warnings.push(
-            `Route file ${basename(file)} exists but no /${name} path found in ${openapiFile}. ` +
+            `Route file ${basename(file)} exists but no matching paths found in ${openapiFile}. ` +
             `Run your spec generator (e.g., zod-to-openapi) to update the API spec`
           );
         }