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.

scripts/build.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Compile a supertensor figure and export every delivery artifact.
+#
+#   ./scripts/build.sh figure.tex [outdir]
+#
+# Produces in outdir (default: alongside the source, in build/):
+#   figure.pdf          vector master
+#   figure.svg          vector, for slides/web
+#   figure.png          white background, 300 dpi  <- inspect this one
+#   figure-alpha.png    transparent background
+#   figure-thumb.png    360 px wide  <- inspect this for the color/hue audit
+#
+# The build FAILS on silent-corruption signals, not only on TeX errors:
+# missing CJK glyphs and overfull boxes both produce figures that compile
+# happily and read wrong.
+set -euo pipefail
+
+SRC="${1:?usage: build.sh figure.tex [outdir]}"
+[[ -f "$SRC" ]] || { echo "no such file: $SRC" >&2; exit 2; }
+SRCDIR="$(cd "$(dirname "$SRC")" && pwd)"
+BASE="$(basename "$SRC" .tex)"
+OUT="${2:-$SRCDIR/build}"
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+mkdir -p "$OUT"
+
+echo "==> xelatex $BASE"
+# supertensor.sty lives in assets/; keep it off the user's texmf tree.
+TEXINPUTS="$ROOT/assets:$SRCDIR:" \
+  xelatex -halt-on-error -interaction=nonstopmode \
+          -output-directory="$OUT" "$SRC" >/dev/null 2>&1 \
+  || { echo "!! xelatex failed; last errors:" >&2
+       grep -n -A4 -m3 '^!' "$OUT/$BASE.log" >&2 || tail -30 "$OUT/$BASE.log" >&2
+       exit 1; }
+
+LOG="$OUT/$BASE.log"
+status=0
+
+if grep -q "Missing character" "$LOG"; then
+  echo "!! missing glyphs (CJK font not applied?):" >&2
+  grep -m5 "Missing character" "$LOG" >&2
+  status=1
+fi
+if grep -qE "^(Overfull|Underfull) \\\\[hv]box" "$LOG"; then
+  echo "!! overfull/underfull boxes -- text is escaping its reserved lane:" >&2
+  grep -m5 -E "^(Overfull|Underfull) \\\\[hv]box" "$LOG" >&2
+  status=1
+fi
+if grep -q "Package supertensor Warning" "$LOG"; then
+  echo "!! supertensor warnings:" >&2
+  grep -m5 -A2 "Package supertensor Warning" "$LOG" >&2
+  status=1
+fi
+
+if command -v pdftocairo >/dev/null 2>&1; then
+  echo "==> exporting svg / png"
+  pdftocairo -svg "$OUT/$BASE.pdf" "$OUT/$BASE.svg"
+  pdftocairo -png -r 300 -singlefile                "$OUT/$BASE.pdf" "$OUT/$BASE"
+  pdftocairo -png -r 300 -singlefile -transp        "$OUT/$BASE.pdf" "$OUT/$BASE-alpha"
+  pdftocairo -png -scale-to-x 360 -scale-to-y -1 -singlefile \
+                                                    "$OUT/$BASE.pdf" "$OUT/$BASE-thumb"
+else
+  echo "!! pdftocairo missing: PDF only, no SVG/PNG" >&2
+  status=1
+fi
+
+echo "==> artifacts in $OUT"
+ls -1 "$OUT/$BASE"*.{pdf,svg,png} 2>/dev/null | sed 's/^/    /'
+if [[ $status -ne 0 ]]; then
+  echo "==> BUILD DIRTY: fix the warnings above before delivering." >&2
+else
+  echo "==> clean. Now do the visual audit (references/checklist.md) --"
+  echo "    a clean build says nothing about collisions or hue budget."
+fi
+exit $status