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/preflight.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Toolchain preflight for supertensor. Run this BEFORE drawing anything:
+# it decides whether the TikZ path is available or the figure must fall back.
+#
+#   ./scripts/preflight.sh          human-readable report
+#   ./scripts/preflight.sh --quiet  exit code only (0 = full TikZ path OK)
+#
+# Exit codes: 0 full path, 1 degraded (no CJK), 2 no LaTeX at all.
+set -uo pipefail
+
+QUIET=0
+[[ "${1:-}" == "--quiet" ]] && QUIET=1
+say() { [[ $QUIET -eq 1 ]] || echo -e "$*"; }
+
+ok=0; warn=0; fail=0
+check() { # name, command
+  local name="$1"; shift
+  if "$@" >/dev/null 2>&1; then say "  ok    $name"; ok=$((ok+1)); return 0
+  else say "  MISS  $name"; return 1; fi
+}
+
+say "supertensor preflight"
+say "--- required ---"
+check "xelatex"            command -v xelatex            || fail=$((fail+1))
+check "standalone.cls"     kpsewhich standalone.cls      || fail=$((fail+1))
+check "tikz.sty"           kpsewhich tikz.sty            || fail=$((fail+1))
+check "xstring.sty"        kpsewhich xstring.sty         || fail=$((fail+1))
+
+say "--- chinese figures ---"
+check "ctex.sty"           kpsewhich ctex.sty            || warn=$((warn+1))
+check "fandol font"        kpsewhich FandolSong-Regular.otf || warn=$((warn+1))
+
+say "--- raster / vector export ---"
+check "pdftocairo"         command -v pdftocairo         || warn=$((warn+1))
+check "latexmk (optional)" command -v latexmk            || true
+
+if [[ $fail -gt 0 ]]; then
+  say ""
+  say "RESULT: no usable LaTeX path."
+  say "Fall back to an SVG or matplotlib figure and say so explicitly in the"
+  say "delivery; do not silently ship a lower-fidelity figure as if it were TikZ."
+  exit 2
+fi
+if [[ $warn -gt 0 ]]; then
+  say ""
+  say "RESULT: degraded."
+  say "  - missing ctex/fandol  -> English-label figures only; do not substitute"
+  say "    an OS-specific CJK font without telling the user it costs portability."
+  say "  - missing pdftocairo   -> deliver PDF only, and say PNG/SVG were skipped."
+  exit 1
+fi
+say ""
+say "RESULT: full path available (TikZ + CJK + vector/raster export)."
+exit 0