veriquote 0.1.1 → 0.2.1

package/CITATION.cff

@@ -9,11 +9,12 @@ authors:
     orcid: "https://orcid.org/0009-0009-5596-736X"
 repository-code: "https://github.com/rickintoplace/veriquote"
 license: MIT
-version: 0.1.1
+version: 0.2.1
 identifiers:
   - type: doi
-    value: 10.5281/zenodo.21552380
-date-released: "2026-07-25"
+    value: 10.5281/zenodo.21552379
+    description: Concept DOI, resolves to the latest version
+date-released: "2026-09-22"
 keywords:
   - large language models
   - retrieval-augmented generation

package/README.md

@@ -1,69 +1,59 @@
 # VeriQuote
 
-**Deterministic + semantic verification of quote-grounded LLM citations.**
+[![npm](https://img.shields.io/npm/v/veriquote)](https://www.npmjs.com/package/veriquote)
 [![DOI](https://zenodo.org/badge/1311867832.svg)](https://doi.org/10.5281/zenodo.21552379)
 
-VeriQuote makes source-grounded assistant answers *auditable*. Instead of
-trusting that a `[1]` citation means anything, the answering model must attach
-a **verbatim quote** for every cited claim, and VeriQuote then checks per
-claim whether:
-
-1. the quote **actually occurs in the source** (deterministic fuzzy text
-   matching with a percent score), and
-2. the quote **actually supports the claim** (a small, temperature-0 LLM judge
-   classifying entailment strength).
-
-The result is a transparent, per-citation report telling users exactly which
-statements are verbatim-backed and supported, which are overstated, and which
-are unsupported or confabulated.
-
-VeriQuote is extracted from and battle-tested in
-[NavigNine](https://navignine.com), a source-grounded research assistant,
-which serves as the reference deployment.
+**Make an LLM quote its sources, then check every quote twice: is it really in
+the source, and does it support the claim?**
+
+A `[1]` after a sentence looks like evidence, but almost nobody checks it. In
+my tests, a fifth of one capable model's "verbatim" quotes were not in the
+source, another model left two thirds of its cited answers with at least one
+citation that had nothing behind it, and an LLM judge happily confirmed a quote
+that was invented. VeriQuote makes the answering model commit to a verbatim
+quote for every citation, then verifies each one: deterministically where
+possible, with an LLM only where it has to. It is written in TypeScript, has no
+dependencies and runs in Node and in the browser.
+
+**Try it in the browser:** [rickinto.place/veriquote](https://rickinto.place/veriquote)
+has eight worked examples, a box for your own text, and the benchmark results as
+interactive charts.
+
+```console
+$ curl -s https://raw.githubusercontent.com/rickintoplace/veriquote/main/examples/ozone-answer.md \
+    | npx veriquote check - --source https://en.wikipedia.org/wiki/Ozone_layer
+
+4 citation(s) · 1 source(s) · judge: glm-5.3-flash
+
+✓ c1 [1]  verbatim 1.00 · entailed 1.00
+    The ozone layer absorbs 97 to 99 percent of the Sun's medium-frequency ultraviolet light.
+✗ c2 [1]  verbatim 1.00 · contradicted 0.00
+    It was discovered in 1913 by the British meteorologist G. M. B. Dobson.
+    Quote credits Fabry and Buisson, not Dobson
+✗ c3 [1]  fuzzy 0.48 · contradicted 0.00
+    Under the Montreal Protocol, all CFC production was banned immediately in 1987.
+    Context says production capped at 1986 levels, not banned; Quote absent from context; appears fabricated
+✗ c4 [1]  quote not in source (best 0.31) · entailed 0.90
+    The treaty limited CFC production to the levels of 1986.
+    the quoted text does not occur in the source
+! uncited  Ozone depletion has since been fully reversed in every region of the atmosphere.
+
+REVISE — 3 failed citation(s), 1 uncited sentence(s)
+```
 
-- **Zero runtime dependencies.** Runs in Node ≥ 18, browsers, and edge runtimes.
-- **Deterministic by construction.** The text matcher is pure; the judge runs
-  at temperature 0 with a closed class vocabulary and strict output validation.
-- **Model-agnostic.** Works with any answering model and any OpenAI-compatible
-  chat-completions endpoint for the judge (OpenAI, OpenRouter, Azure, local
-  gateways) or bring your own `EntailmentJudge` (e.g. a local NLI model).
+Look at `c2` and `c4`. The quote in `c2` is copied correctly, but the claim
+names the wrong person; only the judge can see that. The quote in `c4` is made
+up, and the judge still calls it supported; only the matcher can see that.
+Without an API key the CLI checks the quotes alone. Set
+`VERIQUOTE_JUDGE_API_KEY` and `VERIQUOTE_JUDGE_MODEL` (any OpenAI-compatible
+endpoint) to add the judge.
 
 ## How it works
 
-```
-                        ┌───────────────────────────┐
-  numbered sources ───► │  Answering LLM            │
-  + citation prompt     │  (any model)              │
-                        └────────────┬──────────────┘
-                                     │  answer body with [n]{cX} markers
-                                     │  + EVI1 quote appendix
-                                     ▼
-                        ┌───────────────────────────┐
-                        │ 1. parseAnswer()          │  claims, quotes, protocol
-                        │    (deterministic)        │  completeness warnings
-                        └────────────┬──────────────┘
-                                     ▼
-                        ┌───────────────────────────┐
-                        │ 2. Quote ↔ source match   │  exact / normalized /
-                        │    (deterministic, fuzzy) │  fuzzy %, offsets
-                        └────────────┬──────────────┘
-                                     ▼
-                        ┌───────────────────────────┐
-                        │ 3. Entailment judge       │  entailed / partially /
-                        │    (LLM, temp 0, optional)│  overstated / insufficient
-                        └────────────┬──────────────┘  / contradicted + conf.
-                                     ▼
-                        ┌───────────────────────────┐
-                        │ 4. VerificationReport     │  per-citation scores +
-                        │    (transparency for user)│  answer-level summary
-                        └───────────────────────────┘
-```
-
-### The EVI1 protocol
-
-The answering model is instructed (via `buildCitationInstructions()`) to end
-every cited sentence with citation markers and a claim marker, and to append a
-machine-readable quote appendix:
+The answering model gets the output of `veriquote prompt` (or
+`buildCitationInstructions()`) in its system prompt. Every cited sentence then
+ends with source and claim markers, and the answer ends with a plain-text quote
+appendix:
 
 ```
 Vitamin D supplementation reduced fall risk in older adults.[1]{c1}
@@ -76,51 +66,178 @@ c2|3|"BMD improved with \"high-dose\" regimens"
 END_EVI1
 ```
 
-The protocol is intentionally plain text (not JSON): it survives streaming,
-markdown renderers, and weak models. And `[n]` citations remain human-readable
-even if a client ignores VeriQuote entirely.
-
-### Why two checks?
+The format is plain text rather than JSON, so it survives streaming, Markdown
+renderers and weak models, and the `[n]` markers stay readable if nothing
+checks them. Each citation then goes through three steps:
+
+1. **Parse.** Every cited claim must carry a quote. Missing quotes are reported.
+2. **Match.** Is the quote in the source? Deterministic fuzzy matching that
+   tolerates whitespace, typography, OCR noise and elisions, and reports where
+   the quote was found.
+3. **Judge.** Does the quote support the claim? An LLM at temperature 0 answers
+   `entailed`, `partially_entailed`, `overstated`, `insufficient` or
+   `contradicted`, with a support score.
+
+A citation's combined score is the lower of its match score and its support
+score. A judge error can therefore never lift a citation above what the matcher
+found, and a failed judge call is reported as an error, never counted as
+support. Quoting does not make a model hallucinate less. It makes every claim
+checkable, which is the point.
+
+## Benchmarks
+
+There are three benchmarks, kept separate on purpose: one blended number for a
+two-stage pipeline would hide exactly the failures it exists to separate.
+Everything is in [`bench/`](bench), including how to reproduce it.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rickintoplace/veriquote/main/bench/figures/tango-dark.svg">
+  <img alt="The matcher blocks all 187 quotes that are not in the source and none of the 586 real quotes whose meaning was changed; the judge blocks 84% of unsupported citations and never sees the source; together they cover both kinds of failure." src="https://raw.githubusercontent.com/rickintoplace/veriquote/main/bench/figures/tango-light.svg">
+</picture>
+
+The two checks are blind in opposite places. The matcher never reads the claim,
+so it cannot tell whether a real quote supports it. The judge never sees the
+source, so an invented quote that fits the claim passes it: in the example
+above, the judge rates the made-up quote in `c4` as "entailed 0.90".
+
+### Matcher
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rickintoplace/veriquote/main/bench/figures/matcher-dark.svg">
+  <img alt="Matcher score ranges for fifteen kinds of quote damage: faithful quotes score between 0.66 and 1.0, quotes that are not in the source between 0.14 and 0.40, and quotes whose meaning was changed score high because they are still near-verbatim." src="https://raw.githubusercontent.com/rickintoplace/veriquote/main/bench/figures/matcher-light.svg">
+</picture>
+
+The matcher benchmark needs no API key and no labels, because the right answer
+is known by construction: 2,061 quotes built from five Wikipedia articles, then
+copied faithfully, reformatted, altered or replaced in fifteen different ways. `npm run bench:matcher` reproduces it in
+about two seconds. Faithfully copied quotes never score below 0.660, quotes
+that are not in the source never above 0.396, and the default threshold of 0.4
+sits in that gap. The amber rows are there on purpose: a quote whose meaning was
+changed is still near-verbatim, and catching it is the judge's job.
+
+There are two honest limits. Invented prose built from the source's own words
+(an adversarial case) scores high, and so can a hand-written fabrication that
+reuses the source's vocabulary, like `c3` above at 0.48. The CLI therefore
+fails every citation below 0.5 and leaves the rest to the judge.
+
+### Judge
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rickintoplace/veriquote/main/bench/figures/judges-dark.svg">
+  <img alt="Five open judge models against the human labels of ALCE: they catch between 75% and 84% of unsupported citations, and agree with the annotators on 76.7% to 80.3% of pairs, around the 77.6% of the TRUE NLI model." src="https://raw.githubusercontent.com/rickintoplace/veriquote/main/bench/figures/judges-light.svg">
+</picture>
+
+The judge is measured against the human annotators of ALCE[^alce], with the
+mapping from VeriQuote's classes to ALCE's labels fixed before any model ran.
+*Caught* is the share of citations the annotators marked as unsupported that
+the judge did not call fully supported. On ALCE's yes-or-no question ("does the
+source fully support the claim?"), general-purpose open models agree with the
+annotators about as often as TRUE[^true], the specialised 11B NLI model that
+ALCE uses for its own automatic scores (77.6%). The best of them, `glm-5.3-flash`,
+reaches Cohen's κ 0.53 on the three-way labels (full, partial or no support).
+For comparison, ALCE reports κ 0.525 between its automatic metric and the
+annotators on citation precision.
+
+Before trusting any of this, look at the left panel: even the best judge lets
+one unsupported citation in six through as fully supported. No judge should be
+the only check. With only 56 unsupported pairs per run the intervals are wide,
+so neighbouring models are not really separated. Reasoning helps: with it
+switched off, all three hybrid models catch less and agree less, in exchange
+for answering five to ten times faster.
+
+### Answering models
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rickintoplace/veriquote/main/bench/figures/protocol-dark.svg">
+  <img alt="Protocol compliance for eight answering models: qwen3.6, qwen3.5, deepseek-v4-flash and glm-5.3-flash are close to 100% complete and verbatim; gpt-oss-120b is complete in 33.3% of answers; mistral-medium quotes verbatim in 81.0% of citations; llama-3.1-8b manages about half." src="https://raw.githubusercontent.com/rickintoplace/veriquote/main/bench/figures/protocol-light.svg">
+</picture>
+
+Each model answered 18 questions twice, with the citation instructions in its
+system prompt, and `parseAnswer()` decided mechanically whether it complied.
+Every raw answer is in
+[`bench/results/protocol-answers.jsonl`](bench/results/protocol-answers.jsonl).
+The open models recommended here comply almost perfectly. The failures of the
+others are invisible to a reader: `gpt-oss-120b` almost always prints an
+appendix, yet only a third of its answers give every citation a quote, and
+`mistral-medium` is nearly always complete, yet a fifth of its "quotes" are
+paraphrases. Both answers look impeccably cited. On the three questions the
+sources cannot answer, no model attached a citation without a real quote.
+
+<details>
+<summary>The numbers behind the figures</summary>
+
+| judge model | caught ↑ | agreement | Cohen's κ |
+| --- | ---: | ---: | ---: |
+| `glm-5.3-flash` | 83.9% | 80.3% | 0.529 |
+| `deepseek-v4-flash` | 81.8% | 78.7% | 0.435 |
+| `qwen3.6-35b-a3b` | 81.8% | 78.1% | 0.454 |
+| `qwen3.5-397b-a17b` | 79.2% | 79.7% | 0.483 |
+| `gpt-oss-120b` | 75.0% | 76.7% | 0.394 |
+| `qwen3.5-397b-a17b`, no reasoning | 78.6% | 77.7% | 0.410 |
+| `qwen3.6-35b-a3b`, no reasoning | 78.6% | 77.3% | 0.397 |
+| `glm-5.3-flash`, no reasoning | 75.6% | 74.0% | 0.373 |
+| TRUE (T5-11B), as reported by ALCE[^alce] | | 77.6% | |
+
+| quote family | n | median score | accepted at 0.4 |
+| --- | ---: | ---: | ---: |
+| faithful but reformatted | 1,121 | 1.000 | 100.0% |
+| near-verbatim, meaning changed | 586 | 0.932 | 100.0% |
+| not in the source | 187 | 0.249 | 0.0% |
+
+| answering model | appendix | complete | verbatim | warning-free |
+| --- | ---: | ---: | ---: | ---: |
+| qwen3.6-35b-a3b | 100.0% | 100.0% | 100.0% | 100.0% |
+| qwen3.5-397b-a17b | 100.0% | 100.0% | 100.0% | 100.0% |
+| deepseek-v4-flash | 100.0% | 100.0% | 99.2% | 93.3% |
+| glm-5.3-flash | 96.6% | 96.6% | 99.6% | 96.6% |
+| gemma-4-31b-it | 80.0% | 80.0% | 96.6% | 80.0% |
+| mistral-medium-3.5-128b | 96.7% | 93.3% | 81.0% | 96.7% |
+| gpt-oss-120b | 96.7% | 33.3% | 91.1% | 33.3% |
+| llama-3.1-8b-instruct | 66.7% | 43.3% | 50.3% | 20.0% |
+
+The figures are rendered from `bench/results/*.json` by
+[`bench/figures/render.mjs`](bench/figures/render.mjs).
+</details>
+
+## Use from an agent
+
+An agent that reads sources and writes conclusions is exactly the case
+VeriQuote was built for. [`verify-citations`](integrations/verify-citations) is
+an [Agent Skill](integrations/verify-citations/SKILL.md) that has the agent
+write its sourced answer in the checkable format and run `veriquote check` on
+it before showing it to you. The CLI fetches every cited URL itself, so the
+agent cannot pass with its own truncated or misremembered copy of a page. The
+exit code tells the agent what to do next without parsing anything:
 
-The two checks fail independently, and both failure modes occur in practice:
-
-- A quote can be **verbatim yet irrelevant**: the model copied real text that
-  doesn't support its claim (scope drift, outcome switching, overstatement).
-  Text match passes; the entailment judge catches it.
-- A quote can be **paraphrased or fabricated**: the claim may even be true,
-  but the "quote" is not in the source. The entailment judge might pass; the
-  deterministic matcher catches it, with a percent score that distinguishes
-  light paraphrase (high fuzzy score) from fabrication (low score).
+```
+exit 0  verdict "pass"    every cited claim is grounded     -> present the answer
+exit 2  verdict "revise"  problems[] + instructionsForModel -> fix and re-check
+exit 1  bad input or unreachable source -> do NOT claim the answer was verified
+```
 
-The combined per-citation score is conservative:
-`min(textMatchScore, judgeConfidence)`.
+The skill works in any host that reads Agent Skills, such as Claude Code, and
+the CLI in anything that can run a shell command.
 
-## Installation
+## Use as a library
 
 ```bash
 npm install veriquote
 ```
 
-## Quickstart
-
-### 1. Prompt the answering model
-
 ```ts
 import { buildCitationInstructions } from 'veriquote';
 
 const systemPrompt = `${yourAssistantPrompt}\n\n${buildCitationInstructions()}`;
-// Provide sources as numbered blocks [1], [2], ... in the user/context prompt.
+// Give the sources to the model as numbered blocks [1], [2], …
 ```
 
-### 2. Verify the raw answer
-
 ```ts
 import { ChatCompletionsJudge, verifyAnswer } from 'veriquote';
 
 const judge = new ChatCompletionsJudge({
   baseUrl: 'https://openrouter.ai/api/v1',   // any OpenAI-compatible endpoint
   apiKey: process.env.OPENROUTER_API_KEY,    // server-side only!
-  model: 'google/gemini-2.5-flash-lite',
+  model: 'your-judge-model',                 // pick one with bench/judge
 });
 
 const report = await verifyAnswer({
@@ -129,7 +246,7 @@ const report = await verifyAnswer({
     { title: 'Trial A', url: 'https://…', text: extractedFullText1 },
     { title: 'Trial B', url: 'https://…', text: extractedFullText2 },
   ],
-  judge,                           // omit for text-match-only verification
+  judge,                           // omit to check the quotes only
 });
 
 console.log(report.summary);
@@ -142,82 +259,99 @@ for (const c of report.citations) {
 }
 ```
 
-`report.cleanText` is the answer with all `{cX}` markers removed, ready to
-render (the `[n]` markers remain as human-readable citations).
-
-### 3. Show it to the user
-
-Render each citation's `textMatch.score` (percent), `entailment.class`, and
-combined `score` next to the footnote — e.g. green/yellow/red per claim. This
-is exactly what the NavigNine UI does with tooltips and colored footnotes.
-
-## API overview
+`report.cleanText` is the answer without the `{cX}` markers, ready to render.
+Show each citation's match score, judge class and combined score next to its
+footnote, so a reader can see which sentence carries weight without opening a
+single source.
 
 | Export | Purpose |
 | --- | --- |
-| `buildCitationInstructions(options?)` | Prompt block for the answering model (budgets and quote-length rules configurable). |
-| `verifyAnswer(options)` | Full pipeline: parse → match → judge → report. |
-| `parseAnswer(answer)` | Parse claims, evidence, and protocol warnings without verifying. |
-| `parseEvi1Appendix` / `stripEvi1Appendix` / `serializeEvi1Appendix` | Low-level EVI1 handling. |
-| `matchQuoteAgainstSource(quote, source, options?)` | Deterministic quote matching on its own. |
-| `ChatCompletionsJudge` | Entailment judge for any OpenAI-compatible API. |
-| `EntailmentJudge` (interface) | Bring your own judge (local NLI model, other provider). |
-
-All inputs and outputs are plain, serializable data — see
-[`src/types.ts`](src/types.ts) for the complete, documented data model and
-[`docs/DESIGN.md`](docs/DESIGN.md) for the method description (scoring,
-thresholds, and design rationale).
-
-### Entailment classes
-
-| Class | Confidence band | Meaning |
+| `buildCitationInstructions(options?)` | Prompt block for the answering model; budgets and quote lengths are configurable. |
+| `verifyAnswer(options)` | The full pipeline: parse, match, judge, report. |
+| `parseAnswer(answer)` | Claims, quotes and protocol warnings, without verifying anything. |
+| `parseEvi1Appendix` / `stripEvi1Appendix` / `serializeEvi1Appendix` | Low-level handling of the appendix. |
+| `matchQuoteAgainstSource(quote, source, options?)` | The deterministic matcher on its own. |
+| `ChatCompletionsJudge` | Judge for any OpenAI-compatible API. |
+| `EntailmentJudge` (interface) | Bring your own judge, such as a local NLI model. |
+| `gateReport(report, answer)` | Pass or revise, the list of problems, uncited sentences and a correction prompt. |
+| `fetchSource(url)` / `htmlToText(html)` | Fetch a source independently of the model and extract its text. |
+
+All inputs and outputs are plain, serializable data. See
+[`src/types.ts`](src/types.ts) for the data model and
+[`docs/DESIGN.md`](docs/DESIGN.md) for scoring and thresholds.
+
+| Class | Support score | Meaning |
 | --- | --- | --- |
-| `entailed` | 0.9–1.0 | Claim fully covered by the quote. |
-| `partially_entailed` | 0.5–0.8 | Core message supported, details missing. |
-| `overstated` | 0.3–0.6 | Claim stronger/more general than the evidence. |
-| `insufficient` | 0.1–0.4 | Related but does not confirm the claim. |
-| `contradicted` | 0.0 | Evidence says the opposite. |
-| `error` | — | Judge unavailable for this item (never silently dropped). |
+| `entailed` | 0.9–1.0 | The quote fully covers the claim. |
+| `partially_entailed` | 0.5–0.8 | The core is supported, details are missing. |
+| `overstated` | 0.3–0.6 | The claim is stronger or more general than the quote. |
+| `insufficient` | 0.1–0.4 | The quote is related but does not confirm the claim. |
+| `contradicted` | 0.0 | The quote says the opposite. |
+| `error` | none | The judge failed for this item; it is reported, never dropped. |
+
+## How this differs from the alternatives
+
+| | verbatim quote checked | claim↔evidence checked | model-agnostic | runtime |
+| --- | --- | --- | --- | --- |
+| **VeriQuote** | yes, deterministic | yes, pluggable judge | yes | TypeScript, no dependencies, browser and edge |
+| [Anthropic Citations API](https://platform.claude.com/docs/en/build-with-claude/citations) | not needed: spans are extracted, so they are real by construction | no | Claude only | hosted |
+| [LettuceDetect](https://github.com/KRLabsOrg/LettuceDetect) | no quote protocol | yes, span-level model | yes | Python and model weights |
+| [RAGAS](https://github.com/explodinggradients/ragas) and eval frameworks | no | yes, as an offline metric | yes | Python, offline evaluation |
+
+**Use the Citations API instead** if you are on Claude and only need to know
+that a span is real. It guarantees that by construction, which is stronger than
+any matcher. It does not tell you whether the span supports the sentence built
+on it; for that, pair it with VeriQuote's judge and skip the matcher.
+
+**Use LettuceDetect instead** if you want unsupported spans flagged in an
+answer that follows no citation protocol at all, and you are happy to run a
+model in Python. It solves the problem after the fact; VeriQuote changes what
+the answering model commits to in the first place.
+
+VeriQuote's own niche is narrow, and worth stating plainly: you want the
+answering model pinned to a quote *before* it writes, you want the
+deterministic half of the check to run anywhere, including a browser, and you
+want per-claim results you can show a reader rather than one score on a
+dashboard.
+
+The closest related work is a recent study by Zhang et al.[^zhang], which
+evaluates the same design (inline verbatim quotes, tiered verbatim matching and
+an LLM judge) on clinical guidelines. It found that `claude-opus-5` quoted
+verbatim for 98.0% of its claims but fully substantiated only 37.1% of them.
+VeriQuote is the reusable library, CLI and agent skill for that kind of check,
+with its judge measured against human labels.
 
 ## Security
 
-- **Keep the judge server-side.** `ChatCompletionsJudge` needs an API key;
-  never instantiate it in a browser. Expose a thin authenticated endpoint that
-  calls `verifyAnswer` instead.
-- **Prompt-injection hardening.** Source text is untrusted. Judge inputs are
-  length-capped, stripped of control characters and HTML, and the judge prompt
-  pins them as data ("never instructions"). Output is validated against a
-  closed vocabulary; unknown classes, out-of-range confidences, and
-  hallucinated item IDs are rejected.
-- **No dynamic evaluation.** Tolerant JSON recovery is a string-aware scanner;
-  nothing is ever `eval`ed.
-- **Failure transparency.** Judge failures degrade to `class: "error"` with a
-  `null` score — they are reported, never counted as "supported".
+- **Keep your key on the server.** `ChatCompletionsJudge` needs an API key; in
+  your own app, call `verifyAnswer` from a backend. The demo runs the judge in
+  the browser only with a key the visitor enters.
+- **Source text is untrusted.** Judge inputs are length-capped, stripped of
+  control characters and HTML, and marked as data in the prompt. The judge's
+  output is checked against a closed vocabulary: unknown classes, out-of-range
+  scores and invented item IDs are rejected. Nothing is ever `eval`ed.
 
 ## Reproducibility
 
-For a fixed answer, fixed sources, and a fixed judge model, results are
-reproducible: the matcher is pure, and the judge runs at temperature 0 (pass
-`seed` for providers that support it). Note that hosted LLM APIs are
-best-effort deterministic; for strict reproducibility, pin the model version
-or use a self-hosted judge behind the `EntailmentJudge` interface.
-
-## Integrations
-
-- **[`verify-citations`](integrations/verify-citations/)**: a portable
-  [Agent Skill](integrations/verify-citations/SKILL.md) (single `SKILL.md` +
-  bundled Node CLI) that runs VeriQuote as an **internal hallucination gate**
-  for source-grounded agents: it verifies a cited answer, flags factual
-  sentences that carry no citation, and returns a ready-to-use correction
-  prompt for a self-correction loop. The same skill works across any
-  Agent-Skills host (OpenClaw, Hermes Agent, Claude Code) and any orchestrator
-  that can run a Node CLI.
+The matcher is pure: the same inputs always give the same score. The judge
+runs at temperature 0 (pass `seed` where the provider supports it), but hosted
+models are only deterministic on a best-effort basis. For strict
+reproducibility, pin the model version or put a self-hosted model behind the
+`EntailmentJudge` interface.
 
 ## Citing
 
-If you use VeriQuote in academic work, please cite the Zenodo record (see
-`CITATION.cff`).
+If you use VeriQuote in academic work, please cite it[^veriquote]; the details
+are also in [`CITATION.cff`](CITATION.cff).
 
 ## License
 
 [MIT](LICENSE)
+
+[^alce]: Gao, T., Yen, H., Yu, J., & Chen, D. (2023). Enabling large language models to generate text with citations. In *Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing* (pp. 6465–6488). Association for Computational Linguistics. https://doi.org/10.18653/v1/2023.emnlp-main.398
+
+[^true]: Honovich, O., Aharoni, R., Herzig, J., Taitelbaum, H., Kukliansy, D., Cohen, V., Scialom, T., Szpektor, I., Hassidim, A., & Matias, Y. (2022). TRUE: Re-evaluating factual consistency evaluation. In *Proceedings of the 2022 Conference of the North American Chapter of the Association for Computational Linguistics: Human Language Technologies* (pp. 3905–3920). Association for Computational Linguistics. https://doi.org/10.18653/v1/2022.naacl-main.287
+
+[^zhang]: Zhang, J., Chen, Y., Commodore-Mensah, Y., & Oberst, M. (2026). *Verifiable by construction: Claim-level evaluation of verbatim citation in clinical question answering* (Version 2) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2609.15964
+
+[^veriquote]: Heilmann, E. (2026). *VeriQuote: Deterministic and semantic verification of quote-grounded LLM citations* (Version 0.2.1) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21552379

package/bin/veriquote.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Thin process wrapper; the command logic lives in src/cli/main.ts.
+import { readFile } from 'node:fs/promises';
+import { main } from '../dist/cli/main.js';
+
+async function readStdin() {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+process.exitCode = await main({
+  argv: process.argv.slice(2),
+  env: process.env,
+  stdout: (s) => process.stdout.write(s),
+  stderr: (s) => process.stderr.write(s),
+  readFile: (path) => readFile(path, 'utf8'),
+  readStdin,
+  version: pkg.version,
+  color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
+});

package/dist/cli/main.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `veriquote` command line. Kept free of `process` so it can be tested with
+ * injected I/O; `bin/veriquote.mjs` wires it to the real process.
+ */
+import type { EntailmentJudge } from '../types.js';
+export interface CliIo {
+    argv: string[];
+    env: Record<string, string | undefined>;
+    stdout: (s: string) => void;
+    stderr: (s: string) => void;
+    readFile: (path: string) => Promise<string>;
+    readStdin: () => Promise<string>;
+    fetch?: typeof globalThis.fetch;
+    version: string;
+    /** Use ANSI colors in human output. */
+    color: boolean;
+    /** Test hook: replaces the env-configured judge. */
+    judge?: EntailmentJudge;
+}
+export declare const EXIT: {
+    readonly pass: 0;
+    readonly error: 1;
+    readonly revise: 2;
+};
+export declare function main(io: CliIo): Promise<number>;
+//# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAsC,MAAM,aAAa,CAAC;AAOvF,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,eAAO,MAAM,IAAI;;;;CAA4C,CAAC;AAkG9D,wBAAsB,IAAI,CAAC,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAgCrD"}