feat: land superpaper v1 notes scaffold

Add the ledger schema, class router, lint codes, ingest/build
pipeline, and three work-tree examples: align derivation,
superfig delegation, and supertensor delegation.

references/agents.md

@@ -0,0 +1,14 @@
+# Agents
+
+Must split when pages > 12 **or** top sections > 4 **or** redraws ≥ 2 **or** the user asks to spawn. Otherwise one agent (including 9–12 pages with ≤4 tops and ≤1 redraw).
+
+Writer jobs are lecture rows in `outline.md`, not `coverage.sections_in`. Outline writes `ledger.yaml`, `outline.md`, `notes.tex` inputs, and `F*.request.md`. Writers only touch their `sec-XX.tex`. Figure agents only see the request.
+
+```
+$superpaper <源> 请 spawn 多 sub agents，隔离上下文：
+  - 1 个 outline agent：ledger.yaml + outline.md
+  - N 个 writer agents：sections/sec-XX.tex
+  - 每个计划重绘图 1 个 figure agent：F*.request.md + sibling skill
+  - 1 个 consistency agent：符号、术语、claim 覆盖
+完成后用 scripts/lint.py 与 build.sh 收口。
+```

references/antipatterns.md

@@ -0,0 +1,8 @@
+# Antipatterns
+
+- Drawing a rewrite as `\sfnode` boxes (use `align`).
+- Sending a tensor-shape claim to superfig, or an architecture to supertensor.
+- Loading a figure `.sty` in the notes so sibling warnings leak into the article log.
+- `\input` of a standalone TikZ source instead of `\spfig`.
+- Reusing a `dropped` / retired id for a new object.
+- A decorative group or arrow that is not in the ledger.

references/api.md

@@ -0,0 +1,14 @@
+# Notes macros
+
+Defined in `assets/notes-macros.tex` (loaded by `assets/notes-template.tex`).
+
+| macro | args |
+|---|---|
+| `\splabel{C1}` | hypertarget + label |
+| `\spref{C1}` | clickable id |
+| `\spsource{§3.2}` | source footnote |
+| `\spfig[w]{F1}{caption}{provenance}` | `figures/F1/build/F1.pdf` |
+| `\spscreenshot[w]{F2}{caption}{provenance}` | `figures/F2/orig.png` |
+| `quotebox` | short quotation |
+
+Scripts: `ingest.sh`, `lint.py`, `render_ledger.py`, `build.sh`, `screenshot.sh` all take `--work`.

references/checklist.md

@@ -0,0 +1,9 @@
+# Delivery checklist
+
+- Ledger written first; every core claim has `\splabel`.
+- Formula three-beat present wherever display math appears.
+- Each figure toolkit matches `scripts/router.py`; mixed-class rows were split.
+- Notes do not `\usepackage{superfig|supertensor|superderive}`.
+- Vector figures are PDF includes; screenshots are `orig.png` with a source footnote.
+- `scripts/lint.py --work` and `scripts/build.sh --work` are green.
+- Overfull in the notes log is allowed; missing glyphs and undefined refs are not.

references/fallback.md

@@ -0,0 +1,9 @@
+# Fallback
+
+`preflight.sh`: 0 full, 1 degraded, 2 no XeLaTeX/`article.cls`.
+
+- Exit 2: deliver `ledger.yaml` + Markdown; say there is no PDF.
+- No `pdftotext` / `pdftoppm`: only `--tex` / `--excerpt`.
+- No `jsonschema`: create `.venv` (`python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`).
+- Sibling `build.sh` fails: drop that figure to `align` or screenshot, keep the notes compiling.
+- No `magick`: `screenshot.sh` must fail if `crop_bbox` is set; do not silently ship the full page.

references/figure-request.md

@@ -0,0 +1,11 @@
+# Figure request
+
+Sibling figure agents see only `notes/figures/F*/F*.request.md` plus that sibling `SKILL.md`. They do not read `ledger.yaml`.
+
+- superfig: `\sfnode` keys `role, level, gap, bracket, at=`. `\sfconn` has no endpoints. `at` must be TikZ calc with `($…$)`.
+- supertensor: every `ststack` / `stface` / `stglyph` has `coord: ""`.
+- `allow-raw-tikz` must also appear as `% superfig-lint: allow-raw-tikz` in the `.tex`.
+- Build: `superfig/scripts/build.sh F1.tex F1/build` (second arg is the outdir).
+- Screenshots: `scripts/screenshot.sh --work <work> --id F2` (`pdftoppm -r 200`, then optional `crop_bbox`).
+
+Worked files: `examples/pipeline-delegate/notes/figures/F1/F1.request.md`, `examples/tensor-delegate/notes/figures/F2/F2.request.md`.

references/input.md

@@ -0,0 +1,12 @@
+# Input
+
+`scripts/ingest.sh --work <dir> (--arxiv ID|--pdf FILE|--tex FILE|--excerpt FILE)`
+
+| kind | ingest |
+|---|---|
+| `tex` | copy into `source/tex/`; do not compile |
+| `arxiv` | id regex `^(ar[Xx]iv:)?(\d{4}\.\d{4,5}(v\d+)?|[a-z-]+/\d{7})$`; PDF then optional e-print tar (read only) |
+| `pdf` | copy `source/paper.pdf`; `pdftotext`; pages `pg-%03d.png` at 120 dpi |
+| `excerpt` / `markdown` | `source/excerpt.md`; `coverage.mode=excerpt` |
+
+Do not OCR as the main path. Architecture figures: redraw with superfig. Numeric plots: screenshot or matplotlib. See `scripts/screenshot.sh` for 200 dpi page crops.

references/ledger.md

@@ -0,0 +1,9 @@
+# Ledger
+
+SSOT is `ledger.yaml`. Schema: `assets/ledger.schema.yaml`. Empty template: `assets/ledger.example.yaml`.
+
+Write the ledger before any `sections/*.tex`. Ids are `C1`, `Q1`, `D1`, `A1`, `L1`, `E1`, `DER1`, `F1`, `SA1` — no `F1a`. Retired ids go in `retired_ids`.
+
+`symbols[].kind` aliases (`activation` → `value`, `shape-parameter` → `shape parameter`, …) are normalized in `scripts/lint.py` **before** `SP001`. Canonical list is the schema enum.
+
+v1 derivations use `figure: null` and `align` in the notes. Do not invent a figure for a four-step rewrite.

references/pedagogy.md

@@ -0,0 +1,15 @@
+# Pedagogy
+
+Reuse `youtube-render-pdf` teaching order: motive → idea → mechanism → evidence → takeaway.
+
+Paper-side changes:
+
+- Cite `§` / `Eq.(n)` / Figure / Table / page, not timestamps.
+- Front page is a bibliography card, not a PDF cover screenshot.
+- Math is `\[` or `align`, never `$$`.
+- Formula three-beat: Chinese motive, display math, flat symbol list.
+- `quotebox` for a short quotation with a source; no long PDF paste.
+- End major sections with `\subsection{本章小结}`; end the notes with `\section{总结与延伸}`.
+- Figures stay outside boxes.
+
+Locked first/last titles: 「这篇论文在问什么」…「总结与延伸」, then appendix 符号表 / 推导链一览 / 图表清单.

references/router.md

@@ -0,0 +1,14 @@
+# Router
+
+Authority: `scripts/router.py`. `suggest()` returns a **class**, not a toolkit.
+
+| class | signals (any hit) | accepted toolkits |
+|---|---|---|
+| `numeric` | loss-curve, bar, scatter, histogram, numeric-plot | screenshot, matplotlib |
+| `raster` | table, photo, apparatus, ui | screenshot |
+| `tensor` | axis, shape, transpose, broadcast, gather, shard, contraction, face | supertensor |
+| `fig` | architecture, pipeline, data-flow, state, time, dependency, what-eats-what, argument-map | superfig |
+| `derive` | rewrite-figure, cancel-visual, subst-visual | v1: align |
+| `none` | otherwise | none |
+
+Mixed classes on one row → `SP011`. Split with the next integer ids. Default: do not draw.