@pebbly/aseprite-ai-artist 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is
+[semver](https://semver.org/).
+
+## [0.1.0] — 2026-09-08
+
+First release. Includes every fix from the pre-release audit below.
+
+### Fixed — 2026-09-08 multi-expert audit
+
+Six reviewers plus two live Codex CLI runs; every item below was reproduced
+before it was fixed and has a regression test that fails without the fix.
+
+- **Closed polylines lost their closing edge.** The outline loop stopped one
+  short of the wrap the fill loop already did, so a "closed" triangle shipped
+  with one side missing and the call reported success.
+- **Thick lines were silently clipped.** The bounding box ignored `thickness`,
+  so the cel was grown to the endpoints only and the rest of the brush was
+  dropped — a 7×7 stamp landing one pixel, reported as success.
+- **Fuzzy tile packing merged unrelated tiles on indexed sprites.** The distance
+  function read RGB channels out of palette indices. It now refuses non-RGB
+  sprites instead of guessing.
+- **`transform` op `rotate` with `angle: 0` reported a full-canvas change** for
+  an operation that touched nothing, breaking idempotency checks.
+- **`validate` never ran its `outline` or `banding` checks.** Both were in the
+  schema and in the handler's own default set, and no branch read either — the
+  tool answered "Clean." without running them. Both are now implemented.
+- **`cel` op `list` always reported `linked: false`**, and `frame` op
+  `duplicate` with `linkCels` never actually linked (it called a command that
+  does not exist in Aseprite 1.3).
+- **`draw` op `gradient` ignored `dither`**, and `diagonal` and `radial`
+  silently rendered as `vertical`. All four directions and the dither flag now
+  work.
+- **`transform`'s `scope` parameter did nothing.** Removed rather than
+  half-implemented; transforms act on one cel, and the docs now say so.
+- **`tag`'s `repeat` was ignored.** The schema said `repeat` on input and
+  output while Aseprite's property is `repeats`, so loop counts were silently
+  dropped. Renamed to `repeats` on both sides.
+- **`sprite_manage` op `new` returned an identifier that could not be used.** It
+  answered `"untitled"` while the sprite was called `"Sprite"`, so feeding a
+  tool's own output into the next call failed. Every result now carries a stable
+  `id`, and two unsaved documents are no longer ambiguous.
+- **Previews were capped far below a readable size.** The upscale factor was
+  capped at 16, rendering a 16px sprite at 256px — the case where upscaling
+  matters most. The bound is now on output size (~2048px), so small sprites
+  reach the documented ~1024px.
+- **`selectionOnly` silently widened to the whole cel** when nothing was
+  selected. It now refuses.
+- **Text grids collided past 71 colours**, quietly misreporting which colour was
+  where in the tool used to verify edits. It now refuses.
+- **Config writes were not atomic.** A partial write to `~/.claude.json` (100KB+
+  of Claude Code's own state) would have broken the user's whole setup. Writes
+  go through a temp file and a rename.
+- **A dropped bridge left in-flight calls waiting out their 20s timeout**, which
+  reads to an agent as "slow" rather than "disconnected". They now fail
+  immediately, and a bridge that dies after being spawned can be respawned.
+- **Non-`EADDRINUSE` bind failures were reported as "another bridge owns this
+  port"**, sending users after a process that does not exist.
+- **`run_lua` could leave Lua's global `print` hijacked** for the rest of the
+  Aseprite session if the transaction threw.
+- **The Claude Code plugin could not start on Windows.** Its MCP `command`
+  pointed at a bash script, and Windows does not interpret `#!`. The launcher is
+  now Node.
+- **`package.json` claimed the 2026-07-28 spec**, contradicting ADR-0004's
+  decision to target 2025-11-25. `engines.node` also promised 20.10 while the
+  test script needs 22.6.
+
+### Fixed — audit round two
+
+The six reviewers' full reports arrived after the first round of fixes and
+carried a further fourteen items, all closed here.
+
+- **`snapToPalette` promised a transparency guard it did not have.** A fully
+  transparent input now snaps to itself instead of to the nearest opaque colour,
+  which would have painted over deliberate holes.
+- **`refused` and `too_large` error codes were declared and never raised**, so
+  every "you asked for something out of bounds" refusal arrived as a generic
+  `aseprite_error` and an agent could not tell it apart from an internal
+  failure. Both are now used at the real refusal sites.
+- **The bridge had no frame-size or client cap** on an unauthenticated socket —
+  `ws` defaults to 100 MiB per frame. Now 16 MiB and 64 clients.
+- **The Codex TOML editor matched its block header anywhere in the file**,
+  including inside a comment or a string. The match is now anchored to a line.
+- **`layer`'s `batch` was the least-typed path in the surface** while being the
+  documented way to build a rig: `z.record(z.unknown())` accepted an opacity of
+  `"hello"` and Lua assigned it. It is now the same typed object as the
+  single-op form.
+- **The Lua reconnect state machine had no per-socket identity check**, so an
+  event from a superseded socket could clobber the new connection's state. The
+  TypeScript side already guarded the mirror-image race.
+- **A rejected `close()`/`stop()` left a floating promise rejection** in the
+  CLI's shutdown paths.
+- **Four output schemas under-documented what Lua actually returns** —
+  `palette` op `load`'s `path`, `sprite_manage` op `list`'s colour mode and
+  counts, and the layer entries' `editable`/`isTilemap`/`cels`.
+- **Lua test cleanup was not exception-safe.** One failing assertion left the
+  active document pointing at a closed scratch sprite and cascaded into every
+  later check — the failure this project already hit once. All sixteen scratch
+  blocks now go through a helper that always closes and always restores.
+- **The cross-language CIELAB claim was not actually enforced.** ADR-0001 and
+  ARCHITECTURE.md both said the two ports are held to the same expectations;
+  only the TypeScript side had numeric fixtures. The Lua side now pins the same
+  white/black L\*, ΔE bounds, grey-snaps-to-grey case and hue-shift direction.
+- **`export` op `frames` had no coverage at any level.** Verified it does write
+  one file per frame (numbered from 0, now documented) and locked that in.
+- **The e2e test used the real default ports**, so running it on a machine with
+  a live Aseprite session could steal that session — the bridge accepts the last
+  plugin to connect. Ports are now overridable, the risk is documented, and the
+  test removes the files it writes.
+- **`SECURITY.md` overstated the `allowLua` gate.** It gates the tool surface
+  your agent sees, not the capability: the extension implements `lua.run`
+  whenever installed and the bridge has no authentication. Now stated plainly,
+  alongside the filesystem reach of every `path` argument.
+
+### Added
+
+- `SECURITY.md` — threat model, the localhost bridge's real exposure, what
+  `install` touches, and the `run_lua` gate.
+
+### Added — initial implementation
+
+- **MCP server** (`serve`) speaking protocol `2025-11-25`, with 18 tools grouped
+  by noun. Every tool declares an `outputSchema` and returns
+  `structuredContent`. See [ADR-0003](docs/adr/0003-compact-tool-surface.md) and
+  [ADR-0004](docs/adr/0004-protocol-version.md).
+- **Standalone WebSocket bridge** (`bridge`), singleton by port ownership,
+  outliving MCP server restarts and serving several agent windows at once. See
+  [ADR-0002](docs/adr/0002-standalone-bridge.md).
+- **Aseprite extension** (`extension/ai-artist.lua`) implementing 23 commands
+  against Aseprite 1.3's Lua API, with every mutation inside a transaction so
+  one Ctrl+Z undoes one agent action.
+- **`look`** — upscaled previews, exact one-glyph-per-pixel text grids,
+  animation filmstrips and pixel-level frame diffs.
+- **Palette discipline** — CIELAB ΔE snapping on by default in `draw` and
+  `recolor`, with a report of every colour moved and how far.
+- **Hue-shifted shading** (`recolor` op `shade`, `palette` op `ramp`): shadows
+  cool, highlights warm.
+- **`validate`** — a lint pass with located findings for palette sprawl, stray
+  pixels, semi-transparent pixels, untagged animation and uniform timing.
+- **Skills over MCP** — 11 `/pixel-*` workflows and an 8-chapter pixel-art
+  rulebook, served as `skill://` and `rules://` resources and as MCP prompts, so
+  Codex, Gemini CLI and Cursor get the same discipline as Claude Code.
+- **Cross-client installer** (`install`) for Claude Code, Codex, Gemini CLI,
+  Cursor, VS Code and Windsurf, with backups and `--dry-run`, plus an
+  `AGENTS.md` writer.
+- **`doctor`** — a diagnosis command that reports each link in the chain.
+- **Claude Code plugin** with four specialist subagents (pixel-critic,
+  palette-smith, rig-builder, animation-director) and two hooks.
+- **Tests** — TypeScript unit and integration tests for colour, rendering, the
+  bridge transport and the MCP surface; a headless Lua harness running the real
+  extension handlers inside `aseprite -b` against a real sprite.
+
+- **Tilesets** — `pack` turns a hand-painted mockup into a deduplicated tileset
+  plus a tilemap that reconstructs it pixel for pixel (with an optional
+  `tolerance` for merging near-identical cells), and `export` writes Tiled
+  (`.tsj` tileset plus a `.tmj` map that uses it), Godot 4 (`.tres`) or JSON,
+  each beside a packed PNG. `layout: "blob47"` adds a Tiled wangset whose 47
+  canonical masks are computed, not hardcoded.
+
+### Known limits
+
+- `blob47` export assumes the tileset is authored in canonical blob-mask order
+  and refuses an incomplete set rather than writing a wangset that would
+  autotile wrongly.
+- Godot export targets Godot 4 (`TileSetAtlasSource`); Godot 3 is not emitted.
+- Re-establishing a *dropped* Aseprite connection can wait until the Aseprite
+  window is focused once. A live connection keeps working unfocused.
+- `look` op `ascii` refuses above 64×64; pass a region.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 with-pebbly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# Aseprite AI Artist
+
+Let a coding agent draw pixel art in your **open Aseprite window** — not in a
+copy, not on disk, in the document you are looking at.
+
+One MCP server, one Aseprite extension, and a pixel-art rulebook the agent
+actually has to follow. Works with **Claude Code, Codex CLI, Gemini CLI, Cursor,
+VS Code and Windsurf** from the same one-line config.
+
+```bash
+npx @pebbly/aseprite-ai-artist install --all --agents
+npx @pebbly/aseprite-ai-artist install-extension
+# restart Aseprite, restart your agent
+```
+
+> **Requires Aseprite 1.3+** and Node 22.6+.
+
+---
+
+## What it does
+
+> *"Draw me a 32×32 knight in the PICO-8 palette, then a 4-frame idle."*
+
+The agent inspects the document, picks a palette, blocks in a silhouette,
+**looks at what it drew**, shades with proper hue shifting, rigs the character
+onto layers, animates, tags the cycle, validates, and tells you what it
+compromised on. In your window, undoable, one Ctrl+Z per edit.
+
+## What makes it different
+
+**It works everywhere, not just in Claude Code.** Most Aseprite MCP projects put
+their craft knowledge in a Claude Code plugin. Codex, Gemini and Cursor then get
+raw tools and none of the discipline — which is most of what separates a sprite
+from coloured noise. Here the rules and workflows are served over MCP as
+`rules://` and `skill://` resources *and* as MCP prompts, so every client gets
+them from one source of truth.
+
+**Eighteen tools, not ninety.** Every tool schema sits in the model's context on
+every turn, whether or not you are drawing. Grouping by noun with an `op` enum,
+plus batch arrays, covers the same ground at roughly a sixth of the cost — and
+makes batching the default, so one `draw` call is one undo step for you.
+
+**One config line on every OS.** No compiled binary, no per-platform path, no
+native dependencies. `npx` and go.
+
+**It has to look at its own work.** `look` gives the agent an upscaled preview,
+an exact one-glyph-per-pixel text grid, a filmstrip of every animation frame,
+and a pixel-level diff between frames. `validate` then checks the sprite
+mechanically before anything gets called finished.
+
+**It cannot quietly wreck your file.** When Aseprite is not attached, every tool
+refuses immediately with `doNotFallBackToDisk` rather than timing out — because
+an agent that "recovers" by editing the `.aseprite` file makes changes you never
+see and your next save overwrites.
+
+There is [a whole page](docs/RESEARCH.md) on the other projects in this space,
+what was taken from them, and where they are still better.
+
+## Install
+
+See **[docs/INSTALL.md](docs/INSTALL.md)** for per-client detail and
+troubleshooting.
+
+### Claude Code
+
+The plugin brings the `/pixel-*` skills, the specialist subagents and the hooks,
+not just the tools:
+
+```
+/plugin marketplace add with-pebbly/aseprite-ai-artist
+/plugin install aseprite-ai-artist
+```
+
+### Everything else
+
+```bash
+npx @pebbly/aseprite-ai-artist install codex      # ~/.codex/config.toml
+npx @pebbly/aseprite-ai-artist install gemini     # ~/.gemini/settings.json
+npx @pebbly/aseprite-ai-artist install cursor     # ~/.cursor/mcp.json
+npx @pebbly/aseprite-ai-artist install --all      # all of the above
+```
+
+Existing config is backed up first. `--dry-run` shows the change without making
+it. `--project` writes into the repository instead of your home directory.
+
+### Check it
+
+```bash
+npx @pebbly/aseprite-ai-artist doctor
+```
+
+## The tools
+
+Eighteen, grouped by noun. Full reference in **[docs/TOOLS.md](docs/TOOLS.md)**.
+
+| | |
+|---|---|
+| **Session** | `preflight` · `sprite_info` · `sprite_manage` |
+| **Looking** | `look` · `read_pixels` |
+| **Drawing** | `draw` · `select` · `transform` · `recolor` |
+| **Structure** | `layer` · `frame` · `tag` · `cel` |
+| **Colour & quality** | `palette` · `validate` |
+| **Assets** | `reference` · `export` · `tileset` |
+
+Plus `run_lua` as an escape hatch, off by default.
+
+## The skills
+
+Workflows the agent follows, served to every client:
+
+`pixel-brief` · `pixel-new` · `pixel-palette` · `pixel-draw` · `pixel-shade` ·
+`pixel-rig` · `pixel-animate` · `pixel-tileset` · `pixel-review` · `pixel-fix` ·
+`pixel-export`
+
+And in Claude Code, four specialist subagents: **pixel-critic** (visual QA),
+**palette-smith** (colour), **rig-builder** (layer rigs), **animation-director**
+(cycle planning).
+
+## The rules
+
+The craft is encoded in [`rules/`](rules/) and served as `rules://` resources —
+palette discipline, hue-shifted shading, silhouette and proportion, outlines and
+edges, animation timing, layer rigging, and a review checklist. Skills reference
+rules rather than restating them, so a rule has exactly one place to be wrong.
+
+The mechanical parts are enforced by the tools themselves: `draw` and `recolor`
+snap to the palette by perceptual distance and report every colour they moved,
+so an agent that never reads a word of the rulebook still cannot casually widen
+your palette.
+
+## How it works
+
+```
+your agent  ──stdio/MCP──▶  server  ──ws:9932──▶  bridge  ──ws:9931──▶  Aseprite
+```
+
+Aseprite's Lua WebSocket is a client only, so the bridge holds the listening
+socket. It runs as its own singleton process so that restarting the MCP server —
+which agent hosts do freely — does not drop your Aseprite connection, and so a
+second agent window can attach without stealing the first one's replies.
+
+Details in **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** and the
+[ADRs](docs/adr/).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test                                        # TypeScript: colour, render, bridge, MCP surface
+npm run test:extension                          # Lua handlers, headless, against a real sprite
+```
+
+The Lua tests run the real command handlers inside `aseprite -b` against a real
+sprite — the only way to prove that side works without a human clicking.
+
+## Security
+
+The bridge binds `127.0.0.1` only, on both ports. There is no remote surface and
+no authentication because there is nothing remote to authenticate. `run_lua` is
+arbitrary code execution inside the app holding your unsaved work, and is off
+unless you turn it on.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).
+
+Aseprite is a trademark of Igara Studio S.A. This project is not affiliated with
+or endorsed by them.

package/agents/animation-director.md

@@ -0,0 +1,65 @@
+---
+name: animation-director
+description: Animation planning specialist. Use when planning idle, walk, run, attack or other cycles — it designs key poses, breakdowns, millisecond timing and tags before any frame is drawn, so the motion reads and volume stays consistent. Plans on its own; executes frames on request.
+model: sonnet
+effort: medium
+---
+
+You plan motion before anyone draws it.
+
+Animating by nudging pixels frame to frame accumulates drift; by frame six the
+character is a different size. Keys first, always.
+
+## Procedure
+
+1. `preflight`, `sprite_info`. Check the sprite is rigged — if limbs are baked
+   into one layer, say so and hand off to `rig-builder` first.
+2. Read `rules://05-animation`.
+3. Plan the cycle in writing. Get agreement. Then build.
+4. Review with `look` op `filmstrip` — a vision model reads only the first frame
+   of a GIF, so this is the only way to actually see motion.
+
+## What a plan contains
+
+- **Frame count**, and why that number.
+- **Key poses** — what each one shows, in words specific enough to draw from.
+- **Breakdowns** — which in-betweens are needed and which are not.
+- **Timing in milliseconds per frame**, with contacts held longer than passes.
+- **Tag name and direction.**
+
+## Cycle templates
+
+**Walk (8)**: contact, down, pass, up, then mirrored. Body lowest at down,
+highest at pass. The pass frame is the one people forget, and its absence is why
+a walk looks like sliding.
+
+**Idle (2–4)**: a breath. Chest rises a pixel; shoulders follow one frame later.
+Slow — 200–400ms.
+
+**Attack (4–6)**: anticipation (wind back), strike (fast, 40–60ms), hold
+(150–250ms), recover. Without anticipation it reads weightless.
+
+**Run (6–8)**: like a walk but with a airborne frame where neither foot is down,
+and more forward lean.
+
+## Output
+
+```
+WALK — 8 frames, tag "walk", forward.
+
+ 1 contact L    150ms   widest stance, front heel down, arms opposed
+ 2 down         100ms   body 1px lower, front knee bent
+ 3 pass          80ms   body 1px HIGHER than contact, legs together
+ 4 up           100ms   pushing off, rear heel lifting
+ 5-8 mirrored
+
+Notes: body height must vary by exactly 2px across the cycle (contact 0,
+down -1, pass +1). Arms swing opposite the legs. Cape follows the torso one
+frame late.
+
+Risks: at 32px the knee bend in frame 2 is 2 pixels; if it reads as noise,
+drop it and carry the weight in the body height alone.
+```
+
+Say what you are unsure about. A plan that hides its risks produces eight frames
+of work that has to be redone.

package/agents/palette-smith.md

@@ -0,0 +1,57 @@
+---
+name: palette-smith
+description: Colour and palette specialist. Use when the user needs a cohesive palette, hue-shifted ramps, a specific retro preset, a palette sampled from reference art, or a muddy palette cleaned up. Proposes colours and explains the choice; applies them only when asked.
+model: sonnet
+effort: medium
+---
+
+You choose colours for pixel art, and you can say why.
+
+## Procedure
+
+1. `preflight`, then `sprite_info` — the existing palette and colour mode are
+   usually half the answer.
+2. Read `rules://01-palette-and-color` and `rules://02-shading-and-light`.
+3. `palette` op `analyze` if a palette already exists. Report before proposing.
+4. Propose, with reasoning. Apply only when the user says yes, or when they
+   clearly asked you to just do it.
+
+## How you choose
+
+- **The user named a game or palette** → use it. `palette op="preset"`,
+  `op="load"`, or `reference op="sample_palette"` on a screenshot.
+- **They described an era** → PICO-8 for "8-bit", gameboy for "monochrome",
+  a hand-built 12–16 for "NES-like".
+- **The sprite joins a project** → match an existing asset exactly. Consistency
+  beats a nicer palette.
+- **Nothing said** → PICO-8.
+
+## How you build ramps
+
+`palette op="ramp"` — hue-shifted by construction. 3–5 steps per material.
+Reuse the darkest step across materials; shared darks tie a sprite together and
+cost no slots.
+
+## How you clean up a sprawled palette
+
+`palette op="analyze"` → merge near-duplicates (ΔE < 3 is the same colour to a
+viewer) → `recolor op="snap"` → look at the result. The risk is merging two
+colours that were doing different jobs, so check for form that has gone flat.
+
+## Output
+
+Show the palette as hex with names for what each is for, and say what you would
+not do:
+
+```
+PICO-8, 16 colours. Knight uses 7 of them:
+
+  plate       #5f574f → #c2c3c7 → #fff1e8   (3-step, cool)
+  leather     #ab5236 → #ffa300               (2-step, warm)
+  plume       #ff004d                          (accent, 1 colour, no ramp)
+  outline     #1d2b53                          (shared dark, not black)
+
+Not proposing a skin ramp: the visor is closed, so no skin is visible. If you
+want the visor open, that needs 2 more slots and PICO-8 has no good midtone
+for skin — I'd suggest a custom palette instead.
+```

package/agents/pixel-critic.md

@@ -0,0 +1,69 @@
+---
+name: pixel-critic
+description: Visual QA for pixel art. Use PROACTIVELY before telling a user a sprite is finished, and whenever they ask "is this any good", "why does this look off" or "review this". Inspects the live sprite and returns a scored, located critique against the project rulebook. Read-only — it never edits the sprite.
+model: sonnet
+effort: medium
+tools:
+  - Read
+  - Glob
+  - Grep
+disallowedTools:
+  - Write
+  - Edit
+---
+
+You are a pixel-art critic. You look at sprites and say precisely what is wrong
+with them, with coordinates.
+
+You do not edit. Someone else fixes what you find; conflating the two produces
+critiques written to be easy to fix rather than true.
+
+## Procedure
+
+1. `preflight`. Stop if not ready.
+2. `sprite_info` — size, palette, layers, frames, tags.
+3. `validate` — the mechanical findings.
+4. `look` op `preview` — the overall read.
+5. `look` op `ascii` on anything that felt wrong but you could not name.
+6. `look` op `filmstrip` if there is more than one frame.
+7. Read the rules you are judging against: `rules://07-review-checklist` and
+   whichever specific rule a finding touches.
+
+## What you are looking for
+
+In descending order of how much it costs the user:
+
+1. **Silhouette does not read.** Nothing else matters if this fails.
+2. **Value contrast too low.** Would it survive desaturation?
+3. **Flat shading.** Shadows that are the same hue, darker.
+4. **Palette sprawl.** Near-duplicate colours; off-palette pixels.
+5. **Semi-transparent pixels.** From soft brushes or non-integer resizes.
+6. **Strays and noise.** Isolated pixels, detail that is just dirt.
+7. **Inconsistent lines.** Uneven runs, doubled pixels, jaggies.
+8. **Inconsistent light.** Direction that moves across the sprite or frames.
+9. **Animation: volume drift, height drift, uniform timing, no anticipation.**
+
+## Output
+
+A score out of 10, then findings, then the single highest-value fix.
+
+```
+7/10 — reads well at 1×, held back by flat shading.
+
+BLOCKING
+· Shadow ramp is pure luminance: #c04030 → #802b20 has the same hue.
+  Shadows should cool. rules://02-shading-and-light. (torso, whole cel)
+
+WORTH FIXING
+· 3 stray pixels with no neighbour at (4,19), (5,19), (17,3) — reads as dirt.
+· Palette has #7e2553 and #7d2452 (ΔE 1.1). One of them is doing no work.
+
+NOTE
+· The far arm fuses with the torso outline at (9,14)-(9,16). A one-pixel gap
+  would separate them.
+
+FIRST FIX: rebuild the torso ramp with `palette op="ramp"` and re-snap.
+```
+
+Never say "looks good". If you genuinely find nothing, say what you checked and
+what the sprite does well — that is information; "looks good" is not.

package/agents/rig-builder.md

@@ -0,0 +1,46 @@
+---
+name: rig-builder
+description: Sprite rigging specialist. Use when starting a character that will be animated, or when limbs are baked into one layer and need splitting into animatable parts. Plans the layer rig and builds it on request.
+model: sonnet
+effort: medium
+---
+
+You split characters into animatable parts.
+
+Pixels baked into one layer cannot be animated without redrawing them. Your job
+is to make sure that never becomes the user's problem.
+
+## Procedure
+
+1. `preflight`, `sprite_info`, `look` op `preview`.
+2. Read `rules://06-layers-and-rigging`.
+3. If the art is baked, `look` op `ascii` to find exact part boundaries. Guessing
+   coordinates here clips limbs.
+4. Propose the rig. Build on confirmation.
+
+## The standard rig
+
+Bottom to top: `shadow`, `leg-far`, `arm-far`, `torso`, `head`, `leg-near`,
+`arm-near`, plus `weapon` / `cape` / `hair-front` / `hair-back` as needed.
+
+Build it in one `layer` call with a `batch` array — one undo step for the user.
+
+## Splitting baked art
+
+`draw` op `blit` per part, copying from the source layer to its new home.
+
+Two rules that matter:
+
+- **Overlap generously.** A limb needs a pixel or two under the torso or a gap
+  opens the moment it rotates. Stacking order hides the excess.
+- **Hide the original, do not delete it.** If a boundary was wrong you want it
+  still there. Rename it `flat-original` and hide it.
+
+Verify by hiding the original and running `look` op `preview`: the sprite should
+look unchanged. A limb that lost pixels means a wrong boundary.
+
+## Output
+
+The layer stack you propose, bottom to top, with what goes on each and why any
+part is grouped. Flag anything the design needs that the standard rig lacks —
+a two-handed weapon that crosses the body needs its own thinking about stacking.

package/bin/aseprite-ai-artist

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Superseded by aseprite-ai-artist.mjs, which the plugin manifest now names as
+# its MCP command: Windows does not interpret a `#!` line, so a bash shim there
+# fails to start the server at all. Kept as a thin delegate so an existing POSIX
+# invocation of this path keeps working, with no duplicated build logic.
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/aseprite-ai-artist.mjs" "$@"

package/bin/aseprite-ai-artist.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Launcher for the Claude Code plugin and for anyone running from a checkout.
+ *
+ * This is Node rather than a shell script on purpose: the plugin manifest names
+ * it as the MCP `command`, and Windows does not interpret a `#!` line — a bash
+ * shim there simply fails to start, silently, on the one client this project
+ * treats as first-class. Node is guaranteed present, because the thing being
+ * launched is a Node package.
+ *
+ * A plugin installed from git arrives as source with no build step, so this
+ * builds once on first use and then runs the compiled CLI. Published npm users
+ * never touch this file — they run `npx @pebbly/aseprite-ai-artist`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cli = path.join(root, "dist", "cli.js");
+
+// stderr only: stdout is the MCP stdio channel and any stray byte corrupts it.
+const log = (msg) => process.stderr.write(`[aseprite-ai-artist] ${msg}\n`);
+
+if (!existsSync(cli)) {
+  log("first run — building…");
+  // `shell: true` so npm resolves as npm.cmd on Windows.
+  const steps = [
+    ["install", "--silent", "--no-audit", "--no-fund"],
+    ["run", "--silent", "build"],
+  ];
+  for (const args of steps) {
+    const result = spawnSync("npm", args, { cwd: root, stdio: ["ignore", 2, 2], shell: true });
+    if (result.status !== 0) {
+      log(`build step \`npm ${args.join(" ")}\` failed with status ${result.status}.`);
+      process.exit(result.status ?? 1);
+    }
+  }
+}
+
+const child = spawnSync(process.execPath, [cli, ...process.argv.slice(2)], { stdio: "inherit" });
+process.exit(child.status ?? 1);