docguard-cli 0.9.5 → 0.9.7

package/cli/validators/metrics-consistency.mjs

@@ -36,7 +36,8 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
       if (r.status === 'skipped') return sum;
       return sum + (r.total || 0);
     }, 0);
-    const validatorCount = guardResults.filter(r => r.status !== 'skipped').length;
+    // +1 because Metrics-Consistency itself hasn't been added to results yet
+    const validatorCount = guardResults.filter(r => r.status !== 'skipped').length + 1;
 
     actuals.checks = totalChecks;
     actuals.validators = validatorCount;

package/cli/validators/todo-tracking.mjs

@@ -110,14 +110,19 @@ function checkSkippedTests(projectDir) {
       const isSkipped = SKIP_PATTERNS.some(p => p.test(line));
       if (!isSkipped) continue;
 
-      // Check surrounding lines (1 above, 1 below, and inline) for explanation
-      const prevLine = i > 0 ? lines[i - 1] : '';
-      const nextLine = i < lines.length - 1 ? lines[i + 1] : '';
+      // Check surrounding lines (3 above, 1 below, and inline) for explanation
+      // Developers commonly place block comments above the skip call
+      const surroundingLines = [];
+      for (let j = Math.max(0, i - 3); j <= Math.min(lines.length - 1, i + 1); j++) {
+        surroundingLines.push(lines[j]);
+      }
+
+      // Also check for block comment pattern: /* REASON: ... */ or /** ... REASON: ... */
+      const blockCommentPattern = /\/\*[\s\S]*?(REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:/i;
 
       const hasReason =
-        SKIP_REASON_PATTERN.test(prevLine) ||
-        SKIP_REASON_PATTERN.test(line) ||
-        SKIP_REASON_PATTERN.test(nextLine);
+        surroundingLines.some(l => SKIP_REASON_PATTERN.test(l)) ||
+        blockCommentPattern.test(surroundingLines.join('\n'));
 
       if (hasReason) {
         skippedWithReason++;

package/commands/docguard.fix.md

@@ -1,21 +1,27 @@
 ---
-description: Generate AI prompts to fix specific documentation issues identified by DocGuard
+description: AI-driven documentation repair — research codebase, generate content, validate against CDD standards
+handoffs:
+  - label: Verify Fixes
+    agent: docguard.guard
+    prompt: Run guard to verify all fixes pass
+  - label: Check Score Improvement
+    agent: docguard.score
+    prompt: Show score improvement after fixes
 ---
 
 # DocGuard Fix — AI-Assisted Documentation Repair
 
-Generate targeted fix prompts for specific documentation issues.
+Generate or repair canonical documentation by researching the actual codebase.
 
 ## What to do
 
-1. First, identify what needs fixing:
+1. **Identify what needs fixing**:
 ```bash
 npx docguard-cli diagnose
 ```
 
-2. Generate fix prompts for specific documents:
+2. **For a specific document**, generate a research-aware fix prompt:
 ```bash
-# Fix a specific canonical doc
 npx docguard-cli fix --doc architecture
 npx docguard-cli fix --doc security
 npx docguard-cli fix --doc test-spec
@@ -23,23 +29,37 @@ npx docguard-cli fix --doc data-model
 npx docguard-cli fix --doc environment
 ```
 
-3. The fix command generates a detailed AI prompt. Read the prompt and execute its instructions:
-   - It will reference the project's actual code structure
-   - It will list specific sections to add or update
-   - It will include examples aligned with the project's tech stack
+3. **Execute the research workflow** from the generated prompt:
+   - Read actual code files (not just filenames)
+   - Map module structure and dependencies
+   - Extract real data structures and schemas
+   - Identify actual auth mechanisms and security patterns
 
-4. After fixing, verify the improvement:
+4. **Write documentation with real content**:
+   - Use actual file paths, module names, dependency names
+   - Include working command examples
+   - Use positive language (IEEE 830: "MUST use" not "MUST NOT avoid")
+   - Ensure Flesch-Kincaid grade level 8-10
+
+5. **Include metadata header** in every canonical doc:
+```markdown
+<!-- docguard:version X.X.X -->
+<!-- docguard:status active -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+```
+
+6. **Validate the fix** (iterate up to 3 times):
 ```bash
 npx docguard-cli guard
 ```
 
-5. If the project uses Spec Kit, ensure specs align with spec-kit templates:
-   - `spec.md` must have: User Scenarios, Requirements (FR-IDs), Success Criteria (SC-IDs)
-   - `plan.md` must have: Summary, Technical Context, Project Structure
-   - `tasks.md` must have: Phased breakdown (Phase 1, 2, 3+), Task IDs (T001+)
+7. If the project uses Spec Kit, align with spec-kit templates:
+   - `spec.md`: User Scenarios, Requirements (FR-IDs), Success Criteria (SC-IDs)
+   - `plan.md`: Summary, Technical Context, Project Structure
+   - `tasks.md`: Phased breakdown (Phase 1, 2, 3+), Task IDs (T001+)
 
 ## Important
 
-- Never overwrite existing documentation without creating a `.bak` backup
-- Use `--force` only when explicitly instructed by the user
-- Log any deviations from canonical docs in DRIFT-LOG.md with `// DRIFT: reason`
+- Never use placeholder content — every section must reference real code
+- Back up before overwriting — use `.bak` files or `safeWrite()`
+- Log deviations in DRIFT-LOG.md with `// DRIFT: reason`

package/commands/docguard.guard.md

@@ -1,5 +1,15 @@
 ---
-description: Run DocGuard guard validation — check project documentation quality against CDD standards
+description: Run DocGuard guard validation — check project documentation against CDD standards with 19 validators
+handoffs:
+  - label: Fix All Issues
+    agent: docguard.fix
+    prompt: Fix all documentation issues found by guard
+  - label: Deep Review
+    agent: docguard.review
+    prompt: Perform semantic cross-document consistency analysis
+  - label: Check Score
+    agent: docguard.score
+    prompt: Show CDD maturity score and improvement roadmap
 ---
 
 # DocGuard Guard — Documentation Quality Gate
@@ -8,20 +18,43 @@ Run the DocGuard CLI to validate all documentation against Canonical-Driven Deve
 
 ## What to do
 
-1. Run the guard command:
+1. **Run the guard command**:
 ```bash
 npx docguard-cli guard
 ```
 
-2. Review the output. Each validator reports ✅ (pass) or ❌ (fail):
-   - **Structure**: Required CDD files exist
-   - **Doc Sections**: Canonical docs have required sections
-   - **Drift**: Code deviations logged in DRIFT-LOG.md
-   - **Test-Spec**: Tests match TEST-SPEC.md rules
-   - **Security**: No hardcoded secrets
-   - **Spec-Kit**: Spec quality validation (FR-IDs, sections)
-   - **Doc-Quality**: Readability and writing quality
+2. **Parse the output**. Each of the 19 validators reports ✅ (pass), ⚠️ (warning), or ❌ (fail):
 
-3. If any checks fail, run `docguard diagnose` for a remediation plan.
+   | Validator | What It Checks |
+   |-----------|---------------|
+   | Structure | Required CDD files exist |
+   | Doc Sections | Canonical docs have required sections |
+   | Docs-Sync | External doc references are valid |
+   | Drift | Code deviations logged in DRIFT-LOG.md |
+   | Changelog | CHANGELOG.md is maintained |
+   | Test-Spec | Tests match TEST-SPEC.md rules |
+   | Environment | Environment documentation |
+   | Security | No hardcoded secrets, SECURITY.md quality |
+   | Architecture | Architecture documentation |
+   | Freshness | Docs updated within commit window |
+   | Traceability | Requirements trace to tests |
+   | Docs-Diff | Doc changes match code changes |
+   | Metadata-Sync | Metadata headers are consistent |
+   | Docs-Coverage | All config files documented |
+   | Doc-Quality | Readability, IEEE 830 compliance |
+   | TODO-Tracking | TODOs are tracked |
+   | Schema-Sync | Schema documentation matches code |
+   | Spec-Kit | Spec quality (FR-IDs, sections) |
+   | Metrics-Consistency | Internal counts are accurate |
 
-4. All checks must pass before committing. Exit code 0 = pass, 1 = fail, 2 = warnings only.
+3. **Triage findings by severity**:
+   - **CRITICAL**: Structure, Security, Test-Spec failures
+   - **HIGH**: Doc Sections, Drift, Changelog, Traceability failures
+   - **MEDIUM**: Freshness, Docs-Coverage, Doc-Quality, Metrics-Consistency warnings
+   - **LOW**: TODO-Tracking, Schema-Sync, Spec-Kit, Metadata-Sync warnings
+
+4. For each failing check, provide an **exact fix** — specific file, section, and content to change.
+
+5. After fixing, re-run `npx docguard-cli guard` to verify. Iterate until all checks pass.
+
+6. Exit codes: 0 = all pass, 1 = failures, 2 = warnings only.

package/commands/docguard.review.md

@@ -1,35 +1,53 @@
 ---
-description: Review documentation quality — identify improvements and suggest fixes based on CDD and spec-kit standards
+description: Cross-document consistency analysis — semantic review of documentation health, accuracy, and alignment with codebase
+handoffs:
+  - label: Fix Issues Found
+    agent: docguard.fix
+    prompt: Fix the documentation issues identified in the review
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Validate all documentation passes CDD standards
 ---
 
 # DocGuard Review — Documentation Quality Analysis
 
-Analyze the project's documentation quality and suggest specific improvements.
+Perform comprehensive, read-only analysis of documentation health with semantic cross-document consistency checking.
 
 ## What to do
 
-1. Run the full diagnostic:
+1. **Run the full diagnostic**:
 ```bash
 npx docguard-cli diagnose
-```
-
-2. Run the scoring engine:
-```bash
 npx docguard-cli score
 ```
 
-3. For each issue found, analyze the root cause:
-   - **Missing sections**: Check which mandatory sections are absent from canonical docs
-   - **Low readability**: Identify overly complex sentences or passive voice
-   - **Drift**: Find `// DRIFT:` comments in code not logged in DRIFT-LOG.md
-   - **Stale docs**: Compare doc modification dates against code changes
-   - **Spec quality**: Verify specs have FR-IDs, SC-IDs, and Given/When/Then scenarios
+2. **Perform semantic analysis** (beyond what CLI can check):
+
+   | Analysis Pass | What to Check |
+   |--------------|--------------|
+   | Terminology | Same concepts named consistently across docs |
+   | Architecture ↔ Code | Components listed in ARCHITECTURE.md exist in codebase |
+   | Data Model ↔ Code | Schemas in DATA-MODEL.md match actual implementations |
+   | Test Coverage | Critical flows in TEST-SPEC.md have actual test files |
+   | Security Claims | Auth mechanisms in SECURITY.md match actual code |
+   | Cross-References | Internal doc links resolve to valid targets |
+
+3. **Score each document** on 5 dimensions:
+
+   | Criterion | Weight | What to Evaluate |
+   |-----------|:------:|-----------------|
+   | Completeness | 30% | All mandatory sections present |
+   | Accuracy | 30% | Content matches actual codebase |
+   | Clarity | 20% | Readable, specific, no unexplained jargon |
+   | Currency | 10% | Up-to-date with latest code changes |
+   | Cross-refs | 10% | References are valid and bidirectional |
 
-4. Suggest specific improvements for each issue. Quote the relevant section and propose the fix.
+4. **Classify findings by severity**:
+   - 🔴 **CRITICAL**: Security claim mismatch, missing mandatory doc, broken architecture reference
+   - 🟠 **HIGH**: Undocumented component, stale content (>5 commits behind), terminology conflict
+   - 🟡 **MEDIUM**: Missing cross-reference, minor coverage gap, readability issue
+   - 🟢 **LOW**: Minor formatting, optional section missing, style inconsistency
 
-5. Prioritize fixes by impact:
-   - 🔴 HIGH: Missing docs, security issues, broken traceability
-   - 🟡 MEDIUM: Low readability, missing sections, stale content
-   - 🟢 LOW: Minor formatting, missing badges, metadata sync
+5. **Output a structured report** with findings table, per-document health scores, and priority-ordered recommendations.
 
-6. After making changes, re-run `npx docguard-cli guard` to verify improvements.
+6. **Do NOT modify files** — this is read-only analysis. Suggest fixes for user approval.

package/commands/docguard.score.md

@@ -1,27 +1,37 @@
 ---
-description: Show CDD maturity score — comprehensive documentation health assessment with category breakdown
+description: CDD maturity score with ROI-based improvement roadmap — shows category breakdown, grade progression, and highest-impact fixes
+handoffs:
+  - label: Fix Top Issues
+    agent: docguard.fix
+    prompt: Fix the highest-ROI documentation issues to improve score
+  - label: Full Review
+    agent: docguard.review
+    prompt: Perform deep semantic analysis for accuracy verification
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Verify current guard status after improvements
 ---
 
 # DocGuard Score — CDD Maturity Assessment
 
-Calculate and display the project's Canonical-Driven Development maturity score.
+Calculate and display the project's Canonical-Driven Development maturity score with ROI-based improvement roadmap.
 
 ## What to do
 
-1. Run the scoring engine:
+1. **Run the scoring engine**:
 ```bash
 npx docguard-cli score
 ```
 
-2. For JSON output (CI/CD integration):
+2. **For JSON output** (CI/CD integration):
 ```bash
 npx docguard-cli score --format json
 ```
 
-3. Interpret the results:
+3. **Interpret the grade**:
 
    | Grade | Score | Meaning |
-   |-------|-------|---------|
+   |-------|:-----:|---------|
    | A+ | 95-100 | Exemplary — production-grade documentation |
    | A | 85-94 | Strong — minor improvements possible |
    | B | 70-84 | Good — some gaps to address |
@@ -29,14 +39,23 @@ npx docguard-cli score --format json
    | D | 30-49 | Poor — major gaps in documentation |
    | F | 0-29 | Critical — documentation infrastructure missing |
 
-4. Focus on the category breakdown:
-   - **Structure** (25%): Do required files exist?
-   - **Doc Quality** (20%): Readability, completeness, sections
-   - **Testing** (15%): Test coverage documentation
-   - **Security** (10%): Security documentation
-   - **Environment** (10%): Environment variable documentation
-   - **Drift** (10%): Deviation tracking
-   - **Changelog** (5%): Change log maintenance
-   - **Architecture** (5%): Architecture documentation
-
-5. Prioritize improvements by category weight — fixing Structure issues has the highest impact.
+4. **Analyze category breakdown** (sorted by weight):
+
+   | Category | Weight | What It Measures |
+   |----------|:------:|-----------------|
+   | Structure | 25% | Required CDD files exist |
+   | Doc Quality | 20% | Readability, sections, IEEE 830 compliance |
+   | Testing | 15% | Test documentation coverage |
+   | Security | 10% | Security docs, secrets handling |
+   | Environment | 10% | Environment and setup docs |
+   | Drift | 10% | Code deviation tracking |
+   | Changelog | 5% | Change log maintenance |
+   | Architecture | 5% | Architecture documentation |
+
+5. **Build an ROI-ranked improvement roadmap**:
+   - Calculate `Potential Gain = weight - current points` for each category
+   - Sort by `Potential Gain / Effort` ratio
+   - Show: "If you fix [X], score will increase from [Y] to [Z]"
+   - Show the **minimum set of fixes** to reach the next grade level
+
+6. **Track progress**: Compare current score against previous runs to show improvement.

package/docs/installation.md

@@ -2,25 +2,30 @@
 
 ## Requirements
 
-- **Node.js** ≥ 18
+- **Node.js** ≥ 18 (required for both npm and Python installations)
 - **git** (optional — needed for freshness validation)
 
-## Install via npx (Recommended)
+## Install via npm
 
-No installation needed. Run directly:
+### Option 1: Run directly (no install)
 
 ```bash
-npx docguard --help
+npx docguard-cli diagnose
 ```
 
 This downloads and runs DocGuard on demand. Always uses the latest version.
 
-## Install as Dev Dependency
+### Option 2: Install globally
 
-For projects that want a pinned version:
+```bash
+npm i -g docguard-cli
+docguard diagnose
+```
+
+### Option 3: Dev dependency (pinned version)
 
 ```bash
-npm install --save-dev docguard
+npm install --save-dev docguard-cli
 ```
 
 Then use via npm scripts in `package.json`:
@@ -35,34 +40,44 @@ Then use via npm scripts in `package.json`:
 }
 ```
 
-## Install Globally
+## Install via Python (PyPI)
 
 ```bash
-npm install -g docguard
+pip install docguard-cli
+docguard diagnose
 ```
 
-Then use anywhere:
+> **Note:** The Python package is a thin wrapper that delegates to `npx docguard-cli`. Node.js 18+ must be installed on the system.
+
+The Python wrapper:
+- Detects Node.js 18+ on your system
+- Runs `npx docguard-cli` with all arguments forwarded
+- Provides clear error messages if Node.js is missing
+
+## Install as Spec Kit Extension
+
+If your project uses [GitHub Spec Kit](https://github.com/github/spec-kit):
 
 ```bash
-docguard guard
-docguard score
+specify extension add docguard
 ```
 
+This installs DocGuard's slash commands into your AI agent's command palette.
+
 ## Verify Installation
 
 ```bash
-npx docguard --version
+npx docguard-cli --version
+# Output: docguard v0.9.5
 ```
 
-Should output `DocGuard v0.4.0` (or current version).
-
 ## CI/CD Installation
 
 In GitHub Actions or similar:
 
 ```yaml
 - name: Run DocGuard
-  run: npx docguard ci --threshold 70
+  run: npx docguard-cli guard
 ```
 
 No separate install step needed — `npx` handles it.
@@ -71,11 +86,14 @@ No separate install step needed — `npx` handles it.
 
 ```bash
 # If installed as dev dependency
-npm update docguard
+npm update docguard-cli
 
 # If installed globally
-npm update -g docguard
+npm update -g docguard-cli
+
+# If installed via Python
+pip install --upgrade docguard-cli
 
 # If using npx — always runs latest automatically
-npx docguard@latest --version
+npx docguard-cli@latest --version
 ```

package/docs/quickstart.md

@@ -20,16 +20,32 @@ cd your-project
 npx docguard-cli init
 ```
 
-Creates all 5 canonical docs + tracking files + AI slash commands.
+Creates all 6 canonical docs (including REQUIREMENTS.md) + tracking files + AI slash commands.
 
-### Option C: From existing code (best for established projects)
+### Option C: Spec-Driven Development (spec-kit projects)
+
+If you're using [GitHub Spec Kit](https://github.com/github/spec-kit):
+
+```bash
+# 1. Initialize spec-kit
+specify init . --ai claude
+
+# 2. Add DocGuard as enforcement layer
+specify extension add docguard
+
+# 3. Write specs with AI, validate with DocGuard
+/speckit.specify Build an app that...
+npx docguard-cli guard
+```
+
+### Option D: From existing code (established projects)
 
 ```bash
 cd your-project
 npx docguard-cli generate
 ```
 
-Scans your codebase and generates pre-filled documentation.
+Scans your codebase and generates pre-filled documentation, including REQUIREMENTS.md with spec-kit-aligned FR/SC IDs.
 
 ## Fill the Docs (AI Does It)
 
@@ -52,9 +68,8 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check
+npx docguard-cli guard        # Pass/fail check (19 validators)
 npx docguard-cli score        # 0-100 maturity score
-npx docguard-cli score --tax  # How much time docs cost you
 ```
 
 ## Automate
@@ -66,7 +81,7 @@ npx docguard-cli hooks
 # CI/CD pipelines
 npx docguard-cli ci --threshold 70
 
-# Live watch mode with auto-fix
+# Live watch mode
 npx docguard-cli watch --auto-fix
 ```
 

package/extensions/spec-kit-docguard/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Accioly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/spec-kit-docguard/README.md

@@ -0,0 +1,103 @@
+# DocGuard — CDD Enforcement Extension for Spec Kit
+
+Enterprise-grade Canonical-Driven Development (CDD) enforcement for [Spec Kit](https://github.com/github/spec-kit). Validates, scores, and fixes project documentation with 19 automated validators, AI-driven research workflows, and spec-kit integration hooks.
+
+## Features
+
+- **19 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift, Freshness, and 13 more
+- **4 AI Skills** — Enterprise-grade AI behavior protocols (not just step-lists)
+- **3 Bash Scripts** — JSON-output orchestration for AI consumption
+- **Workflow Chaining** — YAML handoffs enable guard → fix → review → score flows
+- **Spec Kit Hooks** — Quality gate integrations at implement, tasks, and review phases
+- **Zero Dependencies** — Pure Node.js built-ins only
+
+## Installation
+
+```bash
+npm install -g docguard-cli
+```
+
+Or use via npx:
+```bash
+npx docguard-cli guard
+```
+
+## Quick Start
+
+```bash
+# Initialize CDD in your project
+docguard init
+
+# Check documentation health
+docguard guard
+
+# Get AI-ready fix prompts
+docguard fix --doc architecture
+
+# Calculate maturity score
+docguard score
+```
+
+## Commands
+
+| Command | Alias | Purpose |
+|---------|-------|---------|
+| `speckit.docguard.guard` | `docguard.guard` | Run 19-validator quality gate with severity triage |
+| `speckit.docguard.fix` | `docguard.fix` | AI-driven documentation repair with codebase research |
+| `speckit.docguard.review` | `docguard.review` | Cross-document semantic consistency analysis (read-only) |
+| `speckit.docguard.score` | `docguard.score` | CDD maturity score with ROI improvement roadmap |
+| `speckit.docguard.diagnose` | — | Diagnose issues + generate multi-perspective AI prompts |
+| `speckit.docguard.generate` | — | Reverse-engineer canonical docs from codebase |
+
+## AI Skills
+
+DocGuard provides 4 enterprise-grade AI behavior protocols modeled after Spec Kit's skill architecture:
+
+| Skill | Lines | What It Does |
+|-------|:-----:|-------------|
+| `docguard-guard` | 155 | 6-step execution with severity triage, structured reporting, remediation recommendations |
+| `docguard-fix` | 195 | 7-step research workflow with per-document codebase research, 3-iteration validation loops |
+| `docguard-review` | 170 | Semantic cross-document analysis with 6 analysis passes and quality scoring matrix |
+| `docguard-score` | 165 | CDD maturity assessment with ROI-based improvement roadmap and grade progression |
+
+Skills differ from commands in a critical way: **commands tell agents what to run** (step-lists), while **skills tell agents how to think, validate, and iterate** (behavior protocols).
+
+## Spec Kit Integration
+
+### Workflow Hooks
+
+DocGuard integrates into the spec-kit workflow through hooks:
+
+```yaml
+hooks:
+  after_implement:   # Optional — quality gate after /speckit.implement
+    command: speckit.docguard.guard
+  before_tasks:      # Optional — review docs before task generation
+    command: speckit.docguard.review
+  after_tasks:       # Optional — show score after tasks
+    command: speckit.docguard.score
+```
+
+### Workflow Chaining
+
+All commands support YAML handoffs for seamless workflow chaining:
+
+```
+guard → fix → review → score
+  ↑                      ↓
+  └──────────────────────┘
+```
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `docguard-check-docs.sh` | Discover docs, return JSON inventory with metadata |
+| `docguard-suggest-fix.sh` | Run guard, prioritize fixes as JSON |
+| `docguard-init-doc.sh` | Initialize canonical doc with metadata header |
+
+All scripts support `--json` mode for AI-parseable output.
+
+## License
+
+MIT © Ricardo Accioly