paperlint 2.1.0 → 3.0.0

package/dist/cli.js

@@ -13,10 +13,8 @@
  *     uses: zernie/paperlint@<sha>    ← action.yml
  *
  * ⚠️ THE BOUNDARY THIS UTILITY HAS NO RIGHT TO ERASE: the consumer's data stays with the consumer.
- * The typography debt, the marker of the author-list check run, the field dictionary — all of that
- * is about ONE corpus, and wiring it into the package would repeat the defect that put the path
- * `.claude/skills/verify-citations/...` into a rule's message. So they live in the consumer's
- * `package.json`, under the `paperlint` key.
+ * Where the papers are and the project's own rule blocks — that is about ONE corpus, so it lives in
+ * the consumer's own `paperlint.json`, at the project root and in each paper.
  *
  * 🔴 WHY THE COMMAND IS CALLED `lint` AND NOT `check`. It does exactly what everyone else calls by
  * that word: reads files, changes nothing, prints findings, exits non-zero. `check` is taken in the
@@ -26,7 +24,7 @@
  * replaced it: silently breaking someone else's workflow is worse than asking them to fix a line.
  */
 import { ESLint } from "eslint";
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -38,12 +36,15 @@ export { isMain };
 import { checkStructure, formatStructure, asEslintResults, } from "./structure.js";
 import { buildPapers, papersIn, anyFailed, remedyFor, MAIN } from "./build.js";
 import { prepareEngine } from "./build-engine.js";
-import { runToolchain } from "./toolchain.js";
+import { cacheRoot, cachedTree, runToolchain } from "./toolchain.js";
 import { banalInstaller, parseBanalSettings } from "./adapters/banal/index.js";
 import { curlDownload } from "./adapters/curl/index.js";
 import { hostDirs, nodeAdapters, nodeFiles } from "./adapters/node/index.js";
 import { VENUE_RULE_LEVELS, venueRules } from "./venue-rules.js";
-import { paperRules } from "./paper-settings.js";
+import { paperRules, stringFields, } from "./paper-settings.js";
+import { referenceRules, REFERENCE_RULE_LEVELS } from "./reference-rules.js";
+import { onlineReferences } from "./adapters/references/index.js";
+import { narrowToOwners, ownedPatterns, ruleOwners, scopeToOwned, } from "./paper-files.js";
 import { paperPreset, paperPresetProblem, } from "./presets.js";
 import { mergeRequirements, declaredUnion, requirementsFor, NO_REQUIREMENTS, } from "./tex-requirements.js";
 import { doctor } from "./doctor.js";
@@ -51,7 +52,7 @@ import { init, processInteractivity, askOnTerminal } from "./init.js";
 import { DEFAULT_FORMAT, FORMATS, isFormat, newPaper, reportNewPaper, } from "./new-paper.js";
 // The one source for the consumer's config key lives in the .mjs half of the package (the ESLint
 // rules and the skill scripts import it too); its types are in lib/paper-config.d.mts.
-import { CONFIG_KEY, LEGACY_CONFIG_KEY, LEGACY_KEY_MESSAGE, PAPERS_DIR_FIELD, SETTINGS_KEYS, declaredSettings, renamedFieldMessage, } from "../lib/paper-config.mjs";
+import { CONFIG_FILE, DEFAULT_PAPERS_ROOT, PAPERS_DIR_FIELD, SETTINGS_KEYS, findProjectRoot, } from "../lib/paper-config.mjs";
 import { parseRuleBlocks, parseRuleEntries, shippedRuleIds, unknownKeys, } from "./rules-config.js";
 export { init };
 export { nextSteps } from "./init.js";
@@ -64,9 +65,11 @@ import typography from "../eslint-rules/paper-typography.mjs";
 // @ts-expect-error — an ESLint rule in .mjs, it has no types
 import texBuild from "../eslint-rules/tex-build.mjs";
 // @ts-expect-error — an ESLint rule in .mjs, it has no types
-import docFields from "../eslint-rules/doc-fields.mjs";
+import bibReachable from "../eslint-rules/bib-reachable-entry.mjs";
 // @ts-expect-error — an ESLint rule in .mjs, it has no types
-import findingsCause from "../eslint-rules/review-findings-cause.mjs";
+import reviewFrontmatter from "../eslint-rules/review-frontmatter.mjs";
+// @ts-expect-error — an ESLint rule in .mjs, it has no types
+import siblingFrontmatter from "../eslint-rules/sibling-frontmatter.mjs";
 // @ts-expect-error — an ESLint rule in .mjs, it has no types
 import pdfRules from "../eslint-rules/pdf-last-page-balance.mjs";
 const USAGE = `paperlint — machine-checkable gates for a paper kept in git
@@ -84,7 +87,10 @@ const USAGE = `paperlint — machine-checkable gates for a paper kept in git
                                       paper directory is ignored (--dry-run: print the plan only).
                                       Compiles with paperlint's TeX Live, else one on PATH that has every
                                       package the venue declares; on a terminal it offers to install
-                                      one, without a terminal it stops and names \`npx paperlint toolchain\`
+                                      one, without a terminal it stops and names \`npx paperlint toolchain\`.
+                                      Then checks the references online (the cited works exist, titles
+                                      and authors match) into _build/references.json — never failing
+                                      the build: without network it records "not checked"
   npx paperlint toolchain [--check]   install TeX Live with every package the venue presets declare
                                       into ~/.cache/paperlint/texlive (PAPERLINT_TEXLIVE_DIR overrides); a second
                                       run does nothing. --check: report what is missing, change nothing
@@ -100,53 +106,61 @@ init:
   --format tex|md     the new paper's source format; default tex
 
 lint:
-  npx paperlint lint [paths…] [--config <file.json>] [--json]
+  npx paperlint lint [paths…] [--fix] [--config <file.json>] [--json]
 
   <paths…>            where your papers live, e.g. papers. Optional ONLY because the declaration
                       names it — one of the two must name the scope. There is no default
                       of ".": linting whatever happens to be in the checkout is how a green
                       report over a scope nobody chose gets produced.
+  --fix               write every fix the rules offer (section signs, leading zeros, figure
+                      references), then report what is left
   --config <file>     read the settings from this file instead of the discovered one
   --json              machine-readable findings on stdout, nothing else on it
   --max-warnings <n>  fail when warnings exceed n. Default -1: warnings never fail, because
                       most findings here are advisory and a gate that fails on advice gets muted
 
-settings — the \`paperlint\` key of your package.json, found by walking up from the
-current directory, the way every other tool in the stack finds its config. \`--config\` names
-another file of the same shape. \`papersDir\` is required; the rest is optional:
+settings — paperlint.json, at two levels, one schema. Both are optional.
 
-  "paperlint": {
-    "papersDir":         "papers",
-    "authorListCommand": "node scripts/bib-authors.mjs",
-    "typographyDebt":    { "papers/my-paper": { "sectionSign": 12 } },
-    "docFields":         { "read": { "values": ["full", "abstract", "none"] } },
-    "reviewSince":       "2026-08-23",
-    "minFindings":       3,
-    "causeMarker":       "Cause:",
-    "rules": [ { "files": ["papers/my-paper/**"],
-                 "rules": { "pdf/last-page-balance": "error" } } ]
-  }
+  paperlint.json (the project root, beside package.json) — found by walking up from the
+  current directory. \`--config\` names another file of the same shape.
 
-  "rules" takes ESLint flat-config blocks (files, ignores, rules), appended after paperlint's own, with
-  files relative to the file holding the settings. Optional rules (off unless turned on there):
-  pdf/last-page-balance. The venue rules (pdf/fresh, pdf/profile, pdf/fonts, pdf/geometry,
-  pdf/limits, pdf/body-size, pdf/measured) are on for every paper whose paperlint.json names a venue;
-  set one to "off" there to skip it.
+    {
+      "papersDir": "papers",
+      "rules": [ { "files": ["papers/my-paper/**"],
+                   "rules": { "pdf/last-page-balance": "error" } } ]
+    }
 
-per paper — <paper>/paperlint.json (it was venue.json before 2.1.0; \`npx paperlint init\` moves it):
+  "papersDir" defaults to "papers". "extends", "kind" and "pdf" here are defaults for every
+  paper. "papersDir", "structure" and the skills' keys are allowed only here.
 
-  { "extends": "paperlint:aisec", "kind": "research", "rules": { "pdf/last-page-balance": "error" } }
+  <papersDir>/<paper>/paperlint.json — one paper, merged over the root file:
+
+    { "extends": "paperlint:aisec", "kind": "research", "rules": { "pdf/last-page-balance": "error" } }
 
   "extends" names a venue preset: paperlint:<name> (shipped: acm-sigconf, agenticdev, aisec, realm)
   or ./path.jsonc, relative to the paperlint.json. npm presets are not supported yet.
 
-  "rules" there applies to that paper alone, after its preset's rules and before the project's. An unknown key,
-  anywhere in the settings or in a paperlint.json, is an error.
+  "rules" is { "<rule>": "<severity>" } for every paper file in scope, or ESLint flat-config
+  blocks (files, ignores, rules) with globs relative to that file. Order, later wins: paperlint's
+  own, the venue preset's, the root file's, the paper's. Optional rules (off unless turned on):
+  pdf/last-page-balance. The venue rules (pdf/fresh, pdf/profile, pdf/fonts, pdf/geometry,
+  pdf/limits, pdf/body-size, pdf/measured) are on for every paper with a venue preset; set one to
+  "off" to skip it. An unknown key, in either file, is an error.
 `;
 /** The config the user would otherwise write by hand. The data comes from `opts`, the mechanism is here. */
 export function buildConfig(opts = {}, texLanguage) {
     const paperRules = { ...researchQuestion.rules, ...typography.rules };
-    const typographyOpt = ["warn", { debt: opts.typographyDebt ?? {} }];
+    // The reference rules judge `_build/references.json`, and only on `paper.tex`.
+    const texPaperRules = {
+        ...paperRules,
+        ...referenceRules({ files: nodeFiles }),
+    };
+    // Each typography rule reports every occurrence where it is, and fixes it (`--fix`).
+    const prose = {
+        "paper/research-question": "warn",
+        "paper/section-word": "warn",
+        "paper/leading-zero": "warn",
+    };
     const md = {
         language: "markdown/gfm",
         languageOptions: { frontmatter: "yaml" },
@@ -180,51 +194,30 @@ export function buildConfig(opts = {}, texLanguage) {
             rules: {
                 "paper/stages": "error",
                 "paper/source": "error",
-                "paper/author-list": [
-                    "warn",
-                    opts.authorListCommand ? { command: opts.authorListCommand } : {},
-                ],
             },
         },
         {
             files: ["**/paper.md", "**/draft.md"],
             plugins: { markdown, paper: { rules: paperRules } },
             ...md,
-            rules: {
-                "paper/research-question": "warn",
-                "paper/typography": typographyOpt,
-            },
+            rules: prose,
         },
         {
             files: ["**/reviews/*.md"],
-            plugins: {
-                markdown,
-                review: { rules: { ...findingsCause.rules } },
-                doc: docFields,
-            },
+            plugins: { markdown, review: reviewFrontmatter },
             ...md,
-            rules: {
-                /*
-                 * 🔴 THE DEFAULT IS ENGLISH SINCE 2026-09-17. It used to be the Russian word for "Cause:" —
-                 * a Russian word in a package whose interface is English. An `error`-level rule demanded
-                 * that a person put Cyrillic into their own file, and there was nothing to change the
-                 * marker with: `causeMarker` was not threaded through the CLI at all. The only way out was
-                 * to abandon the command and assemble the ESLint config by hand — that is, the defect
-                 * pushed you onto exactly the path the utility frees you from.
-                 * The Russian marker stays EXPRESSIBLE, but now as a value, not as the default.
-                 */
-                "review/findings-cause": [
-                    "error",
-                    {
-                        minFindings: opts.minFindings ?? 3,
-                        ...(opts.causeMarker ? { causeMarker: opts.causeMarker } : {}),
-                        ...(opts.reviewSince ? { sinceCreated: opts.reviewSince } : {}),
-                    },
-                ],
-                ...(opts.docFields
-                    ? { "doc/fields": ["warn", { fields: opts.docFields }] }
-                    : {}),
-            },
+            // A review's frontmatter is a record, validated by paperlint's JSON Schema
+            // (eslint-rules/review-frontmatter.mjs).
+            rules: { "review/frontmatter": "error" },
+        },
+        {
+            // A sibling card says how much of the competing paper was read (`read:`). The cards are
+            // written by this package's analyze-sibling-paper skill; its README is an index, not a card.
+            files: ["**/siblings/*.md"],
+            ignores: ["**/siblings/README.md"],
+            plugins: { markdown, sibling: siblingFrontmatter },
+            ...md,
+            rules: { "sibling/frontmatter": "warn" },
         },
     ];
     // `.tex` only if the language loaded: it pulls in the LaTeX parser, and dying because of it on a
@@ -234,21 +227,32 @@ export function buildConfig(opts = {}, texLanguage) {
             files: ["**/paper.tex"],
             plugins: {
                 tex: { languages: { latex: texLanguage }, rules: texBuild },
-                paper: { rules: paperRules },
+                paper: { rules: texPaperRules },
+                bib: bibReachable,
             },
             language: "tex/latex",
             rules: {
-                "paper/research-question": "warn",
-                "paper/typography": typographyOpt,
+                ...prose,
+                ...REFERENCE_RULE_LEVELS,
+                "paper/figure-ref-style": "warn",
+                "bib/reachable-entry": "warn",
                 "tex/future-promise": "warn",
                 "tex/acm-frontmatter-override": "error",
                 // Silent for a paper whose paperlint.json names no venue (src/venue-rules.ts).
                 ...VENUE_RULE_LEVELS,
             },
         });
+    // 🔴 ONLY THE FILES THESE BLOCKS CLAIM ARE LINTED (src/paper-files.ts). Without this block ESLint's
+    // built-in defaults lint every .js/.mjs/.cjs under the papers directory — a paper's vendored
+    // `repro/` code failed the run with 74 parse errors and not one finding on a paper file. It goes
+    // FIRST: the `.template/` ignore below must come after its directory un-ignore to win.
+    const owners = ruleOwners(cfg);
+    cfg.unshift(scopeToOwned(ownedPatterns(cfg)));
     // The consumer's own blocks, LAST, so a later block wins — ESLint's rule. Parsed by
-    // `readConfig`; each carries the settings file's directory as its `basePath`.
-    cfg.push(...(opts.rules ?? []));
+    // `readConfig`; each carries the settings file's directory as its `basePath`. Each is split so a
+    // rule reaches only the files its plugin is registered for: `paper` is a different plugin beside
+    // PIPELINE-STATUS.md than beside paper.tex, and ESLint throws on a rule its plugin lacks.
+    cfg.push(...(opts.rules ?? []).flatMap((b) => narrowToOwners(b, owners)));
     return cfg;
 }
 /**
@@ -287,48 +291,65 @@ export async function silentOptionalRules(eslint, lintedFiles, opts) {
     return [...turnedOn].filter((id) => !reached.has(id));
 }
 /**
- * Every linted paper's `rules` from its `paperlint.json`, as ESLint blocks scoped to that paper.
- * A file that does not parse, or names a rule paperlint does not ship, stops the run with one line
- * naming the file — the same strictness as the project's own `rules`. A leftover `venue.json` is
- * not read here; `pdf/profile` and `paperlint doctor` name it.
+ * Every linted paper's rules, as ESLint blocks scoped to that paper, in two groups: what its venue
+ * preset turns on, and what its own `paperlint.json` says. The caller puts the root's blocks between
+ * them. A file that does not parse, or names a rule paperlint does not ship, stops the run with one
+ * line naming the file — the same strictness as the root's own `rules`.
  */
 export function paperRuleBlocks(paths) {
-    const papers = [...new Set(paths.flatMap((p) => [p, ...papersIn(p)]))];
-    const out = [];
+    // A FILE named on the command line belongs to the paper it sits in: that paper's settings apply.
+    const dirs = paths.map((p) => existsSync(p) && statSync(p).isFile() ? dirname(p) : p);
+    const papers = [...new Set(dirs.flatMap((p) => [p, ...papersIn(p)]))];
+    const out = { preset: [], own: [] };
     for (const dir of papers) {
         const p = paperPreset(dir, PRESET_DEPS);
         if (p.kind === "settings-problem" && p.problem.kind === "broken")
             return { ok: false, error: paperPresetProblem(dir, p) ?? dir };
-        const block = rulesOfPaper(dir, p);
-        if (!block.ok)
-            return block;
-        if (block.value)
-            out.push(block.value);
+        const blocks = rulesOfPaper(dir, p);
+        if (!blocks.ok)
+            return blocks;
+        out.preset.push(...blocks.value.preset);
+        out.own.push(...blocks.value.own);
     }
     return { ok: true, value: out };
 }
 /**
- * One paper's block: its preset chain's `rules`, then its own — later wins per rule id. A preset
- * that does not resolve contributes nothing here; `pdf/profile` reports it on the paper.
+ * One paper's blocks: its preset chain's `rules`, and its own — either `{ id: severity }` over the
+ * paper's files, or ESLint blocks with globs relative to the paper. A preset that does not resolve
+ * contributes nothing here; `pdf/profile` reports it on the paper.
  */
 function rulesOfPaper(dir, p) {
     const settings = "settings" in p ? p.settings : null;
-    if (settings === null)
-        return { ok: true, value: null };
-    const own = paperRules(dir, settings, SHIPPED_RULES);
-    if (!own.ok)
-        return own;
     const fromPreset = p.kind === "resolved"
         ? parseRuleEntries(p.preset.rules, `the venue preset ${p.preset.chain.join(" → ")} → "rules"`, SHIPPED_RULES)
         : { ok: true, value: {} };
     if (!fromPreset.ok)
         return fromPreset;
-    const rules = { ...fromPreset.value, ...(own.value ?? {}) };
+    const own = settings === null
+        ? { ok: true, value: [] }
+        : Array.isArray(settings.rules)
+            ? parseRuleBlocks(settings.rules, join(dir, CONFIG_FILE), SHIPPED_RULES, dir)
+            : ownRules(dir, settings);
+    if (!own.ok)
+        return own;
+    const scoped = (rules) => Object.keys(rules).length
+        ? [{ basePath: dir, files: PAPER_FILE_PATTERNS, rules }]
+        : [];
     return {
         ok: true,
-        value: Object.keys(rules).length
-            ? { basePath: dir, files: PAPER_FILE_PATTERNS, rules }
-            : null,
+        value: { preset: scoped(fromPreset.value), own: [...own.value] },
+    };
+}
+/** A paper's `{ id: severity }` rules, as one block over the paper's files. */
+function ownRules(dir, settings) {
+    const own = paperRules(dir, settings, SHIPPED_RULES);
+    if (!own.ok)
+        return own;
+    return {
+        ok: true,
+        value: own.value
+            ? [{ basePath: dir, files: PAPER_FILE_PATTERNS, rules: own.value }]
+            : [],
     };
 }
 /**
@@ -336,15 +357,17 @@ function rulesOfPaper(dir, p) {
  * config. A wider glob (everything under the paper) would make ESLint lint files no block gives a
  * language — `paperlint.json` itself would be parsed as JavaScript.
  */
-const PAPER_FILE_PATTERNS = [
-    ...new Set(buildConfig({}, { sentinel: "tex language" }).flatMap((b) => b.files ?? [])),
-];
+const PAPER_FILE_PATTERNS = ownedPatterns(buildConfig({}, { sentinel: "tex language" }));
 /**
- * The settings after the boundary: an unknown key is refused by name, and `rules` becomes parsed
- * config blocks. Nothing after this sees the raw object.
+ * The root `paperlint.json` after the boundary: an unknown key is refused by name, the paper
+ * defaults (`extends`, `kind`, `pdf`) are checked the way a paper's own are, and `rules` becomes
+ * parsed config blocks. Nothing after this sees the raw object.
  */
-export function parseSettings(opts, where, baseDir) {
-    const raw = opts;
+export function parseSettings(json, where, baseDir) {
+    if (typeof json !== "object" || json === null || Array.isArray(json))
+        return { ok: false, error: `${where}: must be a JSON object` };
+    const raw = json;
+    const opts = raw;
     const unknown = unknownKeys(raw);
     if (unknown.length > 0)
         return {
@@ -352,15 +375,18 @@ export function parseSettings(opts, where, baseDir) {
             error: `${where}: unknown key${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")} — ` +
                 `a typo would otherwise read as "not set". Known keys: ${Object.keys(SETTINGS_KEYS).join(", ")}`,
         };
+    const defaults = stringFields(raw);
+    if (!defaults.ok)
+        return { ok: false, error: `${where}: ${defaults.error}` };
     const rules = parseRuleBlocks(raw["rules"], where, SHIPPED_RULES, baseDir);
     if (!rules.ok)
         return rules;
     return { ok: true, value: { ...opts, rules: rules.value } };
 }
 /**
- * The directory ESLint runs from. ESLint ignores every file outside it (#48), and
- * `paper/typography` reads its debt keys relative to it — keys the config writes from its own
- * directory. So: the deepest directory holding the config's directory and every path. With the
+ * The directory ESLint runs from. ESLint ignores every file outside it (#48), and the consumer's
+ * `rules` globs are written relative to the config's directory. So: the deepest directory holding
+ * the config's directory and every path. With the
  * papers inside the config's directory, that is the config's directory itself.
  */
 const lintRoot = (home, paths) => commonDir([home, ...paths]);
@@ -378,6 +404,7 @@ export function parseArgs(argv) {
         paths: [],
         config: null,
         json: false,
+        fix: false,
         all: false,
         dryRun: false,
         check: false,
@@ -411,6 +438,8 @@ export function parseArgs(argv) {
             continue;
         if (a === "--json")
             out.json = true;
+        else if (a === "--fix")
+            out.fix = true;
         else if (a === "--all")
             out.all = true;
         else if (a === "--dry-run")
@@ -444,7 +473,6 @@ export function parseArgs(argv) {
     }
     return out;
 }
-export const PKG_NAME = "package.json";
 /**
  * This package's own version, from the `package.json` beside `src/` and `dist/` alike. `init` pins
  * the CI action to its release tag; an unreadable manifest yields `undefined`, and init then keeps
@@ -459,119 +487,61 @@ function ownVersion() {
         return undefined;
     }
 }
-/**
- * 🔴 THE CLI READS `package.json`, THE ONE DECLARATION. `paperlint init` writes the settings under
- * the `package.json` key that the three hooks and `eslint-rules` already read; the CLI reads the
- * same file, so the install and the check cannot look at different files (issue #33,
- * `docs/install.md`).
- *
- * The walk goes up to the filesystem root, the way eslint, prettier and tsc find theirs, so a run
- * from inside one paper sees the same settings as a run from the repository root.
- */
-export function findConfig(startDir) {
-    let dir = resolve(startDir);
-    for (;;) {
-        const pkg = join(dir, PKG_NAME);
-        if (existsSync(pkg) && declaresSettings(pkg))
-            return pkg;
-        const up = dirname(dir);
-        if (up === dir)
-            return null;
-        dir = up;
-    }
-}
-/**
- * A `package.json` WITHOUT the key is not a declaration and must not stop the walk — every
- * project on the way up has one, so stopping there would make the search find nothing, always.
- * An unparsable one is treated the same way here; `paperlint doctor` is the command that reports it.
- */
-const declaresSettings = (pkgPath) => {
-    try {
-        const d = declaredSettings(JSON.parse(readFileSync(pkgPath, "utf8")));
-        return d.settings !== undefined || d.conflict !== null;
-    }
-    catch {
-        return false;
-    }
-};
 /**
  * Reading the config, ONE reader for all commands. Pulled out of `run()` the moment a second
  * command needed the same config (`build`): two copies of this block would have drifted apart on
  * the very first edit — exactly the class that already cost us the empty-set guard in two places.
  *
- * @returns `{ opts, configPath }` on success, or `{ code }` — and then the caller exits with it.
+ * 🔴 THE CONFIG FINDS ITSELF: the project root is the nearest directory up from `cwd` with a root
+ * `paperlint.json`, else with a `package.json`, else `cwd` (`findProjectRoot`). The file is
+ * optional — without one every setting has its default, and papers are in `papers/`. An explicit
+ * `--config` beats the discovered one: it was named out loud, and a substitution is never silent.
+ *
+ * @returns `{ opts, configPath, root }` on success, or `{ code }` — and then the caller exits with it.
  */
 export function readConfig(a, { log = console.log, err = console.error, cwd = process.cwd(), } = {}) {
-    // 🔴 THE CONFIG FINDS ITSELF. An explicit `--config` beats the discovered one — it was named out
-    // loud, and a substitution is never silent. Either way the file has the shape of a
-    // `package.json`: the settings sit under the key.
-    const configPath = a.config ?? findConfig(cwd);
-    if (a.config && !existsSync(a.config)) {
+    if (a.config && !existsSync(resolve(cwd, a.config))) {
         err(`config file not found: ${a.config}`);
         return { code: 2 };
     }
-    let opts = {};
-    let legacyKey = false;
-    if (configPath) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-        let parsed;
-        try {
-            parsed = JSON.parse(readFileSync(configPath, "utf8"));
-        }
-        catch (e) {
-            err(`${configPath} is not valid JSON: ${e.message}`);
-            return { code: 2 };
-        }
-        const d = declaredSettings(parsed);
-        if (d.conflict !== null) {
-            err(d.conflict);
-            return { code: 2 };
-        }
-        opts = (d.settings ?? {});
-        legacyKey = d.legacy;
-        // The discovered config is NAMED out loud. Otherwise a run from someone else's directory picks
-        // up someone else's file and does not say so — and a typography-debt mismatch looks like a finding.
-        //
-        // 🔴 IN `--json` MODE — TO stderr. Machine output must be ONE parsable document: a line before
-        // the array breaks any `| jq`, and it breaks it for the consumer, not for us. Caught not by a
-        // test but by an attempt to wire our own action to this output; in the harness I first WORKED
-        // AROUND this line (stripped the first line before JSON.parse) — that is, the workaround hid
-        // the defect exactly where it should have been shouting.
-        (a.json ? err : log)(`config: ${relative(cwd, configPath) || PKG_NAME}`);
-        if (legacyKey)
-            (a.json ? err : log)(`  ⚠ ${LEGACY_KEY_MESSAGE}`);
+    const root = a.config
+        ? dirname(resolve(cwd, a.config))
+        : findProjectRoot(cwd);
+    const found = a.config ? resolve(cwd, a.config) : join(root, CONFIG_FILE);
+    const configPath = existsSync(found) ? found : null;
+    if (configPath === null)
+        return { opts: {}, configPath, root };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(configPath, "utf8"));
     }
-    // The old field name is refused before anything else is read from the settings: falling back
-    // to it would keep it working forever, and this package has no released users to migrate.
-    const where = `${configPath ? basename(configPath) : PKG_NAME} → "${legacyKey ? LEGACY_CONFIG_KEY : CONFIG_KEY}"`;
-    const renamed = configPath ? renamedFieldMessage(opts, where) : null;
-    if (renamed) {
-        err(renamed);
+    catch (e) {
+        err(`${configPath} is not valid JSON: ${e.message}`);
         return { code: 2 };
     }
-    if (configPath) {
-        const parsed = parseSettings(opts, where, dirname(resolve(cwd, configPath)));
-        if (!parsed.ok) {
-            err(parsed.error);
-            return { code: 2 };
-        }
-        opts = parsed.value;
-    }
-    // 🔴 THE PAPERS DIRECTORY IS A REQUIRED FIELD. The papers directory is the one thing without which the tool
-    // does not know what it works on, and the one thing that cannot be guessed: a default of "." runs
-    // the rules over the whole checkout and exits green over a scope nobody chose.
-    if (configPath && !hasPapers(opts)) {
-        err(`${configPath} must declare \`${PAPERS_DIR_FIELD}\` — the directory your papers live in, e.g.\n` +
-            `  { "${CONFIG_KEY}": { "${PAPERS_DIR_FIELD}": "papers" } }\n` +
-            `It is the one thing this tool cannot guess. \`npx paperlint init\` writes it for you.`);
+    // The discovered config is NAMED out loud. Otherwise a run from someone else's directory picks
+    // up someone else's file and does not say so — and its settings then look like findings.
+    //
+    // 🔴 IN `--json` MODE — TO stderr. Machine output must be ONE parsable document: a line before
+    // the array breaks any `| jq`, and it breaks it for the consumer, not for us.
+    (a.json ? err : log)(`config: ${relative(cwd, configPath) || CONFIG_FILE}`);
+    const settings = parseSettings(parsed, relative(cwd, configPath) || CONFIG_FILE, root);
+    if (!settings.ok) {
+        err(settings.error);
         return { code: 2 };
     }
-    return { opts, configPath };
+    return { opts: settings.value, configPath, root };
 }
-/** The papers directory field of the settings, read by its one declared name. */
+/** The papers directory field of the settings, read by its one declared name; the default when absent. */
 export function papersDirOf(opts) {
-    return opts[PAPERS_DIR_FIELD];
+    const declared = opts[PAPERS_DIR_FIELD];
+    return declared === undefined ? DEFAULT_PAPERS_ROOT : declared;
 }
+/** The error for a papers directory that is missing or holds no paper. */
+export const noPapersMessage = (dir) => `no papers in ${dir}/ — create one with \`npx paperlint new <name>\`, or set "${PAPERS_DIR_FIELD}" ` +
+    `in ${CONFIG_FILE} if your papers live elsewhere`;
+/** The papers directories of a read config, absolute: each relative to the project root. */
+export const papersRoots = (cfg) => toPaths(papersDirOf(cfg.opts)).map((rel) => resolve(cfg.root, rel));
 /** The papers directory may be one directory or several; both spellings normalise to a list. */
 export function toPaths(papers) {
     if (typeof papers === "string")
@@ -580,7 +550,6 @@ export function toPaths(papers) {
         return papers.filter((x) => typeof x === "string" && x.trim());
     return [];
 }
-const hasPapers = (opts) => toPaths(papersDirOf(opts)).length > 0;
 /**
  * `paperlint hook <name>` — run an editor hook. It exists for ONE thing: so that the wiring does not
  * address the runtime from the project root.
@@ -684,11 +653,10 @@ async function runNew(a, { log, err, cwd, ask = askOnTerminal, }) {
     const cfg = readConfig({ ...a, json: false }, { log: () => { }, err, cwd });
     if (cfg.code !== undefined)
         return cfg.code;
-    const roots = toPaths(papersDirOf(cfg.opts)).map((rel) => resolve(dirname(cfg.configPath ?? cwd), rel));
+    const roots = papersRoots(cfg);
     const papersRoot = roots[0];
-    if (!cfg.configPath || papersRoot === undefined) {
-        err(`no papers directory is declared, so there is nowhere to put \`${name}\`.\n` +
-            `Run \`npx paperlint init\` first — it declares the directory in package.json.`);
+    if (papersRoot === undefined) {
+        err(`"${PAPERS_DIR_FIELD}" names no directory, so there is nowhere to put \`${name}\`.`);
         return 2;
     }
     if (roots.length > 1)
@@ -706,12 +674,7 @@ async function runBuild(a, { log, err, cwd, }) {
     const cfg = readConfig(a, { log, err, cwd });
     if (cfg.code !== undefined)
         return cfg.code;
-    const { opts, configPath } = cfg;
-    // The key that used to name the scripts to run. It is read by nothing now; saying so beats a
-    // setting that silently stopped doing anything.
-    if (opts.buildScripts !== undefined)
-        log(`note: "buildScripts" in ${relative(cwd, configPath ?? "") || "the settings"} is ignored — paperlint builds the paper itself`);
-    const roots = toPaths(papersDirOf(opts)).map((rel) => resolve(configPath ? dirname(configPath) : cwd, rel));
+    const roots = papersRoots(cfg);
     let targets;
     if (a.all) {
         targets = roots.flatMap((r) => papersIn(r));
@@ -735,6 +698,7 @@ async function runBuild(a, { log, err, cwd, }) {
         cwd,
         dryRun: a.dryRun,
         log,
+        checkReferences: onlineReferences,
         engine: () => engineEnv(targets, a, { log, err }),
     });
     if (out.kind === "no-engine")
@@ -765,9 +729,7 @@ export function toolchainTex(cwd) {
         err: () => { },
         cwd,
     });
-    const roots = cfg.code === undefined
-        ? toPaths(papersDirOf(cfg.opts)).map((rel) => resolve(dirname(cfg.configPath ?? cwd), rel))
-        : [];
+    const roots = cfg.code === undefined ? papersRoots(cfg) : [];
     const chains = roots
         .flatMap((r) => papersIn(r))
         .map((dir) => paperPreset(dir, PRESET_DEPS))
@@ -820,6 +782,46 @@ function hostBanalInstaller() {
     });
     return banalInstaller({ ...ports, download }, s);
 }
+/** `paperlint init`: its flags checked here, the install itself in `init.ts`. */
+async function runInit(a, { log, err, cwd, }) {
+    // Deferred, not implemented: named and refused, rather than read as the directory argument.
+    if (a.hooksMode !== null) {
+        err(`--hooks=${a.hooksMode} is not implemented. init writes the hooks into .claude/settings.json ` +
+            `(shared, committed) or, with --no-hooks, nowhere.`);
+        return 2;
+    }
+    if (a.format !== null && !isFormat(a.format)) {
+        err(`--format must be one of ${FORMATS.join(", ")} — got \`${a.format}\``);
+        return 2;
+    }
+    return await init(a.paths[0] ?? ".", {
+        log,
+        err,
+        cwd,
+        version: ownVersion(),
+        yes: a.yes,
+        hooks: !a.noHooks,
+        paper: a.paper,
+        format: isFormat(a.format) ? a.format : null,
+        createPaper: (papersRoot, name, format) => createPaperAt(papersRoot, name, format, { log, err, cwd }),
+        tex: {
+            installed: () => cachedTree(cacheRoot(process.env)) !== null,
+            install: () => runToolchain({
+                check: false,
+                log,
+                err,
+                banal: hostBanalInstaller(),
+                tex: toolchainTex(resolve(cwd, a.paths[0] ?? ".")),
+            }),
+        },
+        resolveCliPapers: (root) => {
+            const read = readConfig({ ...a, config: null }, { log: () => { }, err: () => { }, cwd: root });
+            return read.code === undefined
+                ? (toPaths(papersDirOf(read.opts))[0] ?? null)
+                : null;
+        },
+    });
+}
 export async function run(argv, { log = console.log, err = console.error, cwd = process.cwd(), } = {}) {
     const a = parseArgs(argv);
     // The refusal must come FIRST: behind a flag without a value there is usually a typo, or a
@@ -838,35 +840,8 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
     // `init` asks the CLI's OWN reader what it would lint, so the two sides `doctor` compares are
     // not two implementations of the same question. A second resolver here is the defect the
     // comparison exists to catch.
-    if (a.cmd === "init") {
-        // Deferred, not implemented: named and refused, rather than read as the directory argument.
-        if (a.hooksMode !== null) {
-            err(`--hooks=${a.hooksMode} is not implemented. init writes the hooks into .claude/settings.json ` +
-                `(shared, committed) or, with --no-hooks, nowhere.`);
-            return 2;
-        }
-        if (a.format !== null && !isFormat(a.format)) {
-            err(`--format must be one of ${FORMATS.join(", ")} — got \`${a.format}\``);
-            return 2;
-        }
-        return await init(a.paths[0] ?? ".", {
-            log,
-            err,
-            cwd,
-            version: ownVersion(),
-            yes: a.yes,
-            hooks: !a.noHooks,
-            paper: a.paper,
-            format: isFormat(a.format) ? a.format : null,
-            createPaper: (papersRoot, name, format) => createPaperAt(papersRoot, name, format, { log, err, cwd }),
-            resolveCliPapers: (root) => {
-                const read = readConfig({ ...a, config: null }, { log: () => { }, err: () => { }, cwd: root });
-                return read.code === undefined
-                    ? (toPaths(papersDirOf(read.opts))[0] ?? null)
-                    : null;
-            },
-        });
-    }
+    if (a.cmd === "init")
+        return await runInit(a, { log, err, cwd });
     // `doctor` reads the config but must NOT die on a broken one — reporting that the config is
     // broken is precisely its job. So a failed read becomes "the CLI would lint nothing", which is
     // what it prints, rather than an early exit that tells the reader nothing about the hooks.
@@ -894,39 +869,44 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
     const cfg = readConfig(a, { log, err, cwd });
     if (cfg.code !== undefined)
         return cfg.code;
-    const { opts, configPath } = cfg;
+    const { opts, root } = cfg;
     // A command-line argument OVERRIDES the config: one paper out of the corpus gets linted without
     // editing a file.
     //
-    // 🔴 A path FROM THE CONFIG is resolved relative to the CONFIG'S DIRECTORY, not the current one.
-    // Otherwise walking up is pointless: from `papers/aisec-2026` the file would be found, but
-    // `"papersDir": "papers"` would point at `papers/aisec-2026/papers`, which does not exist — and the
-    // run would fail with "nothing found" where everything is in place. A command-line argument stays
+    // 🔴 A path FROM THE CONFIG is resolved relative to the PROJECT ROOT, not the current directory.
+    // Otherwise walking up is pointless: from `papers/aisec-2026` the root would be found, but
+    // `"papersDir": "papers"` would point at `papers/aisec-2026/papers`. A command-line argument stays
     // relative to the current directory: it was typed here and now.
     //
     // Both kinds end up ABSOLUTE: ESLint below runs from `lintRoot`, not from here, and would resolve a
     // relative argument against the wrong directory.
-    const paths = a.paths.length > 0
-        ? a.paths.map((p) => resolve(cwd, p))
-        : toPaths(papersDirOf(opts)).map((rel) => resolve(dirname(configPath ?? cwd), rel));
+    const paths = a.paths.length > 0 ? a.paths.map((p) => resolve(cwd, p)) : papersRoots(cfg);
     if (paths.length === 0) {
-        err(`nothing to lint: no path was given and no "${CONFIG_KEY}" key was found in a ${PKG_NAME}.\n` +
-            `Run \`npx paperlint init\` here, or pass the directory: \`paperlint lint papers\`.`);
+        err(`nothing to lint: "${PAPERS_DIR_FIELD}" names no directory. Pass one: \`paperlint lint papers\`.`);
         return 2;
     }
+    // 🔴 NO PAPERS WHERE THE CONFIG POINTS IS AN ERROR, NOT A CLEAN RUN. With the default in play the
+    // directory may simply not exist yet; a run over nothing would be green and say nothing.
+    if (a.paths.length === 0) {
+        const empty = paths.find((p) => papersIn(p).length === 0);
+        if (empty !== undefined) {
+            err(noPapersMessage(relative(cwd, empty) || "."));
+            return 2;
+        }
+    }
     // 🔴 STRUCTURE IS CHECKED BEFORE ESLint AND SEPARATELY FROM IT. A rule is invoked for the file
     // handed to it; a missing file is never handed over, so no rule at all can report the absence —
     // a directory without `PIPELINE-STATUS.md` simply gets not a single rule and reports clean. The
     // analysis of why a structure plugin for ESLint does not cure this is in `structure.mjs`.
     const structure = checkStructure(paths, opts.structure, { cwd });
-    // Each paper's own `rules` (its paperlint.json) go after paperlint's blocks and BEFORE the
-    // project's, so the project's package.json still has the last word.
+    // The order, most general first so the most specific wins (ESLint: a later block wins): each
+    // paper's venue preset → the root paperlint.json → the paper's own paperlint.json.
     const papers = paperRuleBlocks(paths);
     if (!papers.ok)
         return (err(papers.error), 2);
     const withPapers = {
         ...opts,
-        rules: [...papers.value, ...(opts.rules ?? [])],
+        rules: [...papers.value.preset, ...(opts.rules ?? []), ...papers.value.own],
     };
     let texLanguage = null;
     try {
@@ -938,10 +918,16 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
         /* without a LaTeX parser we work over markdown */
     }
     const eslint = new ESLint({
-        cwd: lintRoot(configPath ? dirname(resolve(cwd, configPath)) : cwd, paths),
+        cwd: lintRoot(root, paths),
         overrideConfigFile: true,
         overrideConfig: buildConfig(withPapers, texLanguage),
+        fix: a.fix,
     });
+    const unowned = await firstUnownedFile(eslint, paths);
+    if (unowned !== null) {
+        err(`${relative(cwd, unowned) || unowned} is not a file paperlint lints — it lints ${PAPER_FILE_PATTERNS.join(", ")}`);
+        return 2;
+    }
     // 🔴 ESLint THROWS on an empty set (`NoFilesFoundError`) — the guard below simply never got
     // reached, which is what the very first run over an empty directory showed: instead of a clear
     // message a stack from the depths of eslint-helpers.js flew out. A failure stays a failure, but
@@ -952,13 +938,14 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
         results = await eslint.lintFiles(paths);
     }
     catch (e) {
-        const fail = e;
-        if (fail?.messageTemplate === "file-not-found" ||
-            /No files matching/i.test(fail?.message ?? ""))
+        if (isEmptySet(e))
             results = [];
         else
             throw e;
     }
+    // `--fix` writes what the rules fixed; the report below is what is LEFT.
+    if (a.fix)
+        await ESLint.outputFixes(results);
     // 🔴 THE GUARD AGAINST A GREEN ZERO, the same one as in action.yml and for the same reason:
     // ESLint exits zero when there are no findings, and "no findings" is byte-for-byte
     // indistinguishable from "not a single rule got a single file". A rule whose glob did not match
@@ -971,10 +958,35 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
         a,
         log,
         err,
-        where: relative(cwd, dirname(resolve(cwd, configPath ?? "."))) || ".",
+        where: relative(cwd, root) || ".",
         opts: withPapers,
     });
 }
+/**
+ * The first path that is a FILE paperlint does not lint, or null. ESLint would answer such a file
+ * with a warning result ("File ignored because of a matching ignore pattern"), which counts as a
+ * linted file and turns a run over nothing into a green one. The question is asked of ESLint's
+ * own matcher, against the same scope that decides what a directory yields.
+ */
+async function firstUnownedFile(eslint, paths) {
+    for (const p of paths)
+        if (existsSync(p) &&
+            statSync(p).isFile() &&
+            (await eslint.isPathIgnored(p)))
+            return p;
+    return null;
+}
+/**
+ * ESLint's refusals of an empty set: nothing matched (`file-not-found`), or everything that matched
+ * is outside paperlint's scope (`all-matched-files-ignored` — a papers directory holding only
+ * vendored scripts). Both mean "nothing was linted", which the caller reports itself.
+ */
+const isEmptySet = (e) => {
+    const fail = e;
+    return (fail?.messageTemplate === "file-not-found" ||
+        fail?.messageTemplate === "all-matched-files-ignored" ||
+        /No files matching/i.test(fail?.message ?? ""));
+};
 /**
  * The end of `paperlint lint`: refuse an optional rule that reached no paper, print the findings, and
  * decide the exit code. Pulled out of `run` so each question has its own function.