chore(trust): npm provenance attestation + privacy policy + unknown-server FAQ

.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.32.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Fix Skill
 

.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.32.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Guard Skill
 

.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.32.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Review Skill
 

.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.32.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Score Skill
 

.agent/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ 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.32.0
+  version: 0.33.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.32.0 -->
+<!-- docguard:version: 0.33.0 -->
 
 # DocGuard Sync Skill
 

.github/workflows/release.yml

@@ -158,15 +158,23 @@ jobs:
   publish-npm:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
+    # Provenance attestation needs an OIDC token: npm exchanges it with
+    # Sigstore to sign a statement that THIS tarball was built by THIS
+    # workflow from THIS commit. That's what supply-chain checks (npm's
+    # "Provenance" badge, Claude Code's unknown-package legitimacy check,
+    # socket.dev, etc.) verify — without it the package is unattributable.
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-node@v6
         with:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Publish
-        run: npm publish
+      - name: Publish (with provenance)
+        run: npm publish --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **npm provenance attestation.** Releases now publish with `npm publish --provenance` (OIDC + Sigstore): every tarball carries a signed statement that it was built by this repo's GitHub Actions from a specific commit. This is what "unknown package" legitimacy checks (Claude Code, socket.dev, npm's Provenance badge) verify — DocGuard installs are now cryptographically attributable.
+- **PRIVACY.md** — the short, honest policy: DocGuard collects nothing, all analysis is local, no telemetry; the three explicit user-initiated outbound paths (`feedback` URL, `gh`-backed PR commands, opt-in HTTP transport) are enumerated. Ships in the npm package and unblocks Anthropic Connectors Directory submission (a missing privacy policy is an instant rejection there).
+- **FAQ**: why AI agents flag DocGuard as "unknown" on first install, and how to pre-trust it (project `.mcp.json`, Always allow, managed-settings allowlist).
+
 ## [0.33.0] - 2026-07-16
 
 ### Added

PRIVACY.md

@@ -0,0 +1,45 @@
+# Privacy Policy — DocGuard
+
+**Effective: 2026-07-16**
+
+DocGuard is a local-first command-line tool. This policy is short because the
+honest answer is short: **DocGuard collects nothing.**
+
+## What DocGuard does with your data
+
+- **All analysis runs locally.** Validators, scoring, reports, the MCP server —
+  everything reads files on your machine and writes output to your machine.
+  Nothing is uploaded, sampled, or "improved" with your code or docs.
+- **No telemetry, no analytics, no crash reporting.** There is no phone-home
+  code path. The deterministic core makes no network calls at all.
+- **No accounts.** DocGuard has no sign-up, no API keys of its own, and no
+  server-side component operated by us.
+
+## The explicit, user-initiated exceptions
+
+Three commands can *prepare* outbound actions — each is opt-in, visible, and
+executed by you or your own tooling, never silently by DocGuard:
+
+| Command | What happens |
+|---------|--------------|
+| `docguard feedback` | Builds a **prefilled GitHub issue URL** (redacted and length-capped) and saves a local record. Nothing is sent unless you open the URL and submit it yourself. |
+| `docguard upgrade --pr` / `impact --prs` | Shell out to **your** locally-authenticated `gh` CLI to interact with **your** repositories. DocGuard never holds credentials. |
+| `docguard mcp --transport http` | Serves read-only tools over HTTP. Binds to loopback by default; binding a non-loopback address **refuses to start** without an `--api-key`. |
+
+## Data written to disk (yours, locally)
+
+State lives under `.docguard/` in your repo (fix history, score history,
+caches) and `.docguard.baseline.json` if you create one. All of it is plain
+text, in your repository, under your version control — delete it any time.
+
+## Dependencies
+
+One pinned runtime dependency (`@babel/parser`). The npm package is published
+from GitHub Actions with provenance attestation, so you can verify the tarball
+was built from this repository.
+
+## Changes & contact
+
+Changes to this policy land in this file with a dated entry in
+[CHANGELOG.md](CHANGELOG.md). Questions: open an issue at
+<https://github.com/raccioly/docguard/issues> (see [SUPPORT.md](SUPPORT.md)).

README.md

@@ -769,6 +769,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#research--academic-credits) for full citat
 
 ---
 
+## 🔒 Privacy & Supply Chain
+
+DocGuard is local-first: no telemetry, no analytics, no phone-home — the full
+(short) policy is in [PRIVACY.md](PRIVACY.md). npm releases are published with
+[provenance attestation](https://docs.npmjs.com/generating-provenance-statements),
+so you can verify each tarball was built by GitHub Actions from this repository.
+
 ## 📄 License
 
 [MIT](LICENSE) — Free to use, modify, and distribute.

docs/faq.md

@@ -119,6 +119,25 @@ Exit code 0 = pass, 1 = fail. Use `--threshold` to set minimum score.
 
 Yes — DocGuard ships a template at `templates/ci/github-actions.yml`. Copy it to `.github/workflows/` or use the reusable action in `action.yml`.
 
+### Claude (or my AI agent) says DocGuard is "unknown" and wants a legitimacy check. Why?
+
+That's the agent's default posture toward **any** third-party MCP server or
+npx package — MCP servers run code with your permissions, so unknown ones get
+a trust prompt. It's not a DocGuard-specific flag. What DocGuard provides so
+the check can pass:
+
+- **npm provenance** — releases are signed by GitHub Actions (Sigstore), so
+  the tarball is verifiably built from this repository.
+- **Official MCP registry** — `io.github.raccioly/docguard` is a verified
+  namespace at registry.modelcontextprotocol.io.
+- **Read-only annotations** — every MCP tool declares `readOnlyHint`; the
+  server never writes or reaches the network.
+- **[PRIVACY.md](../PRIVACY.md)** — no telemetry, no data collection.
+
+To stop the prompt on your own machines: approve with "Always allow", or
+pre-trust it for a whole team via a project-scoped `.mcp.json` /
+enterprise managed-settings allowlist.
+
 ### Does DocGuard block commits?
 
 Only if you install hooks (`docguard hooks`). Without hooks, it's advisory only.

package.json

@@ -4,7 +4,7 @@
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {
-    "docguard": "./cli/docguard.mjs"
+    "docguard": "cli/docguard.mjs"
   },
   "scripts": {
     "docguard": "node cli/docguard.mjs",
@@ -36,7 +36,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/raccioly/docguard"
+    "url": "git+https://github.com/raccioly/docguard.git"
   },
   "homepage": "https://github.com/raccioly/docguard#readme",
   "mcpName": "io.github.raccioly/docguard",
@@ -57,6 +57,7 @@
     "docs/",
     "schemas/",
     "STANDARD.md",
+    "PRIVACY.md",
     "PHILOSOPHY.md",
     "README.md",
     "LICENSE"