Frequently Asked Questions

General

What is DocGuard?

DocGuard is an AI-native CLI tool that enforces Canonical-Driven Development (CDD). It ensures your project documentation stays accurate, comprehensive, and in sync with your code — using AI to write and maintain the docs.

What is CDD?

Canonical-Driven Development is a methodology where documentation is the source of truth. Instead of writing code first and documenting later (which leads to “document rot”), CDD enforces that documentation exists, is structured, and stays fresh.

Does DocGuard write documentation for me?

No — but it tells AI what to write. DocGuard generates structured research prompts that AI agents execute. The AI reads your codebase, writes the documentation, and DocGuard verifies it’s correct. Your role: review what the AI wrote.

What’s the difference between DocGuard and just writing docs manually?

DocGuard adds three things:

1. Structure — Enforces consistent doc templates across all projects
2. Enforcement — Validates docs exist, have required sections, stay fresh
3. AI automation — Generates prompts so AI writes the docs, not humans

---

Commands

What’s the most important command?

docguard diagnose — it’s the primary command. It runs all checks, identifies every issue, and generates AI fix prompts in a single output. Start here.

What’s the difference between guard and diagnose?

Command	Purpose	When to use
guard	Identify issues (pass/fail gate)	CI pipelines, pre-commit hooks
diagnose	Identify + generate fix prompts	Development, AI agents, fixing docs

diagnose runs guard internally and adds the fix layer on top.

What’s the difference between fix and diagnose?

fix generates prompts for individual documents (fix --doc architecture). diagnose runs everything at once and outputs a combined remediation plan. Use diagnose for a full health check; use fix --doc when you know exactly which doc needs work.

What does generate do that init doesn’t?

init creates empty skeleton templates. generate scans your existing codebase and creates pre-filled docs with real content (detected components, routes, env vars, etc.).

---

Profiles

What profile should I use?

Situation	Profile
Side project, tutorial, prototype	starter
Team project, active development	standard (default)
Regulated, enterprise, compliance	enterprise

Can I switch profiles later?

Yes. Change the "profile" field in .docguard.json and run docguard diagnose to see what’s missing.

Can I override specific validators within a profile?

Yes. Profile sets the baseline, your config overrides:

{
  "profile": "starter",
  "validators": {
    "freshness": true
  }
}

---

Document Tax

What is “document tax”?

The time and effort required to maintain documentation. Too little documentation leads to “document rot” (stale, useless docs). Too much enforcement creates “document tax” (developers spend more time on docs than code).

How does DocGuard avoid document tax?

1. AI writes the docs — human cost drops to near-zero
2. Compliance profiles — choose the right level for your project
3. score --tax — measures your actual maintenance cost
4. Smart enforcement — only flags when relevant code changed

What does score --tax show?

📋 Documentation Tax Estimate
─────────────────────────────────
Tracked docs:        7 files
Active profile:      standard
Est. maintenance:    ~5 min/week
Tax-to-value ratio:  LOW

If tax is HIGH, consider using starter profile or letting AI handle more.

---

CI/CD

How do I add DocGuard to CI?

npx docguard-cli ci --format json --threshold 70

Exit code 0 = pass, 1 = fail. Use --threshold to set minimum score.

Is there a GitHub Action?

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 — 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.

I ran guard on our legacy repo and got dozens of findings. Now what?

Freeze them and move forward:

npx docguard-cli guard --update-baseline   # writes .docguard.baseline.json — commit it

From then on guard/ci pass, suppress the frozen findings visibly (“N pre-existing finding(s) suppressed”), and gate only NEW drift. Burn the baseline down at your own pace; --no-baseline shows the full picture anytime.

---

Document locations

DocGuard adopted the wrong directory as my canonical docs

A Spec Kit feature folder (specs/003-my-feature/) is never adopted: one feature’s spec and data model are not the project’s documentation. If another directory was adopted and you did not want it, state the mapping yourself:

{ "docs": { "roles": { "architecture": "docs/canonical/ARCHITECTURE.md" } } }

An explicit docs.roles is treated as your answer and is never second-guessed. To use DocGuard’s own layout instead, remove docs.roles and create docs-canonical/ before re-running init.

Why will DocGuard not generate into my mapped documents?

On a mapped layout init configures the project and scaffolds only the roles your mapping has not placed, so it never writes into a document you maintain and never creates a duplicate beside it. Generating or repairing a mapped document is a separate matter: setup, init --wizard and diagnose --auto name the mapped roles and stop, because that prose is yours to edit.

Technical

Does DocGuard have dependencies?

One. @babel/parser (exact-pinned), for AST-accurate JS/TS parsing — and it’s loaded optionally, so DocGuard still runs (on the regex fallback tier) if it’s ever missing. Everything else is pure Node.js built-ins. Works with Node.js 18+. Python parsing optionally shells out to the project’s own python3.

Does it work with non-JavaScript projects?

Yes. DocGuard validates documentation structure, not code. It works with any project that has a docs-canonical/ directory. Some validators (architecture import analysis) are JavaScript-focused, but the core CDD framework is language-agnostic.

Does DocGuard read my code?

Yes — for features like generate, diff, and architecture validation. It reads local files only. No data is sent anywhere.

Can I disable validators I don’t need?

Yes. In .docguard.json:

{
  "validators": {
    "security": false,
    "freshness": false
  }
}

Or use a profile that has them disabled by default (like starter).

Can my AI agent use DocGuard without parsing CLI output?

Yes — run the MCP server: claude mcp add docguard -- npx docguard-cli mcp exposes guard, score, explain, verify-claims, and diagnose as native tools for Claude, Cursor, and any MCP client. For CLI-driven agents, guard --format json is the stable contract (findings with stable codes) and guard --format sarif feeds GitHub Code Scanning. See AI Integration.

Guard flagged something that isn’t wrong. What do I do?

Run docguard explain <CODE> first: it says what the finding means and which marker, if any, silences it. Inline // docguard:ignore <CODE> — reason on (or above) the flagged line works for the security codes, REF001, REF002 and SPK010; other codes have their own markers, listed in Finding Codes, and some have none. Report it with docguard feedback (a local-first record plus a one-click prefilled GitHub issue). Don’t disable the whole validator for one false positive; see Troubleshooting.