proofpath 0.1.0__tar.gz → 0.2.0__tar.gz

proofpath-0.2.0/.gitattributes

@@ -0,0 +1,3 @@
+# Test fixtures whose bytes are pinned by a digest must not be CRLF-converted.
+tests/data/*.json text eol=lf
+tests/data/*.jsonl text eol=lf

{proofpath-0.1.0 → proofpath-0.2.0}/CHANGELOG.md

@@ -6,6 +6,128 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-15
+
+The interactive front-end, author-year citations, SARIF output and a cache for the
+two lookups that made a warm re-run slow. Bare `proofpath` now opens the TUI; the
+one-shot verbs are unchanged for CI. Live checks in `docs/eval/2026-09-15-v0.2-live.md`.
+
+### Added
+- **TUI** (spec §13.1): bare `proofpath` opens a `textual` session — a four-line banner
+  with the pet, one prompt bar, and a scrolling log of run blocks. Every CLI verb is a
+  slash command (`/check`, `/resolve`, `/fetch`, `/config`, `/cache`; plus `/allow`,
+  `/cancel #n`, `/help`, `/quit`), a bare verb waits for its argument (`Esc` leaves
+  it), and a line that is not a command is something to check. Runs are scheduled
+  concurrently through one `Scheduler` (network stages in parallel under a shared
+  politeness limiter, the NLI model one run at a time), each run is **cancellable**
+  mid-flight and keeps what it had decided, the coverage footer never scrolls away,
+  and the §7.1 permission prompt is drawn **inline under the stage that hit the wall**
+  with `[allow once] [always] [no] [never]` buttons (or `/allow …`). Every log line
+  works by mouse and by keyboard: run headers fold, stage rows hide their summary,
+  findings open the full quoted passage, `⧉`/`c` copies it, a finding's reference is
+  an OSC 8 link to its source. The pet's eyes blink, watch a run and react to its
+  result — only with colour, never under `--no-color` or `-q`.
+- **Author-year citations** (spec §9, §17): `(Smith et al., 2020)`, `Smith (2020)`,
+  `(Smith, 2020; Jones, 2019)`, `2020a`/`2020b` collisions, `ibid.` and `op. cit.`
+  back-references, and mixed `(Smith, 2020; [12])` all pair with their bibliography
+  entry. Hand-built set of 55 passages, 83 expectations, rate **0.940**
+  (`docs/eval/2026-09-12-pairing-author-year.md`); the numeric set is unchanged at
+  108/109. A marker no entry matches is reported as `UNRESOLVED MARKER`, never guessed.
+- **`check --format sarif`** (spec §13.2): the run as a SARIF 2.1.0 log for VS Code or
+  any SARIF 2.1.0 viewer — one result per finding on its line, the quoted passage in
+  the message of every asserting result, the exact honesty state in `properties`, and
+  the run's coverage in `runs[0].properties`. `--out FILE` writes the same document.
+  Validated against the schemastore schema, vendored in
+  `tests/data/sarif-schema-2.1.0.json`; not yet exercised against GitHub code scanning.
+- **Resolution and retraction cache** (cache schema v3): `resolutions` (30-day TTL,
+  keyed by the marker-free folded entry) and `retractions` (30 days for a notice, 7
+  for its absence). Neither an `UNVERIFIED (provider unavailable)` nor a retraction
+  check every provider failed is ever stored. A warm re-run of the seven-reference
+  draft: **1.35 s** wall clock, 0 network calls (v0.1: 15.8 s). `proofpath cache`
+  counts both tables.
+- The §7.1 aggregate line `skipped N source(s) because the browser was not permitted`
+  is printed by `check` too (terminal and markdown), never dropped by `-q`.
+- `browser_binary_present()`: the consent gate checks for a chromium build under
+  `PLAYWRIGHT_BROWSERS_PATH` or the platform default, so a half-installed environment
+  runs the idempotent installer instead of failing inside the fetch; the consent log
+  gains `browser binary: found|missing`.
+- `commands.py`: the shared wiring behind every mirrored verb (`resolve_reference`,
+  `fetch_target`, `config_*`, `cache_*`) returns result objects and never prints, so
+  `cli.py` and the TUI can only differ in how a result is drawn.
+- Bibliography fallback for PDFs without a `References` heading (paged formats):
+  the last contiguous run of numbered paragraphs is read as the list. AlphaFold:
+  0 → 17 references found, 97 markers now reported as unresolved instead of invisible.
+- Resolver rescues: `First Last and First Last` author lists resolve instead of landing
+  in `AMBIGUOUS`; an arXiv id whose record agrees on author and year is accepted as
+  `RESOLVED (low confidence)` the way a DOI already was. Ghost set 274 rows: false-ghost
+  **0.0 %**, ghost recall 99.1 % (`docs/eval/2026-09-12-ghosts.md`).
+- `tests/data/draft-author-year.md`, a committed author-year draft with an offline
+  smoke test; live: 6 citations paired, 0 unresolved.
+
+### Changed
+- Cache schema **v3** (migrated in place from v1/v2; versions compared as integers).
+- `Claims.unsupported` now means "a style this version cannot pair" and is empty by
+  construction; `UNSUPPORTED CITATION STYLE` is left for footnote-only and
+  superscript-letter styles. Markers that pair with nothing are `unresolved`.
+- `resolve.looks_unindexed` reads only the initials-path author patterns: a full-name
+  list (`First Last and First Last`) no longer counts as "this entry printed an
+  author list", so a title-first book keeps its title (see Known issues for the price).
+- `--format sarif` on `resolve` or `fetch` now says `applies to check only` instead of
+  naming a future version.
+- Stage row `Claims` reads `N citations, M unresolved` (was `M unsupported`).
+
+### Fixed
+- A provider answering with a non-JSON body (a bot wall or maintenance page under a
+  200) escaped `resolve.py` as a raw `JSONDecodeError` traceback. Every provider body
+  is decoded in one place and that failure is a `ProviderError`, so `resolve`, `fetch`
+  and `check` report `UNVERIFIED (provider unavailable)` and never read it as evidence
+  the work does not exist.
+- The §7.1 prompt said `blocked this request (HTTP 200)` for the empty-body bot wall;
+  it now says `answered without readable text (HTTP 200)`.
+- `resolve` on the CLI leaked one HTTP client per invocation; `commands.resolve_reference`
+  owns and closes it.
+- A retraction check every provider failed was recorded as "not retracted". It now
+  raises, is reported as `retraction check unavailable` and counted in the stage
+  summary (`1 unavailable`), and nothing is cached, so the next run asks again
+  (product rule 2). Found alongside it: the fetching stage replaced a source's notes
+  instead of appending, which would have dropped that very note.
+- Versions in the cache file compared as strings (`"10" < "9"`); compared as integers now.
+
+### Known issues
+- `api_calls` in the footer counts LLM calls only (none yet), so a cold run that spent
+  30 s on Crossref and Semantic Scholar still prints `0 API calls`; the provider lookups
+  are shown on the stage lines instead.
+- A cached resolution reprints the notes it was stored with (for example an `openalex
+  unavailable (HTTP 429)` from the day it was resolved) as if they were current.
+- `proofpath check -` names its SARIF artifact `-`; give the draft a file name when the
+  log is meant for a viewer.
+- Author-year pairing matches the first author and the exact year; `(Lindqvist, 2019)`
+  against "Okafor, C. and Lindqvist, S." and a year off by one are reported unresolved,
+  and two surnames sharing a last word (`Berg` / `van der Berg`) are reported ambiguous
+  rather than guessed. `Smith 2020` with no comma is not a marker; `(WHO, 2020)` does
+  not pair with "World Health Organization".
+- An unnumbered two-column bibliography is cut at line breaks (RoBERTa: 103 entries
+  for ~50), so author-year pairing over such a list resolves few items. The largest
+  open item for author-year pairing.
+- The headless bibliography fallback takes only the *last* run of numbered paragraphs
+  (AlphaFold: 17 of 84 entries) and drops the prose printed before a block's first entry.
+- A fabricated `First Last and First Last. Title. Venue.` with no year between the
+  names and the title reaches `UNVERIFIED (not in bibliographic indexes)`, not `GHOST`
+  (the price of the rescue above; rule 3 outranks recall). A proceedings-*volume*
+  record can accept a fabricated paper cited into that volume as `RESOLVED (low
+  confidence)` — the ghost set's one fabricated acceptance (0.9 %).
+- A cold run of a long bibliography is still serial through the providers (129
+  references: minutes); only the TUI's concurrent scheduler runs them in parallel.
+- In the TUI the `loading models …` note is drawn after the `Verifying` row it precedes
+  (it is emitted inside that stage).
+- A `#n` run reference in the TUI is a click target that folds its block, not a
+  hyperlink (spec §13.1); a run number has no address to open.
+- A provider body that is valid JSON but not an object (a bare list or string) still
+  escapes `resolve` as an error, exit 2, rather than being reported as `UNVERIFIED
+  (provider unavailable)`.
+- `/quit` in the TUI waits for an in-flight mirrored `/fetch` to finish before the
+  app exits; a `/check` run is cancelled, a `/fetch` is not.
+
 ## [0.1.0] - 2026-09-12
 
 First working release: `proofpath check` verifies a document's citations end to end

{proofpath-0.1.0 → proofpath-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proofpath
-Version: 0.1.0
+Version: 0.2.0
 Summary: Check whether the sources behind a claim actually say what the claim says.
 Project-URL: Homepage, https://github.com/Yigtwxx/proofpath
 Project-URL: Repository, https://github.com/Yigtwxx/proofpath
@@ -42,7 +42,9 @@ Requires-Dist: typer>=0.15
 Provides-Extra: browser
 Requires-Dist: scrapling[fetchers]>=0.4.15; extra == 'browser'
 Provides-Extra: dev
+Requires-Dist: jsonschema>=4.23; extra == 'dev'
 Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=6.0; extra == 'dev'
 Requires-Dist: pytest>=8.3; extra == 'dev'
 Requires-Dist: respx>=0.22; extra == 'dev'
@@ -71,12 +73,42 @@ Runs locally and free: no API key, no Docker, no server. Windows, Linux, macOS.
 
 ```bash
 uv tool install proofpath
+proofpath
+```
+
+```
+   ,_,
+  (o.o)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~[PROOF]
+   " "    proofpath v0.2.0                                              academic . online . coreml
+          paste a file path, a URL, or a claim.            /help  /config  /quit
+```
+
+Bare `proofpath` opens the terminal UI ([a recorded session](docs/eval/2026-09-15-v0.2-live.md)).
+Paste a path and it runs; every one-shot verb is a slash command (`/check`, `/resolve`,
+`/fetch`, `/config`, `/cache`), runs can be started while others are in flight and
+stopped with `/cancel #n` — a stopped run keeps what it had decided — and the
+coverage footer never scrolls away. Click (or press `enter` on) a finding to read the
+whole quoted passage; `⧉` copies it; a finding's reference is a link to its source.
+When a publisher blocks the plain fetch, the permission question is asked **inline,
+under the stage that hit the wall**, with `[allow once] [always] [no] [never]`.
+
+The same engine behind a pipe or in CI:
 
-proofpath check paper.pdf          # one-shot report → report.md, exit 0/1/2
+```bash
+proofpath check paper.pdf                       # report → report.md, exit 0/1/2
 proofpath check draft.md --format json | jq '.coverage'
-proofpath -q check - < draft.md    # stdin; findings and coverage only
+proofpath check draft.md --format sarif --out draft.sarif   # any SARIF 2.1.0 viewer (VS Code's SARIF Viewer, …)
+proofpath -q check - < draft.md                 # stdin; findings and coverage only
 ```
 
+`--format sarif` writes a SARIF 2.1.0 log: one result per finding on its line, the
+quoted passage in the message, the exact honesty state in `properties`, and the run's
+coverage in the run's properties, so a log opened without the terminal still says how
+much was read. Exit codes are the interface: `0` clean, `1` findings (every
+`UNVERIFIED` and `LOW CONFIDENCE` counts), `2` the run itself failed — no text
+parsing needed to gate a job. Piped or in CI there is **no prompt**: an `ask`
+permission is treated as `deny` and reported.
+
 The install carries **no browser engine**. When a publisher blocks the plain fetch,
 proofpath asks once before downloading one — about 280 MB, into its own environment
 and the shared browser cache, never system-wide — and remembers the answer.
@@ -99,7 +131,9 @@ unverified 14%
 ```
 
 When a quarter or more of the sources could not be read, a further line says so:
-`coverage is weak: unread sources may hold more, so this is a lower bound`.
+`coverage is weak: unread sources may hold more, so this is a lower bound`. When the
+browser step was not permitted, a line counts the sources it cost:
+`skipped N source(s) because the browser was not permitted`.
 
 **No verdict without its passage.** `SUPPORTED` and `REFUTED` cannot exist without
 the quoted sentence they rest on — the cache schema itself refuses to store one.
@@ -113,6 +147,19 @@ was near-certain here", not as a guarantee of 85 % precision. And `medium` lands
 almost exactly on `decide`, so `low` is practically empty among asserted verdicts —
 the display is effectively **two tiers**: near-certain, and asserted at all.
 
+## Citations it reads
+
+Numeric markers — `[12]`, `[12,15]`, `[12-15]`, Nature-style superscripts — and, since
+v0.2, **author-year**: `(Smith et al., 2020)`, `Smith (2020)`, `(Smith, 2020; Jones,
+2019)`, `2020a`/`2020b` collisions, `ibid.` and `op. cit.`, and a mixed
+`(Smith, 2020; [12])`. Pairing rate on the hand-built author-year set: **0.940**
+(83 expectations over 55 passages, [details](docs/eval/2026-09-12-pairing-author-year.md));
+the numeric set is at 108 of 109. Still unpaired, and reported rather than guessed:
+a surname that is not the entry's *first* author, a year off by one, two surnames
+sharing a last word (`Berg` / `van der Berg`), `Smith 2020` with no comma, and an
+initialism such as `(WHO, 2020)` against "World Health Organization". A marker no
+entry matches is listed as an unresolved marker.
+
 ## What the states mean
 
 Absence of evidence is never reported as evidence of absence. Each of these is a
@@ -127,65 +174,68 @@ distinct, printed state (spec §15), never collapsed into a verdict:
 | `UNVERIFIED (unreachable)` | dead link, Wayback miss |
 | `UNVERIFIED (reached, no text extracted)` | 200 answered, nothing readable came back |
 | `UNVERIFIED (network not permitted)` | `permissions.network = deny` |
-| `UNVERIFIED (provider unavailable)` | API down or rate limited after backoff |
+| `UNVERIFIED (provider unavailable)` | API down, rate limited after backoff, or answering with a page instead of a record |
 | `UNVERIFIED (not in bibliographic indexes)` | web page, blog, report — indexes do not cover it, so absence proves nothing |
 | `AMBIGUOUS` | several plausible records, all listed |
 | `NEI` | the source was read and neither supports nor contradicts |
 | `PARAGRAPH-SCOPED` | the citation covers a paragraph; each sentence is judged separately |
-| `UNSUPPORTED CITATION STYLE` | an author–year marker; v0.1 pairs numeric markers only |
+| `UNSUPPORTED CITATION STYLE` | reserved; no detected style produces it in v0.2 |
 
-Exit codes: `0` clean, `1` findings (every `UNVERIFIED` and `LOW CONFIDENCE` counts),
-`2` the run itself failed — no text parsing needed to gate a CI job. An earlier build
-sometimes aborted with `134` after printing a complete report (ONNX runtime
-teardown); fixed in this release — 20 of 20 piped runs exit `1` ([live runs](docs/eval/2026-09-12-v0.1-live.md)).
+An earlier build sometimes aborted with `134` after printing a complete report (ONNX
+runtime teardown); fixed in v0.1 — 20 of 20 piped runs exit `1`
+([live runs](docs/eval/2026-09-12-v0.1-live.md)).
 
-## What v0.1 cannot do yet
+## Known limitations
 
-- **Numeric citation markers only** — `[12]`, `[12,15]`, `[12-15]`; an author–year
-  citation is listed as `UNSUPPORTED CITATION STYLE`, not judged.
 - **Superscript citations only when the PDF marks them as superscript**; a PDF that
   draws them as ordinary digits loses them, and `km²` can be read as `[2]`.
 - **Abstract fallback**: when only an abstract is reachable the verdict is labelled
   `LOW CONFIDENCE (abstract only)`. Three sentences is not a source.
-- **A reference list without a `References` heading is not found at all**, so its
-  markers are reported as uncheckable rather than checked.
-- **Resolution and the retraction check are not cached**, so even a warm re-run goes
-  to the network for them.
-- **The 0 % false-ghost rate is a property of the hand set's citation style.** Live
-  runs hit styles that set does not contain, and misjudged real references because of
-  it ([the live runs](docs/eval/2026-09-12-v0.1-live.md)).
+- **An unnumbered two-column bibliography is cut at line breaks** (RoBERTa's ACL
+  list: 103 entries for ~50, half of them with no author), so author-year pairing over
+  such a list resolves few items — 15 claims where a rejoined list would give 65. The
+  largest open item for author-year pairing.
+- **A reference list without a `References` heading** is read by its shape in paged
+  formats — the last contiguous run of numbered paragraphs — which recovers only that
+  last block (AlphaFold: 17 of 84 entries) and drops the prose printed before a
+  block's first entry.
+- **The 0 % false-ghost rate is measured on 274 hand-built references**, and rule 3
+  is paid for in recall: a fabricated `First Last and First Last. Title. Venue.` with
+  no year between the names and the title is reported as `not in bibliographic
+  indexes`, not as a ghost, and a proceedings-*volume* record can accept a fabricated
+  paper cited into that volume as `RESOLVED (low confidence)` — the set's one
+  fabricated acceptance (0.9 %) ([details](docs/eval/2026-09-12-ghosts.md)).
+- **A cold run of a long bibliography is still serial** through the providers (129
+  references: minutes). Only the TUI runs several documents' network stages at once.
 - **A refused or failed browser install is reported, not hidden**: the source is
   `UNVERIFIED (blocked, browser not permitted)` with the install log, never silently
   counted as unreachable.
 - **Coverage is not perfectly reproducible**: two runs minutes apart can read a
   different number of sources, depending on which providers answered.
-- The TUI and `--format sarif` arrive in **v0.2**; the LLM judge and `--summarize`
-  in **v0.3**.
+- The LLM judge and `--summarize` arrive in **v0.3**.
 
 ## Speed
 
-Apple Silicon Mac, models already downloaded ([live runs](docs/eval/2026-09-12-v0.1-live.md)):
+Apple Silicon Mac, models already downloaded:
 
 | document | first run | cached re-run |
 |---|---|---|
-| 1-page markdown draft, 7 references | 79.3 s | 15.8 s * |
-| 19-page arXiv PDF, 68 references | 12 m 57 s | 3 m 42 s |
-
- * the draft's cached re-run followed the earlier of the two recorded cold runs; the live doc keeps both.
+| 1-page markdown draft, 7 references | 79.3 s (v0.1 cold) | **1.35 s** ([v0.2](docs/eval/2026-09-15-v0.2-live.md)) — 15.8 s in v0.1 |
+| 19-page arXiv PDF, 68 references | 12 m 57 s | 3 m 42 s ([v0.1](docs/eval/2026-09-12-v0.1-live.md)) |
 
-The **first ever** run also downloads about 250 MB of ONNX models. A cached re-run
-reads its chunks and verdicts back from the cache instead of recomputing them, but it
-is not a no-op: both models are still loaded, reference resolution and the retraction
-check still query the network, and any source whose text has expired or was never
-read is fetched again — the PDF re-run above still spent 22 s fetching (it went out to
-Wayback and arXiv) and re-scored 3 of 102 claims.
+The **first ever** run also downloads about 250 MB of ONNX models. Since v0.2 a
+cached re-run asks the network for nothing: reference resolution and the retraction
+check are cached (resolutions 30 days; a retraction hit 30 days, a miss 7 days), the
+fetched text for 7 days, and chunks and verdicts for as long as the text is unchanged. The models are still loaded, and any source whose text
+has expired or was never read is fetched again — the PDF re-run above (v0.1) still
+spent 22 s fetching and re-scored 3 of 102 claims.
 
 ## Looking inside the cache
 
 Everything proofpath fetches, embeds and decides lands in one plain SQLite file:
 
 ```bash
-proofpath cache            # where it is and what it holds
+proofpath cache            # where it is, what it holds, how many lookups it remembers
 proofpath cache ls         # sources, chunk/verdict counts, text expiry
 proofpath cache show <id>  # one source's chunks and verdicts
 proofpath cache clear --expired
@@ -193,8 +243,8 @@ proofpath cache clear --expired
 
 Open `proofpath cache path` in [DB Browser for SQLite](https://sqlitebrowser.org/),
 TablePlus or DBeaver — plain tables, no extension. Raw publisher text expires after
-7 days; verdicts keep the passage they quote. `proofpath resolve REF` and `proofpath
-fetch URL|DOI` run either half on its own.
+7 days; verdicts keep the passage they quote; a provider outage is never stored.
+`proofpath resolve REF` and `proofpath fetch URL|DOI` run either half on its own.
 
 ## Optional LLM judge — arrives in v0.3
 
@@ -209,9 +259,10 @@ comes from the environment or a `.env` file, never from config, and is never pri
 | What | Set | Result |
 |---|---|---|
 | Retrieval + entailment | SciFact dev, 340 pairs | 0.609 accuracy, 0.597 macro-F1, against a 0.406 trivial baseline ([details](docs/eval/2026-09-12-scifact-dev.md)) |
-| Reference resolution | hand-built ghost set, 258 references | 0 % false-ghost, 100 % ghost recall ([details](docs/eval/2026-09-12-ghosts.md)) — but see the live-run caveat above |
+| Reference resolution | hand-built ghost set, 274 references | 0.0 % false-ghost, 99.1 % ghost recall ([details](docs/eval/2026-09-12-ghosts.md)) |
 | Source access | 50 DOIs | 72 % full text, 18 % abstract only, 10 % nothing ([details](docs/eval/2026-09-11-coverage.md)) — a real biomedical paper in the live runs reached 33 % full text |
-| Citation pairing | 61 hand-built passages | 0.98 ([details](docs/eval/2026-09-11-pairing.md)) |
+| Citation pairing, numeric | 61 hand-built passages | 0.99 ([details](docs/eval/2026-09-11-pairing.md)) |
+| Citation pairing, author-year | 55 hand-built passages, 83 expectations | 0.940 ([details](docs/eval/2026-09-12-pairing-author-year.md)) |
 
 Published SciFact results sit around 70–75 F1, not 95. Nothing is tuned on a test
 split, and no number is quoted without the run that produced it.

{proofpath-0.1.0 → proofpath-0.2.0}/README.md

@@ -17,12 +17,42 @@ Runs locally and free: no API key, no Docker, no server. Windows, Linux, macOS.
 
 ```bash
 uv tool install proofpath
+proofpath
+```
+
+```
+   ,_,
+  (o.o)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~[PROOF]
+   " "    proofpath v0.2.0                                              academic . online . coreml
+          paste a file path, a URL, or a claim.            /help  /config  /quit
+```
+
+Bare `proofpath` opens the terminal UI ([a recorded session](docs/eval/2026-09-15-v0.2-live.md)).
+Paste a path and it runs; every one-shot verb is a slash command (`/check`, `/resolve`,
+`/fetch`, `/config`, `/cache`), runs can be started while others are in flight and
+stopped with `/cancel #n` — a stopped run keeps what it had decided — and the
+coverage footer never scrolls away. Click (or press `enter` on) a finding to read the
+whole quoted passage; `⧉` copies it; a finding's reference is a link to its source.
+When a publisher blocks the plain fetch, the permission question is asked **inline,
+under the stage that hit the wall**, with `[allow once] [always] [no] [never]`.
+
+The same engine behind a pipe or in CI:
 
-proofpath check paper.pdf          # one-shot report → report.md, exit 0/1/2
+```bash
+proofpath check paper.pdf                       # report → report.md, exit 0/1/2
 proofpath check draft.md --format json | jq '.coverage'
-proofpath -q check - < draft.md    # stdin; findings and coverage only
+proofpath check draft.md --format sarif --out draft.sarif   # any SARIF 2.1.0 viewer (VS Code's SARIF Viewer, …)
+proofpath -q check - < draft.md                 # stdin; findings and coverage only
 ```
 
+`--format sarif` writes a SARIF 2.1.0 log: one result per finding on its line, the
+quoted passage in the message, the exact honesty state in `properties`, and the run's
+coverage in the run's properties, so a log opened without the terminal still says how
+much was read. Exit codes are the interface: `0` clean, `1` findings (every
+`UNVERIFIED` and `LOW CONFIDENCE` counts), `2` the run itself failed — no text
+parsing needed to gate a job. Piped or in CI there is **no prompt**: an `ask`
+permission is treated as `deny` and reported.
+
 The install carries **no browser engine**. When a publisher blocks the plain fetch,
 proofpath asks once before downloading one — about 280 MB, into its own environment
 and the shared browser cache, never system-wide — and remembers the answer.
@@ -45,7 +75,9 @@ unverified 14%
 ```
 
 When a quarter or more of the sources could not be read, a further line says so:
-`coverage is weak: unread sources may hold more, so this is a lower bound`.
+`coverage is weak: unread sources may hold more, so this is a lower bound`. When the
+browser step was not permitted, a line counts the sources it cost:
+`skipped N source(s) because the browser was not permitted`.
 
 **No verdict without its passage.** `SUPPORTED` and `REFUTED` cannot exist without
 the quoted sentence they rest on — the cache schema itself refuses to store one.
@@ -59,6 +91,19 @@ was near-certain here", not as a guarantee of 85 % precision. And `medium` lands
 almost exactly on `decide`, so `low` is practically empty among asserted verdicts —
 the display is effectively **two tiers**: near-certain, and asserted at all.
 
+## Citations it reads
+
+Numeric markers — `[12]`, `[12,15]`, `[12-15]`, Nature-style superscripts — and, since
+v0.2, **author-year**: `(Smith et al., 2020)`, `Smith (2020)`, `(Smith, 2020; Jones,
+2019)`, `2020a`/`2020b` collisions, `ibid.` and `op. cit.`, and a mixed
+`(Smith, 2020; [12])`. Pairing rate on the hand-built author-year set: **0.940**
+(83 expectations over 55 passages, [details](docs/eval/2026-09-12-pairing-author-year.md));
+the numeric set is at 108 of 109. Still unpaired, and reported rather than guessed:
+a surname that is not the entry's *first* author, a year off by one, two surnames
+sharing a last word (`Berg` / `van der Berg`), `Smith 2020` with no comma, and an
+initialism such as `(WHO, 2020)` against "World Health Organization". A marker no
+entry matches is listed as an unresolved marker.
+
 ## What the states mean
 
 Absence of evidence is never reported as evidence of absence. Each of these is a
@@ -73,65 +118,68 @@ distinct, printed state (spec §15), never collapsed into a verdict:
 | `UNVERIFIED (unreachable)` | dead link, Wayback miss |
 | `UNVERIFIED (reached, no text extracted)` | 200 answered, nothing readable came back |
 | `UNVERIFIED (network not permitted)` | `permissions.network = deny` |
-| `UNVERIFIED (provider unavailable)` | API down or rate limited after backoff |
+| `UNVERIFIED (provider unavailable)` | API down, rate limited after backoff, or answering with a page instead of a record |
 | `UNVERIFIED (not in bibliographic indexes)` | web page, blog, report — indexes do not cover it, so absence proves nothing |
 | `AMBIGUOUS` | several plausible records, all listed |
 | `NEI` | the source was read and neither supports nor contradicts |
 | `PARAGRAPH-SCOPED` | the citation covers a paragraph; each sentence is judged separately |
-| `UNSUPPORTED CITATION STYLE` | an author–year marker; v0.1 pairs numeric markers only |
+| `UNSUPPORTED CITATION STYLE` | reserved; no detected style produces it in v0.2 |
 
-Exit codes: `0` clean, `1` findings (every `UNVERIFIED` and `LOW CONFIDENCE` counts),
-`2` the run itself failed — no text parsing needed to gate a CI job. An earlier build
-sometimes aborted with `134` after printing a complete report (ONNX runtime
-teardown); fixed in this release — 20 of 20 piped runs exit `1` ([live runs](docs/eval/2026-09-12-v0.1-live.md)).
+An earlier build sometimes aborted with `134` after printing a complete report (ONNX
+runtime teardown); fixed in v0.1 — 20 of 20 piped runs exit `1`
+([live runs](docs/eval/2026-09-12-v0.1-live.md)).
 
-## What v0.1 cannot do yet
+## Known limitations
 
-- **Numeric citation markers only** — `[12]`, `[12,15]`, `[12-15]`; an author–year
-  citation is listed as `UNSUPPORTED CITATION STYLE`, not judged.
 - **Superscript citations only when the PDF marks them as superscript**; a PDF that
   draws them as ordinary digits loses them, and `km²` can be read as `[2]`.
 - **Abstract fallback**: when only an abstract is reachable the verdict is labelled
   `LOW CONFIDENCE (abstract only)`. Three sentences is not a source.
-- **A reference list without a `References` heading is not found at all**, so its
-  markers are reported as uncheckable rather than checked.
-- **Resolution and the retraction check are not cached**, so even a warm re-run goes
-  to the network for them.
-- **The 0 % false-ghost rate is a property of the hand set's citation style.** Live
-  runs hit styles that set does not contain, and misjudged real references because of
-  it ([the live runs](docs/eval/2026-09-12-v0.1-live.md)).
+- **An unnumbered two-column bibliography is cut at line breaks** (RoBERTa's ACL
+  list: 103 entries for ~50, half of them with no author), so author-year pairing over
+  such a list resolves few items — 15 claims where a rejoined list would give 65. The
+  largest open item for author-year pairing.
+- **A reference list without a `References` heading** is read by its shape in paged
+  formats — the last contiguous run of numbered paragraphs — which recovers only that
+  last block (AlphaFold: 17 of 84 entries) and drops the prose printed before a
+  block's first entry.
+- **The 0 % false-ghost rate is measured on 274 hand-built references**, and rule 3
+  is paid for in recall: a fabricated `First Last and First Last. Title. Venue.` with
+  no year between the names and the title is reported as `not in bibliographic
+  indexes`, not as a ghost, and a proceedings-*volume* record can accept a fabricated
+  paper cited into that volume as `RESOLVED (low confidence)` — the set's one
+  fabricated acceptance (0.9 %) ([details](docs/eval/2026-09-12-ghosts.md)).
+- **A cold run of a long bibliography is still serial** through the providers (129
+  references: minutes). Only the TUI runs several documents' network stages at once.
 - **A refused or failed browser install is reported, not hidden**: the source is
   `UNVERIFIED (blocked, browser not permitted)` with the install log, never silently
   counted as unreachable.
 - **Coverage is not perfectly reproducible**: two runs minutes apart can read a
   different number of sources, depending on which providers answered.
-- The TUI and `--format sarif` arrive in **v0.2**; the LLM judge and `--summarize`
-  in **v0.3**.
+- The LLM judge and `--summarize` arrive in **v0.3**.
 
 ## Speed
 
-Apple Silicon Mac, models already downloaded ([live runs](docs/eval/2026-09-12-v0.1-live.md)):
+Apple Silicon Mac, models already downloaded:
 
 | document | first run | cached re-run |
 |---|---|---|
-| 1-page markdown draft, 7 references | 79.3 s | 15.8 s * |
-| 19-page arXiv PDF, 68 references | 12 m 57 s | 3 m 42 s |
-
- * the draft's cached re-run followed the earlier of the two recorded cold runs; the live doc keeps both.
+| 1-page markdown draft, 7 references | 79.3 s (v0.1 cold) | **1.35 s** ([v0.2](docs/eval/2026-09-15-v0.2-live.md)) — 15.8 s in v0.1 |
+| 19-page arXiv PDF, 68 references | 12 m 57 s | 3 m 42 s ([v0.1](docs/eval/2026-09-12-v0.1-live.md)) |
 
-The **first ever** run also downloads about 250 MB of ONNX models. A cached re-run
-reads its chunks and verdicts back from the cache instead of recomputing them, but it
-is not a no-op: both models are still loaded, reference resolution and the retraction
-check still query the network, and any source whose text has expired or was never
-read is fetched again — the PDF re-run above still spent 22 s fetching (it went out to
-Wayback and arXiv) and re-scored 3 of 102 claims.
+The **first ever** run also downloads about 250 MB of ONNX models. Since v0.2 a
+cached re-run asks the network for nothing: reference resolution and the retraction
+check are cached (resolutions 30 days; a retraction hit 30 days, a miss 7 days), the
+fetched text for 7 days, and chunks and verdicts for as long as the text is unchanged. The models are still loaded, and any source whose text
+has expired or was never read is fetched again — the PDF re-run above (v0.1) still
+spent 22 s fetching and re-scored 3 of 102 claims.
 
 ## Looking inside the cache
 
 Everything proofpath fetches, embeds and decides lands in one plain SQLite file:
 
 ```bash
-proofpath cache            # where it is and what it holds
+proofpath cache            # where it is, what it holds, how many lookups it remembers
 proofpath cache ls         # sources, chunk/verdict counts, text expiry
 proofpath cache show <id>  # one source's chunks and verdicts
 proofpath cache clear --expired
@@ -139,8 +187,8 @@ proofpath cache clear --expired
 
 Open `proofpath cache path` in [DB Browser for SQLite](https://sqlitebrowser.org/),
 TablePlus or DBeaver — plain tables, no extension. Raw publisher text expires after
-7 days; verdicts keep the passage they quote. `proofpath resolve REF` and `proofpath
-fetch URL|DOI` run either half on its own.
+7 days; verdicts keep the passage they quote; a provider outage is never stored.
+`proofpath resolve REF` and `proofpath fetch URL|DOI` run either half on its own.
 
 ## Optional LLM judge — arrives in v0.3
 
@@ -155,9 +203,10 @@ comes from the environment or a `.env` file, never from config, and is never pri
 | What | Set | Result |
 |---|---|---|
 | Retrieval + entailment | SciFact dev, 340 pairs | 0.609 accuracy, 0.597 macro-F1, against a 0.406 trivial baseline ([details](docs/eval/2026-09-12-scifact-dev.md)) |
-| Reference resolution | hand-built ghost set, 258 references | 0 % false-ghost, 100 % ghost recall ([details](docs/eval/2026-09-12-ghosts.md)) — but see the live-run caveat above |
+| Reference resolution | hand-built ghost set, 274 references | 0.0 % false-ghost, 99.1 % ghost recall ([details](docs/eval/2026-09-12-ghosts.md)) |
 | Source access | 50 DOIs | 72 % full text, 18 % abstract only, 10 % nothing ([details](docs/eval/2026-09-11-coverage.md)) — a real biomedical paper in the live runs reached 33 % full text |
-| Citation pairing | 61 hand-built passages | 0.98 ([details](docs/eval/2026-09-11-pairing.md)) |
+| Citation pairing, numeric | 61 hand-built passages | 0.99 ([details](docs/eval/2026-09-11-pairing.md)) |
+| Citation pairing, author-year | 55 hand-built passages, 83 expectations | 0.940 ([details](docs/eval/2026-09-12-pairing-author-year.md)) |
 
 Published SciFact results sit around 70–75 F1, not 95. Nothing is tuned on a test
 split, and no number is quoted without the run that produced it.