paperlint 2.0.0 → 2.1.0

package/docs/configuration.md

@@ -18,8 +18,8 @@ The README carries the minimal version of this. Everything below is the full sur
     "causeMarker": "Cause:",
     "rules": [
       {
-        "files": ["papers/agenticdev-2026/**"],
-        "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] }
+        "files": ["papers/old-draft/**"],
+        "rules": { "paper/typography": "off" }
       }
     ]
   }
@@ -57,6 +57,61 @@ Until 2026-09-24 this field was called `papers`. The old name is not read as a f
 hooks stay silent instead. The name is defined once, as `PAPERS_DIR_FIELD` in
 `lib/paper-config.mjs`.
 
+## Three levels of settings
+
+Each level is named after the tool, and each says something the others cannot:
+
+```
+package.json                 "paperlint": { … }        the PROJECT: where the papers are, what every paper gets
+papers/
+  my-paper/
+    paper.tex
+    PIPELINE-STATUS.md
+    paperlint.json           { "extends": … }          THIS PAPER: its venue preset, its kind, its own rules — `paperlint new` writes it
+venues/usenix-sec.jsonc      (optional, your own)      a VENUE PRESET: format, page limits, TeX packages, rules
+node_modules/paperlint/skills/submit-paper/references/venues/
+    acm-sigconf.jsonc  agenticdev.jsonc  aisec.jsonc  realm.jsonc      the shipped presets (paperlint:<name>)
+```
+
+`paperlint new` writes `<paper>/paperlint.json` from the template (`templates/paper/paperlint.json`,
+or your `<papers>/.template/paperlint.json` if you keep one), with `"extends": null` — no venue chosen
+yet — and a `$comment` saying what goes there. Until `extends` names a preset, `paperlint lint` gives
+that paper one warning, `pdf/measured`: "this paper names no venue preset yet … set "extends" in
+papers/my-paper/paperlint.json". A paper folder with no `paperlint.json` at all — one created before
+2.1.0 — gets no venue checks and no warning; `npx paperlint new <its name>` adds the file and
+changes nothing else.
+
+```json
+{
+  "extends": "paperlint:aisec",
+  "kind": "research",
+  "rules": { "pdf/body-size": "off" }
+}
+```
+
+| key        | what it is                                                                                                                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `extends`  | the venue preset the built PDF is judged against: `paperlint:<name>` (shipped) or `./path` / `../path` (your own, relative to this file) — [`rules.md`](rules.md#checks-against-the-venue) |
+| `kind`     | the kind of paper (`short`, `research`, …) whose page limit applies                                                                                                                        |
+| `pdf`      | where the built PDF is, relative to the paper, when it is not `paper.pdf`                                                                                                                  |
+| `rules`    | rule id → severity, for this paper alone — the same entries as a `rules` block below                                                                                                       |
+| `$comment` | a note for humans (JSON Schema's comment keyword); ignored                                                                                                                                 |
+
+Any other key is an error naming the file and the key, as in `package.json`.
+
+**Where a paper's rules come from, in order — a later one wins, rule by rule:** paperlint's own
+configuration → the preset chain's `rules`, from the root preset to the one the paper extends →
+the paper's own `rules` → the project's `rules` blocks in `package.json`. So a venue can turn a
+rule on for its papers, a paper can turn it off for itself, and the project can still override
+both. Only rules paperlint ships may be named, at every level.
+
+**`paperlint.json` replaces `venue.json` (2.1.0); `npx paperlint init` moves it.** The old name is not
+read: a paper with only a `venue.json` gets a `pdf/profile` error and `paperlint doctor` names the
+file, both pointing at `init`. `init` writes the same settings as `paperlint.json` —
+`"venue": "aisec"` becomes `"extends": "paperlint:aisec"`, and the `"_"` some files used as a
+comment becomes `"$comment"` — then deletes `venue.json`. It removes a `venue.json` whose
+`paperlint.json` already says the same, and refuses, changing nothing, when both exist and differ.
+
 ## Why the key lives in `package.json`
 
 Because of a count: the `package.json` key has **five** readers — the three editor hooks, the
@@ -65,12 +120,8 @@ import code and cannot walk up a tree looking for a config; it can read a path i
 and the one path it can always name is the project's `package.json`.
 
 `paperlint lint` looks for it in the current directory and then upwards, the way eslint and tsc find
-theirs, and prints which file it found. `--config <file>` overrides the search.
-
-⚠️ **`rpp.json` is deprecated and still read.** Earlier versions of `init` created it; `init` no
-longer does, and a run that reads one says so on its first line. The hooks never read it, so
-leaving settings there is how the linter and the guard end up watching different directories —
-`paperlint init` copies the value across for you.
+theirs, and prints which file it found. `--config <file>` overrides the search; the file has the
+same shape, with the settings under the `paperlint` key.
 
 ## The `rules` key: turning rules on and off
 
@@ -80,11 +131,15 @@ the three keys that make sense in JSON — `files`, `ignores` and `rules`. paper
 **after** its own configuration, so, as in ESLint, a later block wins: a block can turn on a rule
 that is off by default, or change the severity of one that is on.
 
+For ONE paper, the paper's own `paperlint.json` is simpler — no glob to get wrong
+([above](#three-levels-of-settings)). Use a block here for a rule across several papers, or to
+override what a paper says:
+
 ```json
 "rules": [
   {
-    "files": ["papers/agenticdev-2026/**"],
-    "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] }
+    "files": ["papers/**"],
+    "rules": { "pdf/body-size": "off" }
   },
   {
     "files": ["papers/old-draft/**"],
@@ -120,7 +175,7 @@ and the real findings leave with it.
 
 ```json
 "structure": {
-  "markers":      ["PIPELINE-STATUS.md", "paper.tex", "paper.md", "venue.json"],
+  "markers":      ["PIPELINE-STATUS.md", "paper.tex", "paper.md", "paperlint.json"],
   "require":      ["PIPELINE-STATUS.md"],
   "requireOneOf": [["paper.tex", "paper.md"]],
   "ignore":       []
@@ -129,7 +184,7 @@ and the real findings leave with it.
 
 Those are the defaults; you only write the block to change them. `paper.md` is still in them
 because Markdown papers are deprecated but not yet removed
-([#57](https://github.com/zernie/research-paper-pipeline/issues/57)). They were measured against a
+([#57](https://github.com/zernie/paperlint/issues/57)). They were measured against a
 real five-paper corpus rather than chosen — it passes with zero findings, while adding
 `paper.pdf` to `require` produces two findings on papers that are perfectly fine, which is why it
 is not there.
@@ -177,11 +232,12 @@ papers/my-paper
 
 The build does **not** judge the layout. A balanced last page, a page limit, the fonts a venue
 wants — those are verdicts about the finished PDF, and they belong to lint rules that can be
-turned on per venue, given a severity and suppressed with a reason. paperlint once searched for a
+turned on per venue, given a severity and suppressed with a reason: the `pdf/` venue rules
+([`rules.md`](rules.md#checks-against-the-venue)) and the optional `pdf/last-page-balance`. paperlint once searched for a
 `\balance` position itself and failed the build when none worked; that was removed on
 2026-09-24.
 
-The class and its options and the venue in `venue.json` are read from the paper and shown in the
+The class and its options and the venue in `paperlint.json` are read from the paper and shown in the
 plan; later steps decide from them whether they apply.
 
 **`paper.pdf` is deleted before anything runs**, for every targeted paper — before the TeX Live is
@@ -216,18 +272,18 @@ having run on it, because a missing build read as nothing to do.
 ⚠️ **A `build.sh` or `repro/build-submission.sh` in the paper directory is IGNORED.** Earlier
 versions ran it; `paperlint build` now says one line — `build.sh is ignored — paperlint builds the paper
 itself` — and builds the paper itself. The `buildScripts` key is ignored the same way.
-Why: [#59](https://github.com/zernie/research-paper-pipeline/issues/59).
+Why: [#59](https://github.com/zernie/paperlint/issues/59).
 
 ## Using the rules from an existing ESLint config
 
 Under the hood `paperlint lint` builds an ESLint flat config and runs it. If your repository already
 lints with ESLint, you can import the rule modules from `paperlint/eslint-rules/`
-and wire them yourself; `bin/rpp.mjs` exports `buildConfig(options, texLanguage)` that returns
+and wire them yourself; `bin/paperlint.mjs` exports `buildConfig(options, texLanguage)` that returns
 the exact config the CLI uses, so the shortest path is:
 
 ```js
 // eslint.config.mjs
-import { buildConfig } from "paperlint/bin/rpp.mjs";
+import { buildConfig } from "paperlint/bin/paperlint.mjs";
 import { texLanguage } from "paperlint/eslint-rules/latex-language.mjs";
 export default buildConfig({ minFindings: 3 }, texLanguage);
 ```

package/docs/e2e.md

@@ -35,8 +35,7 @@ temporary tree, **under npm and under pnpm separately**, and drives the installe
 
 - the install itself finishes
 - `paperlint --help` answers with zero
-- `paperlint init` declares the papers directory in `package.json`, and does _not_ leave a second
-  carrier `rpp.json` behind
+- `paperlint init` declares the papers directory in `package.json`
 - `paperlint init` finishes with zero — its doctor found no discrepancy
 - `paperlint init` wires the hooks into `.claude/settings.json` — the same commands `hooks.json`
   publishes, once each — and says they need `npm install` in a fresh clone; a second `init`
@@ -88,10 +87,10 @@ paperlint's own cache, because the runner has no other.
 
 ## `test/e2e/toolchain.mjs` — real TeX Live, and only it
 
-`paperlint toolchain` into `$RPP_TEXLIVE_DIR` against real CTAN; a second run must say "nothing to do"
+`paperlint toolchain` into `$PAPERLINT_TEXLIVE_DIR` against real CTAN; a second run must say "nothing to do"
 within seconds; `--check` must exit 0; then the `acmart` fixture is built with PATH holding `node`
 only, so no other TeX Live and no PDF tool can stand in, and the PDF must carry Libertine and Biolinum
-and no Computer Modern face. Without `RPP_TEXLIVE_DIR` it is a declared skip: installing ~270 MB
+and no Computer Modern face. Without `PAPERLINT_TEXLIVE_DIR` it is a declared skip: installing ~270 MB
 into a home directory as a side effect of `npm run check` is the unasked install rule 11 forbids.
 `src/toolchain.harness.mjs` covers the installer's logic (mirror fallback, archive check, time
 limit, verification, idempotence) against a fake mirror on disk, without the network.

package/docs/install.md

@@ -20,6 +20,15 @@ your project's `node_modules`, so it needs the install first.
 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:
 
@@ -68,8 +77,7 @@ gets the hooks; the hook commands run files inside `node_modules`, so a fresh cl
 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
-`rpp.json` was read only by the CLI. `rpp.json` is still read as a deprecated fallback, and
-`paperlint lint` says so.
+config file would be read only by the CLI, so there is none.
 
 **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
@@ -135,7 +143,7 @@ on the tree the manager laid out. It also checks that every shipped skill is rea
 directory under a skill's name survives.
 
 Yarn Plug'n'Play has no `node_modules`, and the hook commands in `plugin/hooks/hooks.json` name
-`${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/rpp.mjs`. Supporting it would need
+`${CLAUDE_PROJECT_DIR}/node_modules/paperlint/bin/paperlint.mjs`. Supporting it would need
 a different answer to "where is the runtime", not a flag.
 
 ## Install size

package/docs/optional-rules.md

@@ -1,8 +1,11 @@
 # Optional rules
 
-Some checks matter only for some venues. paperlint ships them **off**, and you turn them on for the
-papers that need them, in the `rules` setting of your `package.json`
-([`configuration.md`](configuration.md#the-rules-key-turning-rules-on-and-off)).
+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)).
 
 | rule                    | what it checks                                                | who needs it                                              |
 | ----------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
@@ -12,21 +15,18 @@ papers that need them, in the `rules` setting of your `package.json`
 
 ### Turning it on
 
+A paper that extends `paperlint:agenticdev` has it already, at 120 pt. For any other paper, in its
+`papers/my-paper/paperlint.json`:
+
 ```json
 {
-  "paperlint": {
-    "papersDir": "papers",
-    "rules": [
-      {
-        "files": ["papers/agenticdev-2026/**"],
-        "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] }
-      }
-    ]
-  }
+  "extends": "paperlint:aisec",
+  "kind": "research",
+  "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] }
 }
 ```
 
-`files` is relative to the `package.json`. `tolerancePt` is how far apart, in points, the two
+It applies to that paper alone; `"off"` there turns it off for a paper whose preset turns it on. `tolerancePt` is how far apart, in points, the two
 columns may end; it defaults to 120. On a real accepted paper the balanced build ended 2.7 pt apart
 and the one the publisher sent back 321.4 pt apart — nothing in between — so the default leaves a
 wide margin on both sides.
@@ -34,21 +34,22 @@ wide margin on both sides.
 ### What it reads
 
 The rule does not open the PDF to measure it. `paperlint build` measures every PDF it builds and writes
-the result to `<paper>/_build/paper.facts.json` ([`configuration.md`](configuration.md#how-rpp-build-compiles-a-paper)),
+the result to `<paper>/_build/paper.facts.json` ([`configuration.md`](configuration.md#how-paperlint-build-compiles-a-paper)),
 and the rule judges that file, reporting on the paper's `paper.tex` at the `\documentclass` line.
 So: **build, then lint.**
 
-| the rule finds                                      | it says                                                                                                                       |
-| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| columns further apart than `tolerancePt`            | **the finding**, with both heights and how to fix it (below)                                                                  |
-| no `_build/paper.facts.json`                        | build the paper first                                                                                                         |
-| facts about a different PDF than the one on disk    | the facts are stale (their SHA-256 differs) — rebuild                                                                         |
-| facts whose PDF is gone (a failed build removes it) | rebuild                                                                                                                       |
-| a last page of a few lines                          | nothing — there is no layout to balance                                                                                       |
-| 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 with a `files` glob that reaches no `paper.tex`, `paperlint lint` fails and says
-so, rather than reporting a clean run for a rule that never ran.
+| the rule finds                                      | it says                                                                                                                           |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| columns further apart than `tolerancePt`            | **the finding**, with both heights and how to fix it (below)                                                                      |
+| no `_build/paper.facts.json`                        | build the paper first — unless the paper extends a venue preset: then `pdf/measured` already warns, once, and this rule is silent |
+| facts about a different PDF than the one on disk    | the facts are stale (their SHA-256 differs) — rebuild                                                                             |
+| facts whose PDF is gone (a failed build removes it) | rebuild                                                                                                                           |
+| a last page of a few lines                          | nothing — there is no layout to balance                                                                                           |
+| 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
+run for a rule that never ran.
 
 ### Which venues need it
 

package/docs/rules.md

@@ -14,6 +14,13 @@ reads and when it fails. Errors fail `paperlint lint`; warnings print and do not
 | `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                                                                                                                                                                                                                                                  |
 
 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,
@@ -23,15 +30,137 @@ Besides these rules, `paperlint lint` reports a paper directory that is missing
 default `PIPELINE-STATUS.md`) as an error. Which files are required is configurable — see
 [`configuration.md`](configuration.md#required-files).
 
+## 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)):
+
+```json
+{ "extends": "paperlint:aisec", "kind": "research" }
+```
+
+`extends` names a **venue preset** — the way an ESLint config extends a shareable config. `kind`
+names the kind of paper, whose page limit applies. A preset holds the numbers from the venue's call
+for papers, each with the quote it came from, the TeX packages its template needs, and the rules
+the venue implies. A preset may itself extend another: the ACM venues extend the `acm-sigconf`
+family, which holds everything the ACM template decides.
+
+| preset                  | extends                 | template             | kinds                                                    | page limit checked | rules it turns on       |
+| ----------------------- | ----------------------- | -------------------- | -------------------------------------------------------- | ------------------ | ----------------------- |
+| `paperlint:acm-sigconf` | —                       | ACM `acmart` sigconf | none                                                     | no (no kinds)      | —                       |
+| `paperlint:agenticdev`  | `paperlint:acm-sigconf` | ACM `acmart` sigconf | `short` (5 + 2 refs), `full` (10 + 2), `demo` (5 + 2)    | yes                | `pdf/last-page-balance` |
+| `paperlint:aisec`       | `paperlint:acm-sigconf` | ACM `acmart` sigconf | `research`, `benchmark`, `position`, `sok` (10 + 2 each) | yes                | —                       |
+| `paperlint:realm`       | —                       | ACL                  | `long`, `short`                                          | no — see below     | —                       |
+
+That is all that ships today. There is no IEEE, NeurIPS, USENIX or Springer preset. A paper for an
+ACM venue nobody has profiled can extend `paperlint:acm-sigconf` directly: page size, columns and
+fonts are checked, and `pdf/profile` says the page limit is not. For anything else, write your own
+preset ([below](#writing-your-own-venue-preset)). REALM's preset sets no page limit on purpose:
+banal counts the Limitations and Ethics sections as body, ACL does not, and a limit on banal's
+number would fail a correct paper. AgenticDev's turns on `pdf/last-page-balance` because its
+proceedings are produced by Conference Publishing Consulting, which sends back an unbalanced last
+page; AISec's does not, because nothing in hand says who produces the AISec proceedings.
+
+**Build, then lint.** The rules judge what `paperlint build` measured and wrote to
+`_build/paper.facts.json` — page count, fonts, and, through banal, page size, columns, font sizes
+and the split into body and reference pages. They report on the paper's `paper.tex`, at the
+`\documentclass` line. What they say when there is nothing to judge, one rule per reason:
+
+| 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                                                                                                                      |
+| 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                                                          |
+
+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
+name of what the paper extends (`paperlint:agenticdev` → `agenticdev`).
+
+To skip a check for one paper — a finding you accept — set it to `"off"` in the paper's own
+`paperlint.json`:
+
+```json
+{
+  "extends": "paperlint:aisec",
+  "kind": "research",
+  "rules": { "pdf/body-size": "off" }
+}
+```
+
+### Writing your own venue preset
+
+A preset is a JSONC file (JSON with comments — keep the call-for-papers quote beside each number)
+of the same shape as the shipped ones, validated by
+[`venue-profile.schema.json`](../skills/submit-paper/references/venues/venue-profile.schema.json).
+Put it in your repository and extend it by a path relative to the file that names it:
+
+```
+package.json
+venues/
+  usenix-sec.jsonc
+papers/
+  usenix-2027/
+    paper.tex
+    paperlint.json        { "extends": "../../venues/usenix-sec.jsonc", "kind": "full" }
+```
+
+```jsonc
+// venues/usenix-sec.jsonc
+{
+  "name": "USENIX Security",
+  // a standalone preset needs its template's TeX packages; one that extends a family inherits them
+  "template": "article",
+  // TeX Live packages only, each with a file that proves it is installed. The USENIX style file
+  // itself is not in TeX Live: keep it beside paper.tex.
+  "tex": { "packages": { "psnfss": ["times.sty"] } },
+  "format": {
+    "page_size": "letter",
+    "page_w_in": 8.5,
+    "page_h_in": 11,
+    "columns": 2,
+    "body_pt": 10,
+    "body_pt_tol": 0.5,
+    // the page limit of each kind of paper, as the call for papers states it
+    "kinds": { "full": { "body_pages_max": 13 } },
+  },
+  // only if the proceedings' producer asks for a balanced last page
+  "rules": { "pdf/last-page-balance": "error" },
+}
+```
+
+The numbers and packages above illustrate the shape; take yours from the venue's own call for papers and template.
+
+| key        | what it is                                                                                          |
+| ---------- | --------------------------------------------------------------------------------------------------- |
+| `extends`  | the preset this one builds on: `paperlint:<name>` or `./path` / `../path`, relative to this file    |
+| `name`     | how messages name the venue; the file name otherwise                                                |
+| `template` | the `\documentclass` the venue's template uses                                                      |
+| `format`   | page size, columns, fonts, font sizes, and `kinds` (page limits per kind of paper)                  |
+| `tex`      | TeX Live packages, each with the files that prove it is installed. Required unless `extends` is set |
+| `rules`    | rules the venue implies, rule id → severity or `[severity, options]`                                |
+
+How a chain merges, from the root preset to the paper: `tex` is the union — a child never removes a
+package; `format` keys are replaced one by one, and a child's kind replaces that kind whole;
+`rules` are replaced rule by rule, and the paper's own `rules` come last. A chain is at most four
+presets long, and a cycle is refused by name. `paperlint toolchain` installs the packages of every
+shipped preset and of every preset your papers extend.
+
+Presets from npm packages are not supported yet.
+
 ## The paper is LaTeX
 
-The paper body is `paper.tex`, and it gets four rules: `paper/research-question`,
-`paper/typography`, `tex/future-promise` and `tex/acm-frontmatter-override`. The scorecard and
+The paper body is `paper.tex`, and it gets four rules of its own: `paper/research-question`,
+`paper/typography`, `tex/future-promise` and `tex/acm-frontmatter-override` — plus the `pdf/`
+venue rules above, which run on it but judge the files beside it. The scorecard and
 the review notes are Markdown files, and the other five rules read those.
 
 A Markdown body (`paper.md`, or `draft.md`) is still read today and gets only the two `paper/`
 rules, which is why they list it above. Markdown papers are deprecated and being removed
-([#57](https://github.com/zernie/research-paper-pipeline/issues/57)); do not start a new one.
+([#57](https://github.com/zernie/paperlint/issues/57)); do not start a new one.
 
 ## The scorecard's `bytes:` and `sourceBytes:`
 

package/docs/toolchain.md

@@ -36,12 +36,12 @@ The command has two halves, TeX Live and banal (below). Both always run, so one
 hide the other, and the exit code is 0 only when both are ready.
 
 It downloads `install-tl` from a CTAN mirror (four in turn; each download has its own time limit,
-TLS is always verified), installs `scheme-basic` into `~/.cache/rpp/texlive/<TeX Live year>`
-(`$XDG_CACHE_HOME/rpp/texlive` when that is set, `$RPP_TEXLIVE_DIR` over both), and `tlmgr install`s
+TLS is always verified), installs `scheme-basic` into `~/.cache/paperlint/texlive/<TeX Live year>`
+(`$XDG_CACHE_HOME/paperlint/texlive` when that is set, `$PAPERLINT_TEXLIVE_DIR` over both), and `tlmgr install`s
 every package the venue profiles declare. Then it checks the RESULT: `kpsewhich` must find every
 file each profile names, and each declared tool must be an executable in the bin directory. A gap
 fails the command and names the package and its file. Linux and macOS; on Windows it refuses, and
-`paperlint build` uses a TeX Live on PATH that has the packages. `RPP_CTAN_MIRROR` names one mirror
+`paperlint build` uses a TeX Live on PATH that has the packages. `PAPERLINT_CTAN_MIRROR` names one mirror
 (a `…/systems/texlive/tlnet` URL) to use instead of the list.
 
 Measured 2026-09-24 from an empty directory: **3 min 04 s, 269 MB** (du: 298 MB), TeX Live 2026, 47
@@ -109,8 +109,8 @@ therefore does not contain banal. `paperlint toolchain` downloads it from HotCRP
 | version | banal 1.2                                                                                            |
 | sha256  | `fd8cc4ae189b9da02460ae442a34f14434e5784210489fb668313ac671006911`                                   |
 
-It refuses a file with any other sha256, stores it in `~/.cache/rpp/banal/<commit>/banal`
-(`$XDG_CACHE_HOME/rpp/banal` when set, `$RPP_BANAL_DIR` over both), and accepts it only after banal
+It refuses a file with any other sha256, stores it in `~/.cache/paperlint/banal/<commit>/banal`
+(`$XDG_CACHE_HOME/paperlint/banal` when set, `$PAPERLINT_BANAL_DIR` over both), and accepts it only after banal
 has run on a one-page probe and measured it. paperlint then runs it as a separate program — `perl banal
 -no-time -json <file>.xml` — and reads its JSON output. Nothing of banal is copied, linked or
 translated into this package.

package/eslint-rules/paper-typography.mjs

@@ -27,7 +27,7 @@
  * two (blanking preserves length), so scanning `raw` and reporting the offset found there
  * still points at the right byte.
  *
- * ── WHY `bareDecimal` READS NEITHER, BUT THE PARSED TREE (rpp#44) ─────────────────────────
+ * ── WHY `bareDecimal` READS NEITHER, BUT THE PARSED TREE (paperlint#44) ─────────────────────────
  * Origin. On a workshop paper (HotCRP #20) Reviewer B wrote: `Numbers should be completed:
  * e.g. ".05" -> 0.05`. The submitted PDF really carried `p < .05`, `p=.002`, `p=.006` and
  * `p=.037` in its text (measured with pdftotext on the submitted version); the camera-ready

package/eslint-rules/paper-typography.mutations.mjs

@@ -14,7 +14,7 @@
  * fixture exists, not that the count is correct.
  *
  * The bare-decimal count is the exception, because what it gets wrong is not the lexeme but the
- * INPUT: rpp#44 was a correct regex run over the wrong text. So two cases below change what it
+ * INPUT: paperlint#44 was a correct regex run over the wrong text. So two cases below change what it
  * reads — back to the raw source (the SILENT half must die), and with math dropped from the walk
  * (the CAUGHT half must die, since math is where p-values live).
  */

package/eslint-rules/papers.mjs

@@ -85,6 +85,7 @@ import {
   CONFIG_KEY,
   DEFAULT_PAPERS_ROOT,
   PAPERS_DIR_FIELD,
+  PAPER_SETTINGS_FILE,
   declaredSettings,
   renamedFieldMessage,
   settingsOf,
@@ -154,8 +155,11 @@ export function paperFiles(root) {
     tex: [`${root}/*/paper.tex`],
     /** The per-paper stage ledger. */
     status: [`${root}/*/PIPELINE-STATUS.md`],
-    /** The venue data card. */
-    venue: [`${root}/*/venue.json`],
+    /**
+     * The per-paper settings file, `paperlint.json` (`venue.json` before 2.1.0). The key keeps its
+     * old name so a consumer's config that lints these files keeps matching them.
+     */
+    venue: [`${root}/*/${PAPER_SETTINGS_FILE}`],
     /** Facts extracted from the built PDF. */
     pdfFacts: [`${root}/*/_build/paper.facts.json`],
     /** Facts extracted from the bibliography. */

package/eslint-rules/pdf-last-page-balance.harness.mjs

@@ -2,7 +2,7 @@
  * Colocated test for `eslint-rules/pdf-last-page-balance.mjs` (`pdf/last-page-balance`).
  * Run: `npx vigiles test eslint-rules/pdf-last-page-balance.harness.mjs`
  *
- * The rule is driven the way a consumer drives it: through rpp's own `buildConfig`, with the
+ * The rule is driven the way a consumer drives it: through paperlint's own `buildConfig`, with the
  * rule turned on by a `rules` block in the settings — not through a config invented here. Each
  * paper is a temporary directory holding `paper.tex`, `paper.pdf` and the facts `paperlint build`
  * would write beside them.
@@ -51,7 +51,9 @@ const facts = (lastPage, over = {}) => ({
 });
 const MEASURED = (l, r) => ({ kind: "measured", columns_pt: [l, r] });
 
-const root = realpathSync(mkdtempSync(join(tmpdir(), "rpp-balance-rule-")));
+const root = realpathSync(
+  mkdtempSync(join(tmpdir(), "paperlint-balance-rule-")),
+);
 /** A paper directory with paper.tex, paper.pdf and, unless `null`, `_build/paper.facts.json`. */
 const paper = (name, f, { pdf = PDF } = {}) => {
   const dir = join(root, "papers", name);
@@ -67,7 +69,7 @@ const paper = (name, f, { pdf = PDF } = {}) => {
   return dir;
 };
 
-/** Lint files with rpp's config, the rule turned on for `papers/**` (unless `rules` says otherwise). */
+/** Lint files with paperlint's config, the rule turned on for `papers/**` (unless `rules` says otherwise). */
 async function lint(
   files,
   rules = [

package/eslint-rules/pdf-last-page-balance.mjs

@@ -29,12 +29,14 @@
  *
  * Silent, by design, where there is nothing to judge: a stub last page (a few lines) and a review
  * build (numbered lines in the margins make both columns measure full height). Loud where the input
- * is missing: no facts file, a foreign schema, facts about a PDF that is not on disk or changed
+ * is missing: no facts file (unless the paper extends a venue preset — then `pdf/measured` says it),
+ * a foreign schema, facts about a PDF that is not on disk or changed
  * since — a rule that is on and reads nothing must not look like a rule that passed.
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join } from "node:path";
+import { PAPER_SETTINGS_FILE } from "../lib/paper-config.mjs";
 
 /** The difference, in points, that two columns may end apart. See the harness for why 120. */
 export const DEFAULT_TOLERANCE_PT = 120;
@@ -133,11 +135,30 @@ function reportLine(file) {
   }
 }
 
+/**
+ * Whether the paper extends a venue preset. Then the venue rules run on it too, and `pdf/measured`
+ * already says — once, as a warning — that a paper with no facts was not checked; this rule
+ * repeating it as an error would fail a lint-only CI for every paper of a venue whose preset turns
+ * this rule on.
+ */
+function extendsPreset(paperDir) {
+  try {
+    const s = JSON.parse(
+      readFileSync(join(paperDir, PAPER_SETTINGS_FILE), "utf8"),
+    );
+    return typeof s?.extends === "string" && s.extends !== "";
+  } catch {
+    return false;
+  }
+}
+
 /** Everything the rule decides for one paper, as a finding or null. */
 function verdict(paperDir, tolerancePt) {
   const factsFile = join(paperDir, FACTS_REL);
   if (!existsSync(factsFile))
-    return { messageId: "noFacts", data: { file: FACTS_REL } };
+    return extendsPreset(paperDir)
+      ? null
+      : { messageId: "noFacts", data: { file: FACTS_REL } };
   const facts = parseFacts(readFileSync(factsFile, "utf8"));
   if (!facts.ok) return { messageId: facts.messageId, data: facts.data };
   return staleness(paperDir, facts) ?? judgeColumns(facts.last, tolerancePt);

package/fixtures/build-e2e/acmart/paperlint.json

@@ -0,0 +1 @@
+{ "extends": "paperlint:agenticdev", "kind": "short" }

package/fixtures/build-e2e/guards/paper.tex

@@ -1,4 +1,4 @@
-% `\input{paper-guards}` resolves with NO configuration: rpp puts its own venues directory on
+% `\input{paper-guards}` resolves with NO configuration: paperlint puts its own venues directory on
 % TEXINPUTS. The guards fire only on the final pass (\finalpass), so a clean paper with a
 % forward \ref must still build.
 \documentclass{article}