paperlint 10.4.0 → 11.0.0

package/skills/grade-paper-writing/prose-lint.mjs

@@ -17,17 +17,18 @@
  *
  * A `.txt` is the text of the rendered PDF — the page a reviewer actually reads.
  *
- * The figure captions are measured too (`--flags-only`): every `\caption{}` in `paper.tex` and the
+ * The figure captions are measured too, in the report: every `\caption{}` in `paper.tex` and the
  * files it includes, or, beside a rendered page, in `figures/*.tex`.
  *
- * Advisory: it prints findings; `--flags-only` exits with code 1 if anything was found.
+ * Advisory: the report prints every check and exits 0. `--flags-only` prints the checks the report
+ * marks FLAG, each with the lines under it, and nothing on a clean paper; it exits 1 when there is
+ * one — the form for a hook.
  */
 import { paperProse } from "#src/paper-prose";
 import { paperRecord } from "#src/paper-record";
-import { latexReader } from "#src/adapters/latex/index";
+import { captionsOf, latexReader, parseLatex } from "#src/adapters/latex/index";
 import { nodeFiles } from "#src/adapters/node/index";
 import { sourcesCodec } from "#src/adapters/sources-record/index";
-import { texToMdast } from "#eslint-rules/latex-language";
 
 const THRESHOLDS = {
   metadiscourseTotalPer1000: {
@@ -363,77 +364,116 @@ function figureFiles(pagePath, fs, path) {
 }
 
 /**
- * Every `\caption{…}` of `sources` (`{ file, text }`) a reader sees, measured. The LaTeX
- * language's projection blanks what never typesets — verbatim and code, macro definitions, the
- * preamble — and keeps a caption's argument; it keeps comments too, as `html` nodes of its tree,
- * for the rules that read notes. So a caption is skipped when its argument is blank in the
- * projection or it starts inside a comment: a quoted or commented-out `\caption` is not one.
+ * Every `\caption` of `sources` (`{ file, text }`) a reader sees, measured. The captions come from the
+ * parsed source (`captionsOf`, src/adapters/latex/captions.ts): its optional argument, star and spacing
+ * are the parser's, and a caption that is commented out, in verbatim or in a macro's definition is not one.
  */
 function captions(sources) {
-  const out = [];
-  for (const { file: f, text: s } of sources) {
-    const { root, text: seen } = texToMdast(s);
-    const comments = root.children
-      .filter((n) => n.type === "html")
-      .map((n) => [n.position.start.offset, n.position.end.offset]);
-    for (const m of s.matchAll(/\\caption\{/g)) {
-      let i = m.index + m[0].length,
-        depth = 1,
-        j = i;
-      while (j < s.length && depth) {
-        if (s[j] === "{") depth++;
-        else if (s[j] === "}") depth--;
-        j++;
-      }
-      if (
-        !/\S/.test(seen.slice(i, j - 1)) ||
-        comments.some(([a, b]) => m.index >= a && m.index < b)
-      )
-        continue;
-      const text = s
-        .slice(i, j - 1)
-        .replace(/\\[a-zA-Z]+\s*/g, " ")
-        .replace(/[{}]/g, " ")
-        .replace(/---/g, " ")
-        .replace(/\s+/g, " ")
-        .trim();
-      if (!text) continue;
-      // A non-empty caption splits into at least one sentence.
-      const sents = splitSentences(text);
-      out.push({
-        file: f,
-        words: words(text),
+  return sources.flatMap(({ file, text }) =>
+    captionsOf(parseLatex(text)).map((raw) => {
+      // A dash with no spaces round it joins two words in the count, as it never did here.
+      const caption = raw.replace(/---/g, " ");
+      const sents = splitSentences(caption);
+      return {
+        file,
+        words: words(caption),
         longest: Math.max(...sents.map(words)),
         longestSentence: sents.slice().sort((a, b) => words(b) - words(a))[0],
-      });
-    }
-  }
-  return out;
+      };
+    }),
+  );
+}
+
+/**
+ * The findings on the captions of the file `f`: one line per caption sentence or caption over its
+ * limit. A paper's captions are in its own files — paper.tex and what it includes, wherever a figure
+ * is set; a rendered page has the `.tex` of `figures/` beside it. The report and `--flags-only` both
+ * read them from here.
+ */
+function captionFindings(f, tex, fs, path) {
+  return captions(tex ? tex.files : figureFiles(f, fs, path)).flatMap((c) =>
+    CAPTION_LIMITS.filter(over(c)).map(say(c)),
+  );
+}
+
+/**
+ * The two limits a caption is held to: the `THRESHOLDS` key, what of a caption it is measured on, and
+ * how a finding reads. A caption is over a limit when its measure exceeds the threshold's `warn`.
+ */
+const CAPTION_LIMITS = [
+  {
+    key: "captionSentenceWords",
+    measure: (c) => c.longest,
+    say: (c, warn) =>
+      `${c.file}: caption sentence of ${c.longest} words (warn >${warn}) — "${c.longestSentence.slice(0, 110)}…"`,
+  },
+  {
+    key: "captionWords",
+    measure: (c) => c.words,
+    say: (c, warn) =>
+      `${c.file}: caption is ${c.words} words (warn >${warn}) — a caption this long is a section under a picture`,
+  },
+];
+const over = (c) => (limit) => limit.measure(c) > THRESHOLDS[limit.key].warn;
+const say = (c) => (limit) => limit.say(c, THRESHOLDS[limit.key].warn);
+
+/**
+ * Every line of the report as data, in the order it is printed: `ok` is true (passed), false (a
+ * finding, marked `FLAG`) or null (a figure, no check), `under` the lines that name the offenders.
+ * The report prints all of it; `--flags-only` prints the findings: one list, two renderings.
+ */
+function checks(r, captionLines) {
+  const T = THRESHOLDS;
+  return [
+    {
+      ok: r.metadiscoursePer1000 <= T.metadiscourseTotalPer1000.warn,
+      text: `all metadiscourse/1000w  ${r.metadiscoursePer1000}   (Hyland RA baseline 64.9, warn >${T.metadiscourseTotalPer1000.warn})`,
+      under: [],
+    },
+    {
+      ok: null,
+      text: `nominalisations/1000w    ${r.nominalisationsPer1000}`,
+      under: [],
+    },
+    {
+      ok: r.contrastivePer10k <= T.contrastivePer10k.warn,
+      text: `"rather than"/instead-of/10,000w  ${r.contrastivePer10k}   (warn >${T.contrastivePer10k.warn}; not epanorthosis, no published baseline)`,
+      under: [],
+    },
+    {
+      ok: r.wastedStress.length === 0,
+      text: `sentences ending on a cross-ref/citation/hedge (wasted stress position): ${r.wastedStress.length}`,
+      under: r.wastedStress.map((s) => `…${s.slice(-70)}`),
+    },
+    {
+      ok: r.negatedSentencePct <= T.negatedMainClausePct.warn,
+      text: `sentences whose main claim is a negation: ${r.negatedSentencePct}%`,
+      under: [],
+    },
+    {
+      ok: captionLines.length === 0,
+      text: `figure captions over the limit: ${captionLines.length}`,
+      under: captionLines,
+    },
+    {
+      ok: null,
+      text: `topic positions (whose story is this?): ${r.topics.map((t) => `"${t}"`).join(" | ")}`,
+      under: [],
+    },
+  ];
 }
 
-function report(name, r) {
-  const flag = (ok) => (ok ? "ok  " : "FLAG");
+const MARK = { true: "ok  ", false: "FLAG", null: "    " };
+
+function report(name, r, rows) {
   console.log(`\n=== ${name} — ${r.words} words, ${r.sentences} sentences ===`);
   console.log(
     `sentence lengths ${JSON.stringify(r.sentenceLens)}  mean ${r.meanLen}  sd ${r.sdLen}  CV ${r.cv}`,
   );
-  console.log(
-    `${flag(r.metadiscoursePer1000 <= THRESHOLDS.metadiscourseTotalPer1000.warn)} all metadiscourse/1000w  ${r.metadiscoursePer1000}   (Hyland RA baseline 64.9, warn >${THRESHOLDS.metadiscourseTotalPer1000.warn})`,
-  );
-  console.log(`     nominalisations/1000w    ${r.nominalisationsPer1000}`);
-  console.log(
-    `${flag(r.contrastivePer10k <= THRESHOLDS.contrastivePer10k.warn)} "rather than"/instead-of/10,000w  ${r.contrastivePer10k}   (warn >${THRESHOLDS.contrastivePer10k.warn}; not epanorthosis, no published baseline)`,
-  );
-  console.log(
-    `${flag(r.wastedStress.length === 0)} sentences ending on a cross-ref/citation/hedge (wasted stress position): ${r.wastedStress.length}`,
-  );
-  r.wastedStress.forEach((s) => console.log(`       > …${s.slice(-70)}`));
-  console.log(
-    `${flag(r.negatedSentencePct <= THRESHOLDS.negatedMainClausePct.warn)} sentences whose main claim is a negation: ${r.negatedSentencePct}%`,
-  );
-  console.log(
-    `     topic positions (whose story is this?): ${r.topics.map((t) => `"${t}"`).join(" | ")}`,
-  );
+  rows.forEach(({ ok, text, under }) => {
+    console.log(`${MARK[ok]} ${text}`);
+    under.forEach((l) => console.log(`       > ${l}`));
+  });
 }
 
 const args = process.argv.slice(2);
@@ -474,14 +514,14 @@ function pdfTextOnly(t) {
     .replace(/\f/g, "\n\n");
 }
 
-// 🔴 `--flags-only` and a NON-ZERO EXIT, added 2026-08-05, are what let anything downstream act.
-// Until today this file printed a wall of numbers and always exited 0, and it was wired to no hook
-// at all — it ran only if a human or a skill remembered it existed. Its epanorthosis metric sat at
-// 50.8 per 10,000 words (the LLM baseline is 7.8) through five consecutive writing passes and never
-// once flagged, because it had no threshold. The corpus owner found the tic by eye in a single reading and
-// asked why the tooling had not. It had not because it was measuring, and measuring is not checking
-// — which is, word for word, this paper's own thesis running loose inside its own toolchain.
-const flagsOnly = args.includes("--flags-only");
+// `--flags-only` prints the findings of the report (every line it marks FLAG, with the lines under
+// it) and nothing on a clean paper, and exits 1 when there is one: the form for a hook. The report
+// prints all of `checks` and exits 0.
+const mode = args.includes("--flags-only")
+  ? "flags"
+  : args.includes("--headings")
+    ? "headings"
+    : "report";
 let flagged = 0;
 for (const f of args.filter((a) => !a.startsWith("--"))) {
   const raw = fs.readFileSync(f, "utf8");
@@ -509,33 +549,25 @@ for (const f of args.filter((a) => !a.startsWith("--"))) {
     process.exit(2);
   }
   const r = analyse(text, sentences);
-  if (flagsOnly) {
-    const lines = [];
-    // A paper's captions are in its own files — paper.tex and what it includes, wherever a figure
-    // is set; a rendered page has the `.tex` of `figures/` beside it.
-    for (const c of captions(tex ? tex.files : figureFiles(f, fs, path))) {
-      if (c.longest > THRESHOLDS.captionSentenceWords.warn)
-        lines.push(
-          `   ${c.file}: caption sentence of ${c.longest} words (warn >${THRESHOLDS.captionSentenceWords.warn}) — "${c.longestSentence.slice(0, 110)}…"`,
-        );
-      if (c.words > THRESHOLDS.captionWords.warn)
-        lines.push(
-          `   ${c.file}: caption is ${c.words} words (warn >${THRESHOLDS.captionWords.warn}) — a caption this long is a section under a picture`,
-        );
-    }
-    if (lines.length) {
-      flagged += lines.length;
+  const rows = () => checks(r, captionFindings(f, tex, fs, path));
+  if (mode === "flags") {
+    const found = rows().filter((row) => row.ok === false);
+    if (found.length) {
+      flagged += found.length;
       // The header STATES the count, so a caller need not count output lines — header and footer
       // are not findings.
       console.error(
-        `✍️  prose-lint — ${f.split("/").pop()} — ${lines.length} finding(s):`,
+        `✍️  prose-lint — ${f.split("/").pop()} — ${found.length} finding(s):`,
       );
-      lines.forEach((l) => console.error(l));
+      found.forEach(({ text, under }) => {
+        console.error(`   ${text}`);
+        under.forEach((l) => console.error(`      > ${l}`));
+      });
       console.error(
-        "   run prose-lint.mjs on the file without --flags-only for the sentences",
+        "   run prose-lint.mjs on the file without --flags-only for every metric",
       );
     }
-  } else if (args.includes("--headings")) {
+  } else if (mode === "headings") {
     // The whole-document question, printed as one list. Not a gate: "does this heading name a
     // concrete noun" is judgement and pretending otherwise would be the exact failure this file
     // exists to stop. What was missing is cheaper and was the real cause — nobody had ever seen the
@@ -558,10 +590,10 @@ for (const f of args.filter((a) => !a.startsWith("--"))) {
       'a linter, a configuration, a repository, a rule — not "answers", "kinds", "moves".',
     );
   } else {
-    report(f.split("/").pop(), r);
+    report(f.split("/").pop(), r, rows());
   }
 }
-if (!flagsOnly)
+if (mode !== "flags")
   console.log(
     "\n(thresholds and their sources are in THRESHOLDS at the top of this file)",
   );

package/skills/grade-paper-writing/prose-lint.test.ts

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { expect, test } from "vitest";
-import { cpSync } from "node:fs";
+import { cpSync, readFileSync } from "node:fs";
 import { layRecord, recordedTree } from "../../test/recorded-fixture.ts";
 import { runNode, useTempDir, writeTree } from "../../test/support.ts";
 
@@ -62,6 +62,16 @@ const TREE = {
   "commented/paper.tex": tex(
     `Prose here.\n% \\caption{Commented ${LONG_CAPTION_SENTENCE}.}\n\\begin{verbatim}\n\\caption{Quoted ${LONG_CAPTION_SENTENCE}.}\n\\end{verbatim}\n\\begin{figure}\\caption{Real ${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
   ),
+  // The caption command with an optional argument, and with a space before its brace.
+  "optarg/paper.tex": tex(
+    `Prose here. \\begin{figure}\\caption[Short]{${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
+  ),
+  "spaced/paper.tex": tex(
+    `Prose here. \\begin{figure}\\caption {${LONG_CAPTION_SENTENCE}.}\\end{figure}`,
+  ),
+  "negated/paper.tex": tex(
+    "It is not fast. It is not small. It is not red. Nothing here is plain.",
+  ),
   "ends-on-marks/paper.tex": tex(
     "The method holds on every input~\\cite{knuth}. The proof is given in full (Section~\\ref{proof}). The result is new.",
   ),
@@ -83,6 +93,9 @@ const READ: Readonly<Record<string, readonly string[]>> = {
   inline: ["paper.tex", "sec/results.tex"],
   commented: ["paper.tex"],
   "ends-on-marks": ["paper.tex"],
+  negated: ["paper.tex"],
+  optarg: ["paper.tex"],
+  spaced: ["paper.tex"],
   empty: ["paper.tex"],
 };
 writeTree(
@@ -182,6 +195,23 @@ test("--flags-only: an over-long caption flags and exits 1", () => {
   expect(r.stderr).toMatchSnapshot();
 });
 
+test("--flags-only: a metric over its threshold (not a caption) is a finding too, and the report flags the same line", () => {
+  const file = join(root, "negated", "paper.tex");
+  const only = runNode(SCRIPT, ["--flags-only", file]);
+  const report = runNode(SCRIPT, [file]);
+  // Guards: the mode promised "print nothing on a clean paper, any output means a finding" and
+  // looked only at captions; the metrics the report FLAGs are findings of the same kind.
+  assert.deepEqual(
+    { status: only.status, stdout: only.stdout },
+    { status: 1, stdout: "" },
+  );
+  expect(only.stderr).toMatchSnapshot();
+  assert.match(
+    report.stdout,
+    /^FLAG sentences whose main claim is a negation: 75%$/m,
+  );
+});
+
 test("--flags-only: a paper with no figures directory is clean, exit 0 and silent", () => {
   assert.deepEqual(
     runNode(SCRIPT, ["--flags-only", join(root, "clean", "paper.tex")]),
@@ -248,17 +278,13 @@ test("🔴 --flags-only reads the captions of the paper.tex and of the files it
       stdout: r.stdout,
       flagged: r.stderr
         .split("\n")
-        .filter((l) => l.startsWith("   "))
+        .filter((l) => l.startsWith("      > "))
         .map((l) => l.split(":")[0]),
     },
     {
       status: 1,
       stdout: "",
-      flagged: [
-        "   paper.tex",
-        "   sec/results.tex",
-        "   run prose-lint.mjs on the file without --flags-only for the sentences",
-      ],
+      flagged: ["      > paper.tex", "      > sec/results.tex"],
     },
   );
 });
@@ -274,8 +300,14 @@ test("--flags-only on a rendered page reads the captions in figures/*.tex beside
     join(root, "rendered", "page.txt"),
   ]);
   assert.deepEqual(
-    { status: r.status, first: r.stderr.split("\n")[1]?.split(":")[0] },
-    { status: 1, first: "   figures/f.tex" },
+    {
+      status: r.status,
+      first: r.stderr
+        .split("\n")
+        .find((l) => l.startsWith("      > "))
+        ?.split(":")[0],
+    },
+    { status: 1, first: "      > figures/f.tex" },
   );
   // …and a page with no figures/ beside it has no caption to flag.
   assert.deepEqual(runNode(SCRIPT, ["--flags-only", join(root, "page.txt")]), {
@@ -296,9 +328,86 @@ test("🔴 a caption commented out or quoted in verbatim is not measured; a real
       status: r.status,
       findings: r.stderr
         .split("\n")
-        .filter((l) => l.startsWith("   paper.tex:"))
+        .filter((l) => l.startsWith("      > paper.tex:"))
         .map((l) => /— "(\w+)/.exec(l)?.[1]),
     },
     { status: 1, findings: ["Real"] },
   );
 });
+
+/** The `prose-lint.mjs` invocations SKILL.md documents (Step 6), their arguments with `<paper-dir>` filled in. */
+const documentedInvocations = (paperDir: string): readonly string[][] =>
+  readFileSync(join(dirname(SCRIPT), "SKILL.md"), "utf8")
+    .split("\n")
+    .flatMap((line) => {
+      const m =
+        /node \$\{CLAUDE_SKILL_DIR\}\/prose-lint\.mjs ([^#]+?)\s*(#|$)/.exec(
+          line,
+        );
+      return m?.[1] === undefined
+        ? []
+        : [m[1].replaceAll("<paper-dir>", paperDir).split(/\s+/)];
+    });
+
+test("🔴 the invocation SKILL.md documents reports an over-long caption, with no flag the skill does not name", () => {
+  const documented = documentedInvocations(join(root, "p"));
+  // Guards: the report is the documented way to run the checks (Step 6), and captions were
+  // measured only under an undocumented flag — an over-long caption produced no finding.
+  const report = documented.find((a) => !a.includes("--headings"));
+  assert.ok(report !== undefined, "SKILL.md documents a report invocation");
+  const r = runNode(SCRIPT, report);
+  assert.deepEqual(
+    {
+      status: r.status,
+      flagged: r.stdout
+        .split("\n")
+        .filter(
+          (l) => l.startsWith("FLAG figure captions") || l.includes("caption"),
+        ),
+    },
+    {
+      status: 0,
+      flagged: [
+        "FLAG figure captions over the limit: 2",
+        '       > figures/fig1.tex: caption sentence of 46 words (warn >40) — "Big. word0 word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12 word13 word14 word15 wor…"',
+        "       > figures/fig1.tex: caption is 106 words (warn >100) — a caption this long is a section under a picture",
+      ],
+    },
+  );
+});
+
+test("the report says a paper whose captions are within the limits is clean on that line", () => {
+  const r = runNode(SCRIPT, [join(root, "clean", "paper.tex")]);
+  // Guards: the line is printed on a clean paper too, so its absence is never read as a pass.
+  assert.match(r.stdout, /^ok {3}figure captions over the limit: 0$/m);
+});
+
+test("🔴 a caption with an optional argument, or a space before its brace, is measured", () => {
+  const found = (dir: string) => {
+    const r = runNode(SCRIPT, [join(root, dir, "paper.tex")]);
+    return [
+      r.status,
+      /^FLAG figure captions over the limit: (\d+)$/m.exec(r.stdout)?.[1],
+    ];
+  };
+  // Guards: the scan matched `\caption{` only, so `\caption[Short]{…}` and `\caption {…}` were never
+  // read and the report printed "ok ... 0" for a long caption.
+  expect([found("optarg"), found("spaced")]).toEqual([
+    [0, "1"],
+    [0, "1"],
+  ]);
+});
+
+test("🔴 the caption of the package's own p1 fixture, which has an optional argument, is reported", () => {
+  const p1 = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "fixtures",
+    "paper-sources",
+    "p1",
+    "paper.tex",
+  );
+  const r = runNode(SCRIPT, ["--flags-only", p1]);
+  assert.match(r.stderr, /— "Optional-arg caption this sentence/);
+});

package/skills/submission-portal/SKILL.md

@@ -1,69 +1,85 @@
 ---
 name: submission-portal
-description: "Read or change a paper's submission on the venue's HotCRP portal via `paperlint submission show|update`: replace the PDF or abstract, mark it submitted, check it is really \"Submitted\", and verify by sha256 that the portal holds the latest build. Use when the PDF or abstract on HotCRP needs replacing, when asked whether the paper is truly submitted or which PDF reviewers see, or before a deadline. Composes with submit-paper (what to submit); this gets it onto the portal and proves it landed."
+description: "Create, read or change a paper's submission on the venue's HotCRP portal via `paperlint submission new|show|update`: register the paper, replace the PDF or abstract, mark it submitted, and verify by sha256 that the portal holds the latest build. Use when the paper is not yet on HotCRP, when its PDF or abstract there needs replacing, when asked whether it is truly submitted, or before a deadline. Composes with submit-paper (what to submit)."
 allowed-tools: [Read, Grep, Glob, Bash]
 ---
 
-<!-- vigiles:sha256:4b3a8c0b51ebe206 compiled from skills/submission-portal/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:03bc35623dbd7911 compiled from skills/submission-portal/SKILL.md.spec.ts -->
 
-# submission-portal — read and update the submission on the portal, then prove it landed
+# submission-portal — create, read and update the submission on the portal, then prove it landed
 
-`paperlint submission` talks to the venue's submission portal through its API. Only HotCRP is
-supported; for any other portal the command says so and the upload is done by hand.
+`paperlint submission` creates, reads and updates the paper's submission on the venue's portal.
+Only HotCRP is supported; for any other portal the command says so and the upload is done by hand.
+
+## What the command does, and what stays on the site
+
+`submission new` creates the submission with the title, the abstract, the authors and the PDF.
+Everything else — conflicts, topics, the venue's own fields — is done on the site by the author: the
+command prints that list, with the submission's page, after every run.
+
+## Token
+
+One variable per site: `HOTCRP_TOKEN_MSR2027` for `msr2027.hotcrp.com`; for a site not on
+hotcrp.com, its whole host (with a port other than the default) and path. A plain `HOTCRP_TOKEN` is not read. When the command reports
+a missing, misnamed or refused token, **relay its message to the author verbatim and stop**: it
+already says where on the site to make one, which permissions to tick, and which variable to set.
+🔴 Never ask for the token in chat, never print it, never write it to a file — the author sets it in
+their own environment.
 
 ## What must be in place
 
 - **The venue preset declares the portal**: `"portal": { "kind": "hotcrp", "url": "<the site>" }`
-  (`paperlint:aidc` and `paperlint:msr` have it). For your own venue preset, add it there.
-- **The paper's `paperlint.json` names its submission**: `"submission": { "id": <number> }` — the
-  number HotCRP shows for the paper.
-- **A token in `HOTCRP_TOKEN`**, created by the author on the HotCRP site under Account settings →
-  Developer (scopes `submeta:read` and `document:read` to read; `submeta:write` and
-  `document:write` to update). Never ask for it in chat, never print it, never write it to a file:
-  the command reads it from the environment and sends it only as the `Authorization` header.
+  (`paperlint:aidc` and `paperlint:msr` have it).
+- **For `new`: `"authors"` in the paper's `paperlint.json`** — `[{ "name", "email",
+  "affiliation" }]`, every author in the paper's order. The author writes this list; never fill it
+  in from the paper, a profile or memory.
+- **For `show` and `update`: `"submission": { "id": <number> }`** — `new --save` writes it.
 
-A missing key or token stops the command with exit 2 and a line naming the file and key, or the
-variable — fix exactly that and run again.
+A missing key or token stops the command with exit 2 and a line naming what to set — fix exactly that.
 
 ## The procedure — always in this order
 
-1. **Read it.** `npx paperlint submission show papers/<paper>` — status, title, type, topics,
-   abstract length, the PDF the portal holds, and `match`: whether that PDF's sha256 equals the
-   local `paper.pdf`. Rebuild first (`npx paperlint build papers/<paper>`) if the local PDF is stale.
-2. **Dry run.** `npx paperlint submission update papers/<paper>` — sends the PDF (add
-   `--abstract <file>` for a plain-text abstract, `--submit` to mark it submitted) with HotCRP's
-   `dry_run=1`: the portal checks the change and **keeps nothing**. Read `valid`, `changes` and every
-   `portal says:` line. Exit 1 means the portal would refuse it — report why, do not go on.
-3. **Ask the author.** Show the dry run's output and ask for an explicit yes to change the real
-   submission.
-4. **Save — only after that yes.** `npx paperlint submission update papers/<paper> --save` (same
-   flags as the dry run). 🔴 `--save` CHANGES A REAL SUBMISSION that reviewers will see. Never run it
-   without the author's explicit yes in this conversation, never "to test", and never because a
-   dry run was valid.
-5. **Prove it landed.** `npx paperlint submission show papers/<paper>` again: `match` must read
-   `yes — the portal holds this build`, and the status must be what was intended (`submitted` if
-   `--submit` was sent). Anything else is not done — say so.
-
-The same five steps as commands, in order (`<paper>` is the paper's folder):
+`papers/my-paper` stands for the paper's folder.
+
+0. **Create it, once — only while the paper has no `submission` id.**
+   `npx paperlint submission new papers/my-paper` is a dry run: the portal checks it and keeps
+   nothing. It prints the title, the authors and the whole abstract (read from the source's
+   `\begin{abstract}`). Read them with the author; an abstract the command cannot read, or one
+   that reads wrong, is given as a plain-text file with `--abstract <file>`.
+1. **Ask the author** for an explicit yes, then `npx paperlint submission new papers/my-paper --save`,
+   and do the printed "on the site" list with the author.
+2. **Read it.** `npx paperlint submission show papers/my-paper` — status, the PDF the portal holds,
+   and `match`: whether it is the local build. Rebuild first if the local PDF is stale.
+3. **Dry run the change.** `npx paperlint submission update papers/my-paper` (`--abstract <file>`,
+   `--submit` to mark it submitted). Exit 1 means the portal would refuse it — report why, stop.
+4. **Ask the author** for an explicit yes, then the same command with `--save`.
+5. **Prove it landed.** `show` again: `match` must read `yes — the portal holds this build`, and
+   the status must be what was intended. Anything else is not done — say so.
+
+🔴 `--save` creates or changes a real submission that reviewers will see: never without the
+author's yes in this conversation, never "to test", never because a dry run passed.
 
 ```bash
-npx paperlint submission show papers/<paper>
-npx paperlint submission update papers/<paper>
+npx paperlint build papers/my-paper
+# only while the paper has no submission id:
+npx paperlint submission new papers/my-paper
+# … the author reads the dry run and says yes …
+npx paperlint submission new papers/my-paper --save
+npx paperlint submission show papers/my-paper
+npx paperlint submission update papers/my-paper --submit
 # … the author reads the dry run and says yes …
-npx paperlint submission update papers/<paper> --save
-npx paperlint submission show papers/<paper>
+npx paperlint submission update papers/my-paper --submit --save
+npx paperlint submission show papers/my-paper
 ```
 
 ## Reading the answers
 
-- `match yes` is the only proof the reviewers get the local build; a status of `submitted` alone
-  says nothing about WHICH PDF.
-- `the portal refused (HTTP 401): …` — the token is missing, wrong or expired; `403` — the token
-  lacks the scope, or the deadline has passed for this change. The text after the colon is
-  HotCRP's own; quote it.
-- `SAVE WITHHELD by the portal` — HotCRP did not save; nothing changed.
+- `match yes` is the only proof the reviewers get the local build; `submitted` alone says nothing
+  about WHICH PDF.
+- `portal says: …` lines are the portal's own words; quote them.
+- `SAVE WITHHELD` or `NOTHING CREATED` — the portal saved nothing.
 
 ## What this skill does not do
 
-It does not decide whether the paper is ready (that is `harden-paper`), anonymize it, or fill the
-submission form's other fields (authors, conflicts) — see `submit-paper`.
+It does not decide whether the paper is ready (`harden-paper`), anonymize it, or set the portal's
+other fields — see `submit-paper`.