paperlint 2.1.0 → 3.0.0

package/src/cli.ts

@@ -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, type Linter } 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";
@@ -46,12 +44,24 @@ import {
 } from "./structure.ts";
 import { buildPapers, papersIn, anyFailed, remedyFor, MAIN } from "./build.ts";
 import { prepareEngine } from "./build-engine.ts";
-import { runToolchain } from "./toolchain.ts";
+import { cacheRoot, cachedTree, runToolchain } from "./toolchain.ts";
 import { banalInstaller, parseBanalSettings } from "./adapters/banal/index.ts";
 import { curlDownload } from "./adapters/curl/index.ts";
 import { hostDirs, nodeAdapters, nodeFiles } from "./adapters/node/index.ts";
 import { VENUE_RULE_LEVELS, venueRules } from "./venue-rules.ts";
-import { paperRules } from "./paper-settings.ts";
+import {
+  paperRules,
+  stringFields,
+  type PaperSettings,
+} from "./paper-settings.ts";
+import { referenceRules, REFERENCE_RULE_LEVELS } from "./reference-rules.ts";
+import { onlineReferences } from "./adapters/references/index.ts";
+import {
+  narrowToOwners,
+  ownedPatterns,
+  ruleOwners,
+  scopeToOwned,
+} from "./paper-files.ts";
 import {
   paperPreset,
   paperPresetProblem,
@@ -78,13 +88,11 @@ import {
 // 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,
+  CONFIG_FILE,
+  DEFAULT_PAPERS_ROOT,
   PAPERS_DIR_FIELD,
   SETTINGS_KEYS,
-  declaredSettings,
-  renamedFieldMessage,
+  findProjectRoot,
 } from "../lib/paper-config.mjs";
 import {
   parseRuleBlocks,
@@ -93,6 +101,7 @@ import {
   unknownKeys,
   type Parsed,
   type RuleBlock,
+  type RuleEntry,
 } from "./rules-config.ts";
 export { init };
 export { nextSteps } from "./init.ts";
@@ -106,9 +115,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 reviewFrontmatter from "../eslint-rules/review-frontmatter.mjs";
 // @ts-expect-error — an ESLint rule in .mjs, it has no types
-import findingsCause from "../eslint-rules/review-findings-cause.mjs";
+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";
 
@@ -127,7 +138,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
@@ -143,48 +157,46 @@ 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:
-
-  "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" } } ]
-  }
+settings — paperlint.json, at two levels, one schema. Both are optional.
 
-  "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.
+  paperlint.json (the project root, beside package.json) — found by walking up from the
+  current directory. \`--config\` names another file of the same shape.
+
+    {
+      "papersDir": "papers",
+      "rules": [ { "files": ["papers/my-paper/**"],
+                   "rules": { "pdf/last-page-balance": "error" } } ]
+    }
+
+  "papersDir" defaults to "papers". "extends", "kind" and "pdf" here are defaults for every
+  paper. "papersDir", "structure" and the skills' keys are allowed only here.
 
-per paper — <paper>/paperlint.json (it was venue.json before 2.1.0; \`npx paperlint init\` moves it):
+  <papersDir>/<paper>/paperlint.json — one paper, merged over the root file:
 
-  { "extends": "paperlint:aisec", "kind": "research", "rules": { "pdf/last-page-balance": "error" } }
+    { "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. */
@@ -193,7 +205,17 @@ export function buildConfig(
   texLanguage: unknown,
 ): unknown[] {
   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" },
@@ -228,51 +250,30 @@ export function buildConfig(
       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" },
     },
   ];
 
@@ -283,21 +284,32 @@ export function buildConfig(
       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;
 }
 
@@ -359,34 +371,42 @@ export async function silentOptionalRules(
 }
 
 /**
- * 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: readonly string[]): Parsed<RuleBlock[]> {
-  const papers = [...new Set(paths.flatMap((p) => [p, ...papersIn(p)]))];
-  const out: RuleBlock[] = [];
+export function paperRuleBlocks(
+  paths: readonly string[],
+): Parsed<{ preset: RuleBlock[]; own: RuleBlock[] }> {
+  // 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: [] as RuleBlock[], own: [] as RuleBlock[] };
   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: string, p: PaperPreset): Parsed<RuleBlock | null> {
+function rulesOfPaper(
+  dir: string,
+  p: PaperPreset,
+): Parsed<{ preset: RuleBlock[]; own: RuleBlock[] }> {
   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(
@@ -396,12 +416,40 @@ function rulesOfPaper(dir: string, p: PaperPreset): Parsed<RuleBlock | null> {
         )
       : { ok: true as const, value: {} };
   if (!fromPreset.ok) return fromPreset;
-  const rules = { ...fromPreset.value, ...(own.value ?? {}) };
+  const own =
+    settings === null
+      ? { ok: true as const, 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: Record<string, RuleEntry>): RuleBlock[] =>
+    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: string,
+  settings: PaperSettings,
+): Parsed<readonly RuleBlock[]> {
+  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 }]
+      : [],
   };
 }
 
@@ -410,24 +458,24 @@ function rulesOfPaper(dir: string, p: PaperPreset): Parsed<RuleBlock | null> {
  * 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: string[] = [
-  ...new Set(
-    buildConfig({}, { sentinel: "tex language" }).flatMap(
-      (b) => (b as { files?: string[] }).files ?? [],
-    ),
-  ),
-];
+const PAPER_FILE_PATTERNS: string[] = 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: PaperlintConfig,
+  json: unknown,
   where: string,
   baseDir: string,
 ): Parsed<PaperlintConfig> {
-  const raw = opts as Record<string, unknown>;
+  if (typeof json !== "object" || json === null || Array.isArray(json))
+    return { ok: false, error: `${where}: must be a JSON object` };
+  const raw = json as Record<string, unknown>;
+  const opts = raw as PaperlintConfig;
   const unknown = unknownKeys(raw);
   if (unknown.length > 0)
     return {
@@ -436,15 +484,17 @@ export function parseSettings(
         `${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: string, paths: readonly string[]): string =>
@@ -467,6 +517,7 @@ export function parseArgs(argv: readonly string[]): Args {
     paths: [],
     config: null,
     json: false,
+    fix: false,
     all: false,
     dryRun: false,
     check: false,
@@ -498,6 +549,7 @@ export function parseArgs(argv: readonly string[]): Args {
     const a = rest[i];
     if (a === undefined) 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") out.dryRun = true;
     else if (a === "--check") out.check = true;
@@ -521,8 +573,6 @@ export function parseArgs(argv: readonly string[]): Args {
   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
@@ -539,46 +589,17 @@ function ownVersion(): string | 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: string): string | null {
-  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: string): boolean => {
-  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: Args,
@@ -592,85 +613,60 @@ export function readConfig(
     cwd?: string;
   } = {},
 ): ConfigRead {
-  // 🔴 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: PaperlintConfig = {};
-  let legacyKey = false;
-  if (configPath) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-    let parsed: any;
-    try {
-      parsed = JSON.parse(readFileSync(configPath, "utf8"));
-    } catch (e) {
-      err(`${configPath} is not valid JSON: ${(e as Error).message}`);
-      return { code: 2 };
-    }
-    const d = declaredSettings(parsed);
-    if (d.conflict !== null) {
-      err(d.conflict);
-      return { code: 2 };
-    }
-    opts = (d.settings ?? {}) as PaperlintConfig;
-    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}`);
-  }
-
-  // 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);
+  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: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (e) {
+    err(`${configPath} is not valid JSON: ${(e as Error).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: PaperlintConfig): unknown {
-  return (opts as Record<string, unknown>)[PAPERS_DIR_FIELD];
+  const declared = (opts as Record<string, unknown>)[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: string): string =>
+  `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: {
+  opts: PaperlintConfig;
+  root: string;
+}): string[] =>
+  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: unknown): string[] {
   if (typeof papers === "string") return papers.trim() ? [papers.trim()] : [];
@@ -679,9 +675,6 @@ export function toPaths(papers: unknown): string[] {
   return [];
 }
 
-const hasPapers = (opts: PaperlintConfig): boolean =>
-  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.
@@ -828,14 +821,11 @@ async function runNew(
   }
   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) {
+  if (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.`,
+      `"${PAPERS_DIR_FIELD}" names no directory, so there is nowhere to put \`${name}\`.`,
     );
     return 2;
   }
@@ -863,16 +853,7 @@ async function runBuild(
 ): Promise<number> {
   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) {
@@ -900,6 +881,7 @@ async function runBuild(
     cwd,
     dryRun: a.dryRun,
     log,
+    checkReferences: onlineReferences,
     engine: () => engineEnv(targets, a, { log, err }),
   });
   if (out.kind === "no-engine") return 1;
@@ -931,12 +913,7 @@ export function toolchainTex(cwd: string): TexRequirements {
     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))
@@ -1005,6 +982,61 @@ function hostBanalInstaller(): ToolInstaller {
   return banalInstaller({ ...ports, download }, s);
 }
 
+/** `paperlint init`: its flags checked here, the install itself in `init.ts`. */
+async function runInit(
+  a: Args,
+  {
+    log,
+    err,
+    cwd,
+  }: { log: typeof console.log; err: typeof console.error; cwd: string },
+): Promise<number> {
+  // 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: string): string | null => {
+      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: readonly string[],
   {
@@ -1036,43 +1068,7 @@ export async function run(
   // `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: string): string | null => {
-        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.
@@ -1102,45 +1098,48 @@ export async function run(
 
   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),
-        );
+    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\`.`,
+      `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: unknown = null;
@@ -1153,11 +1152,20 @@ export async function run(
   }
 
   const eslint = new ESLint({
-    cwd: lintRoot(configPath ? dirname(resolve(cwd, configPath)) : cwd, paths),
+    cwd: lintRoot(root, paths),
     overrideConfigFile: true,
     overrideConfig: buildConfig(withPapers, texLanguage) as Linter.Config[],
+    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
@@ -1167,15 +1175,13 @@ export async function run(
   try {
     results = await eslint.lintFiles(paths);
   } catch (e) {
-    const fail = e as { messageTemplate?: string; message?: string } | null;
-    if (
-      fail?.messageTemplate === "file-not-found" ||
-      /No files matching/i.test(fail?.message ?? "")
-    )
-      results = [];
+    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
@@ -1191,11 +1197,45 @@ export async function run(
     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: ESLint,
+  paths: readonly string[],
+): Promise<string | null> {
+  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: unknown): boolean => {
+  const fail = e as { messageTemplate?: string; message?: string } | null;
+  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.