---
name: supertensor
description: Create or refine clean, shape-aware figures for tensor/matrix/vector formulas or tensor code — matrix-block diagrams, entry heatmaps, row/column shard stripes, stacked 3D/4D tensors, attention, tensor/expert parallelism, broadcasting, reductions, contractions, gather/scatter and routing. Use whenever tensor shapes or axis meanings must be visually aligned with the computation. Not for plotting numeric data (loss curves, benchmark bars, scatter plots), architecture block diagrams without shapes, or generic flowcharts.
---

# supertensor

Turn a formula or a tensor-code path into one dense, slide-ready figure with three zones:

1. **Top — formula.** The clean mathematical definition. No shape underbraces.
2. **Middle — computation.** Colored faces, shards, stacks, operators, collectives.
3. **Bottom — meaning.** Axes, object semantics, mechanism. One box, three rows.

The `assets/supertensor.sty` package enforces most of the geometry and style rules
by construction. **Draw with the package; do not hand-roll `\draw` rectangles.**
A figure built from raw TikZ has to re-earn every invariant by hand and usually fails one.

## Workflow

1. **Preflight.** `./scripts/preflight.sh`. Exit 0 = TikZ+CJK path. Exit 1 = degraded
   (say so in the delivery). Exit 2 = no LaTeX; read `references/fallback.md` before
   falling back and state explicitly which package guarantees are unavailable.
2. **Reduce** the input to one primary computation path. Drop equivalent objectives,
   diagnostics, and secondary metrics unless asked for.
3. **Build two ledgers** before drawing anything:
   - *shape & semantics* — per symbol: semantic kind, dtype/domain, global and local
     shape, axis meanings, producer/consumer, contracted/broadcast/reduced axes.
     See `references/semantics.md`.
   - *geometry* — one `\stdim{axis}{cells}` per symbolic axis, one `\stsetrole{role}{color}`
     per tensor role. Declaring these makes the invariants automatic.
     See `references/geometry.md`.
4. **Pick the smallest grammar** that exposes the mechanism (see below), then draw with the
   flow layout — `\ststage` / `\strow` … `\strowend`, empty coordinate arguments, gaps
   declared once. Reach for an absolute coordinate only when no band can express the
   placement. See `references/api.md` and `references/layout.md`.
5. **Build and audit.** `./scripts/build.sh fig.tex` runs the source linter, TeX checks and
   exports. Then run the remaining visual/semantic audit in `references/checklist.md`
   against the PNG at full size and thumbnail size. Redraw on any mandatory violation.

For code input, trace the concrete `matmul`, `einsum`, `reshape/view`, `transpose/permute`,
concat, broadcast, and collective calls. Keep code variable names where useful; state any
shape or convention you inferred.

## Choose the visual grammar

| Fact to expose | Grammar | Package |
|---|---|---|
| mask, sparsity, causal structure, elementwise roles | entry cells | `\stface[pattern=causal/lower/band/diag/data]` |
| sharding, device ownership, channel groups | adjacent faces tiling a parent | two `\stface` calls, one role each |
| leading axes (`B`, `h`) | depth | `\ststack{...}{sheets}` |
| discrete choices (indices, token ids, expert ids) | symbols in cells, no ramp | `\stindexface` |
| data movement, collectives, non-linear ops | arrows and nodes | `\stlink`, `\stcomm` |
| a split along the contracted axis | a vertical pair inside one band slot | `\stcol` … `\stcolend` |
| adjacent objects that are one composite (heads of `q`, shards of `W`) | an outline in their own role hue | `\stgroup` … `\stgroupend` |
| an aside about a whole band | a side card off its right edge, one per band | `\stcallout` |

Combine grammars only when each one adds information. Known zeros stay unfilled; masks,
diagonals, sparsity and partitions must encode their exact structure.

## Non-negotiables

These are the rules that make the figure *true* rather than merely pretty. Each has a
reference file with the full statement and the failure it prevents.

- **Geometry** (`references/geometry.md`) — one symbolic axis, one physical edge length,
  everywhere. `a×a` is a square. A transpose swaps the face, not the label. Both
  occurrences of a contracted `k` are the same length. Shards tile their parent exactly.
- **Semantics** (`references/semantics.md`) — one block, one semantic object. Scores,
  indices and masks are three different grammars, never one heatmap. Close the chain
  from continuous score to discrete index to gathered value.
- **Layout** (`references/layout.md`) — everything is a bounding box; tangency counts as
  collision. Reserved lanes for stage heading / tensors / symbols / shapes. Connectors on
  the background layer, text on the foreground layer. Place by cursor, not by hand-tuned
  coordinate: a magic-number offset is only valid for the content it was tuned against.
- **Style** (`references/style.md`) — muted palette, one hue per role, ≤4 active hues per
  row plus gray, three separated lightness levels, non-periodic texture, no decoration.

`references/antipatterns.md` shows what each violation looks like in a rendered figure —
read it once before your first figure.

## Output

Default to editable TikZ. `scripts/build.sh` emits PDF, SVG, white-background PNG,
transparent PNG and a thumbnail. Deliver: the PNG preview, a short mechanism explanation,
and the `.tex` source plus vector artifact.

- **Chinese figures:** `\usepackage[cjk]{supertensor}` (XeLaTeX + portable Fandol). Do not
  select an OS-specific CJK font unless the user asks and accepts the portability cost.
- **English figures:** `\usepackage[en]{supertensor}` — same geometry, English rail labels.
- Keep math in LaTeX, not raw Unicode.
- Add `\stsignature{<subject>}{<box>}` only when the user or house template asks for an
  identification line. It renders only the subject, with no author or handle.

## Iterating

When the user asks for a change, do not restart the figure. Edit the ledger or the one
call that owns the offending object, rebuild, and re-audit. If a fix requires shrinking
type, closing the gutter, or covering another object, the layout is wrong — move the stage
to another row instead. Ask before dropping a stage or an object the user named.