paper-preflight 0.1.0__tar.gz

paper_preflight-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "paper-preflight",
+  "owner": {
+    "name": "amos689",
+    "url": "https://github.com/amos689"
+  },
+  "description": "paper-preflight: pre-submission reference checks for LaTeX papers.",
+  "plugins": [
+    {
+      "name": "paper-preflight",
+      "source": "./plugins/paper-preflight",
+      "description": "Verify every reference of a LaTeX paper against real scholarly records before submission: an MCP server plus a skill that runs the check and fixes what it proves wrong.",
+      "category": "productivity",
+      "tags": ["latex", "bibtex", "citations", "research"]
+    }
+  ]
+}

paper_preflight-0.1.0/.gitattributes

@@ -0,0 +1,11 @@
+# Normalize text files to LF in the repository.
+* text=auto eol=lf
+
+# Test fixtures must keep their exact bytes (CRLF, BOM, GB18030, etc.).
+tests/fixtures/** -text
+evals/cassettes/** -text
+
+*.png binary
+*.jpg binary
+*.pdf binary
+*.gif binary

paper_preflight-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# paper-preflight outputs
+.preflight/
+
+# Spike scratch space and downloaded benchmark data (never committed)
+.spikes/
+evals/.data/
+evals/.cache/
+evals/results/*.jsonl
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+.pytest_tmp/

paper_preflight-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^tests/fixtures/
+      - id: end-of-file-fixer
+        exclude: ^tests/fixtures/
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.10
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

paper_preflight-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,18 @@
+# pre-commit hooks for LaTeX projects (https://pre-commit.com). Both check the whole project in
+# the repository root, so they run once per commit when a .tex or .bib file changed.
+- id: paper-preflight
+  name: paper-preflight (verify references)
+  description: Verify every cited reference against Crossref, dblp, arXiv, DataCite and OpenAlex.
+  entry: paper-preflight check
+  language: python
+  types_or: [tex, bib]
+  pass_filenames: false
+  require_serial: true
+- id: paper-preflight-offline
+  name: paper-preflight (offline, cached answers only)
+  description: Citation-key checks plus cached reference verdicts; never touches the network.
+  entry: paper-preflight check --offline
+  language: python
+  types_or: [tex, bib]
+  pass_filenames: false
+  require_serial: true

paper_preflight-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

paper_preflight-0.1.0/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-03
+
+The first release.
+
+### Added
+
+- Project scaffold: packaging, CLI entry point (`--version`, `doctor`), CI, contribution docs.
+- Verdict engine: one verdict per reference (verified, metadata mismatch, identifier conflict,
+  not found, cannot determine) with rules REF001-REF005, REF010-REF015, REF018, REF090 and RUN001.
+  Search results with another title and no author in common are other works: they no longer
+  keep an entry nobody found from being reported as not found (REF003).
+- `check` verifies the cited references online by default; `--offline` answers from the local
+  cache only. Text output adds a verdict summary line; JSON adds `verification` and `references`.
+  Exit code 2 when a source was unavailable and nothing blocking was found.
+- `--refresh` (`check`, `bib fetch`, `bib fix`) asks every source again instead of using cached
+  answers; within the run each answer is still asked for once. It contradicts `--offline`.
+- The JSON report records what each source did (`verification.sources`: requests, cache hits,
+  stale hits, negatives and unavailability by reason), so a run can be audited and compared.
+- Releases are published to PyPI from GitHub Releases through trusted publishing, with PEP 740
+  attestations (`release.yml`, `docs/releasing.md`); the PyPI page links back to GitHub.
+- When the arXiv API refuses requests or times out, arXiv IDs are verified through DataCite
+  (`10.48550/arXiv.<id>`); the run still reports arXiv as unavailable.
+- Semantic Scholar as an optional rescue source, used only when `S2_API_KEY` is set: it is asked
+  about references no other source found, stays below the keyed limit of 1 request/s, backs off
+  exponentially on HTTP 429, and its outages never block a verdict. Its answers are cached
+  locally but never exported (licence).
+- PubMed (NCBI E-utilities) verifies PMIDs: its record anchors the entry, a PMID it does not
+  know is REF002, and articles it marks as retracted get REF004. `doctor` checks it too.
+- PMCIDs are verified too: PubMed Central gives their PMID, whose PubMed record anchors the
+  entry; a PMCID it does not know is REF002.
+- Evaluation harness for the HALLMARK benchmark (`evals/run_hallmark.py`): flag / clean / abstain
+  outcomes, fabrication-only and any-issue modes, precision, conservative recall, false-positive
+  rate and coverage, broken down by hallucination type.
+- `doctor` checks each source with one uncached request and reports `ok`, `unavailable` (with the
+  reason: rate limit, bot wall, timeout ...) or `skipped`; `--offline` skips the check.
+- MCP server (`paper-preflight mcp`, needs the `mcp` extra): read-only `preflight_check` with
+  paged findings and `preflight_explain`; paths are confined to the workspace root
+  (`docs/mcp.md`).
+- Claude Code plugin and marketplace (`plugins/paper-preflight`): the MCP server plus a
+  `paper-preflight` skill that runs the check before a paper is called finished.
+- pre-commit hooks (`docs/pre-commit.md`): `paper-preflight-offline` (seconds, cached verdicts
+  only) and `paper-preflight` (full online verification).
+- `paper-preflight explain [RULE]`: what a rule detects, its severity, its message and whether a
+  fix is safe; without an argument it lists every rule.
+- CFG001: a `% preflight: ignore[...]` comment that silenced nothing is reported (info), among
+  the rules that ran on its entry; unknown rule names always are. Documented in the README.
+- First full HALLMARK dev_public results (`evals/results/hallmark-dev_public.md`), with a second
+  summary that leaves out labels checked by hand and found wrong (`evals/hallmark_disputed.toml`).
+- `bib fetch <DOI|arXiv ID>` or `bib fetch --title ...`: a BibTeX entry built from the registry
+  record (published versions of preprints keep their eprint; retracted works warn; ambiguous
+  titles list candidates; `--format json` for agents).
+- MCP tool `preflight_bib_lookup`: `bib fetch` for agents.
+- `bib fix`: edits the .bib files from the verified records, as a diff or with `--apply`;
+  `--level safe` (identifier formatting, missing DOIs) or `unsafe` (also authors, title, year,
+  venue, wrong identifiers). Only the affected fields change. REF016 offers a missing DOI.
+- GitHub Action (`action.yml`): runs the check, writes the job summary and a SARIF report,
+  caches answers per bibliography (`docs/github-action.md`).
+- Identifier lookups (doi.org, Crossref, DataCite, OpenAlex, arXiv, and dblp's published-version
+  links) are cached per identifier, so adding an entry no longer makes its batch companions
+  unverifiable in `--offline` runs, nor hides their published versions (REF015).
+- REF014 also reports an invented venue on a paper whose venue is known: an unrecognised name
+  that shares no word or abbreviation with the recorded venue (abbreviations stay unknown).
+- REF012 also reports a title that is close to the record's but has other words ("towards" for
+  "for", "Hidden" for "Latent") and names them; spelling, hyphenation, "&", math and
+  "RETRACTED:" notices do not count, nor do preprints whose earlier titles are unknown.
+- REF011 also reports an author whose surname is right but whose given name belongs to someone
+  else ("Aviral Sharma" for Archit Sharma). Initials, short forms, middle names, hyphenation,
+  transcriptions and common nicknames (Bill, Misha) agree.
+- More venues are recognised for REF014: AISTATS, UAI, COLT, CoRL, TMLR, IJCV, WWW, WSDM, CIKM,
+  ICASSP, Interspeech, MICCAI, ICRA, IROS, WACV and BMVC. URLs in a venue field are ignored.
+- An unrecognised venue is also reported when it names something the recorded venue does not
+  ("International Conference on Quantum Machine Learning" for ICML). Abbreviations, ordinals,
+  series and publishers (PMLR, LNCS, OpenReview) never count, only booktitle and journal are
+  judged, and a workshop must share no word at all with the recorded venue.
+- The same recognised venue now counts as evidence when binding a search result: a four- or
+  five-word title at the same venue in the same year names one work (wrong authors become
+  REF010 instead of "cannot determine"), and a year more than three years off is no reprint
+  when the venue is the same (REF013).
+- A search result by the same people at the same venue in the same year binds when its title
+  is one or two words off, even below the usual similarity threshold; REF012 names the words.
+
+[Unreleased]: https://github.com/amos689/paper-preflight/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/amos689/paper-preflight/releases/tag/v0.1.0

paper_preflight-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of conduct
+
+This project follows the
+[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful and constructive, assume good faith, and focus on the work. Harassment,
+personal attacks and discriminatory language are not tolerated.
+
+Because this tool deals with research integrity, one extra rule applies: **do not use issues,
+discussions or pull requests to accuse named authors of misconduct.** Report tool behaviour,
+not people.
+
+Report unacceptable behaviour privately to the maintainers via GitHub's private reporting
+features. Maintainers will review reports promptly and confidentially.

paper_preflight-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to paper-preflight
+
+Thanks for your interest! The project is pre-alpha; the architecture is still settling, so
+please open an issue before starting larger changes.
+
+## Development setup
+
+```bash
+# requires uv (https://docs.astral.sh/uv/)
+uv sync
+uv run pytest
+uv run ruff check && uv run ruff format --check
+uv run mypy
+uv run pre-commit install
+```
+
+## Ground rules
+
+1. **No LLM in the verdict path.** Verdicts must be reproducible from recorded source
+   responses. No bibliographic field may be generated by a language model.
+2. **Abstain rather than guess.** If a source is unavailable (rate limit, bot challenge,
+   timeout, HTML instead of JSON), the affected references become "cannot determine",
+   never "not found".
+3. **Every network call goes through a source adapter** with rate limiting and caching.
+   Never scrape sites that forbid automated access (Google Scholar, CNKI/Wanfang/VIP search
+   pages, paywalled publisher pages) and never try to bypass bot challenges.
+4. **Licenses.** Runtime dependencies must be MIT/BSD/Apache-2.0/ISC/MPL-2.0/PSF licensed.
+   Adapted code must be permissively licensed and recorded in `THIRD_PARTY_NOTICES.md`.
+5. **Test fixtures.** Recorded API responses may only come from sources whose data can be
+   redistributed (Crossref without abstracts, OpenAlex, DataCite, arXiv metadata, dblp).
+   Never commit Semantic Scholar responses or full texts.
+6. **Bilingual messages.** User-visible strings need English and Simplified Chinese versions.
+7. **Fabricated test data uses fictional author names**, never real people.
+
+## Reporting false positives
+
+False positives are the bugs we care about most. Please use the "False positive" issue
+template and include the BibTeX entry and the output of `paper-preflight explain <finding-id>`.
+
+## Commit messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, …).

paper_preflight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paper-preflight contributors
+
+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.

paper_preflight-0.1.0/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.5
+Name: paper-preflight
+Version: 0.1.0
+Summary: Pre-submission integrity gate for LaTeX papers: every reference verified against real scholarly records. No LLM guessing, no false accusations.
+Project-URL: Homepage, https://github.com/amos689/paper-preflight
+Project-URL: Issues, https://github.com/amos689/paper-preflight/issues
+Project-URL: Changelog, https://github.com/amos689/paper-preflight/blob/main/CHANGELOG.md
+Author: paper-preflight contributors
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: academic-writing,agent-skills,bibtex,citations,hallucinated-citations,latex,mcp,references,research-integrity
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: bibtexparser<3,>=2.0
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: platformdirs>=4
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pylatexenc<3,>=2.10
+Requires-Dist: rapidfuzz<4,>=3.9
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: mcp
+Requires-Dist: fastmcp<4.1,>=4.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# paper-preflight
+
+<!-- mcp-name: io.github.amos689/paper-preflight -->
+
+**English** · [简体中文](https://github.com/amos689/paper-preflight/blob/main/README.zh-CN.md)
+
+[![CI](https://github.com/amos689/paper-preflight/actions/workflows/ci.yml/badge.svg)](https://github.com/amos689/paper-preflight/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/amos689/paper-preflight/blob/main/LICENSE)
+![Python 3.11–3.14](https://img.shields.io/badge/python-3.11%E2%80%933.14-blue.svg)
+
+**Check every reference of a LaTeX paper against real scholarly records before you submit.
+No LLM guessing, no false accusations.**
+
+Language models invent references, and copy-pasted BibTeX carries wrong years, wrong authors
+and dead DOIs. paper-preflight reads your `.tex` and `.bib` files and asks Crossref, dblp,
+arXiv, DataCite, PubMed and OpenAlex (and Semantic Scholar, if you have a key) about every cited
+work:
+
+- Does it exist?
+- Does it match what you wrote?
+- Has it been retracted?
+- Has the preprint you cite been published since?
+
+When it cannot tell, it says so instead of guessing.
+
+> **Status: v0.1, an early release.** False positives are the bugs we most want to hear
+> about: please [open an issue](https://github.com/amos689/paper-preflight/issues).
+
+The repository's [demo paper](https://github.com/amos689/paper-preflight/blob/main/examples/demo-paper) cites eleven works, several of them wrong on
+purpose. A real run, against the live sources:
+
+```text
+$ paper-preflight check examples/demo-paper
+paper-preflight 0.0.1.dev0 · main.tex · 12 entries, 12 cited keys
+
+error   CIT001 main.tex:31
+    Citation key 'nonexistent2023' is not defined in any bibliography file (1 use(s)).
+error   REF001 refs.bib:43
+    The doi of 'devlin2019bert' (10.1109/cvpr.2016.90) resolves to a different work in Crossref: "Deep Residual Learning for Image Recognition" (He et al., 2016).
+error   REF003 refs.bib:66
+    'lindqvist2024quantum' was not found in Crossref, dblp and Semantic Scholar, and every source responded. Check that the work exists and that its title is correct.
+error   REF004 refs.bib:73
+    'wakefield1998ileal' has been retracted (reported by Crossref, OpenAlex). Cite it only if the text discusses the retraction.
+error   CIT002 refs.bib:127
+    Entry key 'kingma2015adam' is already defined at line 47; BibTeX ignores this one.
+warning REF015 refs.bib:31
+    'he2015residual' cites a preprint that has been published in CVPR (2016), DOI 10.1109/cvpr.2016.90. Cite the published version and keep the eprint field.
+warning CIT004 refs.bib:37
+    Entries 'devlin2019bert' and 'he2016deep' look like the same work (same DOI).
+warning REF013 refs.bib:51
+    'kingma2015adam' gives the year 2016, but dblp records 2015.
+warning REF017 refs.bib:111
+    The doi of 'tacl2019example' contains LaTeX escapes: '10.1162/tacl\_a\_00276'. Write it as: 10.1162/tacl_a_00276
+info    REF005 refs.bib:73
+    'wakefield1998ileal' has a published correction (reported by Crossref).
+info    REF090 refs.bib:86
+    'goodfellow2016deep' could not be verified: grey literature without an identifier (book, report, software, web page).
+info    REF090 refs.bib:94
+    'zhou2016ml' could not be verified: non-Latin titles are not supported yet; grey literature without an identifier (book, report, software, web page).
+info    CIT003 refs.bib:115
+    Entry 'lecun1998gradient' is never cited.
+
+References: 6 verified · 1 metadata mismatch · 1 identifier conflict · 1 not found · 2 cannot determine
+5 error(s) · 4 warning(s) · 4 info
+```
+
+Each finding is backed by a record (or by every source answering "no"). The correct NeurIPS
+paper is verified through dblp even though Crossref only holds fake copies of it, and the two
+books without identifiers are reported as "cannot determine" instead of "not found".
+
+## What it catches
+
+| Rule | Finding |
+|---|---|
+| REF001 | The DOI or arXiv ID points to a different paper |
+| REF002 | The DOI or arXiv ID does not exist |
+| REF003 | The work was not found in any source, and every source answered |
+| REF004 · REF005 | The work was retracted, or has an expression of concern or a correction |
+| REF010–REF014 | Authors, title, year or venue differ from the real record |
+| REF015 | A cited preprint has been formally published |
+| REF016 | The registry has a DOI the entry lacks (offered as a safe fix) |
+| REF017 | An identifier is written so that links break (`10.1162/tacl\_a\_00276`, `…v1`) |
+| CIT001–CIT008 | Undefined, duplicate, unused or near-duplicate citation keys; broken `.bib` syntax |
+| REF090 | Cannot determine, always with the reason (source unavailable, grey literature, …) |
+
+`paper-preflight explain REF003` describes any rule.
+
+## How accurate is it?
+
+paper-preflight is measured on [HALLMARK](https://github.com/rpatrik96/hallmark), a public
+benchmark of real and hallucinated BibTeX entries, against the live sources.
+
+| Split | Mode | Precision | Recall | False-positive rate | Coverage |
+|---|---|---|---|---|---|
+| `test_public`: 831 entries, never used during development | Any issue | 97.9% | 88.4% | 2.6% | 96.7% |
+| | Fabrication | 99.0% | 48.6% | 0.6% | 96.7% |
+| `dev_public`: 1,119 entries, used during development | Any issue | 97.6% | 90.5% | 2.1% | 98.3% |
+| | Fabrication | 98.1% | 52.5% | 1.0% | 98.3% |
+
+HALLMARK v1.2.3, every entry of both public splits, run on 2026-10-03. *Fabrication* counts a
+wrong identifier, a work not found and no author in common; *any issue* also counts wrong
+authors, title, year or venue.
+
+- **The held-out split confirms the development numbers:** the same precision and two points
+  less recall on entries no rule was ever tuned on.
+- **Every flag on a `dev_public` entry labelled VALID was checked by hand.** The 11 that remain are not
+  correct citations: DOIs that belong to other papers, author lists naming people who did not
+  write the paper, a shifted year and a truncated title.
+- **Without them, both modes reach 100% precision and 0% false positives.** The list, each item
+  with a reason one lookup confirms, is in
+  [`evals/hallmark_disputed.toml`](https://github.com/amos689/paper-preflight/blob/main/evals/hallmark_disputed.toml).
+- **What is still missed:** invented venues on papers known only as preprints (an arXiv record
+  cannot contradict a venue) and author lists that merely leave people out. See
+  [`evals/results/`](https://github.com/amos689/paper-preflight/blob/main/evals/results/) for every hallucination type.
+
+Precision comes first: a reference is called fabricated only on positive evidence, and an
+unanswered or ambiguous lookup is reported as "cannot determine", never as "not found". The
+evaluation harness and every run's summary are in [`evals/`](https://github.com/amos689/paper-preflight/blob/main/evals/README.md).
+
+## Quick start
+
+With [uv](https://docs.astral.sh/uv/) nothing needs installing (or `pip install paper-preflight`):
+
+```bash
+uvx paper-preflight check path/to/paper
+```
+
+`path/to/paper` is the project directory, its main `.tex` file, or a single `.bib` file.
+
+| Option | Effect |
+|---|---|
+| `--format json` / `--format sarif` | Machine-readable output (SARIF works with GitHub code scanning) |
+| `--offline` | Never touch the network; use only answers already in the local cache |
+| `--refresh` | Ask every source again instead of using cached answers (after a correction, say) |
+| `--fail-on warning` | Make warnings fail the run too (the default is errors) |
+| `--lang zh` | Chinese messages (also chosen automatically from your locale) |
+
+Exit codes:
+
+| Code | Meaning |
+|---|---|
+| 0 | Nothing at or above `--fail-on` was found |
+| 1 | Blocking findings |
+| 2 | No blocking findings, but a source was unavailable, so the paper cannot be called clean yet |
+| 3 | Usage error |
+
+## Fetch verified BibTeX
+
+Instead of writing an entry from memory, ask for it by DOI, arXiv ID or title. Every field
+comes from the registry record, which a comment above the entry names:
+
+```bash
+paper-preflight bib fetch 1810.04805
+```
+
+```bibtex
+% Verified with paper-preflight against dblp (conf/naacl/DevlinCLT19), 2026-10-03
+@inproceedings{devlin2019bert,
+  title         = {{BERT:} Pre-training of Deep Bidirectional Transformers for Language Understanding},
+  author        = {Devlin, Jacob and Chang, Ming-Wei and Lee, Kenton and Toutanova, Kristina},
+  booktitle     = {NAACL-HLT (1)},
+  year          = {2019},
+  doi           = {10.18653/v1/n19-1423},
+  eprint        = {1810.04805},
+  archivePrefix = {arXiv},
+}
+```
+
+- **Preprints:** an arXiv preprint that has been published comes back as the published version,
+  with its `eprint` kept (`--prefer preprint` for the preprint itself).
+- **Titles:** `--title` (with `--author`/`--year` if needed) lists the candidates instead of
+  choosing when several works match.
+- **Retractions:** a retracted work comes with a warning.
+- **Agents:** `--format json` is for scripts and agents.
+
+## Fix the bibliography
+
+`bib fix` turns findings into edits of your `.bib` files, taken from the verified records. It
+prints a diff and changes nothing until you add `--apply`:
+
+```bash
+paper-preflight bib fix path/to/paper --level unsafe
+```
+
+```diff
+--- a/refs.bib
++++ b/refs.bib
+@@ -48,7 +47,7 @@
+   title     = {Adam: A Method for Stochastic Optimization},
+   author    = {Kingma, Diederik P. and Ba, Jimmy},
+   booktitle = {International Conference on Learning Representations (ICLR)},
+-  year      = {2016},
++  year      = {2015},
+ }
+```
+
+- `--level safe` (the default) only fixes what cannot change which work is cited: identifiers
+  written so that links break, and DOIs the registry has but the entry lacks.
+- `--level unsafe` also rewrites authors, title, year and venue from the record, and removes
+  identifiers that point to another work. Review the diff first.
+- Only the affected fields change; comments, formatting, line endings and encoding are kept.
+  A reference nobody could find is never "fixed": only you can say what was meant.
+
+## Silence a finding you have checked
+
+A comment directly above an entry silences rules for that entry, with an optional reason:
+
+```bibtex
+% preflight: ignore[REF003] reason="internal technical report, not indexed anywhere"
+@techreport{lab2024internal,
+  ...
+}
+```
+
+The verdict stays in the JSON report; only the finding is dropped. A suppression that silenced
+nothing is reported as CFG001 (info), so stale comments do not pile up. Reference rules are only
+judged after a complete online run, since offline answers and outages may leave them unrun.
+
+## Use it from your coding agent
+
+**Claude Code** — install the plugin. It bundles an MCP server and a skill that makes Claude
+check the references before calling a paper finished, fix only what is proven wrong, and never
+invent a reference.
+
+```bash
+claude plugin marketplace add amos689/paper-preflight
+```
+
+```bash
+claude plugin install paper-preflight@paper-preflight
+```
+
+**Codex, Cursor, VS Code and other MCP clients** — run `paper-preflight mcp`. The tools are
+read-only and confined to your workspace; see [docs/mcp.md](https://github.com/amos689/paper-preflight/blob/main/docs/mcp.md).
+
+**pre-commit** — check citation keys and cached verdicts on every commit in seconds; see
+[docs/pre-commit.md](https://github.com/amos689/paper-preflight/blob/main/docs/pre-commit.md).
+
+**GitHub Actions** — `uses: amos689/paper-preflight@main` checks the paper on every push, with
+the report in the job summary and optional code-scanning alerts; see
+[docs/github-action.md](https://github.com/amos689/paper-preflight/blob/main/docs/github-action.md).
+
+## Better results with free credentials
+
+paper-preflight works without any account. These optional environment variables make it faster
+and more complete; their values are never printed or logged.
+
+| Variable | Effect |
+|---|---|
+| `PAPER_PREFLIGHT_EMAIL` | Crossref's polite pool: faster, more reliable lookups |
+| `OPENALEX_API_KEY` | A larger OpenAlex budget for retraction checks |
+| `S2_API_KEY` | Semantic Scholar as a rescue source for references nobody else found |
+
+`paper-preflight doctor` shows which are set and whether each source answers right now.
+
+## How it works
+
+1. **Source-first.** It reads the LaTeX project as LaTeX sees it: comments, `\iffalse` blocks and
+   `\includeonly` are respected, `.aux` files are used when they are fresh, and the first
+   definition of a duplicated key wins, as in BibTeX.
+2. **Identifier-first routing.** DOIs go to their registration agency (doi.org tells which:
+   Crossref, DataCite, …). arXiv IDs go to arXiv, with DataCite as a fallback, and PMIDs and
+   PMCIDs to PubMed (which also marks retracted articles). Entries without identifiers are searched by
+   title in dblp and Crossref.
+3. **Field-by-field matching with guards.** It compares titles (including earlier arXiv version
+   titles), authors (tolerating transcriptions such as Reiß/Reis), year and venue. A search
+   result is used only when enough of these agree and no other work fits as well; known fake
+   DOI copies are skipped.
+4. **One verdict per reference:** verified, metadata mismatch, identifier conflict, not found,
+   or cannot determine with a reason. "Not found" needs every required source to answer "no".
+5. **No LLM anywhere in the verdict.** Answers are cached locally (SQLite), so re-runs are fast
+   and `--offline` works.
+
+## Design principles
+
+- **Positive confirmation or abstain.** Rate limits, outages and unindexed works lead to "cannot
+  determine", never to "not found".
+- **Neutral wording.** Findings state observations ("not found in Crossref, dblp and Semantic
+  Scholar, and every source responded"), never accusations.
+- **Local-first, no telemetry.** Only the metadata of the cited works (DOIs, titles, authors) is
+  sent to the public scholarly APIs above. Your manuscript never leaves your machine.
+
+## What it will never do
+
+Help evade plagiarism or AI-text detection, scrape paywalled or bot-protected sites, recommend
+or "complete" references from memory, or name and shame authors.
+
+## Roadmap
+
+- The first PyPI release (v0.1)
+- Chinese-language references (v0.2)
+
+Progress is tracked in [docs/PROGRESS.md](https://github.com/amos689/paper-preflight/blob/main/docs/PROGRESS.md) (in Chinese) and the
+[changelog](https://github.com/amos689/paper-preflight/blob/main/CHANGELOG.md).
+
+## Contributing
+
+Bug reports with a reproducible `.bib` entry are the most valuable contribution, especially
+false positives. See [CONTRIBUTING.md](https://github.com/amos689/paper-preflight/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/amos689/paper-preflight/blob/main/LICENSE). See [THIRD_PARTY_NOTICES.md](https://github.com/amos689/paper-preflight/blob/main/THIRD_PARTY_NOTICES.md) for adapted code.