paperlint 2.0.0

package/docs/install.md

@@ -0,0 +1,170 @@
+# Installation
+
+This page covers what `npm i -D paperlint` and `npx paperlint init` set up, exactly what
+`init` writes, which package managers work, what the install weighs, and what to do when something
+is off. The README has the short version.
+
+## Install
+
+```sh
+npm i -D paperlint
+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.
+
+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:
+
+- **TeX Live** — `npx paperlint toolchain` installs the packages your venues declare (or answer `Y` when
+  `paperlint build` offers). It also fetches **banal**, HotCRP's page-geometry script, which needs
+  `perl`. See [`toolchain.md`](toolchain.md).
+- **Java and Python 3** — some skills call them; install them yourself. `paperlint init` and
+  `paperlint doctor` list what is missing and which skills go quiet without it. `paperlint lint` needs none of
+  these programs.
+
+## What `paperlint init` does
+
+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`.
+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.
+
+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
+question (Ctrl+D) also takes the default.
+
+## What `paperlint init` writes
+
+| what                                                               | where                   | when                                                                                                                                                                              |
+| ------------------------------------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| a `paperlint` key naming your papers directory                     | your `package.json`     | always                                                                                                                                                                            |
+| 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
+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
+`rpp.json` was read only by the CLI. `rpp.json` is still read as a deprecated fallback, and
+`paperlint lint` says so.
+
+**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
+its install script in 5.0.0 and Playwright in 1.38.0, because a failed install is cached and its
+output is hidden. An install that can fail quietly is worse than a step that says what it needs.
+
+**Hooks go into `.claude/settings.json`, not a plugin.** Claude Code documents that file as the
+way to share hooks with a team, `init` can write it, `paperlint doctor` can read it back, and it needs
+nothing installed inside Claude Code. A plugin fetched from npm gets no `node_modules` (`npm pack`
+strips the lockfile, and the host runs `npm ci` only when one is present), so it could not carry
+code that runs (probes: [`prior-art/repro/`](prior-art/repro/README.md); decision:
+[`prior-art/paper-folder-scaffolding.md`](prior-art/paper-folder-scaffolding.md) § 5). The package
+ships no plugin.
+
+**Skills are linked, not left in `node_modules`.** Claude Code finds project skills in
+`.claude/skills/<name>/SKILL.md` and never inside `node_modules`. The links also make the
+project-relative script paths inside the skills (`.claude/skills/paper-pipeline/scripts/x.mjs`)
+resolve.
+
+- **What is linked:** every subdirectory with a `SKILL.md` under the package's `skills/`
+  directory (`SHIPPED_SKILLS_DIR` in `skills/paper-pipeline/scripts/consumer.mjs`). No list is
+  written down.
+- **Where a link points:** the package as it resolves by name from your project, spelled through
+  `node_modules/paperlint`. Under pnpm the resolved path is a version-stamped store
+  directory, and a link spelled that way would dangle after the next upgrade.
+- **What it never does:** replace an entry it did not make. Such an entry is named in the report
+  and left alone, and `init` still succeeds; `paperlint doctor` repeats it as a warning.
+
+**`paperlint doctor` exists because the edit guard is silent when it works.** `paper-edit-guard` says
+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.
+
+### How comparable tools install
+
+Read from their published tarballs on 2026-09-18. Most write their config from an `init`; the two
+that do not (Prettier, lint-staged) need the most steps. Playwright, the closest analogue (config,
+a CI workflow and a heavy toolchain), asks two questions and guesses the rest.
+
+| tool        | commands to working state                                   | writes config?                                                      | wires hooks/CI?                                                  | install-time script?                              |
+| ----------- | ----------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
+| ESLint      | **1** — `npm init @eslint/config@latest`, installs deps too | yes, `eslint.config.js`                                             | no                                                               | none                                              |
+| Playwright  | **1** — `npm init playwright@latest`                        | yes                                                                 | **yes — GH Actions workflow + browsers, both asked inside init** | **removed in 1.38.0**                             |
+| Biome       | 2 — install, `biome init`                                   | yes, zero prompts                                                   | no                                                               | none (platform binaries via optionalDependencies) |
+| husky       | 2 — install, `husky init`                                   | yes — edits `package.json`, writes `.husky/`, sets `core.hooksPath` | yes, git hooks                                                   | **removed in 5.0.0**                              |
+| changesets  | 2 — install, `changeset init`                               | yes                                                                 | no                                                               | none                                              |
+| Tailwind v4 | 3 + hand edits                                              | **no — `init` deleted, the package has no `bin` at all**            | no                                                               | none                                              |
+| Prettier    | 3 — config created by shelling out to `node --eval`         | **no init command exists**                                          | no                                                               | none                                              |
+| lint-staged | 4+, all manual                                              | no                                                                  | no, delegates to husky                                           | none                                              |
+
+## Package managers
+
+**npm and pnpm are covered; Yarn Plug'n'Play is not supported.**
+
+`test/e2e/install.mjs` packs the tarball, installs it into a clean project with each manager that
+launches on the machine, and runs the hook command to see whether it resolves. A grep over
+`hooks.json` would not do: the string is right under any manager, and whether it resolves depends
+on the tree the manager laid out. It also checks that every shipped skill is reachable as
+`.claude/skills/<name>/SKILL.md`, that a second `init` changes nothing, and that a foreign
+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
+a different answer to "where is the runtime", not a flag.
+
+## Install size
+
+Measured 2026-09-23 with npm 10.9.7 on a clean project (production dependencies only). Since then
+zernie/vigiles#280 made the `vigiles` grammars optional, so the `@ast-grep/*` and `typescript` rows
+are probably smaller now; re-measure before quoting them.
+
+|                                        |       size |
+| -------------------------------------- | ---------: |
+| tarball                                |     1.2 MB |
+| this package, unpacked                 |     3.7 MB |
+| **`node_modules` in total**            | **136 MB** |
+| of which `@ast-grep/*` (via `vigiles`) |      51 MB |
+| of which `typescript` (via `vigiles`)  |      23 MB |
+| of which `vigiles` itself              |       6 MB |
+
+Neither `paperlint lint` nor any of the three hooks loads `@ast-grep` or `typescript` (traced);
+`vigiles` itself is loaded.
+
+## 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                                                            |

package/docs/optional-rules.md

@@ -0,0 +1,107 @@
+# 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)).
+
+| rule                    | what it checks                                                | who needs it                                              |
+| ----------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
+| `pdf/last-page-balance` | the two columns of the last page end at about the same height | two-column papers whose publisher asks for it — see below |
+
+## `pdf/last-page-balance`
+
+### Turning it on
+
+```json
+{
+  "paperlint": {
+    "papersDir": "papers",
+    "rules": [
+      {
+        "files": ["papers/agenticdev-2026/**"],
+        "rules": { "pdf/last-page-balance": ["error", { "tolerancePt": 120 }] }
+      }
+    ]
+  }
+}
+```
+
+`files` is relative to the `package.json`. `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.
+
+### 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)),
+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.
+
+### Which venues need it
+
+Researched 2026-09-24 from the publishers' own pages. The requirement comes from some **production
+vendors**, not from the paper templates, and no standard format checker tests it — HotCRP's
+[`checkformat.php`](https://github.com/kohler/hotcrp/blob/master/src/checkformat.php) with
+[banal](https://github.com/kohler/hotcrp/blob/master/src/banal), ACL's
+[aclpubcheck](https://github.com/acl-org/aclpubcheck) and IEEE PDF eXpress all leave it alone.
+
+| venue or publisher                                                                                      | balance required?                                                                                                                   | source                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Conference Publishing Consulting** (produces ICSE, ASE and other SIGSOFT/SIGPLAN proceedings for ACM) | **yes** — the paper "has balanced columns on the last page, if the page is not filled"; problem papers are sent back to the authors | [instructions](https://www.conference-publishing.com/Instructions.php?Conf=ICSE12) · [help](https://www.conference-publishing.com/Help.php) · [procedure](https://www.conference-publishing.com/Procedure.html) |
+| **Sheridan Communications** (ACM SIG conferences, e.g. CCS)                                             | **yes** — "balance the last page into 2 even length columns"                                                                        | [CCS instructions](https://www.scomminc.com/pp/acmsig/ccs.htm)                                                                                                                                                  |
+| ACM `acmart` class                                                                                      | the class balances by default (option `balance`); no ACM-wide written rule was found                                                | [acmart on CTAN](https://ctan.org/pkg/acmart) · [acmart issue #328](https://github.com/borisveytsman/acmart/issues/328)                                                                                         |
+| IEEE (`IEEEtran`)                                                                                       | **advised** for camera-ready, not a written rule; PDF eXpress does not check it                                                     | [IEEEtran on CTAN](https://ctan.org/pkg/ieeetran) (`IEEEtran_HOWTO`, pp. 16–17)                                                                                                                                 |
+| ACL                                                                                                     | no                                                                                                                                  | [aclpubcheck](https://github.com/acl-org/aclpubcheck) has no such check                                                                                                                                         |
+| USENIX, AAAI, ICML                                                                                      | not mentioned in their 2025–2026 author instructions                                                                                | —                                                                                                                                                                                                               |
+| NeurIPS, Springer LNCS                                                                                  | not applicable — one column                                                                                                         | —                                                                                                                                                                                                               |
+
+⚠️ **ACM TAPS venues:** ACM's TAPS system compiles the final PDF itself from your source. A fix that
+lives only in a generated file (an edited `.bbl`) may never reach the proceedings; put the fix in
+your source.
+
+### Fixing it by hand
+
+paperlint does not fix it for you, deliberately: every mechanism is documented as unreliable by its own
+authors, and a layout change can silently move a page break in a paper whose page count is
+limited. Conference Publishing Consulting's own advice, in its order:
+
+1. > "For the ACMART style, use option 'balance' or, if this does not work, option 'pbalance'."
+
+   `balance` is already acmart's default, and it calls `\balance` from the **second** column of the
+   last page — where balance.sty does nothing. That is the usual case when the last page is all
+   bibliography. So try `\documentclass[…,pbalance]{acmart}` (acmart calls it experimental; it
+   needs an extra LaTeX pass and may give up).
+
+2. `\usepackage{flushend}`. IEEEtran's guide warns of "a spacing anomaly between two lines within
+   a reference in the second column of the last page".
+3. `\balance` (from balance.sty) placed in what would be the **first** column of the last page. In
+   a bibliography that means inside `\begin{thebibliography}`, before the `\bibitem` that starts the
+   last page's first column; the balance documentation says it "should be issued somewhere in the
+   text of what would be the first column of the last page".
+4. A `\newpage` between references in the `.bbl` file (the vendor's fourth option) — the most
+   fragile, since bibtex rewrites the `.bbl` on every build.
+
+For IEEEtran, the class's own guide recommends `\IEEEtriggeratref{N}` over any package.
+
+Then `paperlint build` again and `paperlint lint` again.
+
+### Why it is not part of `paperlint build`
+
+Until 2026-09-24 `paperlint build` searched for a `\balance` position itself — rebuilding once per
+bibliography entry — and failed the build, deleting the PDF, when none worked. It was removed:
+only some venues ask for balance, a build step cannot be turned on per venue, given a severity or
+suppressed with a reason, and an automatic layout change was the one place the build rewrote a
+paper's output behind the author's back. The build now only measures; the rule judges.

package/docs/package-shape-options.md

@@ -0,0 +1,262 @@
+# Package shape — four options, and what was measured to get there
+
+**Status:** a design pass run 2026-09-19 against [`prior-art/`](prior-art/README.md). It is a
+PROPOSAL, not a decision. It sits beside the prior art rather than inside it because a proposal
+and its evidence age at different rates.
+
+The pass was given the repository, the recorded reasons behind today's design, and permission to
+research further. It came back having **refuted four premises it was handed** before proposing
+anything. Those corrections are the valuable part and are recorded first, each with its
+verification status.
+
+---
+
+## Premise corrections
+
+### 1. VERIFIED — the 81 MB is a `vigiles/package.json` fact, not a hook-runtime fact
+
+The recorded trade-off was "ordinary dependency (heavy) versus optional peer (light, but a manual
+install step)". That framing is false, because the runtime does not use the heavy modules at all.
+
+Measured on the v28 build, top-level `require` of `typescript`, `@ast-grep/*` or `mvdan-sh` in
+each module of the `hook-runtime run-program` chain:
+
+```
+dist/hook-runtime.js         0
+dist/core/hook-program.js    0
+dist/load-hook.js            0
+dist/hook-install.js         0
+dist/core/hook-providers.js  0
+dist/hook-state-store.js     0
+dist/observe.js              0
+```
+
+They arrive because `vigiles` lists them under its own `dependencies`. Independently confirmed by
+this repository's consumer-side measurement the same day: after the v28 lazy-boundary work the
+adapter registry loads **18 modules instead of 107, with zero ast-grep and no native binding** on
+the hook path.
+
+### 2. CORRECTED — `optionalDependencies` does NOT deliver the weight cut
+
+The proposal was to move the heavy modules to `optionalDependencies`, keeping `vigiles` an
+ordinary dependency and cutting the install from ~148 MB to ~67 MB. **Measured, and it does not
+work that way:**
+
+```console
+$ npm config get omit
+                                  # empty — nothing is omitted by default
+
+$ cat package.json                # { "optionalDependencies": { "is-odd": "^3.0.1" } }
+$ npm install && ls node_modules/is-odd
+is-odd                            # INSTALLED by default
+
+$ npm install --omit=optional && ls node_modules/is-odd
+                                  # absent only with the explicit flag
+```
+
+npm installs optional dependencies unless they fail to build or the user passes `--omit=optional`.
+So this prescription reintroduces exactly the manual step that made the optional-peer design get
+reverted.
+
+**What would actually work, and it is a different change:** publish the runtime as its own light
+package, so the heavy modules are not in the dependency closure of what a hook consumer installs.
+`vigiles lint` and `vigiles compile` keep the full set; a project that only runs hooks pulls the
+small one. This is a real upstream change rather than a manifest tweak, and the question it raises
+is no longer "will optional deps be accepted" but **"is the runtime worth splitting into its own
+package"**.
+
+### 3. MEASURED — two of the three platform claims needed correcting
+
+These three were taken from the host's documentation and were load-bearing for Option B. They
+have now been measured against the real `claude` CLI (2.1.278) driven by a scripted mock model, so
+each run is deterministic and costs nothing. Scripts: [`prior-art/repro/`](prior-art/repro/README.md).
+
+**(a) `${CLAUDE_SKILL_DIR}` substitutes in a skill's body — HOLDS, and it is the ONLY variable
+that works in both doors.** Measured in the project channel and the plugin channel, the latter
+with the session's cwd in an unrelated directory:
+
+```
+=== A. PROJECT-level skill (.claude/skills) — the npm+symlink door ===
+  CLAUDE_SKILL_DIR     -> "/tmp/vigiles-harness-BHkoMg/.claude/skills/xchan-project"
+  CLAUDE_PLUGIN_ROOT   NOT SUBSTITUTED -> "${CLAUDE_PLUGIN_ROOT}"
+=== B. PLUGIN-provided skill — the plugin door ===
+  CLAUDE_SKILL_DIR     -> ".../xchanplugin/skills/xchan-plugin"
+  CLAUDE_PLUGIN_ROOT   -> ".../xchanplugin"
+```
+
+The documented `${CLAUDE_PLUGIN_ROOT}` is a literal no-op in the project channel, and where it
+does work it anchors to the plugin root rather than the skill, so it would force two spellings of
+every path. There is no second candidate. **Bonus the claim omitted:** `allowed-tools` frontmatter
+substitutes too — which matters, because 18 of the 89 SKILL.md occurrences live there rather than
+in the body.
+
+**(b) The `hooks:` caveat is real and WORSE than "not substituted".** The placeholder is passed
+through to the shell, which expands an unset variable to nothing, so
+`node ${CLAUDE_SKILL_DIR}/scripts/x.mjs` silently becomes `node /scripts/x.mjs` — no error, and no
+`${...}` literal left to grep for. The hook fires (`exitCode 0`, sentinel green), so this is "no
+substitution", not "no run". Upstream `anthropics/claude-code#36135` describes exactly this and is
+**closed as not planned**. ⇒ `plugin/hooks/hooks.json` must keep `${CLAUDE_PROJECT_DIR}` /
+`${CLAUDE_PLUGIN_ROOT}` and must never adopt `${CLAUDE_SKILL_DIR}`.
+
+**(c) The npm marketplace entry — HOLDS, but the shape recorded above was WRONG.** `source` is an
+object whose own `source` key names the type. Verified twice, independently, capturing the real
+exit code:
+
+```console
+$ claude plugin validate <flat, as this note first recorded it> --strict   # RC=1
+  > plugins[0].source: Bare source name "npm" requires metadata.pluginRoot.
+$ claude plugin validate <nested>                                --strict   # RC=0
+  √ Validation passed
+$ claude plugin validate <"source": "nosuchsourcetype">          --strict   # RC=1  (control)
+```
+
+```json
+{
+  "name": "research-paper-pipeline",
+  "source": {
+    "source": "npm",
+    "package": "research-paper-pipeline",
+    "version": "^0.1.0"
+  }
+}
+```
+
+`version` is optional and accepts an exact version or a range. Because the wrong shape fails
+`claude plugin validate --strict` with a nonzero code, this is a defect that a CI gate can make
+unshippable rather than a thing to remember.
+
+**(d) "Dependencies are not installed" — FALSE as worded; the conclusion survives for a different
+reason.** Measured A/B on two byte-identical plugins differing only by a lockfile: with one,
+`node_modules` materialised in the plugin cache; without one, nothing, and no log entry. Lifecycle
+scripts did not run in either. The true rule is **`npm ci --ignore-scripts` runs iff `package.json`
+AND a supported lockfile are both present in the fetched root**. What rescues the conclusion is a
+separate fact: `npm pack` strips `package-lock.json` unconditionally — proven with a positive
+control, where a newly created file listed in the same `files[]` array was included while the
+lockfile in that array was not.
+
+⇒ **A plugin installed from npm gets no `node_modules`, silently.** Three scripts break on it, not
+zero: `pipeline-check.mjs`, `extract-ref-facts.mjs` and `bib-authors.mjs`, all reaching
+`markdown-it`. Which retires a number this note carried: the closure is **two** third-party
+packages over **eight** referenced scripts, not one over seven — `extract-ref-facts.mjs` reaches
+`@retorquere/bibtex-parser` through a dynamic `await import()` that a static grep does not see.
+
+⏳ **Not measured, recorded as such:** the documented 60-second install timeout; the personal
+`~/.claude/skills` and `--add-dir` channels (2 of 4 locations verified); and a genuine
+`{"source":"npm"}` install end-to-end — the A/B used a local git source, since publishing to a
+registry was out of scope.
+
+### 4. VERIFIED INDEPENDENTLY — the mtime check is wrong on every fresh checkout
+
+git does not preserve modification times; a CI checkout gives every file the same timestamp. A
+"build log older than its source" rule keyed on mtime is therefore decided by clone order, not by
+content. Recording `sha256(source)` at build time makes it a pure comparison. See
+[`prior-art/nondeterministic-checks.md`](prior-art/nondeterministic-checks.md).
+
+---
+
+## The four options
+
+Each was asked for a complete `--help`, a delivery table, a config, an install counted in actions,
+the structural guarantee it buys, and its migration cost. Condensed here; the shape is what
+matters.
+
+### A — "A linter, full stop"
+
+paperlint is Ruff for papers. Skills and hooks leave the package entirely and become a separate,
+self-contained Claude Code plugin that _calls_ paperlint when present and says so loudly when absent.
+
+```
+paperlint — lint and build for a paper kept in git
+
+  npx paperlint init            find the papers directory, declare it, offer the CI step
+  npx paperlint lint [dir…]     run every rule; warnings never fail (--strict makes them)
+  npx paperlint build [paper]   run the paper's own build script; record sha256 of source and pdf
+
+  --json   machine-readable findings      --strict   promote warnings to errors
+```
+
+Removed: `doctor` (folded into an idempotent `init`), `hook` (no hooks in the package),
+`--config` and the `rpp.json` fallback, `--max-warnings` (a threshold nobody chooses on purpose)
+→ binary `--strict`, `--dry-run`, `--all`.
+
+**Buys:** the linter cannot depend on an agent runtime, so the weight cut needs nobody's
+permission. A plugin cannot be half-installed. **Costs:** two repos, two version lines, three
+hooks rewritten as plain stdin-JSON/exit-2 scripts outside the vigiles machinery.
+
+### B — "One artifact, two doors"
+
+One published tarball that is simultaneously the npm package and the plugin: the marketplace entry
+points at npm, the plugin manifest sits at package root, `skills/` is the default scanned
+directory, and `paperlint init` opens both doors.
+
+```
+paperlint — machine-checkable gates for a paper kept in git
+
+  npx paperlint init            declare where the papers live; wire CI and the plugin; then doctor
+  npx paperlint lint [dir…]     run every rule; --strict to fail on warnings; --json for machines
+  npx paperlint build [paper]   run the paper's own build script; record sha256 of source and pdf
+  npx paperlint doctor          what is wired vs. what only looks wired
+
+  `paperlint hook <name>` exists for the plugin wiring and is not for typing.
+```
+
+`doctor` survives here _because_ this option puts two copies of the package on disk (plugin cache
+and `node_modules`) and something must say whether their versions agree.
+
+**Buys:** the plugin and the npm package cannot ship different skills — there is one tarball, so
+the "installs all 24 skills" contradiction is resolved by fact rather than by editing prose. Every
+skill path becomes `${CLAUDE_SKILL_DIR}/…`, which the host resolves instead of the prose guessing.
+**Costs:** publishing to npm becomes a precondition; the SKILL.md literals rewritten (measured:
+**89** occurrences across 23 skills — 71 in bodies, 18 in `allowed-tools`, both of which
+substitute) and the existing advisory rule flipped to error; and vendoring `markdown-it`, because
+the plugin door gets no `node_modules` at all (correction 3d). **Gives up:** nothing structural — the
+package stays a 26-skill monolith, and a researcher who never uses an agent still downloads 2.9 MB
+of markdown.
+
+### C — "Plugin-first"
+
+The plugin is the primary artifact; the npm package shrinks to the two commands skills shell out
+to. Honest about audience, and explicitly not recommended by the pass itself: this repository's
+own primary consumer installs through npm and symlinks, so the primary consumer would sit on the
+secondary path.
+
+### D — "A runner, and rule packs like Vale"
+
+paperlint becomes a runner; rules are packages declared in config and pulled with `paperlint add`, following
+Vale's `Packages:` + `sync`, textlint's rule packages, and `astro add`. Severity is data inside a
+pack, capped by the runner. **Right shape for a second author; ceremony for one publisher.** Named
+here so it is not reinvented, with its trigger: a second rule author.
+
+---
+
+## Ranking, as delivered
+
+1. **B**, because it removes a delivery channel instead of documenting it and closes each open
+   problem by construction.
+2. **A**, because its weight cut depends on no upstream change — take it if the runtime split is
+   refused.
+3. **C** — coherent, wrong primary audience.
+4. **D** — 2027.
+
+⚠️ **The stated deciding question was "will vigiles move the heavy modules to optional
+dependencies". Correction 2 retires that question**: optional dependencies install by default. The
+real question is whether the hook runtime is worth publishing as its own package. If it is not, A
+moves to first for exactly the reason given — it is the only option that gets light without
+asking anyone.
+
+## Three fixes that no option makes optional
+
+1. **Declare `exports`.** An empty `exports` map beside a README that documents importing from
+   `bin/rpp.mjs` is a false statement about the API surface.
+2. **Replace the mtime and wall-clock checks with hashes recorded by `build`.**
+3. **Make hooks consume `paperlint lint --json` and read the `severity` field.** Anything that
+   re-derives severity from rendered text — an emoji, a prefix — is lossily reconstructing a field
+   that already exists one layer down.
+
+## One proposal deliberately NOT acted on
+
+The pass suggests `paperlint init` write `enabledPlugins` and the marketplace entry into the consumer's
+`.claude/settings.json` so the plugin is enabled without `/plugin` commands. It is a coherent
+idea with a precedent, and it is recorded here as a proposal only: a tool writing into a user's
+agent settings is a decision for the person who owns those settings, not a detail of the install
+script.

package/docs/prior-art/README.md

@@ -0,0 +1,76 @@
+# Prior art — how comparable tools are shaped
+
+**Why this folder lives in the repository.** These are technical records that code and other docs
+cite by path: `test/e2e/install.mjs` cites `package-location.md`, `scripts/marketplace-shape.mjs`
+and `docs/install.md` point at the probes in `repro/`, and `eslint.config.mjs` excludes `repro/`
+by name. Moving the folder out would leave those references pointing nowhere. The notes are for
+contributors and maintainers, not for someone checking a paper, which is why the README does not
+link them and `CONTRIBUTING.md` does.
+
+Why this folder exists: this package is four things at once (a linter over papers, a build
+front-end, a host for agent hooks, and a carrier of skills), and every design argument about
+its command surface kept being settled by taste. These notes settle them by looking at tools
+that already solved the same problem, with the URL that was checked.
+
+**Files are split by QUESTION, not by tool** — Quarto answers two different questions and has to
+be citable for each one separately.
+
+| file                                                         | the question                                                                | the verdict in one line                                                                                                                                                                                              |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`multi-mode-tools.md`](multi-mode-tools.md)                 | how do linter + builder + extension host live in one CLI?                   | small-feeling tools have fewer **nouns**, not fewer capabilities — the project config supplies what would be an argument                                                                                             |
+| [`blocking-vs-advisory.md`](blocking-vs-advisory.md)         | who decides to fail the run — the rule or the runner?                       | severity is **data on the finding**; failing is the **runner's** decision, and the default is not to fail                                                                                                            |
+| [`nondeterministic-checks.md`](nondeterministic-checks.md)   | may a check read the clock, an mtime, or a diff?                            | yes, but make it opt-in, never blocking — and prefer a **recorded fact** to an inferred one, which dissolves most of them                                                                                            |
+| [`content-delivery.md`](content-delivery.md)                 | how is installable content (skills, styles, extensions) delivered?          | the **config declares it and a command fetches it**; content that hard-codes its own install path is betting on one channel                                                                                          |
+| [`test-tooling.md`](test-tooling.md)                         | what do we test with — a framework? a local registry?                       | **change nothing**: a runner buys a reporter and a second exit code; a registry is what MULTI-package repos need. Both have named triggers                                                                           |
+| [`package-location.md`](package-location.md)                 | how does a package find its own installed files, and its own bin?           | resolve the package dir **once** from `<pkg>/package.json`; **keep** the `.bin` launch — it is the only check that observes the manager's own work. Yarn PnP stays out, for a harder reason than previously recorded |
+| [`readme-structure.md`](readme-structure.md)                 | how do comparable linters lead a new reader to a first working run?         | one sentence, then a real run with its real output; install on the first screen; design reasoning never on the front page                                                                                            |
+| [`paper-folder-scaffolding.md`](paper-folder-scaffolding.md) | who creates a paper folder, and who wires the hooks — a command or a human? | ship the template as a FILE and scaffold from it (`rpp new`); `init` writes the hooks into `.claude/settings.json` instead of printing `/plugin` lines                                                               |
+
+## Tools examined, and for what
+
+| tool                                                 | why it is here                                                                                       |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Quarto**                                           | the domain analogue — scientific publishing with `render` / `check` / `publish` and extensions       |
+| **Vale**                                             | the content analogue — a prose linter whose styles are declared in config and fetched by `vale sync` |
+| **Biome**                                            | the "one tool, one config, one command" position, stated by its own authors                          |
+| **Danger JS**                                        | a linter for the PROCESS rather than the code; levels as separate functions                          |
+| **reviewdog**                                        | non-blocking by default; failing is a flag on the runner                                             |
+| **eslint-plugin-unicorn** (`expiring-todo-comments`) | proof that a time-dependent lint rule is respectable — and how its author contained it               |
+| **Semgrep** (`--baseline-commit`)                    | a before/after check without an event: same analysis, two revisions, subtract                        |
+| **ESLint**, **Clippy**, **pre-commit**               | severity as config data; content declared, fetched and pinned                                        |
+
+## How to use this folder
+
+- **Before changing the command surface**, read `multi-mode-tools.md`. The argument "we need
+  another command for X" is usually an argument that the config is not declaring something.
+- **Before adding a check that can fail a build**, read `blocking-vs-advisory.md` and
+  `nondeterministic-checks.md` in that order.
+- **Before adding anything to the plugin or the skills**, read `content-delivery.md` — it
+  records the measured state in which the plugin channel delivers zero skills.
+
+## What this folder is NOT
+
+It does not argue whether this package should exist, or how it compares to other academic
+skill suites — that question is answered in `CONTRIBUTING.md`, § "Why not one of the existing
+academic skill suites". Different question, deliberately not merged.
+
+## The scripts behind the numbers
+
+[`repro/`](repro/README.md) holds the probes for the platform measurements that
+`../package-shape-options.md` § "Premise corrections" rests on — the `${CLAUDE_SKILL_DIR}`
+substitution table, the five marketplace shapes with their real exit codes, and the dependency
+closure scan. They are kept so a verdict here can be disagreed with by running a program.
+
+It also holds the CLAIM 4–6 probes behind [`package-location.md`](package-location.md): the
+resolution matrix under npm and pnpm, the Yarn PnP zip-path measurement, the four ways to launch
+an installed bin, and the `exports`-map mutation that is the entire case for changing anything.
+
+## Status
+
+Written 2026-09-19 from first-hand fetches of the sources cited in each file.
+
+The design pass run against these notes landed the same day:
+[`../package-shape-options.md`](../package-shape-options.md) — four options for the package's
+shape, a ranking, and four premise corrections that came out of it. It sits BESIDE this folder,
+not inside it, because a proposal and its evidence age at different rates: these notes stay true
+as long as the tools they cite do; that proposal expires the moment a shape is chosen.