Release: cover page at publication, sponsor logo approval

- register --live adds the Institute's cover edition beside the published
PDF in the same push. A cover it cannot make is reported in the log, the
state and the curator ping, and the page still publishes.
- The cover tool handles papers registered under the Institute prefix as
well as earlier records. The cover names the journal, volume, article
number, dates and licence with the page's own citation and matches the
manuscript's page size, and the tool checks the result before replacing
anything.
- Sponsor logo uploads are held for the curator's approval; --apply reviews
a held upload and publishes it.

crossref_deposit.py

@@ -69,6 +69,8 @@ LICENSE_URLS = {
     "cc-by-sa-4.0": "https://creativecommons.org/licenses/by-sa/4.0/",
     "cc0-1.0": "https://creativecommons.org/publicdomain/zero/1.0/",
 }
+# Adds the 1-page ICSAC cover: public/papers/<sub_id>.pdf -> <sub_id>-icsac.pdf.
+COVER_TOOL = Path(_REPO_ROOT) / "tools" / "wrap-paper-pdf.py"
 
 
 def _write_json_atomic(path, data) -> None:
@@ -743,7 +745,8 @@ def register(sub_dir: Path, *, live: bool = False, override_window: bool = False
       1. re-stage the XML under the reserved DOI: publication_date = today and the
          landing slug re-derived -- the deposit describes registration day
       2. Crossref deposit; poll until OUR DOI reads Success   -> crossref_registered_at
-      3. /publications push (+ PDF, + public review record)    -> publications_pushed_at
+      3. /publications push (+ PDF and its ICSAC cover edition, + public review record)
+                                                               -> publications_pushed_at
       4. Zenodo archive publish (preflight: draft carries our DOI) -> zenodo_published_at
       5. author "published" notice DRAFTED to Gmail             -> author_drafted_at
       6. one curator ping that says what actually happened
@@ -865,6 +868,7 @@ def register(sub_dir: Path, *, live: bool = False, override_window: bool = False
             _save_staged()
             state = json.loads(state_p.read_text())
         outcome["landing"] = state.get("publications_url")
+        outcome["cover"] = _cover_line(state.get("cover"), state.get("publications_slug"))
 
         # 4. Zenodo archive under the same DOI
         if not ck.get("zenodo_published_at"):
@@ -905,6 +909,7 @@ def register(sub_dir: Path, *, live: bool = False, override_window: bool = False
     # 6. the truthful ping
     _ping(f"DOI REGISTERED for {sub_dir.name}: https://doi.org/{doi}\n"
           f"Landing: {outcome.get('landing') or '(publications not configured)'}\n"
+          f"Cover page: {outcome.get('cover')}\n"
           f"Zenodo archive: {outcome.get('archive')}\n"
           f"ICSAC Zenodo community: {outcome.get('community') or 'not attempted'}\n"
           f"Author 'published' email: {outcome['author_draft']}"
@@ -976,6 +981,64 @@ def _landing(slug: str) -> str:
     return publications.publications_url(slug)
 
 
+def _deposited_dates(xml_path: Path) -> tuple[Optional[_dt.date], Optional[_dt.date]]:
+    """(acceptance_date, publication_date) exactly as deposited: the first
+    publication_date with a day is the article's (the issue's carries a year only)."""
+    def _d(el) -> Optional[_dt.date]:
+        try:
+            return _dt.date(int(el.findtext(_q("year"))), int(el.findtext(_q("month"))), int(el.findtext(_q("day"))))
+        except (TypeError, ValueError):
+            return None
+    try:
+        root = ET.parse(xml_path).getroot()
+    except (OSError, ET.ParseError):
+        return None, None
+    acc = next((d for d in map(_d, root.iter(_q("acceptance_date"))) if d), None)
+    pub = next((d for d in map(_d, root.iter(_q("publication_date"))) if d), None)
+    return acc, pub
+
+
+def _make_cover(sub_dir: Path, slug: str, *, log) -> dict:
+    """Run tools/wrap-paper-pdf.py on the PDF just copied to the website tree.
+    Returns {"file", "made_at", "path"} or {"error", "at"}; never raises."""
+    import subprocess
+    import publications
+    sub_id = sub_dir.name
+    out = Path(publications.WEBSITE_REPO) / "public" / "papers" / f"{sub_id}-icsac.pdf"
+    acc, pub = _deposited_dates(sub_dir / "crossref" / "deposit.xml")
+    cmd = [sys.executable, str(COVER_TOOL), "--slug", slug]
+    if acc:
+        cmd += ["--accepted", acc.isoformat()]
+    if pub:
+        cmd += ["--published", pub.isoformat()]
+    started = time.time()
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True, timeout=300,
+                           env=dict(os.environ, ICSAC_WEBSITE_REPO=publications.WEBSITE_REPO))
+        ok = r.returncode == 0 and out.exists() and out.stat().st_mtime >= started - 1
+        said = [ln for ln in (r.stderr or "").splitlines() if ln.startswith("cover not made: ")]
+        tail = (r.stderr or "").strip().splitlines()
+        why = (said[-1][len("cover not made: "):] if said else
+               f"the tool exited 0 but did not write {out.name}" if r.returncode == 0 else
+               tail[-1] if tail else f"the tool exited {r.returncode}")
+    except Exception as exc:
+        ok, why = False, f"{type(exc).__name__}: {exc}"
+    if ok:
+        log(f"  crossref: cover page made -> /papers/{out.name}")
+        return {"file": f"/papers/{out.name}", "made_at": _now_iso(), "path": str(out)}
+    log(f"  crossref: COVER NOT MADE for {sub_id}: {why[:300]}")
+    return {"error": why[:300], "at": _now_iso()}
+
+
+def _cover_line(cover: Optional[dict], slug: Optional[str]) -> str:
+    if not cover:
+        return "not recorded"
+    if cover.get("file"):
+        return f"made ({cover['file']})"
+    return (f"NOT MADE ({cover.get('error')}). The page links the bare PDF until it exists: fix, run "
+            f"tools/wrap-paper-pdf.py --slug {slug or '<slug>'}, then commit + push the website")
+
+
 def _push_publications(sub_dir: Path, submission: dict, doi: str, *, log) -> dict:
     """Upsert /publications, copy the PDF to the website tree, stage the public
     review, push. Mirrors publish_watcher._register_published for Zenodo."""
@@ -1017,6 +1080,7 @@ def _push_publications(sub_dir: Path, submission: dict, doi: str, *, log) -> dic
         log("  crossref: publications registry not configured; landing page NOT pushed")
         return {}
     extra = []
+    cover: dict = {}
     if publications.WEBSITE_REPO:
         pdf_src = sub_dir / "paper.pdf"
         if pdf_src.exists():
@@ -1024,6 +1088,15 @@ def _push_publications(sub_dir: Path, submission: dict, doi: str, *, log) -> dic
             dest.parent.mkdir(parents=True, exist_ok=True)
             shutil.copyfile(pdf_src, dest)
             extra.append(str(dest))
+            # The ICSAC edition beside the bare file, in the same commit. A failed
+            # cover never blocks the page (it links the bare PDF until one exists),
+            # and it is never silent: it reaches the log, state.json and the ping.
+            cover = _make_cover(sub_dir, entry["slug"], log=log)
+            if cover.get("path"):
+                extra.append(cover["path"])
+        else:
+            cover = {"error": f"no paper.pdf in {sub_dir.name}, so no PDF was published", "at": _now_iso()}
+            log(f"  crossref: COVER NOT MADE for {sub_id}: {cover['error']}")
     review_md, rqc_md = publications.stage_public_review_for_slug(
         sub_id, entry["slug"], config.REVIEWS_DIR, approved=True)   # (review_key, slug, dir) -- same call as publish_watcher
     # The public review record travels in the same commit as the registry entry;
@@ -1061,6 +1134,8 @@ def _push_publications(sub_dir: Path, submission: dict, doi: str, *, log) -> dic
     state = json.loads(state_p.read_text()) if state_p.exists() else {}
     state["publications_slug"] = entry["slug"]
     state["publications_url"] = publications.publications_url(entry["slug"])
+    if cover:
+        state["cover"] = {k: v for k, v in cover.items() if k != "path"}
     _write_json_atomic(state_p, state)
     log(f"  crossref: publications entry pushed -> {state['publications_url']}")
     return entry

intake/scripts/test_cover_pdf.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""Checks for the ICSAC cover edition of a published PDF (2026-10-18): a paper
+without a Zenodo record_id gets wrapped (<sub_id>.pdf -> <sub_id>-icsac.pdf),
+the cover names the journal, volume, article number, dates, licence and the
+page's citation, the author's pages and the bare file are left untouched,
+register --live makes the cover in the same push, and a failed cover is
+reported (log, state.json, ping) without blocking the page.
+Offline: no network, no mail, no pings; every write lands in one temporary
+directory that is removed at the end, pass or fail. Run from the repo root
+with the venv:
+    .venv/bin/python intake/scripts/test_cover_pdf.py
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import types
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+TOOL = ROOT / "tools" / "wrap-paper-pdf.py"
+
+failures: list[str] = []
+
+
+def check(cond: bool, name: str) -> None:
+    print(("  ok   " if cond else "  FAIL ") + name)
+    if not cond:
+        failures.append(name)
+
+
+def sha(p: Path) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()
+
+
+def flat(text: str) -> str:
+    return re.sub(r"\s+", " ", text or "").strip()
+
+
+def squeeze(text: str) -> str:
+    """Text extraction splits words at kerned pairs ("T est"): compare without spaces."""
+    return re.sub(r"\s+", "", text or "")
+
+
+PERSISTENCE_TS = """export const PERSISTENCE_TITLE = 'Persistence';
+export const PERSISTENCE_VOLUMES: ReadonlyArray<{ volume: string; from: string; year: string }> = [
+  { volume: '1', from: '2026-01-01', year: '2026' },
+];
+export function isInstituteDoi(doi: string): boolean {
+  return /^10\\.5555\\//i.test(bare(doi));
+}
+"""
+CC_BY = "https://creativecommons.org/licenses/by/4.0/"
+DEPOSIT_XML = """<?xml version="1.0"?>
+<doi_batch xmlns="http://www.crossref.org/schema/5.4.0"><body><journal>
+<journal_issue><publication_date media_type="online"><year>2026</year></publication_date></journal_issue>
+<journal_article><publication_date media_type="online"><month>03</month><day>03</day><year>2026</year></publication_date>
+<acceptance_date><month>03</month><day>02</day><year>2026</year></acceptance_date></journal_article>
+</journal></body></doi_batch>"""
+
+tmp = Path(tempfile.mkdtemp(prefix="cover-pdf-"))
+try:
+    import weasyprint
+    import pypdf
+    from PIL import Image
+
+    def make_site(name: str) -> Path:
+        site = tmp / name
+        (site / "src" / "data").mkdir(parents=True)
+        (site / "src" / "lib").mkdir(parents=True)
+        (site / "public" / "papers").mkdir(parents=True)
+        (site / "src" / "lib" / "persistence.ts").write_text(PERSISTENCE_TS)
+        Image.new("RGBA", (330, 200), (139, 94, 60, 255)).save(site / "public" / "logo_trans_ICSAC_notext.png")
+        return site
+
+    def make_pdf(path: Path, pages: int = 2) -> None:
+        body = "".join(f'<p style="page-break-after: always">Manuscript page {i + 1}. '
+                       f'<a href="https://example.com/{i}">a link</a></p>' for i in range(pages))
+        path.write_bytes(weasyprint.HTML(string=f"<html><body>{body}</body></html>").write_pdf())
+
+    def run_tool(site: Path, *args: str) -> subprocess.CompletedProcess:
+        return subprocess.run([sys.executable, str(TOOL), *args], capture_output=True, text=True,
+                              env=dict(os.environ, ICSAC_WEBSITE_REPO=str(site)), timeout=300)
+
+    PAPER = {"slug": "a-test-article", "sub_id": "ICSAC-SUB-09999", "title": "A Test Article",
+             "authors": ["Ada B. Lovelace", "Alan Turing", "Grace Hopper"], "doi": "10.5555/icsac.2026.999",
+             "accepted_date": "2026-03-03", "source": "submission-pdf", "license_url": CC_BY}
+
+    # ── 1. a paper without a record_id gets wrapped ──────────────────────────
+    print("1. a paper without a Zenodo record_id")
+    site = make_site("site1")
+    (site / "src" / "data" / "accepted.json").write_text(json.dumps([PAPER]))
+    bare = site / "public" / "papers" / "ICSAC-SUB-09999.pdf"
+    make_pdf(bare)
+    before = sha(bare)
+    r = run_tool(site, "--slug", "a-test-article", "--accepted", "2026-03-02", "--published", "2026-03-03")
+    out = site / "public" / "papers" / "ICSAC-SUB-09999-icsac.pdf"
+    check(r.returncode == 0 and out.exists(), "exit 0 and <sub_id>-icsac.pdf written beside the bare file")
+    check(sha(bare) == before, "the bare file is byte-for-byte unchanged")
+    got, src = pypdf.PdfReader(str(out)), pypdf.PdfReader(str(bare))
+    check(len(got.pages) == len(src.pages) + 1, "one page added, no more")
+    p1 = flat(got.pages[0].extract_text())
+    for want, what in (("Persistence", "names the journal"),
+                       ("VOLUME 1 (2026)", "names the volume and year"),
+                       ("ARTICLE 999", "names the article number from the Institute DOI"),
+                       ("10.5555/icsac.2026.999", "carries the DOI"),
+                       ("03/02/2026", "carries the acceptance date"),
+                       ("Published online", "labels the publication date"),
+                       ("03/03/2026", "carries the publication date"),
+                       ("CC BY 4.0", "carries the licence"),
+                       ("https://icsacinstitute.org/publications/a-test-article", "carries the editorial record URL"),
+                       ("Reviewed by the ICSAC panel", "keeps the open-review line"),
+                       ("does not modify the author's manuscript", "keeps the does-not-modify paragraph")):
+        check(want.lower() in p1.lower(), f"cover {what}")   # labels print in small caps (CSS uppercase)
+    check("peer review" not in p1.lower() and "peer-review" not in p1.lower(), "cover never says peer review")
+    check(squeeze("Lovelace, A. B., Turing, A., & Hopper, G. (2026). A Test Article. Persistence, 1, Article 999. "
+                  "https://doi.org/10.5555/icsac.2026.999") in squeeze(p1), "cite-as line in the page's journal format")
+    same = all(got.pages[i + 1].get_contents().get_data() == src.pages[i].get_contents().get_data()
+               for i in range(len(src.pages)))
+    check(same, "pages 2..n carry the author's content streams unchanged")
+    check(all(len(got.pages[i + 1].get("/Annots") or []) == len(src.pages[i].get("/Annots") or [])
+              for i in range(len(src.pages))), "the author's link annotations are kept")
+    hv = lambda rd: tuple(map(int, re.match(r"%PDF-(\d+)\.(\d+)", rd.pdf_header).groups()))
+    check(hv(got) >= hv(src), f"PDF header {got.pdf_header} is not older than the source's {src.pdf_header}")
+    imgs = [(x.image.width, x.image.height) for x in got.pages[0].images]
+    check(imgs and all(w <= 400 and h <= 250 for w, h in imgs), f"the cover carries only the small logo {imgs}")
+
+    # ── 2. a Zenodo-route paper: first publication before acceptance ─────────
+    print("2. a Zenodo-route paper")
+    z = {"slug": "a-zenodo-paper", "record_id": "12345", "title": "A Zenodo Paper", "authors": ["Test Author"],
+         "doi": "10.5281/zenodo.12345", "accepted_date": "2026-05-04", "source": "zenodo-community",
+         "license_url": CC_BY}
+    (site / "src" / "data" / "accepted.json").write_text(json.dumps([PAPER, z]))
+    make_pdf(site / "public" / "papers" / "12345.pdf", pages=1)
+    r = run_tool(site, "--slug", "a-zenodo-paper", "--published", "2026-02-02")
+    p1 = flat(pypdf.PdfReader(str(site / "public" / "papers" / "12345-icsac.pdf")).pages[0].extract_text())
+    check(r.returncode == 0, "exit 0")
+    check("ARTICLE" not in p1.upper().split("VOLUME 1 (2026)")[1][:20], "no article number for a Zenodo DOI")
+    check(p1.upper().find("FIRST PUBLISHED") < p1.upper().find("ACCEPTED") and "02/02/2026, on Zenodo" in p1,
+          "dates in the order they happened, the first publication named as Zenodo's")
+    check(squeeze("Author, T. (2026). A Zenodo Paper. Zenodo. https://doi.org/10.5281/zenodo.12345. "
+                  "Reviewed by the ICSAC panel.") in squeeze(p1), "cite-as line in the page's Zenodo format")
+
+    # ── 3. failures are reported, never silent, and write nothing ────────────
+    print("3. failures")
+    bad = dict(PAPER, slug="no-licence", sub_id="ICSAC-SUB-09998", license_url="https://example.com/mine")
+    (site / "src" / "data" / "accepted.json").write_text(json.dumps([PAPER, z, bad]))
+    make_pdf(site / "public" / "papers" / "ICSAC-SUB-09998.pdf", pages=1)
+    b_before = sha(site / "public" / "papers" / "ICSAC-SUB-09998.pdf")
+    r = run_tool(site, "--slug", "no-licence", "--accepted", "2026-03-02", "--published", "2026-03-03")
+    check(r.returncode == 1 and "cover not made" in r.stderr and "licence" in r.stderr,
+          "an unknown licence: exit 1, 'cover not made' with the reason")
+    check(not (site / "public" / "papers" / "ICSAC-SUB-09998-icsac.pdf").exists(), "nothing written for it")
+    check(sha(site / "public" / "papers" / "ICSAC-SUB-09998.pdf") == b_before, "its bare file untouched")
+    missing = dict(PAPER, slug="no-pdf", sub_id="ICSAC-SUB-09997")
+    (site / "src" / "data" / "accepted.json").write_text(json.dumps([missing]))
+    r = run_tool(site, "--slug", "no-pdf", "--accepted", "2026-03-02", "--published", "2026-03-03")
+    check(r.returncode == 1 and "source PDF missing" in r.stderr, "a missing source PDF: exit 1 with the reason")
+    nokey = {k: v for k, v in PAPER.items() if k != "sub_id"} | {"slug": "doi-only"}
+    (site / "src" / "data" / "accepted.json").write_text(json.dumps([missing, nokey]))
+    r = run_tool(site, "--all")
+    check(r.returncode == 1 and "nothing to cover" in r.stdout and "doi-only" in r.stdout,
+          "--all names a paper with no PDF on the site instead of skipping it quietly")
+    check("no-pdf" in r.stderr and "1 not made" in r.stdout, "--all reports the failure and counts it")
+
+    # ── 4. the citation port matches the page's rules (cite.ts) ──────────────
+    print("4. citation port")
+    spec = importlib.util.spec_from_file_location("wrap_paper_pdf", TOOL)
+    wp = importlib.util.module_from_spec(spec); spec.loader.exec_module(wp)
+    vols = [{"volume": "1", "from": "2026-01-01", "year": "2026"}, {"volume": "2", "from": "2027-06-01", "year": "2027"}]
+    check(wp.format_author_apa("Grace B. Hopper") == "Hopper, G. B.", "APA: initials, kept initial")
+    check(wp.format_author_apa("Hopper, Grace") == "Hopper, Grace", "APA: 'Last, First' kept as written")
+    check(wp.format_author_apa("Plato") == "Plato", "APA: a single name kept")
+    check(wp.authors_apa_list([]) == "Anonymous", "no authors -> Anonymous")
+    check(wp.authors_apa_list(["A B", "C D"]) == "B, A. & D, C.", "two authors joined with &")
+    check(wp.volume_for("2027-07-01", vols)["volume"] == "2", "volume from the table by acceptance date")
+    check(wp.article_number_for("doi:10.5555/icsac.2026.012", "10.5555") == "012", "article number from the DOI sequence")
+    check(wp.article_number_for("10.5281/zenodo.1", "10.5555") is None, "no article number for a Zenodo DOI")
+    real_ts = (Path(os.environ.get("ICSAC_WEBSITE_REPO", "")) / "src" / "lib" / "persistence.ts")
+    if real_ts.exists():   # the operator checkout: the prefix the live page uses is read, not assumed
+        check(re.fullmatch(r"10\.\d{4,9}", wp.Site(real_ts.parents[2]).journal()["prefix"] or "") is not None,
+              "the website's persistence.ts yields a DOI prefix")
+    site_j = wp.Site(site).journal()
+    check(site_j["prefix"] == "10.5555" and site_j["title"] == "Persistence", "the fixture's prefix and title are read")
+
+    # ── 5. register --live makes the cover in the same push ──────────────────
+    print("5. register --live")
+    import publications as pub
+    import crossref_deposit as cd
+    from intake import author_approval
+    sys.modules["stats"] = types.SimpleNamespace(
+        compute_stats=lambda *a, **k: (_ for _ in ()).throw(RuntimeError("stats stubbed")))
+    pushed: list[list[str]] = []
+    pings: list[str] = []
+    pub.READY_DIR = str(tmp / "ready-to-publish")
+    pub.stage_public_review_for_slug = lambda *a, **k: (None, None)
+    pub.commit_and_push = lambda *a, **k: pushed.append(list(k.get("extra_paths") or []))
+    cd.stage = lambda *a, **k: None
+    cd.validate_xml = lambda b: None
+    cd.deposit = lambda *a, **k: "batch-1"
+    cd.poll_result = lambda *a, **k: {"status": "completed", "success": 1, "failure": 0}
+    cd._ping = pings.append
+    cd._publish_zenodo_archive = lambda *a, **k: None
+    cd._notify_author = lambda *a, **k: True
+    author_approval.gate = lambda *a, **k: (True, "approved (stub)")
+
+    def make_sub(name: str, site: Path, with_pdf: bool = True) -> Path:
+        sub = tmp / name
+        (sub / "crossref").mkdir(parents=True)
+        (sub / "submission.json").write_text(json.dumps({
+            "sub_id": name, "title": f"Article {name}", "abstract": "A", "license": "cc-by-4.0",
+            "creators": [{"name": "Lovelace, Ada"}], "form": {"name": "Ada Lovelace"}}))
+        (sub / "state.json").write_text(json.dumps({"decision": "accept", "state": "completed"}))
+        (sub / "crossref" / "deposit.xml").write_text(DEPOSIT_XML)
+        (sub / "crossref" / "staged.json").write_text(json.dumps({"doi": "10.5555/icsac.2026.998", "registered": False}))
+        if with_pdf:
+            make_pdf(sub / "paper.pdf", pages=2)
+        pub.WEBSITE_REPO = str(site)
+        pub.REGISTRY_PATH = str(site / "src" / "data" / "accepted.json")
+        return sub
+
+    check(cd._deposited_dates(Path(tmp / "nope.xml")) == (None, None), "no deposit file -> no dates, no crash")
+    site5 = make_site("site5"); (site5 / "src" / "data" / "accepted.json").write_text("[]")
+    sub = make_sub("ICSAC-SUB-09990", site5)
+    acc, pubd = cd._deposited_dates(sub / "crossref" / "deposit.xml")
+    check((str(acc), str(pubd)) == ("2026-03-02", "2026-03-03"), "the deposited dates are read (the article's, not the issue's year)")
+    cd.register(sub, live=True, log=lambda m: None)
+    cov = site5 / "public" / "papers" / "ICSAC-SUB-09990-icsac.pdf"
+    bare5 = site5 / "public" / "papers" / "ICSAC-SUB-09990.pdf"
+    check(cov.exists(), "register --live wrote <sub_id>-icsac.pdf")
+    check(sha(bare5) == sha(sub / "paper.pdf"), "the bare copy is the author's paper.pdf, untouched")
+    check(pushed and str(cov) in pushed[-1] and str(bare5) in pushed[-1], "both files ride the same commit")
+    st = json.loads((sub / "state.json").read_text())
+    check(st.get("cover", {}).get("file") == "/papers/ICSAC-SUB-09990-icsac.pdf", "state.json records the cover")
+    check(pings and "Cover page: made (/papers/ICSAC-SUB-09990-icsac.pdf)" in pings[-1], "the ping says the cover was made")
+    p1 = flat(pypdf.PdfReader(str(cov)).pages[0].extract_text())
+    check("03/02/2026" in p1 and "03/03/2026" in p1, "the cover carries the deposited dates")
+
+    # ── 6. a failed cover is reported and does not block the page ────────────
+    print("6. a failed cover")
+    failing = tmp / "failing-tool.py"
+    failing.write_text("import sys\nprint('cover not made: boom (stub)', file=sys.stderr)\nsys.exit(1)\n")
+    real_tool = cd.COVER_TOOL
+    cd.COVER_TOOL = failing
+    try:
+        site6 = make_site("site6"); (site6 / "src" / "data" / "accepted.json").write_text("[]")
+        sub = make_sub("ICSAC-SUB-09991", site6)
+        logs: list[str] = []
+        out = cd.register(sub, live=True, log=logs.append)
+        ck = json.loads((sub / "crossref" / "staged.json").read_text())["checkpoints"]
+        st = json.loads((sub / "state.json").read_text())
+        check(bool(ck.get("publications_pushed_at")) and out.get("author_draft") == "drafted",
+              "the page is still published and the later steps run")
+        check(st.get("cover", {}).get("error") == "boom (stub)", "state.json records why")
+        check(any("COVER NOT MADE" in m and "boom" in m for m in logs), "the log says COVER NOT MADE with the reason")
+        check("Cover page: NOT MADE (boom (stub))" in pings[-1] and "wrap-paper-pdf.py --slug" in pings[-1],
+              "the ping says NOT MADE and how to make it")
+        check(not (site6 / "public" / "papers" / "ICSAC-SUB-09991-icsac.pdf").exists()
+              and all("icsac.pdf" not in p for p in pushed[-1]), "no cover file written or committed")
+    finally:
+        cd.COVER_TOOL = real_tool
+    site7 = make_site("site7"); (site7 / "src" / "data" / "accepted.json").write_text("[]")
+    sub = make_sub("ICSAC-SUB-09992", site7, with_pdf=False)
+    cd.register(sub, live=True, log=lambda m: None)
+    check("Cover page: NOT MADE (no paper.pdf" in pings[-1], "no paper.pdf: reported, not skipped")
+finally:
+    shutil.rmtree(tmp, ignore_errors=True)
+
+print()
+if failures:
+    print(f"FAILED: {len(failures)}")
+    for f in failures:
+        print("  - " + f)
+    sys.exit(1)
+print("ALL GREEN")

intake/scripts/test_sponsor_logo_hold.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Checks that a Stripe sponsor-logo upload is held for the curator (nothing
+publishes without the curator's approval) and that --apply
+publishes it only on the typed word "publish".
+Offline: Stripe, Telegram and the curator ping are stubbed; the website repo
+and its remote are temporary git repositories, removed at the end, pass or fail.
+Run from the repo root:
+    .venv/bin/python intake/scripts/test_sponsor_logo_hold.py
+"""
+from __future__ import annotations
+
+import asyncio
+import builtins
+import inspect
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import types
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+
+from fastapi import HTTPException  # noqa: E402
+
+failures: list[str] = []
+
+
+def check(cond: bool, name: str) -> None:
+    print(("  ok   " if cond else "  FAIL ") + name)
+    if not cond:
+        failures.append(name)
+
+
+def git(repo: Path, *args: str) -> str:
+    return subprocess.run(["git", "-c", "user.email=t@example.com", "-c", "user.name=t", *args],
+                          cwd=repo, capture_output=True, text=True, check=True).stdout
+
+
+class FakeUpload:
+    def __init__(self, data: bytes):
+        self.data = data
+
+    async def read(self, n: int = -1) -> bytes:
+        return self.data[:n] if n and n > 0 else self.data
+
+
+PNG = b"\x89PNG\r\n\x1a\n" + b"\x00" * 64
+SVG = b'<svg xmlns="http://www.w3.org/2000/svg"><rect width="1" height="1" fill="#000"/></svg>'
+BAD_SVG = b'<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>'
+SESSION_ID = "cs_test_abc123"
+
+tmp = Path(tempfile.mkdtemp(prefix="sponsor-logo-hold-"))
+real_stdin, real_input = sys.stdin, builtins.input
+try:
+    from intake import sponsor_logo as sl
+    import notify
+
+    remote = tmp / "remote.git"
+    subprocess.run(["git", "init", "-q", "--bare", "-b", "main", str(remote)], check=True)
+    site = tmp / "site"
+    subprocess.run(["git", "clone", "-q", str(remote), str(site)], check=True, capture_output=True)
+    git(site, "checkout", "-q", "-b", "main")
+    (site / "src" / "data").mkdir(parents=True)
+    (site / "public" / "supporter-logos").mkdir(parents=True)
+    (site / "public" / "supporter-logos" / ".keep").write_text("")
+    yaml_path = site / "src" / "data" / "supporters.yaml"
+    yaml_path.write_text(sl._render_supporters({"supporters": [
+        {"display_name": "Example Sponsor Co", "tier": "sponsor", "joined": "2026-10-01", "status": "active",
+         "stripe_sub": "sub_example", "website_url": "https://example.com", "logo_pending": True}]}))
+    git(site, "add", "-A")
+    git(site, "commit", "-q", "-m", "seed")
+    git(site, "push", "-q", "-u", "origin", "main")
+
+    sl.WEBSITE_REPO = site
+    sl.LOGO_DIR = site / "public" / "supporter-logos"
+    sl.SUPPORTERS_YAML = yaml_path
+    sl.READY_DIR = tmp / "ready"
+    sl._retrieve_checkout_session = lambda sid: {
+        "mode": "subscription", "payment_status": "paid",
+        "subscription": {"id": "sub_example", "status": "active",
+                         "items": {"data": [{"price": {"product": sl.SPONSOR_PRODUCT_ID}, "current_period_end": 4_102_444_800}]}},
+        "custom_fields": [{"key": "display_name", "text": {"value": "Example Sponsor Co"}},
+                          {"key": "website_url", "text": {"value": "example.com"}}]}
+    pings: list[str] = []
+    notify.send_to_curator = lambda message, **k: (pings.append(message), True)[1]
+    images: list[tuple[str, str]] = []
+    sl._send_logo_to_telegram = lambda image, caption: (images.append((image.name, caption)), True)[1]
+    seed_head = git(site, "rev-parse", "HEAD").strip()
+    seed_yaml = yaml_path.read_text()
+
+    def upload(data: bytes) -> dict:
+        return asyncio.run(sl.handle_sponsor_logo(None, SESSION_ID, FakeUpload(data), b""))
+
+    print("1. an upload is held, not published")
+    out = upload(PNG)
+    held_json = sl.READY_DIR / f"{sl.STAGE_PREFIX}{__import__('hashlib').sha256(SESSION_ID.encode()).hexdigest()[:8]}.json"
+    check(out.get("ok") is True and out.get("held") is True, "the sponsor gets a success answer marked held")
+    check(git(site, "status", "--porcelain") == "", "the website repo is untouched")
+    check(yaml_path.read_text() == seed_yaml, "supporters.yaml is unchanged")
+    check(sorted(p.name for p in sl.LOGO_DIR.iterdir()) == [".keep"], "no logo file reaches the site")
+    check(git(site, "rev-parse", "HEAD").strip() == seed_head, "no commit was made")
+    check(held_json.exists() and held_json.with_suffix(".png").exists(), "the logo and its listing wait in ready-to-publish")
+    rec = json.loads(held_json.read_text())
+    check(rec["display_name"] == "Example Sponsor Co" and rec["website_url"] == "https://example.com"
+          and rec["stripe_sub"] == "sub_example", "the held listing carries the Stripe-verified details")
+    check(len(pings) == 1 and "Example Sponsor Co" not in pings[0] and "--apply" in pings[0],
+          "one curator ping, with no sponsor name, naming the apply command")
+    check(len(images) == 1 and images[0][0].endswith(".png") and "Example Sponsor Co" in images[0][1],
+          "the image itself goes to the curator's Telegram")
+
+    print("2. a re-upload replaces the held one")
+    upload(SVG)
+    check(held_json.with_suffix(".svg").exists() and not held_json.with_suffix(".png").exists(),
+          "the SVG replaced the held PNG")
+    check(json.loads(held_json.read_text())["logo_ext"] == "svg", "the held listing points at the new file")
+
+    print("3. an active SVG is refused before anything is held")
+    try:
+        upload(BAD_SVG)
+        check(False, "a scripted SVG is refused")
+    except HTTPException as e:
+        check(e.status_code == 415, "a scripted SVG is refused (415)")
+    check(json.loads(held_json.read_text())["logo_ext"] == "svg", "the held upload is left as it was")
+
+    print("4. apply refuses without a terminal or the typed word")
+    sys.stdin = types.SimpleNamespace(isatty=lambda: False)
+    check(sl.main(["--apply", str(held_json)]) == 1, "no terminal: refused")
+    sys.stdin = types.SimpleNamespace(isatty=lambda: True)
+    builtins.input = lambda prompt="": "yes"
+    check(sl.main(["--apply", str(held_json)]) == 1, "a word other than publish: refused")
+    check(git(site, "status", "--porcelain") == "" and yaml_path.read_text() == seed_yaml, "still nothing written")
+
+    print("5. a held image that changed after the upload is refused")
+    svg_path = held_json.with_suffix(".svg")
+    svg_path.write_bytes(SVG.replace(b"#000", b"#fff"))
+    builtins.input = lambda prompt="": "publish"
+    check(sl.main(["--apply", str(held_json)]) == 1, "sha mismatch: refused")
+    svg_path.write_bytes(SVG)
+
+    print("6. publish writes the logo and the listing, commits as ICSAC, pushes")
+    check(sl.main(["--apply", str(held_json)]) == 0, "apply returns 0")
+    data = __import__("yaml").safe_load(yaml_path.read_text())
+    entry = data["supporters"][0]
+    logo_name = held_json.stem.removeprefix(sl.STAGE_PREFIX) + ".svg"
+    check(entry.get("logo_path") == f"/supporter-logos/{logo_name}" and "logo_pending" not in entry,
+          "the record now points at the logo; logo_pending cleared")
+    check((sl.LOGO_DIR / logo_name).read_bytes() == SVG, "the logo file is on the site")
+    check(git(site, "log", "-1", "--format=%an <%ae>").strip() == "ICSAC <info@icsacinstitute.org>", "committed as ICSAC")
+    check(git(remote, "rev-parse", "main").strip() == git(site, "rev-parse", "HEAD").strip(), "pushed to the remote")
+    check(not held_json.exists() and held_json.with_name(held_json.name + ".applied").exists()
+          and svg_path.with_name(svg_path.name + ".applied").exists(), "the held files are marked applied")
+
+    print("7. the upload path itself can never publish")
+    src = inspect.getsource(sl.handle_sponsor_logo)
+    check(not any(w in src for w in ("_git_output", "_write_supporters", "push")), "handle_sponsor_logo has no git or YAML write")
+finally:
+    sys.stdin, builtins.input = real_stdin, real_input
+    shutil.rmtree(tmp, ignore_errors=True)
+
+print(f"\n{'PASS' if not failures else 'FAILED'}: {len(failures)} failure(s)")
+sys.exit(0 if not failures else 1)

intake/sponsor_logo.py

@@ -3,7 +3,8 @@
 Lives next to intake_server.py and gets wired in via a single import +
 route registration there. Kept in its own module so the submission
 intake stays focused; this module owns the website-repo side effects
-(file write, supporters.yaml mutation, git commit + push).
+(file write, supporters.yaml mutation, git commit + push), which run only
+when the curator publishes a held upload.
 
 The Stripe Checkout Session ID is the auth token: anyone with a valid
 paid Sponsor session can upload a logo for that session. Stripe is
@@ -19,19 +20,32 @@ Filename for the uploaded logo: first 8 chars of sha256(session_id) +
 canonical extension by mime sniff (PNG/JPEG/SVG/WebP). The session-id
 hash is opaque, collision-free in practice, and stable for re-uploads.
 
-Side effects per successful upload:
-  1. Logo written to icsacinstitute.org/public/supporter-logos/<8hex>.<ext>
-  2. supporters.yaml updated (record keyed by stripe_sub id; logo_pending
-     cleared, logo_path set, display_name + website_url filled).
-  3. `git commit && git push origin main` from the website repo.
+An upload publishes nothing: nothing reaches the site without the curator's
+approval. Side effects per successful upload:
+  1. The logo and the proposed listing are held in the ready-to-publish
+     directory as sponsor-logo-<8hex>.<ext> + sponsor-logo-<8hex>.json; a
+     re-upload for the same session replaces the held one.
+  2. The curator gets one ping (no sponsor name, since it also goes to the
+     ntfy backup) and the image itself on Telegram, so it can be seen first.
+
+Publishing, from the repo root:
+    .venv/bin/python -m intake.sponsor_logo --apply <held .json>
+shows the supporters.yaml diff, asks for the typed word "publish", then
+writes public/supporter-logos/<8hex>.<ext> and the record (keyed by
+stripe_sub; logo_pending cleared, logo_path, display_name and website_url
+set), commits and pushes from the website repo.
 """
 
 from __future__ import annotations
 
+import argparse
+import difflib
 import hashlib
+import json
 import os
 import re
 import subprocess
+import sys
 import time
 from datetime import datetime, timezone
 from pathlib import Path
@@ -50,6 +64,9 @@ SPONSOR_PRODUCT_ID = "prod_UXiXkUln7XbrQz"
 WEBSITE_REPO = Path.home() / "Desktop" / "icsac" / "icsacinstitute.org"
 LOGO_DIR = WEBSITE_REPO / "public" / "supporter-logos"
 SUPPORTERS_YAML = WEBSITE_REPO / "src" / "data" / "supporters.yaml"
+# Held uploads wait for the curator here (the directory publications.py holds entries in).
+READY_DIR = Path.home() / "icsac-submissions" / "ready-to-publish"
+STAGE_PREFIX = "sponsor-logo-"
 
 # Multipart upload cap. CF Pages edge already enforces ~5 MB; this is
 # the belt-and-suspenders check after the body parse.
@@ -227,18 +244,21 @@ def _load_supporters() -> dict[str, Any]:
     return loaded
 
 
-def _write_supporters(data: dict[str, Any]) -> None:
-    """Atomic write — temp file + rename so a crash mid-write can't corrupt."""
-    SUPPORTERS_YAML.parent.mkdir(parents=True, exist_ok=True)
-    tmp = SUPPORTERS_YAML.with_suffix(SUPPORTERS_YAML.suffix + ".tmp")
+def _render_supporters(data: dict[str, Any]) -> str:
     header = (
         "# ICSAC Supporters Registry\n"
         "# Written by sponsor-logo intake + Stripe poll job.\n"
         "# Schema: see commit history of this file.\n\n"
     )
-    body = yaml.safe_dump(data, sort_keys=False, allow_unicode=True)
+    return header + yaml.safe_dump(data, sort_keys=False, allow_unicode=True)
+
+
+def _write_supporters(data: dict[str, Any]) -> None:
+    """Atomic write — temp file + rename so a crash mid-write can't corrupt."""
+    SUPPORTERS_YAML.parent.mkdir(parents=True, exist_ok=True)
+    tmp = SUPPORTERS_YAML.with_suffix(SUPPORTERS_YAML.suffix + ".tmp")
     with tmp.open("w", encoding="utf-8") as f:
-        f.write(header + body)
+        f.write(_render_supporters(data))
     tmp.replace(SUPPORTERS_YAML)
 
 
@@ -281,43 +301,161 @@ def _upsert_sponsor(
         existing["stripe_sub"] = stripe_sub
 
 
-def _git(*args: str) -> None:
-    """Run a git command in the website repo. Raise 500 with a clean message
-    on failure so the API caller gets a real error instead of a stack trace."""
-    proc = subprocess.run(
-        ["git", *args],
-        cwd=WEBSITE_REPO,
-        capture_output=True,
-        text=True,
-        check=False,
-        timeout=60,
-    )
+def _git_output(*args: str) -> str:
+    proc = subprocess.run(["git", *args], cwd=WEBSITE_REPO, capture_output=True,
+                          text=True, check=False, timeout=60)
     if proc.returncode != 0:
-        tail = (proc.stderr or proc.stdout or "").strip().splitlines()
-        msg = " | ".join(tail[-3:]) if tail else "git command failed"
-        raise HTTPException(500, f"git {args[0]} failed: {msg}")
-
-
-def _git_commit_push(logo_path_rel: str, display_name: str) -> None:
-    """Commit supporters.yaml + the new logo, then push to origin/main."""
-    # Pull first so the push can fast-forward — the website repo is the
-    # source of truth and may have unrelated commits from elsewhere.
-    _git("pull", "--rebase", "--autostash", "origin", "main")
-    _git("add", "src/data/supporters.yaml", logo_path_rel)
-    # If nothing changed (re-upload with identical bytes + same record),
-    # commit will fail; treat that as success.
-    status = subprocess.run(
-        ["git", "diff", "--cached", "--quiet"],
-        cwd=WEBSITE_REPO,
-        check=False,
+        raise RuntimeError(f"git {args[0]} failed: {(proc.stderr or proc.stdout).strip()[:300]}")
+    return proc.stdout
+
+
+def _stage_upload(session_hash: str, ext: str, data: bytes, listing: dict[str, str]) -> tuple[Path, Path]:
+    """Hold the logo and its proposed listing for the curator. Writes nothing to the site.
+    A re-upload for the same session replaces the held one, whatever its extension."""
+    READY_DIR.mkdir(parents=True, exist_ok=True)
+    base = f"{STAGE_PREFIX}{session_hash}"
+    image = READY_DIR / f"{base}.{ext}"
+    for other_ext in ALLOWED_MIME_EXT.values():
+        stale = READY_DIR / f"{base}.{other_ext}"
+        if other_ext != ext and stale.exists():
+            stale.unlink()
+    tmp = image.with_name(image.name + ".tmp")
+    tmp.write_bytes(data)
+    tmp.replace(image)
+    record = {
+        "held_at": datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "reason": "Sponsor logo upload (Stripe checkout)",
+        "session_hash": session_hash,
+        "logo_file": image.name,
+        "logo_ext": ext,
+        "logo_sha256": hashlib.sha256(data).hexdigest(),
+        **listing,
+    }
+    stage = READY_DIR / f"{base}.json"
+    tmp = stage.with_name(stage.name + ".tmp")
+    tmp.write_text(json.dumps(record, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    tmp.replace(stage)
+    return stage, image
+
+
+def _send_logo_to_telegram(image: Path, caption: str) -> bool:
+    """Show the curator the uploaded image itself. Telegram only: the ntfy backup carries no names."""
+    import config  # noqa: PLC0415 — editorial root module, on sys.path in the server and with -m
+
+    token = getattr(config, "TELEGRAM_TOKEN", "")
+    chat_id = getattr(config, "TELEGRAM_CHAT_ID", "")
+    if not token or not chat_id:
+        return False
+    data = {"chat_id": str(chat_id), "caption": caption[:1000]}
+    thread_id = str(getattr(config, "TELEGRAM_THREAD_ID", "") or "").strip()
+    if thread_id:
+        data["message_thread_id"] = thread_id
+    try:
+        with httpx.Client(timeout=20.0) as client:
+            resp = client.post(f"https://api.telegram.org/bot{token}/sendDocument", data=data,
+                               files={"document": (image.name, image.read_bytes())})
+        return resp.status_code == 200 and bool(resp.json().get("ok"))
+    except (httpx.HTTPError, ValueError) as e:
+        # Only the type: the request URL carries the bot token.
+        print(f"  sponsor-logo: Telegram image send failed ({type(e).__name__})")
+        return False
+
+
+def _ping_curator(stage: Path, image: Path, display_name: str) -> None:
+    import notify  # noqa: PLC0415
+
+    message = ("READY TO PUBLISH (held for your approval): a Sponsor logo upload from /sponsor-onboarding. "
+               "Review and publish from the editorial-system directory: "
+               f".venv/bin/python -m intake.sponsor_logo --apply {stage}")
+    try:
+        pinged = bool(notify.send_to_curator(message, parse_mode=None))
+    except Exception as e:  # noqa: BLE001 — the upload is held either way
+        print(f"  sponsor-logo: curator ping error ({type(e).__name__})")
+        pinged = False
+    if not pinged:
+        print(f"  sponsor-logo: curator ping failed; the upload is still held at {stage}")
+    if not _send_logo_to_telegram(image, f"Sponsor logo held for your approval: {display_name}"):
+        print(f"  sponsor-logo: image not sent to Telegram; it is held at {image}")
+
+
+def _apply_staged(stage: Path, push: bool = True) -> int:
+    """Review a held upload and, on the typed word "publish", put it on the site."""
+    held = json.loads(stage.read_text(encoding="utf-8"))
+    session_hash = str(held.get("session_hash", ""))
+    ext = str(held.get("logo_ext", ""))
+    if not re.fullmatch(r"[0-9a-f]{8}", session_hash) or ext not in ALLOWED_MIME_EXT.values():
+        print("sponsor-logo: the held file is malformed; nothing written", file=sys.stderr)
+        return 1
+    image = stage.with_name(f"{STAGE_PREFIX}{session_hash}.{ext}")
+    data = image.read_bytes()
+    if hashlib.sha256(data).hexdigest() != held.get("logo_sha256"):
+        print("sponsor-logo: the held image changed since the upload; nothing written", file=sys.stderr)
+        return 1
+    mime = _sniff_mime(data[:64])
+    if ALLOWED_MIME_EXT.get(mime or "") != ext or (mime == "image/svg+xml" and not _svg_is_inert(data)):
+        print("sponsor-logo: the held image failed the format check; nothing written", file=sys.stderr)
+        return 1
+    if _git_output("status", "--porcelain").strip():
+        print("sponsor-logo: the website repo has uncommitted changes; refusing to apply over them", file=sys.stderr)
+        return 1
+    if push:
+        _git_output("pull", "--rebase", "origin", "main")
+
+    before = SUPPORTERS_YAML.read_text(encoding="utf-8") if SUPPORTERS_YAML.exists() else ""
+    supporters = _load_supporters()
+    out_name = f"{session_hash}.{ext}"
+    display_name = str(held.get("display_name", ""))
+    _upsert_sponsor(
+        supporters,
+        stripe_sub=str(held.get("stripe_sub", "")),
+        display_name=display_name,
+        website_url=str(held.get("website_url", "")),
+        logo_path=f"/supporter-logos/{out_name}",
+        valid_through=str(held.get("valid_through", "")),
     )
-    if status.returncode == 0:
-        return  # nothing staged; bail without commit/push
-    msg = f"sponsors: add {display_name} logo"
-    _git("-c", "user.email=info@icsacinstitute.org",
-         "-c", "user.name=ICSAC",
-         "commit", "-m", msg)
-    _git("push", "origin", "main")
+    after = _render_supporters(supporters)
+    logo_file = LOGO_DIR / out_name
+    if after == before and logo_file.exists() and logo_file.read_bytes() == data:
+        print(f"sponsor-logo: the site already shows {stage.name}; nothing to publish")
+        _mark_applied(stage, image)
+        return 0
+    sys.stdout.writelines(difflib.unified_diff(before.splitlines(True), after.splitlines(True),
+                                               "supporters.yaml (live)", "supporters.yaml (after)"))
+    print(f"\nLogo: public/supporter-logos/{out_name} ({max(1, len(data) // 1024)} KB {ext}). "
+          f"The image went to Telegram with the ping; held copy: {image}")
+    if not sys.stdin.isatty():
+        print("sponsor-logo: --apply needs a terminal to confirm; nothing written", file=sys.stderr)
+        return 1
+    word = input('Type "publish" to write the logo and supporters.yaml and '
+                 + ("commit and push: " if push else "commit (no push): "))
+    if word.strip() != "publish":
+        print("sponsor-logo: not confirmed; nothing written")
+        return 1
+
+    LOGO_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = logo_file.with_name(logo_file.name + ".tmp")
+    tmp.write_bytes(data)
+    tmp.replace(logo_file)
+    # An earlier upload under another extension would be left orphaned.
+    for other_ext in ALLOWED_MIME_EXT.values():
+        stale = LOGO_DIR / f"{session_hash}.{other_ext}"
+        if other_ext != ext and stale.exists():
+            stale.unlink()
+    _write_supporters(supporters)
+    _git_output("add", "-A", "--", "src/data/supporters.yaml", "public/supporter-logos")
+    _git_output("-c", "user.email=info@icsacinstitute.org", "-c", "user.name=ICSAC",
+                "commit", "-m", f"sponsors: add {display_name} logo")
+    if push:
+        _git_output("push", "origin", "main")
+    _mark_applied(stage, image)
+    print("sponsor-logo: published" if push else "sponsor-logo: committed (not pushed)")
+    return 0
+
+
+def _mark_applied(stage: Path, image: Path) -> None:
+    for p in (stage, image):
+        if p.exists():
+            p.rename(p.with_name(p.name + ".applied"))
 
 
 def prefill_for_session(session_id: str) -> dict[str, Any]:
@@ -401,44 +539,35 @@ async def handle_sponsor_logo(
 
     # Filename: opaque 8-char session-id hash. Stable for re-uploads.
     session_hash = hashlib.sha256(session_id.encode()).hexdigest()[:8]
-    out_name = f"{session_hash}.{ext}"
-    out_path = LOGO_DIR / out_name
-    LOGO_DIR.mkdir(parents=True, exist_ok=True)
-
-    # Write atomically — temp file + rename, so a partial write can't
-    # leave a half-bytes logo on disk.
-    tmp_path = out_path.with_suffix(out_path.suffix + ".tmp")
-    tmp_path.write_bytes(chunk_bytes)
-    tmp_path.replace(out_path)
-
-    # If this session previously uploaded under a different extension
-    # (e.g. PNG then later SVG), purge the stale variants so git diff
-    # doesn't accumulate orphans.
-    for other_ext in ALLOWED_MIME_EXT.values():
-        if other_ext == ext:
-            continue
-        stale = LOGO_DIR / f"{session_hash}.{other_ext}"
-        if stale.exists():
-            stale.unlink()
-
-    logo_path_rel = f"public/supporter-logos/{out_name}"
-
-    supporters = _load_supporters()
-    _upsert_sponsor(
-        supporters,
-        stripe_sub=info["stripe_sub"],
-        display_name=display_name,
-        website_url=website_url,
-        logo_path="/" + logo_path_rel.removeprefix("public/"),
-        valid_through=info["valid_through"],
-    )
-    _write_supporters(supporters)
 
-    _git_commit_push(logo_path_rel, display_name)
+    # Held for the curator; nothing reaches the site until the curator publishes it.
+    stage, image = _stage_upload(session_hash, ext, chunk_bytes, {
+        "stripe_sub": info["stripe_sub"],
+        "display_name": display_name,
+        "website_url": website_url,
+        "valid_through": info["valid_through"],
+    })
+    _ping_curator(stage, image, display_name)
 
     return {
         "ok": True,
+        "held": True,
         "display_name": display_name,
-        "logo_path": "/" + logo_path_rel.removeprefix("public/"),
-        "committed_at": int(time.time()),
+        "received_at": int(time.time()),
     }
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Review and publish a held sponsor-logo upload.")
+    ap.add_argument("--apply", type=Path, required=True, metavar="FILE", help="the held sponsor-logo-<id>.json")
+    ap.add_argument("--no-push", action="store_true", help="commit but do not pull or push")
+    args = ap.parse_args(argv)
+    try:
+        return _apply_staged(args.apply, push=not args.no_push)
+    except Exception as e:  # noqa: BLE001
+        print(f"sponsor-logo: apply FAILED: {getattr(e, 'detail', None) or e!r}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tools/wrap-paper-pdf.py

@@ -1,286 +1,375 @@
 #!/usr/bin/env python3
-"""Wrap an ICSAC-accepted paper with a 1-page ICSAC cover.
-
-Reads paper metadata from icsacinstitute.org/src/data/accepted.json,
-renders a Letter-trim cover via WeasyPrint, and prepends it to the
-author's PDF via pypdf. Output is written alongside the source PDF
-with an `-icsac.pdf` suffix.
-
-The author's manuscript is NEVER modified — the cover is a new first
-page only. The unwrapped PDF stays in place at <record_id>.pdf so
-Scholar / Zenodo / archival tooling can still grab the bare manuscript.
+"""Wrap an accepted Persistence article with a 1-page ICSAC cover.
+
+Reads the article from the website's src/data/accepted.json and the volume
+table from src/lib/persistence.ts, renders a cover the size of the author's
+first page (Letter or A4) via WeasyPrint, and prepends it to the author's PDF
+via pypdf. The author's PDF is public/papers/<key>.pdf and the result is
+public/papers/<key>-icsac.pdf, where <key> is the Zenodo record_id for papers
+deposited there and the submission ID (ICSAC-SUB-NNNNN) for papers registered
+under the Institute's DOI prefix.
+
+The author's manuscript is NEVER modified: the cover is a new first page only,
+and the bare <key>.pdf stays in place for Scholar, the Crossref link and
+archival tooling. After writing, the result is read back: page 1 must be the
+cover and every later page must carry the source page's content unchanged.
+
+Dates: --accepted / --published when given (register --live passes the dates
+it deposited with Crossref). Otherwise an Institute DOI reads both from
+Crossref, and a Zenodo DOI takes the acceptance date from the registry and the
+first publication date from the Zenodo record. A date or licence that can't be
+read stops the run: the cover never guesses.
 
 Usage:
   wrap-paper-pdf.py --slug the-dynamic-existence-threshold
   wrap-paper-pdf.py --all
-  wrap-paper-pdf.py --slug X --fetch   # download source from Zenodo if missing
+  wrap-paper-pdf.py --slug X --fetch    # download a missing Zenodo source PDF
+  wrap-paper-pdf.py --slug X --accepted 2026-03-02 --published 2026-03-03
+  wrap-paper-pdf.py --slug X --out DIR  # write the result to DIR instead
+
+Exit 0 when every cover asked for was written; 1 when any was not ("cover not
+made: <reason>" on stderr).
 """
 from __future__ import annotations
 import argparse
+import base64
+import datetime as _dt
+import hashlib
 import io
 import json
 import os
+import re
 import sys
+import tempfile
+import urllib.parse
 import urllib.request
-from datetime import date
 from pathlib import Path
 
 import weasyprint
 import pypdf
+from PIL import Image
 
-_SITE = os.environ.get("ICSAC_WEBSITE_REPO")
-if not _SITE:
-    sys.exit("set ICSAC_WEBSITE_REPO to the website checkout (the folder holding src/data/accepted.json)")
-SITE = Path(_SITE)
-LOGO = SITE / "public" / "logo_trans_ICSAC_notext.png"
-ACCEPTED = SITE / "src" / "data" / "accepted.json"
-OUT_DIR = SITE / "public" / "papers"
+SITE_URL = "https://icsacinstitute.org"
+USER_AGENT = "ICSAC-cover-tool/2.0 (+https://icsacinstitute.org; mailto:info@icsacinstitute.org)"
+PUBLISHER = "Institute for Complexity Science and Advanced Computing"
 
-# License default per project policy
-DEFAULT_LICENSE = "CC-BY 4.0"
+# Same labels as the article page (src/pages/publications/[slug].astro).
+LICENSE_LABELS = {
+    "https://creativecommons.org/licenses/by/4.0/": "CC BY 4.0",
+    "https://creativecommons.org/licenses/by-sa/4.0/": "CC BY-SA 4.0",
+    "https://creativecommons.org/publicdomain/zero/1.0/": "CC0 1.0",
+}
+# Zenodo licence ids -> the URL the registry would carry.
+ZENODO_LICENSES = {
+    "cc-by-4.0": "https://creativecommons.org/licenses/by/4.0/",
+    "cc-by-sa-4.0": "https://creativecommons.org/licenses/by-sa/4.0/",
+    "cc0-1.0": "https://creativecommons.org/publicdomain/zero/1.0/",
+}
+LOGO_HEIGHT_PT = 46
+LOGO_PPI = 300
 
 
-def _accepted_us(iso: str) -> str:
-    """2026-04-19 → 04/19/2026 (US format used elsewhere on the site)."""
-    if not iso:
-        return ""
-    y, m, d = iso.split("-")
-    return f"{m}/{d}/{y}"
+class CoverError(Exception):
+    """This paper's cover can't be made; nothing is written for it."""
 
 
-def _authors_str(authors: list[str]) -> str:
-    if not authors:
-        return "Anonymous"
-    if len(authors) <= 3:
-        return ", ".join(authors)
-    return ", ".join(authors[:2]) + f", et al. ({len(authors)} authors)"
+class Site:
+    def __init__(self, root: Path):
+        self.root = Path(root)
+        self.accepted = self.root / "src" / "data" / "accepted.json"
+        self.persistence_ts = self.root / "src" / "lib" / "persistence.ts"
+        self.papers = self.root / "public" / "papers"
+        self.logo = self.root / "public" / "logo_trans_ICSAC_notext.png"
+        self.fonts = self.root / "public" / "fonts"
 
+    def load_papers(self) -> list[dict]:
+        d = json.loads(self.accepted.read_text(encoding="utf-8"))
+        return d if isinstance(d, list) else d.get("papers", [])
 
-def _load_papers() -> list[dict]:
-    d = json.loads(ACCEPTED.read_text())
-    return d if isinstance(d, list) else d.get("papers", [])
+    def find(self, slug: str) -> dict:
+        for p in self.load_papers():
+            if p.get("slug") == slug:
+                return p
+        raise CoverError(f"slug not found in accepted.json: {slug}")
 
+    def journal(self) -> dict:
+        """{title, volumes (oldest first), prefix} from persistence.ts, the file the
+        article page reads: the journal title, the volume table, and the DOI
+        prefix its isInstituteDoi() treats as the Institute's own."""
+        ts = self.persistence_ts.read_text(encoding="utf-8")
+        t = re.search(r"PERSISTENCE_TITLE\s*=\s*'([^']+)'", ts)
+        m = re.search(r"PERSISTENCE_VOLUMES[^=]*=\s*\[(.*?)\];", ts, re.S)
+        rows = re.findall(
+            r"\{\s*volume:\s*'([^']+)',\s*from:\s*'(\d{4}-\d{2}-\d{2})',\s*year:\s*'(\d{4})'\s*,?\s*\}",
+            m.group(1) if m else "")
+        p = re.search(r"function isInstituteDoi\b.*?/\^10\\\.(\d{4,9})\\/", ts, re.S)
+        if not t or not rows or not p:
+            raise CoverError(f"couldn't read the journal title, volume table or DOI prefix from {self.persistence_ts}")
+        vols = sorted(({"volume": v, "from": f, "year": y} for v, f, y in rows), key=lambda r: r["from"])
+        return {"title": t.group(1), "volumes": vols, "prefix": f"10.{p.group(1)}"}
 
-def _find(slug: str) -> dict:
-    for p in _load_papers():
-        if p.get("slug") == slug:
-            return p
-    raise SystemExit(f"slug not found in accepted.json: {slug}")
 
+# ── the citation, ported from the site's src/lib/cite.ts + persistence.ts ──
 
-def _zenodo_fetch_pdf(record_id: str, dest: Path) -> None:
-    """Download the primary PDF file from a Zenodo record."""
-    api = f"https://zenodo.org/api/records/{record_id}"
-    print(f"  fetching Zenodo metadata: {api}")
-    with urllib.request.urlopen(api, timeout=30) as r:
-        meta = json.loads(r.read())
-    files = meta.get("files", [])
-    pdfs = [f for f in files if f.get("key", "").lower().endswith(".pdf")]
-    if not pdfs:
-        raise SystemExit(f"no PDF file on Zenodo record {record_id}")
-    # Pick the largest (most likely the manuscript over supplementary)
-    pdf = max(pdfs, key=lambda f: f.get("size", 0))
-    url = pdf["links"]["self"]
-    print(f"  downloading: {url}")
-    with urllib.request.urlopen(url, timeout=120) as r, open(dest, "wb") as out:
-        out.write(r.read())
-    print(f"  saved → {dest}  ({dest.stat().st_size} bytes)")
+def bare_doi(doi: str) -> str:
+    return re.sub(r"^doi:", "", doi or "", flags=re.I).strip()
 
 
-_COVER_CSS = """
-@page { size: Letter; margin: 0.75in 0.85in 1.1in 0.85in; }
-
-body {
-  font-family: "EB Garamond", Georgia, "Times New Roman", serif;
-  font-size: 11pt;
-  line-height: 1.5;
-  color: #0A1929;
-  margin: 0;
-}
+def is_institute_doi(doi: str, prefix: str) -> bool:
+    return bare_doi(doi).lower().startswith(prefix.lower() + "/")
 
-.header {
-  display: flex;
-  align-items: center;
-  gap: 14pt;
-  padding-bottom: 12pt;
-  border-bottom: 1pt solid #8B5E3C;
-}
 
-.header img {
-  width: 44pt;
-  height: 44pt;
-}
+def article_number_for(doi: str, prefix: str) -> str | None:
+    m = re.match(re.escape(prefix) + r"/icsac\.\d{4}\.(\d{3,})$", bare_doi(doi), re.I)
+    return m.group(1) if m else None
 
-.header-text {
-  display: flex;
-  flex-direction: column;
-}
 
-.header-org {
-  font-family: "Inter", "Helvetica Neue", Arial, sans-serif;
-  font-size: 9.5pt;
-  letter-spacing: 1.2pt;
-  text-transform: uppercase;
-  color: #8B5E3C;
-  font-weight: 600;
-  line-height: 1.3;
-}
+def volume_for(accepted: str, volumes: list[dict]) -> dict | None:
+    d = (accepted or "")[:10]
+    if not re.match(r"^\d{4}-\d{2}-\d{2}$", d):
+        return None
+    hit = None
+    for row in volumes:
+        if d >= row["from"]:
+            hit = row
+    return hit
 
-.header-tag {
-  font-family: "Inter", "Helvetica Neue", Arial, sans-serif;
-  font-size: 8.5pt;
-  color: #6E5C42;
-  margin-top: 3pt;
-  letter-spacing: 0.3pt;
-}
-
-.title-block {
-  margin: 32pt 0 0;
-}
 
-.title {
-  font-size: 20pt;
-  font-weight: 600;
-  line-height: 1.22;
-  margin: 0 0 10pt;
-  color: #0A1929;
-}
+def format_author_apa(name: str) -> str:
+    t = name.strip()
+    if not t:
+        return ""
+    if "," in t:
+        return t
+    parts = t.split()
+    if len(parts) == 1:
+        return parts[0]
+    initials = [p if p.endswith(".") else p[0].upper() + "." for p in parts[:-1]]
+    return f"{parts[-1]}, {' '.join(initials)}"
+
+
+def authors_apa_list(authors: list[str]) -> str:
+    f = [format_author_apa(a) for a in authors]
+    if not f:
+        return "Anonymous"
+    if len(f) == 1:
+        return f[0]
+    if len(f) == 2:
+        return f"{f[0]} & {f[1]}"
+    return ", ".join(f[:-1]) + ", & " + f[-1]
+
+
+def doi_url(doi: str) -> str:
+    return "https://doi.org/" + re.sub(r"^doi:", "", doi, flags=re.I)
+
+
+def cite_as(paper: dict, j: dict) -> str:
+    """The page's "The work" plain-text citation (cite.ts plainTextWork)."""
+    authors = authors_apa_list(paper.get("authors") or [])
+    year = (paper.get("accepted_date") or "")[:4]
+    if is_institute_doi(paper["doi"], j["prefix"]):
+        vol = volume_for(paper.get("accepted_date") or "", j["volumes"])
+        art = article_number_for(paper["doi"], j["prefix"])
+        loc = j["title"] + (f", {vol['volume']}" if vol else "") + (f", Article {art}" if art else "")
+        return f"{authors} ({year}). {paper['title']}. {loc}. {doi_url(paper['doi'])}"
+    return f"{authors} ({year}). {paper['title']}. Zenodo. {doi_url(paper['doi'])}. Reviewed by the ICSAC panel."
+
+
+# ── record lookups (dates, licence) ──────────────────────────────────────────
+
+def _get_json(url: str) -> dict:
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT, "Accept": "application/json"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return json.loads(r.read())
+
+
+def _iso(value: str, what: str) -> _dt.date:
+    try:
+        return _dt.date.fromisoformat((value or "")[:10])
+    except ValueError:
+        raise CoverError(f"{what} isn't a date: {value!r}")
+
+
+def _crossref_date(msg: dict, *keys: str) -> _dt.date | None:
+    for k in keys:
+        parts = ((msg.get(k) or {}).get("date-parts") or [[]])[0]
+        if len(parts) == 3:
+            return _dt.date(*parts)
+    return None
+
+
+def resolve_record(paper: dict, prefix: str, accepted: str | None, published: str | None) -> dict:
+    """{accepted, published, published_where, license_url}, each from its record."""
+    doi = bare_doi(paper["doi"])
+    out = {"accepted": _iso(accepted, "--accepted") if accepted else None,
+           "published": _iso(published, "--published") if published else None,
+           "published_where": None,
+           "license_url": paper.get("license_url") or None}
+    if is_institute_doi(doi, prefix):
+        if not (out["accepted"] and out["published"]):
+            try:
+                msg = _get_json("https://api.crossref.org/works/" + urllib.parse.quote(doi, safe="/"))["message"]
+            except Exception as exc:
+                raise CoverError(f"couldn't read the dates from Crossref for {doi} ({type(exc).__name__}: "
+                                 f"{str(exc)[:80]}); pass --accepted and --published")
+            out["accepted"] = out["accepted"] or _crossref_date(msg, "accepted")
+            out["published"] = out["published"] or _crossref_date(msg, "published-online", "published")
+            if not out["license_url"]:
+                lic = [x.get("URL") for x in msg.get("license") or [] if x.get("content-version") == "vor"]
+                out["license_url"] = lic[0] if lic else None
+    else:
+        out["accepted"] = out["accepted"] or _iso(paper.get("accepted_date"), "accepted_date")
+        out["published_where"] = "Zenodo" if paper.get("record_id") else None
+        if paper.get("record_id") and not (out["published"] and out["license_url"]):
+            try:
+                meta = _get_json(f"https://zenodo.org/api/records/{paper['record_id']}")["metadata"]
+            except Exception as exc:
+                raise CoverError(f"couldn't read Zenodo record {paper['record_id']} ({type(exc).__name__}: "
+                                 f"{str(exc)[:80]}); pass --published")
+            if not out["published"] and meta.get("publication_date"):
+                out["published"] = _iso(meta["publication_date"], "Zenodo publication_date")
+            if not out["license_url"]:
+                out["license_url"] = ZENODO_LICENSES.get(((meta.get("license") or {}).get("id") or "").lower())
+    if not out["accepted"]:
+        raise CoverError(f"no acceptance date on record for {doi}; pass --accepted")
+    if not out["published"]:
+        raise CoverError(f"no publication date on record for {doi}; pass --published")
+    if out["license_url"] not in LICENSE_LABELS:
+        raise CoverError(f"licence for {doi} is {out['license_url'] or 'not on record'}; the cover names "
+                         f"only {', '.join(LICENSE_LABELS.values())}")
+    return out
 
-.authors {
-  font-size: 11.5pt;
-  color: #4B5563;
-  font-style: italic;
-  margin: 0 0 26pt;
-}
 
-.meta {
-  display: grid;
-  grid-template-columns: 115pt 1fr;
-  gap: 7pt 16pt;
-  font-size: 10pt;
-  margin-bottom: 24pt;
-}
+# ── rendering ────────────────────────────────────────────────────────────────
 
-.meta dt {
-  font-family: "Inter", "Helvetica Neue", Arial, sans-serif;
-  color: #8B5E3C;
-  font-weight: 600;
-  letter-spacing: 0.6pt;
-  text-transform: uppercase;
-  font-size: 8pt;
-  margin: 0;
-}
+def _us(d: _dt.date) -> str:
+    return d.strftime("%m/%d/%Y")
 
-.meta dd {
-  color: #1f1f1f;
-  margin: 0;
-  word-break: break-word;
-}
 
-.meta dd a {
-  color: #1f1f1f;
-  text-decoration: none;
-}
+def _escape(s: str) -> str:
+    return (s or "").replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")
 
-.venue {
-  padding: 12pt 14pt;
-  background-color: rgba(139, 94, 60, 0.06);
-  border-left: 2pt solid #8B5E3C;
-  font-size: 10pt;
-  line-height: 1.55;
-  margin-bottom: 22pt;
-}
 
-.venue strong {
-  color: #8B5E3C;
-}
+def _logo_data_uri(path: Path) -> str:
+    """The mark cropped to its ink and scaled to LOGO_PPI at the printed size, so
+    the cover doesn't carry (and viewers don't decode) the 2568 px master."""
+    im = Image.open(path).convert("RGBA")
+    im = im.crop(im.getbbox() or (0, 0, *im.size))
+    h = round(LOGO_HEIGHT_PT / 72 * LOGO_PPI)
+    im = im.resize((round(im.width * h / im.height), h), Image.LANCZOS)
+    buf = io.BytesIO()
+    im.save(buf, "PNG", optimize=True)
+    return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
 
-.record {
-  font-family: "Inter", "Helvetica Neue", Arial, sans-serif;
-  font-size: 9pt;
-  color: #4B5563;
-  margin-bottom: 18pt;
-}
 
-.record-label {
-  letter-spacing: 0.6pt;
-  text-transform: uppercase;
-  font-size: 8pt;
-  color: #8B5E3C;
-  font-weight: 600;
-  display: block;
-  margin-bottom: 3pt;
-}
+def _font_faces(fonts: Path) -> str:
+    faces = [("EB Garamond", "normal", "400 700", "eb-garamond-latin.woff2"),
+             ("EB Garamond", "italic", "400", "eb-garamond-italic-latin.woff2"),
+             ("Inter", "normal", "400 700", "inter-latin.woff2")]
+    return "".join(
+        f"@font-face {{ font-family: '{fam}'; font-style: {style}; font-weight: {weight}; "
+        f"src: url('{(fonts / f).as_uri()}') format('woff2'); }}\n"
+        for fam, style, weight, f in faces if (fonts / f).exists())
 
-.record a {
-  color: #8B5E3C;
-  text-decoration: none;
-  word-break: break-all;
-}
 
-.note {
-  position: fixed;
-  bottom: 0.5in;
-  left: 0.85in;
-  right: 0.85in;
-  padding-top: 8pt;
-  border-top: 0.5pt solid #ccc;
-  font-family: "Inter", "Helvetica Neue", Arial, sans-serif;
-  font-size: 7.5pt;
-  line-height: 1.45;
-  color: #888;
-}
+_COVER_CSS = """
+@page { margin: 0.75in 0.85in 1.25in 0.85in; }
+body { font-family: "EB Garamond", Georgia, "Times New Roman", serif; font-size: 11pt;
+       line-height: 1.5; color: #0A1929; margin: 0; }
+.sans { font-family: "Inter", "Helvetica Neue", Arial, sans-serif; }
+.mast { display: flex; align-items: center; gap: 14pt; padding-bottom: 12pt;
+        border-bottom: 1pt solid #8B5E3C; }
+.mast img { height: 46pt; width: auto; }
+.journal { font-size: 25pt; font-weight: 600; line-height: 1.05; color: #0A1929; letter-spacing: 0.2pt; }
+.issue { font-family: "Inter", "Helvetica Neue", Arial, sans-serif; font-size: 9pt; font-weight: 600;
+         letter-spacing: 1.1pt; text-transform: uppercase; color: #8B5E3C; margin-top: 5pt; }
+.org { font-family: "Inter", "Helvetica Neue", Arial, sans-serif; font-size: 8.5pt; color: #6E5C42;
+       margin-top: 2pt; letter-spacing: 0.2pt; }
+.title { font-size: 20pt; font-weight: 600; line-height: 1.22; margin: 30pt 0 10pt; color: #0A1929; }
+.authors { font-size: 11.5pt; color: #4B5563; font-style: italic; margin: 0 0 24pt; }
+.meta { display: grid; grid-template-columns: 115pt 1fr; gap: 7pt 16pt; font-size: 10.5pt; margin: 0 0 22pt; }
+.meta dt { font-family: "Inter", "Helvetica Neue", Arial, sans-serif; color: #8B5E3C; font-weight: 600;
+           letter-spacing: 0.6pt; text-transform: uppercase; font-size: 8pt; margin: 0; padding-top: 2pt; }
+.meta dd { color: #1f1f1f; margin: 0; overflow-wrap: anywhere; }
+a { color: inherit; text-decoration: none; }
+.venue { padding: 11pt 14pt; background-color: rgba(139, 94, 60, 0.06); border-left: 2pt solid #8B5E3C;
+         font-size: 10.5pt; line-height: 1.55; margin-bottom: 20pt; }
+.venue strong { color: #8B5E3C; }
+.block { margin-bottom: 16pt; }
+.label { font-family: "Inter", "Helvetica Neue", Arial, sans-serif; letter-spacing: 0.6pt;
+         text-transform: uppercase; font-size: 8pt; color: #8B5E3C; font-weight: 600; display: block;
+         margin-bottom: 3pt; }
+.record a { font-family: "Inter", "Helvetica Neue", Arial, sans-serif; font-size: 9pt; color: #8B5E3C;
+            overflow-wrap: anywhere; }
+.cite p { margin: 0; font-size: 10.5pt; line-height: 1.5; overflow-wrap: anywhere; }
+.note { position: fixed; bottom: -0.65in; left: 0; right: 0; padding-top: 8pt; border-top: 0.5pt solid #ccc;
+        font-family: "Inter", "Helvetica Neue", Arial, sans-serif; font-size: 7.5pt; line-height: 1.45;
+        color: #6b6b6b; }
 """
 
 
-def _render_cover(paper: dict) -> bytes:
-    rid = paper.get("record_id") or ""
-    slug = paper["slug"]
-    title = paper["title"]
+def _page_size(page) -> str:
+    """The author's first page size, so the file has one page width (A4 papers
+    get an A4 cover); Letter when that page is landscape or an odd size."""
+    w, h = float(page.mediabox.width), float(page.mediabox.height)
+    if (page.get("/Rotate") or 0) % 180:
+        w, h = h, w
+    return f"{w:.2f}pt {h:.2f}pt" if 500 <= w <= 700 and 700 <= h <= 900 else "Letter"
+
+
+def render_cover(paper: dict, rec: dict, site: Site, size: str = "Letter") -> bytes:
+    j = site.journal()
+    doi = bare_doi(paper["doi"])
+    vol = volume_for(paper.get("accepted_date") or "", j["volumes"])
+    art = article_number_for(doi, j["prefix"])
+    issue = " &middot; ".join(x for x in (
+        f"Volume {_escape(vol['volume'])} ({_escape(vol['year'])})" if vol else "",
+        f"Article {_escape(art)}" if art else "") if x)
+    record_url = f"{SITE_URL}/publications/{paper['slug']}"
+    if rec["published_where"]:
+        pub_dt, pub_dd = "First published", f"{_us(rec['published'])}, on {_escape(rec['published_where'])}"
+    else:
+        pub_dt, pub_dd = "Published online", _us(rec["published"])
+    # The two dates in the order they happened: a Zenodo deposit predates its acceptance.
+    dates = [("Accepted", _us(rec["accepted"])), (pub_dt, pub_dd)]
+    if rec["published"] < rec["accepted"]:
+        dates.reverse()
     authors = paper.get("authors") or []
-    doi = paper.get("doi") or ""
-    accepted = paper.get("accepted_date") or ""
-    sub_id = paper.get("sub_id") or "—"
-
-    doi_url = f"https://doi.org/{doi.lstrip('doi:').strip()}" if doi else ""
-    record_url = f"https://icsacinstitute.org/publications/{slug}"
-
-    # Logo as file:// URI so WeasyPrint loads it without fetching
-    logo_uri = f"file://{LOGO}"
-
     html = f"""<!DOCTYPE html>
-<html><head><meta charset="utf-8"><title>{title}</title>
-<style>{_COVER_CSS}</style>
+<html lang="en"><head><meta charset="utf-8"><title>{_escape(paper['title'])}</title>
+<style>{_font_faces(site.fonts)}{_COVER_CSS}@page {{ size: {size}; }}</style>
 </head><body>
-  <div class="header">
-    <img src="{logo_uri}" alt="" />
-    <div class="header-text">
-      <div class="header-org">Institute for Complexity Science and Advanced Computing</div>
-      <div class="header-tag">Open editorial record &middot; No fees &middot; Author retains copyright</div>
+  <div class="mast">
+    <img src="{_logo_data_uri(site.logo)}" alt="" />
+    <div>
+      <div class="journal">{_escape(j['title'])}</div>
+      {f'<div class="issue">{issue}</div>' if issue else ''}
+      <div class="org">{PUBLISHER}</div>
     </div>
   </div>
 
-  <div class="title-block">
-    <div class="title">{_escape(title)}</div>
-    <div class="authors">{_escape(_authors_str(authors))}</div>
-  </div>
+  <div class="title">{_escape(paper['title'])}</div>
+  <div class="authors">{_escape(', '.join(authors) or 'Anonymous')}</div>
 
   <dl class="meta">
-    <dt>DOI</dt><dd>{_escape(doi)}</dd>
-    <dt>Accepted</dt><dd>{_escape(_accepted_us(accepted))}</dd>
-    <dt>License</dt><dd>{DEFAULT_LICENSE}</dd>
-    <dt>Submission ID</dt><dd>{_escape(sub_id)}</dd>
+    <dt>DOI</dt><dd><a href="{_escape(doi_url(doi))}">{_escape(doi)}</a></dd>
+{''.join(f'    <dt>{t}</dt><dd>{d}</dd>' + chr(10) for t, d in dates)}    <dt>License</dt><dd><a href="{_escape(rec['license_url'])}">{LICENSE_LABELS[rec['license_url']]}</a></dd>
   </dl>
 
   <div class="venue">
-    <strong>Reviewed by the ICSAC panel</strong> &mdash; the Institute's open editorial record. The full record &mdash; AI panel reviews, Review Quality Control audit, and the curation team&rsquo;s verdict &mdash; is publicly available at the URL below.
+    <strong>Reviewed by the ICSAC panel.</strong> The full editorial record, with the AI panel reviews, the Review Quality Control audit and the curation team&rsquo;s verdict, is public at the URL below.
   </div>
 
-  <div class="record">
-    <span class="record-label">Editorial record</span>
+  <div class="block record">
+    <span class="label">Editorial record</span>
     <a href="{record_url}">{record_url}</a>
   </div>
 
+  <div class="block cite">
+    <span class="label">Cite as</span>
+    <p>{_escape(cite_as(paper, j))}</p>
+  </div>
+
   <div class="note">
     This cover page is added by the Institute for Complexity Science and Advanced Computing. It does not modify the author's manuscript that follows. The author retains copyright under the license indicated; ICSAC publishes the editorial record but does not claim ownership of the work.
   </div>
@@ -288,61 +377,145 @@ def _render_cover(paper: dict) -> bytes:
     return weasyprint.HTML(string=html).write_pdf()
 
 
-def _escape(s: str) -> str:
-    return (s or "").replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+# ── wrapping ─────────────────────────────────────────────────────────────────
 
+def _zenodo_fetch_pdf(record_id: str, dest: Path) -> None:
+    """Download the primary PDF file from a Zenodo record."""
+    files = _get_json(f"https://zenodo.org/api/records/{record_id}").get("files", [])
+    pdfs = [f for f in files if f.get("key", "").lower().endswith(".pdf")]
+    if not pdfs:
+        raise CoverError(f"no PDF file on Zenodo record {record_id}")
+    pdf = max(pdfs, key=lambda f: f.get("size", 0))   # the manuscript over a supplement
+    req = urllib.request.Request(pdf["links"]["self"], headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=120) as r:
+        _write_atomic(dest, r.read())
+    print(f"  saved {dest} ({dest.stat().st_size} bytes)")
+
+
+def _write_atomic(path: Path, data: bytes) -> None:
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.")
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        os.chmod(tmp, (path.stat().st_mode & 0o777) if path.exists() else 0o644)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def _header_version(reader: pypdf.PdfReader) -> tuple[int, int]:
+    m = re.match(r"%PDF-(\d+)\.(\d+)", reader.pdf_header or "")
+    return (int(m.group(1)), int(m.group(2))) if m else (1, 3)
+
+
+def _content_digest(page) -> str:
+    c = page.get_contents()
+    return hashlib.sha256(c.get_data() if c is not None else b"").hexdigest()
 
-def wrap_one(paper: dict, fetch: bool = False) -> Path:
-    rid = paper.get("record_id")
-    slug = paper["slug"]
-    if not rid:
-        raise SystemExit(f"paper has no record_id (upload route not yet supported): {slug}")
 
-    source = OUT_DIR / f"{rid}.pdf"
+def pdf_key(paper: dict) -> str | None:
+    return paper.get("record_id") or paper.get("sub_id") or None
+
+
+def wrap_one(paper: dict, site: Site, *, fetch: bool = False, accepted: str | None = None,
+             published: str | None = None, out_dir: Path | None = None) -> Path:
+    slug = paper["slug"]
+    key = pdf_key(paper)
+    if not key:
+        raise CoverError(f"{slug} has neither a Zenodo record_id nor a submission ID, so no PDF of it is on the site")
+    source = site.papers / f"{key}.pdf"
     if not source.exists():
-        if fetch:
+        if fetch and paper.get("record_id"):
             print(f"  source PDF missing, fetching from Zenodo: {source}")
-            _zenodo_fetch_pdf(rid, source)
+            _zenodo_fetch_pdf(paper["record_id"], source)
         else:
-            raise SystemExit(f"source PDF missing: {source}  (use --fetch to download)")
-
-    print(f"  rendering cover for {slug}…")
-    cover_bytes = _render_cover(paper)
+            raise CoverError(f"source PDF missing: {source}"
+                             + ("  (use --fetch to download)" if paper.get("record_id") else ""))
+    src_sha = hashlib.sha256(source.read_bytes()).hexdigest()
+    src = pypdf.PdfReader(str(source))
+    if src.is_encrypted:
+        raise CoverError(f"{source.name} is encrypted; the cover tool won't rewrite it")
+
+    rec = resolve_record(paper, site.journal()["prefix"], accepted, published)
+    print(f"  rendering cover for {slug} (accepted {rec['accepted']}, published {rec['published']}"
+          f"{', on ' + rec['published_where'] if rec['published_where'] else ''}, {LICENSE_LABELS[rec['license_url']]})")
+    cover = pypdf.PdfReader(io.BytesIO(render_cover(paper, rec, site, _page_size(src.pages[0]))))
+    if len(cover.pages) != 1:
+        raise CoverError(f"the cover for {slug} rendered to {len(cover.pages)} pages, not 1")
 
-    out = OUT_DIR / f"{rid}-icsac.pdf"
     writer = pypdf.PdfWriter()
-    writer.append(fileobj=io.BytesIO(cover_bytes))
-    writer.append(fileobj=str(source))
-    with open(out, "wb") as f:
-        writer.write(f)
-    print(f"  wrote → {out}  ({out.stat().st_size} bytes)")
+    writer.append(cover)
+    writer.append(src)
+    major, minor = max(_header_version(src), _header_version(cover))
+    writer.pdf_header = f"%PDF-{major}.{minor}"
+    writer.add_metadata({"/Title": paper["title"], "/Author": ", ".join(paper.get("authors") or [])})
+    buf = io.BytesIO()
+    writer.write(buf)
+
+    # Read the result back before it replaces anything: the cover first, then the
+    # author's pages with their content streams unchanged.
+    got = pypdf.PdfReader(io.BytesIO(buf.getvalue()))
+    if len(got.pages) != len(src.pages) + 1:
+        raise CoverError(f"the result has {len(got.pages)} pages, expected {len(src.pages) + 1}")
+    if bare_doi(paper["doi"]) not in re.sub(r"\s+", "", got.pages[0].extract_text() or ""):
+        raise CoverError("page 1 of the result doesn't read as the cover (its DOI isn't on it)")
+    for i, page in enumerate(src.pages):
+        if _content_digest(got.pages[i + 1]) != _content_digest(page):
+            raise CoverError(f"page {i + 2} of the result doesn't match page {i + 1} of {source.name}")
+    if hashlib.sha256(source.read_bytes()).hexdigest() != src_sha:
+        raise CoverError(f"{source.name} changed while its cover was being made")
+
+    out = (Path(out_dir) if out_dir else site.papers) / f"{key}-icsac.pdf"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    _write_atomic(out, buf.getvalue())
+    print(f"  wrote {out} ({out.stat().st_size} bytes, {len(got.pages)} pages, {writer.pdf_header})")
     return out
 
 
-def main():
-    ap = argparse.ArgumentParser()
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
     ap.add_argument("--slug")
     ap.add_argument("--all", action="store_true")
-    ap.add_argument("--fetch", action="store_true",
-                    help="Download source PDF from Zenodo if missing")
-    args = ap.parse_args()
-
-    OUT_DIR.mkdir(parents=True, exist_ok=True)
+    ap.add_argument("--fetch", action="store_true", help="Download a missing source PDF from Zenodo")
+    ap.add_argument("--accepted", help="acceptance date, YYYY-MM-DD (--slug only)")
+    ap.add_argument("--published", help="publication date, YYYY-MM-DD (--slug only)")
+    ap.add_argument("--out", type=Path, help="write <key>-icsac.pdf here instead of public/papers")
+    args = ap.parse_args(argv)
+    site_root = os.environ.get("ICSAC_WEBSITE_REPO")
+    if not site_root:
+        ap.error("set ICSAC_WEBSITE_REPO to the website checkout (the folder holding src/data/accepted.json)")
+    if not (args.slug or args.all) or (args.slug and args.all):
+        ap.error("specify --slug or --all")
+    if args.all and (args.accepted or args.published):
+        ap.error("--accepted and --published go with --slug")
+    site = Site(Path(site_root))
 
+    failed = 0
     if args.all:
-        papers = _load_papers()
-        for p in papers:
-            if not p.get("record_id"):
-                print(f"SKIP {p['slug']} (no record_id)")
-                continue
-            print(f"\n→ {p['slug']}")
-            wrap_one(p, fetch=args.fetch)
-    elif args.slug:
-        print(f"→ {args.slug}")
-        wrap_one(_find(args.slug), fetch=args.fetch)
+        papers = site.load_papers()
     else:
-        ap.error("specify --slug or --all")
+        try:
+            papers = [site.find(args.slug)]
+        except CoverError as exc:
+            print(f"cover not made: {exc}", file=sys.stderr)
+            return 1
+    for p in papers:
+        print(f"-> {p['slug']}")
+        if args.all and not pdf_key(p):
+            print(f"  no PDF on the site for {p['slug']} (no record_id or sub_id): nothing to cover")
+            continue
+        try:
+            wrap_one(p, site, fetch=args.fetch, accepted=args.accepted, published=args.published,
+                     out_dir=args.out)
+        except CoverError as exc:
+            failed += 1
+            print(f"cover not made: {p['slug']}: {exc}", file=sys.stderr)
+    if args.all:
+        print(f"{len(papers) - failed} of {len(papers)} handled, {failed} not made")
+    return 1 if failed else 0
 
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())