@pebbly/aseprite-ai-artist 0.1.0

package/extension/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "aseprite-ai-artist",
+  "displayName": "Aseprite AI Artist",
+  "description": "Lets a coding agent draw in this Aseprite session over a local WebSocket link. Connects to 127.0.0.1 only; nothing leaves the machine.",
+  "version": "0.1.0",
+  "author": "with-pebbly",
+  "publisher": "with-pebbly",
+  "license": "MIT",
+  "categories": ["Scripts"],
+  "contributes": {
+    "scripts": [{ "path": "./ai-artist.lua" }]
+  },
+  "api": 1
+}

package/hooks/hooks.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-status.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__plugin_aseprite-ai-artist_aseprite__draw|mcp__plugin_aseprite-ai-artist_aseprite__recolor|mcp__plugin_aseprite-ai-artist_aseprite__transform",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/look-nudge.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/look-nudge.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * After a mutating pixel operation, remind the model to look at the result.
+ *
+ * Not looking is the single most common failure mode: the tool result says
+ * "412 pixels changed" and the model reports a finished sprite it has never
+ * seen. The nudge fires once per session so it stays a reminder rather than
+ * noise the model learns to skip.
+ */
+
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+let payload = {};
+try {
+  payload = JSON.parse(readFileSync(0, "utf8"));
+} catch {
+  process.exit(0);
+}
+
+const sessionId = payload.session_id || "unknown";
+const stateDir = path.join(
+  process.env.CLAUDE_PLUGIN_DATA || path.join(os.tmpdir(), "aseprite-ai-artist"),
+  "look-nudge",
+);
+const marker = path.join(stateDir, `${sessionId}.seen`);
+
+if (existsSync(marker)) process.exit(0);
+
+try {
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(marker, String(Date.now()));
+} catch {
+  // A hook that cannot write its marker should still nudge once, not crash.
+}
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext:
+        "You just changed pixels. Call `look` before deciding whether it worked — op 'preview' for the overall read, op 'ascii' for exact pixel positions. A tool result saying pixels changed is not evidence that the sprite is right.",
+    },
+  }),
+);

package/hooks/session-status.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Tells the session whether Aseprite is actually reachable, before the model
+ * tries to draw and gets a confusing failure five tool calls in.
+ *
+ * Deliberately cheap: a raw TCP connect to the bridge's control port, no
+ * dependencies, hard 400ms budget. A hook that slows session start is a hook
+ * people disable.
+ */
+
+import net from "node:net";
+
+const CONTROL_PORT = Number(process.env.ASEPRITE_AI_CONTROL_PORT || 9932);
+const PLUGIN_PORT = Number(process.env.ASEPRITE_AI_PLUGIN_PORT || 9931);
+const BUDGET_MS = 400;
+
+function probe(port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: "127.0.0.1", port });
+    const done = (open) => {
+      socket.destroy();
+      resolve(open);
+    };
+    socket.setTimeout(BUDGET_MS);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+const [bridge, plugin] = await Promise.all([probe(CONTROL_PORT), probe(PLUGIN_PORT)]);
+
+// The plugin port being open means the bridge is listening for Aseprite, not
+// that Aseprite has connected — only `preflight` can answer that, so say so
+// rather than implying a readiness this probe cannot see.
+const message = bridge
+  ? `aseprite-ai-artist: bridge is up on :${CONTROL_PORT}. Call preflight before any drawing to confirm Aseprite itself is attached.`
+  : `aseprite-ai-artist: no bridge on :${CONTROL_PORT} yet — it starts on the first tool call. If drawing fails, run \`npx @pebbly/aseprite-ai-artist doctor\`.`;
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: message,
+    },
+  }),
+);

package/knowledge/palettes.json

@@ -0,0 +1,60 @@
+{
+  "$comment": "Bundled palette presets. Values are transcribed from each palette's published definition; see docs/PALETTES.md for provenance and how to add more. Anything not listed here can still be loaded from a .gpl/.hex/.pal/.png file via palette op 'load'.",
+  "presets": {
+    "pico8": {
+      "name": "PICO-8",
+      "author": "Lexaloffle",
+      "size": 16,
+      "notes": "Fantasy-console fixed palette. Strong, saturated, forgiving — a good default when a user says 'retro' without more detail.",
+      "colors": [
+        "#000000", "#1d2b53", "#7e2553", "#008751",
+        "#ab5236", "#5f574f", "#c2c3c7", "#fff1e8",
+        "#ff004d", "#ffa300", "#ffec27", "#00e436",
+        "#29adff", "#83769c", "#ff77a8", "#ffccaa"
+      ]
+    },
+    "gameboy": {
+      "name": "Game Boy (DMG)",
+      "author": "Nintendo",
+      "size": 4,
+      "notes": "The original green LCD. Four values only — everything is silhouette and value contrast, no colour to hide behind.",
+      "colors": ["#0f380f", "#306230", "#8bac0f", "#9bbc0f"]
+    },
+    "gameboy-pocket": {
+      "name": "Game Boy Pocket",
+      "author": "Nintendo",
+      "size": 4,
+      "notes": "Neutral grey variant of the DMG ramp.",
+      "colors": ["#000000", "#555555", "#aaaaaa", "#ffffff"]
+    },
+    "cga": {
+      "name": "CGA (16-colour)",
+      "author": "IBM",
+      "size": 16,
+      "notes": "IBM CGA/EGA text palette. Harsh, high-contrast, unmistakably 1980s PC.",
+      "colors": [
+        "#000000", "#0000aa", "#00aa00", "#00aaaa",
+        "#aa0000", "#aa00aa", "#aa5500", "#aaaaaa",
+        "#555555", "#5555ff", "#55ff55", "#55ffff",
+        "#ff5555", "#ff55ff", "#ffff55", "#ffffff"
+      ]
+    },
+    "1bit": {
+      "name": "1-bit",
+      "author": "—",
+      "size": 2,
+      "notes": "Pure black and white. Forces dithering for every intermediate value.",
+      "colors": ["#000000", "#ffffff"]
+    },
+    "grayscale-8": {
+      "name": "Grayscale 8",
+      "author": "—",
+      "size": 8,
+      "notes": "Even value ramp. Useful as a working palette while blocking in form, before colour is chosen.",
+      "colors": [
+        "#000000", "#242424", "#484848", "#6d6d6d",
+        "#919191", "#b6b6b6", "#dadada", "#ffffff"
+      ]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@pebbly/aseprite-ai-artist",
+  "version": "0.1.0",
+  "description": "Agent-native control layer for Aseprite. MCP server (2025-11-25 spec, designed forward to 2026-07-28) + cross-agent skills for Claude Code, Codex, Gemini CLI and Cursor.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "bin": {
+    "aseprite-ai-artist": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "extension",
+    "skills",
+    "rules",
+    "agents",
+    "hooks",
+    "knowledge",
+    "templates",
+    "examples",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/with-pebbly/aseprite-ai-artist.git"
+  },
+  "homepage": "https://github.com/with-pebbly/aseprite-ai-artist#readme",
+  "bugs": "https://github.com/with-pebbly/aseprite-ai-artist/issues",
+  "keywords": [
+    "aseprite",
+    "pixel-art",
+    "mcp",
+    "model-context-protocol",
+    "sprites",
+    "animation",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "cursor"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --experimental-strip-types tests/color.test.ts tests/render.test.ts tests/bridge.test.ts tests/server.test.ts",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test:extension": "aseprite -b --script-param root=. --script tests/extension.test.lua",
+    "test:e2e": "node tests/e2e.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ws": "^8.21.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.2"
+  }
+}

package/rules/00-core-principles.md

@@ -0,0 +1,57 @@
+# Core principles
+
+Pixel art is not "a small image". It is an image where every pixel was a
+decision. That constraint is the whole medium: an agent that treats a 32×32
+canvas as a low-resolution render will produce something that is technically
+correct and unmistakably wrong.
+
+## The loop
+
+Inspect → decide → draw in one batch → look → fix → validate.
+
+Skipping "look" is the single most common failure. You cannot tell from a tool
+result whether a sprite reads; you have to see it. `look` op `preview` shows you
+what a human sees; op `ascii` shows you exactly which pixel is where.
+
+## Resolution is a budget, not a limitation
+
+At 16×16 a character gets roughly 3 pixels of head, 5 of torso and 4 of legs.
+There is no room for a nose. Decide what the sprite must communicate at a
+glance — a class, a threat, a direction — and spend the pixels there.
+
+Common sizes and what fits:
+
+| Size | Fits |
+|------|------|
+| 8×8 | An icon or an item. One idea. |
+| 16×16 | A readable character with 2–3 colours per material. |
+| 32×32 | Facial suggestion, distinct armour pieces, believable weapon. |
+| 48×48+ | Real detail; now the risk is noise, not scarcity. |
+
+## Constraints beat cleverness
+
+Pick and write down, before drawing: canvas size, palette, light direction,
+outline style, and whether the sprite is side-on, top-down or 3⁄4. Every later
+decision either follows from those or is a mistake.
+
+## What makes generated pixel art look generated
+
+In rough order of how quickly a person spots it:
+
+1. **Too many colours.** Ninety near-identical browns instead of a four-step
+   ramp. Fix: a palette, and `paletteLock` left on.
+2. **Flat luminance shading.** Shadow = the same hue, darker. Real shading
+   shifts hue (see `rules://02-shading-and-light`).
+3. **Anti-aliased or semi-transparent pixels.** Usually from a resize or a soft
+   brush. At 1× they read as blur, not smoothness.
+4. **Noise.** Isolated pixels with no neighbour, "detail" that is just dirt.
+5. **Mushy silhouette.** The shape does not read as anything when filled black.
+6. **Mechanical timing.** Every animation frame the same duration.
+
+`validate` checks 1, 3, 4 and 6 mechanically. The rest you have to look at.
+
+## Never silently change what the user did not ask about
+
+Do not resize their canvas, re-index their colour mode, flatten their layers or
+overwrite their file unless they asked. When a task seems to require one of
+those, say so and ask.

package/rules/01-palette-and-color.md

@@ -0,0 +1,51 @@
+# Palette and colour
+
+## Decide the palette first
+
+A palette chosen after the art is finished means repainting the art. Choose
+before the first pixel, and state it back to the user so they can object early.
+
+Reasonable defaults when the user has no preference:
+
+- "retro" / "8-bit" / no detail given → **PICO-8** (16 colours, forgiving, reads well)
+- "Game Boy" / "monochrome" → **gameboy** (4 values; pure form study)
+- "NES-like" → a hand-built 12–16 colour palette, 3–4 hues × 4 values
+- A specific game named → sample it: `reference` op `sample_palette`
+
+Load one with `palette` op `preset`, or a file the user has with op `load`.
+
+## Size
+
+Most sprites want **8–32 colours total**. Per material, 3–5 steps is plenty:
+shadow, base, light, and optionally a deep shadow and a specular.
+
+More colours is not more quality. It is more decisions, more inconsistency, and
+a sprite that cannot be recoloured for a palette swap later.
+
+## Ramps, not gradients
+
+A **ramp** is an ordered run of colours for one material. Build them with
+`palette` op `ramp`, which hue-shifts as it goes (see
+`rules://02-shading-and-light`). Reuse ramps across materials wherever you can —
+sharing the darkest step between skin and leather ties a sprite together and
+costs nothing.
+
+## Palette lock
+
+`draw` and `recolor` snap every colour to the nearest palette entry by
+perceptual (CIELAB) distance, by default. Leave it on.
+
+When the report says a colour moved a long way (ΔE > 12), that is the tool
+telling you the palette has no colour for what you asked. Do not turn the lock
+off to force it through — either pick a different colour or tell the user the
+palette needs a new entry and let them decide.
+
+## Contrast is what makes a sprite readable
+
+Value contrast, not hue contrast, carries readability. A sprite that is all
+mid-tones disappears against a background. Check by squinting — or run
+`recolor` op `desaturate` on a copy and see whether the shapes survive.
+
+Keep the darkest and lightest steps of a ramp genuinely far apart. Two colours
+with ΔE under 3 are the same colour to a viewer; `palette` op `analyze` flags
+those as near-duplicates.

package/rules/02-shading-and-light.md

@@ -0,0 +1,56 @@
+# Shading and light
+
+## Pick a light direction and never move it
+
+One light source, stated up front — usually upper-left or upper-right. Every
+surface in the sprite is lit from that direction, in every frame of every
+animation. A sprite whose light drifts between frames looks like it is made of
+different materials each frame.
+
+## Hue-shift, always
+
+The difference between pixel art and a brightness slider:
+
+- **Shadows** rotate toward the ambient — in practice, **toward blue/purple** —
+  and lose a little saturation.
+- **Highlights** rotate **toward yellow/orange** and gain a little saturation.
+
+A red `#c04030` shades to something like `#8a2f45` (cooler), not `#802b20`
+(the same hue, darker). The second one is the tell.
+
+`recolor` op `shade` applies this rule; `palette` op `ramp` builds ramps that
+already obey it. Use them instead of picking darker hex values by hand.
+
+## Order of work
+
+1. **Block in** flat base colours per material. No shading at all yet.
+2. **Check the silhouette** — see `rules://03-silhouette-and-form`.
+3. **One shadow step**, on the side away from the light. Stop and look.
+4. **One light step**, on the side facing it.
+5. Only then consider a second shadow, a specular, or reflected light.
+
+Most sprites are finished at step 4. Detail added before the form is right just
+makes the wrongness harder to see.
+
+## Dithering
+
+Dithering buys you an intermediate value you do not have colours for, and it
+adds texture. It is not free: at small sizes it reads as noise.
+
+- Use it for large flat areas, skies, gradients on 32×32 and up.
+- Avoid it on a 16×16 character; you do not have the pixels.
+- Prefer ordered patterns (`bayer4`) over `noise`. Random dithering looks like
+  dirt at low resolutions.
+- Keep the two dithered colours adjacent in a ramp. Dithering between distant
+  colours produces visible speckle.
+
+`draw` op `dither` handles the pattern; you choose the two colours and the ratio.
+
+## Anti-aliasing
+
+Manual AA — placing one intermediate colour at a hard diagonal — is a legitimate
+technique on larger sprites. It is **not** the same as alpha blending.
+
+Never leave semi-transparent pixels in pixel art. They come from soft brushes and
+non-integer resizes, and they make a sprite look blurry and impossible to palette
+swap. `validate` flags them.

package/rules/03-silhouette-and-form.md

@@ -0,0 +1,60 @@
+# Silhouette and form
+
+## The silhouette test
+
+Fill the sprite with a single flat colour. Can you still tell what it is? If not,
+no amount of shading will save it.
+
+This is the highest-leverage check in pixel art and it takes one call:
+`look` op `preview` after a `recolor` op `replace` on a copy, or just squint at
+the preview. Do it before you shade, not after.
+
+Silhouettes fail because of:
+
+- **Symmetry.** A perfectly symmetrical pose reads as a statue. Break it: one
+  arm forward, weapon on one side, head turned.
+- **Tangents.** An arm whose outline touches the torso outline fuses into one
+  blob. Leave a gap, or overlap clearly.
+- **Uniform limb width.** Everything the same thickness reads as a stick figure.
+
+## Proportions
+
+Game characters are usually stylised shorter than life. Common ratios, measured
+in head-heights:
+
+| Style | Heads tall | Reads as |
+|-------|-----------|----------|
+| 2 | Chibi / cute | Toy, mascot |
+| 3–4 | Classic JRPG / action | The default; safe |
+| 5–6 | Realistic-ish | Needs 48px+ to work |
+
+At 16×16 you are at 2–3 heads whether you planned it or not. Plan it.
+
+## The 3⁄4 view
+
+Most top-down and isometric games want 3⁄4: the character faces the camera but
+is seen slightly from above. In practice:
+
+- The head shows the face **and** a little of the top of the skull.
+- The shoulders are wider than a pure front view suggests.
+- Feet are visible as separate shapes, not a single base.
+- The far-side limb is partly hidden by the torso — that is what sells depth.
+
+## Direction sets
+
+A 4-direction set is down / up / left / right; 8 adds the diagonals. Rules:
+
+- **Left and right are mirrors** — draw one, use `transform` op `flip` on a
+  copied layer. Mirror asymmetric details (a scar, a shoulder pad) back by hand
+  if the character has any, or accept the flip and say so.
+- **Up** shows the back of the head and no face. This is the frame agents most
+  often get wrong by drawing a face on the back of a head.
+- Keep the **same pixel height and centre of mass** across all directions, or
+  the character appears to bob when the player turns.
+
+## Volume consistency
+
+Across an animation, a limb must stay the same number of pixels thick unless it
+is foreshortened on purpose. Volume drift — an arm that quietly gains two pixels
+by frame four — is very visible in motion and invisible frame by frame. Review
+with `look` op `filmstrip`, which is exactly what it is for.

package/rules/04-outlines-and-edges.md

@@ -0,0 +1,46 @@
+# Outlines and edges
+
+## Choose one outline style and hold it
+
+| Style | What it is | Use when |
+|-------|-----------|----------|
+| **None** | Shapes defined by colour alone | Backgrounds, high-colour art |
+| **Full black** | Every edge outlined in one dark colour | Icons, high-contrast game art |
+| **Selective** | Outline only where the shape meets the background | The usual choice for characters |
+| **Coloured** | Outline is a dark version of the fill it borders | Soft, painterly look |
+
+Selective outlining — outline on the outside, none between internal shapes — is
+what most sprites want. It keeps the silhouette crisp without turning the
+interior into a colouring book.
+
+Pure black outlines on everything read as harsh and flatten the form. A very dark
+version of the sprite's own colours nearly always looks better.
+
+## Clean lines
+
+A pixel line is clean when its segment lengths are consistent: 2,2,2,2 or
+4,4,4,4 — not 3,2,4,1. Inconsistent runs produce the jagged look people call
+"jaggies", and they are the difference between a hand-drawn-looking curve and a
+computed one.
+
+- A 45° line is one pixel per step.
+- A shallow line is a run of N, then N, then N. Keep N the same.
+- Never place a single pixel that breaks an otherwise even run.
+
+`draw` op `line` uses Bresenham, which is even by construction. Hand-placed
+`pixels` ops are where runs go wrong — check them with `look` op `ascii`.
+
+## Doubles and corners
+
+Avoid **doubled pixels** on a diagonal: two pixels side by side inside a line
+that is otherwise single-width. They read as a lump.
+
+At a corner, one pixel is a sharp corner and two is a rounded one. Pick
+deliberately and be consistent across the sprite.
+
+## Banding
+
+Banding is when two ramp steps run parallel for a long stretch, creating a
+visible stripe that reads as a contour line rather than a curved surface. Break
+it by letting the boundary between steps wander, or by dithering a short section
+of it.

package/rules/05-animation.md

@@ -0,0 +1,62 @@
+# Animation
+
+## Timing is the performance
+
+Frame durations carry more of the life in a cycle than the drawings do. Uniform
+timing reads mechanical no matter how good the poses are.
+
+Rules of thumb, at 60fps-equivalent thinking but expressed in milliseconds:
+
+| Cycle | Frames | Typical timing |
+|-------|--------|----------------|
+| Idle (breathing) | 2–4 | 200–400ms each, slow |
+| Walk | 4–8 | 100–150ms; hold contact poses longer |
+| Run | 6–8 | 60–100ms |
+| Attack | 3–6 | Fast on the strike (40–60ms), long on the hold (150–250ms) |
+
+Set a whole cycle at once: `frame` op `set_duration` with a `durations` array.
+
+## Key poses first
+
+Draw the extremes, then the in-betweens. Never animate by nudging pixels frame
+to frame — drift accumulates and by frame six the character is a different size.
+
+A walk cycle's canonical poses:
+
+1. **Contact** — front foot lands, back foot pushing off. Widest stance.
+2. **Down** — weight over the front leg, body at its **lowest**.
+3. **Pass** — legs together, body at its **highest**. This is the frame people
+   forget, and its absence is why a walk looks like sliding.
+4. **Up** — pushing off, rising.
+
+Then mirror all four for the other leg: 8 frames. A 4-frame walk uses contact
+and pass for each leg.
+
+## The principles that survive at 16 pixels
+
+- **Anticipation** — a small movement opposite to the action before it. One
+  frame of crouch before a jump. Skipping it makes everything feel weightless.
+- **Follow-through** — hair, cloak and weapon keep moving after the body stops.
+- **Squash and stretch** — sparingly, and only where a material would deform.
+- **Arcs** — a hand travels along a curve, never a straight line.
+- **Overlap** — parts do not all start and stop together.
+
+Easing does not exist frame-by-frame; you get it from **spacing**. Poses close
+together = slow; far apart = fast. That is the whole trick.
+
+## Working method
+
+1. `rig` the character onto separate layers first (see `rules://06-layers-and-rigging`).
+2. Block in the key poses on their own frames. Look at them as a filmstrip.
+3. Add in-betweens only once the keys read.
+4. Set timing.
+5. Tag the cycle. Untagged frames are unusable by a game engine.
+6. Review with `look` op `filmstrip` — a vision model reads only the first
+   frame of a GIF, so a filmstrip is the only way to actually see the motion.
+
+## Cross-frame checks
+
+- Does the character stay the same height? (Except deliberate squash.)
+- Do limbs keep the same thickness?
+- Does the light stay in the same place?
+- Does the cycle loop — is frame N a plausible predecessor of frame 1?

package/rules/06-layers-and-rigging.md

@@ -0,0 +1,52 @@
+# Layers and rigging
+
+## Split before you animate, not after
+
+Pixels baked into one layer cannot be animated without redrawing them. Separating
+a finished sprite into limbs later is more work than building it separated. If
+the sprite will ever move, rig it first.
+
+## The standard character rig
+
+Bottom to top in the layer stack, so nearer parts draw over farther ones:
+
+```
+  arm-near          ← the arm on the camera side
+  leg-near
+  head
+  torso
+  arm-far           ← partly hidden by the torso; this is what sells depth
+  leg-far
+  shadow            ← ground contact, if the style has one
+```
+
+Add `weapon`, `cape`, `hair-back` and `hair-front` as the design needs. Keep the
+names stable — every later tool call refers to them by name.
+
+Build the whole rig in one `layer` call with a `batch` array; that is one undo
+step for the user and one round trip for you.
+
+## Groups
+
+Group related layers (`arms`, `legs`) once the count passes about eight. Groups
+hold no pixels themselves — target their children when drawing.
+
+## Cels
+
+A **cel** is one layer's image on one frame. Cels are only as big as their
+content, which is why moving a limb between frames is `cel` op `move` (cheap,
+lossless) rather than redrawing it.
+
+**Linked cels** share one image across several frames: edit once, every linked
+frame updates. Use them for parts that genuinely do not move in a cycle — a
+static torso under moving arms. Do not link something you will later want to
+differ; unlinking after the fact loses the shared history.
+
+## Non-destructive habits
+
+- Keep a `reference` layer locked and semi-transparent while tracing; delete it
+  before export.
+- Keep sketch/blockout on its own layer until the clean pass is done.
+- Never merge layers to "simplify" unless the user asked. The layer split is the
+  sprite's editability.
+- Hide layers rather than deleting them when trying an alternative.