feat: add superfig paper-figure toolkit

Standalone LaTeX/TikZ skill for non-tensor paper figures: node/edge
macros, lint-on-warning build, golden examples, and negative fixtures.

SKILL.md

@@ -0,0 +1,82 @@
+---
+name: superfig
+description: Create or refine clean paper-style figures for non-tensor concepts — architecture and block diagrams, pipelines and data flow, state/time flows, dependency graphs, and conceptual mechanism diagrams. Use whenever a paper idea should be explained with clear nodes, edges, grouping, captions, and a short meaning box in a muted slide-ready style. Not for tensor/matrix/shape semantics (use supertensor) or plotting numeric data.
+---
+
+# superfig
+
+Turn one paper claim or mechanism into one dense, slide-ready figure with three zones:
+
+1. **Top — idea.** The compact claim or formula. Optional; call it after the drawing.
+2. **Middle — structure.** Semantic nodes, directed edges, grouped composites, and captions.
+3. **Bottom — meaning.** What the idea is, what the objects are, what the mechanism does.
+
+`assets/superfig.sty` enforces the house style and the common cursor/role discipline.
+Draw with `\sfnode` / `\sfconn` / `\sfarrow` / `\sfgroup`; do not hand-roll TikZ rectangles
+and arrows unless the linter explicitly allows it.
+
+## When to use
+
+- Architecture, block diagram, pipeline, data flow, dependency graph, state or time flow.
+- A conceptual mechanism that is not a tensor shape: nodes, arrows, containment, lanes.
+- A figure that should look like `supertensor` in palette and text hierarchy.
+
+Do **not** use for tensor faces, axes, contractions, sharding or broadcasting; route those to
+`supertensor`. Do not use for loss curves, benchmark bars, scatter plots, or dashboards.
+
+## Workflow
+
+1. **Preflight.** `./scripts/preflight.sh`. Exit 0 = TikZ+CJK path. Exit 1 = degraded
+   (say so). Exit 2 = no LaTeX; read `references/fallback.md` and name the lost guarantees.
+2. **Reduce** the paper to one primary claim. Drop parallel objectives, optional modules,
+   diagnostics and secondary paths unless the user asks for them.
+3. **Build a semantics ledger** before drawing:
+   - *nodes* — each block is one semantic object: kind, domain/range, owner, lifecycle.
+   - *edges* — each arrow is data flow, control flow, dependency, or causality; never decoration.
+   - *groups* — an outline only when it names a real composite object.
+   See `references/grammar.md`.
+4. **Choose the smallest grammar** that exposes the mechanism:
+   - one object = `\sfnode[role=..., level=...]{name}{label}{width}{height}`
+   - horizontal flow = `\sfstage` + `\sfrow` … `\sfrowend`
+   - horizontal connector with label = `\sfconn{name}{label}`
+   - fixed/branching edge = `\sfarrow[options]{from}{to}` or `\sfarrowlabel`
+   - composite = `\sfgroup[role=...]{name}{(member1)(member2)}{}` then `\sfcaption`
+   - a whole-band aside = `\sfcallout`
+   - bottom explanation = `\sfmeaningbox`
+   Full macro list: `references/api.md`. Worked figures: `examples/`.
+5. **Build and audit.** `./scripts/build.sh fig.tex` runs lint, TeX checks, and exports.
+   Then run `references/checklist.md` against the PNG full-size and thumbnail. Redraw on
+   any mandatory violation.
+
+## Non-negotiables
+
+- **Semantics** — one node, one object. An edge says one relationship. A group is a real
+  composite, not a decorative border.
+- **Layout** — use the cursor in flow rows; use `at={<coord>}` only when the topology is
+  genuinely non-linear. Never hand-tune a neighbor against a magic offset.
+- **Style** — muted palette, one hue per role, at most four active hues plus gray,
+  three separated lightness levels, no saturated primaries, no dashboard clutter.
+- **Build** — `Missing character`, overfull/underfull boxes, and `Package superfig Warning`
+  are build failures, not cosmetic warnings.
+
+`references/antipatterns.md` shows the common ways a clean compile still tells the reader
+something false.
+
+## Output
+
+Default to editable TikZ. `scripts/build.sh` emits PDF, SVG, white-background PNG,
+transparent PNG and a 360 px thumbnail. Deliver the PNG preview, a one-paragraph mechanism
+explanation, and the `.tex` source plus vector artifact.
+
+- **Chinese figures:** `\usepackage[cjk]{superfig}` (XeLaTeX + portable Fandol). Keep
+  standard English terms where natural (`softmax`, `logits`, `gather`).
+- **English figures:** `\usepackage[en]{superfig}` — same geometry, English meaning-box rails.
+- Keep math in LaTeX, not raw Unicode.
+- Add `\sfsignature{<subject>}{<box>}` only when the user or house template asks for it.
+
+## Iterating
+
+When the user asks for a change, do not restart the figure. Edit the role/ledger or the one
+macro call that owns the offending object, rebuild, and re-audit. If a fix requires shrinking
+type, closing the gutter, or covering another object, move the stage to another row instead.
+Ask before dropping an object or edge the user named.