# The Quality Rubric for AC Papers

What a finished paper on **papers.aesthetic.computer** has to clear before it
counts as done. This is the companion to `VOICE.md` (how a paper *sounds*) and
`HAND.md` (how code *reads*) — this file is how a paper is *built and checked*.
It was reverse-engineered from the publishing stack itself: `cli.mjs`,
`tools/check-columns.mjs`, the three `.sty` files, `bin/gen-cover.mjs`, and the
figure-rich exemplar `arxiv-keymaps/keymaps.tex`. When the tooling and this doc
disagree, the tooling wins — fix this file.

The exemplar to hold a flagship paper against is **`arxiv-keymaps`**. When in
doubt, open it.

Two of these gates are enforced by tools today; everything else is enforced by
reading the paper next to keymaps. The two hard gates are flagged **[HARD]**.

---

## A — Voice & argument (`VOICE.md`)

- **A1** First person, plain. "i built this," not "the author implemented." Grep
  the `.tex` for `we propose`, `the authors`, `it should be noted`, `a novel
  approach to`, `in this paper we` → zero hits.
- **A2** Conviction, quiet but absolute. The conclusion states a belief plainly.
  No "results suggest potential viability."
- **A3** Em dashes for asides, short sentences, fragments that land. `---`, not
  semicolon or parenthesis chains.
- **A4** Cite when it matters, never to prove you read things. No paragraph is a
  bare pile of `\citep{}`.
- **A5** The register gradient holds: abstract formal-ish but ends on a line that
  lands; intro opens on the *thing*, not a lit survey; body is whiteboard-precise;
  limitations say what's broken before anyone asks; conclusion is yours.
- **A6** One source file for cards + arxiv. Never maintain divergent content
  across formats.

## B — Structure

- **B1** Abstract in a `\begin{quote}…\textbf{Abstract.}` block after the title.
  One dense paragraph, lands on its last line.
- **B2** Introduction names the object first — often "Figure 1 is…" — and ends
  with a one-line roadmap of the movements to come.
- **B3** Numbered body sections carry `\label{sec:…}` and cross-reference each
  other by label.
- **B4** A limitations pass, or an honest counter-case, that argues against the
  paper's own favored object at least once — without minimizing or dramatizing.
- **B5** Conclusion restates the contribution and the belief.
- **B6** `\section*{Acknowledgments}` when there's a residency or venue context,
  with the pals badge.

## C — Citations

- **C1** natbib + `plainnat`. Every `.bib` entry is actually `\cite`d; every
  `\cite` resolves. Build shows no "undefined citation."
- **C2** Load-bearing citations are real and read — the theoretical anchor is
  cited repeatedly, not name-dropped once.
- **C3** **Diversity is a quality axis, not an afterthought.** The house target
  from the `arxiv-diversity` audit: **≥30% women authors, ≥20% non-Western
  authors.** A cluster of citations that is all-male or all-Western is a defect to
  fix before publishing, the same as a broken build. Verify each new citation's
  metadata against a primary source — guessed page numbers and years are how
  wrong citations ship.
- **C4** Prefer the platter reading corpus (`system/public/assets/papers/
  readings/`) as the scholarly foundation where it fits.

## D — Figures (the keymaps standard)

Keymaps carries 7 figures (2 full-width `figure*`), 2 tables, and 28 QR tiles. A
flagship paper is expected to show its argument, not just state it.

- **D1** Real figures built from the argument — hand-built TikZ diagrams, or
  captured screenshots of the actual thing under discussion (a UI, a piece, a
  real user comment) — not decorative filler.
- **D2** Wide content spans both columns via `figure*[t]` / `table*[p]`.
- **D3** Captions are dense and explanatory. A caption says what to read *and*
  what it proves. "Figure 1: the system" fails.
- **D4** Where the paper catalogs external objects, each resolves to a canonical
  home via a `\qrc{}` QR tile.
- **D5** Inline micro-glyphs (`\key{}`, keycap chips, etc.) used consistently when
  they aid reading.
- **D6** Screenshots are legitimate evidence: the coarse UI being criticized, the
  AC piece being praised, the user comment proving demand. Caption them like
  exhibits — say what the reader is looking at and why it is in the paper.

## E — Cover (`bin/gen-cover.mjs`)

- **E1** A hand-rendered **emblem on cream paper** (colored pencil + gouache,
  silkscreen imperfection) generated by `gen-cover.mjs` (OpenAI gpt-image-2).
  Reads like a record-label seal or a band-tee print.
- **E2** ONE singular subject, floating in the central two-thirds, periphery
  dissolving to bare paper. No frame, no border, no background scene, no clusters.
- **E3** Never spell the subject's name. Identity is carried by emblem,
  silhouette, color, era.
- **E4** Muted natural palette, square 1:1.
- **E5** Prompt lives at `figures/cover-prompt.txt`; output `figures/cover.png`.
- **E6** Included in the title block at `width=0.5–0.7\textwidth`, centered.
- **E7** The cover feeds the index tile (`genCoverTile`); a paper with a
  `figures/cover.png` gets a designed tile instead of a page-1 render.

## F — Typography & layout

- **F1** `\documentclass[10pt,letterpaper,twocolumn]{article}`, `% !TEX program =
  xelatex`. (Essays use `ac-paper-essay.sty`; cards use `ac-paper-cards.sty`.)
- **F2** Geometry `0.75in` margins, folio clear of the sheet edge.
- **F3** Body is **Latin Modern** (Roman/Sans/Mono, mono `Scale=0.85`). **YWFT
  Processing** (`\acbold`/`\aclight`) is reserved for the title and header only —
  its punctuation glyphs are unreliable in body text.
- **F4** AC palette exact: `acpink 180,72,135` · `acpurple 120,80,180` ·
  `acdark 64,56,74` · `acgray 119,119,119`. Diagram chips (`acgreen`/etc.) allowed.
- **F5** `\section` = bold, normalsize, UPPERCASE, `\thesection.`, tight spacing.
- **F6** hyperref links colored `acpurple`; `xurl` loaded; `pdftitle`/`pdfauthor`
  set.
- **F7** Long identifiers/paths wrap via a `\code{}`-style command so they never
  overflow. Two-column breaking tuned (`\tolerance`, `\emergencystretch`,
  `\hyphenpenalty`). Use `\raggedbottom` so short paragraphs don't get their
  inter-paragraph glue stretched into false "title" spacing.
- **F8 [HARD]** **Nothing may break the columnar arrangement.**
  `node papers/cli.mjs check` reports zero `Overfull \hbox > 0.5pt`. This is the
  rule: nothing ships that breaks the columns.
- **F9** Title block: `\acbold` title in `acdark`, cover, italic subtitle in
  `acpink`, byline `@jeffrey · Aesthetic.Computer · ORCID 0009-0007-4460-4913`,
  language bar, then a pink rule. Every dot in "Aesthetic.Computer" is the pink
  `\acdot`.

## G — Build & publish hygiene (`cli.mjs`)

- **G1 [HARD]** Build is **xelatex 3-pass + bibtex** (`xelatex; bibtex; xelatex;
  xelatex`). Success = a real PDF exists, not exit code.
- **G2 [HARD]** No silent failure: the `.log` contains no `! Package fontspec
  Error` and no `nullfont`. A stub PDF from a font fallback is a broken build even
  though xelatex exits 0.
- **G3** Deterministic PDFs: `SOURCE_DATE_EPOCH` from newest source mtime. Same
  bytes in → same bytes out (this is what keeps the oven from auto-commit loops).
- **G4** Version stamp: `\InputIfFileExists{version}` pulls `\paperhash` (git
  short hash, `+` if the paper dir is dirty) and `\paperrev`, with a `dev`/`?`
  fallback, rendered in a colophon badge.
- **G5** History stamp: `\InputIfFileExists{history}` renders an in-PDF changelog
  from the git log of the paper's own `.tex`.
- **G6** Draft watermark on by default (45° pink "WORKING DRAFT" + the
  "Working Draft — not for citation" header). A print edition turns it off.
- **G7** Registered in `PAPER_MAP`: `{ base, siteName, title }`, siteName ending
  `-26-arxiv` (or `-essay` / `-deck` / `-dossier-26-arxiv`).
- **G8** In exactly one `CATEGORIES` lane (platform / essays / audits / decks /
  dossiers / software). Uncategorized triggers a WARN.
- **G9** Has an `IMPORTANCE` rank (missing → 99, sinks to the bottom of the index).
- **G10** `metadata.json` entry with a real `created` date; `revisions`
  increments on each publish.
- **G11** Thumbnail generated in `thumbs/{siteName}.jpg` (cover tile preferred).
- **G12** Index + Atom feed regenerated; `verify` reports zero broken PDF links.
- **G13** `PAPER_COPY` entry with a `detail` line and an `abstract` for the index
  card and the feed.
- **G14** Optional lanes if present: cards (`{base}-cards.tex`), translations
  (da/es/zh/ja/ru), a `PODCASTS` reading.

---

## The review pass (run this before calling a paper done)

1. **Voice** — grep the banned phrases (A1); the conclusion states a belief (A2, B5).
2. **Structure** — abstract-quote, object-first intro with roadmap, honest
   limitations, conclusion, acknowledgments (B1–B6).
3. **Citations** — every entry cited and resolving; metadata verified against
   primary sources; ≥30% women / ≥20% non-Western (C1–C3).
4. **Figures** — real diagrams and captured exhibits with dense captions; wide
   ones as `figure*`; QR tiles resolve (D1–D6).
5. **Cover** — single emblem, cream paper, no name, 1:1; included at
   0.5–0.7\textwidth (E1–E6).
6. **Layout** — 10pt twocolumn, Latin Modern body + ywft title, palette exact,
   `node papers/cli.mjs check` = 0 overflows (F1–F9).
7. **Build/publish** — xelatex 3-pass+bibtex clean, `.log` free of `fontspec
   Error`/`nullfont`, watermark on for drafts, registered in `PAPER_MAP` /
   `CATEGORIES` / `IMPORTANCE` / `PAPER_COPY` / `metadata.json`, thumbnail + feed
   + no broken links (G1–G13).

The teeth today are **F8** and **G1–G2** — the column check and a clean,
non-stub xelatex build. Everything else is enforced by holding the paper up next
to keymaps and being honest about the difference.

---

*Maintained alongside `VOICE.md`. Update this when the tooling changes.*