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

{docguard_cli-0.20.0/extensions/spec-kit-docguard → docguard_cli-0.21.0/.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.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.20.0/extensions/spec-kit-docguard → docguard_cli-0.21.0/.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.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.20.0/extensions/spec-kit-docguard → docguard_cli-0.21.0/.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.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.20.0 → docguard_cli-0.21.0}/.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.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.20.0 → docguard_cli-0.21.0}/.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.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.20.0 → docguard_cli-0.21.0}/.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.0}/.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.0}/CHANGELOG.md

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.20.0
+Version: 0.21.0
 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.0}/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.0}/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.0/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);
+}

{docguard_cli-0.20.0 → docguard_cli-0.21.0}/cli/commands/init.mjs

@@ -92,6 +92,61 @@ 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
@@ -101,6 +156,19 @@ export async function runInit(projectDir, config, flags) {
     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];