# superfig

A paper-figure toolkit for non-tensor diagrams: a LaTeX/TikZ macro package, a
build pipeline that fails on silent corruption, worked examples, and an agent
skill that ties them together.

It is the generic-node sibling of `supertensor`. Same house style, same
role/cursor/warning discipline. The primitives are nodes, edges and groups,
not tensor faces. Use `supertensor` when axis lengths and shape identities
are the claim.

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 node/edge figures.

```
SKILL.md              the skill entry point (lean; loads references on demand)
references/           grammar, layout, style, api, checklist, antipatterns
assets/superfig.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
scripts/test.sh       positive examples plus negative package/lint fixtures
examples/             four golden examples + an anti-pattern gallery
```

## Quick start

```bash
./scripts/preflight.sh                          # 0 = full path, 1 = degraded, 2 = no LaTeX
./scripts/build.sh examples/pipeline.tex        # -> examples/build/pipeline.{pdf,svg,png}
./scripts/test.sh
```

A minimal figure:

```tex
\documentclass[border=10pt]{standalone}
\usepackage[cjk]{superfig}

\sfsetrole{input}{sfTeal}
\sfsetrole{model}{sfOrange}

\begin{document}\begin{tikzpicture}
  \sfstage{S}{one band, placed by cursor}
  \sfrow{R1}{14mm}
    \sfnode[role=input]{x}{输入 $x$}{16mm}{12mm}
    \sfconn{e1}{预处理}
    \sfnode[role=model]{f}{模型 $f_\theta$}{18mm}{12mm}
  \sfrowend
  \sflane{R1}
  \sfcaption{x}{$x$}{原始输入}
  \sfcaption{f}{$f_\theta$}{可学习参数}
\end{tikzpicture}\end{document}
```

See `references/api.md` for the full macro list.

## Examples

| file | shows |
|---|---|
| `pipeline.tex` | cursor flow; loss as a side object, not a station on the forward path |
| `branch-architecture.tex` | residual skip; a group captioned on the shared lane |
| `state-flow.tex` | time/state step; one `\sfcallout` on a finished band |
| `dependency-graph.tex` | dual-encoder join, fusion placed from existing anchors |
| `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. The skill assumes `scripts/` and
`assets/` sit beside it.

## Why the build script fails on warnings

`Missing character` drops a CJK glyph silently. `Overfull \hbox` lets a label
escape its lane. `Package superfig Warning` is an undeclared role, a
single-member group, a band overflow, a second callout, or a callout hanging
off a node. `build.sh` greps for all of them and exits non-zero.

A clean build also proves the source avoided raw TikZ drawing, a formula
placed before the last row, and more than four active hues. It still cannot
prove that the relationships are right; that is what `references/checklist.md`
is for.