@esthernandez/vibe-doc 0.2.2 → 0.3.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "vibe-doc",
+  "version": "0.3.0",
+  "description": "AI-powered documentation gap analyzer. Scans your codebase, classifies your project, identifies missing technical documentation, and generates professional docs from your existing artifacts.",
+  "author": {
+    "name": "626Labs LLC"
+  }
+}

package/commands/check.md

@@ -0,0 +1,7 @@
+---
+description: Check documentation completeness for deployment
+---
+
+Read `${CLAUDE_PLUGIN_ROOT}/skills/check/SKILL.md` and follow its instructions to run a CI-safe documentation check.
+
+Run `npx vibe-doc check` in the user's project directory. Present pass/fail results clearly. If docs are missing or stale, suggest running `/generate` to fix gaps.

package/commands/generate.md

@@ -0,0 +1,11 @@
+---
+description: Generate missing documentation
+---
+
+Read `${CLAUDE_PLUGIN_ROOT}/skills/generate/SKILL.md` and follow its full conversational flow to generate documentation for identified gaps.
+
+The generate skill will guide you through:
+1. Reviewing the current gap report
+2. Selecting which gaps to address
+3. Asking synthesis questions per doc type
+4. Generating markdown and/or docx output

package/commands/scan.md

@@ -0,0 +1,11 @@
+---
+description: Scan your project for documentation gaps
+---
+
+Read `${CLAUDE_PLUGIN_ROOT}/skills/scan/SKILL.md` and follow its full conversational flow to scan the user's project, classify it, and generate a documentation gap report.
+
+The scan skill will guide you through:
+1. Entry gate (context vs cold start)
+2. Artifact inventory scan via CLI
+3. Classification with user confirmation
+4. Gap report presentation

package/commands/status.md

@@ -0,0 +1,7 @@
+---
+description: Show current Vibe Doc status
+---
+
+Run `npx vibe-doc status` in the user's project directory via bash. Present the output in a clean format showing last scan time, classification, and documentation coverage.
+
+If no state exists, tell the user to run `/scan` first.

package/dist/generator/docx-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docx-writer.d.ts","sourceRoot":"","sources":["../../src/generator/docx-writer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOhD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,CA0CjB"}
+{"version":3,"file":"docx-writer.d.ts","sourceRoot":"","sources":["../../src/generator/docx-writer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAmBhD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,CAAC,CA0CjB"}

package/dist/generator/docx-writer.js

@@ -42,6 +42,18 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const docx_1 = require("docx");
 const logger_1 = require("../utils/logger");
+// Resolve vibe-doc's own version at module load time so generated docs
+// stamp the correct tool version. __dirname in dist/generator/ is one
+// level below the package root.
+const pkgVersion = (() => {
+    try {
+        const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+    }
+    catch {
+        return 'unknown';
+    }
+})();
 // Color scheme
 const NAVY = '1B2A4A';
 const STEEL = '3D5A80';
@@ -101,7 +113,7 @@ function parseMarkdownContent(content, docType, metadata) {
     let isFirstH1 = true;
     // Add metadata header as paragraphs
     sections.push(new docx_1.Paragraph({
-        text: `Generated by Vibe Doc v0.1.0`,
+        text: `Generated by Vibe Doc v${pkgVersion}`,
         spacing: { line: 240, lineRule: 'auto' },
     }));
     sections.push(new docx_1.Paragraph({

package/dist/generator/extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/generator/extractor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAib/C;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,YAAY,EACnB,WAAW,GAAE,MAAsB,GAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2CxB"}
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/generator/extractor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AA+gB/C;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,YAAY,EACnB,WAAW,GAAE,MAAsB,GAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuDxB"}

package/dist/generator/extractor.js

@@ -413,6 +413,85 @@ function extractThreatModel(projectPath, state) {
     }
     return result;
 }
+/**
+ * Extract data for README template.
+ * Pulls project name and description from package.json when available.
+ */
+function extractReadme(projectPath, _state) {
+    const pkg = readPackageJson(projectPath);
+    const extracted = {};
+    if (pkg?.name) {
+        extracted.projectName = pkg.name;
+    }
+    if (pkg?.description) {
+        extracted.tagline = pkg.description;
+        extracted.overview = pkg.description;
+    }
+    // Try to surface a reasonable install command for npm packages
+    if (pkg?.name) {
+        extracted.installation = `\`\`\`bash\nnpm install ${pkg.name}\n\`\`\``;
+    }
+    return extracted;
+}
+/**
+ * Extract data for Install Guide template.
+ * Uses package.json engines field for Node version prerequisites.
+ */
+function extractInstallGuide(projectPath, _state) {
+    const pkg = readPackageJson(projectPath);
+    const extracted = {};
+    const prereqParts = [];
+    if (pkg?.engines?.node) {
+        prereqParts.push(`- Node.js ${pkg.engines.node}`);
+    }
+    if (pkg?.engines && Object.keys(pkg.engines).length > 0) {
+        for (const [engine, version] of Object.entries(pkg.engines)) {
+            if (engine !== 'node') {
+                prereqParts.push(`- ${engine} ${version}`);
+            }
+        }
+    }
+    if (prereqParts.length > 0) {
+        extracted.prerequisites = prereqParts.join('\n');
+    }
+    if (pkg?.name) {
+        extracted.installSteps = `\`\`\`bash\nnpm install -g ${pkg.name}\n\`\`\``;
+    }
+    return extracted;
+}
+/**
+ * Extract data for Skill/Command Reference template.
+ * Lists SKILL.md files and commands/*.md files from the documentation inventory.
+ */
+function extractSkillCommandReference(_projectPath, state) {
+    const extracted = {};
+    const docFiles = state.artifactInventory?.categories?.documentation?.files ?? [];
+    const normalizedDocs = docFiles.map((f) => f.replace(/\\/g, '/'));
+    const skillFiles = normalizedDocs.filter((f) => /\/skills\/[^/]+\/SKILL\.md$/i.test(f));
+    const commandFiles = normalizedDocs.filter((f) => /\/commands\/[^/]+\.md$/i.test(f));
+    if (skillFiles.length > 0) {
+        const skillNames = skillFiles.map((f) => {
+            const match = f.match(/\/skills\/([^/]+)\//);
+            return match ? `- \`${match[1]}\`` : null;
+        }).filter(Boolean);
+        extracted.skillList = skillNames.join('\n');
+    }
+    if (commandFiles.length > 0) {
+        const commandNames = commandFiles.map((f) => {
+            const name = path.basename(f, '.md');
+            return `- \`/${name}\``;
+        });
+        extracted.commandList = commandNames.join('\n');
+    }
+    return extracted;
+}
+/**
+ * Extract data for Changelog/Contributing template.
+ * Minimal — the template is mostly user-filled.
+ */
+function extractChangelogContributing(_projectPath, _state) {
+    return {};
+}
 /**
  * Main extraction function - maps doc type to specific extractor
  */
@@ -442,6 +521,18 @@ function extractDataForDocType(docType, state, projectPath = process.cwd()) {
             case 'threat-model':
                 extracted = extractThreatModel(projectPath, state);
                 break;
+            case 'readme':
+                extracted = extractReadme(projectPath, state);
+                break;
+            case 'install-guide':
+                extracted = extractInstallGuide(projectPath, state);
+                break;
+            case 'skill-command-reference':
+                extracted = extractSkillCommandReference(projectPath, state);
+                break;
+            case 'changelog-contributing':
+                extracted = extractChangelogContributing(projectPath, state);
+                break;
             default:
                 logger_1.logger.warn('Unknown doc type for extraction', { docType });
                 extracted = {};

package/dist/generator/markdown-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-writer.d.ts","sourceRoot":"","sources":["../../src/generator/markdown-writer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,WAAW,GACpB,MAAM,CAyBR"}
+{"version":3,"file":"markdown-writer.d.ts","sourceRoot":"","sources":["../../src/generator/markdown-writer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkBH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,WAAW,GACpB,MAAM,CAyBR"}

package/dist/generator/markdown-writer.js

@@ -41,6 +41,18 @@ exports.writeMarkdown = writeMarkdown;
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const logger_1 = require("../utils/logger");
+// Resolve vibe-doc's own version at module load time so generated docs
+// stamp the correct tool version. __dirname in dist/generator/ is one
+// level below the package root.
+const pkgVersion = (() => {
+    try {
+        const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+    }
+    catch {
+        return 'unknown';
+    }
+})();
 /**
  * Write rendered content to a markdown file with metadata header
  * @param renderedContent - The rendered markdown content
@@ -75,7 +87,7 @@ function writeMarkdown(renderedContent, docType, projectPath, metadata) {
  */
 function generateMetadataHeader(metadata, docType) {
     const lines = [
-        '<!-- Generated by Vibe Doc v0.1.0 -->',
+        `<!-- Generated by Vibe Doc v${pkgVersion} -->`,
         `<!-- Date: ${metadata.generatedAt} -->`,
         `<!-- Classification: ${metadata.classification} -->`,
         `<!-- Source artifacts: ${metadata.sourceArtifacts} files scanned -->`,

package/dist/templates/index.d.ts

@@ -10,6 +10,19 @@
 export declare function loadTemplate(docType: string, cacheDir?: string): string;
 /**
  * Get path to the embedded template file
+ *
+ * __dirname at runtime is dist/templates/ (compiled from src/templates/index.ts).
+ * Templates are copied to dist/templates/embedded/ by scripts/copy-templates.js.
+ * So the templates directory relative to __dirname is just ./embedded/.
+ *
+ * The same path works in dev under tsx, where __dirname is src/templates/ and
+ * templates live at src/templates/embedded/.
+ *
+ * This was historically broken: the function looked for
+ * `__dirname/templates/embedded/` which produced `dist/templates/templates/embedded/`
+ * in published packages (nested "templates" directory). Combined with the
+ * copy-templates.js fast-glob bug (fixed in v0.2.2), template loading failed
+ * in every published version before v0.2.3.
  */
 export declare function getTemplatePath(docType: string): string;
 /**

package/dist/templates/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAuBvE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWvD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAgBxC;AAED,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAuBvE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAgBxC;AAED,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/templates/index.js

@@ -76,15 +76,22 @@ function loadTemplate(docType, cacheDir) {
 }
 /**
  * Get path to the embedded template file
+ *
+ * __dirname at runtime is dist/templates/ (compiled from src/templates/index.ts).
+ * Templates are copied to dist/templates/embedded/ by scripts/copy-templates.js.
+ * So the templates directory relative to __dirname is just ./embedded/.
+ *
+ * The same path works in dev under tsx, where __dirname is src/templates/ and
+ * templates live at src/templates/embedded/.
+ *
+ * This was historically broken: the function looked for
+ * `__dirname/templates/embedded/` which produced `dist/templates/templates/embedded/`
+ * in published packages (nested "templates" directory). Combined with the
+ * copy-templates.js fast-glob bug (fixed in v0.2.2), template loading failed
+ * in every published version before v0.2.3.
  */
 function getTemplatePath(docType) {
-    // __dirname is the dist directory at runtime
-    // Look for templates in both src (dev) and dist (prod) locations
-    let templatesDir = path.join(__dirname, 'templates', 'embedded');
-    // In development, __dirname points to src/templates, so adjust
-    if (!fs.existsSync(templatesDir)) {
-        templatesDir = path.join(__dirname, '..', '..', 'src', 'templates', 'embedded');
-    }
+    const templatesDir = path.join(__dirname, 'embedded');
     return path.join(templatesDir, `${docType}.md`);
 }
 /**

package/dist/templates/renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/templates/renderer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAaD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAwFzE"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/templates/renderer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAaD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CA0FzE"}

package/dist/templates/renderer.js

@@ -17,7 +17,9 @@ function renderTemplate(template, data) {
     let rendered = template;
     const confidenceLevels = [];
     // Extract all token patterns
-    const tokenPattern = /\{\{(extracted|user)\.([a-z0-9\-]+)\}\}/g;
+    // Supports both kebab-case (existing convention: service-overview) and
+    // camelCase (new plugin-oriented templates: installSteps).
+    const tokenPattern = /\{\{(extracted|user)\.([a-zA-Z0-9\-]+)\}\}/g;
     const tokens = new Map();
     let match;
     while ((match = tokenPattern.exec(template)) !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esthernandez/vibe-doc",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "AI-powered documentation gap analyzer and generator for modern codebases. Scans your project, classifies your architecture, and generates professional docs from your existing artifacts.",
   "author": "626Labs LLC",
   "license": "MIT",
@@ -24,6 +24,9 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "skills",
+    "commands",
+    ".claude-plugin",
     "README.md"
   ],
   "scripts": {

package/skills/check/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: check
+description: >
+  This skill should be used when the user mentions "check my docs",
+  "am I ready to deploy", "documentation check", "CI check",
+  "are my docs current", "deployment readiness", or wants to verify
+  their project meets documentation requirements before shipping.
+---
+
+# Vibe Doc Check Skill
+
+Simple CI-safe validation: verify that Required documentation exists and is current.
+
+**Shared behavior:** Read `skills/guide/SKILL.md` for state management, CLI patterns, and output formatting.
+
+---
+
+## Conversational Flow
+
+### 1. Run Check Command
+
+Execute the validation:
+
+```bash
+cd <project-path> && npx vibe-doc check .
+```
+
+---
+
+### 2. Present Results
+
+**If check passes:**
+
+```
+✓ Documentation Check PASSED
+
+Your project meets all Required documentation standards.
+
+Status Summary:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Classification: Web Application (Regulated, Customer-Facing)
+
+Required Docs:
+  ✓ Threat Model
+  ✓ Architecture Decision Records
+  ✓ Runbook
+  ✓ Test Plan
+
+All 4 required documents exist and are current.
+Last generated: 2026-04-05 (6 days ago)
+Last significant changes: 2026-04-08 (3 commits)
+
+Status: CURRENT (no staleness concerns)
+
+Next steps:
+  • Continue development
+  • Regenerate docs if major changes land (e.g., new deployment target, architecture pivot)
+  • Or just re-run this check before each deployment
+```
+
+---
+
+**If check fails:**
+
+```
+✗ Documentation Check FAILED
+
+Your project is missing or has stale Required documentation.
+
+Classification: Web Application (Regulated, Customer-Facing)
+
+Required Docs:
+  ✓ Threat Model (current)
+  ✗ Architecture Decision Records (MISSING)
+  ✓ Runbook (STALE — 18 commits, last generated 2026-03-25)
+  ✗ Test Plan (MISSING)
+
+Status: 1 of 4 docs current (25%)
+
+Why stale or missing?
+  • Runbook: 18 commits landed since generation, including deployment config changes
+  • ADRs: No generation history (may never have been created)
+  • Test Plan: No generation history (may never have been created)
+
+Risk: HIGH — Cannot deploy with missing Required docs
+
+Next steps to fix:
+
+Option 1: Quick regeneration (5-10 min)
+  Run the Generate skill to refresh stale docs and create missing ones.
+  
+Option 2: Manual review
+  If you've already created these docs manually (not via Vibe Doc):
+    1. Review docs/generated/ to see what exists
+    2. Run Scan skill to update your project profile
+    3. Then re-run this check
+    
+Option 3: Mark as not-applicable
+  If a Required doc doesn't apply to your project:
+    1. Update your classification in the Scan skill
+    2. Re-run this check
+```
+
+---
+
+### 3. Next Steps Checkpoint
+
+Ask user how to proceed:
+
+```
+[regenerate] → Run the Generate skill to fix gaps
+[scan] → Update project profile with Scan skill
+[review] → I'll show you what's in docs/generated/
+[exit] → Done with check (I'll report failure to CI)
+```
+
+**If user picks "regenerate":**
+- Transition to Generate skill with pre-selected stale/missing docs
+
+**If user picks "scan":**
+- Transition to Scan skill
+
+**If user picks "review":**
+- Show contents summary of docs/generated/ folder
+- List which Required docs exist and their last-modified dates
+
+**If user picks "exit":**
+- Show exit code for CI integration
+- Provide command to add to pipeline
+
+---
+
+## CI/CD Integration
+
+The check command is designed to be CI-safe. Show user how to integrate:
+
+```
+To add this check to your CI/CD pipeline:
+
+GitHub Actions example:
+
+  name: Documentation Check
+  on: [push, pull_request]
+  
+  jobs:
+    vibe-doc-check:
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+        - run: npm install -g vibe-doc
+        - run: npx vibe-doc check .
+          # Command exits with:
+          #   0 = all Required docs exist and current
+          #   1 = missing or stale Required docs
+```
+
+Other CI systems (GitLab CI, CircleCI, Jenkins):
+
+```bash
+# Run this command in your pipeline
+npx vibe-doc check .
+
+# Exit codes:
+#   0 = PASS (deploy allowed)
+#   1 = FAIL (deploy blocked)
+```
+
+---
+
+## Exit Codes & Automation
+
+The `check` command returns standard exit codes:
+
+| Exit Code | Meaning | Action |
+|-----------|---------|--------|
+| `0` | All Required docs exist and are current | Deployment can proceed |
+| `1` | Missing or stale Required docs | Deployment blocked; regenerate docs |
+
+**Use in CI conditionals:**
+
+```yaml
+# GitHub Actions
+- run: npx vibe-doc check .
+  continue-on-error: true  # Optional: allow preview deployments on fail
+  
+- name: Report Status
+  if: success()
+  run: echo "Documentation verified ✓"
+  
+- name: Report Status
+  if: failure()
+  run: |
+    echo "Documentation check failed ✗"
+    echo "Regenerate docs before merging: run Generate skill"
+    exit 1
+```
+
+---
+
+## Error Handling
+
+### No Classification Profile
+
+If no scan has been run:
+
+```
+Documentation check requires a project profile.
+
+Run the Scan skill first to:
+  • Analyze your project's artifacts
+  • Classify your app type
+  • Identify what documentation you need
+
+Then re-run this check.
+```
+
+### Check Command Fails
+
+```
+Check command failed: [error message]
+
+This usually means:
+  • No .vibe-doc/state.json file (run Scan first)
+  • Corrupted state file
+  • File system permissions issue
+
+Next steps:
+  1. Run Scan skill to create/repair project profile
+  2. Then re-run check
+```
+
+### Ambiguous Staleness
+
+If a doc's staleness is unclear (code changed but impact unknown):
+
+```
+⚠ Uncertain Staleness: Runbook
+
+This doc was generated on 2026-03-25. Since then:
+  • 18 commits (mostly feature work)
+  • 3 commits touched deployment configs
+  • 1 commit changed environment variables
+
+The doc may be outdated, but I'm not 100% certain.
+
+[regenerate] → Re-create the doc to be safe
+[keep] → The doc is still accurate (skip regeneration)
+```
+
+---
+
+## State & Output
+
+**Read from `.vibe-doc/state.json`:**
+- Classification (which Required docs apply)
+- Generated doc metadata (timestamps, file locations)
+- Generation history (to detect staleness)
+
+**Output to user:**
+- Pass/fail status
+- List of missing/stale/current docs
+- Exit code for CI
+
+**No files created or modified by this skill.**
+
+---
+
+## Use Cases
+
+**Developer before local deployment:**
+```
+npx vibe-doc check .
+# → Verify docs are current before deploying to staging
+```
+
+**CI pipeline (on every push):**
+```
+# Block merge if Required docs are missing
+if ! npx vibe-doc check .; then
+  exit 1
+fi
+```
+
+**CI pipeline (allow preview on fail):**
+```
+# Allow preview deployments, but warn on missing docs
+npx vibe-doc check . || true
+```
+
+**Scheduled check (weekly reminder):**
+```
+# Every Monday, check if docs have gone stale
+# If docs are >2 weeks old, alert the team
+```
+
+---
+
+**Last updated:** 2026-04-11 | **Version:** 1.0