docgrity 0.1.2 → 0.1.3

package/README.md

@@ -1,151 +1,104 @@
-# Docgrity for VS Code
+# Docgrity Action & CLI
 
-[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/ujjavala.docgrity?label=VS%20Code%20Marketplace)](https://marketplace.visualstudio.com/items?itemName=ujjavala.docgrity)
-[![CI](https://github.com/ujjavala/docgrity-vscode/actions/workflows/ci.yml/badge.svg)](https://github.com/ujjavala/docgrity-vscode/actions/workflows/ci.yml)
+**Continuous doc-integrity for your repo's markdown: contradictions, duplicates and open
+questions — as a GitHub Action (with deduplicated issues) and a read-only local CLI.**
 
-**Find where your repository's docs disagree with themselves — and raise a GitHub issue to get it fixed.**
+Part of the Docgrity family:
 
-**Install:** search “Docgrity” in the Extensions view, or `code --install-extension ujjavala.docgrity`
-
-The repo-docs sibling of the [Docgrity Confluence app](https://ujjavala.github.io/docgrity-site/).
-Scoped deliberately: **markdown files only** (`**/*.md` — READMEs, ADRs, runbooks, guides).
-
-This repo contains all three repo-docs surfaces:
-
-| Surface | Where | Acts? |
+| Surface | Job | Acts? |
 |---|---|---|
-| **VS Code extension** (this root) | interactive scans in the editor | raises issues, human-approved one at a time |
-| **GitHub Action** ([action/](action/)) | CI: schedule + PRs | opt-in deduped issues, job summary, HTML report |
-| **Local CLI** ([action/bin/docgrity.js](action/bin/docgrity.js)) | your terminal | **read-only** report dashboard, no actions |
-
-See [action/README.md](action/README.md) for Action and CLI usage
-(`uses: ujjavala/docgrity-vscode/action@main`).
-
-## What it does
-
-1. **Scan** — `Docgrity: Scan repository docs` collects your markdown files, picks
-   candidate pairs locally with TF-IDF (no network), then asks the LLM to assess:
-   - **Contradictions** — conflicting factual claims across two docs
-   - **Duplicates** — substantially overlapping docs that should be merged
-   - **Open questions** — unresolved TBD/TODO/"who owns this?" buried in docs
-2. **Review** — findings appear in the Docgrity view with evidence excerpts; each
-   excerpt is a click away from the exact spot in the file, and shows as a
-   diagnostic squiggle. Every finding records the model + prompt version.
-3. **Act** — right-click a finding → **Raise GitHub issue**. Docgrity drafts the
-   issue (title, evidence, suggested next step, *potential* owner from git history),
-   shows you the draft, and only creates it after you approve. The issue is labelled
-   `docgrity` and `docgrity:<type>`.
-
-## Zero cost, zero keys
-
-- All LLM calls go through **your own GitHub Copilot subscription** via the VS Code
-  Language Model API. No API keys, no servers, no telemetry.
-- Issue creation uses VS Code's built-in GitHub sign-in.
-- Candidate selection is local TF-IDF — the LLM only sees the top pairs.
-
-## Modes: report-only vs report + issues
-
-| `docgrity.mode` | Behaviour |
-|---|---|
-| `report-and-issue` (default) | Scan, review findings, and raise GitHub issues — each previewed and human-approved. |
-| `report-only` | Scan and review only. The *Raise GitHub issue* action is hidden and blocked — the extension is guaranteed to never post anywhere. Good for client repos, compliance-sensitive environments, or just reading. |
-
-Set it in Settings → search “docgrity mode”, or in `.vscode/settings.json`:
-
-```json
-{ "docgrity.mode": "report-only" }
+| [Confluence app](https://ujjavala.github.io/docgrity-site/) | wiki integrity | comments (human-approved) |
+| VS Code extension | interactive repo-doc scans | raises issues (human-approved) |
+| **This Action** | continuous CI enforcement | issues (opt-in, deduped, capped) + report |
+| **This CLI** | local observation | **read-only** — report dashboard only |
+
+## GitHub Action
+
+```yaml
+- uses: ujjavala/docgrity-vscode/action@main
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  with:
+    provider: github-models   # free — uses GITHUB_TOKEN, no API key
+    create_issues: 'true'     # opt-in; default false
+    max_new_issues: 5
 ```
 
-Per-workspace settings win over user settings, so you can default to report-only
-globally and enable issues only in repos you own.
+Full example with weekly schedule, PR trigger and Pages report publishing:
+[examples/docgrity.yml](examples/docgrity.yml).
+
+What it does per run:
 
-## Choosing which checks run
+1. Collects markdown docs (`**/*.md`, capped), selects candidate pairs locally (TF-IDF),
+   assesses with the LLM using versioned prompts and typed-JSON validation, verifies
+   every evidence excerpt verbatim against the source (hallucination guard).
+2. Writes a **job summary** table and a **static HTML report** (`docgrity-report/`)
+   with evidence, links to docs on GitHub, and *potential* owners from git history.
+3. **Opt-in** (`create_issues: true`): syncs GitHub issues **deduplicated by a stable
+   finding fingerprint** — new findings create issues (capped per run), unchanged ones
+   are left alone, resolved ones are auto-closed with a comment. Labels: `docgrity`,
+   `docgrity:<type>`.
 
-Each check is a separate toggle — run any combination:
+### Providers
 
-| Setting | Default | What it does |
+| provider | key | cost |
 |---|---|---|
-| `docgrity.checks.duplicates` | `true` | Pairwise duplicate detection |
-| `docgrity.checks.contradictions` | `true` | Pairwise contradiction detection |
-| `docgrity.checks.openQuestions` | `true` | Per-doc unresolved-question detection |
+| `github-models` (default in CI) | none — uses `GITHUB_TOKEN` with `models: read` | free (being retired by GitHub — prefer a BYO provider) |
+| `gemini` / `openai` / `anthropic` | `api_key` input (use a repo secret) | your key |
+| `ollama` | none — local or tunnelled endpoint | free, fully private |
 
-These combine freely with any model (`docgrity.model.*`) and either mode
-(`docgrity.mode`). Disabling checks also speeds up scans: pair selection is
-skipped entirely when both pairwise checks are off.
+## Local CLI (read-only)
 
-## Scan performance
+```bash
+npm i -g docgrity
+docgrity scan --open
+```
 
-- When both pairwise checks are enabled they run as a **single combined LLM
-  call per pair** (the model reads each pair once, not twice).
-- Docs with no open-question signals (no TODO/TBD/`???`/unanswered questions)
-  are **pre-filtered out** before any LLM call.
-- Assessments run with **bounded concurrency** (4 at a time).
-- For large repos, tune `docgrity.maxFiles`, `docgrity.maxPairs`, and
-  `docgrity.include` to narrow the corpus.
+or without installing: `npx docgrity scan --open` (from a repo checkout:
+`npx github:ujjavala/docgrity-vscode scan --open`).
 
-## Choosing your model (Copilot, Claude, GPT, local llama…)
+Runs the same scan locally and opens the **report dashboard**: findings, evidence,
+doc links and potential owners. **The CLI never raises issues or takes any action** —
+by design, local scans observe; only CI (explicitly opted in) acts.
 
-Run **`Docgrity: Select AI model`** from the command palette — it lists every model
-VS Code exposes and saves your choice. Or set it manually:
+```
+Usage: docgrity scan [options]
 
-| Setting | Meaning | Default |
-|---|---|---|
-| `docgrity.model.vendor` | `vscode.lm` vendor id (`copilot` covers Copilot + BYOK models; empty = any) | `copilot` |
-| `docgrity.model.family` | preferred model family, e.g. `gpt-4o`, `claude-sonnet-4.5`, `llama3.1` (empty = first available) | `""` |
-
-**Options, in order of simplicity:**
-
-1. **Copilot (default)** — sign in to GitHub Copilot; nothing to configure.
-2. **Claude / GPT / Gemini via Copilot** — any model enabled in Copilot's model picker
-   is available; set `docgrity.model.family` (e.g. `claude-sonnet-4.5`) or use
-   *Select AI model*.
-3. **Local Ollama** — install [Ollama](https://ollama.com), `ollama pull llama3.1`,
-   then in Copilot Chat → **Manage models** → add the Ollama model. It registers under
-   the `copilot` vendor; pick it with *Select AI model*. Fully local — no doc content
-   leaves your machine.
-4. **Remote Ollama over a Cloudflare Tunnel** — if your model runs on another box
-   (home server, GPU rig):
-   ```bash
-   # on the machine running Ollama
-   cloudflared tunnel --url http://localhost:11434
-   ```
-   Point Copilot's Manage models → Ollama endpoint at the generated
-   `https://….trycloudflare.com` URL. Note: quick tunnels get a **new URL on every
-   restart** — re-update the endpoint each time, or create a **named tunnel** with your
-   own domain for a stable URL (`cloudflared tunnel create …`). Protect a named tunnel
-   with Cloudflare Access — an open LLM endpoint is abusable.
-
-Small local models fail Docgrity's strict-JSON validation more often than hosted
-ones; failed responses are rejected safely (never mis-recorded) — expect fewer
-findings rather than wrong ones. 8B+ instruct models work best.
-
-## Design principles (shared with the Forge app)
-
-- Typed JSON outputs only — model responses are validated in code, never trusted prose.
-- Every finding requires verbatim evidence, verified against the source file
-  (hallucinated quotes are dropped).
-- Ownership is always *potential* (last git author), never asserted.
-- Nothing is posted anywhere without explicit human approval.
-- Doc content is untrusted input — it cannot override agent instructions.
+  --dir <path>            Directory to scan (default: .)
+  --out <path>            Report output directory (default: docgrity-report)
+  --open                  Open the HTML report when done
+
+  --checks <list>         duplicates, contradictions, open-questions — any combination
+  --max-files <n>         Max markdown files (default: 200)
+  --max-pairs <n>         Max document pairs (default: 25)
+  --threshold-duplicate / --threshold-contradiction / --threshold-open-question <0..1>
+
+  --provider <p>          ollama | gemini | openai | anthropic | github-models
+  --model <m>             Model name
+  --endpoint <url>        Ollama endpoint (default http://localhost:11434)
 
-## Requirements
+  --version, -v           Installed version + latest on npm
+  --help, -h              Full help
+```
 
-- VS Code 1.95+, an active GitHub Copilot subscription, a workspace with a GitHub
-  `origin` remote (for issue creation).
+Provider auto-detection: `DOCGRITY_API_KEY` set → `gemini`; else `GITHUB_TOKEN` →
+`github-models`; else → `ollama` (local, fully private — nothing leaves your machine).
 
-## Development
+Examples:
 
 ```bash
-npm install
-npm run compile
-# F5 in VS Code to launch the Extension Development Host
+docgrity scan --checks contradictions                     # one check only
+docgrity scan --checks duplicates,open-questions --max-pairs 10
+docgrity scan --provider ollama --model llama3.1:8b       # fully local
+DOCGRITY_API_KEY=... docgrity scan --provider gemini --open
 ```
 
-## Settings
+## Design principles (shared across all Docgrity surfaces)
 
-| Setting | Default | Purpose |
-|---|---|---|
-| `docgrity.include` | `**/*.md` | Docs glob (markdown only by design) |
-| `docgrity.exclude` | `**/{node_modules,…}/**` | Excluded paths |
-| `docgrity.maxFiles` / `docgrity.maxPairs` | 200 / 25 | Scan caps |
-| `docgrity.thresholds.*` | 0.75 / 0.7 / 0.6 | Confidence gates per finding type |
+- Typed JSON outputs only; model responses validated in code.
+- Every finding requires verbatim evidence, verified against the source file.
+- Ownership is always *potential* (last git author), never asserted.
+- Action-taking is opt-in, capped, and auditable (issue trailer records model +
+  prompt version + fingerprint).
+- Doc content is untrusted input — it cannot override agent instructions.
+- Zero dependencies; plain Node 20+ ESM.

package/package.json

@@ -1,171 +1,38 @@
 {
   "name": "docgrity",
-  "displayName": "Docgrity — Doc Integrity for Repos",
-  "description": "Finds contradictions, duplicates and open questions across your repository's markdown docs, and raises GitHub issues to get them fixed. Uses your own Copilot subscription — no keys, no servers.",
-  "version": "0.1.2",
-  "publisher": "ujjavala",
+  "version": "0.1.3",
+  "description": "Docgrity doc-integrity scans for CI and local use: contradictions, duplicates and open questions across repository markdown docs. Read-only CLI — generates an HTML report; never posts anything.",
+  "type": "module",
+  "bin": { "docgrity": "bin/docgrity.js" },
+  "files": [
+    "bin/",
+    "src/",
+    "action.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "scan": "node bin/docgrity.js scan",
+    "test": "node --test \"test/*.test.mjs\""
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ujjavala/docgrity-vscode"
-  },
-  "bin": {
-    "docgrity": "action/bin/docgrity.js"
+    "url": "git+https://github.com/ujjavala/docgrity-vscode.git",
+    "directory": "action"
   },
-  "icon": "media/icon.png",
-  "engines": {
-    "vscode": "^1.95.0"
-  },
-  "categories": [
-    "AI",
-    "Linters",
-    "Other"
+  "homepage": "https://ujjavala.github.io/docgrity-vscode-site/",
+  "bugs": "https://github.com/ujjavala/docgrity-vscode/issues",
+  "keywords": [
+    "documentation",
+    "markdown",
+    "lint",
+    "contradiction",
+    "duplicate",
+    "llm",
+    "cli",
+    "github-action"
   ],
-  "main": "./out/extension.js",
-  "activationEvents": [],
-  "contributes": {
-    "commands": [
-      {
-        "command": "docgrity.scan",
-        "title": "Docgrity: Scan repository docs"
-      },
-      {
-        "command": "docgrity.selectModel",
-        "title": "Docgrity: Select AI model (Copilot / Claude / local…)"
-      },
-      {
-        "command": "docgrity.raiseIssue",
-        "title": "Docgrity: Raise GitHub issue for finding"
-      },
-      {
-        "command": "docgrity.openReport",
-        "title": "Docgrity: Open findings report (markdown)"
-      },
-      {
-        "command": "docgrity.clearFindings",
-        "title": "Docgrity: Clear findings"
-      }
-    ],
-    "viewsContainers": {
-      "activitybar": [
-        {
-          "id": "docgrity",
-          "title": "Docgrity",
-          "icon": "media/icon.svg"
-        }
-      ]
-    },
-    "views": {
-      "docgrity": [
-        {
-          "id": "docgrity.findings",
-          "name": "Findings"
-        }
-      ]
-    },
-    "menus": {
-      "view/item/context": [
-        {
-          "command": "docgrity.raiseIssue",
-          "when": "view == docgrity.findings && viewItem == finding && docgrity.issuesEnabled"
-        }
-      ],
-      "commandPalette": [
-        {
-          "command": "docgrity.raiseIssue",
-          "when": "docgrity.issuesEnabled"
-        }
-      ]
-    },
-    "configuration": {
-      "title": "Docgrity",
-      "properties": {
-        "docgrity.mode": {
-          "type": "string",
-          "enum": [
-            "report-only",
-            "report-and-issue"
-          ],
-          "enumDescriptions": [
-            "Scan and show findings in the editor only. The 'Raise GitHub issue' action is hidden — nothing can be posted anywhere.",
-            "Scan, show findings, and allow raising GitHub issues (each one previewed and human-approved before posting)."
-          ],
-          "default": "report-and-issue",
-          "description": "What Docgrity is allowed to do. 'report-only' guarantees the extension never posts anything."
-        },
-        "docgrity.checks.duplicates": {
-          "type": "boolean",
-          "default": true,
-          "description": "Check document pairs for duplicates (docs that should be merged)."
-        },
-        "docgrity.checks.contradictions": {
-          "type": "boolean",
-          "default": true,
-          "description": "Check document pairs for contradictions (conflicting factual claims)."
-        },
-        "docgrity.checks.openQuestions": {
-          "type": "boolean",
-          "default": true,
-          "description": "Check each document for unresolved open questions (TBDs, TODOs, unanswered questions)."
-        },
-        "docgrity.include": {
-          "type": "string",
-          "default": "**/*.md",
-          "description": "Glob for documents to scan (markdown only by design)."
-        },
-        "docgrity.exclude": {
-          "type": "string",
-          "default": "",
-          "description": "Additional glob for paths to exclude from scans. node_modules, dist, build, vendor etc. and anything in .gitignore are always excluded."
-        },
-        "docgrity.maxFiles": {
-          "type": "number",
-          "default": 200,
-          "description": "Maximum number of markdown files per scan."
-        },
-        "docgrity.maxPairs": {
-          "type": "number",
-          "default": 25,
-          "description": "Maximum candidate document pairs assessed per scan."
-        },
-        "docgrity.model.vendor": {
-          "type": "string",
-          "default": "copilot",
-          "description": "Language model vendor to use via vscode.lm. 'copilot' covers Copilot models and Ollama models added through Copilot Chat's 'Manage models'. Set to another provider's vendor id, or empty for any available model."
-        },
-        "docgrity.model.family": {
-          "type": "string",
-          "default": "",
-          "description": "Preferred model family (e.g. 'gpt-4o', 'llama3.1'). Empty = first available model from the vendor."
-        },
-        "docgrity.thresholds.duplicate": {
-          "type": "number",
-          "default": 0.75,
-          "description": "Minimum confidence to record a duplicate finding."
-        },
-        "docgrity.thresholds.contradiction": {
-          "type": "number",
-          "default": 0.7,
-          "description": "Minimum confidence to record a contradiction finding."
-        },
-        "docgrity.thresholds.openQuestion": {
-          "type": "number",
-          "default": 0.6,
-          "description": "Minimum confidence to record an open-question finding."
-        }
-      }
-    }
-  },
-  "scripts": {
-    "compile": "tsc -p ./",
-    "watch": "tsc -watch -p ./",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "vscode:prepublish": "npm run compile"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/vscode": "^1.95.0",
-    "typescript": "^5.6.0",
-    "vitest": "^3.2.7"
-  }
+  "author": "ujjavala",
+  "license": "MIT"
 }

package/.github/workflows/ci.yml

@@ -1,54 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-      - name: Install dependencies
-        run: npm ci
-      - name: Compile (strict TypeScript)
-        run: npm run compile
-      - name: Unit tests
-        run: npm test
-      - name: Action unit tests (zero-dependency, node:test)
-        working-directory: action
-        run: npm test
-      - name: Dependency vulnerability audit
-        run: npm audit --audit-level=high
-      - name: Secret pattern scan (source only)
-        run: |
-          ! grep -rInE "(sk-[A-Za-z0-9]{20,}|AIza[A-Za-z0-9_-]{30,}|ghp_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,})" src/ action/src/ action/bin/ \
-            && echo "No hardcoded credentials found."
-      - name: Package extension
-        run: npx --yes @vscode/vsce package --no-dependencies
-      - name: Upload .vsix artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: docgrity-vsix
-          path: '*.vsix'
-
-  codeql:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      security-events: write
-    steps:
-      - uses: actions/checkout@v4
-      - uses: github/codeql-action/init@v3
-        with:
-          languages: javascript-typescript
-          queries: security-and-quality
-      - uses: github/codeql-action/analyze@v3

package/.vscodeignore

@@ -1,13 +0,0 @@
-.vscode/**
-src/**
-test/**
-node_modules/**
-samples/**
-action/**
-.github/**
-tsconfig.json
-vitest.config.ts
-.gitignore
-**/*.map
-media/icon.svg.png
-*.vsix

package/action/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Ujjavala
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/action/README.md

@@ -1,104 +0,0 @@
-# Docgrity Action & CLI
-
-**Continuous doc-integrity for your repo's markdown: contradictions, duplicates and open
-questions — as a GitHub Action (with deduplicated issues) and a read-only local CLI.**
-
-Part of the Docgrity family:
-
-| Surface | Job | Acts? |
-|---|---|---|
-| [Confluence app](https://ujjavala.github.io/docgrity-site/) | wiki integrity | comments (human-approved) |
-| VS Code extension | interactive repo-doc scans | raises issues (human-approved) |
-| **This Action** | continuous CI enforcement | issues (opt-in, deduped, capped) + report |
-| **This CLI** | local observation | **read-only** — report dashboard only |
-
-## GitHub Action
-
-```yaml
-- uses: ujjavala/docgrity-vscode/action@main
-  env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  with:
-    provider: github-models   # free — uses GITHUB_TOKEN, no API key
-    create_issues: 'true'     # opt-in; default false
-    max_new_issues: 5
-```
-
-Full example with weekly schedule, PR trigger and Pages report publishing:
-[examples/docgrity.yml](examples/docgrity.yml).
-
-What it does per run:
-
-1. Collects markdown docs (`**/*.md`, capped), selects candidate pairs locally (TF-IDF),
-   assesses with the LLM using versioned prompts and typed-JSON validation, verifies
-   every evidence excerpt verbatim against the source (hallucination guard).
-2. Writes a **job summary** table and a **static HTML report** (`docgrity-report/`)
-   with evidence, links to docs on GitHub, and *potential* owners from git history.
-3. **Opt-in** (`create_issues: true`): syncs GitHub issues **deduplicated by a stable
-   finding fingerprint** — new findings create issues (capped per run), unchanged ones
-   are left alone, resolved ones are auto-closed with a comment. Labels: `docgrity`,
-   `docgrity:<type>`.
-
-### Providers
-
-| provider | key | cost |
-|---|---|---|
-| `github-models` (default in CI) | none — uses `GITHUB_TOKEN` with `models: read` | free (being retired by GitHub — prefer a BYO provider) |
-| `gemini` / `openai` / `anthropic` | `api_key` input (use a repo secret) | your key |
-| `ollama` | none — local or tunnelled endpoint | free, fully private |
-
-## Local CLI (read-only)
-
-```bash
-npm i -g docgrity
-docgrity scan --open
-```
-
-or without installing: `npx docgrity scan --open` (from a repo checkout:
-`npx github:ujjavala/docgrity-vscode scan --open`).
-
-Runs the same scan locally and opens the **report dashboard**: findings, evidence,
-doc links and potential owners. **The CLI never raises issues or takes any action** —
-by design, local scans observe; only CI (explicitly opted in) acts.
-
-```
-Usage: docgrity scan [options]
-
-  --dir <path>            Directory to scan (default: .)
-  --out <path>            Report output directory (default: docgrity-report)
-  --open                  Open the HTML report when done
-
-  --checks <list>         duplicates, contradictions, open-questions — any combination
-  --max-files <n>         Max markdown files (default: 200)
-  --max-pairs <n>         Max document pairs (default: 25)
-  --threshold-duplicate / --threshold-contradiction / --threshold-open-question <0..1>
-
-  --provider <p>          ollama | gemini | openai | anthropic | github-models
-  --model <m>             Model name
-  --endpoint <url>        Ollama endpoint (default http://localhost:11434)
-
-  --version, -v           Installed version + latest on npm
-  --help, -h              Full help
-```
-
-Provider auto-detection: `DOCGRITY_API_KEY` set → `gemini`; else `GITHUB_TOKEN` →
-`github-models`; else → `ollama` (local, fully private — nothing leaves your machine).
-
-Examples:
-
-```bash
-docgrity scan --checks contradictions                     # one check only
-docgrity scan --checks duplicates,open-questions --max-pairs 10
-docgrity scan --provider ollama --model llama3.1:8b       # fully local
-DOCGRITY_API_KEY=... docgrity scan --provider gemini --open
-```
-
-## Design principles (shared across all Docgrity surfaces)
-
-- Typed JSON outputs only; model responses validated in code.
-- Every finding requires verbatim evidence, verified against the source file.
-- Ownership is always *potential* (last git author), never asserted.
-- Action-taking is opt-in, capped, and auditable (issue trailer records model +
-  prompt version + fingerprint).
-- Doc content is untrusted input — it cannot override agent instructions.
-- Zero dependencies; plain Node 20+ ESM.