docguard-cli 0.20.0__tar.gz → 0.21.1__tar.gz

{docguard_cli-0.20.0/extensions/spec-kit-docguard → docguard_cli-0.21.1/.agent}/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.20.0
+  version: 0.21.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.1 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.20.0/extensions/spec-kit-docguard → docguard_cli-0.21.1/.agent}/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.20.0
+  version: 0.21.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.1 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.20.0/extensions/spec-kit-docguard → docguard_cli-0.21.1/.agent}/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.20.0
+  version: 0.21.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.1 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.20.0 → docguard_cli-0.21.1}/.agent/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.20.0
+  version: 0.21.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.1 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.20.0 → docguard_cli-0.21.1}/.agent/skills/docguard-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.20.0
+  version: 0.21.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.20.0 → docguard_cli-0.21.1}/.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
         with:
           fetch-depth: 0 # Full git history for freshness validator
 
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
 
@@ -82,7 +82,7 @@ jobs:
     needs: test
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'

{docguard_cli-0.20.0 → docguard_cli-0.21.1}/.github/workflows/release.yml

@@ -52,7 +52,7 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
       - name: Run Tests
@@ -151,7 +151,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'
@@ -167,7 +167,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 

{docguard_cli-0.20.0 → docguard_cli-0.21.1}/CHANGELOG.md

@@ -7,6 +7,140 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.1] - 2026-05-26
+
+**Security patch — closes issue #190.** Command injection vulnerability in
+`docguard init` via the `ai` field of `.specify/init-options.json` is fixed.
+
+### Security
+
+- **Issue #190: command injection in `cli/commands/init.mjs` and
+  `cli/ensure-skills.mjs`.** The `detectAIAgent()` helper returned the
+  `ai` field from `.specify/init-options.json` without validation, and
+  that value was then shell-interpolated into an `execSync` invocation:
+  ```js
+  const aiFlag = `--ai ${detectedAgent}`;
+  execSync(`specify init ... ${aiFlag} ...`);
+  ```
+  A local attacker with file-system write access to a victim's repo
+  could plant `{"ai": "claude; touch /tmp/pwned;"}` and trigger
+  arbitrary command execution on the victim's next `docguard init`.
+
+  **Severity:** Medium (requires local file-system access; pre-fix
+  `detectAIAgent` consumed configs from any project DocGuard ran in).
+
+  **Discovered:** 23 duplicate auto-generated draft PRs from the
+  "Sentinel" AI agent flagged this during the v0.19 cleanup sweep.
+  The drafts were closed as noise but the underlying finding was
+  tracked in #190 — fixed properly here.
+
+  **Fix (two layers, defense in depth):**
+  1. `getDetectedAgent()` now allowlist-validates the `ai` field against
+     `/^[a-zA-Z0-9_-]{1,32}$/`. Anything else (shell metacharacters,
+     non-strings, oversized values) returns `null`.
+  2. New `safeSpawnSpecify(args, opts)` helper uses `execFileSync` with
+     args passed as an array — no shell interpolation possible. Both
+     unsafe call sites (`init.mjs` and `ensure-skills.mjs`) now use
+     this helper. Cross-platform (POSIX direct exec / Windows
+     `cmd.exe /c specify.cmd`).
+
+### Tests
+
+- 596 → **610** (+14): `tests/security-init-injection.test.mjs` pins
+  both defense layers. Tests every shell metacharacter (`;`, backtick,
+  `$()`, `|`, `&&`, newline), oversized values, non-string types,
+  malformed JSON, missing config files. Asserts the legitimate
+  allowlist (claude, cursor-agent, gemini, agy, copilot, windsurf,
+  codex, roo, amp, kiro-cli, tabnine, underscore-bearing future names).
+
+### Audit
+
+`grep -rn execSync cli/` was re-run; remaining call sites are all
+hardcoded literals (no attacker-influenced interpolation): freshness
+git probes, score's git probe, setup/doc-quality `which`-style
+detection. Documented in commit message.
+
+## [0.21.0] - 2026-05-26
+
+**Time-to-value.** The funnel-unblocker release. Until v0.21, a dev shopping
+for documentation tools had to install DocGuard, run `init`, write some
+canonical docs, and only then could they see what the tool actually does.
+v0.21 compresses that to **30 seconds, zero install**:
+
+```bash
+npx docguard-cli demo
+```
+
+Plus: `docguard init` now auto-detects existing projects and switches to
+"scan and propose" mode (reverse-engineering canonical docs from your code)
+instead of dumping a blank skeleton. The blank-skeleton path is still one
+flag away (`--skeleton`).
+
+### Added
+
+- **`docguard demo`** — the marquee feature of this release. Copies a baked-in
+  fixture (`templates/demo-fixture/` — a 4-service payments API with
+  intentional drift) to a temp directory, git-inits it, runs guard + score
+  against it, then prints a **curated narrative**: top-5 findings spanning
+  multiple validators, each annotated with the real-world impact ("Your AI
+  agent reads the architecture doc and gives wrong answers about how the
+  system works"), the CDD maturity score, and a clear three-line CTA showing
+  both `npm install -g` and `npx` paths. Temp fixture is cleaned up on exit
+  (or kept via `--keep` for inspection). Total time: ~0.5s for the guard
+  run; total experience: ~30s from `npx` to the install CTA.
+- **`templates/demo-fixture/`** — ships with the package (already in
+  `files: ["templates/"]`). 12-file pretend "acme-payments" project with
+  drift across 7 validator categories: undocumented 4th service, missing
+  API endpoint in reference, env var drift between `.env.example` and
+  `ENVIRONMENT.md`, `CHANGELOG` missing `[Unreleased]`, README sections
+  per Standard README spec missing, etc.
+- **`docguard init --skeleton`** — explicit opt-in to the v0.20 blank-template
+  behavior. For greenfield projects where the scan would find nothing.
+- **`docguard demo --keep`** — preserves the temp fixture and reports its
+  path. Useful for poking around what a real-world DocGuard-managed project
+  looks like.
+
+### Changed
+
+- **Smart `docguard init` first-run.** When `init` runs in a directory that
+  has existing source code (`cli/`, `src/`, `lib/`, `app/`, or 10+ source
+  files at top level) AND no `docs-canonical/`, it automatically dispatches
+  to `runGenerate` with `--plan` — the "scan and propose" path. Heuristic
+  opts out for: `--skeleton`, `--wizard`, `--skip-prompts` (CI), explicit
+  `--profile`, or projects that already have canonical docs (re-init case).
+  Result: the 80% of adopters who arrive with an existing codebase get
+  immediate value from the very first command, instead of staring at a
+  blank skeleton.
+- **`--help` updates.** New top section: "First-time? Try the demo (no
+  install, no setup): `npx docguard-cli demo`". `demo` listed in Tools.
+  `init` description updated to mention the new auto-detect behavior and
+  the `--skeleton` opt-out.
+- **README.** New CTA block at the top under the H1, above the Table of
+  Contents: prominent `npx docguard-cli demo` callout drives the funnel.
+  Validator/command counts updated by `canonical-sync` to 14 commands.
+
+### Tests
+
+- 582 → **596 tests** (+14):
+  - `tests/demo-command.test.mjs` (6): demo exits 0; output contains banner
+    + findings + score + CTA; `--quiet` suppresses banner; temp fixture is
+    cleaned up by default; `--keep` preserves it; top-5 findings span 3+
+    distinct validators (variety, not noise).
+  - `tests/init-smart-detection.test.mjs` (8): empty dir → skeleton; dir
+    with `src/` → smart mode; dir with `cli/` → smart mode; `--skeleton`
+    forces skeleton even with code present; `--skip-prompts` keeps skeleton
+    (CI determinism); pre-existing canonical docs skip smart mode; 10+
+    top-level Python files trigger smart mode; <10 + no code dir → skeleton.
+
+### Strategic context
+
+This is item #2 from the v0.19 SURFACE-AUDIT's adoption-friction analysis
+("no demo path — devs have to install, init, write docs, run guard just to
+see what we do"). v0.20 closed friction #1 (surface sprawl); v0.21 closes
+#2 (time-to-value). Next up per the 5-release arc: v0.22 — AI-native fix
+loop (`docguard fix --apply` calls Claude/Codex and opens a PR with the
+fix end-to-end).
+
 ## [0.20.0] - 2026-05-26
 
 **Consolidation.** 21 user-facing commands become 13. The promise from

{docguard_cli-0.20.0 → docguard_cli-0.21.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.20.0
+Version: 0.21.1
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme
@@ -36,6 +36,14 @@ Description-Content-Type: text/markdown
 
 ---
 
+> **✨ 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)
@@ -75,7 +83,7 @@ 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 (13)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (14)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
@@ -259,7 +267,7 @@ This installs DocGuard's slash commands (`/docguard.guard`, `/docguard.review`,
 
 ## Usage
 
-DocGuard ships **13 commands** (the "Daily 5" + 8 situational tools). 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).
+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:
 

{docguard_cli-0.20.0 → docguard_cli-0.21.1}/README.md

@@ -12,6 +12,14 @@
 
 ---
 
+> **✨ 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)
@@ -51,7 +59,7 @@ 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 (13)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (14)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
@@ -235,7 +243,7 @@ This installs DocGuard's slash commands (`/docguard.guard`, `/docguard.review`,
 
 ## Usage
 
-DocGuard ships **13 commands** (the "Daily 5" + 8 situational tools). 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).
+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:
 

{docguard_cli-0.20.0 → docguard_cli-0.21.1}/action.yml

@@ -77,7 +77,7 @@ runs:
   using: 'composite'
   steps:
     - name: Setup Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v6
       with:
         node-version: ${{ inputs.node-version }}
 
@@ -247,7 +247,7 @@ runs:
 
     - name: Post Fix Summary to PR Comment
       if: (inputs.command == 'fix' || inputs.command == 'sync') && inputs.comment-on-pr == 'true' && github.event_name == 'pull_request'
-      uses: actions/github-script@v7
+      uses: actions/github-script@v9
       with:
         script: |
           const count = parseInt('${{ steps.fix.outputs.fixes-applied }}' || '0', 10);
@@ -288,7 +288,7 @@ runs:
 
     - name: Post Score to PR Comment
       if: inputs.command == 'score' && github.event_name == 'pull_request'
-      uses: actions/github-script@v7
+      uses: actions/github-script@v9
       with:
         script: |
           const score = '${{ steps.run.outputs.score }}' || '?';

docguard_cli-0.21.1/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);
+}