DocProof

Docs at the reading level you choose — with proof the facts survived.

DocProof rewrites documentation to a target reading level (Grade 6 → Professional) and then verifies the rewrite: every technical claim in the original is extracted, matched against the rewrite, and judged — preserved, weakened, strengthened, missing, contradicted, or added. Simplification may drop precision, but never silently: no silent loss is the contract.

Files in, files out. No platform, no hosting, no format. Works on any markdown — READMEs, Docusaurus/Starlight docs folders, Obsidian vaults, exported wikis.

Quickstart

# Keyless, instant — readability report (code-aware: fences & inline code excluded)
npx docproof score docs/

# Keyless — did an edit/AI-rewrite change exact facts? (numbers, versions, flags, URLs, code, paths)
npx docproof verify original.md rewritten.md --exact-only

# BYOK — simplify with full claim-preservation verification
export ANTHROPIC_API_KEY=...        # or OPENAI_API_KEY, or a local model via --provider ollama
npx docproof simplify README.md --level grade6

# No API key, but a Claude Pro/Max subscription? Use Claude Code as the engine:
npx docproof simplify README.md --level grade6 --provider claude-code

simplify emits three artifacts next to your file:

• README.simplified.md — the rewrite
• README.simplified.report.md — readability before/after + the full claim verdict table
• .docproof/claims/…claims.json — a committable claim ledger (diffable in PRs)

Commands

| Command | Needs a key? | What it does | |---|---|---| | docproof score [paths] | No | Grade per file: FK, Gunning Fog, SMOG, ARI, Coleman-Liau, composite. --check --max-grade N gates CI. | | docproof verify <a> <b> | --exact-only: No · full: yes | Claim-preservation diff between two versions of a doc. --check exits 1 on errors. | | docproof simplify <paths> | Yes (BYOK or claude-code) | Rewrite to --level grade6\|highschool\|college\|professional, verify, auto-repair lost claims, report. | | docproof init | No | Write docproof.config.yaml + prepare .docproof/ (cache gitignored, ledgers committable). |

Global: --json everywhere (stdout stays machine-clean; progress goes to stderr), --dry-run on simplify prints a token/cost estimate before anything is called, --no-cache, NO_COLOR respected.

How verification works

1. Deterministic exact-fact pass (always, free, no LLM): numbers, versions, CLI flags, URLs, inline code, and file paths are extracted from both documents and compared as multisets. A 3.2 that became 3.4 is caught here — with zero false positives.
2. Protected regions: before any LLM sees your text, inline code, link targets, versions, flags, and your configured protectedTerms are frozen into tokens; code fences never leave the process at all. Tokens are validated after rewriting (each exactly once) — a rewrite that mangles one is rejected and the original section is kept.
3. Claim extraction: typed claims (requirement, numeric, version, instruction, warning, limitation, behavioral, fact) are extracted from both versions at temperature 0, cached by content hash.
4. Alignment + judgment: each original claim is matched against rewrite claims (lexical shortlist → LLM entailment judgment). Claims with no lexical match get a second chance against the full revised section before ever being called missing — false alarms are the enemy.
5. Repair loop: lost or contradicted claims trigger a targeted re-rewrite of the offending sections, then re-verification.
6. Anything the judge isn't sure about is reported as uncertain — never silently forced into a verdict.

Providers

BYOK via environment: ANTHROPIC_API_KEY (default models: Haiku fast-tier / Sonnet strong-tier), OPENAI_API_KEY, or local --provider ollama. Override models in docproof.config.yaml:

provider: anthropic
models:
  fast: claude-haiku-4-5-20251001
  strong: claude-sonnet-5
defaultLevel: highschool
protectedTerms: [CandleKit]

A deterministic --provider mock runs the whole pipeline offline (used by the test suite).

No API key? Claude Pro/Max subscription

--provider claude-code routes every LLM call through the Claude Code CLI (claude -p), so usage bills against your Claude subscription instead of an API key. Requirements: Claude Code installed and signed in. Tiers map to haiku (fast) / sonnet (strong); override via models: in config.

Caveats: each call carries Claude Code's own system prompt (~20k input tokens), so it consumes your subscription's usage limits noticeably faster than raw API calls — fine for docs-sized runs, and the content-hash cache means unchanged sections cost nothing on re-runs. Temperature/max-token settings are not configurable through the CLI and are ignored. --dry-run prices subscription usage at $0.

Exit codes

0 success · 1 check failed (--check) · 2 usage/config error · 3 provider error. CI recipe:

- run: npx docproof verify docs/guide.md docs/guide.simplified.md --exact-only --check

Agent companions

companions/ ships thin adapters — Claude Code skills (/document-simplify, /document-verify, /document-score) and a Cursor rule — that shell out to this CLI. The CLI is the product; agents are interchangeable front-ends.

Status & naming

v0.1 — "Simplify, verified" (per the blueprint): score, simplify, verify. Drift audit (docproof audit) and generation (docproof generate) are the next release beats.

Formerly drafted as "AutoDoc" — renamed because autodoc, autodocs, and autodoc-cli are all occupied on npm. docproof verified available 2026-07-09.

MIT © DocProof contributors