paperlint 2.1.0 → 3.1.0

package/docs/install.md

@@ -14,21 +14,6 @@ npx paperlint init
 Two commands in one terminal, in this order: `init` links the skills and hooks to the copy in
 your project's `node_modules`, so it needs the install first.
 
-**Upgrading from `research-paper-pipeline`** (the package's name before 2.0.0):
-`npm rm research-paper-pipeline && npm i -D paperlint`, then `npx paperlint init`. It moves the
-`"research-paper-pipeline"` key in `package.json` to `"paperlint"`, and replaces the hook commands
-and skill links that pointed into the old package. Until then the old key is still read, with a
-warning.
-
-**Upgrading from 2.0.0**: 2.0.0 wrote hook commands that run `node_modules/paperlint/bin/rpp.mjs`,
-a file later versions do not ship, so those hooks stop running. `npx paperlint doctor` names them;
-`npx paperlint init` replaces them and keeps your own commands in the same matcher. The TeX Live
-and banal caches moved from `~/.cache/rpp/` to `~/.cache/paperlint/`, so `npx paperlint toolchain`
-downloads TeX Live once more (delete the old directory afterwards), and the environment variables
-are now `PAPERLINT_TEXLIVE_DIR`, `PAPERLINT_BANAL_DIR` and `PAPERLINT_CTAN_MIRROR` — the `RPP_*`
-names are no longer read. A leftover `rpp.json` is ignored; its settings belong under the
-`"paperlint"` key of `package.json`.
-
 The npm package carries everything: the `paperlint` command, the ESLint rules, the Claude Code skills
 and hooks, and the scripts the skills run. External programs are separate:
 
@@ -43,15 +28,18 @@ and hooks, and the scripts the skills run. External programs are separate:
 
 In order:
 
-1. **Finds the papers directory**, or asks for it. The project must have a `package.json`; without
-   one `init` stops and tells you to run `npm init -y` first.
-2. **Declares it once**, as the `paperlint` key in your `package.json`.
+1. **Finds the papers directory**, or asks for it when several directories look like one.
+2. **Declares it**, in a root `paperlint.json`, only when it is not the default `papers`. A project
+   on the defaults gets no config file at all.
 3. **Links each shipped skill** into `.claude/skills/<name>`, where Claude Code looks for skills.
 4. **Writes the hook commands** into `.claude/settings.json`, beside your own entries.
 5. **Offers a GitHub Actions workflow**, pinned to the release tag of the version you installed.
 6. **Offers a first paper** (`paperlint new`) if the papers directory has none.
-7. **Reports missing external programs** and the command that installs each. It installs nothing.
-8. **Runs `paperlint doctor`** and exits with its verdict.
+7. **Offers TeX Live** for `paperlint build` (`paperlint toolchain`, ~270 MB, ~3 min, once), with
+   the size in the question and NO as the default. Without a terminal it asks nothing and lists the
+   command as the next step. `paperlint lint` needs no TeX.
+8. **Reports missing external programs** and the command that installs each. It installs nothing.
+9. **Runs `paperlint doctor`** and exits with its verdict.
 
 It asks only what it cannot guess or what costs something. A human at a terminal is asked; an
 agent, CI or `--yes` takes the defaults, and `init` prints which default it took. An unanswered
@@ -61,23 +49,23 @@ question (Ctrl+D) also takes the default.
 
 | what                                                               | where                   | when                                                                                                                                                                              |
 | ------------------------------------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| a `paperlint` key naming your papers directory                     | your `package.json`     | always                                                                                                                                                                            |
+| `{ "papersDir": … }` naming your papers directory                  | `paperlint.json`        | only when it is not the default `papers`                                                                                                                                          |
 | the three hook commands, merged in beside your own entries         | `.claude/settings.json` | by default. A human at a terminal is asked [Y/n]; an agent, CI or `--yes` gets YES; `--no-hooks` skips. Hand-wired under another spelling: nothing written, so nothing runs twice |
 | a GitHub Actions workflow, pinned to `@v<installed version>`       | `.github/workflows/`    | only if you say yes; it asks once, and only when a human is at a terminal (stdin and stdout, no `CI`, no `--yes`)                                                                 |
 | a first paper, via `paperlint new`                                 | `<papers>/<name>/`      | only when the papers directory holds none: asked of a human at a terminal, otherwise only with `--paper <name>`                                                                   |
 | one relative symlink per shipped skill, into the installed package | `.claude/skills/<name>` | always — except where that name is already taken (a directory, a file, a link elsewhere): that entry is left as it is and named in the report                                     |
 
-It installs no software and touches nothing else. Commit `.claude/settings.json` so every clone
+It installs no software you did not say yes to, and touches nothing else. Commit `.claude/settings.json` so every clone
 gets the hooks; the hook commands run files inside `node_modules`, so a fresh clone needs
 `npm install` first.
 
 ## Why it is shaped this way
 
-**One declaration, in `package.json`.** A hook cannot import code or walk up a tree looking for a
-config; it can only read a path it can spell, and the one it can always spell is
-`$CLAUDE_PROJECT_DIR/package.json`. That key is read by the three hooks, `eslint-rules/papers.mjs`,
-`lib/skill-trigger-cases.mjs` and `skills/paper-pipeline/scripts/consumer.mjs`; a separate
-config file would be read only by the CLI, so there is none.
+**One file, at the project root.** A hook cannot import code or walk up a tree looking for a
+config; it can only read a path it can spell, and `$CLAUDE_PROJECT_DIR/paperlint.json` is one. The
+same file is read by the CLI, the three hooks, `eslint-rules/papers.mjs`,
+`lib/skill-trigger-cases.mjs` and `skills/paper-pipeline/scripts/consumer.mjs`. It is optional:
+absent, every reader takes the same defaults.
 
 **Nothing runs at install time.** No postinstall script and no automatic TeX download. npm's rule
 is that _"the only valid use of install or preinstall scripts is for compilation"_; husky removed
@@ -110,9 +98,7 @@ resolve.
 nothing while guarding and says nothing while watching a directory that does not exist, so
 "installed" and "protecting you" look the same from outside. `doctor` prints the papers directory
 `paperlint lint` resolves and the one the hooks resolve, whether they match, whether the hooks are wired
-(once, twice, or not at all), and which external programs are missing. It also warns when the
-project still enables the old `research-paper-pipeline` plugin, because plugin plus settings would
-run every hook twice. A plugin installed at user scope is outside what it can read, and it says so.
+(once, twice, or not at all), and which external programs are missing.
 
 ### How comparable tools install
 
@@ -166,13 +152,12 @@ Neither `paperlint lint` nor any of the three hooks loads `@ast-grep` or `typesc
 
 ## Troubleshooting
 
-| symptom                                                      | cause and fix                                                                                                                                   |
-| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `init`: skills "nothing linked", or hooks that fail to start | the package is not installed in this project (`npx` ran a temporary copy). Run `npm i -D paperlint`, then `npx paperlint init` again            |
-| `init` stops: no `package.json`                              | run `npm init -y`, then `npx paperlint init` again                                                                                              |
-| `paperlint lint`: `nothing to lint`                          | no declaration was found. Run `npx paperlint init`, or pass the directory: `paperlint lint papers`                                              |
-| hooks fail with `Cannot find module` in a fresh clone        | the hook commands run files in `node_modules`: run `npm install`                                                                                |
-| `paperlint: not built`                                       | installed from git with `--ignore-scripts`, or a clone before building: run `npm run build` in the package                                      |
-| every hook runs twice                                        | the project still enables the old plugin. `init` and `doctor` print the uninstall command; also remove it from `enabledPlugins`                 |
-| a skill does not show up in Claude Code                      | its name was already taken in `.claude/skills/`. `init` names it and leaves it alone; rename or remove yours and run `npx paperlint init` again |
-| anything else                                                | `npx paperlint doctor` — it checks the setup and exits non-zero on anything miswired                                                            |
+| symptom                                                      | cause and fix                                                                                                                                                                          |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`: skills "nothing linked", or hooks that fail to start | the package is not installed in this project (`npx` ran a temporary copy). Run `npm i -D paperlint`, then `npx paperlint init` again                                                   |
+| `paperlint lint`: `no papers in papers/`                     | there is no paper where `papersDir` points. Create one with `npx paperlint new <name>`, or set `"papersDir"` in `paperlint.json`                                                       |
+| hooks fail with `Cannot find module` in a fresh clone        | the hook commands run files in `node_modules`: run `npm install`                                                                                                                       |
+| `paperlint: not built`                                       | installed from git with `--ignore-scripts`, or a clone before building: run `npm run build` in the package                                                                             |
+| a skill does not show up in Claude Code                      | its name was already taken in `.claude/skills/`. `init` names it and leaves it alone; rename or remove yours and run `npx paperlint init` again                                        |
+| **every** shell command is blocked in Claude Code            | `paper-edit-guard` cannot parse the root `paperlint.json` (merge-conflict markers, a typo), and refuses rather than guess. Fix it with a normal file edit — file edits are not blocked |
+| anything else                                                | `npx paperlint doctor` — it checks the setup and exits non-zero on anything miswired                                                                                                   |

package/docs/optional-rules.md

@@ -3,9 +3,10 @@
 Some checks matter only for some venues. paperlint ships them **off**. A venue preset that needs one
 turns it on for its papers (AgenticDev's turns on `pdf/last-page-balance`), and a paper can turn one
 on or off for itself in its own `paperlint.json`
-([`configuration.md`](configuration.md#three-levels-of-settings)). No glob is involved: a paper's
-rules apply to that paper. The `rules` setting of your `package.json` still overrides both, for one
-paper or many ([`configuration.md`](configuration.md#the-rules-key-turning-rules-on-and-off)).
+([`configuration.md`](configuration.md#a-papers-paperlintjson)). No glob is involved: a paper's
+rules apply to that paper. The root `paperlint.json` can turn it on for every paper, or for some
+with a block ([`configuration.md`](configuration.md#the-rules-key-turning-rules-on-and-off)); a
+paper's own file still has the last word for that paper.
 
 | rule                    | what it checks                                                | who needs it                                              |
 | ----------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
@@ -48,7 +49,7 @@ So: **build, then lint.**
 | a review build with numbered lines                  | nothing — the numbers run down the whole page, so both columns measure full height, and balance is a camera-ready requirement     |
 
 If you turn the rule on — in a `paperlint.json` beside no `paper.tex`, or with a `files` glob in
-`package.json` that reaches none — `paperlint lint` fails and says so, rather than reporting a clean
+the root `paperlint.json` that reaches none — `paperlint lint` fails and says so, rather than reporting a clean
 run for a rule that never ran.
 
 ### Which venues need it

package/docs/rules.md

@@ -3,29 +3,63 @@
 The README lists what each check catches in one line. This page says exactly which file each one
 reads and when it fails. Errors fail `paperlint lint`; warnings print and do not.
 
-| Rule                           | Level | Reads                                         | Fails when                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------ | ----- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `paper/stages`                 | error | `PIPELINE-STATUS.md`                          | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares                                                                                                                                                                                                                                                                                                                  |
-| `paper/source`                 | error | `PIPELINE-STATUS.md`                          | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it)                                                                                                                                                                                                                                                                                                                                                  |
-| `paper/author-list`            | warn  | `PIPELINE-STATUS.md`                          | a stage is declared and **no cell of the scorecard's table contains the run marker** (default `bib-authors`). It checks that you recorded the cross-check; it does not read your `.bib`. What to run is your own `authorListCommand`, empty by default                                                                                                                                                                                                          |
-| `paper/research-question`      | warn  | `paper.tex`, `paper.md`, `PIPELINE-STATUS.md` | a stage is declared and either the scorecard has no `researchQuestion` field, or it has one the paper does not contain. The declared sentence is compared against the source with whitespace collapsed — your words, not a pattern. Advisory, because nothing here can judge whether what you declared _is_ a research question                                                                                                                                 |
-| `paper/typography`             | warn  | `paper.tex`, `paper.md`                       | any of four counts rises above the per-paper allowance you set: `§` or `\S\ref` instead of "Section"; a decimal with no leading zero (`.05` instead of `0.05`, IEEE / ISO 80000-1 style), counted only where the reader sees it — prose, math and table cells, not macro options, column specs, comments, code or tikz; `Fig.` and `Figure` mixed in one document; bibliography entries with no doi, url or arXiv id. Existing debt is tolerated, growth is not |
-| `tex/future-promise`           | warn  | `paper.tex`                                   | a camera-ready build still says "will be released" about something already handed over                                                                                                                                                                                                                                                                                                                                                                          |
-| `tex/acm-frontmatter-override` | error | `paper.tex`                                   | an `acmart` build overrides ACM's front-matter commands and drops template elements from page 1                                                                                                                                                                                                                                                                                                                                                                 |
-| `review/findings-cause`        | error | `reviews/*.md`                                | a review lists at least `minFindings` (default 3) findings and no cell introduces a cause with the marker (default `Cause:`)                                                                                                                                                                                                                                                                                                                                    |
-| `doc/fields`                   | warn  | `reviews/*.md`                                | a front-matter field is missing or holds a value outside the list you configured. Off entirely unless you configure `docFields`                                                                                                                                                                                                                                                                                                                                 |
-| `pdf/fresh`                    | error | `paper.tex` → `_build/paper.facts.json`       | the paper names a venue and the facts cannot be judged: not JSON, a schema other than 2, or they describe a PDF that is gone or differs from the one on disk (its SHA-256)                                                                                                                                                                                                                                                                                      |
-| `pdf/profile`                  | error | `paper.tex` → `paperlint.json`                | `paperlint.json` is not JSON or has an unknown key, only a pre-2.1.0 `venue.json` is there (`npx paperlint init` moves it), its `extends` does not resolve (not found, a cycle, a chain longer than four, a preset that fails the schema, an npm name), it names no `kind` while the preset has kinds, or names a kind the preset does not have                                                                                                                 |
-| `pdf/fonts`                    | error | `paper.tex` → `_build/paper.facts.json`       | a font the pages draw is Type 3 or not embedded, or no font starts with the family the venue preset names for body text (`fonts_text`) or headings (`fonts_title`)                                                                                                                                                                                                                                                                                              |
-| `pdf/geometry`                 | error | `paper.tex` → `_build/paper.facts.json`       | the page width or height is more than `dimTol` (default 0.05 in) off the preset's, or the column count differs                                                                                                                                                                                                                                                                                                                                                  |
-| `pdf/limits`                   | error | `paper.tex` → `_build/paper.facts.json`       | body or reference pages exceed the limit of the paper's kind, or the reference font size is outside the preset's range widened by `body_pt_tol`                                                                                                                                                                                                                                                                                                                 |
-| `pdf/body-size`                | warn  | `paper.tex` → `_build/paper.facts.json`       | the body font size is more than `body_pt_tol` off the preset's. A warning: banal measures the mode of the rendered text, not the declared size (9.30 pt measured at a declared 9)                                                                                                                                                                                                                                                                               |
-| `pdf/measured`                 | warn  | `paper.tex` → `_build/paper.facts.json`       | the paper's `paperlint.json` names no venue preset yet; or it names one and there are no facts (it was not built), or the facts carry no page geometry (banal was not found) — so the checks above did not run                                                                                                                                                                                                                                                  |
+| Rule                           | Level | Reads                                         | Fails when                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------ | ----- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `paper/stages`                 | error | `PIPELINE-STATUS.md`                          | a declared stage's PDF is missing, or the `bytes:` it names does not match the file's real size, or a frozen PDF exists that no stage declares                                                                                                                                                                                                                                                                                                                |
+| `paper/source`                 | error | `PIPELINE-STATUS.md`                          | a declared stage has no frozen `.tex` beside its PDF (a commit hash does not count — squash and gc destroy it)                                                                                                                                                                                                                                                                                                                                                |
+| `paper/author-list`            | error | `paper.tex` → `_build/references.json`        | an entry's authors are not those of the version it cites — typically the arXiv preprint's list under a published venue. Checked online by `paperlint build` (DBLP), reported on the entry's own line                                                                                                                                                                                                                                                          |
+| `paper/research-question`      | warn  | `paper.tex`, `paper.md`, `PIPELINE-STATUS.md` | a stage is declared and either the scorecard has no `researchQuestion` field, or it has one the paper does not contain. The declared sentence is compared against the source with whitespace collapsed — your words, not a pattern. Advisory, because nothing here can judge whether what you declared _is_ a research question                                                                                                                               |
+| `paper/section-word`           | warn  | `paper.tex`, `paper.md`                       | `§` or `\S\ref` instead of the word Section. **Fixable:** `--fix` writes `Section~\ref{…}` / `Section 5`                                                                                                                                                                                                                                                                                                                                                      |
+| `paper/leading-zero`           | warn  | `paper.tex`, `paper.md`                       | a decimal below 1 without its leading zero (`.05` instead of `0.05`, IEEE / ISO 80000-1 style), counted only where the reader sees it — prose, math and table cells, not macro options, column specs, comments, code or tikz. A number right after `¶` or `§` (`¶¶.42`) is a paragraph designator and is not reported; in a paragraph that cites numbers that way, another bare decimal is reported without a fix, with the zero as a suggestion. **Fixable** |
+| `paper/figure-ref-style`       | warn  | `paper.tex`                                   | `Fig.~\ref` and `Figure~\ref` mixed in one document; each minority occurrence is reported. **Fixable:** `--fix` writes the majority form                                                                                                                                                                                                                                                                                                                      |
+| `bib/reachable-entry`          | warn  | `paper.tex` (its `filecontents` bibliography) | an entry has no doi, url or arXiv id — a reader has nothing to follow. Reported on the entry; no fix, the link has to be looked up                                                                                                                                                                                                                                                                                                                            |
+| `paper/cite-exists`            | error | `paper.tex` → `_build/references.json`        | an entry's doi or arXiv id resolves to nothing, or to a different work. Checked online by `paperlint build`; a work that was merely not found is not a finding                                                                                                                                                                                                                                                                                                |
+| `paper/refs-fresh`             | error | `paper.tex` → `_build/references.json`        | the bibliography changed since the build checked it (its SHA-256 differs) — run `npx paperlint build`                                                                                                                                                                                                                                                                                                                                                         |
+| `paper/refs-checked`           | warn  | `paper.tex` → `_build/references.json`        | the paper has a bibliography and no build has checked it, or the last build could not (no network) — so the two rules above did not run                                                                                                                                                                                                                                                                                                                       |
+| `tex/future-promise`           | warn  | `paper.tex`                                   | a camera-ready build still says "will be released" about something already handed over                                                                                                                                                                                                                                                                                                                                                                        |
+| `tex/acm-frontmatter-override` | error | `paper.tex`                                   | an `acmart` build overrides ACM's front-matter commands and drops template elements from page 1                                                                                                                                                                                                                                                                                                                                                               |
+| `review/frontmatter`           | error | `reviews/*.md`                                | the review's frontmatter fails paperlint's JSON Schema — a `findings` record without `id`/`status`, an unknown field, or an **open** finding with no `cause` (`skill-defect` · `missing-skill` · `hook` · `rule`). A review with no `findings` key is not checked for findings                                                                                                                                                                                |
+| `sibling/frontmatter`          | warn  | `siblings/*.md` (not `README.md`)             | a sibling card's frontmatter has no `read:` saying how much of the competing paper was read (`full` · `abstract` · `none`)                                                                                                                                                                                                                                                                                                                                    |
+| `pdf/fresh`                    | error | `paper.tex` → `_build/paper.facts.json`       | the paper names a venue and the facts cannot be judged: not JSON, a schema other than 2, or they describe a PDF that is gone or differs from the one on disk (its SHA-256)                                                                                                                                                                                                                                                                                    |
+| `pdf/profile`                  | error | `paper.tex` → `paperlint.json`                | `paperlint.json` is not JSON or has an unknown key, its `extends` does not resolve (not found, a cycle, a chain longer than four, a preset that fails the schema, an npm name), it names no `kind` while the preset has kinds, or names a kind the preset does not have                                                                                                                                                                                       |
+| `pdf/fonts`                    | error | `paper.tex` → `_build/paper.facts.json`       | a font the pages draw is Type 3 or not embedded, or no font starts with the family the venue preset names for body text (`fonts_text`) or headings (`fonts_title`)                                                                                                                                                                                                                                                                                            |
+| `pdf/geometry`                 | error | `paper.tex` → `_build/paper.facts.json`       | the page width or height is more than `dimTol` (default 0.05 in) off the preset's, or the column count differs                                                                                                                                                                                                                                                                                                                                                |
+| `pdf/limits`                   | error | `paper.tex` → `_build/paper.facts.json`       | body or reference pages exceed the limit of the paper's kind, or the reference font size is outside the preset's range widened by `body_pt_tol`                                                                                                                                                                                                                                                                                                               |
+| `pdf/body-size`                | warn  | `paper.tex` → `_build/paper.facts.json`       | the body font size is more than `body_pt_tol` off the preset's. A warning: banal measures the mode of the rendered text, not the declared size (9.30 pt measured at a declared 9)                                                                                                                                                                                                                                                                             |
+| `pdf/measured`                 | warn  | `paper.tex` → `_build/paper.facts.json`       | the paper's `paperlint.json` names no venue preset yet; or it names one and there are no facts (it was not built), or the facts carry no page geometry (banal was not found) — so the checks above did not run                                                                                                                                                                                                                                                |
 
 Optional rules — off unless you turn them on in the `rules` setting, because only some venues need
 them — are on their own page: [`optional-rules.md`](optional-rules.md). Today there is one,
 `pdf/last-page-balance`.
 
+## A deliberate exception: a disable directive, with the reason
+
+When a finding is right in general and wrong for one line — a quoted `.05`, a bibliography entry
+for an invited talk that has no link — keep the exception where it is, with ESLint's own directive
+in a `%` comment (`<!-- … -->` in markdown). The part after `--` is the reason, and it stays in the
+file for the next reader:
+
+```latex
+% eslint-disable-next-line paper/leading-zero -- quoted verbatim from the reviewer
+They wrote ".05" in their report.
+Also here: .06 % eslint-disable-line paper/leading-zero -- quoted too
+
+% eslint-disable paper/section-word -- a table reproduced from the venue's own template
+…
+% eslint-enable paper/section-word
+```
+
+This works inside the `filecontents` bibliography of `paper.tex` too, above the entry:
+
+```latex
+% eslint-disable-next-line bib/reachable-entry -- an invited talk, no recording exists
+@misc{smith2024talk, …}
+```
+
+A directive that no longer silences anything is itself reported, so a stale exception does not
+linger. There is no per-paper allowance or counter: the typography rules fix themselves with
+`paperlint lint --fix`, and what is left is either fixed or excepted by name, on its line.
+
 Besides these rules, `paperlint lint` reports a paper directory that is missing a required file (by
 default `PIPELINE-STATUS.md`) as an error. Which files are required is configurable — see
 [`configuration.md`](configuration.md#required-files).
@@ -33,7 +67,7 @@ default `PIPELINE-STATUS.md`) as an error. Which files are required is configura
 ## Checks against the venue
 
 A paper says where it is submitted in a `paperlint.json` beside `paper.tex`
-([`configuration.md`](configuration.md#three-levels-of-settings)):
+([`configuration.md`](configuration.md#a-papers-paperlintjson)):
 
 ```json
 { "extends": "paperlint:aisec", "kind": "research" }
@@ -69,12 +103,13 @@ and the split into body and reference pages. They report on the paper's `paper.t
 | the paper                                                                                        | what you get                                                                                                                 |
 | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
 | has a `paperlint.json` that extends no preset (`"extends": null` is what `paperlint new` writes) | `pdf/measured` warning naming the file to set — no venue chosen yet                                                          |
-| has no `paperlint.json` at all (a paper made before 2.1.0)                                       | nothing                                                                                                                      |
+| has no `paperlint.json` at all                                                                   | nothing                                                                                                                      |
 | extends a preset that does not resolve (a typo, a missing file)                                  | `pdf/profile` error, listing the shipped presets                                                                             |
 | has not been built (no facts file)                                                               | `pdf/measured` warning — it does not fail the run, because lint often runs where nothing is built (the CI action only lints) |
 | was built without banal                                                                          | `pdf/measured` warning; fonts are still checked, the rest is not                                                             |
 | has facts about another PDF than the one on disk                                                 | `pdf/fresh` error, and nothing else is judged                                                                                |
-| names no `kind`, or a kind the preset lacks                                                      | `pdf/profile` error; everything but the page limit is still checked                                                          |
+| names no `kind` while its preset has kinds, or a kind the preset lacks                           | `pdf/profile` error; everything but the page limit is still checked                                                          |
+| names no `kind` and its preset has none (`paperlint:acm-sigconf`)                                | nothing — that preset has no page limit to check; everything else is                                                         |
 
 The venue comes from `paperlint.json`, not from the facts, so changing it needs no rebuild: the
 measurements do not depend on it. Messages name the venue by the preset's `name`, else by the file
@@ -100,6 +135,7 @@ Put it in your repository and extend it by a path relative to the file that name
 
 ```
 package.json
+paperlint.json            (optional)
 venues/
   usenix-sec.jsonc
 papers/
@@ -164,7 +200,11 @@ rules, which is why they list it above. Markdown papers are deprecated and being
 
 ## The scorecard's `bytes:` and `sourceBytes:`
 
-A stage in `PIPELINE-STATUS.md` looks like this:
+**When you submit,** copy the PDF and `paper.tex` you sent into the paper's `versions/` folder and
+record the stage in the front matter of `PIPELINE-STATUS.md` (the paper's scorecard). From then on
+`paper/stages` fails if that PDF goes missing or changes size, and `paper/source` if its source was
+not kept. Today you record it by hand; a command for it is planned
+([#100](https://github.com/zernie/paperlint/issues/100)). A stage looks like this:
 
 ```yaml
 ---
@@ -180,8 +220,9 @@ researchQuestion: "Does pruning the state space reduce review cost?"
 ---
 ```
 
-Today you write `bytes:` and `sourceBytes:` yourself, or the agent does, once, when the stage is
-recorded; no command in this package generates them. They are not a checksum to maintain: a
+A stage name may use `a-z`, `0-9`, `.`, `_` and `-`. You write `bytes:` and `sourceBytes:` yourself
+(`wc -c < versions/2026-07-22-submitted.pdf`), or the agent does, once, when the stage is recorded;
+no command in this package generates them. They are not a checksum to maintain: a
 frozen PDF is never supposed to change, so `bytes:` disagreeing with the file means the file was
 replaced after it was declared, and that is exactly the finding. If you really did re-freeze a
 stage, update the number in the same commit.

package/docs/skills.md

@@ -0,0 +1,80 @@
+# Skills
+
+Every skill paperlint ships, by the stages of [the pipeline](../README.md#-the-pipeline). Each line
+says what you get; the skill's name is the second column.
+
+You do not call them by name: you ask Claude Code for the thing ("is this idea worth a paper?"), and
+the skill whose description matches starts. `paperlint init` installs them into
+`.claude/skills/` ([`install.md`](install.md)). Each one's full instructions are its
+`skills/<name>/SKILL.md`.
+
+`test/skills-catalog.test.ts` fails when this list and the shipped `skills/` directory disagree.
+
+## Across every stage
+
+| you get                                                                                   | skill            |
+| ----------------------------------------------------------------------------------------- | ---------------- |
+| a guided path through the stages: what to do now, and which skill does it                 | `paper-pipeline` |
+| where the paper stands, measured: pages from the real build, what is checked, what blocks | `paper-status`   |
+
+## 1 · Idea
+
+| you get                                                                                 | skill                   |
+| --------------------------------------------------------------------------------------- | ----------------------- |
+| a go / no-go on the idea, with the reason and the smallest result that makes a paper    | `research-ideate`       |
+| who already works on it, dated against your deadline, and what you can still claim      | `map-prior-work`        |
+| one close competitor read in full: is yours "just X?", and the sentence that answers it | `analyze-sibling-paper` |
+| candidate mechanisms from other fields, when the work needs a design, not a measurement | `sweep-design-space`    |
+
+## 2 · Venue
+
+| you get                                                                        | skill                   |
+| ------------------------------------------------------------------------------ | ----------------------- |
+| a ranked list of venues that fit: deadline, page limit, indexing, remote talks | `find-venue`            |
+| what papers accepted at that venue do well, and what would make yours stronger | `study-accepted-papers` |
+| the deadlines worked backwards, as events in your calendar                     | `plan-paper-timeline`   |
+
+## 3 · Study
+
+| you get                                                                                    | skill             |
+| ------------------------------------------------------------------------------------------ | ----------------- |
+| a study design with honest statistics, and a reproduction artifact that checks its numbers | `build-benchmark` |
+
+## 4 · Draft
+
+| you get                                                                            | skill            |
+| ---------------------------------------------------------------------------------- | ---------------- |
+| a first draft from your results: claims sized, threats to validity written         | `draft-paper`    |
+| an outline where each section follows from the one before                          | `argument-arc`   |
+| a cut plan: what to cut, merge or move to the appendix                             | `tighten-paper`  |
+| what a reader with no context understood from your last edit, sentence by sentence | `cold-read-diff` |
+| the compiled pages as images, to read on a screen or a phone                       | `render-paper`   |
+
+## 5 · Review
+
+| you get                                                                       | skill                      |
+| ----------------------------------------------------------------------------- | -------------------------- |
+| a writing grade, with the sentence to fix for each point                      | `grade-paper-writing`      |
+| every cited work confirmed to exist, with the right authors, title and year   | `verify-citations`         |
+| one hostile review: overclaims, missing baselines, holes in the method        | `paper-adversarial-review` |
+| a simulated program committee: several reviews, a decision and the must-fixes | `pc-panel-review`          |
+| ready or not ready to submit, worst problem first                             | `harden-paper`             |
+
+## 6 · Submit
+
+| you get                                                             | skill                 |
+| ------------------------------------------------------------------- | --------------------- |
+| the submission, step by step: anonymization, the form, the artifact | `submit-paper`        |
+| the reproduction artifact uploaded to OSF for anonymous review      | `osf-artifact-upload` |
+
+## 7 · Camera-ready
+
+| you get                                                                                    | skill          |
+| ------------------------------------------------------------------------------------------ | -------------- |
+| the final version: authors back, the artifact public with a DOI, any disclosure done first | `camera-ready` |
+
+## 8 · Extend
+
+| you get                                                       | skill          |
+| ------------------------------------------------------------- | -------------- |
+| a plan for the next, stronger paper built on the accepted one | `extend-paper` |

package/eslint-rules/bib-reachable-entry.mjs

@@ -0,0 +1,75 @@
+/**
+ * `bib/reachable-entry` — a bibliography entry a reader cannot follow: no doi, no url, no arXiv
+ * id. Reported ON THE ENTRY, one finding per entry; there is no fix, because the link has to be
+ * looked up. Default severity: warn.
+ *
+ * Provenance: Reviewer A on HotCRP #20 (2026-08-23), "not every entry has a DOI/link" — one
+ * paper had 0 of 47 entries reachable. Until 3.0.0 this was one count inside `paper/typography`,
+ * silenced per paper by a declared debt; now each entry is its own finding, and an entry that
+ * genuinely has no link (a talk, a personal communication) carries a disable directive with its
+ * reason, in the bibliography itself:
+ *
+ *   % eslint-disable-next-line bib/reachable-entry -- an invited talk, no recording exists
+ *   @misc{smith2024talk, …}
+ *
+ * ⚠️ NOT "no doi". Measured 2026-08-24: ICLR/NeurIPS/TMLR issue no DOIs at all, so a doi-only
+ * rule would demand something that does not exist and get muted for lying. A url or an arXiv id
+ * counts.
+ *
+ * The bibliography read is the one INSIDE `paper.tex` (`filecontents`), where the papers this
+ * package targets keep it. The entry boundaries and fields are found by a line-anchored `@` and
+ * a field name followed by `=` — BibTeX's own lexical shape, one lexeme at a time, not a parse:
+ * the parser (`@retorquere/bibtex-parser`) is an OPTIONAL peer of this package.
+ */
+import { bibRange } from "./paper-typography.mjs";
+
+/** Entry types that are not references. */
+const NOT_AN_ENTRY = /^@(comment|string|preamble)\b/i;
+const HAS_LINK = /\b(doi|url)\s*=/i;
+const HAS_ARXIV = /arxiv[:\s]*\d{4}\.\d{4,5}/i;
+
+export default {
+  rules: {
+    "reachable-entry": {
+      meta: {
+        type: "suggestion",
+        docs: {
+          description:
+            "a bibliography entry carries a doi, a url or an arXiv id — something a reader can follow",
+        },
+        schema: [],
+        messages: {
+          unreachable:
+            "`{{key}}` has no doi, url or arXiv id — a reader has nothing to follow. If none exists, keep the exception with `% eslint-disable-next-line bib/reachable-entry -- <why>` above the entry",
+        },
+      },
+      create(context) {
+        return {
+          "root:exit"() {
+            const sc = context.sourceCode;
+            const raw = sc.raw ?? sc.text;
+            const bib = typeof raw === "string" ? bibRange(raw) : null;
+            if (!bib) return;
+            const starts = [...bib.body.matchAll(/^@/gm)].map((m) => m.index);
+            starts.forEach((s, i) => {
+              const entry = bib.body.slice(s, starts[i + 1] ?? bib.body.length);
+              if (NOT_AN_ENTRY.test(entry)) return;
+              if (HAS_LINK.test(entry) || HAS_ARXIV.test(entry)) return;
+              const head = entry.split("\n")[0];
+              const key = /\{\s*([^,\s]+)/.exec(head)?.[1] ?? "?";
+              const from = bib.bodyStart + s;
+              context.report({
+                loc: {
+                  start: sc.getLocFromIndex(from),
+                  end: sc.getLocFromIndex(from + head.length),
+                },
+                messageId: "unreachable",
+                data: { key },
+              });
+            });
+          },
+        };
+      },
+    },
+  },
+};

package/eslint-rules/latex-language.mjs

@@ -64,7 +64,9 @@
  *     is not substituted). Anonymisation is normally done with exactly those, so coinage and
  *     jargon rules see less on an anonymised version than on a camera-ready.
  *  8. `% eslint {"rules":…}` inside `.tex` does NOT work: `applyInlineConfig` returns empty.
- *     `% eslint-disable-next-line <rule> -- reason` DOES work.
+ *     The disable directives DO work — `% eslint-disable-next-line <rule> -- reason`,
+ *     `% eslint-disable-line`, `% eslint-disable` / `% eslint-enable` — and since 3.0.0 also
+ *     inside a `filecontents` bibliography, whose `%` lines are made comment nodes below.
  *  9. `\section*{…}` is untested and does not occur in the corpus (measured: 0 occurrences).
  *     When it appears, `plain()` will glue all arguments together and the heading may come out
  *     as `*X`.
@@ -207,6 +209,32 @@ export function texToMdast(src) {
     });
   }
 
+  // 🔴 A `filecontents` body is not LaTeX — it is the `.bib` the paper writes, usually in the
+  // preamble — so the parser returns it as one verbatim node and no comment nodes from it. A
+  // disable directive above a bibliography entry (`% eslint-disable-next-line bib/reachable-entry
+  // -- …`) was therefore invisible. Its `%` lines are made comments here, the only way
+  // `getInlineConfigNodes` sees them. BibTeX ignores text between entries, so the line is
+  // harmless to the build.
+  for (const n of ast.content)
+    if (
+      n.type === "verbatim" &&
+      /^filecontents\*?$/.test(String(n.env)) &&
+      P(n)
+    ) {
+      let at = P(n).start.offset;
+      for (const line of src.slice(at, P(n).end.offset).split("\n")) {
+        const text = line.replace(/\r$/, "");
+        const pct = /^\s*%/.test(text) ? text.indexOf("%") : -1;
+        if (pct >= 0)
+          children.push({
+            type: "html",
+            value: text.slice(pct + 1),
+            position: { start: loc(at + pct), end: loc(at + text.length) },
+          });
+        at += line.length + 1;
+      }
+    }
+
   (function walk(node) {
     if (Array.isArray(node)) return node.forEach((n) => walk(n));
     if (!node || typeof node !== "object") return;