docgrity 0.1.2

package/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+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

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

package/LICENSE

@@ -0,0 +1,21 @@
+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/README.md

@@ -0,0 +1,151 @@
+# Docgrity for VS Code
+
+[![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)
+
+**Find where your repository's docs disagree with themselves — and raise a GitHub issue to get it fixed.**
+
+**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? |
+|---|---|---|
+| **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" }
+```
+
+Per-workspace settings win over user settings, so you can default to report-only
+globally and enable issues only in repos you own.
+
+## Choosing which checks run
+
+Each check is a separate toggle — run any combination:
+
+| Setting | Default | What it does |
+|---|---|---|
+| `docgrity.checks.duplicates` | `true` | Pairwise duplicate detection |
+| `docgrity.checks.contradictions` | `true` | Pairwise contradiction detection |
+| `docgrity.checks.openQuestions` | `true` | Per-doc unresolved-question detection |
+
+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.
+
+## Scan performance
+
+- 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.
+
+## Choosing your model (Copilot, Claude, GPT, local llama…)
+
+Run **`Docgrity: Select AI model`** from the command palette — it lists every model
+VS Code exposes and saves your choice. Or set it manually:
+
+| 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.
+
+## Requirements
+
+- VS Code 1.95+, an active GitHub Copilot subscription, a workspace with a GitHub
+  `origin` remote (for issue creation).
+
+## Development
+
+```bash
+npm install
+npm run compile
+# F5 in VS Code to launch the Extension Development Host
+```
+
+## Settings
+
+| 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 |

package/action/LICENSE

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,104 @@
+# 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.

package/action/action.yml

@@ -0,0 +1,30 @@
+name: 'Docgrity doc-integrity scan'
+description: >-
+  Finds contradictions, duplicates and open questions across repository markdown
+  docs. Writes a job summary and a static HTML report; optionally raises
+  deduplicated GitHub issues.
+branding:
+  icon: 'file-text'
+  color: 'blue'
+inputs:
+  provider:
+    description: 'LLM provider: github-models (default, uses GITHUB_TOKEN), gemini, openai, anthropic'
+    default: 'github-models'
+  api_key:
+    description: 'API key for gemini/openai/anthropic (pass a repo secret). Not needed for github-models.'
+    default: ''
+  create_issues:
+    description: 'Create/update deduplicated GitHub issues for findings (opt-in)'
+    default: 'false'
+  max_new_issues:
+    description: 'Cap on new issues created per run'
+    default: '5'
+  include:
+    description: 'Markdown glob'
+    default: '**/*.md'
+  out_dir:
+    description: 'Report output directory'
+    default: 'docgrity-report'
+runs:
+  using: 'node20'
+  main: 'bin/action.js'

package/action/bin/action.js

@@ -0,0 +1,71 @@
+/**
+ * GitHub Action entrypoint. Reads inputs from env (INPUT_*), runs the scan,
+ * writes the job summary + HTML report, and (opt-in) syncs deduplicated issues.
+ */
+import { mkdir, writeFile, appendFile } from 'fs/promises';
+import path from 'path';
+import { makeClient } from '../src/llm.js';
+import { runScan } from '../src/scan.js';
+import { renderReport, renderSummaryMarkdown } from '../src/report.js';
+import { syncIssues } from '../src/issues.js';
+
+const input = (name, fallback = '') =>
+  (process.env[`INPUT_${name.toUpperCase()}`] ?? fallback).toString().trim() || fallback;
+
+const root = process.env.GITHUB_WORKSPACE ?? process.cwd();
+const token = process.env.GITHUB_TOKEN ?? process.env.INPUT_GITHUB_TOKEN ?? '';
+const slug = process.env.GITHUB_REPOSITORY ?? '';
+const branch = (process.env.GITHUB_REF_NAME ?? 'main').replace(/^refs\/heads\//, '');
+
+try {
+  const client = makeClient({
+    provider: input('provider', 'github-models'),
+    apiKey: input('api_key'),
+    githubToken: token,
+  });
+
+  console.log(`Docgrity scan on ${slug} (${branch})`);
+  const { findings, stats } = await runScan(root, { client, log: (m) => console.log(m) });
+
+  // Opt-in issue sync (deduped by fingerprint, capped, auto-close resolved).
+  let issueResult = null;
+  if (input('create_issues', 'false') === 'true') {
+    if (!token) throw new Error('create_issues requires GITHUB_TOKEN with issues: write');
+    issueResult = await syncIssues({
+      client,
+      token,
+      slug,
+      findings,
+      maxNewIssues: Number(input('max_new_issues', '5')) || 5,
+      log: (m) => console.log(m),
+    });
+  }
+
+  // Static HTML report + raw findings.
+  const outDir = path.resolve(root, input('out_dir', 'docgrity-report'));
+  await mkdir(outDir, { recursive: true });
+  await writeFile(path.join(outDir, 'index.html'), renderReport({ findings, stats, repoSlug: slug, branch }));
+  await writeFile(path.join(outDir, 'findings.json'), JSON.stringify({ findings, stats }, null, 2));
+
+  // Job summary.
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    let summary = renderSummaryMarkdown({ findings, stats });
+    if (issueResult) {
+      summary += `\n\nIssues: ${issueResult.created.length} created, ${issueResult.closed.length} closed, ${issueResult.unchanged} unchanged${issueResult.skipped ? `, ${issueResult.skipped} skipped (cap)` : ''}.`;
+    }
+    await appendFile(process.env.GITHUB_STEP_SUMMARY, summary + '\n');
+  }
+
+  // Outputs.
+  if (process.env.GITHUB_OUTPUT) {
+    await appendFile(
+      process.env.GITHUB_OUTPUT,
+      `findings=${findings.length}\nreport_dir=${outDir}\n`
+    );
+  }
+
+  console.log(`Done: ${findings.length} finding(s). Report in ${outDir}`);
+} catch (err) {
+  console.error(`::error::Docgrity scan failed: ${err.message}`);
+  process.exit(1);
+}

package/action/bin/docgrity.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Docgrity local CLI — read-only. Runs a scan and produces the HTML report
+ * dashboard (findings, evidence, doc links, potential owners). Deliberately
+ * cannot raise issues or take any action: local scans observe, CI acts.
+ *
+ * Usage:
+ *   docgrity scan [--provider gemini|openai|anthropic|github-models] [--model m]
+ *                 [--dir .] [--out docgrity-report] [--open]
+ * Keys via env: DOCGRITY_API_KEY (BYO providers) or GITHUB_TOKEN (github-models).
+ */
+import { mkdir, writeFile, readFile } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execFile } from 'child_process';
+import { makeClient } from '../src/llm.js';
+import { runScan } from '../src/scan.js';
+import { renderReport } from '../src/report.js';
+import { githubRepoSlug, defaultBranch } from '../src/corpus.js';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) args[key] = argv[++i];
+      else args[key] = true;
+    } else args._.push(argv[i]);
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+const HELP = `docgrity — doc-integrity scans for repository markdown (read-only)
+
+Finds contradictions, duplicates, and open questions across your repo's
+markdown docs, and writes an HTML report + findings.json. The CLI never
+posts anything anywhere — it is report-only by design.
+
+Usage:
+  docgrity scan [options]
+
+Options:
+  --dir <path>            Directory to scan (default: .)
+  --out <path>            Report output directory (default: docgrity-report)
+  --open                  Open the HTML report when done
+
+  --checks <list>         Comma-separated checks to run (default: all)
+                          duplicates, contradictions, open-questions
+  --max-files <n>         Max markdown files to scan (default: 200)
+  --max-pairs <n>         Max document pairs to assess (default: 25)
+  --threshold-duplicate <0..1>       Min confidence, duplicates (default: 0.75)
+  --threshold-contradiction <0..1>   Min confidence, contradictions (default: 0.7)
+  --threshold-open-question <0..1>   Min confidence, open questions (default: 0.6)
+
+  --provider <p>          ollama | gemini | openai | anthropic | github-models
+                          (default: auto — see below)
+  --model <m>             Model name (provider-specific default otherwise)
+  --endpoint <url>        Ollama endpoint (default: http://localhost:11434,
+                          or DOCGRITY_OLLAMA_URL; supports tunnelled remotes)
+
+  --version, -v           Print installed version (and latest on npm)
+  --help, -h              Show this help
+
+Environment:
+  DOCGRITY_API_KEY        API key for gemini / openai / anthropic
+  DOCGRITY_OLLAMA_URL     Default Ollama endpoint
+  GITHUB_TOKEN / GH_TOKEN Token for the github-models provider
+
+Provider auto-detection (when --provider is omitted):
+  DOCGRITY_API_KEY set → gemini; else GITHUB_TOKEN set → github-models;
+  else → ollama (local, fully private).
+
+Examples:
+  docgrity scan --open
+  docgrity scan --checks contradictions
+  docgrity scan --checks duplicates,open-questions --max-pairs 10
+  docgrity scan --provider ollama --model llama3.1:8b
+  docgrity scan --provider gemini            # DOCGRITY_API_KEY=...
+  docgrity scan --dir ./docs --out /tmp/report --threshold-contradiction 0.8
+
+Docs: https://ujjavala.github.io/docgrity-vscode-site/
+`;
+
+async function localVersion() {
+  const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+  return JSON.parse(await readFile(pkgPath, 'utf8')).version;
+}
+
+async function latestVersion() {
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 3000);
+    const res = await fetch('https://registry.npmjs.org/docgrity/latest', { signal: ctrl.signal });
+    clearTimeout(t);
+    if (!res.ok) return undefined;
+    return (await res.json()).version;
+  } catch {
+    return undefined;
+  }
+}
+
+if (args.help || args.h || args._[0] === 'help') {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (args.version || args.v) {
+  const installed = await localVersion();
+  const latest = await latestVersion();
+  console.log(`docgrity ${installed}`);
+  if (latest && latest !== installed) {
+    console.log(`Latest on npm: ${latest} — update with: npm i -g docgrity`);
+  } else if (latest) {
+    console.log('Up to date.');
+  }
+  process.exit(0);
+}
+
+if (args._[0] !== 'scan') {
+  console.log(HELP);
+  process.exit(args._[0] ? 1 : 0);
+}
+
+const CHECK_NAMES = { duplicates: 'duplicates', contradictions: 'contradictions', 'open-questions': 'openQuestions' };
+function parseChecks(value) {
+  if (!value || value === true) return { duplicates: true, contradictions: true, openQuestions: true };
+  const checks = { duplicates: false, contradictions: false, openQuestions: false };
+  for (const name of String(value).split(',').map((s) => s.trim()).filter(Boolean)) {
+    const key = CHECK_NAMES[name];
+    if (!key) {
+      console.error(`docgrity: unknown check "${name}" (valid: ${Object.keys(CHECK_NAMES).join(', ')})`);
+      process.exit(1);
+    }
+    checks[key] = true;
+  }
+  return checks;
+}
+
+const numArg = (v, fallback) => (v === undefined || v === true ? fallback : Number(v));
+
+const root = path.resolve(args.dir ?? '.');
+const outDir = path.resolve(root, args.out ?? 'docgrity-report');
+const provider =
+  args.provider ??
+  (process.env.DOCGRITY_API_KEY ? 'gemini' : process.env.GITHUB_TOKEN || process.env.GH_TOKEN ? 'github-models' : 'ollama');
+const checks = parseChecks(args.checks);
+
+try {
+  const client = makeClient({
+    provider,
+    apiKey: process.env.DOCGRITY_API_KEY,
+    githubToken: process.env.GITHUB_TOKEN || process.env.GH_TOKEN,
+    model: args.model,
+    endpoint: args.endpoint,
+  });
+
+  const enabled = Object.entries(checks).filter(([, on]) => on).map(([k]) => k).join(', ');
+  console.log(`Docgrity local scan (read-only) — provider: ${provider}; checks: ${enabled}`);
+  const { findings, stats } = await runScan(root, {
+    client,
+    checks,
+    maxFiles: numArg(args['max-files'], 200),
+    maxPairs: numArg(args['max-pairs'], 25),
+    thresholds: {
+      duplicate: numArg(args['threshold-duplicate'], 0.75),
+      contradiction: numArg(args['threshold-contradiction'], 0.7),
+      openQuestion: numArg(args['threshold-open-question'], 0.6),
+    },
+    log: (m) => console.log(`  ${m}`),
+  });
+
+  const slug = await githubRepoSlug(root);
+  const branch = slug ? await defaultBranch(root) : undefined;
+  const html = renderReport({ findings, stats, repoSlug: slug, branch });
+
+  await mkdir(outDir, { recursive: true });
+  const reportPath = path.join(outDir, 'index.html');
+  await writeFile(reportPath, html);
+  await writeFile(path.join(outDir, 'findings.json'), JSON.stringify({ findings, stats }, null, 2));
+
+  console.log(`\n${findings.length} finding(s) across ${stats.docs} docs.`);
+  console.log(`Report: ${reportPath}`);
+  console.log('Note: local scans are read-only — review owners and evidence in the report; issues are only raised by CI (opt-in).');
+
+  if (args.open) execFile(process.platform === 'darwin' ? 'open' : 'xdg-open', [reportPath]);
+} catch (err) {
+  console.error(`docgrity: ${err.message}`);
+  process.exit(1);
+}