paperlint 10.4.1 → 11.0.0

package/scripts/refresh-deadlines/main.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * `npm run refresh-deadlines [-- --presets <dir>] [-- --summary <file.md>]`, which
+ * .github/workflows/deadlines.yml runs from source (no `dist/`). The composition root: the command
+ * line, the files, the clock, and HotCRP's adapter plugged into the port `refresh.ts` reads.
+ */
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hotcrpDeadlines } from "#src/adapters/hotcrp/index";
+import { presetsDir } from "#src/package-dirs";
+import { isMain } from "../../skills/paper-pipeline/scripts/consumer.mjs";
+import { runRefresh, type PresetFiles } from "./refresh.ts";
+
+/** `--presets <dir>` and `--summary <file>`; a flag without a value is no value. */
+export function argsOf(argv: readonly string[]) {
+  const value = (flag: string): string | null =>
+    argv.includes(flag) ? (argv[argv.indexOf(flag) + 1] ?? null) : null;
+  return {
+    presets: value("--presets") ?? presetsDir(),
+    summary: value("--summary"),
+  };
+}
+
+/** The `*.jsonc` presets in `dir`, on disk. */
+export const presetsIn = (dir: string): PresetFiles => ({
+  names: readdirSync(dir)
+    .filter((f) => f.endsWith(".jsonc"))
+    .toSorted(),
+  read: (name) => readFileSync(join(dir, name), "utf8"),
+  write: (name, text) => {
+    writeFileSync(join(dir, name), text);
+  },
+  path: (name) => join(dir, name),
+});
+
+/** Where the pull request's body is written: the `--summary` file, or nowhere. */
+export const summaryTo = (path: string | null) =>
+  path === null
+    ? null
+    : (text: string) => {
+        writeFileSync(path, text);
+      };
+
+// `isMain`, not a comparison with `file://${argv[1]}`: that is false through a symlink (consumer.mjs).
+if (isMain(import.meta.url)) {
+  const args = argsOf(process.argv.slice(2));
+  process.exit(
+    await runRefresh({
+      presets: presetsIn(args.presets),
+      portal: (site) => hotcrpDeadlines({ url: site }),
+      today: new Date().toISOString().slice(0, 10), // the clock, read at the edge
+      log: console.log,
+      summary: summaryTo(args.summary),
+    }),
+  );
+}

package/scripts/refresh-deadlines/refresh.test.ts

@@ -0,0 +1,287 @@
+/**
+ * The refresh's logic: what one preset becomes, what a run prints, writes and returns — over a
+ * fake VenueDeadlines port that answers plain domain values (how HotCRP's page is parsed is
+ * src/adapters/hotcrp/deadlines.test.ts's) and presets held in memory.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "vitest";
+import type { PortalDeadlines } from "#src/domain/deadline";
+import { err, ok, type Result } from "#src/domain/result";
+import type { PortalFailure } from "#src/domain/submission";
+import type { VenueDeadlines } from "#src/ports/venue-deadlines";
+import { parsePreset } from "#src/tex-requirements";
+import {
+  refreshPreset,
+  runRefresh,
+  withDeadlines,
+  type Outcome,
+  type PresetFiles,
+} from "./refresh.ts";
+
+const ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const PRESETS = join(ROOT, "presets");
+const MSR = join(PRESETS, "msr.jsonc");
+const msrText = readFileSync(MSR, "utf8");
+const readings = (text: string) => parsePreset(text, MSR).deadlines ?? [];
+/** MSR with its submission deadline two days before the portal's. */
+const earlier = msrText.replace(
+  '"at": "2026-10-21T11:59:59Z"',
+  '"at": "2026-10-19T04:00:00Z"',
+);
+/** Presets held in memory, by name: what a run reads, and what it writes back. */
+function inMemory(files: Readonly<Record<string, string>>) {
+  const written: Record<string, string> = {};
+  const presets: PresetFiles = {
+    names: Object.keys(files).toSorted(),
+    read: (name) => files[name] ?? "",
+    write: (name, text) => {
+      written[name] = text;
+    },
+    path: (name) => join(PRESETS, name),
+  };
+  return { presets, written };
+}
+
+/** What MSR 2027's portal lists — the readings presets/msr.jsonc holds. */
+const MSR_PAGE: PortalDeadlines = {
+  now: 1792434476,
+  open: true,
+  blind: true,
+  deadlines: [
+    {
+      what: "submission",
+      label: "Submission deadline",
+      at: "2026-10-21T11:59:59Z",
+    },
+    {
+      what: "resubmission",
+      label: "Resubmission deadline",
+      at: "2026-10-24T11:59:59Z",
+    },
+  ],
+};
+/** What AIDC 2026's portal lists — the readings presets/aidc.jsonc holds. */
+const AIDC_PAGE: PortalDeadlines = {
+  now: 1791194489,
+  open: true,
+  blind: true,
+  deadlines: [
+    {
+      what: "submission",
+      label: "Submission deadline",
+      at: "2026-10-03T11:59:59Z",
+    },
+    { what: "camera-ready", label: "camera-ready", at: "2026-10-31T11:59:59Z" },
+  ],
+};
+/** A portal that answers `answer`. */
+const answering =
+  (answer: Result<PortalDeadlines, PortalFailure>) => (): VenueDeadlines => ({
+    read: () => Promise.resolve(answer),
+  });
+/** Each site's page, by the URL the preset names. */
+const bySite = (url: string): VenueDeadlines =>
+  answering(ok(url.includes("acsac") ? AIDC_PAGE : MSR_PAGE))();
+
+/** The outcome, known to be of `kind` — or the test fails naming what it was. */
+function as<K extends Outcome["kind"]>(
+  o: Outcome,
+  kind: K,
+): Extract<Outcome, { kind: K }> {
+  const isKind = (x: Outcome): x is Extract<Outcome, { kind: K }> =>
+    x.kind === kind;
+  if (!isKind(o)) throw new Error(`expected ${kind}, got ${JSON.stringify(o)}`);
+  return o;
+}
+
+describe("withDeadlines — the `deadlines` value replaced by jsonc-parser, everything else as written", () => {
+  test("writing back the readings the file holds gives the file's own bytes", async () => {
+    expect(await withDeadlines(msrText, MSR, readings(msrText))).toBe(msrText);
+  });
+});
+
+test("a preset with a portal and no `deadlines` yet: each reading added, the block right after `portal`", async () => {
+  const start = msrText.indexOf("  // Read from the portal");
+  const end = msrText.indexOf("  ],\n", start) + "  ],\n".length;
+  const o = as(
+    await refreshPreset({
+      file: MSR,
+      text: msrText.slice(0, start) + msrText.slice(end),
+      portal: answering(ok(MSR_PAGE)),
+      today: "2026-10-19",
+    }),
+    "changed",
+  );
+  expect(o.changes).toEqual([
+    "submission: added 2026-10-21T11:59:59Z",
+    "resubmission: added 2026-10-24T11:59:59Z",
+  ]);
+  expect(readings(o.text)).toEqual(readings(msrText));
+  expect(o.text).toMatch(
+    /"url": "https:\/\/msr2027\.hotcrp\.com",\n {2}\},\n {2}"deadlines": \[/,
+  );
+});
+
+describe("refreshPreset on MSR 2027's page", () => {
+  test("the portal says what the preset says: unchanged", async () => {
+    const o = await refreshPreset({
+      file: MSR,
+      text: msrText,
+      portal: answering(ok(MSR_PAGE)),
+      today: "2026-10-06",
+    });
+    expect(o).toEqual({
+      kind: "unchanged",
+      url: "https://msr2027.hotcrp.com/deadlines",
+      notes: [],
+    });
+  });
+
+  test("the portal moved the submission: only that reading changes, with today's read day", async () => {
+    const o = as(
+      await refreshPreset({
+        file: MSR,
+        text: earlier,
+        portal: answering(ok(MSR_PAGE)),
+        today: "2026-10-20",
+      }),
+      "changed",
+    );
+    expect(o.changes).toEqual([
+      "submission: 2026-10-19T04:00:00Z → 2026-10-21T11:59:59Z",
+    ]);
+    // Only the deadlines block differs: the comments and every other key are the file's own.
+    expect(o.text).toBe(
+      msrText.replace(
+        '"read": "2026-10-19",\n    },\n    {\n      "what": "resubmission"',
+        '"read": "2026-10-20",\n    },\n    {\n      "what": "resubmission"',
+      ),
+    );
+  });
+});
+
+describe("refreshPreset — what it skips, and a portal it cannot read", () => {
+  test("a preset without a portal, or with one paperlint has no adapter for, is skipped", async () => {
+    const aisec = join(PRESETS, "aisec.jsonc");
+    const skipped = { kind: "skipped" };
+    expect(
+      await refreshPreset({
+        file: aisec,
+        text: readFileSync(aisec, "utf8"),
+        portal: answering(ok(MSR_PAGE)),
+        today: "2026-10-05",
+      }),
+    ).toEqual(skipped);
+    expect(
+      await refreshPreset({
+        file: MSR,
+        text: msrText.replace('"kind": "hotcrp"', '"kind": "easychair"'),
+        portal: answering(ok(MSR_PAGE)),
+        today: "2026-10-05",
+      }),
+    ).toEqual(skipped);
+  });
+
+  test.each<[string, PortalFailure, string]>([
+    [
+      "a site that answers 404",
+      {
+        kind: "refused",
+        httpStatus: 404,
+        messages: [
+          { message: "No such conference", field: null, status: null },
+        ],
+      },
+      "the portal refused (HTTP 404): No such conference",
+    ],
+    [
+      "a site that does not answer",
+      { kind: "unreachable", detail: "connect ECONNREFUSED" },
+      "the portal cannot be reached: connect ECONNREFUSED",
+    ],
+    [
+      "a page that is not the one expected",
+      { kind: "malformed", httpStatus: 200, detail: "no init" },
+      "the portal answered HTTP 200, but not as its API does: no init",
+    ],
+  ])("%s is reported, never guessed", async (_what, failure, why) => {
+    expect(
+      await refreshPreset({
+        file: MSR,
+        text: msrText,
+        portal: answering(err(failure)),
+        today: "2026-10-05",
+      }),
+    ).toEqual({
+      kind: "unreadable",
+      url: "https://msr2027.hotcrp.com/deadlines",
+      why,
+    });
+  });
+});
+
+describe("runRefresh — what it prints, writes and returns", () => {
+  test("nothing changed: one line, no preset written, exit 0", async () => {
+    const { presets, written } = inMemory(
+      Object.fromEntries(
+        readdirSync(PRESETS)
+          .filter((f) => f.endsWith(".jsonc"))
+          .map((f) => [f, readFileSync(join(PRESETS, f), "utf8")]),
+      ),
+    );
+    const lines: string[] = [];
+    const code = await runRefresh({
+      presets,
+      portal: bySite,
+      today: "2026-10-06",
+      log: (l) => lines.push(l),
+      summary: null,
+    });
+    expect([code, written]).toStrictEqual([0, {}]);
+    expect(lines.at(-1)).toMatch(
+      /^✓ no deadline changed: 2 preset\(s\) with a portal read, \d+ skipped$/,
+    );
+  });
+
+  test("a preset that does not parse is a defect of the repository: exit 1, naming it", async () => {
+    const lines: string[] = [];
+    const summaries: string[] = [];
+    const code = await runRefresh({
+      presets: inMemory({ "bad.jsonc": "{ nope" }).presets,
+      portal: bySite,
+      today: "2026-10-06",
+      log: (l) => lines.push(l),
+      summary: (text) => summaries.push(text),
+    });
+    expect(code).toBe(1);
+    expect(lines[0]).toMatch(
+      /^::error title=deadlines::bad\.jsonc does not parse: /,
+    );
+    expect(summaries[0]).toMatch(/^- 🔴 `bad\.jsonc` does not parse: /m);
+  });
+});
+
+describe("runRefresh — a changed preset", () => {
+  test("a changed preset is written back, and the summary names it", async () => {
+    const { presets, written } = inMemory({ "msr.jsonc": earlier });
+    const lines: string[] = [];
+    const summaries: string[] = [];
+    const code = await runRefresh({
+      presets,
+      portal: bySite,
+      today: "2026-10-20",
+      log: (l) => lines.push(l),
+      summary: (text) => summaries.push(text),
+    });
+    expect(code).toBe(0);
+    expect(readings(written["msr.jsonc"] ?? "")[0]?.at).toBe(
+      "2026-10-21T11:59:59Z",
+    );
+    expect(lines.at(-1)).toBe("1 preset(s) changed");
+    expect(summaries[0]).toMatch(
+      /^- `msr\.jsonc` \(https:\/\/msr2027\.hotcrp\.com\/deadlines\)\n {2}- submission: 2026-10-19T04:00:00Z → 2026-10-21T11:59:59Z$/m,
+    );
+  });
+});

package/scripts/refresh-deadlines/refresh.ts

@@ -0,0 +1,183 @@
+/**
+ * THE SHIPPED PRESETS' DEADLINES, RE-READ FROM THEIR PORTALS — the refresh's logic, behind the
+ * VenueDeadlines port and the preset files it is handed (`main.ts` plugs in the real ones). For
+ * every preset whose `portal` paperlint has an adapter for, the portal's deadlines are compared
+ * with the preset's `deadlines` (`compare.ts`), and a preset that changed is rewritten — the
+ * `deadlines` value only, by jsonc-parser, then Prettier as `npm run fmt` would.
+ *
+ * IT REPORTS, IT DOES NOT BLOCK. A portal that is down, gone or not the page expected is a
+ * `::warning::` line and a line in the summary, and the run exits 0 — the venue's outage is not this
+ * repository's defect, and the next day's run reads it again. A preset that does not parse IS:
+ * `::error::`, exit 1.
+ */
+import { applyEdits, modify } from "jsonc-parser";
+import { format } from "prettier";
+import type { IsoDate, Reading } from "#src/domain/deadline";
+import { supportedPortal } from "#src/domain/submission";
+import { messageOf } from "#src/domain/text";
+import type { VenueDeadlines } from "#src/ports/venue-deadlines";
+import { failureText } from "#src/submission";
+import { parsePreset } from "#src/tex-requirements";
+import { refreshReadings } from "./compare.ts";
+
+/** What happened to one preset. */
+export type Outcome =
+  | { readonly kind: "skipped" }
+  | { readonly kind: "broken"; readonly why: string }
+  | { readonly kind: "unreadable"; readonly url: string; readonly why: string }
+  | {
+      readonly kind: "unchanged";
+      readonly url: string;
+      readonly notes: readonly string[];
+    }
+  | {
+      readonly kind: "changed";
+      readonly url: string;
+      readonly text: string;
+      readonly changes: readonly string[];
+      readonly notes: readonly string[];
+    };
+
+/** The presets of one directory, by file name. */
+export interface PresetFiles {
+  /** The `*.jsonc` presets' names, sorted. */
+  readonly names: readonly string[];
+  readonly read: (name: string) => string;
+  readonly write: (name: string, text: string) => void;
+  /** Where a preset lives, as a message names it and Prettier infers its format from. */
+  readonly path: (name: string) => string;
+}
+
+/** The preset's text with its `deadlines` value set to `readings` (inserted after `portal` when absent). */
+export async function withDeadlines(
+  text: string,
+  file: string,
+  readings: readonly Reading[],
+): Promise<string> {
+  const edits = modify(text, ["deadlines"], readings, {
+    formattingOptions: { insertSpaces: true, tabSize: 2 },
+    getInsertionIndex: (keys) => keys.indexOf("portal") + 1,
+  });
+  // Prettier, for what jsonc-parser does not print: the trailing commas `npm run fmt:check` requires.
+  return format(applyEdits(text, edits), { filepath: file });
+}
+
+/** One preset: its portal read, its readings compared, its new text when one changed. */
+export async function refreshPreset(o: {
+  readonly file: string;
+  readonly text: string;
+  readonly portal: (site: string) => VenueDeadlines;
+  readonly today: IsoDate;
+}): Promise<Outcome> {
+  const parsed = ((): ReturnType<typeof parsePreset> | string => {
+    try {
+      return parsePreset(o.text, o.file);
+    } catch (e) {
+      return messageOf(e);
+    }
+  })();
+  if (typeof parsed === "string") return { kind: "broken", why: parsed };
+  const portal = parsed.portal === null ? null : supportedPortal(parsed.portal);
+  if (portal === null || !portal.ok) return { kind: "skipped" };
+  const url = `${portal.value.url}/deadlines`;
+  const page = await o.portal(portal.value.url).read();
+  if (!page.ok)
+    return { kind: "unreadable", url, why: failureText(page.error) };
+  const r = refreshReadings(parsed.deadlines ?? [], page.value, url, o.today);
+  if (r.changes.length === 0) return { kind: "unchanged", url, notes: r.notes };
+  const text = await withDeadlines(o.text, o.file, r.readings);
+  return { kind: "changed", url, text, changes: r.changes, notes: r.notes };
+}
+
+/** The lines one preset's outcome contributes: to the log (annotations included) and to the summary. */
+function report(
+  name: string,
+  o: Outcome,
+): { readonly log: readonly string[]; readonly md: readonly string[] } {
+  switch (o.kind) {
+    case "skipped":
+      return { log: [], md: [] };
+    case "broken":
+      return {
+        log: [`::error title=deadlines::${name} does not parse: ${o.why}`],
+        md: [`- 🔴 \`${name}\` does not parse: ${o.why}`],
+      };
+    case "unreadable":
+      return {
+        log: [
+          `::warning title=deadlines::${name}: could not read ${o.url} — ${o.why}`,
+        ],
+        md: [`- ⚠️ \`${name}\`: could not read ${o.url} — ${o.why}`],
+      };
+    case "unchanged":
+      return { log: o.notes.map((n) => `${name}: ${n}`), md: [] };
+    case "changed": {
+      const lines = [...o.changes, ...o.notes];
+      return {
+        log: lines.map((c) => `${name}: ${c}`),
+        md: [`- \`${name}\` (${o.url})`, ...lines.map((c) => `  - ${c}`)],
+      };
+    }
+  }
+}
+
+/** The pull request's body. */
+const summaryOf = (today: IsoDate, lines: readonly string[]): string =>
+  [
+    `The venue presets' deadlines, re-read on ${today} from each preset's portal by \`.github/workflows/deadlines.yml\` (\`scripts/refresh-deadlines/\`). A reading whose value changed carries today's \`read\` day; the others keep theirs.`,
+    "",
+    ...lines,
+    "",
+    "Merging releases a patch; papers get the new dates through their normal update of paperlint.",
+    "",
+  ].join("\n");
+
+/** What a refresh run needs: the presets, how to read a portal, the day, where to print. */
+export interface RefreshDeps {
+  readonly presets: PresetFiles;
+  readonly portal: (site: string) => VenueDeadlines;
+  readonly today: IsoDate;
+  readonly log: (line: string) => void;
+  /** Where the pull request's body goes; null: nowhere. */
+  readonly summary: ((text: string) => void) | null;
+}
+
+/** Every preset, refreshed — a changed one written back. */
+const outcomesOf = (
+  d: RefreshDeps,
+): Promise<readonly { readonly name: string; readonly out: Outcome }[]> =>
+  Promise.all(
+    d.presets.names.map(async (name) => {
+      const out = await refreshPreset({
+        file: d.presets.path(name),
+        text: d.presets.read(name),
+        portal: d.portal,
+        today: d.today,
+      });
+      if (out.kind === "changed") d.presets.write(name, out.text);
+      return { name, out };
+    }),
+  );
+
+/** Every preset refreshed, reported to the log and the summary. 0 unless a preset does not parse. */
+export async function runRefresh(d: RefreshDeps): Promise<number> {
+  const outcomes = await outcomesOf(d);
+  const reports = outcomes.map(({ name, out }) => report(name, out));
+  const count = (k: Outcome["kind"]) =>
+    outcomes.filter((x) => x.out.kind === k).length;
+  [
+    ...reports.flatMap((r) => r.log),
+    count("changed") === 0
+      ? `✓ no deadline changed: ${String(count("unchanged"))} preset(s) with a portal read, ${String(count("skipped"))} skipped`
+      : `${String(count("changed"))} preset(s) changed`,
+  ].forEach((l) => {
+    d.log(l);
+  });
+  d.summary?.(
+    summaryOf(
+      d.today,
+      reports.flatMap((r) => r.md),
+    ),
+  );
+  return count("broken") > 0 ? 1 : 0;
+}

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`.