paperlint 2.1.0 → 3.1.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,15 +44,31 @@ 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,
+  presetProblemText,
+  resolvePreset,
+  shippedPresets,
+  SHIPPED_PREFIX,
   type PaperPreset,
 } from "./presets.ts";
 import type { ToolInstaller } from "./ports/tool-installer.ts";
@@ -74,17 +88,16 @@ import {
   newPaper,
   reportNewPaper,
   type PaperFormat,
+  type VenueSetting,
 } from "./new-paper.ts";
 // 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 +106,7 @@ import {
   unknownKeys,
   type Parsed,
   type RuleBlock,
+  type RuleEntry,
 } from "./rules-config.ts";
 export { init };
 export { nextSteps } from "./init.ts";
@@ -106,18 +120,23 @@ 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 = (): string[] => 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
@@ -127,7 +146,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
@@ -142,49 +164,56 @@ 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:
-
-  "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.
 
-per paper — <paper>/paperlint.json (it was venue.json before 2.1.0; \`npx paperlint init\` moves it):
+    {
+      "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.
+
+  <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)
+  "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. */
@@ -193,7 +222,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 +267,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 +301,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;
 }
 
@@ -310,6 +339,64 @@ export const SHIPPED_RULES: ReadonlySet<string> = shippedRuleIds(
   [markdown],
 );
 
+/** A plugin as `rulePlugins` gives it: its rules, and for `tex` the LaTeX language when given. */
+export interface RulePlugin {
+  readonly rules?: Readonly<Record<string, unknown>>;
+  readonly languages?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 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?: unknown): Record<string, RulePlugin> {
+  const out: Record<string, { rules: Record<string, unknown> }> = {};
+  for (const block of buildConfig({}, texLanguage ?? { sentinel: "tex" }))
+    for (const [name, plugin] of Object.entries(
+      (block as { plugins?: Record<string, RulePlugin> }).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?: unknown): Linter.Config[] {
+  return [
+    {
+      name: "paperlint/rules-off",
+      plugins: rulePlugins(texLanguage) as Linter.Config["plugins"],
+      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: unknown): boolean => {
   const sev = Array.isArray(entry) ? entry[0] : entry;
@@ -333,12 +420,17 @@ export const OPTIONAL_RULES: ReadonlySet<string> = new Set(
  * 🔴 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: ESLint,
-  lintedFiles: readonly string[],
+  files: readonly string[],
   opts: PaperlintConfig,
 ): Promise<string[]> {
   const turnedOn = new Set(
@@ -349,44 +441,52 @@ export async function silentOptionalRules(
     ),
   );
   const reached = new Set<string>();
-  for (const f of lintedFiles.filter((p) => basename(p) === MAIN)) {
-    const cfg = (await eslint.calculateConfigForFile(f)) as {
-      rules?: Record<string, unknown>;
-    };
-    for (const id of turnedOn) if (isOn(cfg.rules?.[id])) reached.add(id);
+  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)) as
+      { rules?: Record<string, unknown> } | undefined;
+    for (const id of turnedOn) 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: 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,38 +496,63 @@ 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;
+  // 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: Record<string, RuleEntry>): RuleBlock[] =>
+    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: string,
+  settings: PaperSettings,
+): Parsed<readonly RuleBlock[]> {
+  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: 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 +561,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 +594,7 @@ export function parseArgs(argv: readonly string[]): Args {
     paths: [],
     config: null,
     json: false,
+    fix: false,
     all: false,
     dryRun: false,
     check: false,
@@ -474,6 +602,8 @@ export function parseArgs(argv: readonly string[]): Args {
     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.
@@ -495,9 +625,23 @@ export function parseArgs(argv: readonly string[]): Args {
   };
 
   for (let i = 0; i < rest.length; i++) {
-    const a = rest[i];
-    if (a === undefined) continue;
+    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 = (): string | undefined => {
+      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") out.dryRun = true;
     else if (a === "--check") out.check = true;
@@ -505,23 +649,35 @@ export function parseArgs(argv: readonly string[]): Args {
     else if (a === "--no-hooks") out.noHooks = true;
     else if (a.startsWith("--hooks="))
       out.hooksMode = a.slice("--hooks=".length);
-    else if (a === "--paper") out.paper = valueFor(a, ++i) ?? null;
-    else if (a === "--format") out.format = valueFor(a, ++i) ?? null;
+    else if (a === "--paper") out.paper = take() ?? null;
+    else if (a === "--format") 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;
+    else if (a === "--config" || a === "--options") 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: ReadonlySet<string> = 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
@@ -539,46 +695,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 +719,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 +781,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.
@@ -776,16 +875,143 @@ export async function createPaperAt(
     log,
     err,
     cwd,
-  }: { log: typeof console.log; err: typeof console.error; cwd: string },
+    venue = null,
+  }: {
+    log: typeof console.log;
+    err: typeof console.error;
+    cwd: string;
+    /** What `--venue` chose; null writes the template's `paperlint.json` as it is. */
+    venue?: VenueChoice | null;
+  },
 ): Promise<number> {
-  const result = newPaper(papersRoot, name, format);
+  const result = newPaper(papersRoot, name, format, { venue });
   const here = (p: string): string => 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 });
 }
 
+/** A venue `paperlint new` will write, with what the messages need to say about it. */
+export interface VenueChoice extends VenueSetting {
+  /** The preset's word in messages (`agenticdev`, `my-workshop`). */
+  readonly label: string;
+  /** The preset's kinds; empty when it sets no page limit. */
+  readonly kinds: readonly string[];
+}
+
+/**
+ * `--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: { readonly venue: string | null; readonly kind: string | null },
+  {
+    paperDir,
+    cwd,
+    interactive,
+    ask,
+  }: {
+    paperDir: string;
+    cwd: string;
+    interactive: boolean;
+    ask: (q: string) => Promise<string>;
+  },
+): Promise<Parsed<VenueChoice | null>> {
+  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: string): Promise<string> =>
+    (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: string): { ok: false; error: string } => ({
+  ok: false,
+  error,
+});
+
+/** What `--venue` names → the `extends` value, relative to `<paperDir>/paperlint.json`. */
+function venueSpec(
+  venue: string,
+  {
+    shipped,
+    paperDir,
+    cwd,
+  }: { shipped: readonly string[]; paperDir: string; cwd: string },
+): Parsed<string> {
+  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.
@@ -807,7 +1033,7 @@ async function runNew(
   const [name, ...extra] = a.paths;
   if (!name || extra.length > 0) {
     err(
-      `\`new\` takes exactly one paper name: \`paperlint new my-paper [--format tex|md]\``,
+      `\`new\` takes exactly one paper name: \`paperlint new my-paper [--venue <preset>] [--kind <kind>] [--format tex|md]\``,
     );
     return 2;
   }
@@ -828,14 +1054,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;
   }
@@ -843,7 +1066,30 @@ async function runNew(
     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 as const, 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,
+  });
 }
 
 /**
@@ -863,16 +1109,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 +1137,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 +1169,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 +1238,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[],
   {
@@ -1029,6 +1317,12 @@ export async function run(
     );
     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;
@@ -1036,43 +1330,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 +1360,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 +1414,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 +1437,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 +1459,50 @@ export async function run(
     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: 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.
@@ -1211,22 +1518,24 @@ async function reportLint(
     err,
     where,
     opts,
+    projectPapers,
   }: {
     a: Args;
     log: typeof console.log;
     err: typeof console.error;
     where: string;
     opts: PaperlintConfig;
+    projectPapers: readonly string[];
   },
 ): Promise<number> {
   const silent = await silentOptionalRules(
     eslint,
-    results.map((r) => r.filePath),
+    [...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 ` +
+      `${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;