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

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

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

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

{docguard_cli-0.21.1 → docguard_cli-0.22.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.21.1
+  version: 0.22.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.21.1 → docguard_cli-0.22.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.21.1
+  version: 0.22.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.21.1 → docguard_cli-0.22.0}/.docguard.json

@@ -40,5 +40,40 @@
     "environment": true,
     "freshness": true
   },
-  "severity": {}
+  "severity": {},
+  "surfaceSync": {
+    "surfaces": [
+      {
+        "name": "commands",
+        "glob": "cli/commands/*.mjs",
+        "extract": "basename-no-ext",
+        "ignore": [
+          "agents", "hooks", "ci", "badge", "llms", "publish",
+          "setup", "impact"
+        ],
+        "docs": ["README.md"],
+        "section": "Usage"
+      },
+      {
+        "name": "validators",
+        "glob": "cli/validators/*.mjs",
+        "extract": "basename-no-ext",
+        "ignore": [
+          "drift",
+          "doc",
+          "doc-sections",
+          "drift-comments"
+        ],
+        "docs": ["README.md"],
+        "section": "Validators"
+      },
+      {
+        "name": "slash-commands",
+        "glob": "templates/commands/*.md",
+        "extract": "basename-no-ext",
+        "docs": ["README.md"],
+        "section": "Slash Commands"
+      }
+    ]
+  }
 }

docguard_cli-0.22.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      all-npm:
+        patterns: ["*"]
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      all-pip:
+        patterns: ["*"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      all-actions:
+        patterns: ["*"]

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

@@ -15,7 +15,7 @@ jobs:
         node-version: [18, 20, 22]
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # Full git history for freshness validator
 
@@ -81,7 +81,7 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v')
     needs: test
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version: 20

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

@@ -19,7 +19,7 @@ jobs:
       version: ${{ steps.check.outputs.version }}
       changed: ${{ steps.check.outputs.changed }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 2 # Need previous commit to compare
 
@@ -49,7 +49,7 @@ jobs:
       matrix:
         node-version: [18, 20, 22]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - uses: actions/setup-node@v6
@@ -68,7 +68,7 @@ jobs:
     outputs:
       tag: v${{ needs.detect-version.outputs.version }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # Fetch all history + tags for reliable tag detection
 
@@ -125,7 +125,7 @@ jobs:
     needs: [detect-version, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Build extension ZIP
         run: |
@@ -150,7 +150,7 @@ jobs:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version: 20
@@ -166,7 +166,7 @@ jobs:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
@@ -189,3 +189,139 @@ jobs:
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+
+  # ── Step 7: Sync Spec Kit community catalog ────────────────────────────
+  # Inlined here (rather than triggered via workflow_run from a sibling
+  # workflow) because workflow_run-triggered jobs get 401 on the
+  # `gh repo sync … --source github/spec-kit` API call even with a valid
+  # PAT in secrets. Same-workflow secret access is consistent — fixes the
+  # auto-sync that was failing on every release since the workflow_run
+  # auth quirk surfaced.
+  sync-catalog:
+    needs: [detect-version, build-extension, publish-npm, publish-pypi]
+    if: needs.detect-version.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout docguard repo
+        uses: actions/checkout@v6
+
+      - name: Get version and metadata
+        id: meta
+        run: |
+          VERSION="${{ needs.detect-version.outputs.version }}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "download_url=https://github.com/raccioly/docguard/releases/download/v${VERSION}/spec-kit-docguard-v${VERSION}.zip" >> "$GITHUB_OUTPUT"
+          echo "updated_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$GITHUB_OUTPUT"
+          echo "✅ Version: $VERSION"
+
+      - name: Extract release notes from CHANGELOG
+        id: notes
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          NOTES=$(awk "/^## \\[${VERSION}\\]/{found=1; next} /^## \\[/{if(found) exit} found{print}" CHANGELOG.md)
+          if [ -z "$NOTES" ]; then
+            NOTES="Updated to v${VERSION}. See [CHANGELOG](https://github.com/raccioly/docguard/blob/main/CHANGELOG.md) for details."
+          fi
+          echo "$NOTES" > /tmp/changelog-section.md
+          echo "✅ Release notes extracted ($(wc -l < /tmp/changelog-section.md) lines)"
+
+      - name: Sync fork with upstream
+        env:
+          GH_TOKEN: ${{ secrets.SPECKIT_PR_TOKEN }}
+        run: |
+          gh repo sync raccioly/spec-kit --source github/spec-kit --branch main --force
+          echo "✅ Fork synced with upstream"
+
+      - name: Checkout spec-kit fork (fresh after sync)
+        uses: actions/checkout@v6
+        with:
+          repository: raccioly/spec-kit
+          token: ${{ secrets.SPECKIT_PR_TOKEN }}
+          path: spec-kit-fork
+          ref: main
+
+      - name: Update catalog.community.json
+        working-directory: spec-kit-fork
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          DOWNLOAD_URL="${{ steps.meta.outputs.download_url }}"
+          UPDATED_AT="${{ steps.meta.outputs.updated_at }}"
+          cp ${{ github.workspace }}/.github/scripts/patch-catalog.py /tmp/patch-catalog.py
+          python3 /tmp/patch-catalog.py "$VERSION" "$DOWNLOAD_URL" "$UPDATED_AT"
+
+      - name: Create or update branch
+        working-directory: spec-kit-fork
+        run: |
+          BRANCH="update-docguard"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -B "$BRANCH"
+          git add extensions/catalog.community.json extensions/README.md
+          git commit -m "chore: update DocGuard extension to v${{ steps.meta.outputs.version }}" || echo "No changes to commit"
+          git push --force origin "$BRANCH"
+          echo "✅ Branch $BRANCH pushed"
+
+      - name: Create or update PR
+        working-directory: spec-kit-fork
+        env:
+          GH_TOKEN: ${{ secrets.SPECKIT_PR_TOKEN }}
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          BRANCH="update-docguard"
+          PR_TITLE="chore: update DocGuard extension to v${VERSION}"
+
+          cat > /tmp/pr-body.md << 'HEADER'
+          ## DocGuard Community Extension Update
+
+          Updates the DocGuard community extension catalog entry.
+
+          ### Changes
+          HEADER
+
+          echo "- Version: **v${VERSION}**" >> /tmp/pr-body.md
+          echo "- Download: \`spec-kit-docguard-v${VERSION}.zip\`" >> /tmp/pr-body.md
+          echo "- Repository: https://github.com/raccioly/docguard" >> /tmp/pr-body.md
+          echo "" >> /tmp/pr-body.md
+          echo "### Release Notes" >> /tmp/pr-body.md
+          echo "" >> /tmp/pr-body.md
+          cat /tmp/changelog-section.md >> /tmp/pr-body.md
+          echo "" >> /tmp/pr-body.md
+          echo "---" >> /tmp/pr-body.md
+          echo "*This PR was automatically generated by the DocGuard release pipeline.*" >> /tmp/pr-body.md
+
+          EXISTING_PR=$(gh pr list \
+            --repo github/spec-kit \
+            --head "raccioly:${BRANCH}" \
+            --state open \
+            --json number \
+            --jq '.[0].number' 2>/dev/null || echo "")
+
+          if [ -z "$EXISTING_PR" ] || [ "$EXISTING_PR" = "null" ]; then
+            EXISTING_PR=$(gh pr list \
+              --repo github/spec-kit \
+              --state open \
+              --search "head:raccioly:${BRANCH}" \
+              --json number \
+              --jq '.[0].number' 2>/dev/null || echo "")
+          fi
+
+          if [ -n "$EXISTING_PR" ] && [ "$EXISTING_PR" != "null" ]; then
+            echo "Found existing PR #${EXISTING_PR} — updating title and body..."
+            gh pr edit "$EXISTING_PR" \
+              --repo github/spec-kit \
+              --title "$PR_TITLE" \
+              --body-file /tmp/pr-body.md
+            echo "✅ Updated existing PR #${EXISTING_PR} to v${VERSION}"
+          else
+            PR_URL=$(gh pr create \
+              --repo github/spec-kit \
+              --head "raccioly:${BRANCH}" \
+              --base main \
+              --title "$PR_TITLE" \
+              --body-file /tmp/pr-body.md 2>&1) && {
+              echo "✅ Created new PR: $PR_URL"
+            } || {
+              echo "⚠️ Could not create or find PR — branch was force-pushed with v${VERSION} content"
+            }
+          fi

{docguard_cli-0.21.1 → docguard_cli-0.22.0}/.github/workflows/sync-speckit-catalog.yml

@@ -1,11 +1,16 @@
-name: Sync DocGuard to Spec Kit Community Catalog
-
-# Triggers after the release workflow completes, or manually
+name: Sync DocGuard to Spec Kit Community Catalog (Manual)
+
+# Manual recovery only. The automatic post-release sync now runs inside
+# release.yml itself (see the `sync-catalog` job there). This workflow
+# is kept for one-off catalog updates outside the release flow, e.g.
+# fixing a stale entry, retrying after upstream maintenance, or pushing
+# a metadata-only refresh.
+#
+# The previous workflow_run trigger was removed because it caused
+# repeatable HTTP 401s on `gh repo sync ... --source github/spec-kit`
+# despite the PAT being valid — a known GitHub Actions auth quirk for
+# cross-workflow secret usage in workflow_run contexts.
 on:
-  workflow_run:
-    workflows: ["Auto Release — Tag, GitHub Release, npm, PyPI"]
-    types: [completed]
-    branches: [main]
   workflow_dispatch:
     inputs:
       version:
@@ -19,12 +24,10 @@ permissions:
 jobs:
   sync-catalog:
     runs-on: ubuntu-latest
-    # Only run if the release workflow succeeded (or manual trigger)
-    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
 
     steps:
       - name: Checkout docguard repo
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Get version and metadata
         id: meta
@@ -71,7 +74,7 @@ jobs:
           echo "✅ Fork synced with upstream"
 
       - name: Checkout spec-kit fork (fresh after sync)
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           repository: raccioly/spec-kit
           token: ${{ secrets.SPECKIT_PR_TOKEN }}

{docguard_cli-0.21.1 → docguard_cli-0.22.0}/AGENTS.md

@@ -41,7 +41,7 @@
 | Command | Purpose |
 |---------|---------|
 | `diagnose` | **Primary** — identify issues + generate AI fix prompts |
-| `guard` | Validate project (CI gate) — 23 validators |
+| `guard` | Validate project (CI gate) — 24 validators |
 | `generate` | Reverse-engineer docs from code |
 | `fix --doc <name>` | AI prompt for specific document |
 | `score` | CDD maturity score (0-100) |

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

@@ -7,6 +7,126 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-05-28
+
+### Added — Surface-Sync validator (item-level enumerable drift)
+
+`canonical-sync` already checks NUMERIC count claims in the README (ships
+N commands, N validators, mermaid diagram counts). But running the docguard
+repo through itself showed `canonical-sync` passing 3/3 while the README's
+command table silently omitted `demo` — the count matched, the table was
+wrong, the user hit "command not found" anyway. Count-level checks miss
+item-level drift.
+
+**Surface-Sync** is the item-level complement. For each configured surface
+(commands, validators, slash commands, templates — anything enumerable), it
+compares code-truth (from a glob) against the names appearing in table rows
+and bullet items in target docs. Warns on items present in code but missing
+from the doc, and on items listed in the doc but missing from code.
+
+Key behaviors:
+
+- **N/A by default.** Returns "nothing to validate" unless the project's
+  `.docguard.json` declares at least one surface under `surfaceSync.surfaces`.
+  Existing docguard projects upgrade safely with zero new noise.
+- **Section-scoped scanning.** Each surface can specify a `section` heading;
+  the validator restricts scanning to that section so a README containing
+  both a Commands table and a Validators table doesn't produce cross-table
+  false positives.
+- **Format-aware extraction.** Recognises documented entries written as
+  `` `name` ``, `**Name**`, `| `name` |`, `| N | **Name** |`, and bullet
+  items. Strips leading `docguard ` / `/` prefixes and folds case so README's
+  `**API-Surface**` matches file basename `api-surface.mjs`.
+- **Code-block immune.** Fenced code blocks are stripped before scanning so
+  shell examples don't inflate the documented set.
+- **`ignore` list per surface.** Known deprecation aliases, scaffolders
+  behind `init --with`, and display-name-vs-filename mismatches can be
+  silenced without disabling the surface entirely.
+
+Config shape (in `.docguard.json`):
+
+```json
+{
+  "surfaceSync": {
+    "surfaces": [
+      {
+        "name": "commands",
+        "glob": "cli/commands/*.mjs",
+        "extract": "basename-no-ext",
+        "ignore": ["setup", "impact"],
+        "docs": ["README.md"],
+        "section": "Usage"
+      }
+    ]
+  }
+}
+```
+
+DocGuard's own `.docguard.json` now declares three surfaces (commands,
+validators, slash-commands) so the project polices its own README on every
+`guard` run. Run `docguard explain surfaceSync` for fix guidance.
+
+### Fixed — eight field-test bugs from v0.20.0
+
+Confirmed running v0.20.0 against two real projects (a Python codebase for
+the v0.20.0 cycle and a Next.js 15 App Router codebase). All eight were
+reproduced in the source, fixed surgically, and pinned with regression
+tests. Specs: `specs/004-v020-env-var-false-negative/`, `specs/005-hugocross-next-bugs/`.
+
+- **API-Surface emits wrong path for Next.js App Router with `src/` layout**
+  — `src/app/api/health/route.ts` was reported as `GET /app/api/health`
+  instead of `GET /api/health`. Caused the validator to fire two false
+  warnings per route (documented-missing + undocumented-in-code) on every
+  `src/app/api/` file. `cli/scanners/routes.mjs`.
+
+- **Freshness validator ignored `<!-- docguard:last-reviewed YYYY-MM-DD -->`**
+  — header was generated into every template, recommended in the freshness
+  fix text itself, checked by `score` for ALCOA+, but never read by
+  `validateFreshness`. The reviewer's explicit "I reviewed this" signal
+  had zero effect. The header now overrides the git-log fallback.
+  `cli/validators/freshness.mjs`.
+
+- **Environment-vars in pipe-table rows (no backticks) were treated as
+  undocumented** — projects using `| VAR_NAME | description | required |`
+  table syntax were silently flagged for every var. The doc parser only
+  matched backtick-quoted names; it now also extracts the first column of
+  markdown pipe-table rows. `cli/validators/environment.mjs`.
+
+- **Docs-Diff warning was unactionable** — emitted `"N documented but not
+  found in code"` with no filename. Now lists up to 5 paths inline with
+  `(+N more)` for the long-tail. `cli/validators/docs-diff.mjs`.
+
+- **Traceability ignored `// @doc` annotations AND missed Next.js App
+  Router paths** — templates told users `// @doc API-REFERENCE.md` would
+  link a source file to a canonical doc; the scanner never read the
+  annotation. Compound: the `API-REFERENCE.md` TRACE_MAP only matched
+  `routes/`, `controllers/`, `handlers/`, `openapi/swagger`, and
+  `middleware/` — none of which cover `app/api/`. Added an annotation
+  scanner (top-of-file, multi-language comment syntax) and an
+  `(app|pages)/api/` glob. `cli/validators/traceability.mjs`.
+
+- **`docguard upgrade --apply` silently broke Metrics-Consistency** — when
+  a CLI upgrade added or removed validators, the project's hardcoded "N
+  validators" counts in markdown went stale and the very next
+  `docguard guard` failed Metrics-Consistency. The user did nothing wrong.
+  `upgrade --apply` now prints an explicit nudge to run `fix --write`
+  using the just-installed binary (the current process holds the OLD CLI's
+  validator list, so it cannot apply the fix itself). `cli/commands/upgrade.mjs`.
+
+- **Python env-vars were never scanned at all** — `grepEnvUsage` walked
+  `.py` files but the regex list was JS-only (`process.env.*`,
+  `import.meta.env.*`). Every documented Python env var read as "in docs,
+  not in code". Added patterns for `os.environ["X"]`, `os.environ.get("X")`,
+  and `os.getenv("X")`. The `explain` command's claim that Python was
+  supported now actually holds. `cli/shared-source.mjs`.
+
+- **`docguard memory` "Accuracy" overlapped `docguard score` "Accuracy"
+  with different denominators** — same word, same project, wildly different
+  numbers. Renamed the per-claim metric in `memory` to **"Claim match
+  rate"** (matched claims / total claims) so it no longer collides with
+  the score's weighted accuracy axis across all signals. JSON field name
+  unchanged for backward compatibility. `cli/commands/memory.mjs`.
+
 ## [0.21.1] - 2026-05-26
 
 **Security patch — closes issue #190.** Command injection vulnerability in

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.21.1
+Version: 0.22.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
@@ -27,7 +27,9 @@ Description-Content-Type: text/markdown
 > **The enforcement layer for Spec-Driven Development.**
 > Validate. Score. Enforce. Ship documentation that AI agents can actually use.
 
+[![CI](https://github.com/raccioly/docguard/actions/workflows/ci.yml/badge.svg)](https://github.com/raccioly/docguard/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/docguard-cli)](https://www.npmjs.com/package/docguard-cli)
+[![npm downloads](https://img.shields.io/npm/dw/docguard-cli)](https://www.npmjs.com/package/docguard-cli)
 [![PyPI](https://img.shields.io/pypi/v/docguard-cli)](https://pypi.org/project/docguard-cli/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
@@ -42,6 +44,8 @@ Description-Content-Type: text/markdown
 > ```
 > Runs against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.
 
+![DocGuard demo](assets/demo.gif)
+
 ---
 
 ## Table of Contents
@@ -91,7 +95,7 @@ graph TD
     Commands --> setup["setup wizard"]
     Commands --> other["diff · init · fix · trace · impact · sync<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (23)"]
+    guard --> Validators["Validators (24)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -119,7 +123,7 @@ graph TD
 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.
+  failures, and fix recipes for any of the 24 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
@@ -261,7 +265,7 @@ DocGuard is a [community extension](https://github.com/github/spec-kit/blob/main
 specify extension add docguard
 ```
 
-This installs DocGuard's slash commands (`/docguard.guard`, `/docguard.review`, `/docguard.fix`, `/docguard.score`) into your AI agent's command palette.
+This installs DocGuard's slash commands (`/docguard.init`, `/docguard.guard`, `/docguard.review`, `/docguard.fix`, `/docguard.update`) into your AI agent's command palette.
 
 ---
 
@@ -274,7 +278,7 @@ DocGuard ships **14 commands** (the "Daily 5" + 9 situational tools, including t
 | Command | What It Does |
 |:--------|:-------------|
 | `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
-| `guard` | Validate against canonical docs — 23 validators |
+| `guard` | Validate against canonical docs — 24 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) |
@@ -283,6 +287,7 @@ DocGuard ships **14 commands** (the "Daily 5" + 9 situational tools, including t
 
 | Command | Purpose |
 |:--------|:--------|
+| `demo` | Zero-install showcase — runs guard against a baked-in drifting fixture (`npx docguard-cli demo`) |
 | `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) |
@@ -367,7 +372,7 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-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.
+DocGuard runs **24 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 |
 |:--|:----------|:--------------|:--------|
@@ -394,6 +399,7 @@ DocGuard runs **23 automated validators** on every `guard` check. Every one is *
 | 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 |
+| 24 | **Surface-Sync** | Item-level enumerable drift — names in doc tables/lists (commands, validators, etc.) match code-truth (opt-in via `surfaceSync.surfaces`; N/A unless configured) | ✅ On |
 
 **Per-validator controls** (in `.docguard.json`):
 ```json
@@ -461,10 +467,11 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 23 validators |
+| `/docguard.init` | Initialize Canonical-Driven Development in a new or existing project |
+| `/docguard.guard` | Run quality validation — check all 24 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 |
+| `/docguard.update` | Update canonical docs after code changes — detect drift and sync documentation |
 
 These commands are installed into your AI agent's command directory:
 
@@ -681,6 +688,12 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#research--academic-credits) for full citat
 
 ---
 
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=raccioly/docguard&type=Date)](https://star-history.com/#raccioly/docguard&Date)
+
+---
+
 ## 📄 License
 
 [MIT](LICENSE) — Free to use, modify, and distribute.