supertensor: shape-aware tensor figure toolkit

Extracted from the tensor-formula-viz skill and rebuilt around the idea that
the geometry rules should be enforced by construction rather than restated as
prose an agent has to remember.

- assets/supertensor.sty: faces, stacks, index faces, shared caption lanes,
  meaning box, signature. Macros take a declared axis and a declared role, so
  equal shapes get equal edges, a x a is square, a transpose swaps the face,
  and contracted axes share an edge length -- without any manual alignment.
- scripts/preflight.sh: decide the TikZ/CJK path before drawing.
- scripts/build.sh: compile and fail on silent corruption (missing CJK glyphs,
  overfull boxes, undeclared roles), then export pdf/svg/png/thumb.
- scripts/test.sh: build every figure as a regression test for the package.
- examples/: three golden figures (TP-FFN, causal MHA, MoE top-k gather) plus
  an anti-pattern gallery of figures that compile cleanly and still lie.
- SKILL.md + references/: lean entry point, details loaded on demand.

references/style.md

@@ -0,0 +1,94 @@
+# House style
+
+The package ships these defaults; this file explains what you must still decide and what
+you must not undo.
+
+## Canvas
+
+White background, natural `standalone` crop. No forced 16:9. No title by default. The top
+holds at most two compact formula lines: the primary chain and, only if essential, one
+companion definition.
+
+Each stage is one horizontal algebraic row with a shared visual baseline. Use the fewest
+stages that preserve the primary path. No unrelated branches, no dashboard panels.
+
+## Type hierarchy
+
+| element | size | macro / style |
+|---|---|---|
+| formula | `\large` | `\stformula` |
+| stage label | `\small\bfseries`, muted | `st stage` |
+| operator | `\Large` | `st op` |
+| symbol | `\small` | `\stcaption` arg 2 |
+| shape | `\scriptsize`, muted | `\stcaption` arg 3 |
+| bottom prose | `\small` | `\stmeaningbox` |
+| signature | `\scriptsize`, low contrast | `\stsignature` |
+
+Never shrink below this to make something fit — see `layout.md`.
+
+## Faces
+
+Separate tiles with a small white gutter and 0.5–1 pt corner rounding (`\st@tile` does
+this). Thin neutral brackets, `black!55`–`black!70` outer borders. No saturated
+tensor-colored outlines, no continuous spreadsheet grid.
+
+**Encode support before magnitude.** Every known zero stays white/unfilled; every shown
+nonzero gets color. A diagonal matrix must read instantly as colored diagonal cells on a
+white field. `pattern=diag/band/lower/upper/causal/data` fill exactly the structural
+support.
+
+## Color
+
+Palette (already defined): `stTeal #4F8FA5`, `stOrange #EE995B`, `stCoral #C95B5B`,
+`stViolet #8A74B5`, `stGray #85898F`. Muted, mid-chroma, paper-like. Do not add saturated
+primaries.
+
+- One semantic color per tensor role, held across every stage: `\stsetrole{q}{stTeal}`.
+  Macros take a **role**, never a color.
+- At most four active hue families per algebraic row, plus neutral gray. Vary lightness or
+  reuse the related input/output family before spending a new hue.
+- If sign matters: hue for sign, intensity for magnitude.
+- Contrast comes from **lightness separation, not saturation**. Levels are `role!30`,
+  `role!55`, `role!80` (`\stlevelpct`); white is reserved for zero/absence. Do not render
+  a whole tensor in `role!5`–`role!15` pastel.
+- Illustrative dense tensors use two or three **non-periodic** levels. `pattern=dense`
+  composes coprime moduli to avoid this; a polynomial hash mod 3 makes rows 1, 2, 4, 5
+  identical and the eye reads that stripe as structure in the data. No checkerboards, no
+  regular stripes, no symmetric motifs unless they encode real structure.
+
+## Bottom box
+
+One full-width, low-contrast box, one reading column, three fixed-label rows:
+
+- **Axes** — what each dimension means.
+- **Objects** — semantic kind / domain / range (see `semantics.md`).
+- **Mechanism** — at most two essential mappings, contractions, broadcasts or boundaries.
+
+Narrow bold label rail, left-aligned ragged-right `\small` content, 8–10 pt inner padding,
+0.4–0.6 em row gaps. Rail labels localize with the package option (`zh` default, `en`).
+Keep each row compact: prefer symbol semantics over numeric configuration. When it is too
+long, **remove content** — never add cards, columns or smaller type. Pass `{}` to omit a row.
+
+## Signature
+
+One centered line below the box, outside it, low-contrast gray, `\scriptsize` or smaller:
+`\stsignature{<subject>}{<fit node>}` renders `<subject>@五道口纳什`. The subject must name
+what this figure actually visualizes. Keep it on one line, with a small but visible gap.
+
+## Never
+
+Charts or metric insets not present in the primary formula. Decorative pills, banners,
+shadows, repeated separators, explanatory cards.
+
+## Reference image
+
+`assets/kimi-matrix-style-reference.png` — inspect it with an image viewer before drawing
+when entry-level matrix blocks are central or Kimi-like styling is requested. Use it only
+to calibrate tile spacing, rounding, neutral brackets, restrained hue, lightness separation
+and structural whitespace. Do not copy its content, and do not embed it in the output.
+
+## Language
+
+Chinese figures use concise Chinese labels with standard English terms where helpful
+(`softmax`, `All-Reduce`, `gather` stay in English). Switch the whole figure at once —
+`\usepackage[en]{supertensor}` plus English stage headings and box text — never mix.