docguard-cli 0.18.1 → 0.21.0

package/README.md

@@ -12,9 +12,18 @@
 
 ---
 
+> **✨ See what DocGuard catches in 30 seconds — no install, no setup:**
+> ```bash
+> npx docguard-cli demo
+> ```
+> Runs against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.
+
+---
+
 ## Table of Contents
 
 - [What is DocGuard?](#what-is-docguard)
+- [What's New](#-whats-new)
 - [Quick Start](#-quick-start)
 - [Spec Kit Integration](#-spec-kit-integration)
 - [Usage](#usage)
@@ -50,15 +59,15 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 ```mermaid
 graph TD
-    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (15)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (14)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
     Commands --> diagnose["diagnose"]
     Commands --> setup["setup wizard"]
-    Commands --> other["diff · init · fix · trace<br/>agents · hooks · badge · ci · watch"]
+    Commands --> other["diff · init · fix · trace · impact · sync<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (19)"]
+    guard --> Validators["Validators (23)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -81,6 +90,37 @@ graph TD
 
 ---
 
+## ✨ What's New
+
+Recent highlights across the v0.16 → v0.19 line:
+
+- **`docguard explain <validator>`** — `docguard explain freshness` prints purpose, rules, common
+  failures, and fix recipes for any of the 23 validators. No need to dig into source.
+- **`docguard memory --diff`** — surface what changed in your canonical docs between two refs
+  (`HEAD~10..HEAD` by default). Great for code review and changelog drafting.
+- **`docguard score --diff`** — see exactly which validators moved the score up or down between
+  two commits. Pinpoints regressions without re-running the full suite by hand.
+- **`docguard upgrade --apply --pr`** — when the config schema bumps, DocGuard migrates
+  `.docguard.json` for you and (optionally) opens a PR with the change.
+- **Language-aware patterns** — test discovery and trace mapping now understand Python, Rust, Go,
+  Java, Ruby, and PHP layouts in addition to JS/TS. Sensible defaults, override via config.
+- **Per-validator severity overrides** — escalate `freshness` to `high` for production repos,
+  demote `doc-quality` to `low` for prototypes. Configurable per-project.
+- **JSON Schema for `.docguard.json`** — IDE autocomplete, in-line docs, and validation via
+  `$schema`. Shipped in the package at `schemas/docguard-config.schema.json`.
+- **Version pin (`docguardVersion` + `--pin`)** — pin the CLI version your project supports so
+  CI fails loudly if someone bumps DocGuard without re-running the suite.
+- **Cross-process plan cache** — repeated runs reuse the validator plan across processes when
+  the working tree hasn't changed. ~30% faster guard runs on typical repos.
+- **Headless-aware banner** — `--quiet`, `--format json`, `--write`, and `--changed-only`
+  automatically suppress the banner so JSON output stays parse-clean.
+- **npm-pack smoke gate** — every release now extracts the actual tarball and runs the CLI
+  end-to-end before publish, catching missing-file regressions.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+
+---
+
 ## ⚡ Quick Start
 
 ### Node.js (npm)
@@ -203,24 +243,49 @@ This installs DocGuard's slash commands (`/docguard.guard`, `/docguard.review`,
 
 ## Usage
 
-DocGuard ships **13 commands**:
+DocGuard ships **14 commands** (the "Daily 5" + 9 situational tools, including the zero-install `demo`). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+
+**The Daily 5** — what you'll reach for 95% of the time:
+
+| Command | What It Does |
+|:--------|:-------------|
+| `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
+| `guard` | Validate against canonical docs — 23 validators |
+| `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
+| `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
+| `score` | CDD maturity score (0-100; `--diff` for delta between refs) |
+
+**Tools (situational, but day-to-day useful):**
 
 | Command | Purpose |
 |:--------|:--------|
-| `diagnose` | **Primary** — identify every issue + generate AI fix prompts |
-| `guard` | Validate project against canonical docs (CI gate) |
-| `generate` | Reverse-engineer docs from existing codebase |
-| `init` | Initialize CDD docs from templates (interactive) |
-| `score` | CDD maturity score (0–100) with weighted breakdown |
-| `fix --doc <name>` | Generate AI prompt for a specific document |
-| `fix --write` | Apply deterministic fixes (remove stale documented endpoints) — no AI |
-| `diff` | Compare canonical docs vs actual code artifacts |
-| `agents` | Generate agent-specific config files |
-| `trace` | Requirements traceability matrix |
-| `ci` | CI/CD pipeline check with threshold |
-| `watch` | Live watch mode with auto-fix |
-| `hooks` | Install git hooks (pre-commit, pre-push) |
-| `llms` | Generate `llms.txt` (AI-friendly project summary) |
+| `diagnose` | AI orchestrator — guard → emit fix prompts in one command |
+| `fix` | Generate AI fix instructions for specific docs (`--doc <name> --format prompt`) |
+| `fix --write` | Apply deterministic fixes (no AI — version bumps, counts, anchors, sections) |
+| `fix --history` | Audit log of every mechanical fix applied (from `.docguard/fixed.json`) |
+| `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) |
+| `explain <warning>` | Paste any warning — get the validator's docstring + fix path |
+| `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
+| `memory --diff` | Drill into which specific claims don't match code |
+| `score --diff` | Drill into which checks pulled each category down |
+| `trace` / `trace --reverse <file>` | Requirements traceability — forward AND reverse |
+| `upgrade [--apply] [--pr]` | Check + migrate `.docguard.json` schema; `--pr` opens a PR |
+| `watch` | Live mode: re-run guard on file changes |
+
+**`init --with <name>` scaffolders** — picked at init time:
+
+| Scaffolder | What It Generates |
+|:-----------|:------------------|
+| `agents` | `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.github/copilot-instructions.md` |
+| `hooks` | Git pre-commit / pre-push hooks |
+| `ci` | GitHub Actions / pipeline YAML |
+| `badge` | Shields.io score badges for README |
+| `llms` | `llms.txt` (AI-friendly summary) |
+| `publish` | External doc-site config (Mintlify) — experimental |
+
+Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with agents,hooks,badge,ci`).
+
+**Deprecation aliases** — `setup` · `agents` · `hooks` · `ci` · `badge` · `llms` · `publish` · `impact` keep working in v0.20.x with a yellow stderr warning. `audit → guard` is permanent (no warning). See [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
 
 ### CLI Flags
 
@@ -228,10 +293,22 @@ DocGuard ships **13 commands**:
 |:-----|:------------|:---------|
 | `--dir <path>` | Project directory (default: `.`) | All |
 | `--verbose` | Show detailed output | All |
-| `--format json` | Machine-readable output for CI/CD | score, guard, diff |
+| `--quiet` / `-q` | Suppress banner — for hooks, CI loops, scripts | All |
+| `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain |
 | `--force` | Overwrite existing files (creates `.bak` backups) | generate, agents, init |
-| `--profile <name>` | Starter, standard, or enterprise | init |
-| `--agent <name>` | Target specific AI agent | agents |
+| `--force-redo` | Bypass ping-pong suppression in `.docguard/fixed.json` | fix --write |
+| `--profile <name>` | Starter / standard / enterprise | init |
+| `--no-spec-kit` | Skip auto-init of `.specify/` / `.agent/` scaffolding | init |
+| `--changed-only [--since <ref>]` | Pre-commit lite mode (5 fast validators on changed files only) | guard |
+| `--timings` | Per-validator wall-time profile (slowest first) | guard |
+| `--show-failing` | Show warnings/errors even when status is PASS | guard |
+| `--pin` | Record running CLI version into `.docguard.json` (reproducibility) | guard |
+| `--diff` | Per-category drill-down | score, memory |
+| `--check-only` | Exit 1 if behind (for CI) | upgrade |
+| `--apply` | Actually run the migration | upgrade |
+| `--pr` | Open a PR with the migration | upgrade |
+| `--reverse <file>` | Reverse traceability (code → docs) | trace |
+| `--history` | Show fix audit log | fix |
 
 ### Example Output
 
@@ -266,30 +343,47 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **19 automated validators** on every `guard` check:
+DocGuard runs **23 automated validators** on every `guard` check. Every one is **language-aware** as of v0.16 — patterns for Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), PHP, and JS/TS all match.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
 | 1 | **Structure** | Required CDD files exist | ✅ On |
-| 2 | **Doc Sections** | Canonical docs have required sections | ✅ On |
+| 2 | **Doc Sections** | Canonical docs have required sections (or N/A markers) | ✅ On |
 | 3 | **Docs-Sync** | Routes/services referenced in docs + OpenAPI cross-check | ✅ On |
-| 4 | **Drift-Comments** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
+| 4 | **Drift-Comments** | `// DRIFT:` comments logged in DRIFT-LOG.md (skips test files by default) | ✅ On |
 | 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
 | 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
-| 7 | **Environment** | Env vars documented, .env.example exists | ✅ On |
+| 7 | **Environment** | Env vars documented, `.env.example` exists | ✅ On |
 | 8 | **Security** | No hardcoded secrets in source code | ✅ On |
-| 9 | **Architecture** | Imports follow layer boundaries | ✅ On |
-| 10 | **Freshness** | Docs not stale relative to code changes | ✅ On |
+| 9 | **Architecture** | Imports follow layer boundaries (honors `config.ignore`) | ✅ On |
+| 10 | **Freshness** | Docs not stale relative to code changes (rename-aware via `git log --follow`) | ✅ On |
 | 11 | **Traceability** | Requirement IDs (FR, SC, NFR, US, AC, T) trace to tests | ✅ On |
 | 12 | **Docs-Diff** | Code artifacts match documented entities | ✅ On |
-| 13 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
-| 14 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
-| 15 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
-| 16 | **Doc-Quality** | Writing quality (readability, passive voice, atomicity) | ✅ On |
-| 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests | ✅ On |
+| 13 | **API-Surface** | API-REFERENCE.md endpoints match real routes (OpenAPI cross-check) | ✅ On |
+| 14 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
+| 15 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
+| 16 | **Doc-Quality** | Writing quality (readability, passive voice, atomicity, IEEE 830) | ✅ On |
+| 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests (skips test files by default) | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
-| 20 | **API-Surface** | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes); flags documented-but-deleted endpoints | ✅ On |
+| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints) | ✅ On |
+| 21 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
+| 22 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
+| 23 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
+
+**Per-validator controls** (in `.docguard.json`):
+```json
+{
+  "validators": {
+    "test-spec": false,                 // disable (kebab-case OR camelCase both accepted)
+    "freshness": true
+  },
+  "severity": {
+    "todoTracking": "high",             // warnings fail CI
+    "freshness": "low"                  // warnings ignored for exit code
+  }
+}
+```
 
 ---
 
@@ -343,7 +437,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 22 validators |
+| `/docguard.guard` | Run quality validation — check all 23 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.score` | Show CDD maturity score with category breakdown |

package/cli/commands/demo.mjs

@@ -0,0 +1,241 @@
+/**
+ * Demo Command — v0.21.
+ *
+ * The 30-second "ah-ha" experience for devs shopping for doc tools.
+ *
+ *   npx docguard-cli demo
+ *
+ * Spins up a baked-in fixture project (`templates/demo-fixture/`) — a 4-service
+ * payments API with INTENTIONAL doc drift — runs guard against it, and prints
+ * a curated narrative with real-world-impact annotations + a clear install CTA.
+ *
+ * Zero install required, zero damage to the user's environment: the fixture
+ * is copied to a temp directory, git-initialized there, and cleaned up on exit.
+ *
+ * Why this exists: per SURFACE-AUDIT v0.21 plan, the #2 friction point for
+ * adoption was "no demo path — devs have to install, init, write docs, run
+ * guard just to see what we do." This command compresses that to 30 seconds.
+ */
+
+import { mkdtempSync, rmSync, cpSync, existsSync, writeFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { c } from '../shared.mjs';
+import { runGuardInternal, classifyResult } from './guard.mjs';
+import { runScoreInternal } from './score.mjs';
+import { loadConfig } from '../docguard.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const FIXTURE_SRC = resolve(__dirname, '../../templates/demo-fixture');
+
+/**
+ * Each warning pattern gets a 1-2 line "real-world impact" gloss. Keyed by
+ * a regex on the warning text; the first match wins. Falls back to the
+ * generic gloss for unrecognized warnings (so this dictionary stays
+ * resilient as validators evolve).
+ *
+ * The point: turn validator-speak ("Missing 'Setup Steps' section") into
+ * adopter-speak ("New devs spend an hour figuring out how to run this").
+ */
+const IMPACT_GLOSS = [
+  {
+    re: /env var.*not documented|missing.*Environment Variables/i,
+    impact: 'New devs hit cryptic "X is undefined" runtime errors at boot. CI bypasses the missing var entirely.',
+  },
+  {
+    re: /[Aa]rchitecture|service.*not (in|mentioned)|not in [Aa]rchitecture/,
+    impact: 'Your AI agent reads the architecture doc and gives wrong answers about how the system works.',
+  },
+  {
+    re: /missing.*Usage|missing.*License|README/,
+    impact: 'First-time visitors bounce. The README is the storefront — empty sections = lost trust.',
+  },
+  {
+    re: /endpoint|route|API-REFERENCE/i,
+    impact: 'Clients call a documented endpoint that no longer exists, or worse — miss a new endpoint entirely.',
+  },
+  {
+    re: /Test-Spec|test.*directory|test files/,
+    impact: 'Your TEST-SPEC doesn\'t reflect reality. New tests get written in the wrong place.',
+  },
+  {
+    re: /Unreleased.*section|Changelog/,
+    impact: 'Release automation can\'t auto-detect what\'s pending. Versioning becomes manual guesswork.',
+  },
+  {
+    re: /Spec.?Kit/i,
+    impact: 'Specs aren\'t structured for AI agents to use. You miss the multiplier on spec-driven development.',
+  },
+  {
+    re: /Config file.*not mentioned/,
+    impact: 'Devs see an unknown config file and don\'t know if it\'s safe to delete or required.',
+  },
+  {
+    re: /unlinked doc|not in your requiredFiles/,
+    impact: 'Doc lives in canonical/ but isn\'t in the manifest — guard skips it, drift accumulates silently.',
+  },
+];
+
+function getImpact(warning) {
+  for (const { re, impact } of IMPACT_GLOSS) {
+    if (re.test(warning)) return impact;
+  }
+  return null;
+}
+
+/**
+ * Set up a temp copy of the fixture, git-init it, return the path.
+ */
+function setupFixture() {
+  const dir = mkdtempSync(join(tmpdir(), 'docguard-demo-'));
+  cpSync(FIXTURE_SRC, dir, { recursive: true });
+  // Initialize git so any history-aware validators (Freshness, Drift-Comments)
+  // can run without erroring. Identity is set locally so commit succeeds on
+  // CI runners that have no global git identity.
+  const opts = { cwd: dir, stdio: 'ignore' };
+  spawnSync('git', ['init', '-q', '-b', 'main'], opts);
+  spawnSync('git', ['config', 'user.email', 'demo@docguard.dev'], opts);
+  spawnSync('git', ['config', 'user.name', 'docguard-demo'], opts);
+  spawnSync('git', ['add', '-A'], opts);
+  spawnSync('git', ['commit', '-q', '-m', 'fixture'], opts);
+  return dir;
+}
+
+/**
+ * Pretty-print a curated guard run.
+ */
+function presentResults(guardData, scoreData) {
+  const allWarnings = [];
+  for (const v of guardData.validators) {
+    for (const w of (v.warnings || [])) {
+      allWarnings.push({ validator: v.name, message: w, severity: v.severity });
+    }
+  }
+
+  console.log(`\n${c.bold}🔍 What DocGuard found in your fixture:${c.reset}`);
+  console.log(`${c.dim}   Validators run: ${guardData.validators.length}   ·   Warnings: ${allWarnings.length}   ·   Time: ~0.5s${c.reset}\n`);
+
+  // Pick up to 5 warnings showing VARIETY across validators (not 5 from the
+  // same one). Dedupe by validator name; within each validator group, pick
+  // the highest-severity warning. Then rank the picks by severity.
+  const sev = { high: 0, medium: 1, low: 2 };
+  const byValidator = new Map();
+  for (const w of allWarnings) {
+    const prev = byValidator.get(w.validator);
+    if (!prev || (sev[w.severity] ?? 1) < (sev[prev.severity] ?? 1)) {
+      byValidator.set(w.validator, w);
+    }
+  }
+  const ranked = [...byValidator.values()].sort((a, b) => {
+    return (sev[a.severity] ?? 1) - (sev[b.severity] ?? 1);
+  });
+  const top = ranked.slice(0, 5);
+
+  for (let i = 0; i < top.length; i++) {
+    const w = top[i];
+    const sev = w.severity === 'high' ? `${c.red}[HIGH]${c.reset}`
+              : w.severity === 'low'  ? `${c.dim}[LOW]${c.reset}`
+              : `${c.yellow}[MED]${c.reset}`;
+    console.log(`   ${c.bold}${i + 1}.${c.reset} ${sev} ${c.cyan}${w.validator}${c.reset}`);
+    console.log(`      ${c.dim}${w.message}${c.reset}`);
+    const impact = getImpact(w.message);
+    if (impact) {
+      console.log(`      ${c.green}→${c.reset} ${impact}`);
+    }
+    console.log('');
+  }
+
+  if (allWarnings.length > top.length) {
+    console.log(`   ${c.dim}... and ${allWarnings.length - top.length} more. Run \`docguard guard\` in your repo to see everything.${c.reset}\n`);
+  }
+
+  // Score line
+  if (scoreData && typeof scoreData.score === 'number') {
+    const grade = scoreData.score >= 90 ? 'A' : scoreData.score >= 80 ? 'B' : scoreData.score >= 70 ? 'C' : scoreData.score >= 60 ? 'D' : 'F';
+    const color = scoreData.score >= 80 ? c.green : scoreData.score >= 60 ? c.yellow : c.red;
+    console.log(`${c.bold}📊 CDD Maturity Score:${c.reset} ${color}${scoreData.score}/100 (${grade})${c.reset}`);
+    console.log(`${c.dim}   ↑ This is the fixture's score. Yours will hopefully be higher.${c.reset}\n`);
+  }
+}
+
+function printCTA() {
+  console.log(`${c.bold}🛠️  Fixing drift like this:${c.reset}`);
+  console.log(`   ${c.cyan}docguard fix --write${c.reset}      ${c.dim}— patches the mechanical stuff (version refs, counts, anchors)${c.reset}`);
+  console.log(`   ${c.cyan}docguard sync --write${c.reset}     ${c.dim}— refreshes code-truth sections to match the codebase${c.reset}`);
+  console.log(`   ${c.cyan}docguard diagnose${c.reset}         ${c.dim}— generates an AI prompt for the prose drift (Claude/GPT/Cursor)${c.reset}\n`);
+
+  console.log(`${c.bold}🚀 Try it on YOUR project:${c.reset}`);
+  console.log(`   ${c.green}npm install -g docguard-cli${c.reset}`);
+  console.log(`   ${c.green}cd your-project${c.reset}`);
+  console.log(`   ${c.green}docguard init${c.reset}              ${c.dim}— scans existing code and proposes canonical docs${c.reset}`);
+  console.log(`   ${c.green}docguard guard${c.reset}             ${c.dim}— see what we catch${c.reset}\n`);
+
+  console.log(`${c.dim}Or stay zero-install:${c.reset}`);
+  console.log(`   ${c.green}npx docguard-cli init${c.reset}`);
+  console.log(`   ${c.green}npx docguard-cli guard${c.reset}\n`);
+
+  console.log(`${c.bold}📚 Learn more:${c.reset} ${c.cyan}https://github.com/raccioly/docguard${c.reset}`);
+}
+
+/**
+ * Public entry point — `docguard demo`.
+ *
+ * @param {string} _projectDir — ignored; demo uses its own temp fixture
+ * @param {object} _config — ignored
+ * @param {object} flags — supports --quiet (skip banner) and --keep (don't cleanup fixture)
+ */
+export function runDemo(_projectDir, _config, flags = {}) {
+  if (!flags.quiet) {
+    console.log(`\n${c.bold}🎬 DocGuard Demo${c.reset} ${c.dim}— see what we catch in 30 seconds${c.reset}`);
+    console.log(`${c.dim}   No install. No setup. We're running against a sample 4-service payments API${c.reset}`);
+    console.log(`${c.dim}   with intentional drift between code and docs.${c.reset}\n`);
+  }
+
+  if (!existsSync(FIXTURE_SRC)) {
+    console.error(`${c.red}Demo fixture not found at ${FIXTURE_SRC}.${c.reset}`);
+    console.error(`${c.dim}If this is a packaging bug, please file an issue.${c.reset}`);
+    process.exit(1);
+  }
+
+  let fixture;
+  try {
+    fixture = setupFixture();
+    if (!flags.quiet) console.log(`${c.dim}   Fixture ready at ${fixture}${c.reset}\n`);
+  } catch (err) {
+    if (fixture) rmSync(fixture, { recursive: true, force: true });
+    console.error(`${c.red}Failed to set up demo fixture: ${err.message}${c.reset}`);
+    process.exit(1);
+  }
+
+  // Run guard + score against the fixture
+  let guardData, scoreData;
+  try {
+    // Load full config (defaults + fixture's .docguard.json) — same path the
+    // real `docguard guard` uses. The fixture ships its own .docguard.json
+    // so this hydrates the right project name + profile.
+    const config = loadConfig(fixture);
+    guardData = runGuardInternal(fixture, config);
+    scoreData = runScoreInternal(fixture, config);
+  } catch (err) {
+    rmSync(fixture, { recursive: true, force: true });
+    console.error(`${c.red}Demo guard run failed: ${err.message}${c.reset}`);
+    process.exit(1);
+  }
+
+  presentResults(guardData, scoreData);
+  printCTA();
+
+  // Cleanup unless --keep
+  if (!flags.keep) {
+    rmSync(fixture, { recursive: true, force: true });
+    if (!flags.quiet) console.log(`${c.dim}   Fixture cleaned up.${c.reset}`);
+  } else {
+    console.log(`${c.dim}   Fixture kept at ${fixture} (--keep)${c.reset}`);
+  }
+
+  // Always exit 0 — the demo is informational, never a failure
+  process.exit(0);
+}

package/cli/commands/guard.mjs

@@ -139,7 +139,8 @@ import { validateCrossReferences } from '../validators/cross-reference.mjs';
 import { validateGeneratedStaleness } from '../validators/generated-staleness.mjs';
 import { validateTodoTracking } from '../validators/todo-tracking.mjs';
 import { validateSchemaSync } from '../validators/schema-sync.mjs';
-import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
+import { validateSpecKitIntegration } from '../validators/spec-kit.mjs';
+import { validateCanonicalSync } from '../validators/canonical-sync.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -237,6 +238,22 @@ export function runGuardInternal(projectDir, config) {
     }
   }
 
+  // ── Canonical-Sync runs AFTER main loop, BEFORE metrics-consistency.
+  //    Needs the live validator results to count "real" validators that ran.
+  //    (Pre-canonical-sync ordering — comes before metrics-consistency so the
+  //    metrics validator sees a stable surface count.)
+  if (validators.canonicalSync !== false) {
+    const start = performance.now();
+    try {
+      const result = validateCanonicalSync(projectDir, config, results);
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ ...result, name: 'Canonical-Sync', key: 'canonicalSync', durationMs, ...classifyResult(result) });
+    } catch (err) {
+      const durationMs = Math.round((performance.now() - start) * 100) / 100;
+      results.push({ name: 'Canonical-Sync', key: 'canonicalSync', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
+    }
+  }
+
   // ── Metrics-Consistency runs AFTER all other validators (needs their results) ──
   if (validators.metricsConsistency !== false) {
     const start = performance.now();
@@ -317,7 +334,8 @@ function liteValidatorsConfig() {
     'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
     'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
     'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
-    'schemaSync', 'specKit', 'crossReference', 'generatedStaleness', 'metricsConsistency',
+    'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
+    'canonicalSync', 'metricsConsistency',
   ];
   const out = {};
   for (const k of all) out[k] = CHANGED_ONLY_VALIDATORS.includes(k);

package/cli/commands/init.mjs

@@ -17,6 +17,45 @@ import { execSync } from 'node:child_process';
 import { c, PROFILES } from '../shared.mjs';
 import { ensureSkills, detectAgentMode, detectAIAgent, isSpecKitAvailable, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
 
+// v0.20: scaffolder names that can be passed via `init --with <name>` and
+// dispatched to the corresponding standalone runner. Each name maps to its
+// canonical command module. Keep in sync with cli/docguard.mjs router.
+const SCAFFOLDER_DISPATCH = {
+  agents:  async (dir, cfg, flags) => (await import('./agents.mjs')).runAgents(dir, cfg, flags),
+  hooks:   async (dir, cfg, flags) => (await import('./hooks.mjs')).runHooks(dir, cfg, flags),
+  ci:      async (dir, cfg, flags) => (await import('./ci.mjs')).runCI(dir, cfg, flags),
+  badge:   async (dir, cfg, flags) => (await import('./badge.mjs')).runBadge(dir, cfg, flags),
+  llms:    async (dir, cfg, flags) => (await import('./llms.mjs')).runLlms(dir, cfg, flags),
+  publish: async (dir, cfg, flags) => (await import('./publish.mjs')).runPublish(dir, cfg, flags),
+};
+
+/**
+ * Run one or more scaffolders after init has completed.
+ * Called when `docguard init --with agents,hooks,ci` is invoked.
+ * Each scaffolder runs in sequence; if one throws, the rest are skipped
+ * (matches the standalone command's failure semantics).
+ */
+async function runScaffolders(projectDir, config, flags, names) {
+  const unknown = names.filter(n => !SCAFFOLDER_DISPATCH[n]);
+  if (unknown.length > 0) {
+    console.error(`${c.red}Unknown --with target(s): ${unknown.join(', ')}${c.reset}`);
+    console.log(`${c.dim}Valid: ${Object.keys(SCAFFOLDER_DISPATCH).join(', ')}${c.reset}`);
+    process.exit(1);
+  }
+
+  console.log(`\n${c.bold}🧰 Scaffolders:${c.reset} ${c.cyan}${names.join(', ')}${c.reset}\n`);
+
+  for (const name of names) {
+    console.log(`${c.dim}── ${name} ───────────────────────────────────────${c.reset}`);
+    try {
+      await SCAFFOLDER_DISPATCH[name](projectDir, config, flags);
+    } catch (err) {
+      console.error(`${c.red}✗ ${name} failed: ${err.message}${c.reset}`);
+      process.exit(1);
+    }
+  }
+}
+
 function detectProjectType(dir) {
   const pkgPath = resolve(dir, 'package.json');
   if (existsSync(pkgPath)) {
@@ -53,7 +92,83 @@ function askQuestion(prompt) {
 
 // ── Init Command ─────────────────────────────────────────────────────────
 
+/**
+ * v0.21 — Smart first-run detection.
+ *
+ * Heuristic: if the user is running `docguard init` against a project that
+ * already has substantial source code (cli/, src/, lib/, app/, or 10+ source
+ * files at depth 1-2) AND has no docs-canonical/ yet, switch from the
+ * skeleton-first path to the "scan and propose" path — i.e. dispatch to
+ * `docguard generate --plan` which reverse-engineers canonical docs from
+ * existing code.
+ *
+ * Rationale: blank skeletons feel useless for existing projects (the dev
+ * has to write everything from scratch). The scan path delivers immediate
+ * value: "here's what your project actually does, mapped to canonical doc
+ * shape." That's a 30-second wow for the 80% of adopters who arrive with
+ * an existing codebase.
+ *
+ * Opt out: `docguard init --skeleton` forces the blank-template path
+ * (preserves the v0.20 behavior for greenfield projects and CI flows).
+ *
+ * @returns {boolean} true if smart-detection fired and dispatched
+ */
+function shouldRunGenerate(projectDir, flags) {
+  if (flags.skeleton)        return false; // explicit opt-out
+  if (flags.skipPrompts)     return false; // non-interactive (CI) keeps deterministic skeleton path
+  if (flags.wizard)          return false; // wizard has its own scan step
+  if (flags.profile)         return false; // explicit profile = user knows what they want
+
+  // If canonical docs already exist, this is a re-init, not a first-run.
+  const canonicalDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonicalDir)) {
+    try {
+      const entries = readdirSync(canonicalDir).filter(f => f.endsWith('.md'));
+      if (entries.length > 0) return false;
+    } catch { /* fall through */ }
+  }
+
+  // Existing-code signals: any of cli/, src/, lib/, app/ as a directory.
+  const codeDirs = ['cli', 'src', 'lib', 'app'];
+  for (const d of codeDirs) {
+    if (existsSync(resolve(projectDir, d))) return true;
+  }
+
+  // Fallback: count source files at top level (Python / Rust / Go projects
+  // often don't use src/ — files live at the root).
+  try {
+    const exts = ['.py', '.rs', '.go', '.java', '.rb', '.ts', '.tsx', '.mjs', '.js'];
+    const topLevel = readdirSync(projectDir).filter(f => {
+      return exts.some(e => f.endsWith(e));
+    });
+    if (topLevel.length >= 10) return true;
+  } catch { /* fall through */ }
+
+  return false;
+}
+
 export async function runInit(projectDir, config, flags) {
+  // v0.20: `--wizard` dispatches to the full interactive onboarding (formerly
+  // `docguard setup`). Done before profile validation so the wizard can ask
+  // for the profile itself if needed.
+  if (flags.wizard) {
+    const { runSetup } = await import('./setup.mjs');
+    return runSetup(projectDir, config, flags);
+  }
+
+  // v0.21: smart first-run — for existing projects without canonical docs,
+  // dispatch to `generate --plan` (the "scan and propose" path). Opt out
+  // with --skeleton or by setting --profile/--skip-prompts/--wizard explicitly.
+  if (shouldRunGenerate(projectDir, flags)) {
+    console.log(`${c.bold}🔍 DocGuard Init — Smart Mode${c.reset}`);
+    console.log(`${c.dim}   Detected existing project with code but no canonical docs.${c.reset}`);
+    console.log(`${c.dim}   Switching to "scan and propose" mode — DocGuard will reverse-engineer${c.reset}`);
+    console.log(`${c.dim}   canonical docs from your code instead of dumping a blank skeleton.${c.reset}`);
+    console.log(`${c.dim}   (Opt out: ${c.cyan}docguard init --skeleton${c.dim} for the blank-template path.)${c.reset}\n`);
+    const { runGenerate } = await import('./generate.mjs');
+    return runGenerate(projectDir, config, { ...flags, plan: true });
+  }
+
   const profileName = flags.profile || 'standard';
   const profile = PROFILES[profileName];
 
@@ -369,4 +484,11 @@ poetry.lock
 
   // Auto-install DocGuard skills and commands (spec-kit skills handled by specify init)
   ensureSkills(projectDir, flags);
+
+  // v0.20: `docguard init --with agents,hooks,ci,badge,llms,publish` runs
+  // the named scaffolders after init has finished. Each one runs in sequence
+  // and uses the same flags object (so --force / --skip-prompts propagate).
+  if (Array.isArray(flags.with) && flags.with.length > 0) {
+    await runScaffolders(projectDir, config, flags, flags.with);
+  }
 }