paperlint 2.1.0 → 3.1.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,20 +36,23 @@ 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 { paperPreset, paperPresetProblem, } from "./presets.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, presetProblemText, resolvePreset, shippedPresets, SHIPPED_PREFIX, } from "./presets.js";
 import { mergeRequirements, declaredUnion, requirementsFor, NO_REQUIREMENTS, } from "./tex-requirements.js";
 import { doctor } from "./doctor.js";
 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,17 +65,21 @@ 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";
+/** The shipped venue presets, read from the package's venues directory — the one list. */
+const SHIPPED_VENUES = () => shippedPresets(packageVenuesDir());
 const USAGE = `paperlint — machine-checkable gates for a paper kept in git
 
   npx paperlint init [dir]            set the project up: detect the papers directory, declare it
                                       in package.json, link the skills, wire the hooks into
                                       .claude/settings.json, offer the CI step, report what is missing
-  npx paperlint new <name> [--format tex|md]
+  npx paperlint new <name> [--venue <preset>] [--kind <kind>] [--format tex|md]
                                       create <papers>/<name>/ from the template; never overwrites,
                                       on an existing folder adds only the missing files, then lints it
   npx paperlint lint [paths…]         run every rule over your papers
@@ -84,7 +89,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
@@ -99,54 +107,71 @@ init:
   --paper <name>      create this paper too (without a human, the only way init creates one)
   --format tex|md     the new paper's source format; default tex
 
+new:
+  --venue <preset>    the venue preset, written as "extends" into the paper's paperlint.json:
+                      a shipped one (${SHIPPED_VENUES().join(", ")}), or a path to your
+                      own preset starting with ./ or ../, relative to where you run the command.
+                      On a terminal without --venue, new asks; "none" leaves it unset
+  --kind <kind>       the paper's kind at that venue (its page limit), e.g. short — one of the
+                      preset's kinds; needs --venue
+  --format tex|md     the 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" names a venue preset: paperlint:<name> (shipped: acm-sigconf, agenticdev, aisec, realm)
+    { "extends": "paperlint:aisec", "kind": "research", "rules": { "pdf/last-page-balance": "error" } }
+
+  "extends" names a venue preset: paperlint:<name> (shipped: ${SHIPPED_VENUES().join(", ")})
   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 +205,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 +238,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;
 }
 /**
@@ -256,6 +271,54 @@ export function buildConfig(opts = {}, texLanguage) {
  * config rather than listed again. `@eslint/markdown` is a dependency's plugin, not paperlint's.
  */
 export const SHIPPED_RULES = shippedRuleIds(buildConfig({}, { sentinel: "tex language" }), [markdown]);
+/**
+ * Every plugin paperlint's config registers, ONE object per name, read off that config. In it one
+ * name is bound to different objects in different blocks (`paper` beside `PIPELINE-STATUS.md` is
+ * not `paper` beside `paper.tex`); here their rules are merged, so a config that lints any paper
+ * file knows every rule id. `@eslint/markdown` is a dependency's plugin and is left out. The LaTeX
+ * language rides on `tex` when `texLanguage` is given, and that is how a consumer registers it: a
+ * second `tex` plugin of its own is refused by ESLint ("Cannot redefine plugin "tex"", measured
+ * with and without the language here). Without it, `tex` carries rules only — for a config that
+ * lints markdown papers alone.
+ */
+export function rulePlugins(texLanguage) {
+    const out = {};
+    for (const block of buildConfig({}, texLanguage ?? { sentinel: "tex" }))
+        for (const [name, plugin] of Object.entries(block.plugins ?? {}))
+            if (plugin !== markdown)
+                out[name] = { rules: { ...out[name]?.rules, ...plugin.rules } };
+    if (out["tex"] && texLanguage !== undefined)
+        return {
+            ...out,
+            tex: { ...out["tex"], languages: { latex: texLanguage } },
+        };
+    return out;
+}
+/**
+ * A flat-config fragment for a consumer's OWN ESLint run over paper files (#104): every rule
+ * paperlint ships, registered and turned off. Without it a `% eslint-disable-next-line
+ * paper/leading-zero -- why` — the documented escape hatch — fails that run with "Definition for
+ * rule 'paper/leading-zero' was not found". Off, because `paperlint lint` is where they run.
+ *
+ * The second block is not optional, and it is measured: a directive naming a rule that is off
+ * suppresses nothing, so ESLint reports it as an unused directive (a warning by default, an error
+ * under `reportUnusedDisableDirectives: "error"`). On the files paperlint lints that report is
+ * switched off in THIS run — `paperlint lint` still reports a directive that silences nothing.
+ */
+export function rulesOff(texLanguage) {
+    return [
+        {
+            name: "paperlint/rules-off",
+            plugins: rulePlugins(texLanguage),
+            rules: Object.fromEntries([...SHIPPED_RULES].map((id) => [id, "off"])),
+        },
+        {
+            name: "paperlint/rules-off/directives",
+            files: PAPER_FILE_PATTERNS,
+            linterOptions: { reportUnusedDisableDirectives: "off" },
+        },
+    ];
+}
 /** Whether a rule entry (`"error"`, `2`, `["warn", {…}]`) turns the rule on. */
 const isOn = (entry) => {
     const sev = Array.isArray(entry) ? entry[0] : entry;
@@ -270,81 +333,103 @@ export const OPTIONAL_RULES = new Set([...SHIPPED_RULES].filter((id) => !buildCo
  * 🔴 AN OPTIONAL RULE THAT IS ON AND REACHES NO PAPER IS A GREEN ZERO. A `files` glob that matches
  * nothing — a typo, a path relative to the wrong directory — leaves the rule never invoked, and a
  * rule that never runs reports exactly like a rule that passed. So for every optional rule the
- * consumer turned on, some linted `paper.tex` must actually have it enabled; the ones none has are
+ * consumer turned on, some `paper.tex` must actually have it enabled; the ones none has are
  * returned, for the caller to refuse.
+ *
+ * `files` is every `paper.tex` the guard may count: the ones this run linted AND every paper of the
+ * project. Judged against the run alone, `paperlint lint papers/c` failed on a block written for
+ * papers a and b (#103) — a block that reaches a paper outside this run is not dead. A glob that
+ * reaches no paper of the project at all still fails, from a subset as from the whole.
  */
-export async function silentOptionalRules(eslint, lintedFiles, opts) {
+export async function silentOptionalRules(eslint, files, opts) {
     const turnedOn = new Set((opts.rules ?? []).flatMap((b) => Object.entries(b.rules)
         .filter(([id, e]) => OPTIONAL_RULES.has(id) && isOn(e))
         .map(([id]) => id)));
     const reached = new Set();
-    for (const f of lintedFiles.filter((p) => basename(p) === MAIN)) {
+    for (const f of new Set(files.filter((p) => basename(p) === MAIN))) {
+        // Undefined for a file outside ESLint's cwd or scope: it reaches nothing.
         const cfg = (await eslint.calculateConfigForFile(f));
         for (const id of turnedOn)
-            if (isOn(cfg.rules?.[id]))
+            if (isOn(cfg?.rules?.[id]))
                 reached.add(id);
     }
     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;
+    // No `files`: `narrowToOwners` scopes the block to what paperlint lints under `dir`, exceptions
+    // included. A copy of the globs here is how the siblings index got parsed as JavaScript (#101).
+    const scoped = (rules) => Object.keys(rules).length ? [{ basePath: dir, rules }] : [];
+    return {
+        ok: true,
+        value: { preset: scoped(fromPreset.value), own: [...own.value] },
+    };
+}
+/** A paper's `{ id: severity }` rules, as one block over the paper's files (narrowed later, #101). */
+function ownRules(dir, settings) {
+    const own = paperRules(dir, settings, SHIPPED_RULES);
+    if (!own.ok)
+        return own;
     return {
         ok: true,
-        value: Object.keys(rules).length
-            ? { basePath: dir, files: PAPER_FILE_PATTERNS, rules }
-            : null,
+        value: own.value ? [{ basePath: dir, rules: own.value }] : [],
     };
 }
 /**
- * The files a paper's block may reach: exactly the ones paperlint's own blocks lint, read off its
- * 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.
+ * The globs paperlint lints, for the refusal message only. Which files a block reaches is decided by
+ * `narrowToOwners` from `ownedScopes` (src/paper-files.ts), where each glob keeps its exceptions.
  */
-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 +437,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 +466,7 @@ export function parseArgs(argv) {
         paths: [],
         config: null,
         json: false,
+        fix: false,
         all: false,
         dryRun: false,
         check: false,
@@ -385,6 +474,8 @@ export function parseArgs(argv) {
         noHooks: false,
         paper: null,
         format: null,
+        venue: null,
+        kind: null,
         hooksMode: null,
         // -1 = warnings NEVER fail the run. In this set most findings are advisory by design, and a
         // gate that fails on advice gets muted entirely.
@@ -406,11 +497,27 @@ export function parseArgs(argv) {
         return v;
     };
     for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === undefined)
+        const arg = rest[i];
+        if (arg === undefined)
             continue;
+        // `--flag=value` is `--flag value` for every flag that takes a value: the CI action writes
+        // `--max-warnings="$N"`, and that form used to fall through to the list of paths.
+        const eq = arg.indexOf("=");
+        const inline = arg.startsWith("--") && eq > 0 && VALUE_FLAGS.has(arg.slice(0, eq))
+            ? arg.slice(eq + 1)
+            : undefined;
+        const a = inline === undefined ? arg : arg.slice(0, eq);
+        const take = () => {
+            if (inline === undefined)
+                return valueFor(a, ++i);
+            if (inline === "")
+                out.missingValue = a;
+            return inline === "" ? undefined : inline;
+        };
         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")
@@ -424,27 +531,43 @@ export function parseArgs(argv) {
         else if (a.startsWith("--hooks="))
             out.hooksMode = a.slice("--hooks=".length);
         else if (a === "--paper")
-            out.paper = valueFor(a, ++i) ?? null;
+            out.paper = take() ?? null;
         else if (a === "--format")
-            out.format = valueFor(a, ++i) ?? null;
+            out.format = take() ?? null;
+        else if (a === "--venue")
+            out.venue = take() ?? null;
+        else if (a === "--kind")
+            out.kind = take() ?? null;
         // `--options` was the first spelling and is kept working. It named the wrong thing — every
         // other tool in the stack calls this file its config — but a flag in someone's CI is not
         // ours to break.
         else if (a === "--config" || a === "--options")
-            out.config = valueFor(a, ++i) ?? null;
+            out.config = take() ?? null;
         else if (a === "--max-warnings") {
-            const v = valueFor(a, ++i);
+            const v = take();
             if (v !== undefined)
                 out.maxWarnings = Number(v);
         }
         else if (a === "--help" || a === "-h")
             out.help = true;
+        // An unknown flag is refused by name. Read as a path, it silently lints something else.
+        else if (a.startsWith("-") && a !== "-")
+            out.unknownFlag ??= a;
         else
             out.paths.push(a);
     }
     return out;
 }
-export const PKG_NAME = "package.json";
+/** The flags that take a value, in either spelling: `--flag value` or `--flag=value`. */
+const VALUE_FLAGS = new Set([
+    "--paper",
+    "--format",
+    "--venue",
+    "--kind",
+    "--config",
+    "--options",
+    "--max-warnings",
+]);
 /**
  * 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 +582,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 +645,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.
@@ -648,16 +712,90 @@ resolve = (spec) => createRequire(import.meta.url).resolve(spec), } = {}) {
  * become two implementations. The lint runs on THAT folder, so the first thing printed after the
  * file list is its verdict rather than the old "missing PIPELINE-STATUS.md".
  */
-export async function createPaperAt(papersRoot, name, format, { log, err, cwd, }) {
-    const result = newPaper(papersRoot, name, format);
+export async function createPaperAt(papersRoot, name, format, { log, err, cwd, venue = null, }) {
+    const result = newPaper(papersRoot, name, format, { venue });
     const here = (p) => relative(cwd, p) || p;
     for (const line of reportNewPaper(result, here))
         log(line);
     if (!result.ok)
         return 2;
+    const config = here(join(result.dir, CONFIG_FILE));
+    if (venue === null)
+        log(`  venue: none yet — set "extends" in ${config}, or next time: paperlint new <name> --venue <preset> (${SHIPPED_VENUES().join(", ")})`);
+    else if (venue.kind === null && venue.kinds.length > 0)
+        log(`  kind: not set — \`${venue.label}\` sets a page limit per kind (${venue.kinds.join(", ")}); add "kind" to ${config}. Until then lint reports pdf/profile`);
     log(``);
     return run(["lint", result.dir], { log, err, cwd });
 }
+/**
+ * `--venue` / `--kind` → the `extends` and `kind` to write into `<paperDir>/paperlint.json`, or why
+ * not. Parsed here, at the boundary, and resolved through the same `resolvePreset` lint uses — so a
+ * venue `new` accepts is a venue lint resolves. On a terminal with no `--venue` it asks, with
+ * "none" as the default; without a terminal it chooses nothing (null), as before.
+ *
+ * A path is relative to where the command runs, because that is where it was typed; it is written
+ * relative to the paper's `paperlint.json`, because that is what `extends` is relative to. Written
+ * as typed, `./venues/x.jsonc` would name `<paper>/venues/x.jsonc`.
+ */
+export async function chooseVenue(flags, { paperDir, cwd, interactive, ask, }) {
+    const shipped = SHIPPED_VENUES();
+    if (flags.kind !== null && flags.venue === null)
+        return bad(`--kind needs --venue: a kind is a page limit of one venue preset — \`paperlint new <name> --venue <preset> --kind ${flags.kind}\``);
+    const asked = async (q) => (await ask(q).catch(() => "")).trim();
+    const venue = flags.venue ??
+        (interactive
+            ? await asked(`venue: ${[...shipped, "none"].join(" / ")} [none] `)
+            : "");
+    if (venue === "" || (flags.venue === null && venue === "none"))
+        return { ok: true, value: null };
+    const spec = venueSpec(venue, { shipped, paperDir, cwd });
+    if (!spec.ok)
+        return spec;
+    const r = resolvePreset(spec.value, join(paperDir, CONFIG_FILE), PRESET_DEPS);
+    if (!r.ok)
+        return bad(`--venue ${venue}: ${presetProblemText(r.error)}`);
+    const kinds = [...r.value.format.kinds.keys()];
+    const label = r.value.label;
+    if (flags.kind !== null) {
+        if (kinds.length === 0)
+            return bad(`--kind ${flags.kind}: \`${label}\` has no kinds — it sets no page limit, so there is no kind to choose`);
+        if (!kinds.includes(flags.kind))
+            return bad(`--kind ${flags.kind}: \`${label}\` has no kind \`${flags.kind}\`; its kinds: ${kinds.join(", ")}`);
+    }
+    const kind = flags.kind ??
+        (interactive && kinds.length > 0
+            ? await asked(`kind: ${[...kinds, "later"].join(" / ")} [later] `)
+            : null);
+    return {
+        ok: true,
+        value: {
+            extends: spec.value,
+            kind: kind !== null && kinds.includes(kind) ? kind : null,
+            label,
+            kinds,
+        },
+    };
+}
+const bad = (error) => ({
+    ok: false,
+    error,
+});
+/** What `--venue` names → the `extends` value, relative to `<paperDir>/paperlint.json`. */
+function venueSpec(venue, { shipped, paperDir, cwd, }) {
+    if (venue.startsWith("./") || venue.startsWith("../")) {
+        const file = resolve(cwd, venue);
+        if (!existsSync(file))
+            return bad(`--venue ${venue}: no such file (${file}) — a path is relative to where you run the command`);
+        const rel = relative(paperDir, file).split(sep).join("/");
+        return { ok: true, value: rel.startsWith("../") ? rel : `./${rel}` };
+    }
+    const name = venue.startsWith(SHIPPED_PREFIX)
+        ? venue.slice(SHIPPED_PREFIX.length)
+        : venue;
+    if (!shipped.includes(name))
+        return bad(`--venue ${venue}: no such venue preset. Shipped: ${shipped.join(", ")} — or a path to your own preset, starting with ./ or ../`);
+    return { ok: true, value: `${SHIPPED_PREFIX}${name}` };
+}
 /**
  * `paperlint new <name>` — the papers directory comes from the same declaration every other command
  * reads; there is no second way to name it. See `new-paper.ts` for what it writes and why.
@@ -665,7 +803,7 @@ export async function createPaperAt(papersRoot, name, format, { log, err, cwd, }
 async function runNew(a, { log, err, cwd, ask = askOnTerminal, }) {
     const [name, ...extra] = a.paths;
     if (!name || extra.length > 0) {
-        err(`\`new\` takes exactly one paper name: \`paperlint new my-paper [--format tex|md]\``);
+        err(`\`new\` takes exactly one paper name: \`paperlint new my-paper [--venue <preset>] [--kind <kind>] [--format tex|md]\``);
         return 2;
     }
     let format = DEFAULT_FORMAT;
@@ -684,16 +822,37 @@ 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)
         log(`several papers directories are declared — using the first: ${relative(cwd, papersRoot) || papersRoot}`);
-    return createPaperAt(papersRoot, name, format, { log, err, cwd });
+    const paperDir = join(papersRoot, name);
+    // An existing paperlint.json is never overwritten, so a venue for it is refused, not dropped.
+    const hasConfig = existsSync(join(paperDir, CONFIG_FILE));
+    if (hasConfig && (a.venue !== null || a.kind !== null)) {
+        err(`${relative(cwd, join(paperDir, CONFIG_FILE))} already exists and is never overwritten — set "extends" and "kind" in it by hand`);
+        return 2;
+    }
+    const venue = hasConfig
+        ? { ok: true, value: null }
+        : await chooseVenue(a, {
+            paperDir,
+            cwd,
+            interactive: processInteractivity(a.yes).interactive,
+            ask,
+        });
+    if (!venue.ok)
+        return (err(venue.error), 2);
+    return createPaperAt(papersRoot, name, format, {
+        log,
+        err,
+        cwd,
+        venue: venue.value,
+    });
 }
 /**
  * 🔴 THE TARGET IS NAMED, "EVERYTHING" IS AN OPTION. That is how it is for everyone whose build is
@@ -706,12 +865,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 +889,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 +920,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 +973,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
@@ -831,6 +1024,10 @@ export async function run(argv, { log = console.log, err = console.error, cwd =
             `not what the command line said.`);
         return 2;
     }
+    if (a.unknownFlag !== undefined) {
+        err(`unknown flag \`${a.unknownFlag}\` — \`paperlint --help\` lists every flag`);
+        return 2;
+    }
     if (a.help || !a.cmd) {
         log(USAGE);
         return a.help ? 0 : 2;
@@ -838,35 +1035,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 +1064,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 +1113,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 +1133,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,20 +1153,50 @@ 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,
+        // Every paper of the project, not only the ones on the command line (#103).
+        projectPapers: papersRoots(cfg)
+            .flatMap((r) => papersIn(r))
+            .map((d) => join(d, MAIN))
+            .filter((f) => existsSync(f)),
     });
 }
+/**
+ * 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.
  */
 async function reportLint(eslint, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #49: replace with a real type
-results, structure, { a, log, err, where, opts, }) {
-    const silent = await silentOptionalRules(eslint, results.map((r) => r.filePath), opts);
+results, structure, { a, log, err, where, opts, projectPapers, }) {
+    const silent = await silentOptionalRules(eslint, [...results.map((r) => r.filePath), ...projectPapers], opts);
     if (silent.length > 0) {
-        err(`${silent.join(", ")} is turned on in "rules", but no linted paper.tex gets it — check the block's ` +
+        err(`${silent.join(", ")} is turned on in "rules", but no paper.tex of the project gets it — check the block's ` +
             `"files" (relative to ${where}). A rule that never runs reports exactly like a rule that passed.`);
         return 1;
     }