---
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; fall back to SVG/matplotlib and say
   explicitly that the figure is not TikZ.
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 reserve
   stage lanes and draw. See `references/layout.md` and `references/api.md`.
5. **Build and audit.** `./scripts/build.sh fig.tex`. A clean build only proves TeX was
   happy; then run the visual audit in `references/checklist.md` against the PNG at full
   size and at thumbnail size. Redraw on any mandatory-invariant 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 | `\starrow`, `\starrowlabel`, `st comm` |

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.
- **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.
- The identification line is `\stsignature{<subject>}{<box>}`; it renders
  `<subject>@五道口纳什`. Change the handle with `\stsetauthor{...}` only when asked.

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