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.

README.md

@@ -0,0 +1,87 @@
+# supertensor
+
+A shape-aware toolkit for drawing tensor formulas: a LaTeX/TikZ macro package, a build
+pipeline that fails on silent corruption, worked examples, and an agent skill that ties
+them together.
+
+It exists because figures of this kind fail in a specific way — they compile, they look
+clean, and they tell the reader something false. A face captioned `Kᵀ` that was never
+transposed; shards that do not tile their parent; an index tensor drawn with a lightness
+ramp. The package's job is to make the correct thing the easy thing.
+
+```
+SKILL.md              the skill entry point (lean; loads references on demand)
+references/           geometry, semantics, layout, style, api, checklist, antipatterns
+assets/supertensor.sty  the macro package
+scripts/preflight.sh  is the TikZ + CJK path available?
+scripts/build.sh      compile, audit the log, export pdf/svg/png/thumb
+examples/             three golden examples + an anti-pattern gallery
+```
+
+## Quick start
+
+```bash
+./scripts/preflight.sh                       # 0 = full path, 1 = degraded, 2 = no LaTeX
+./scripts/build.sh examples/mha-causal.tex   # -> examples/build/mha-causal.{pdf,svg,png}
+```
+
+A minimal figure:
+
+```tex
+\documentclass[border=10pt]{standalone}
+\usepackage[cjk]{supertensor}
+
+\stsetrole{act}{stTeal}      % one hue per tensor role, held across every stage
+\stsetrole{w}{stOrange}
+\stdim{T}{6}                 % one symbolic axis -> one physical edge length
+\stdim{d}{4}
+
+\begin{document}\begin{tikzpicture}
+  \stface[role=act, bracket=true]{X}{(0,0)}{T}{d}
+  \node[st op, right=6mm of X] (m) {$\times$};
+  \stface[role=w]{W}{($(m)+(1.4,0)$)}{d}{d}
+  \node[inner sep=0pt, fit=(X)(W)] (row) {};
+  \stlane{row}
+  \stcaption{X}{$\mathbf X$}{$T\times d$}
+  \stcaption{W}{$\mathbf W$}{$d\times d$}
+  \stnolane
+\end{tikzpicture}\end{document}
+```
+
+Because `T` and `d` come from the ledger, the contracted axis is automatically one edge
+length in both operands, `d×d` is automatically square, and any other face of shape `T×d`
+in the figure is automatically identical to `X`.
+
+See `references/api.md` for the full macro list.
+
+## Examples
+
+| file | shows |
+|---|---|
+| `tp-ffn-allreduce.tex` | column-then-row sharding, exact tiling, one hue per TP rank, a collective as a real node |
+| `mha-causal.tex` | leading axes as stack depth, a physically swapped `Kᵀ`, a mask in a different grammar from the scores it gates |
+| `moe-topk-gather.tex` | scores → indices → Boolean support → gather, with all three cell grammars side by side |
+| `antipatterns.tex` | four figures that compile cleanly and still teach something false |
+
+## Using it as an agent skill
+
+`SKILL.md` is the entry point; the `references/` files are loaded on demand. Point your
+agent runtime at this directory (for Claude Code, symlink or copy it under
+`~/.claude/skills/`). The skill assumes `scripts/` and `assets/` sit beside it.
+
+## Why the build script fails on warnings
+
+Two LaTeX warnings produce a figure that is quietly wrong rather than visibly broken:
+`Missing character` (a CJK glyph silently dropped — the label just is not there) and
+`Overfull \hbox` (text escaping its reserved lane and landing on a tensor). `build.sh`
+greps for both and exits non-zero. A `Package supertensor Warning` — an undeclared role
+falling back to gray — is treated the same way.
+
+A clean build still proves nothing about collisions, hue budget or whether the math is
+right. That is what `references/checklist.md` is for.
+
+## Provenance
+
+Extracted from the `tensor-formula-viz` skill in `wdkns-skills`, which remains in place
+unchanged. The prose rules that could be enforced mechanically became macros; the rest
+became `references/`.