paperlint 2.0.1 → 3.0.0

package/CLAUDE.md

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

package/CONTRIBUTING.md

@@ -109,6 +109,27 @@ node scripts/run-mutations.mjs   # run the remaining batteries (deprecated, #52
 None of these are needed to USE the tool — they are here because the gates are part of the
 argument, not decoration.
 
+## Adding a venue
+
+A venue is a **preset**, a JSONC file in `skills/submit-paper/references/venues/`, validated by
+`venue-profile.schema.json` beside it. Adding one is three files and no code:
+
+1. **The preset, thin.** `venues/<name>.jsonc` extends the template family it is built on
+   (`"extends": "paperlint:acm-sigconf"` for an ACM venue) and adds only what the call for papers
+   sets: `format.kinds` (the page limit of each kind of paper) and, when the venue's producer asks
+   for something an optional rule checks, `rules`. Every number carries the quote it came from.
+   A venue on a template with no family yet stands alone (`template`, `tex`, `format`) — or, better,
+   add the family first: measured on a real template build (banal + pdf.js), not copied from
+   documentation ([#88](https://github.com/zernie/paperlint/issues/88)).
+2. **The card.** `venues/<name>.md` — prose about the venue: deadlines, tracks, the blind model,
+   what the form asks.
+3. **A test.** A case in `src/presets.test.ts` that `paperlint:<name>` resolves over its family with
+   the kinds you declared; `src/tex-requirements.harness.mjs` already checks every shipped preset
+   against the schema.
+
+`paperlint toolchain` picks the new preset's packages up by itself, and the README and
+[`docs/rules.md`](docs/rules.md#checks-against-the-venue) list the shipped presets — update both.
+
 ## Releases
 
 Every push to `main` runs semantic-release (`.github/workflows/release.yml`). The squash commit —

package/README.md

@@ -1,255 +1,306 @@
+<!--
+README style — keep it scannable, not a wall of text:
+- One idea per paragraph; paragraphs ≤ 3 lines. Split anything longer.
+- Every section starts with a heading (##); sub-topics get ###. No section longer than one screen.
+- Lists over prose for anything with 3+ items; bullets ≤ 2 lines.
+- Tables for comparisons (commands, venues, checks). Code blocks for every command and file.
+- A blank line between every block. Bold only for the one phrase a skimmer must see.
+- Mechanics and edge cases live in docs/, linked — not inline.
+- A reader must be able to answer "what is it, which venues, how do I start" from the first screen.
+- Sparse emoji are fine where they help rhythm and scanning (e.g. one per section heading or feature bullet); never decorative, never several in a row.
+-->
+
 # paperlint
 
 [![npm version](https://img.shields.io/npm/v/paperlint)](https://www.npmjs.com/package/paperlint)
 ![Node version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fzernie%2Fpaperlint%2Fmain%2Fpackage.json&query=%24.engines.node&label=node)
 
-A linter for scientific papers written in LaTeX. It catches the mechanical mistakes that get a
+**A linter for scientific papers written in LaTeX.** It catches the mechanical mistakes that get a
 paper desk-rejected or sent back at camera-ready, before you submit.
 
-A LaTeX paper can build without an error and still be wrong. The ACM template silently switches to
-another font when one of its font packages is missing, and the pages break differently. The same
-source paginates differently on a machine with another version of the template. The submitted PDF
-gets overwritten a week later and nobody can say what was sent. You find out from a reviewer or a
-publisher, or never. paperlint checks for these on your machine and in CI:
-
-- **Builds the same PDF everywhere.** `paperlint toolchain` installs TeX Live with exactly the
-  packages your venue's template needs and checks that each one is really there, so the silent
-  font switch cannot happen and your laptop and CI build with the same TeX Live.
-- **Keeps what you submitted.** Record "submitted on 22 July, as this PDF", and paperlint fails if
-  that PDF changes or disappears, or its LaTeX source was not kept beside it.
-- **Knows the classic slips.** An ACM paper that overrides the title-page commands and loses part
-  of page 1; "code will be released" left in a camera-ready; references without a DOI or URL; an
-  unbalanced last page, for publishers that ask for balanced columns (an optional check).
-- **Works with coding agents.** Hooks and skills for Claude Code run the checks after every edit
-  and stop an agent from rewriting the paper around them.
+A LaTeX paper can build without an error and still be wrong: a missing font package silently
+changes the font, another template version changes the pagination, the submitted PDF gets
+overwritten. paperlint checks for these on your machine and in CI:
+
+- 📏 **Checks against your venue.** Page limit, embedded fonts, paper size, columns and font sizes,
+  as the call for papers sets them.
+- 🧱 **Builds the same PDF everywhere.** `paperlint toolchain` installs TeX Live with exactly the
+  packages your venue's template needs.
+- 📌 **Keeps what you submitted.** Record the PDF you sent, and paperlint fails if it changes or
+  disappears, or its LaTeX source was not kept.
+- 🔗 **Checks your references online.** At build time: each cited work exists, and its author list
+  is the published version's.
+- ✏️ **Knows the classic slips.** `§` instead of "Section", `.05` instead of `0.05`.
+  `paperlint lint --fix` fixes them.
+
+It is built on ESLint: the checks are ESLint rules over `.tex` and `.md` files, named like
+`paper/leading-zero`. You do not need to know ESLint to use it.
+
+## Contents
+
+- [Supported venues](#-supported-venues)
+- [Skills](#-skills)
+- [Getting started](#-getting-started)
+- [Commands](#-commands)
+- [Configuration](#-configuration)
+- [Run it in CI](#-run-it-in-ci)
+- [FAQ](#-faq)
+- [Docs](#-docs)
+
+## 🎯 Supported venues
+
+A preset holds a venue's format and page limits. Its **kind** is the paper type the venue sets a
+limit for — `short`, `full`, `research` — named once per paper in its `paperlint.json`.
+
+| preset                  | venue              | format                           | page limit                                                     |
+| ----------------------- | ------------------ | -------------------------------- | -------------------------------------------------------------- |
+| `paperlint:acm-sigconf` | any ACM conference | ACM two-column conference format | not checked: the family sets no kinds                          |
+| `paperlint:agenticdev`  | AgenticDev @ ASE   | ACM two-column conference format | `short` 5, `full` 10, `demo` 5 body pages, + 2 of references   |
+| `paperlint:aisec`       | AISec @ ACM CCS    | ACM two-column conference format | 10 body pages + 2 (`research`, `benchmark`, `position`, `sok`) |
+| `paperlint:realm`       | REALM @ EMNLP      | ACL two-column format, A4        | `long` 8, `short` 4 — recorded, not checked (below)            |
+
+REALM's limit is recorded but not checked because ACL leaves the Limitations and Ethics sections
+out of the page count, and the PDF measurement counts them as body pages: a paper within the limit
+would fail.
+
+Another venue: [a four-line preset file](#another-venue).
+
+## 🧠 Skills
+
+paperlint has two halves:
+
+1. **The linter** — `lint` and `build` — is deterministic: the same paper gives the same verdict,
+   so it belongs in CI.
+2. **The skills** help with the work itself, where the answer is a judgment call. They are
+   optional; `paperlint init` installs them for [Claude Code](https://claude.com/claude-code).
+
+- **Start here** — run the whole process step by step (`paper-pipeline`), or ask where the paper
+  stands (`paper-status`).
+- **Judge the idea** — is it worth doing (`research-ideate`), who else works on it
+  (`map-prior-work`), read a close competitor in depth (`analyze-sibling-paper`).
+- **Pick a venue** — find where to send it (`find-venue`), see what gets accepted there
+  (`study-accepted-papers`), put the deadlines in your calendar (`plan-paper-timeline`).
+- **Do the study and write** — design the study and its artifact (`build-benchmark`), write the
+  draft (`draft-paper`), fix the outline (`argument-arc`), cut it down (`tighten-paper`).
+- **Review before you submit** — a reader with no context (`cold-read-diff`), the prose
+  (`grade-paper-writing`), a hostile reviewer (`paper-adversarial-review`), a simulated committee
+  (`pc-panel-review`), the references (`verify-citations`), the final check (`harden-paper`).
+- **Submit and after** — render pages to images (`render-paper`), submit (`submit-paper`), upload
+  the artifact (`osf-artifact-upload`), camera-ready (`camera-ready`), the next paper (`extend-paper`).
+
+## 🚀 Getting started
 
-It is for researchers and engineers who write papers in LaTeX inside git and submit them to
-conferences or journals.
+<!-- `vigiles:symbol src/init.ts#init` — `npm run check` fails if this function is renamed or removed. -->
 
-## Install and set up
+1. Install (Node 22.13 or newer):
 
-<!-- `vigiles:symbol src/init.ts#init` — `npm run check` fails if this function is renamed or removed. -->
+   ```sh
+   npm i -D paperlint
+   ```
 
-```sh
-npm i -D paperlint
-npx paperlint init
-```
+2. Set up — it finds your papers directory, offers a CI workflow and a first paper, and (with
+   Claude Code) links the skills:
 
-Node 22.13 or newer. Install first: `paperlint init` links the skills and hooks to the copy in
-your project's `node_modules`, so run without the install it has nothing to link to.
+   ```sh
+   npx paperlint init
+   ```
 
-`paperlint init` finds your papers directory and records it in `package.json`, offers a CI workflow and a
-first paper, and sets up the optional Claude Code skills and hooks. It installs no software. It
-asks questions only when you run it in a terminal; an agent, CI or `--yes` gets the defaults, and
-each default it takes is printed. It ends by running `paperlint doctor`, which checks the setup.
-Exactly what it writes: [`docs/install.md`](docs/install.md#what-paperlint-init-writes).
+3. TeX Live, for building — once. `init` offers it; `paperlint lint` alone needs no TeX:
 
-## What you get
+   ```sh
+   npx paperlint toolchain   # ~270 MB, ~3 min, once
+   ```
 
-| command                       | what it does                                                                                       |
-| ----------------------------- | -------------------------------------------------------------------------------------------------- |
-| `npx paperlint init`          | sets the project up (see above)                                                                    |
-| `npx paperlint new my-paper`  | creates a paper folder from a template; never overwrites a file                                    |
-| `npx paperlint lint`          | runs every check over your papers; `npx paperlint lint papers/my-paper` checks one                 |
-| `npx paperlint build <paper>` | compiles `paper.tex` to `paper.pdf` with pdflatex and bibtex; `--all` builds every paper           |
-| `npx paperlint toolchain`     | installs TeX Live with the LaTeX packages your venues need; `--check` only reports what is missing |
-| `npx paperlint doctor`        | checks the setup and exits non-zero if something is miswired                                       |
-| `npx paperlint --help`        | every command and flag                                                                             |
+4. Create a paper:
 
-A venue is the conference or journal you submit to. TeX Live is the standard LaTeX distribution;
-`paperlint build` offers to install it the first time it needs it.
+   <!-- `vigiles:symbol src/new-paper.ts#newPaper` — `npm run check` fails if this function is renamed or removed. -->
 
-## Your first paper in five minutes
+   ```sh
+   npx paperlint new my-paper
+   ```
 
-### Starting a paper
+   ```
+     ✓ created papers/my-paper
+         + PIPELINE-STATUS.md  (from the package template)
+         + paper.tex  (from the package template)
+         + paperlint.json  (from the package template)
+   ```
 
-<!-- `vigiles:symbol src/new-paper.ts#newPaper` — `npm run check` fails if this function is renamed or removed. -->
+5. Pick the venue ([the table above](#-supported-venues)) in `papers/my-paper/paperlint.json`:
 
-After `npx paperlint init`:
+   ```json
+   { "extends": "paperlint:agenticdev", "kind": "short" }
+   ```
 
-```sh
-npx paperlint new my-paper
-```
+6. Build the PDF:
 
-```
-  ✓ created papers/my-paper
-      + PIPELINE-STATUS.md  (from the package template)
-      + paper.tex  (from the package template)
+   ```sh
+   npx paperlint build papers/my-paper
+   ```
 
-config: package.json
-✓ 2 file(s) checked, no findings
-```
+7. Check every paper:
 
-You now have one folder per paper:
+   ```sh
+   npx paperlint lint
+   ```
 
-```
-papers/
-  my-paper/
-    paper.tex                 the paper, in LaTeX
-    PIPELINE-STATUS.md        the paper's record: its research question and the stages it reached
-    reviews/*.md              review notes (optional)
-    versions/                 the exact PDF and source you sent at each stage, never edited
-```
+   Sample output, on a paper with two slips and no `PIPELINE-STATUS.md`:
 
-A **stage** is a point the paper has reached, such as `submitted` or `camera-ready` (the final
-version for the proceedings). The name may use `a-z`, `0-9`, `.`, `_` and `-`. On a folder that
-already exists, `paperlint new` adds only the missing files. To use your own templates, put files with
-the same names in `papers/.template/`; `{{name}}` in them becomes the paper's name.
+   ```
+   papers/hand
+     error  missing `PIPELINE-STATUS.md` — `paper/stages`, `paper/source` and `paper/research-question` read this file, so nothing `hand` declares about its stages, sources or research question is checked
+   …/papers/hand/paper.tex
+     3:4   warning  `§` instead of the word «Section» — `paperlint lint --fix` writes it                              paper/section-word
+     3:19  warning  `.05` has no leading zero — write `0.05` (IEEE / ISO 80000-1); `paperlint lint --fix` inserts it  paper/leading-zero
 
-Write the paper, then check and build it:
+   ✖ 2 problems (0 errors, 2 warnings)
+     0 errors and 2 warnings potentially fixable with the `--fix` option.
+   ```
 
-```sh
-npx paperlint lint                     # check every paper
-npx paperlint build papers/my-paper    # writes papers/my-paper/paper.pdf
-```
+Errors fail the run (exit 1); warnings only print, unless you pass `--max-warnings <n>`. To keep
+a deliberate exception, put the reason on the line above:
+`% eslint-disable-next-line paper/leading-zero -- quoted from the reviewer`.
 
-`paperlint build` runs pdflatex and bibtex until the references settle. There is no build script to
-write; a `build.sh` in the paper folder is ignored.
+### 📌 When you submit
 
-When you submit, copy the PDF and `paper.tex` into `versions/` and record the stage in the front
-matter of `PIPELINE-STATUS.md`, with the file sizes in bytes:
+Copy the PDF and `paper.tex` into `versions/`, and record the stage in the front matter of
+`PIPELINE-STATUS.md`. You write the sizes yourself (`wc -c < file`):
 
 ```yaml
 stages:
   - stage: submitted
     date: 2026-07-22
-    venue: A Venue 2026
     pdf: versions/2026-07-22-submitted.pdf
     bytes: 305412
     source: versions/2026-07-22-submitted.tex
     sourceBytes: 57210
 ```
 
-From then on `paperlint lint` fails if that PDF goes missing or changes size. A frozen PDF should never
-change, so a size that no longer matches means the file was replaced after you recorded it
+From then on `paperlint lint` fails if that PDF goes missing or changes size
 ([`docs/rules.md`](docs/rules.md#the-scorecards-bytes-and-sourcebytes)).
 
-### What a finding looks like
+## 🧰 Commands
 
-On a paper folder made by hand, with only `paper.tex`:
+| command                       | what it does                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `npx paperlint init`          | sets the project up                                                            |
+| `npx paperlint new my-paper`  | creates a paper folder from a template; never overwrites a file                |
+| `npx paperlint lint`          | runs every check over your papers; `--fix` fixes what can be fixed             |
+| `npx paperlint build <paper>` | compiles `paper.tex` to `paper.pdf`, measures it, checks the references online |
+| `npx paperlint toolchain`     | installs TeX Live with the packages your venues need (~270 MB, ~3 min, once)   |
+| `npx paperlint doctor`        | checks the setup and exits non-zero if something is miswired                   |
+| `npx paperlint --help`        | every command and flag                                                         |
 
-```
-config: package.json
-papers/my-paper
-  error  missing `PIPELINE-STATUS.md` — `paper/stages`, `paper/source` and `paper/author-list` read this file, so nothing `my-paper` declares about its stages, sources or authors is checked
-…/my-papers/papers/my-paper/paper.tex
-  1:1  warning  1 × `§` instead of «Section» (reviewer B). Paying the debt down is silent; growth is reported                                                 paper/typography
-  1:1  warning  1 × a decimal without a leading zero, `.05` instead of `0.05` (IEEE / ISO 80000-1 style). Paying the debt down is silent; growth is reported  paper/typography
-
-✖ 2 problems (0 errors, 2 warnings)
-```
+### 🔍 What the checks catch
 
-Each finding gives the file, line and column, the level, what is wrong, and the check that found
-it. The first line is an error about the folder: without `PIPELINE-STATUS.md`, the three checks
-that read it have nothing to check; `npx paperlint new my-paper` adds the file and leaves `paper.tex`
-alone. The two warnings count typography slips against an allowance you can set per paper: going over
-it is reported, fixing some is not ("paying the debt down is silent").
+| check                 | catches                                                                |
+| --------------------- | ---------------------------------------------------------------------- |
+| `pdf/fonts`           | the template's fonts are missing — LaTeX silently used Computer Modern |
+| `pdf/limits`          | more pages than the venue allows for your kind of paper                |
+| `paper/stages`        | the PDF you recorded as submitted changed or disappeared               |
+| `paper/source`        | the LaTeX source of a submitted version was not kept                   |
+| `bib/reachable-entry` | a reference with no DOI, URL or arXiv id                               |
+| `paper/author-list`   | a reference lists the preprint's authors, not the published version's  |
 
-`paperlint lint` exits `1` when any check reports an error (as here, even though the summary line counts
-only the warnings in files), or when it checked no files at all (usually a wrong path). Warnings
-never fail the run unless you pass `--max-warnings <n>`. `--json` prints the findings as JSON.
+Every check: [`docs/rules.md`](docs/rules.md). Checks only some venues need are off until you
+turn them on: [`docs/optional-rules.md`](docs/optional-rules.md).
 
-## Run it in CI
+## 🧩 Configuration
 
-`paperlint init` offers to write this GitHub Actions workflow step for you. By hand:
+Two levels, one file name, both optional:
 
-```yaml
-- uses: zernie/paperlint@v2.0.0
-  with:
-    paths: papers
+```
+paperlint.json                   the project: papersDir, rules, defaults for every paper
+papers/my-paper/paperlint.json   one paper: its venue, its kind, its own rules
 ```
 
-Use the tag of the version you installed (`npm ls paperlint`): every npm release has
-a git tag of the same version, so the step runs the same code as your package. It runs
-`paperlint lint`. `paths` is required, and the step fails if it checked zero files, so a typo in the path
-shows up red. Optional inputs: `config`, `max-warnings` (default `-1`, no limit), `texcount` (default
-`true`), `working-directory`.
+`papersDir` defaults to `papers`. If your papers live elsewhere, say so in a `paperlint.json`
+beside your `package.json`:
 
-## What the checks catch
+```json
+{ "papersDir": "docs/papers" }
+```
 
-| check                          | level   | catches                                                                                                    |
-| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
-| `paper/stages`                 | error   | a stage's PDF is missing, or it is not the same file any more (its size changed)                           |
-| `paper/source`                 | error   | a stage has no frozen source file next to its PDF                                                          |
-| `paper/author-list`            | warning | a stage is declared, but `PIPELINE-STATUS.md` does not record that the author list was checked             |
-| `paper/research-question`      | warning | the research question is missing from `PIPELINE-STATUS.md`, or the paper does not contain that sentence    |
-| `paper/typography`             | warning | more `§`, `.05`-style decimals, mixed `Fig.`/`Figure`, or references without a DOI or URL than you allowed |
-| `tex/future-promise`           | warning | a camera-ready still says your code "will be released"                                                     |
-| `tex/acm-frontmatter-override` | error   | an ACM paper overrides the template's title-page commands, so parts of page 1 go missing                   |
-| `review/findings-cause`        | error   | a review note lists several findings and names no cause for any of them                                    |
-| `doc/fields`                   | warning | a review note's front matter is missing a field you require (off unless configured)                        |
+- A paper's file merges over the root's: its `extends` and `kind` win, its `rules` apply last.
+- Only the paper files under `papersDir` are linted, never a `repro/` script beside a paper.
+- An unknown key is an error, so a typo cannot silently turn a setting off.
 
-Errors fail the run; warnings only print. What each check reads: [`docs/rules.md`](docs/rules.md).
-Checks that only some venues need are off until you turn them on:
-[`docs/optional-rules.md`](docs/optional-rules.md).
+Every key: [`docs/configuration.md`](docs/configuration.md).
 
-## Configuration
+### Another venue
 
-`paperlint init` writes the one required setting into `package.json`:
+Write a preset in your repository, and extend it by path from the paper's `paperlint.json`
+(`"extends": "../../venues/my-venue.jsonc"`):
 
-```json
+```jsonc
 {
-  "paperlint": {
-    "papersDir": "papers"
-  }
+  "extends": "paperlint:acm-sigconf",
+  "format": { "kinds": { "short": { "body_pages_max": 4 } } },
 }
 ```
 
-`papersDir` has no default, so the tool never checks a folder you did not choose: without it,
-`paperlint lint` stops and says so, unless you pass a path. An unknown key is an error. The optional
-settings, and how to use the checks inside your own ESLint setup, are in
-[`docs/configuration.md`](docs/configuration.md). TeX Live, its install location and the external
-programs the skills use are in [`docs/toolchain.md`](docs/toolchain.md).
+The full shape: [`docs/rules.md`](docs/rules.md#writing-your-own-venue-preset).
 
-## Claude Code (optional)
+## 🤖 Run it in CI
 
-`paperlint lint` needs only Node. If you use Claude Code, `paperlint init` also sets up two things:
+`paperlint init` offers to write this workflow for you, pinned to the version you installed. By
+hand:
 
-**Skills** — one per stage of writing a paper, from checking the idea through drafting, review,
-submission and camera-ready. They are linked into `.claude/skills/`. Start with `/paper-pipeline`;
-it routes to the rest. Some call Java or Python 3, which you install yourself.
+```yaml
+- uses: zernie/paperlint@v3.0.0
+  with:
+    paths: papers
+```
 
-**Hooks** — written into `.claude/settings.json`. Commit that file so every clone gets them; a
-fresh clone needs `npm install` before they run.
+- Pin the tag of the version you installed: `npm ls paperlint` prints it.
+- The step runs `paperlint lint`. It does not build, so CI needs no TeX Live.
 
-| hook                 | blocks? | what it does                                                     |
-| -------------------- | ------- | ---------------------------------------------------------------- |
-| `paper-edit-guard`   | yes     | stops a shell command from writing to a paper file               |
-| `paper-skills-nudge` | no      | after a paper edit, shows the agent the pre-submission checklist |
-| `paper-status-gates` | no      | after a paper edit, lists the stages that have not run yet       |
+## ❓ FAQ
 
-**Know this about `paper-edit-guard`:** if the `paperlint` key in `package.json`
-cannot be read (the file is missing, or has merge-conflict markers), it blocks **every** shell
-command in Claude Code, not only paper ones, until the key is readable again. Fix `package.json`
-with a normal file edit — those are not blocked.
+**Does it install anything without asking?**
+No. TeX Live comes only from `paperlint toolchain`, or when you say yes in `init` or `build`. On
+Windows, install TeX Live yourself.
 
-## What it does not do
+**Will `new` or `init` overwrite my files?**
+No. They only add what is missing, and `init` keeps a `papersDir` you already declared.
 
-- **It does not install software behind your back.** `paperlint init` installs nothing; TeX Live comes
-  only from `paperlint toolchain` or when you answer yes in `paperlint build`. On Windows, install TeX Live
-  yourself.
-- **It does not guess what to check.** There is no default papers directory.
-- **It does not overwrite your files.** `paperlint new` and `paperlint init` only add what is missing.
-- **It does not run your build script.** `paperlint build` compiles the paper itself.
-- **It does not write or grade the paper.** `paperlint lint` checks records and a few mechanical
-  mistakes; judging the writing is what the optional skills are for.
-- **New papers are LaTeX.** Markdown papers (`paper.md`) are still read but deprecated
-  ([#57](https://github.com/zernie/paperlint/issues/57)).
-- **No Yarn Plug'n'Play.** npm and pnpm are supported
-  ([`docs/install.md`](docs/install.md#package-managers)).
+**My venue isn't listed — what now?**
+Write [a four-line preset](#another-venue) that extends the closest template family. For any ACM
+venue, `paperlint:acm-sigconf` already checks the format, without a page limit.
 
-## Contributing
+**Do I need TeX Live just to lint?**
+No. `paperlint lint` needs only Node. `paperlint build` needs TeX Live.
 
-See [`CONTRIBUTING.md`](CONTRIBUTING.md): how the package is tested, the one command that runs
-every check, and how releases work: the pull-request title decides the version (`feat:` is a
-minor release, `fix:` a patch).
+**What does a CI failure look like?**
+The step fails, and its log lists each finding with file, line, check and message. It also fails
+when it checked zero files, so a wrong `paths` shows up red.
 
-## License
+**Several papers for different venues in one repo?**
+Yes. Each paper names its own venue in its own `paperlint.json`.
+
+**Where does my configuration live?**
+In `paperlint.json` — at the project root (optional) and in each paper. Nothing goes into
+`package.json`.
+
+**Do I need Claude Code?**
+No. The linter needs only Node. With Claude Code, `init` also links the skills and wires three
+hooks into `.claude/settings.json`: one stops a shell command from writing to a paper file, two
+remind the agent what is left after a paper edit ([`docs/install.md`](docs/install.md)).
+
+**Does it change my paper?**
+Only `paperlint lint --fix`, and only three rules: `paper/section-word` (`§` → Section),
+`paper/leading-zero` (`.05` → `0.05`) and `paper/figure-ref-style` (one figure-reference style).
 
-MIT.
+## 📚 Docs
+
+- [`docs/install.md`](docs/install.md) — what `init` does, package managers, troubleshooting
+- [`docs/configuration.md`](docs/configuration.md) — every setting, and how `build` compiles
+- [`docs/rules.md`](docs/rules.md) — every check, what it reads and when it fails
+- [`docs/optional-rules.md`](docs/optional-rules.md) — checks only some venues need
+- [`docs/toolchain.md`](docs/toolchain.md) — TeX Live, and Banal (HotCRP's page-geometry checker, GPL)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how the package is tested and released
+
+## License
 
-**banal is not part of this package.** banal, the page-geometry script from
-[HotCRP](https://github.com/kohler/hotcrp) (Geoffrey M. Voelker, Eddie Kohler), is licensed
-GPL-2.0-or-later. paperlint does not contain, copy or modify it: `paperlint toolchain` downloads it from HotCRP
-at a pinned commit, checks its sha256, and paperlint runs it as a separate program (`perl banal …`),
-reading its JSON output. Details: [`docs/toolchain.md`](docs/toolchain.md#page-geometry-banal-without-poppler).
+MIT. Banal, used for page geometry, is GPL and not part of this package:
+[`docs/toolchain.md`](docs/toolchain.md#page-geometry-banal-without-poppler).

package/action.yml

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

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

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

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

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