paperlint 2.1.0 → 3.1.0

package/CLAUDE.md

@@ -193,7 +193,7 @@ the CONFIG is not declaring something. Check that before adding a verb.
 
 `npm i -D paperlint` brings all the code — rules, skills, hooks, scripts. `paperlint init`
 then does what only a command can, because it depends on the project it lands in: it finds the
-papers directory and declares it in `package.json`, links each skill into `.claude/skills/`, writes
+papers directory and declares it in a root `paperlint.json` when it is not the default `papers`, links each skill into `.claude/skills/`, writes
 the hook commands into `.claude/settings.json` (vigiles' `mergeRegistrations`, reading
 `plugin/hooks/hooks.json` as the one source), and offers a CI workflow pinned to the installed
 release's tag. `paperlint doctor` reads all of it back. Details: `docs/install.md`.
@@ -520,6 +520,11 @@ import none of the three are frozen in `scripts/harness-api.frozen.json`, which
 exits 1 when no file matches, and it transpiles without type-checking, so `npm run check` runs
 `tsc -p tsconfig.test.json` as its own gate.
 
+**Local = the fast gates on what you touched; the full `npm run check` = CI.** Locally run vitest on
+the touched test files, `npx tsc --noEmit`, `npx eslint <touched files>` and `npm run fmt:check`, then
+push and read CI by job name. The repo is public, so CI is free, and it also runs the TeX e2e that
+cannot run locally; a local full run takes 10-15 min, most of it the mutation batteries (#52).
+
 ⚠️ **Not `vigiles test .`** — the `.` is read as a FILE, the runner dies with
 `ERR_UNSUPPORTED_DIR_IMPORT`, and it still exits 0. See the measured table below.
 

package/README.md

@@ -1,297 +1,305 @@
+<!--
+README style — keep it scannable, not a wall of text:
+- One idea per paragraph; paragraphs ≤ 3 lines. Split anything longer.
+- Every section starts with a heading (##); sub-topics get ###. No section longer than one screen.
+- Lists over prose for anything with 3+ items; bullets ≤ 2 lines.
+- Tables for comparisons (commands, venues, checks). Code blocks for every command and file.
+- A blank line between every block. Bold only for the one phrase a skimmer must see.
+- Mechanics and edge cases live in docs/, linked — not inline.
+- A reader must be able to answer "what is it, which venues, how do I start" from the first screen.
+- Sparse emoji are fine where they help rhythm and scanning (e.g. one per section heading or feature bullet); never decorative, never several in a row.
+- One name per thing, everywhere (lint, build, venue preset, kind, skill, papersDir), each explained once, before it is used.
+- Editing this file: re-read all of it first, and change it so it still reads as one document — the opening, the diagram, the order and the names your change touches. Remove or merge what it makes redundant. Never bolt on a section or patch one paragraph in isolation.
+-->
+
 # paperlint
 
 [![npm version](https://img.shields.io/npm/v/paperlint)](https://www.npmjs.com/package/paperlint)
 ![Node version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fzernie%2Fpaperlint%2Fmain%2Fpackage.json&query=%24.engines.node&label=node)
 
-A linter for scientific papers written in LaTeX. It catches the mechanical mistakes that get a
-paper desk-rejected or sent back at camera-ready, before you submit.
-
-A LaTeX paper can build without an error and still be wrong. The ACM template silently switches to
-another font when one of its font packages is missing, and the pages break differently. The same
-source paginates differently on a machine with another version of the template. The submitted PDF
-gets overwritten a week later and nobody can say what was sent. You find out from a reviewer or a
-publisher, or never. paperlint checks for these on your machine and in CI:
-
-- **Checks against your venue.** Point the paper's `paperlint.json` at a venue preset
-  (`"extends": "paperlint:aisec"`), build, lint: the page limit for your kind of paper, embedded
-  fonts and the template's font families, the paper size and column count, and the font sizes, as
-  the venue's call for papers sets them — plus the checks the venue implies, such as a balanced last
-  page. Presets ship for the ACM `acmart` sigconf family and three venues — AgenticDev and AISec
-  (ACM) and REALM (ACL); for any other venue, a preset is one JSON file in your repository
-  ([`docs/rules.md`](docs/rules.md#writing-your-own-venue-preset)).
-- **Builds the same PDF everywhere.** `paperlint toolchain` installs TeX Live with exactly the
-  packages your venue's template needs and checks that each one is really there, so the silent
-  font switch cannot happen and your laptop and CI build with the same TeX Live.
-- **Keeps what you submitted.** Record "submitted on 22 July, as this PDF", and paperlint fails if
-  that PDF changes or disappears, or its LaTeX source was not kept beside it.
-- **Knows the classic slips.** An ACM paper that overrides the title-page commands and loses part
-  of page 1; "code will be released" left in a camera-ready; references without a DOI or URL; an
-  unbalanced last page, for publishers that ask for balanced columns (an optional check).
-- **Works with coding agents.** Hooks and skills for Claude Code run the checks after every edit
-  and stop an agent from rewriting the paper around them.
-
-It is for researchers and engineers who write papers in LaTeX inside git and submit them to
-conferences or journals.
-
-## Install and set up
+**Write a research paper in LaTeX from idea to camera-ready, and catch what gets it sent back
+before you submit.** It comes in two parts:
+
+- ✅ **A linter** — a command-line tool, no AI needed. Its headline catches:
+  - 📏 a paper over the page limit for its kind at your venue;
+  - 🔤 the wrong font — LaTeX silently fell back to Computer Modern because a package was missing;
+  - 🔗 a bad reference — a cited work that does not exist, or lists the preprint's authors.
+
+  Smaller slips too: `§` for "Section", `.05` for `0.05` — fixed for you.
+
+- 🧠 **Skills for [Claude Code](https://claude.com/claude-code)** — optional, 24 of them, covering the
+  whole pipeline: the idea, the venue, the study, the draft, the reviews, submission.
+
+## Contents
+
+- [The pipeline](#-the-pipeline)
+- [Supported venues](#-supported-venues)
+- [Getting started](#-getting-started)
+  - [A new paper](#a-new-paper)
+  - [A paper you already have](#a-paper-you-already-have)
+- [Commands](#-commands)
+- [Skills](#-skills)
+- [Lint and build](#-lint-and-build)
+- [Configuration](#-configuration)
+  - [Add a venue that isn't listed](#-add-a-venue-that-isnt-listed)
+- [Run it in CI](#-run-it-in-ci)
+- [FAQ](#-faq)
+- [Docs](#-docs)
+
+## 🧭 The pipeline
+
+```text
+stage           what you get                          skills  linter
+1 idea          a go / no-go, with the reason         yes
+2 venue         venues ranked, deadlines planned      yes
+3 study         a study design, honest statistics     yes
+4 draft         a first draft, then a tighter one     yes     lint
+5 review        the objections, before the reviewers  yes     lint
+6 submit        a PDF within the limit, recorded      yes     build, lint
+7 camera-ready  the final, de-anonymised PDF          yes     build, lint
+8 extend        a plan for the next paper             yes
+
+skills: optional, with Claude Code
+lint:   every edit and every CI run, once the paper exists (paperlint new)
+build:  compiles and measures the PDF; lint then checks pages, fonts, references
+```
 
-<!-- `vigiles:symbol src/init.ts#init` — `npm run check` fails if this function is renamed or removed. -->
+## 🎯 Supported venues
 
-```sh
-npm i -D paperlint
-npx paperlint init
-```
+A **venue preset** holds a venue's format and page limits. A paper's **kind** picks which limit
+applies: at AgenticDev a `short` paper gets 5 pages and a `full` one 10. You choose it once per paper.
 
-Node 22.13 or newer. Install first: `paperlint init` links the skills and hooks to the copy in
-your project's `node_modules`, so run without the install it has nothing to link to.
+| preset                  | venue              | format             | kinds and page limits                                                                       |
+| ----------------------- | ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
+| `paperlint:acm-sigconf` | any ACM conference | ACM two-column     | no kinds: the format only, no page limit                                                    |
+| `paperlint:agenticdev`  | AgenticDev @ ASE   | ACM two-column     | `short` 5, `full` 10, `demo` 5 pages, + 2 pages of references                               |
+| `paperlint:aisec`       | AISec @ ACM CCS    | ACM two-column     | `research`, `benchmark`, `position`, `sok`: 10 pages + 2 pages of references                |
+| `paperlint:realm`       | REALM @ EMNLP      | ACL two-column, A4 | `long` 8, `short` 4 — recorded, not checked ([why](docs/rules.md#checks-against-the-venue)) |
 
-`paperlint init` finds your papers directory and records it in `package.json`, offers a CI workflow and a
-first paper, and sets up the optional Claude Code skills and hooks. It installs no software. It
-asks questions only when you run it in a terminal; an agent, CI or `--yes` gets the defaults, and
-each default it takes is printed. It ends by running `paperlint doctor`, which checks the setup.
-Exactly what it writes: [`docs/install.md`](docs/install.md#what-paperlint-init-writes).
+Not shipped yet: IEEE, USENIX, NeurIPS, Springer, and ACL venues other than REALM.
+[Add yours](#-add-a-venue-that-isnt-listed) in one small file.
 
-## What you get
+## 🚀 Getting started
 
-| command                       | what it does                                                                                       |
-| ----------------------------- | -------------------------------------------------------------------------------------------------- |
-| `npx paperlint init`          | sets the project up (see above)                                                                    |
-| `npx paperlint new my-paper`  | creates a paper folder from a template; never overwrites a file                                    |
-| `npx paperlint lint`          | runs every check over your papers; `npx paperlint lint papers/my-paper` checks one                 |
-| `npx paperlint build <paper>` | compiles `paper.tex` to `paper.pdf` with pdflatex and bibtex; `--all` builds every paper           |
-| `npx paperlint toolchain`     | installs TeX Live with the LaTeX packages your venues need; `--check` only reports what is missing |
-| `npx paperlint doctor`        | checks the setup and exits non-zero if something is miswired                                       |
-| `npx paperlint --help`        | every command and flag                                                                             |
+### A new paper
 
-A venue is the conference or journal you submit to. TeX Live is the standard LaTeX distribution;
-`paperlint build` offers to install it the first time it needs it.
+<!-- `vigiles:symbol src/init.ts#init` — `npm run check` fails if this function is renamed or removed. -->
 
-## Your first paper in five minutes
+1. Install (Node 22.13 or newer):
 
-### Starting a paper
+   ```sh
+   npm i -D paperlint
+   ```
 
-<!-- `vigiles:symbol src/new-paper.ts#newPaper` — `npm run check` fails if this function is renamed or removed. -->
+2. Set up. `init` asks three questions: where your papers live (default `papers/`), whether to
+   install TeX Live now, and whether to add a CI workflow. With Claude Code it also installs the
+   skills and three hooks ([what they do](docs/install.md)).
 
-After `npx paperlint init`:
+   ```sh
+   npx paperlint init
+   ```
 
-```sh
-npx paperlint new my-paper
-```
+3. Create a paper. `--venue` names its venue preset from the table above, `--kind` which of its page
+   limits applies:
 
-```
-  ✓ created papers/my-paper
-      + PIPELINE-STATUS.md  (from the package template)
-      + paper.tex  (from the package template)
-      + paperlint.json  (from the package template)
+   <!-- `vigiles:symbol src/new-paper.ts#newPaper` — `npm run check` fails if this function is renamed or removed. -->
 
-config: package.json
-…/papers/my-paper/paper.tex
-  1:1  warning  this paper names no venue preset yet, so its page limit, fonts and format are not checked — set "extends" in papers/my-paper/paperlint.json (e.g. "paperlint:agenticdev"; see docs/rules.md)  pdf/measured
+   ```sh
+   npx paperlint new my-paper --venue agenticdev --kind short
+   ```
 
-✖ 1 problem (0 errors, 1 warning)
-```
+   It writes `papers/my-paper/` (in the folder you gave `init`) with three files:
+   - `paper.tex` — your paper;
+   - `paperlint.json` — its venue preset and kind;
+   - `PIPELINE-STATUS.md` — which stage the paper is at; the skills read and update it.
 
-The warning is the only thing left to do: the paper does not say where it is going yet.
+4. Build the PDF. **This needs TeX Live, a ~270 MB download (~3 min, once).** If you said no in
+   `init`, run `npx paperlint toolchain` first.
 
-You now have one folder per paper:
+   ```sh
+   npx paperlint build papers/my-paper
+   ```
 
-```
-papers/
-  my-paper/
-    paper.tex                 the paper, in LaTeX
-    PIPELINE-STATUS.md        the paper's record: its research question and the stages it reached
-    paperlint.json            this paper's settings: its venue preset and kind — `new` writes it
-    reviews/*.md              review notes (optional)
-    versions/                 the exact PDF and source you sent at each stage, never edited
-```
+5. Check it:
 
-`paperlint new` writes `paperlint.json` with `"extends": null` and a comment saying what goes
-there. To have the paper checked against its venue, name the venue preset and the kind of paper:
+   ```sh
+   npx paperlint lint
+   ```
 
-```json
-{ "extends": "paperlint:aisec", "kind": "research" }
-```
+   On the stub from step 3 the first run already catches something (output shortened):
 
-Settings come in three levels, each named after the tool:
+   ```text
+   papers/my-paper/paper.tex
+     1:1   error    1 column(s), agenticdev requires 2 — the wrong document class or class option   pdf/geometry
+     1:1   error    no font starts with `LinLibertine` (body text of agenticdev); the PDF has: CMR10, …   pdf/fonts
+     8:4   warning  `§` instead of the word «Section» — `paperlint lint --fix` writes it              paper/section-word
+   ```
 
-```
-package.json            "paperlint": { "papersDir": "papers" }        the project
-papers/my-paper/
-  paperlint.json        { "extends": "paperlint:aisec", … }            this paper
-paperlint:aisec         a venue preset: shipped, or ./your-venue.jsonc  the venue
-```
+   `new` writes a format-neutral stub in plain `article`, and AgenticDev wants ACM's class. Make
+   the first line `\documentclass[sigconf]{acmart}`, build again, and the errors are gone.
 
-More in [`docs/configuration.md`](docs/configuration.md#three-levels-of-settings).
-`paperlint.json` replaces `venue.json` (2.1.0); `npx paperlint init` moves it.
+### A paper you already have
 
-A **stage** is a point the paper has reached, such as `submitted` or `camera-ready` (the final
-version for the proceedings). The name may use `a-z`, `0-9`, `.`, `_` and `-`. On a folder that
-already exists, `paperlint new` adds only the missing files. To use your own templates, put files with
-the same names in `papers/.template/`; `{{name}}` in them becomes the paper's name.
+paperlint finds a paper by its folder: `<papersDir>/<name>/`, with the main file named `paper.tex`.
 
-Write the paper, then check and build it:
+1. Put the paper there — for example `papers/my-paper/paper.tex`, the rest of its files beside it. If
+   your paper folders already live elsewhere, say `thesis/`, [set `papersDir`](#-configuration) instead.
+2. Run `npx paperlint new my-paper --venue <preset> --kind <kind>`. On an existing folder it only
+   adds the missing `paperlint.json` and `PIPELINE-STATUS.md`; it never touches `paper.tex`.
+3. Build and lint, as above.
 
-```sh
-npx paperlint lint                     # check every paper
-npx paperlint build papers/my-paper    # writes papers/my-paper/paper.pdf
-```
+## 🧰 Commands
 
-`paperlint build` runs pdflatex and bibtex until the references settle. There is no build script to
-write; a `build.sh` in the paper folder is ignored.
+| command                                                     | what it does                                                                   |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `npx paperlint init`                                        | sets the project up                                                            |
+| `npx paperlint new my-paper --venue <preset> --kind <kind>` | creates a paper folder for that venue, or completes an existing one            |
+| `npx paperlint build <paper>`                               | compiles `paper.tex` to `paper.pdf`, measures it, checks the references online |
+| `npx paperlint lint`                                        | runs every check over your papers; `--fix` fixes what can be fixed             |
+| `npx paperlint toolchain`                                   | installs TeX Live with the packages your venues need (~270 MB, ~3 min, once)   |
+| `npx paperlint doctor`                                      | checks the setup and exits non-zero if something is miswired                   |
+| `npx paperlint --help`                                      | every command and flag                                                         |
 
-When you submit, copy the PDF and `paper.tex` into `versions/` and record the stage in the front
-matter of `PIPELINE-STATUS.md`, with the file sizes in bytes:
+## 🧠 Skills
 
-```yaml
-stages:
-  - stage: submitted
-    date: 2026-07-22
-    venue: A Venue 2026
-    pdf: versions/2026-07-22-submitted.pdf
-    bytes: 305412
-    source: versions/2026-07-22-submitted.tex
-    sourceBytes: 57210
-```
+You do not need to learn the skills' names: you ask Claude Code, and the matching skill starts.
+`paper-pipeline` walks you through the stages; any skill also starts on its own when you ask for
+what it does — "is this idea worth a paper?", "find me a venue for this". `init` installs them.
 
-From then on `paperlint lint` fails if that PDF goes missing or changes size. A frozen PDF should never
-change, so a size that no longer matches means the file was replaced after you recorded it
-([`docs/rules.md`](docs/rules.md#the-scorecards-bytes-and-sourcebytes)).
+- **A go / no-go on your idea, with the reason.** `research-ideate`
+- **A ranked list of venues that fit** — deadline, page limit, indexing. `find-venue`
+- **A first draft from your results.** `draft-paper`
+- **A hostile review before the real one.** `paper-adversarial-review`
+- **A ready / not ready verdict before you submit**, worst problem first. `harden-paper`
+- **Where your paper stands**, measured from the real build. `paper-status`
 
-### What a finding looks like
+All 24, by stage: [`docs/skills.md`](docs/skills.md).
 
-On a paper folder made by hand, with only `paper.tex`:
+## 🔍 Lint and build
 
-```
-config: package.json
-papers/my-paper
-  error  missing `PIPELINE-STATUS.md` — `paper/stages`, `paper/source` and `paper/author-list` read this file, so nothing `my-paper` declares about its stages, sources or authors is checked
-…/my-papers/papers/my-paper/paper.tex
-  1:1  warning  1 × `§` instead of «Section» (reviewer B). Paying the debt down is silent; growth is reported                                                 paper/typography
-  1:1  warning  1 × a decimal without a leading zero, `.05` instead of `0.05` (IEEE / ISO 80000-1 style). Paying the debt down is silent; growth is reported  paper/typography
-
-✖ 2 problems (0 errors, 2 warnings)
-```
+|        | `paperlint build`                                                                            | `paperlint lint`                                                                                      |
+| ------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| needs  | Node, TeX Live, the network                                                                  | Node                                                                                                  |
+| does   | compiles `paper.tex`, measures the PDF, checks each reference online (exists, right authors) | checks the source, and judges what build recorded: page limit, fonts, the reference results — offline |
+| writes | `paper.pdf`, and in `_build/` the measurements and the reference results                     | nothing (`--fix`: the three fixable slips)                                                            |
 
-Each finding gives the file, line and column, the level, what is wrong, and the check that found
-it. The first line is an error about the folder: without `PIPELINE-STATUS.md`, the three checks
-that read it have nothing to check; `npx paperlint new my-paper` adds the file and leaves `paper.tex`
-alone. The two warnings count typography slips against an allowance you can set per paper: going over
-it is reported, fixing some is not ("paying the debt down is silent").
+- If `paper.pdf` or the bibliography changed since the last build, lint fails and tells you to rebuild.
+- Lint also checks the pipeline's own records: `PIPELINE-STATUS.md`, reviews, notes on related
+  papers ([`docs/rules.md`](docs/rules.md)).
+- The rules run on ESLint, so a deliberate exception is a comment on the line above:
+  `% eslint-disable-next-line paper/leading-zero -- quoted from the reviewer`.
+- Errors fail the run; warnings only print, unless you pass `--max-warnings <n>`.
 
-`paperlint lint` exits `1` when any check reports an error (as here, even though the summary line counts
-only the warnings in files), or when it checked no files at all (usually a wrong path). Warnings
-never fail the run unless you pass `--max-warnings <n>`. `--json` prints the findings as JSON.
+Every check: [`docs/rules.md`](docs/rules.md). How build compiles:
+[`docs/configuration.md`](docs/configuration.md#how-paperlint-build-compiles-a-paper).
 
-## Run it in CI
+## 🧩 Configuration
 
-`paperlint init` offers to write this GitHub Actions workflow step for you. By hand:
+Two levels, one file name, both optional:
 
-```yaml
-- uses: zernie/paperlint@v2.0.0
-  with:
-    paths: papers
 ```
+paperlint.json                   the project: papersDir, rules, defaults for every paper
+papers/my-paper/paperlint.json   one paper: its venue preset ("extends"), its kind, its own rules
+```
+
+- `papersDir` is the folder that holds your paper folders; it defaults to `papers`.
+- The paper's venue preset is its `"extends"` key — the one `new --venue` writes.
+- A paper's `paperlint.json` overrides the project's, key by key.
+- **An unknown key is an error**, so a typo cannot silently turn a setting off.
 
-Use the tag of the version you installed (`npm ls paperlint`): every npm release has
-a git tag of the same version, so the step runs the same code as your package. It runs
-`paperlint lint`. `paths` is required, and the step fails if it checked zero files, so a typo in the path
-shows up red. Optional inputs: `config`, `max-warnings` (default `-1`, no limit), `texcount` (default
-`true`), `working-directory`.
-
-## What the checks catch
-
-| check                          | level   | catches                                                                                                          |
-| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------- |
-| `paper/stages`                 | error   | a stage's PDF is missing, or it is not the same file any more (its size changed)                                 |
-| `paper/source`                 | error   | a stage has no frozen source file next to its PDF                                                                |
-| `paper/author-list`            | warning | a stage is declared, but `PIPELINE-STATUS.md` does not record that the author list was checked                   |
-| `paper/research-question`      | warning | the research question is missing from `PIPELINE-STATUS.md`, or the paper does not contain that sentence          |
-| `paper/typography`             | warning | more `§`, `.05`-style decimals, mixed `Fig.`/`Figure`, or references without a DOI or URL than you allowed       |
-| `tex/future-promise`           | warning | a camera-ready still says your code "will be released"                                                           |
-| `tex/acm-frontmatter-override` | error   | an ACM paper overrides the template's title-page commands, so parts of page 1 go missing                         |
-| `review/findings-cause`        | error   | a review note lists several findings and names no cause for any of them                                          |
-| `doc/fields`                   | warning | a review note's front matter is missing a field you require (off unless configured)                              |
-| `pdf/limits`                   | error   | more body or reference pages than the venue allows for your kind of paper, or a reference font size out of range |
-| `pdf/fonts`                    | error   | a Type 3 or unembedded font, or the venue template's fonts are missing (a silent Computer Modern fallback)       |
-| `pdf/geometry`                 | error   | the paper size or column count differs from the venue's                                                          |
-| `pdf/body-size`                | warning | the body font size is off the venue's                                                                            |
-| `pdf/profile`                  | error   | the paper's `extends` names no preset (a typo), or a kind of paper the venue does not have                       |
-| `pdf/fresh`                    | error   | the build facts describe an earlier PDF than the one on disk                                                     |
-| `pdf/measured`                 | warning | the venue checks did not run: the paper names no venue preset yet, or was not built                              |
-
-The `pdf/` checks run only for a paper whose `paperlint.json` extends a venue preset, and they judge the PDF
-`paperlint build` made: build, then lint. Errors fail the run; warnings only print. What each check
-reads: [`docs/rules.md`](docs/rules.md).
-Checks that only some venues need are off until you turn them on:
-[`docs/optional-rules.md`](docs/optional-rules.md).
-
-## Configuration
-
-`paperlint init` writes the one required setting into `package.json`:
-
-```json
+Every key: [`docs/configuration.md`](docs/configuration.md). Already use ESLint for other files? See
+[`docs/configuration.md`](docs/configuration.md#using-the-rules-from-an-existing-eslint-config).
+
+### ➕ Add a venue that isn't listed
+
+A venue preset is a small JSONC file: the preset it builds on, and the page limit of each kind of
+paper. For an ACM workshop with a 4-page limit for short papers, `venues/my-workshop.jsonc`:
+
+```jsonc
 {
-  "paperlint": {
-    "papersDir": "papers"
-  }
+  // page size, columns and fonts of the ACM two-column format
+  "extends": "paperlint:acm-sigconf",
+  "format": {
+    // one entry per kind of paper the call for papers names
+    "kinds": {
+      // the limit from the call for papers, in pages, references not counted
+      "short": { "body_pages_max": 4 },
+    },
+  },
 }
 ```
 
-`papersDir` has no default, so the tool never checks a folder you did not choose: without it,
-`paperlint lint` stops and says so, unless you pass a path. An unknown key is an error. The optional
-settings, and how to use the checks inside your own ESLint setup, are in
-[`docs/configuration.md`](docs/configuration.md). TeX Live, its install location and the external
-programs the skills use are in [`docs/toolchain.md`](docs/toolchain.md).
+```sh
+npx paperlint new my-paper --venue ./venues/my-workshop.jsonc --kind short
+```
+
+Give the path from where you run the command; `new` rewrites it relative to the paper's own
+`paperlint.json`. A venue in another format: [`docs/rules.md`](docs/rules.md#writing-your-own-venue-preset).
+
+## 🤖 Run it in CI
+
+Two options:
 
-## Claude Code (optional)
+| job                        | time                          | checks                                     |
+| -------------------------- | ----------------------------- | ------------------------------------------ |
+| build, then lint           | ~3 min first run, then cached | everything                                 |
+| lint only (`init` adds it) | seconds                       | the source; not pages, fonts or references |
 
-`paperlint lint` needs only Node. If you use Claude Code, `paperlint init` also sets up two things:
+Lint judges pages, fonts and references from what build measured, so the full job builds first:
+
+```yaml
+name: papers
+on: [push, pull_request]
+jobs:
+  papers:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/paperlint/texlive
+          key: texlive-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+      - run: npx paperlint toolchain
+      - run: npx paperlint build --all
+      - run: npx paperlint lint
+```
 
-**Skills** — one per stage of writing a paper, from checking the idea through drafting, review,
-submission and camera-ready. They are linked into `.claude/skills/`. Start with `/paper-pipeline`;
-it routes to the rest. Some call Java or Python 3, which you install yourself.
+Lint only — each paper then gets one warning that it was not built:
 
-**Hooks** — written into `.claude/settings.json`. Commit that file so every clone gets them; a
-fresh clone needs `npm install` before they run.
+```yaml
+- uses: zernie/paperlint@v3.0.0
+  with:
+    paths: papers # your papersDir
+```
 
-| hook                 | blocks? | what it does                                                     |
-| -------------------- | ------- | ---------------------------------------------------------------- |
-| `paper-edit-guard`   | yes     | stops a shell command from writing to a paper file               |
-| `paper-skills-nudge` | no      | after a paper edit, shows the agent the pre-submission checklist |
-| `paper-status-gates` | no      | after a paper edit, lists the stages that have not run yet       |
+## ❓ FAQ
 
-**Know this about `paper-edit-guard`:** if the `paperlint` key in `package.json`
-cannot be read (the file is missing, or has merge-conflict markers), it blocks **every** shell
-command in Claude Code, not only paper ones, until the key is readable again. Fix `package.json`
-with a normal file edit — those are not blocked.
+**Does it install anything without asking?**
+No. TeX Live comes only from `paperlint toolchain`, or when you say yes in `init` or `build`. On
+Windows, install TeX Live yourself.
 
-## What it does not do
+**Several papers for different venues in one repo?**
+Yes. Each paper names its own venue preset in its own `paperlint.json`.
 
-- **It does not install software behind your back.** `paperlint init` installs nothing; TeX Live comes
-  only from `paperlint toolchain` or when you answer yes in `paperlint build`. On Windows, install TeX Live
-  yourself.
-- **It does not guess what to check.** There is no default papers directory.
-- **It does not overwrite your files.** `paperlint new` and `paperlint init` only add what is missing.
-- **It does not run your build script.** `paperlint build` compiles the paper itself.
-- **It does not write or grade the paper.** `paperlint lint` checks records and a few mechanical
-  mistakes; judging the writing is what the optional skills are for.
-- **New papers are LaTeX.** Markdown papers (`paper.md`) are still read but deprecated
-  ([#57](https://github.com/zernie/paperlint/issues/57)).
-- **No Yarn Plug'n'Play.** npm and pnpm are supported
-  ([`docs/install.md`](docs/install.md#package-managers)).
+**Does it change my paper?**
+Only `paperlint lint --fix`, and only three rules: `paper/section-word` (`§` → Section),
+`paper/leading-zero` (`.05` → `0.05`) and `paper/figure-ref-style` (one figure-reference style).
 
-## Contributing
+## 📚 Docs
 
-See [`CONTRIBUTING.md`](CONTRIBUTING.md): how the package is tested, the one command that runs
-every check, and how releases work: the pull-request title decides the version (`feat:` is a
-minor release, `fix:` a patch).
+- [`docs/skills.md`](docs/skills.md) — every skill, by stage
+- [`docs/install.md`](docs/install.md) — what `init` does, the hooks, package managers, troubleshooting
+- [`docs/configuration.md`](docs/configuration.md) — every setting, how `build` compiles, using your own ESLint
+- [`docs/rules.md`](docs/rules.md) — every check, venue presets, recording a submitted PDF
+- [`docs/optional-rules.md`](docs/optional-rules.md) — checks only some venues need
+- [`docs/toolchain.md`](docs/toolchain.md) — TeX Live, and Banal (HotCRP's page-geometry checker, GPL)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how the package is tested and released, and adding a venue to it
 
 ## License
 
-MIT.
-
-**banal is not part of this package.** banal, the page-geometry script from
-[HotCRP](https://github.com/kohler/hotcrp) (Geoffrey M. Voelker, Eddie Kohler), is licensed
-GPL-2.0-or-later. paperlint does not contain, copy or modify it: `paperlint toolchain` downloads it from HotCRP
-at a pinned commit, checks its sha256, and paperlint runs it as a separate program (`perl banal …`),
-reading its JSON output. Details: [`docs/toolchain.md`](docs/toolchain.md#page-geometry-banal-without-poppler).
+MIT. Banal, used for page geometry, is GPL and not part of this package:
+[`docs/toolchain.md`](docs/toolchain.md#page-geometry-banal-without-poppler).

package/action.yml

@@ -26,11 +26,9 @@ description: Install the toolchain the texcount/* rules need, run ESLint, and re
 inputs:
   config:
     description: >-
-      Path to the `package.json` holding the `paperlint` settings. Optional: `paperlint lint` finds it by walking up from the working directory,
-      the way eslint and tsc find theirs, so most callers never set this. Pass it only when the
-      file is somewhere the walk cannot reach. ⚠️ Until 2026-09-18 this input took a path to an
-      ESLint FLAT CONFIG and defaulted to `eslint.config.mjs`; a caller still passing one will
-      fail loudly on the first run rather than lint against it.
+      Path to the project's root `paperlint.json`. Optional, and so is the file: `paperlint lint`
+      finds it by walking up from the working directory, the way eslint and tsc find theirs, so
+      most callers never set this. Pass it only when the file is somewhere the walk cannot reach.
     required: false
     default: ""
   paths:
@@ -135,4 +133,4 @@ runs:
         npx paperlint lint $PAPERLINT_PATHS ${PAPERLINT_CONFIG:+--config "$PAPERLINT_CONFIG"} \
           --max-warnings="$PAPERLINT_MAXWARN" --json > "$RUNNER_TEMP/paperlint-report.json" || RC=$?
         node "$GITHUB_ACTION_PATH/scripts/eslint-report-guard.mjs" \
-          "$RUNNER_TEMP/paperlint-report.json" "$RC" "$PAPERLINT_PATHS" "${PAPERLINT_CONFIG:-package.json}"
+          "$RUNNER_TEMP/paperlint-report.json" "$RC" "$PAPERLINT_PATHS" "${PAPERLINT_CONFIG:-paperlint.json}"

package/dist/adapters/references/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The online reference checks, as the `CheckReferences` port: `verify-cites` (the cited work
+ * exists, the title matches — Crossref, OpenAlex, Semantic Scholar, arXiv) and `bib-authors` (the
+ * authors are the published version's — DBLP). Both ship in this package's verify-citations skill;
+ * this adapter only runs them and shapes their answers.
+ *
+ * "Not checked" is decided up front, by one request: when Crossref cannot be reached at all, the
+ * checkers would degrade every entry to `unresolvable` / `unchecked`, which reads like a result.
+ * Saying `not-checked` with the reason is the honest record.
+ */
+import type { CheckReferences } from "../../ports/check-references.ts";
+export declare const onlineReferences: CheckReferences;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/references/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/references/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,iCAAiC,CAAC;AAwEzC,eAAO,MAAM,gBAAgB,EAAE,eAgB9B,CAAC"}