anatomy

Files (111)

• .gitattributes
• .gitignore
• CHANGELOG.md
• LICENSE
• README.md
• SKILL.md
• UPSTREAM.md
• openai.yaml · agents/
• evals.json · evals/
• arcade-cabinet.css · examples/arcade-cabinet/
• build.mjs · examples/arcade-cabinet/
• live.js · examples/arcade-cabinet/
• parts.mjs · examples/arcade-cabinet/
• screen.mjs · examples/arcade-cabinet/
• build.mjs · examples/desk-computer/
• build.mjs · examples/dial-indicator/
• build.mjs · examples/raptor-engine/
• live.js · examples/raptor-engine/
• raptor.css · examples/raptor-engine/
• build.mjs · examples/ripple-tank/
• live.js · examples/ripple-tank/
• model.mjs · examples/ripple-tank/
• ripple.css · examples/ripple-tank/
• art.tsx · examples/spot-plate/
• drops.ts · examples/spot-plate/
• fan.ts · examples/spot-plate/
• figure.tsx · examples/spot-plate/
• geometry.ts · examples/spot-plate/
• live.tsx · examples/spot-plate/
• rig.ts · examples/spot-plate/
• spot-plate.css · examples/spot-plate/
• art.tsx · examples/test-rig/
• figure.tsx · examples/test-rig/
• geometry.ts · examples/test-rig/
• live.tsx · examples/test-rig/
• pose.ts · examples/test-rig/
• rig.ts · examples/test-rig/
• stretch.css · examples/test-rig/
• view.ts · examples/test-rig/
• build.mjs · examples/turning-dial/
• dial.css · examples/turning-dial/
• live.js · examples/turning-dial/
• stress.mjs · examples/turning-dial/
• audit.mjs · kit/
• canvas-painter.mjs · kit/
• gl-shared.mjs · kit/
• gl.mjs · kit/
• iso-kit.mjs · kit/
• iso-kit.ts · kit/
• iso.css · kit/
• lathe.mjs · kit/
• draw.tsx · kit/react/
• live.tsx · kit/react/
• tube.mjs · kit/
• turn-audit.mjs · kit/
• turn-build.mjs · kit/
• turn-fixed.mjs · kit/
• turn.mjs · kit/
• 3d.md · references/
• craft.md · references/
• …and 51 more

SKILL.md (first lines)

## Aeon runtime integration

On Aeon this skill runs headless in a GitHub Actions job through the configured harness adapter, and `.github/workflows/aeon.yml` kills that job at 50 minutes. **The rules in this section override any upstream guidance below that conflicts with them** (sizing, timings, asking or telling the user, and where files are written). Everything from `# Anatomy` down is the vendored upstream text, kept verbatim; read it through these rules.

Today is ${today}.

### 1. Brief

`${var}` is the illustration brief, for example `"how a write-ahead log survives a crash"`. If `${var}` is empty, append `ANATOMY_NO_VAR` under `### anatomy` in `memory/logs/${today}.md` and exit 0 with no build and no notify: a figure costs real CI time, so a blank default run does nothing.

### 2. Headless: never ask

Nobody is there to answer. Never ask a question, wait for a choice, or "tell the user" before working. Where the upstream text says to tell, ask or wait for the user, decide yourself and put the decision (size, any downscale) in the notify and the log instead.

### 3. Time budget and size

Run `date` at the start and at each step. The whole run (research, build, checks, commit, notify) must fit in about 35-40 minutes so the job is never killed. This replaces upstream workflow step 1 and its estimates:

- Build a **Figure** or smaller: one mechanism, 40-80 parts, SVG with at most one WebGL layer. Have a page that builds and opens by about minute 15, then deepen it.
- A brief that reads as a **Hero** or an **Epic**, or that needs the 3D mode, is downscaled to a Figure that keeps the core of the idea. Never start a Hero, an Epic or a 3D figure on Aeon (the 3D orbit audit alone takes 15-20 minutes). Say in the notify what the full version would add.
- Use the framework-free path (a Node build script writing one standalone HTML page). The runner has no React or TypeScript toolchain for this skill.
- Checks, in order of value: the build, `--audit` when the figure has pipes, cables or round parts, `scripts/lines.mjs`, and one desktop plus one phone (390 wide) capture with `scripts/capture.mjs`. Skip the long close-up sweeps and shader contact sheets when time is short, and say which checks were skipped.
- At about minute 30, stop adding detail and run the final checks. At about minute 38, deliver what you have if the page builds and opens, with `--severity warn` naming what is unfinished.

### 4. Work outside the repo

Never write anything inside `skills/anatomy/`: the run's commit step stages the whole worktree, so files built there would land in the repo. Copy the skill to a scratch directory and do all work there (examples, your figure, `shots/`, browser profiles):

```bash
REPO_ROOT=$(pwd)
WORK="${RUNNER_TEMP:-/tmp}/anatomy-run"
rm -rf "$WORK" && mkdir -p "$WORK" && cp -R skills/anatomy "$WORK/anatomy"
cd "$WORK/anatomy"
node examples/dial-indicator/build.mjs          # builds an example inside the copy
```

The examples ship as source only (`build.mjs` and its modules); their built `.html` pages are not checked in. To look at one, build it in the copy as above (add `--light` for the light theme) and capture it; read `build.mjs` and its modules for the code. Put your own figure at `$WORK/anatomy/examples/<slug>/build.mjs`, where `<slug>` is a short name you pick from the brief (lowercase `a-z`, `0-9` and hyphens, at most 40 characters), so its `../../kit/` and `../../scripts/` imports resolve like the examples'. If the scripts cannot find Chrome, set `CHROME_PATH` (for example `/usr/bin/google-chrome`).

### 5. Deliver the figure

The deliverable is one self-contained HTML page (kit inlined with `kitScript()`, no external files), dark theme unless the brief asks for light, plus a desktop screenshot. Copy them into the repo; the workflow's commit step commits `output/**` after the run:

```bash
cd "$REPO_ROOT"
OUT="output/anatomy/${today}-<slug>"
mkdir -p output/anatomy
cp "$WORK/anatomy/examples/<slug>/<slug>.html" "$OUT.html"
cp "$WORK/anatomy/shots/<slug>-desktop.png" "$OUT.png"    # if a capture was made
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
```

One figure per run. Links: `https://github.com/${REPO}/blob/main/${OUT}.png` shows the screenshot, and `https://github.com/${REPO}/raw/main/${OUT}.html` is the page (GitHub shows HTML as source, so download it and open it in a browser). They go live once the run's commit lands, about a minute after the run.

### 6. Record, notify, log

- Append one line to `memory/state/anatomy-figures.jsonl`: `{"date","brief","slug","size":"figure","parts":N,"html":"output/anatomy/...","png":"...","bytes":N,"checks":{"build":"pass","audit":"pass|skipped","lines":"pass|N ends","capture":"pass"}}`.
- Notify once: write a short body (title, one line on what moves and what that motion means, the two links, size and parts, checks, any downscale) to `.pending-notify-temp/anatomy-${today}.md` (`mkdir -p .pending-notify-temp` first), then run `./notify --severity success -f .pending-notify-temp/anatomy-${today}.md`. On a failed or partial run use `--severity warn` and say what happened and the one thing the operator can do.
- Append under `### anatomy` in `memory/logs/${today}.md`: the brief, the result (`ANATOMY_OK`, `ANATOMY_DOWNSCALED`, `ANATOMY_PARTIAL`, `ANATOMY_FAILED` or `ANATOMY_NO_VAR`), the output paths and the checks.

### 7. Evals and boundaries

`evals/evals.json` is the evaluation corpus for skill-repair, self-improve and manual validation; a normal run builds the brief, not an eval. Aeon's normal scorer writes the run score and `skill-health` ranks it; do not create a parallel health or repair ledger. Don't modify `aeon.yml`, other skills, or the vendored files under `skills/anatomy/`.

# Anatomy

This skill makes figures like a small instrument on a bench: a heavy base on feet, rails with tick rulers, a carriage on bushings, knurled knobs, coil springs, a dial gauge whose needle moves, screws as tiny dots. The reader understands the idea because they recognise the machine. Every number the figure shows comes from the same model that moves its parts.

Eight complete examples ship with the skill. Open the closest one before you start. Each framework-free example is built with `node examples/<name>/build.mjs`, which writes a standalone HTML page next to the script; add `--light` for the light theme.

- `examples/dial-indicator/` is the smallest: a dial gauge on a stand, about 300 lines in all.
- `examples/desk-computer/` is framework-free SVG: a desk computer with a keyboard you can type on. The typed line appears on a CRT screen drawn in the plane of the case front, and the picture collapses to a line and a dot when you switch it off. It has about 85 solids and 850 paths.
- `examples/arcade-cabinet/` is an upright arcade cabinet with its side panel off, a Hero of about 240 solids and 15 cables. A quarter flies into the slot, rolls down the coin chute at the speed a rolling disc reaches on a 30° slope, trips the coin-switch wire and drops into the cash box; the switch's pulse runs chunk by chunk along its cable to the board, and the CRT warms up, self-tests and runs an attract mode drawn in the plane of the tilted monitor. The stick tilts and closes a microswitch under the panel. It shows how to place a camera so a cutaway's mechanism stays in view, a concave board drawn as a prism along any axis, moving parts rebuilt in the page from the same module the build uses, and live coins and a wire drawn in reserved slots of the settled order. `node build.mjs --audit` proves the geometry.
- `examples/raptor-engine/` is a rocket engine hanging in a test stand. Its round parts come from `kit/lathe.mjs` and its pipes and harness from `kit/tube.mjs`. It comes apart into 11 assemblies with staggered springs and per-frame depth re-sorting. Every part records its true shape, and `node build.mjs --audit` (`kit/audit.mjs`) proves, at rest, apart and in every replayed frame of the explode, that nothing passes through anything, that every end sits on a real mount, that no bend pinches, folds or lands on another line, that no curved profile's slope wobbles, and that every overlap is drawn in depth order. A WebGL plume, shock, splash and steam render between the back and front SVG. It is the reference for dense pipework, smooth shading and fades.
- `examples/ripple-tank/` is a school ripple tank on tall legs over a paper screen, seen from 44° up. Two WebGL layers (lamp light, shadows and caustics on the paper, and the water's reflections and glass) are registered to the isometric planes and driven by a pure dispersion and optics model (`model.mjs`); a frequency change travels out from the dippers through a history texture.
- `examples/test-rig/` is a production figure from a real site (React/Next): a glass button on a spring-mounted carriage, a finger probe on a rail that presses and pulls, and a dial gauge reading the lean. It has 53 solids and about 470 paths.
- `examples/spot-plate/` is a second production figure from the same site: six pairs of glass drops on a spot plate, each pair drawn from one distance field, so a pair closer than `merge` runs together into one piece of glass. A fan of feeler blades sets `merge`, one blade per gap. It is the reference for shapes that morph into each other and for one control driving many parts.
- `examples/turning-dial/` is the optional 3D mode: a combination dial that turns in true 3D with a small robot hand on it. It has about 90 live parts in metal materials, a second turn group, a hinge, a three-hinge finger that lifts and a pod that breaks off as a free body. A WebGL LED, its light pool and sparks follow the moving parts. `stress.mjs` beside it is a dense hand of about 380 parts in a cluttered workshop, used to measure performance.

The test rig is the quality bar for the drawing itself. The Raptor is the bar for shader work: a WebGL effect has to reach its standard of world-space, no-pop, seamless rendering.

## The one idea that matters

**The object is the explanation.** Don't draw boxes, arrows and labels. Invent a real, well-made physical thing whose working *is* the concept. Here is how earlier figures mapped:

| Concept | Object |
|---|---|
| One shared GPU context serving many canvases | A gantry plotter: one print head visiting 16 wells |
| A cache key that skips work when nothing changed | A pin-tumbler lock: when every pin matches, the plug turns and nothing is redrawn |
| Seven render targets with different bytes per texel | A chest of seven drawers, each as deep as its bytes |
| A separable blur (49 × 49 taps vs 49 + 49) | A bed-of-nails stamp beside two combs on rails |
| A spring that presses and leans | A test rig with springs, a probe and a dial gauge |
| A height profile | A profile (contour) gauge pressed against the edge |
| Light that depends on facing | A small photo studio: key and fill lamps around a turntable |

Two ways this fails, both seen in practice:

- **Too abstract.** Stacked plates, floating slabs or labelled boxes don't read as anything.
- **Too flat and bland.** One big slab with a few lines on it has no volume, no parts and nothing to discover.

The fix for both is the same: a recognisable machine, built from many small, precise, purposeful parts.

**Every creation is highly detailed.** This holds for every figure, however small the idea or the request: a quick explainer is still a dense, real machine, never a few slabs. What scales with the size (workflow step 1) is how far you push it: a Figure gets the 4× sweep over its subject and mechanism, a Hero or an Epic over the whole drawing.
- **Read the real thing.** Build it the way the real object is built: every screw, seam, bevel, bushing, label plate, cable with its connector, scale with its ticks, and the parts that hold the parts.
- **Two looks.** At 1× it reads as one clear machine. At 4× every region still has something true to find; a bare face or an empty corner is unfinished work, not calm.
- **Purposeful, never noise.** Detail comes from parts that belong to the mechanism. Each one sits on another part, ends on an edge, and fades rather than stops.
- **Check it last.** Before you finish, zoom to 4× (over the subject and mechanism for a Figure, the whole drawing for a Hero or an Epic) and add the real parts that are missing wherever a region is plain.

## Workflow

Work in this order. Write the concept and the parts list before any geometry. Most of the quality is decided there.

1. **Size it before you start.** Tell the user which size the request is and roughly how long it will take, before any other work.
   - **Figure**: one mechanism, 40–80 parts, SVG with at most one WebGL layer. About 30–90 minutes. Build it without asking.
   - **Hero**: a dense object, several WebGL layers or one 3D subject, 80–150 parts. About 2–4 hours. Say so, then build it unless the user asked for something quick.
   - **Epic**: a whole vehicle, building or plant with many moving systems, or the 3D mode on more than one subject. 6 hours or more. Do not start it. Give the estimate, propose a Hero version that keeps the core of the idea, and list what the full version would add. Build the Epic only when the user chooses it.
   - Whatever the size, have a working page that opens in the browser within the first hour, and deepen it from there. Run `date` at the start and at each step, and when a step runs past twice its share of the estimate, tell the user where it stands and what is left.
2. **Truth first.** Collect the real numbers and behaviour of the thing being explained: sizes, counts, thresholds, curves. The readout, motion and caption must all be true. If you can, write the model as a small pure module, like `rig.ts` in the test-rig example, and drive everything from it.
3. **Invent the object.** Pick a machine, tool, instrument or piece of furniture whose mechanism maps one-to-one onto the concept. Say in one sentence what moves and what that motion means. Never copy a reference image: take its finish, not its object.
4. **Parts list.** Write at least 40 parts (40–80 for a Figure, 80–150 for a Hero, more for an Epic), grouped: base (plate, feet, groove, corner screws, label plate, ruler strip), structure (posts, rails, frame bars, end stops), mechanism (carriage, bushings, springs, plunger, needle), controls (knurled knob, thumb screw, crown) and the subject itself, which is the one lit part. Each part sits on another part. `references/craft.md` has a vocabulary of parts with recipes.

From aeonfun/aeon, MIT.

More from aeonfun/aeon