Verifiable claims and citations
Can it check my draft? Yes, in Markdown or LaTeX — a claim is a comment beside the prose it describes, checked against the run ledger for one of five verdicts, and a citation key is linted against your configured bibliography the same way.
Verifiable claims
A README says "MAE 0.353 eV vs experiment". That number was transcribed by hand and nothing checks it: re-run the benchmark and the document asserts 0.353 forever. A claim is an HTML comment beside the prose it describes, so the document renders exactly as before:
The cut leaves WER essentially unchanged (**0.053 vs 0.043** baseline).
<!-- claim: ablation/stack_4 metric=wer value=0.053 tol=0.001 -->
uv run attest claims ~/projects # verify every claim
uv run attest claims ~/projects --coverage # numbers no claim covers
Five verdicts, and the distinctions are the design. supported: a run agrees.
contradicted: a run disagrees — the document or the run is wrong.
unsupported: no run matches, so the claim may be true but nothing backs it.
ambiguous: a wildcard matched several runs, so which is meant is undecidable.
stale: the value matches but the artifact changed after as_of.
unsupported and contradicted never collapse together — one needs a run, the
other needs a correction. ambiguous exists because silently taking the first
of several matches is how a checker reports a confident wrong answer.
attest claims exits non-zero on a contradiction, so it can gate a commit.
A claim can also carry cite=<key>, and that key is linted too — uncited
when no configured .bib or Zotero source has it — from the CLI (attest
claims) as well as the cite.check / runs.claims_check MCP tools. It is a
lint ("no source has this key"), never "the paper does not support this
claim". See examples/citations/ for a worked run of both linters together.
Does the cited paper say it?
attest support draft.md (MCP: cite.support) is the check the lint is not.
For every citing sentence -- Pandoc [@key], a claim's cite=<key>, or LaTeX
\cite{key} -- it finds the paper in the library, reads the best text held
for it (full text from attest library fulltext, else the abstract, else the
title; reported as text_level), ranks the source's sentences against the
citing one, and returns supported, partially_supported, contradicted,
not_found or source_unavailable with a verbatim quote and a reason.
The judge is the local chat model (--judge auto, the default), falling back
to a deterministic check when none answers (--judge none forces it). Either
way, numbers are checked by code: a sentence that keeps the paper's number but
attaches it to something else -- "outperforms invariant models by up to three
orders of magnitude" against "up to three orders of magnitude fewer training
data" -- is contradicted even when the model says it is supported. Every
quote is checked to be an exact substring of the source. attest support
exits 1 on any contradicted (--fail-on widens the gate), like attest
claims; --sentence ... --cite KEY checks one sentence.
--coverage is the inverse, and the more useful half for adoption: a document
with zero contradicted claims can still assert a dozen unverifiable numbers.
Only decimals count as measurements — on a real index, 212 numbers reduce to 30
decimals and the decimals are the results.
LaTeX papers
A .tex source is a first-class document. A claim is a % comment with the
same body, on its own line or trailing the table row it backs; it compiles to
nothing and needs no package:
The best student reaches a WER of \num{0.0642}.
% claim: speech/kdsweep_t4 metric=wer value=0.0642
$T=2$ & 0.0701 & 0.023 \\ % claim: speech/kdsweep_t2 metric=wer value=0.0701
uv run attest claims paper/main.tex # the five verdicts, exit 1 on a contradiction
uv run attest claims paper/main.tex --coverage # numbers no claim covers
uv run attest claims paper/main.tex --citations # \cite keys the bibliography lacks
Pass the root file: \input, \include and \subfile are followed (a
cycle is read once), the whole tree is one document, and every finding names
its own file. \% is a percent sign, never a comment.
Coverage reads prose and table cells, \num{}, \SI{}{} and \qty{}{}, a
number alone in inline math ($0.021$, $12.2\%$), and 1{,}234.5 as
1234.5. It skips comments, equations and display math, math with a symbol in
it ($\alpha = 0.5$), \label/\ref/\cite arguments, package options,
and lengths (0.48\textwidth, 2pt).
cite.check (and attest claims --citations) reads every *cite* command —
\cite, \citep[see][p.~3]{a,b}, \citet, \citealp, \parencite,
\textcite, \autocite, \footcite, \cites{a}{b} — skipping natbib's
\setcitestyle/\citestyle. The candidate .bib files are those beside
the paper, ATTEST_BIB_PATHS, and the owner bibliography in ATTEST_BIB_OUT.
Once the paper names its files (\bibliography{refs}, \addbibresource{refs.bib})
a key resolves only in those, as BibTeX would read it; a key some other file
or the library defines is reported in missing_keys with
defined_in_unloaded, and a named file that does not exist in
unresolved_bib_resources. With no named file, any candidate, the library
store or Zotero resolves a key. A key two LOADED files both define is
reported in repeated_keys ({key, files, paper}; attest claims --citations
prints it as repeated without failing, since BibTeX builds with the first) --
the usual cause is saving or editing a paper from an uploaded .bib, which
puts the same key in the generated owner .bib. These rules match AgentMarkit's latex-paper
skill. tests/fixtures/latex/ is a three-file paper exercising all of it.
The library
One deduplicated store of references, filled by attest library sync (or the
cite.sync tool) from every configured source: the .bib files named in
ATTEST_BIB_PATHS (else any *.bib in the working directory), a Zotero
library at ATTEST_ZOTERO_PATH (else Zotero's default), and the feed's own
items that carry a DOI or arXiv id. The same paper from three sources is one
row with three source entries, each recording what that source offered and
when. Identity is a pure rule: DOI, else versionless arXiv id, else the
normalised title and year. Merging fills empty fields and keeps the first value
of a disagreement, recording the conflict on the source that offered it, so
cite.lookup can show a disagreement rather than lose it.
Three flags reach off the machine. ATTEST_CITATION_WEB (arXiv and CrossRef:
abstracts, authors, venues) and ATTEST_CITATION_SCHOLAR (Semantic Scholar
reference lists, one request every three seconds, cached forever) are both
off by default and read only when the readers are built; they fill fields on
references the library already holds and never add a paper on their own.
ATTEST_RESEARCH_WEB is the opposite default -- on unless set to 0 -- and
governs feed.research, research: topic feeds, and attest library
fulltext: the one path that introduces a reference from the wire rather
than filling one that is already there. cite.sources says which are live.
uv run attest library sync # read every source; embed what it can
uv run attest library search "equivariant force fields"
uv run attest library search "" --author batzner --year 2022
uv run attest library tag --limit 50 # a model call per reference, ~2.3s each
uv run attest library status
Search is semantic when the library is embedded (the model server was
reachable during sync or library embed) and substring otherwise, and the
output says which — the cite.search tool carries the same semantic flag
and caveat. cite.check and attest claims resolve cite=<key> through
the store first, so a key synced from Zotero resolves even when no .bib sits
in the working directory. See docs/superpowers/specs/2026-09-05-library-store-design.md.
attest library fulltext pulls bodies (arXiv PDF, or PMC open-access XML by
PMCID) for references that have none, ten per run by default and also at the
end of attest ingest; cite.lookup serves them in 2000-character windows,
never whole, and never embeds them. attest library export --bib refs.bib
[--author A] [--year Y] [--tag T] [--source S] writes a filtered set as
BibTeX rendered from the rows -- @article for a journal, @misc with
eprint/archivePrefix for a preprint, the .bib key when one supplied it,
else <family><year><word> -- refusing to overwrite without --force.
cite.lookup returns the same bibtex for one record.
Formatting (APA, IEEE, Chicago, Nature, Vancouver), owner edits, notes, tags,
duplicate merging and .bib import are the citation manager's: attest bib
and cite.format, in The citation manager.
References join the concept graph through their tags — from attest library
tag, or from a .bib keywords field — and attest library related KEY
(the cite.related tool) walks a paper's citation edges both ways, from
Semantic Scholar reference lists or a .bib cites field
(identity|title; identity|title); a cited paper not in the library is
listed, never fetched. examples/molecular-ai/ shows both from a committed
.bib that real software generated from real papers. See
docs/superpowers/specs/2026-09-05-library-graph-and-molecular-ai-design.md.