# 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.

This repository is a **child** of SuperPaper, the family parent that
routes paper notes to the right figure toolkit. Clone SuperPaper with
`--recurse-submodules` for the whole family; use this directory alone
when you only need shape-aware tensor figures.

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/lint.py       reject source-level invariant escapes
scripts/build.sh      lint, 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}
  \ststage{S1}{one band, placed by cursor}
  \strow{row}{T}                            % band height, declared once
    \stface[role=act, bracket=true]{X}{}{T}{d}   % empty coord = at the cursor
    \stglyph{m}{$\times$}
    \stface[role=w]{W}{}{d}{d}
  \strowend
  \stcaption{X}{$\mathbf X$}{$T\times d$}
  \stcaption{W}{$\mathbf W$}{$d\times d$}
\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`.

Because the coordinates are empty, each object reserves its own width and the gap between
them is `\stgutter`, declared once. Nothing here is a tuned offset, so growing a label can
only push its neighbours apart — it can never land on top of one. And the band declares its
height, so an object that does not fit is a failed build rather than something the reader
discovers.

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, a `\stcol` split along the contracted axis |
| `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.

The flow layout adds two of its own: an object that overflows its band, and a `\stcol`
whose contents do not add up to the height it declared (which means it is drawn
off-center). Both are things a reader would have to notice for you.

A clean build now also proves the source avoided untracked absolute objects, ledger
changes, raw rectangles, unclosed `\stgroup` blocks, side cards anchored to a single face
or doubled up on one band, and excess per-row hues. It still cannot prove that the math,
semantics or rendered relationships are 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/`.