Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs: entry README, architecture diagrams, tables of contents, uniform doc headers, 2.0.0 release notes
Soohong Kim438b7cf60aea
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 70737de..acd1f65 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,14 +2,46 @@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.-## Unreleased (v2.0.0) - Video to Sprite--- Added the `sprite_gen/video` domain: `sprite-gen video-canvas` (state canvas — tall for jumps, wide for attacks, square otherwise; the still's corner key fills the padding), `sprite-gen video-frames` (ffmpeg extraction + cutout keying with an edge-contact gate), `sprite-gen video-loop` (global-period cycle detection, strip with `body_h` metadata, 1-bit-alpha GIF, `img2webp -exact` WebP, seam and periodicity gates, output re-verification) and `sprite-gen video-set` (directions × states with staggered starts and a bounded HTTP 429 retry, per-item reports and a table).-- Declared `ffmpeg` and `img2webp` as required binaries for the video pipeline; `docs/video-pipeline.md` records the contract and the rules behind it. A new domain plus new required binaries is why this is a major version.-- `video-loop --cycle auto|periodic|one-shot`: action states (`jump`, `attack`, unknown) whose clip performs the action once now get a recorded one-shot cut (rest → excursion → rest, medoid rest pose, 3-MAD excursion) instead of a hard failure; the report keeps the rejected periodic attempt and `table.md` gains a `kind` column. `walk`, `run`, `idle` still fail loud without a period.-- Walk detection window floor 10 % → 6 % of the clip so a legless body's fast bounce resolves; the 15 % depth rule keeps rejecting the one-step half period (verified on a biped and a quadruped).-- `video-set` motion templates no longer assume a biped ("this body type" instead of knees/arms).-- Slimmed `SKILL.md` into a route-first hub (still / atlas / video-to-loop / utilities) under the 24 KB skill budget; the interpreter rationale, the rename gate and the breathing contract moved verbatim to `docs/interpreter.md`, `docs/rename-gate.md` and `docs/breathing.md`.+## Unreleased (v2.0.0) - Four pipelines, one taxonomy++### Highlights++- **Video → sprite loops.** One still becomes a whole motion set: `video-canvas` pads it into the canvas the state needs, `video` animates it in place through Grok Imagine, `video-frames` keys every frame, `video-loop` finds the true period (or the one performed action) and emits a strip, a transparent GIF and a WebP, and `video-set` runs directions × states with per-item reports. Every stage is measured and fails by name.+- **Parallel row generation is a command.** `gen-set` generates every state row of a prepared run N at a time with the run's own identity ref, one report per row, a table and a non-zero exit on any failure — what the skill used to describe in prose.+- **One taxonomy.** `sprite-gen --help` opens with the four named pipelines (A atlas rows · B video → loop · C utilities · D post-processing) and groups every verb by domain; the grouping, the `scripts/` map and the docs index all derive from `sprite_gen/_modules.py`.+- **Documentation you can navigate.** `docs/README.md` indexes every doc once under its branch with a one-line owner; `docs/architecture.md` opens with a domain diagram and a four-pipeline diagram; the largest docs carry a table of contents; the repo README shrinks to an entry page and the sections it carried live in the docs that own them.++### Breaking++- New required binaries for pipeline B: `ffmpeg` (frame extraction) and `img2webp` from libwebp (WebP with exact alpha). Pipelines A, C and D do not need them.+- Removed the `scripts/` aliases that pointed at library modules or verb-less modules. Use the verb or module instead:++ | Removed | Use |+ |---|---|+ | `scripts/extract.py` | `sprite-gen extract` (`scripts/extract_sprite_row_frames.py`) |+ | `scripts/gif_utils.py` | `from sprite_gen.util import gif_utils` |+ | `scripts/runio.py` | `from sprite_gen.spec import runio` |+ | `scripts/reroll_state_row.py` | `sprite_gen.effects.reroll` (module; `interpolate_frames.py` covers the take workflow) |++- Maintainer experiments moved to `scripts/dev/` (`breathe_mutation_battery.py`, `measure_align_sigma.py`, `validate_pr6_subject_profile.py`, `check_visible_magenta.py`); they are not verbs and the skill no longer requires them.+- `docs/static-pose-recipe.md` merged into `docs/breathing.md` (one contract, one owner); links to the old file are gone.++### Added++- `sprite_gen/video/` domain and the verbs `video-canvas`, `video-frames`, `video-loop`, `video-set` (contract: `docs/video-pipeline.md`). `video-loop --cycle auto|periodic|one-shot`: action states (`jump`, `attack`, unknown) whose clip performs the action once get a recorded one-shot cut (rest → excursion → rest) instead of a hard failure; the report keeps the rejected periodic attempt and `table.md` gains a `kind` column. `walk`, `run`, `idle` still fail loud without a period.+- `sprite-gen gen-set` (`sprite_gen/gen/gen_set.py`, `scripts/gen_set.py`): anchors before rows on direction runs, reuse unless `--force`, `reports/gen-set/table.md` + `set.report.json`, `--provider` honoured verbatim with `gen`'s own default resolution and its recorded codex → grok availability failover per row.+- `sprite_gen._modules.DOMAINS` / `domain_of()`: display order and one-line meaning per domain; `cli.command_domains()` derives the help groups. A verb whose module is not in the table fails loudly.+- `docs/README.md` (documentation index) with a test that pins it to the file set and resolves every relative markdown link; tables of contents in `run-contract.md`, `layer-tracks.md`, `curation.md`, `directional-anchor-workflow.md`, `architecture.md`; `scripts/dev/README.md`.++### Changed++- `SKILL.md` is a route-first hub (still / atlas / video-to-loop / utilities) under the 24 KB skill budget; the interpreter rationale, the rename gate and the breathing contract moved verbatim to `docs/interpreter.md`, `docs/rename-gate.md`, `docs/breathing.md`.+- Walk detection window floor 10 % → 6 % of the clip so a legless body's fast bounce resolves; the 15 % depth rule keeps rejecting the one-step half period (verified on a biped and a quadruped). `video-set` motion templates no longer assume a biped.+- `README.md` is an entry page: what it is, the four pipelines, one quickstart each, install. Breathe, chroma-alpha quality, Backbone Lattice and the curation webview tour moved verbatim to `docs/breathing.md`, `docs/chroma-alpha.md`, `docs/pixel-unfake.md`, `docs/curation.md`.++### Removed++- See **Breaking** for the removed `scripts/` aliases and the merged doc.## v1.61.0 - Image to Videodiff --git a/README.md b/README.mdindex 0fc982b..1e53937 100644--- a/README.md+++ b/README.md@@ -1,6 +1,6 @@<h1 align="center">sprite-gen</h1>-<p align="center"><b>One drawing in. A game-ready sprite atlas out — breathing.</b></p>+<p align="center"><b>One drawing in. Game-ready sprites out — as an atlas, or as transparent motion loops.</b></p><p align="center">@@ -18,257 +18,108 @@----## Breathe--A still idle reads as frozen. **Breathe** turns a single pose into a living loop — deterministic squash & stretch baked on top of your curated frames. No regeneration, no re-extraction, no extra art. One sidecar field:--```json-"breathe": { "depth": 0.05, "breaths": 3 }-```--- **Anatomy-aware.** The engine measures the silhouette: neck bottleneck, symmetric eye pair on neckless blobs, torso-vs-appendage width. Heads stay **bit-identical** across every frame; wings and arms get pushed, never stretched.-- **Pixel-true.** Integer row/column mapping only — every output frame is still clean pixel art on the same grid. A 1px outline stays a 1px outline: the warp preserves silhouette edges and normalizes staircase doubling, anchored on the inner line.-- **A ruler you can grab.** Drag the rigid boundary (red), the body axis (blue), and the torso width (dashed) right on the live playback. The server re-derives the anatomy on release — and the preview keeps breathing while it recalculates.-- **Byte-identical preview.** The webview mirror and the Python bake produce the same bytes, enforced by golden tests. What you watch looping is exactly what ships in the atlas.--<p align="center">- <img src="docs/assets/breathe-editor.png" width="760" alt="breathe region editor: rigid boundary, body axis and torso width lines over live playback, with the baked phase filmstrip" />-</p>--The same deterministic bake applies to front, side, and back views of any silhouette, including humanoids, blobs, and tentacles.-Ask an image model for a "sprite sheet" and you know what you get: a character whose face changes every frame, a background that won't key out, poses that overlap and drift off-grid, and a PNG your game engine can't actually consume. Cute demo, useless asset.-`sprite-gen` is a Codex/Claude skill that closes that gap. Give it **one base image** and a list of actions — it drives the generation row by row, locks the character's identity, strips the chroma background to real alpha, extracts each pose as a clean transparent frame, and bakes a runtime atlas **with a machine-readable `manifest.json.frame_layout`**.+`sprite-gen` is a Codex/Claude skill and a Python CLI that closes that gap. Give it **one base image** — it drives generation row by row, locks the character's identity, strips the chroma background to real alpha, extracts each pose as a clean transparent frame, and bakes a runtime atlas **with a machine-readable `manifest.json.frame_layout`**. Or hand the same still to a video model and get back a seamless, transparent loop per motion state. For the last 10% that generation never gets right, a **curation webview** lets you compare, reject, nudge and watch the loop live before you bake.-And for the last 10% that generation never gets right, there's a **curation webview**: compare frames side by side, reject the broken ones, nudge rotation/scale/position non-destructively, watch the loop live — then bake. The pipeline does the labor; you keep the taste.+## Four pipelines, one CLI-```text-sprite-request.json → layout guides + prompts → sprite-gen gen state rows-→ chroma alpha → connected components → transparent frames-→ sprite-sheet-alpha.png + manifest.json.frame_layout-```+Every verb works alone or as a pipeline stage. `sprite-gen --help` prints this same map, with every verb grouped by domain.```mermaidflowchart LR- REQ["sprite-request.json<br/>(numeric SSoT)"] --> GUIDES["layout guides<br/>+ prompts"]- GUIDES --> GEN["sprite-gen gen<br/>state row strips"]- GEN --> EXTRACT["chroma alpha →<br/>connected components"]- EXTRACT --> FRAMES["transparent frames"]- FRAMES --> ATLAS["sprite-sheet-alpha.png<br/>+ manifest.json.frame_layout"]- FRAMES -. "curation webview (optional)" .-> ATLAS+ subgraph A["A · atlas rows"]+ direction LR+ a1[prepare] --> a2["gen · gen-set"] --> a3[extract] --> a4[curation] --> a5[compose-atlas]+ end+ subgraph B["B · video → loop"]+ direction LR+ b1[video-canvas] --> b2[video] --> b3[video-frames] --> b4[video-loop]+ end+ subgraph C["C · utilities"]+ direction LR+ c1[cutout] ~~~ c2[slice-sheet] ~~~ c3[unpack-atlas]+ end+ subgraph D["D · post-processing"]+ direction LR+ d1[recolor] ~~~ d2[compose-layers] ~~~ d3[export-*]+ end```-> Full architecture: [`docs/architecture.md`](docs/architecture.md)+| Pipeline | What goes in → what comes out | Docs |+|---|---|---|+| **A · atlas rows** | one still + a list of states → `sprite-sheet-alpha.png` + `manifest.json.frame_layout`, with **Breathe** baked on idle poses | [run-contract](docs/run-contract.md) · [breathing](docs/breathing.md) |+| **B · video → loop** | one still → per state, a seamless transparent GIF / WebP / strip, animated by Grok Imagine and cut at its true period | [video-pipeline](docs/video-pipeline.md) · [video](docs/video.md) |+| **C · utilities** | an imported image or grid sheet → clean transparent cuts; a finished atlas → a curator-ready run | [sheet-slicing](docs/sheet-slicing.md) · [curation](docs/curation.md) |+| **D · post-processing** | a finished sheet → deterministic colourways, rig layer composites, Aseprite / Phaser / Flame exports | [recolor](docs/recolor.md) · [layer-tracks](docs/layer-tracks.md) · [engine-export](docs/engine-export.md) |++Full index: [`docs/README.md`](docs/README.md). Architecture with domain and pipeline diagrams: [`docs/architecture.md`](docs/architecture.md).## What you actually get-- **A transparent sprite atlas** (`sprite-sheet-alpha.png`) — real alpha, no leftover chroma fringe, verified against white backgrounds.+- **A transparent sprite atlas** (`sprite-sheet-alpha.png`) — real alpha, no leftover chroma fringe, verified against white backgrounds ([why the extractor unmixes instead of peeling](docs/chroma-alpha.md)).- **A runtime manifest** (`manifest.json.frame_layout`) — absolute frame rectangles, per-state fps and loop flags. Your engine samples rectangles; it never guesses a grid.-- **Deterministic colourways** — `sprite-gen recolor` takes the base sheet plus a palette map and bakes N variant sheets in one command (exact RGB match by default; same input, same output bytes). The curation webview blink-compares them and records the adopted name. Detail: [`docs/recolor.md`](docs/recolor.md).-- **QA you can watch** — per-state GIFs and contact sheets, so motion is judged as motion before anything ships.-- **Honest labels** — short readable actions (idle, jump, attack, wave) are the stable path; cyclic locomotion (walk/run) is marked experimental unless motion QA actually passes. No silent overpromising.--## Chroma alpha quality--The extractor keeps chroma cleanup deterministic: soft-alpha unmix preserves antialiased hair strands and thin outlines instead of peeling them away before coverage can be solved.--<p align="center">- <img src="docs/assets/chroma-fullbody-illustration-magenta.png" width="640" alt="full-body chroma comparison: illustration on magenta key" /><br />- <em>Illustration, magenta key: source, v1.12.0 peel, v1.13.0 soft-alpha unmix.</em>-</p>--<p align="center">- <img src="docs/assets/chroma-fullbody-illustration-green.png" width="640" alt="full-body chroma comparison: illustration on green key" /><br />- <em>Illustration, green key: source, v1.12.0 peel, v1.13.0 soft-alpha unmix.</em>-</p>--<p align="center">- <img src="docs/assets/chroma-fullbody-pixelart-magenta.png" width="640" alt="full-body chroma comparison: pixel art on magenta key" /><br />- <em>Pixel art, magenta key: source, v1.12.0 peel, v1.13.0 binarized output.</em>-</p>--<p align="center">- <img src="docs/assets/chroma-fullbody-pixelart-green.png" width="640" alt="full-body chroma comparison: pixel art on green key" /><br />- <em>Pixel art, green key: source, v1.12.0 peel, v1.13.0 binarized output.</em>-</p>--The close-up crops below show the edge detail behind the full-body comparisons.------## Backbone Lattice--AI-generated "pixel art" is not pixel art. The blocks wobble, the edges carry antialiasing, and the lattice drifts within a single row, so cutting on an even grid smears one block into the next. The community fix is to "unfake" the image — guess the block size from run lengths and re-quantize — but that measures each frame on its own, so a walk cycle's cell size breathes frame to frame.--**Backbone Lattice** measures one grid for the whole subject and holds every cut to it. Per-frame pitch detection feeds a row-wide, cross-frame consensus that outvotes harmonic misdetections; that consensus grid is the *backbone* every cut snaps to. Cuts land on actual colour boundaries, and a minimum cell width proportional to the measured pitch keeps two neighbouring cuts from ever collapsing onto the same band. One backbone, so the same block stays the same size across a whole animation instead of jumping between frames.--The result is verified against what shipped, not eyeballed on a hand-picked frame: every pixel-unfake run is re-derived from its own source strip and compared pixel by pixel. The shape you approved stays the shape you get; what changes is only where outlines and shading land, which is exactly what the backbone decides.--## Curation webview--Generation gets you 90%. The webview is where a human takes it to *shipped* — standalone, no Studio or framework dependency, runs anywhere the skill is installed (Claude Code Desktop, the Codex app, a plain terminal).----- **Two rows per state:** the **play sequence** on top and a **candidate pool** below (e.g. a second or third generated take). Drag a frame's ⠿ grip to reorder the sequence, or pull a cut up from the pool — rebuild one clean run loop from the best frames across takes. The arrangement is saved, so reopening restores it.-- **Non-destructive transform** per frame: drag = move, wheel = scale, top handle = rotate, bottom-left = shear, plus a horizontal-flip toggle for left-right-reversed output. Edits live in a `curation.json` sidecar — source PNGs are never rewritten, and the compose step bakes the result deterministically. Preview and bake share one affine matrix, so what you align is what you get.-- **Live preview** animates the sequence at the state's fps, with play/pause, frame-by-frame stepping, and a 0.25×–4× speed control.-- Not just for sprites: point it at any folder of image candidates (icons, logos, generated drafts) with `unpack_atlas_run.py --pngs-dir` and use it as a general pick-the-winner view.--### Isometric ground grid--For isometric sets, the webview overlays the floor grid (from `meta.json` tile/anchor) so you can snap furniture to the diamond axes with the shear handle.----<img src="docs/assets/curator-iso.png" width="520" alt="isometric ground grid overlay" />--### Languages--The webview ships with English and Korean. Pass `--lang en|ko` when launching, or use the in-app toggle:--```bash-python3 scripts/serve_curation.py --run-dir <run-dir> --lang en # or ko-```--## Python support--`sprite-gen` supports CPython 3.10+. CI runs the minimum supported version (3.10) and the latest covered version (3.14) on GitHub-hosted runners.--The quickstart requires a Python install with working `venv`/`ensurepip`. If `python3 -m venv` fails before package installation in a local distribution, use a standard CPython build for any supported version and rerun the same commands.+- **Breathe** — a still idle becomes a living loop, deterministic squash & stretch baked on your curated frames from one sidecar field, anatomy-aware and pixel-true ([details](docs/breathing.md)).+- **Pixel-art that stays on grid** — the Backbone Lattice measures one grid for the whole subject and holds every cut to it ([details](docs/pixel-unfake.md)).+- **Motion loops from video** — jumps get a tall canvas, attacks a wide one, the loop point is the clip's own period, and a one-shot action is cut rest → action → rest ([details](docs/video-pipeline.md)).+- **Deterministic colourways** — `recolor` bakes N variant sheets from a palette map; same input, same output bytes ([details](docs/recolor.md)).+- **QA you can watch** — per-state GIFs and contact sheets, so motion is judged as motion before anything ships. Cyclic locomotion (walk/run) stays experimental unless motion QA actually passes.## Quickstart```bash-# 0. install dependencies (Pillow, NumPy) into a fresh virtualenv+# install (Pillow, NumPy) into a fresh virtualenv — the venv is the only supported interpreterpython3 -m venv .venv && source .venv/bin/activatepip install -e .--# 1. prepare a run from a base image-python3 scripts/prepare_sprite_run.py --out-dir <run-dir> --character-id <id> --base-image base.png--# 2. generate one row image per state with the engine-owned provider CLI-python3 scripts/generate_sprite_image.py --provider codex \- --prompt-file <run-dir>/prompts/<state>.txt \- --out <run-dir>/raw/<state>.png \- --ref <run-dir>/base-source.png \- --ref <run-dir>/references/layout-guides/<state>.png-# 3. extract frames-python3 scripts/extract_sprite_row_frames.py --run-dir <run-dir>--# 4. (optional) curate frames in the webview-python3 scripts/serve_curation.py --run-dir <run-dir>--# 5. bake the runtime atlas-python3 scripts/compose_sprite_atlas.py --run-dir <run-dir>+sprite-gen --help```-### Editing a finished sheet--When only the combined sheet survives, rebuild a curator-ready run dir, then curate and export:+**A · atlas rows** — one still to a runtime atlas.```bash-# rebuild frames: explicit --grid, --manifest rectangles, or alpha auto-detect (default)-python3 scripts/unpack_atlas_run.py --atlas sheet.png # auto-detect-python3 scripts/unpack_atlas_run.py --manifest manifest.json # exact rectangles-python3 scripts/unpack_atlas_run.py --pngs-dir furniture/ # import a loose PNG set--# after curating, bake corrections back to named PNGs-python3 scripts/export_curated_pngs.py --run-dir <run-dir>+sprite-gen prepare --out-dir <run> --character-id <id> --base-image base.png # request, guides, prompts+sprite-gen gen-set --run-dir <run> --provider codex # every state row, 4 at a time+sprite-gen extract --run-dir <run> # chroma → transparent frames+sprite-gen curation --run-dir <run> # (optional) pick, nudge, breathe+sprite-gen compose-atlas --run-dir <run> # sprite-sheet-alpha.png + manifest.json```-Output defaults to a findable `<source>-curator` folder next to the input.--### Baking colourways of a finished sheet--Once the atlas is composed, swap selected colours into N finished sheets without-re-running generation. Dot art is exact-match by default; soft-edged art can opt-into a tolerance. Geometry and alpha never move — the base manifest describes-every variant.+**B · video → loop** — one still to transparent loops (needs `ffmpeg`, `img2webp`, and your own `grok` login or `XAI_API_KEY`).```bash-# draft the opaque colours (edit into a recolor spec with kind "sprite-gen-recolor")-python3 -m sprite_gen.cli recolor-palette --base <run-dir>/sprite-sheet-alpha.png --out palette.draft.json--# bake every colourway into <run-dir>/variants/-python3 -m sprite_gen.cli recolor --run-dir <run-dir> --spec recolor.spec.json--# blink-compare and adopt in the curation view-python3 -m sprite_gen.cli curation --run-dir <run-dir>+sprite-gen video-set --base side=still.png --states idle,walk,run,jump,attack --out-dir set/+# per item: video-canvas → video → video-frames → video-loop; set/table.md names every result```-Full spec/report contract and the adopt sidecar field: [`docs/recolor.md`](docs/recolor.md).--### Cutting a background off an imported image--Generated sprites are keyed off their own magenta/green background inside the-pipeline, so they never need this. `cutout` is the import/post-edit utility: an-image that arrived *with* an opaque uniform background (a hand-drawn icon, a-downloaded sprite, a screenshot) is turned into a clean transparent PNG.--<p align="center">- <img src="docs/assets/cutout-demo.png" width="720" alt="cutout: a white-background game icon turned into a clean transparent PNG, glass highlights preserved" />-</p>+**C · utilities** — each stands alone.```bash-# routes on the corner colour: white/ivory -> matte, magenta/green -> extract engine-python3 -m sprite_gen.cli cutout icon.png --white-check+sprite-gen cutout icon.png --white-check # white/ivory → matte, magenta/green → chroma engine+sprite-gen slice-sheet --sheet sheet.png --chroma-key magenta --grid 3x2 # multi-figure sheet → per-cell cuts+sprite-gen unpack-atlas --atlas sheet.png # finished atlas → curator-ready run (or --pngs-dir folder/)```-It reads the corner background colour and routes (`--key auto|white|magenta|green`):--- **white / ivory / solid** → position matte. A corner flood-fill keeps the- connected background only (bright highlights *inside* the object survive, not- holed), then a decontaminated soft alpha feathers the border. Tune with- `--strength` (bevel removal), `--band` (edge depth), `--erode`.-- **magenta / green key** → the project's verified `extract` chroma engine is- reused as-is. Key colours never appear in objects, so its colour-only cut is- safe there — exactly where a white matte's flood-fill guard is *not* needed.+**D · post-processing** — refine a finished sheet without regenerating.-`--white-check` writes cyan/magenta/yellow composites so any leftover fringe-shows loudly. For uniform backgrounds; not for complex/non-uniform ones.--The full agent-facing workflow and contracts live in [`SKILL.md`](SKILL.md).+```bash+sprite-gen recolor-palette --base <run>/sprite-sheet-alpha.png --out palette.draft.json+sprite-gen recolor --run-dir <run> --spec recolor.spec.json # → <run>/variants/+sprite-gen compose-layers --run-dir <run> # rig runs: declared stacks → <run>/layers/+sprite-gen export-aseprite --run-dir <run> # Aseprite JSON for Phaser / Flame+```-## Install+The agent-facing workflow, gates and contracts live in [`SKILL.md`](SKILL.md).-From Codex skill installer workflows, install this repository as a root skill:+## Install as a skill```bashpython3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \--repo aldegad/sprite-gen --path . --name sprite-gen```-### Image generation ownership--Provider-backed generation is part of this engine (`sprite_gen.gen`), with-`codex` and `grok` as the supported providers. The general `image-gen` skill is-only a thin shuttle to the same command, so it does not need a second provider-implementation. Transparent stills follow a per-provider strategy: `codex` asks-`image_gen` for a real alpha channel (native, first choice) and the measured alpha-is published; `grok` is keyed out of a chroma background. See-[`docs/gen.md`](docs/gen.md) for the CLI and verification contract.--### Image to video--`sprite-gen video --image still.png --prompt "…" --out clip.mp4` animates one-still through Grok Imagine using **your own** credential — the `grok` CLI login-(`grok login`, SuperGrok Imagine quota) or an `XAI_API_KEY`. Nothing is shipped-with the repo; the report says which one ran. An expired login stops before-uploading and tells you the exact refresh command. Setup, parameters, and the-verification contract: [`docs/video.md`](docs/video.md).--### Video → sprite loops--`sprite-gen video-set --base side=still.png --states idle,walk,run,jump,attack --out-dir set/`-turns one still into a seamless, transparent loop per state: the still is padded into-the canvas the state needs (jumps tall, attacks wide), animated in place by Grok-Imagine, keyed frame by frame, and cut at its true period into a strip, a GIF and a-WebP — each stage measured and fail-loud. Contract and the measured rules behind it:-[`docs/video-pipeline.md`](docs/video-pipeline.md).+Image generation is part of this engine (`sprite_gen.gen`, providers `codex` and `grok`; the general `image-gen` skill is a thin shuttle over it). Video uses **your own** credential — the `grok` CLI login or an `XAI_API_KEY` — and nothing is shipped with the repo ([docs/video.md](docs/video.md)).++`sprite-gen` supports CPython 3.10+; CI runs 3.10 and 3.14. The quickstart needs a Python with working `venv`/`ensurepip`.## Attributiondiff --git a/SKILL.md b/SKILL.mdindex 5fa70b3..bb00f08 100644--- a/SKILL.md+++ b/SKILL.md@@ -223,19 +223,6 @@ qa_note=<one sentence>## Docs Topology-Leaf docs are one link deep. Walk the branch that matches your task; each doc owns its tables and this hub only points.--```text-CONTRACT & STRUCTURE docs/run-contract.md · docs/architecture.md-REQUEST AUTHORING docs/states-and-frames.md · docs/subject-profiles.md · docs/pixel-unfake.md · docs/chroma-alpha.md-GENERATION docs/gen.md · docs/video.md · docs/video-pipeline.md · docs/frame-interpolation.md · docs/seamless-video-loop.md-CURATION docs/curation.md · docs/breathing.md-COLOURWAYS docs/recolor.md-LAYER TRACKS docs/layer-tracks.md-ENGINE EXPORT docs/engine-export.md-SPECIALIZED INPUTS docs/directional-anchor-workflow.md · docs/sheet-slicing.md-QA docs/qa-motion.md · docs/locomotion-curation.md-RUNTIME & PROCESS docs/interpreter.md · docs/rename-gate.md · docs/troubleshooting.md-```+The documentation index is [`docs/README.md`](docs/README.md): every leaf doc once, under the four pipelines (A atlas rows · B video → loop · C utilities · D post-processing) and the taxonomy branches, each with a one-line owner. Leaf docs are one link deep; each owns its tables and this hub only points. Architecture with the domain and pipeline diagrams: [`docs/architecture.md`](docs/architecture.md).Concept ownership: `sprite-request.json`/cell/states/takes → run-contract §2 · states-and-frames; `run_revision`/salvage/`curation.stale-*.json` and every `curation.json` field (`selected`/`order`/`deleted`/`transforms`/`pixels`/`clones`/`pixel_unfake`/`revision`/`recolor.picked`) → curation.md; frame **clones** → curation.md + compose; `frame_layout` runtime contract → run-contract + "Runtime Contract" above; `fit`/pixel-unfake twins → pixel-unfake.md; recolor spec/report/`variants/` → recolor.md; `rig`/`track`/`layers` → layer-tracks.md; video canvas/period/seam/strip meta → video-pipeline.md; webview interactions → `sprite_gen/curator/` described in curation.md + recolor.md.diff --git a/docs/architecture.md b/docs/architecture.mdindex e5f8260..aa007d0 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -1,31 +1,90 @@# sprite-gen — Implemented Architecture-> Status: reference (describes the code as it actually is, v1.56.x, 2026-07-11).+> Owns: How the code is laid out: domains, stage ownership, the numeric SSoT, the cell model, extraction internals, runtime manifest · Index: [docs/README.md](README.md)++> Status: reference (describes the code as it actually is, v2.0.0, 2026-09-09).> Canonical behavior contract lives in [`../SKILL.md`](../SKILL.md); this doc-> explains *how* the scripts realize that contract. If this doc and `SKILL.md`-> ever disagree, `SKILL.md` wins and this doc is the bug.+> explains *how* the code realizes that contract. If this doc and `SKILL.md`+> ever disagree, `SKILL.md` wins and this doc is the bug. The documentation+> index is [`README.md`](README.md).++## Contents++- [0. Domains — the taxonomy](#0-domains--the-taxonomy)+- [1. Four pipelines](#1-four-pipelines)+- [2. Stage ownership (each script does one job)](#2-stage-ownership-each-script-does-one-job)+- [3. The numeric SSoT: `sprite-request.json`](#3-the-numeric-ssot-sprite-requestjson)+- [4. The cell model](#4-the-cell-model-read-this--it-is-the-most-misunderstood-part)+- [5. Idle-anchor architecture (identity ownership)](#5-idle-anchor-architecture-identity-ownership)+- [6. Extraction internals](#6-extraction-internals-extract_sprite_row_framespy)+- [7. Curation sidecar (`curation.json`)](#7-curation-sidecar-curationjson)+- [8. Runtime contract (`manifest.json`)](#8-runtime-contract-manifestjson)+- [9. Output directory](#9-output-directory-one-worker-owns-one-character-folder)+- [10. Inverse paths](#10-inverse-paths-editing-finished-assets)+- [11. Relationship to hatch-pet](#11-relationship-to-hatch-pet)++## 0. Domains — the taxonomy++`sprite_gen/_modules.py` is the one table that says which domain a module belongs to.+`sprite-gen --help`, the `scripts/` wrappers and the docs index enumerate from it; a+module that is not in the table cannot be a verb (the CLI raises instead of inventing+a group). Every domain package is a folder under `sprite_gen/`.++```mermaid+flowchart TB+ subgraph pkg["sprite_gen/ (_modules.py owns the mapping)"]+ direction LR+ spec["spec<br/>sprite-request schema · layout resolver · runio (lock + atomic writes) · migrations"]+ gen["gen<br/>prepare · gen (codex / grok) · gen-set · video (Grok Imagine)"]+ video["video<br/>canvas · frames · loop · batch (video-set)"]+ frames["frames<br/>extract · cutout · slice-sheet · unpack-atlas · segment"]+ curate["curate<br/>curation sidecar · direction anchors"]+ compose["compose<br/>atlas · cycle · gif · layers · export-pngs · export-aseprite"]+ effects["effects<br/>breathe · anatomy · recolor · interpolate"]+ qa["qa<br/>inspect · score · preview · correction-loop"]+ serve["serve<br/>curation webview · composition canvas"]+ end+ cli["cli.py — one entrypoint, verbs grouped by domain"] --> pkg+ spec -.read by every stage.-> gen & frames & compose & qa+```-## 1. One sentence+## 1. Four pipelines-A character image plus a numeric request becomes a transparent sprite atlas by-generating **one horizontal strip per animation state**, cleaning chroma,-extracting poses as connected components, refitting each pose into a fixed cell-(optionally through the deterministic pixel-unfake path), and packing the-cells into a single sheet described by a runtime manifest.+One sentence: a character image plus a numeric request becomes a transparent sprite+atlas (pipeline A) or a set of transparent motion loops (pipeline B); imported images+are cut clean (C); finished sheets are refined without regeneration (D). Every verb is+also a standalone tool — the pipelines are the order the docs recommend, not a wrapper.```mermaidflowchart TD- REQ["sprite-request.json<br/>(numeric SSoT)"] --> PREP["prepare_sprite_run.py"]- PREP --> GUIDES["references/layout-guides/<state>.png<br/>prompts/<state>.txt"]- GUIDES --> GEN["sprite-gen gen<br/>(codex or grok; one image per state — the only AI step)"]- GEN --> RAW["raw/<state>.png<br/>(one horizontal strip per state)"]- RAW --> EXTRACT["extract_sprite_row_frames.py<br/>chroma removal → connected components<br/>→ fit_to_cell or pixel-unfake path"]- EXTRACT --> FRAMES["frames/<state>/frame-N.png (+ frame-N.plain.png twin)<br/>frames/frames-manifest.json"]- FRAMES --> CURATE["serve_curation.py (optional webview)<br/>curation.json (non-destructive sidecar)"]- FRAMES --> COMPOSE["compose_sprite_atlas.py"]- CURATE -. "selected / transforms / pixel_unfake" .-> COMPOSE- COMPOSE --> ATLAS["sprite-sheet-alpha.png + manifest.json<br/>(frame_layout = runtime SSoT)"]- FRAMES --> QA["preview_animation.py<br/>qa/<state>-contact.png · qa/<state>.gif"]+ subgraph A["A · atlas rows (docs/run-contract.md)"]+ REQ["sprite-request.json<br/>(numeric SSoT)"] --> PREP["prepare"]+ PREP --> GUIDES["references/layout-guides/<state>.png<br/>prompts/<state>.txt"]+ GUIDES --> GEN["gen · gen-set<br/>(codex or grok; one strip per state — the only AI step)"]+ GEN --> RAW["raw/<state>.png"]+ RAW --> EXTRACT["extract<br/>chroma removal → connected components<br/>→ fit_to_cell or pixel-unfake"]+ EXTRACT --> FRAMES["frames/<state>/frame-N.png<br/>frames/frames-manifest.json"]+ FRAMES --> CURATE["curation (webview)<br/>curation.json sidecar"]+ FRAMES --> COMPOSE["compose-atlas"]+ CURATE -. "selected / transforms / breathe" .-> COMPOSE+ COMPOSE --> ATLAS["sprite-sheet-alpha.png + manifest.json<br/>(frame_layout = runtime SSoT)"]+ FRAMES --> QA["preview · inspect · score"]+ end+ subgraph B["B · video → loop (docs/video-pipeline.md)"]+ STILL["one still on a flat key"] --> CANVAS["video-canvas<br/>state canvas (tall / wide / square)"]+ CANVAS --> VID["video<br/>Grok Imagine, in-place motion"]+ VID --> VFR["video-frames<br/>ffmpeg + cutout keying"]+ VFR --> LOOP["video-loop<br/>true period or one-shot → strip · GIF · WebP"]+ SET["video-set"] -. "directions × states" .-> CANVAS+ end+ subgraph C["C · utilities"]+ CUT["cutout<br/>white matte / chroma engine"] ~~~ SLICE["slice-sheet"] ~~~ UNPACK["unpack-atlas"]+ end+ subgraph D["D · post-processing"]+ RECOLOR["recolor · recolor-palette"] ~~~ LAYERS["compose-layers"] ~~~ EXPORT["export-pngs · export-aseprite"]+ end+ ATLAS --> D+ UNPACK --> CURATE```## 2. Stage ownership (each script does one job)diff --git a/docs/breathing.md b/docs/breathing.mdindex 0d9eaaa..5cf1a7c 100644--- a/docs/breathing.md+++ b/docs/breathing.md@@ -1,5 +1,26 @@# 호흡(idle breathing) · 정지 자세 행 — 후처리 레이어 계약+> Owns: The idle-breathing post-process layer and the static-pose row recipe · Index: [docs/README.md](README.md)++## What Breathe does (from the README, 2026-09-09)++A still idle reads as frozen. **Breathe** turns a single pose into a living loop — deterministic squash & stretch baked on top of your curated frames. No regeneration, no re-extraction, no extra art. One sidecar field:++```json+"breathe": { "depth": 0.05, "breaths": 3 }+```++- **Anatomy-aware.** The engine measures the silhouette: neck bottleneck, symmetric eye pair on neckless blobs, torso-vs-appendage width. Heads stay **bit-identical** across every frame; wings and arms get pushed, never stretched.+- **Pixel-true.** Integer row/column mapping only — every output frame is still clean pixel art on the same grid. A 1px outline stays a 1px outline: the warp preserves silhouette edges and normalizes staircase doubling, anchored on the inner line.+- **A ruler you can grab.** Drag the rigid boundary (red), the body axis (blue), and the torso width (dashed) right on the live playback. The server re-derives the anatomy on release — and the preview keeps breathing while it recalculates.+- **Byte-identical preview.** The webview mirror and the Python bake produce the same bytes, enforced by golden tests. What you watch looping is exactly what ships in the atlas.++<p align="center">+ <img src="assets/breathe-editor.png" width="760" alt="breathe region editor: rigid boundary, body axis and torso width lines over live playback, with the baked phase filmstrip" />+</p>++The same deterministic bake applies to front, side, and back views of any silhouette, including humanoids, blobs, and tentacles.+> SKILL.md Script Map 에서 옮겨온 본문(2026-09-09, 허브 슬림화). `compose_sprite_gif.py` / `compose_sprite_atlas.py` 가 굽는 호흡 레이어, 정지 자세 행 레시피, 큐레이션 뷰의 호흡 편집기 계약을 소유한다. 실측 근거·프레임 게이트는 아래 "정지 자세(Static-Pose) 행 레시피" 절.- **에이전트 주도 호흡** (사용자가 "숨쉬기 적용해서 뽑아줘" 라고만 해도 됨): 호흡은 사이드카 필드라 뷰 없이도 켤 수 있다 — (1) `states.<state>.breathe = {"depth": 0.06, "breaths": 1, "lag": 0.1}` 만 쓰면 된다. **경계는 선언하지 않는다** — `sprite_gen/anatomy.py` 가 검출한다. 큐레이터를 거치면 그 결과가 사이드카 `anatomy` 에 얼려지고(`GET /api/breathe-anatomy`), 뷰 없이 에이전트가 `breathe` 만 쓴 런은 `anatomy` 가 비어 있어 **굽기가 매번 다시 잰다** — 굽기는 사이드카에 쓰지 않는다. 어느 쪽이든 동작한다. **굽기는 얼린 값을 신뢰하지 않는다 — 언제나 자기 기준 프레임에서 다시 잰다** (얼린 값은 큐레이터 프리뷰용 캐시다). 사이드카와 어긋나면 manifest 의 `sidecar_drift` 로 값을 실어 보고한다. 그 캐시가 아직 유효한지는 기준 프레임의 **입력** 지문(원본 파일 스탬프·픽셀편집·변형·변종)으로 판정하고, 어긋나면 큐레이터가 프리뷰·영상 내보내기를 **거부하며 갱신하라고 알린다** — 조용히 낡은 숫자로 그리지 않는다. 사람이 특정 행에 고정하고 싶을 때만 `rigid_row` 를 준다. (에이전트 직접 쓰기는 `load_curation`→`stamp_curation` 도장 경로 필수, 열린 탭은 새로고침 안내 — 함정 상세: [`troubleshooting.md`](troubleshooting.md)), (2) `compose_sprite_gif.py`/`compose_sprite_atlas.py` 가 자동으로 굽는다. 검증: gif-manifest 의 `breathe.phases`. **구 `splits`/`amplitude`/`subpixel` 은 요란하게 거부된다** — 옮기려면 `sprite-gen migrate-breathe <run-dir> --apply`.@@ -67,3 +88,7 @@3. 깜빡임(정면/옆)은 자동 생성하지 않는다 — "깜빡임 추가 대기" 로 보고하고사람이 정지 프레임 확정 후 눈을 깎는다.4. 열린 큐레이션 탭이 있으면 두-작성자 충돌 방지를 위해 새로고침을 안내한다.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/chroma-alpha.md b/docs/chroma-alpha.mdindex 4d04a42..e86a6e9 100644--- a/docs/chroma-alpha.md+++ b/docs/chroma-alpha.md@@ -1,5 +1,37 @@# Chroma Key & Alpha Cleanup — sprite-gen reference+> Owns: Choosing the chroma key and diagnosing alpha cleanup after extraction · Index: [docs/README.md](README.md)++## Why the extractor unmixes instead of peeling (from the README, 2026-09-09)++The extractor keeps chroma cleanup deterministic: soft-alpha unmix preserves antialiased hair strands and thin outlines instead of peeling them away before coverage can be solved.++<p align="center">+ <img src="assets/chroma-fullbody-illustration-magenta.png" width="640" alt="full-body chroma comparison: illustration on magenta key" /><br />+ <em>Illustration, magenta key: source, v1.12.0 peel, v1.13.0 soft-alpha unmix.</em>+</p>++<p align="center">+ <img src="assets/chroma-fullbody-illustration-green.png" width="640" alt="full-body chroma comparison: illustration on green key" /><br />+ <em>Illustration, green key: source, v1.12.0 peel, v1.13.0 soft-alpha unmix.</em>+</p>++<p align="center">+ <img src="assets/chroma-fullbody-pixelart-magenta.png" width="640" alt="full-body chroma comparison: pixel art on magenta key" /><br />+ <em>Pixel art, magenta key: source, v1.12.0 peel, v1.13.0 binarized output.</em>+</p>++<p align="center">+ <img src="assets/chroma-fullbody-pixelart-green.png" width="640" alt="full-body chroma comparison: pixel art on green key" /><br />+ <em>Pixel art, green key: source, v1.12.0 peel, v1.13.0 binarized output.</em>+</p>++The close-up crops below show the edge detail behind the full-body comparisons.+++++> `SKILL.md` 허브에서 분리한 시나리오 상세. 크로마 키를 고르거나(특히 소재색이 키와 인접할 때), 추출 후 소재색 손실을 진단할 때 이 문서를 따른다. 분기표 SSoT 는 image-gen SKILL.md 최상단 게이트이고, 이 문서는 그 규칙의 sprite-gen 쪽 상세다.## Key selectiondiff --git a/docs/curation.md b/docs/curation.mdindex 9c7f70e..44a0a24 100644--- a/docs/curation.md+++ b/docs/curation.md@@ -1,5 +1,49 @@# Curation — webview, standalone view, finished-sheet editing, `curation.json` — sprite-gen reference+> Owns: The webview, standalone candidate view, finished-sheet editing and every `curation.json` field · Index: [docs/README.md](README.md)++## Contents++- [The webview in one screen (from the README, 2026-09-09)](#the-webview-in-one-screen-from-the-readme-2026-09-09)+ - [Isometric ground grid](#isometric-ground-grid)+ - [Languages](#languages)+- [Standalone Curation View (이미지 후보 큐레이션 — 스프라이트 아님)](#standalone-curation-view-이미지-후보-큐레이션-스프라이트-아님)+- [Curation Webview (파이프라인 스텝 3.5) — 캐릭터 검수의 정식 뷰](#curation-webview-파이프라인-스텝-35-캐릭터-검수의-정식-뷰)+ - [Colourway (recolor) compare and pick](#colourway-recolor-compare-and-pick)+ - [생성 트리거 관용구 (SSoT = `src/gen-trigger.js`)](#생성-트리거-관용구-ssot-srcgen-triggerjs)+- [Editing a finished sprite sheet (no `frames/` source)](#editing-a-finished-sprite-sheet-no-frames-source)+- [Multi-agent rules for the auto-launch (클로징 스텝 5)](#multi-agent-rules-for-the-auto-launch-클로징-스텝-5)+- [Curation Sidecar (`curation.json`)](#curation-sidecar-curationjson)+- [Related](#related)+- [Base editing (same component as frames)](#base-editing-same-component-as-frames)++## The webview in one screen (from the README, 2026-09-09)++Generation gets you 90%. The webview is where a human takes it to *shipped* — standalone, no Studio or framework dependency, runs anywhere the skill is installed (Claude Code Desktop, the Codex app, a plain terminal).++++- **Two rows per state:** the **play sequence** on top and a **candidate pool** below (e.g. a second or third generated take). Drag a frame's ⠿ grip to reorder the sequence, or pull a cut up from the pool — rebuild one clean run loop from the best frames across takes. The arrangement is saved, so reopening restores it.+- **Non-destructive transform** per frame: drag = move, wheel = scale, top handle = rotate, bottom-left = shear, plus a horizontal-flip toggle for left-right-reversed output. Edits live in a `curation.json` sidecar — source PNGs are never rewritten, and the compose step bakes the result deterministically. Preview and bake share one affine matrix, so what you align is what you get.+- **Live preview** animates the sequence at the state's fps, with play/pause, frame-by-frame stepping, and a 0.25×–4× speed control.+- Not just for sprites: point it at any folder of image candidates (icons, logos, generated drafts) with `unpack_atlas_run.py --pngs-dir` and use it as a general pick-the-winner view.++### Isometric ground grid++For isometric sets, the webview overlays the floor grid (from `meta.json` tile/anchor) so you can snap furniture to the diamond axes with the shear handle.++++<img src="assets/curator-iso.png" width="520" alt="isometric ground grid overlay" />++### Languages++The webview ships with English and Korean. Pass `--lang en|ko` when launching, or use the in-app toggle:++```bash+python3 sprite-gen curation --run-dir <run-dir> --lang en # or ko+```+> `SKILL.md` 허브에서 분리한 시나리오 상세. 큐레이션뷰를 띄우거나(파이프라인 스텝 3.5 / 클로징 스텝 5), 임의 이미지 후보군을 비교·선택하거나, 완성된 시트를 다시 편집하거나, `curation.json` 스키마를 다뤄야 할 때 이 문서를 따른다.## Standalone Curation View (이미지 후보 큐레이션 — 스프라이트 아님)diff --git a/docs/directional-anchor-workflow.md b/docs/directional-anchor-workflow.mdindex a7f7a3e..4401c62 100644--- a/docs/directional-anchor-workflow.md+++ b/docs/directional-anchor-workflow.md@@ -1,7 +1,18 @@# Directional / 45° Anchor Workflow — sprite-gen reference+> Owns: Directional / 45° rows: base → direction anchors → rows, the left-right gate · Index: [docs/README.md](README.md)+> `SKILL.md` 에서 분리한 시나리오 상세. 방향성·45도·locomotion 행 생성 시 이 문서를 따른다. 기본 simple sprite (`idle`/`jump`/`attack`/`wave`) 에는 필요 없다. 내용은 손실 없이 `SKILL.md` 본문에서 그대로 옮겨졌다.+## Contents++- [전체 체인 한눈에 (그림)](#전체-체인-한눈에-그림)+- [Prepare 스캐폴딩 (`--directions`, 2026-07-14)](#prepare-스캐폴딩---directions-2026-07-14)+- [Hatch-Pet Locomotion Pattern](#hatch-pet-locomotion-pattern)+- [Directional Chain Default](#directional-chain-default)+- [Checklist Direction-Anchor Workflow](#checklist-direction-anchor-workflow)+- [Advanced Gates](#advanced-gates)+### 전체 체인 한눈에 (그림)```text@@ -316,3 +327,6 @@ Expose only these gates to the caller for advanced hatch-style runs:All prompt text, guides, extraction, atlas composition, and QA must be regenerated from `sprite-request.json`. Do not keep a separate prompt fork as a second truth surface. If an advanced gate fails QA, report the state as failed or experimental rather than silently falling back to a static or mirrored result.+## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/engine-export.md b/docs/engine-export.mdindex b17d81e..cca4031 100644--- a/docs/engine-export.md+++ b/docs/engine-export.md@@ -1,5 +1,7 @@# Engine export+> Owns: Aseprite-compatible export for Phaser and Flame · Index: [docs/README.md](README.md)+`sprite-gen export-aseprite` describes a composed sprite-gen atlas using the JSON schema consumed by Aseprite loaders. It does not create an editable `.aseprite` source file and it does not re-encode the PNG.Run it after `compose-atlas`:@@ -50,3 +52,7 @@ This writes `exports/aseprite/idle.json`, `walk.json`, and so on. Every file use- `loop` remains in `manifest.json`. Aseprite frame tags carry direction and range but no sprite-gen loop policy, and Flame's Aseprite factory constructs its default looping animation without reading tags.- The curation webview is unchanged. This is a post-compose CLI export, not a new webview download button.- The exporter refuses malformed row mappings and output paths outside the run directory. Split-state files are staged as a complete directory and then published together.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/frame-interpolation.md b/docs/frame-interpolation.mdindex d5a821b..ffe7751 100644--- a/docs/frame-interpolation.md+++ b/docs/frame-interpolation.md@@ -1,5 +1,7 @@# AI Frame Interpolation (in-betweens)+> Owns: Generative in-betweens for sprite frames, recorded as a take · Index: [docs/README.md](README.md)+`sprite_gen/effects/interpolate.py` (`scripts/interpolate_frames.py`) makes an **in-betweenframe** between two frames of one state — a half-closed eyelid between open/closedidle frames, a mid-swing arm between windup and strike.@@ -90,3 +92,7 @@ stray pixels with the curator's pixel editor if needed. Identity drift is a rerointerpolator (alignment canvas contract, prompt composition, take write, requestidempotency, loud rejections including unknown providers). Real provider generationis exercised manually, not in CI.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/gen.md b/docs/gen.mdindex cf0b18a..31f6fd3 100644--- a/docs/gen.md+++ b/docs/gen.md@@ -1,5 +1,7 @@# `sprite-gen gen` — provider-backed image generation (engine SSoT)+> Owns: `sprite-gen gen` / `gen-set`: providers, default resolution, transparency strategy per provider, row usage · Index: [docs/README.md](README.md)+Generation is a first-class engine module (`sprite_gen/gen/`), not an externalskill. One call = a prompt (+ optional reference images) → one **verified** PNG ondisk, with an optional transparent output whose strategy is decided per provider@@ -190,3 +192,7 @@ On a 4-frame idle mushroom row, grok generatedin ~18.4 s vs codex ~39.0 s (~2.1× faster). codex adhered better to negative constraints("no grid lines"); grok added faint cell dividers. Pick per need: grok for speed, codexfor tighter prompt adherence.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/interpreter.md b/docs/interpreter.mdindex cd704ba..77b7b21 100644--- a/docs/interpreter.md+++ b/docs/interpreter.md@@ -1,5 +1,7 @@# 실행 인터프리터 — 전역 `python3` 는 이 스킬의 인터프리터가 아니다+> Owns: Why the project venv is the only interpreter (no global `python3`, no NumPy fallback) · Index: [docs/README.md](README.md)+> SKILL.md 허브에서 옮겨온 전문(2026-09-09, 허브 슬림화). 규칙 자체(venv 절대경로 · 폴백 금지 · NumPy 게이트)는 허브가 요약으로 유지하고, 근거와 세부는 여기가 소유한다.이 스킬의 모든 명령은 **레포 루트의 venv 인터프리터**로 실행한다:@@ -46,3 +48,7 @@ $SPRITE_GEN_ROOT/.venv/bin/python <script.py> ...`docs/*.md` 는 활성화 단계가 없는 셸에서 읽히므로, 절대경로든 상대경로든 **여기서는 상대형을 쓰지않는다** — 위 venv 절대경로 형식 하나만 쓴다. (`tests/test_entrypoint_interpreter.py` 가 이 두 파일군에대해 잠근다.)++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/layer-tracks.md b/docs/layer-tracks.mdindex 783bd99..f88bde1 100644--- a/docs/layer-tracks.md+++ b/docs/layer-tracks.md@@ -1,5 +1,7 @@# Layer Tracks — rig · track · composite contract (SSoT)+> Owns: Rig runs: `rig` / `track` / `layers` contract and `compose-layers` · Index: [docs/README.md](README.md)+> Status: **contract** (normative). This doc owns the optional layer feature: the> character rig profile, the per-row track kind, the composite stack, and what a> layer bake is allowed to touch.@@ -16,6 +18,25 @@> [`../sprite_gen/compose/compose_layers.py`](../sprite_gen/compose/compose_layers.py), pinned by> `tests/test_layer_compose.py`.+## Contents++- [0. One sentence](#0-one-sentence)+- [1. The compatibility rule (read this first)](#1-the-compatibility-rule-read-this-first)+- [2. Ownership audit — what already owns what](#2-ownership-audit-what-already-owns-what)+ - [Boundary findings](#boundary-findings)+- [3. Request schema extension](#3-request-schema-extension)+ - [3.1 Profiles and landmarks](#31-profiles-and-landmarks)+ - [3.2 Tracks](#32-tracks)+ - [3.3 Stack elements](#33-stack-elements)+- [4. Composition contract (deterministic)](#4-composition-contract-deterministic)+- [5. Output and manifest extension](#5-output-and-manifest-extension)+- [6. Validation contract](#6-validation-contract)+- [7. Using it — the CLI and where it sits in the run](#7-using-it-the-cli-and-where-it-sits-in-the-run)+ - [7.1 Declaring](#71-declaring)+ - [7.2 Baking](#72-baking)+- [8. Out of scope](#8-out-of-scope)+- [Related](#related)+## 0. One sentenceA run may declare a **rig** (a character type profile plus integer landmarks perdiff --git a/docs/locomotion-curation.md b/docs/locomotion-curation.mdindex 11cca15..a296189 100644--- a/docs/locomotion-curation.md+++ b/docs/locomotion-curation.md@@ -1,5 +1,7 @@# Locomotion Curation & Clean GIF Export — sprite-gen reference+> Owns: Motion-phase experiments, manual selected cycles, clean GIF export · Index: [docs/README.md](README.md)+> `SKILL.md` 에서 분리한 시나리오 상세. motion-phase 실험·수동 selected-cycle·클린 GIF export 가 필요할 때 따른다. 내용은 손실 없이 `SKILL.md` 본문에서 그대로 옮겨졌다.### Motion Phase Guide Experiment@@ -70,3 +72,7 @@ Clean GIF invariants:- Use infinite loop (`loop-count 0`) for looped states.- Keep contact sheets separate from GIFs. Contact sheets may use checker backgrounds for inspection; runtime/shareable GIFs should preserve transparency.- If a loop only works after dropping or reordering frames, record the selected 1-based frame order. Do not hide that as an automatic pass.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/pixel-unfake.md b/docs/pixel-unfake.mdindex a29e5dc..cf8f486 100644--- a/docs/pixel-unfake.md+++ b/docs/pixel-unfake.md@@ -1,5 +1,15 @@# Pixel Unfake Fit (`fit` / `pixel_unfake`) — sprite-gen reference+> Owns: The `fit` / `pixel_unfake` path for pixel-art targets and jitter-free locomotion · Index: [docs/README.md](README.md)++## Backbone Lattice (from the README, 2026-09-09)++AI-generated "pixel art" is not pixel art. The blocks wobble, the edges carry antialiasing, and the lattice drifts within a single row, so cutting on an even grid smears one block into the next. The community fix is to "unfake" the image — guess the block size from run lengths and re-quantize — but that measures each frame on its own, so a walk cycle's cell size breathes frame to frame.++**Backbone Lattice** measures one grid for the whole subject and holds every cut to it. Per-frame pitch detection feeds a row-wide, cross-frame consensus that outvotes harmonic misdetections; that consensus grid is the *backbone* every cut snaps to. Cuts land on actual colour boundaries, and a minimum cell width proportional to the measured pitch keeps two neighbouring cuts from ever collapsing onto the same band. One backbone, so the same block stays the same size across a whole animation instead of jumping between frames.++The result is verified against what shipped, not eyeballed on a hand-picked frame: every pixel-unfake run is re-derived from its own source strip and compared pixel by pixel. The shape you approved stays the shape you get; what changes is only where outlines and shading land, which is exactly what the backbone decides.+> `SKILL.md` 허브에서 분리한 시나리오 상세. 픽셀아트 타깃, 지터 없는 locomotion, 게임-레디 청키 픽셀 출력이 필요할 때 이 문서를 따른다. 구현 내부(피치 검출·grid-snap·팔레트 단계별 코드 동작)는 [`architecture.md`](architecture.md) §6 참조.## `fit` objectdiff --git a/docs/qa-motion.md b/docs/qa-motion.mdindex 7be8394..7e46a5f 100644--- a/docs/qa-motion.md+++ b/docs/qa-motion.md@@ -1,5 +1,7 @@# Motion Continuity QA (BLOCKING) — sprite-gen reference+> Owns: Motion Continuity — the blocking judgement of a row as motion · Index: [docs/README.md](README.md)+> `SKILL.md` 허브에서 분리한 시나리오 상세. 추출·아틀라스 QA 를 통과한 행을 **모션으로서** 판정할 때 이 문서를 따른다. Motion Continuity 는 BLOCKING 이다 — 판정 기준 전체가 여기 있다.Static identity QA is not enough. A row can have the right frame count, clean alpha, and consistent identity and still animate as garbage. Review motion **as motion**:diff --git a/docs/recolor.md b/docs/recolor.mdindex 5899d8b..cb20717 100644--- a/docs/recolor.md+++ b/docs/recolor.md@@ -1,5 +1,7 @@# Recolor — deterministic palette-swap bake + colourway pick — sprite-gen reference+> Owns: Deterministic palette-swap bake, colourway pick, `variants/` and its report · Index: [docs/README.md](README.md)+> Split out of the `SKILL.md` hub. Follow this doc when you need to bake N colour> variants of one base sheet from a palette map, or when the curation webview is> comparing and adopting those baked colourways. Implementation:diff --git a/docs/rename-gate.md b/docs/rename-gate.mdindex bbbefb4..e558124 100644--- a/docs/rename-gate.md+++ b/docs/rename-gate.md@@ -1,5 +1,7 @@# 리네임 게이트 — 어휘/키를 바꿀 때 (BLOCKING)+> Owns: What must move together when a vocabulary word or key is renamed · Index: [docs/README.md](README.md)+> SKILL.md 허브에서 옮겨온 계약 본문(2026-09-09, 허브 슬림화). 허브는 이 페이지를 가리키기만 한다.스키마 키·식별자·라벨을 걸쳐 어휘를 바꾸는 작업(`pixel_perfect` → `pixel_unfake` 류)은@@ -26,3 +28,7 @@- [ ] **은퇴 이름은 조용한 별칭으로 남기지 않는다.** 새 이름을 안내하며 hard error. 그 안내문구 자체는 치환 대상에서 제외한다.- [ ] **순수 리네임 주장은 골든 회귀로 증명한다.** 리네임 전/후 산출물이 바이트 동일한지.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/run-contract.md b/docs/run-contract.mdindex f5093cc..5501a49 100644--- a/docs/run-contract.md+++ b/docs/run-contract.md@@ -1,5 +1,7 @@# Run Contract — pipeline stages · run-dir folder tree · curation-view display (SSoT)+> Owns: The atlas pipeline's normative contract: stages, the run-dir folder tree, curation-view display, atomic extract, concurrency scope · Index: [docs/README.md](README.md)+> Status: **contract** (normative). This doc is the single source of truth for> three things every sprite-gen run must satisfy so that **any agent who serves a> view gets the same experience** — the base reference row, the per-state@@ -16,6 +18,19 @@> If the three ever disagree: behavior → SKILL.md wins; structure/display → this> doc wins; architecture.md is the bug.+## Contents++- [1. Pipeline stages](#1-pipeline-stages)+- [2. Run-dir folder contract](#2-run-dir-folder-contract)+- [2-b-2. Reading a run never writes to it](#2-b-2-reading-a-run-never-writes-to-it)+- [2-c. External consumers install from `curated/`, never from `frames/`](#2-c-external-consumers-install-from-curated-never-from-frames)+- [3. Curation-view display contract](#3-curation-view-display-contract)+- [4. Import-run source rule (`--pngs-dir`)](#4-import-run-source-rule---pngs-dir)+- [5. Conformance status](#5-conformance-status)+- [6. Failed extract is atomic — no partial generation in `frames/`](#6-failed-extract-is-atomic-no-partial-generation-in-frames)+- [7. Guarantee boundary — atomicity & concurrency (honest scope)](#7-guarantee-boundary-atomicity-concurrency-honest-scope)+- [Related](#related)+## 1. Pipeline stagesOne image-gen call **per state row** is the only AI step; every stage after it isdiff --git a/docs/seamless-video-loop.md b/docs/seamless-video-loop.mdindex bae2634..3879ea3 100644--- a/docs/seamless-video-loop.md+++ b/docs/seamless-video-loop.md@@ -1,5 +1,7 @@# Seamless Video Loop (ambient clip → infinite loop)+> Owns: Making a non-looping ambient clip loop forever (RIFE seam bridge) — a different job from pipeline B · Index: [docs/README.md](README.md)+Turn a **non-looping AI-generated ambient video clip** (an `sprite-gen gen` video, aSeedance/Veo/Kling i2v clip, a title/hero backdrop) into a clip that loops **forever withno visible seam** — for a title-screen background, a hero loop, a store-page ambient shot.@@ -99,3 +101,7 @@ A single still cannot tell a playing loop from a paused first frame. Judge numerFor a game/app, ship the looped clips as the player's native codec and let the player loop(Unity `VideoPlayer.isLooping = true`, HTML `<video loop>`). Because the seam is alreadyseamless in the file, the engine's plain loop needs no crossfade.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/sheet-slicing.md b/docs/sheet-slicing.mdindex 4e40937..258c25c 100644--- a/docs/sheet-slicing.md+++ b/docs/sheet-slicing.md@@ -1,5 +1,7 @@# Sheet Slicing — multi-figure grid sheets to per-cell standing cuts (tachi-e)+> Owns: Multi-figure grid sheets to per-cell standing cuts; the `cutout` routes · Index: [docs/README.md](README.md)+`slice_sheet_cells.py` (= `sprite_gen.cli slice-sheet`) turns ONE generatedimage containing a COLSxROWS grid of the same character (expressions, poses,outfits) into per-cell RGBA cuts on a fixed canvas with a shared feet@@ -91,3 +93,7 @@ feet line across cells, the flat chroma background, and no grid lines,labels, or numbers. Two-arm/anatomy constraints belong in the prompt too:the slicer cannot repair a three-armed generation, only regeneration fixesbad drawing (same doctrine as the row pipeline).++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/states-and-frames.md b/docs/states-and-frames.mdindex aaea642..83386ef 100644--- a/docs/states-and-frames.md+++ b/docs/states-and-frames.md@@ -1,5 +1,7 @@# States & Frame Counts — sprite-gen reference+> Owns: Which states to request and how many frames each · Index: [docs/README.md](README.md)+> `SKILL.md` 허브에서 분리한 시나리오 상세. 요청할 상태(state) 목록과 프레임 수를 정할 때 이 문서를 따른다.## Simple MVP Scopediff --git a/docs/subject-profiles.md b/docs/subject-profiles.mdindex 18070b7..b729a6d 100644--- a/docs/subject-profiles.md+++ b/docs/subject-profiles.md@@ -1,5 +1,7 @@# Subject profiles - character vs effect+> Owns: `character` vs `effect` subjects and the sparse-frame floor they set · Index: [docs/README.md](README.md)+The sparse-frame floor (`--min-used-pixels`) catches empty frames and extraction debris. The right floor depends on what a run draws and on its cell geometry. A character normally fills more of its cell than a spell spark, while users may choose any resolution, so neither profile owns one absolute pixel constant.```jsonc@@ -63,3 +65,7 @@ These public examples were generated through `prepare --subject effect`, `gen`,- Use `--min-used-pixels` only for a deliberate outlier below the derived profile floor.- Keep chroma-key hues far from wispy or translucent effect colors so unmixing does not erase the subject into the debris band.- Do not lower a global floor for every run. That would disable the debris guard for unrelated subjects.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex 6b5ed58..8e88af2 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -1,5 +1,7 @@# Troubleshooting+> Owns: Symptoms of a pipeline that is "quietly wrong", with causes and fixes · Index: [docs/README.md](README.md)+파이프라인이 "조용히 이상한" 대표 증상들과 원인·대처. 전부 회귀에서 도출.(엔진은 특정 오케스트레이터를 모른다 — 여기의 규칙은 어떤 에이전트 환경에서든 성립.)@@ -52,3 +54,7 @@- **원인**: WebM/MP4 조립은 서버 머신의 `ffmpeg` 를 쓴다 — 없으면 관측 가능한500(`ffmpeg not found`)을 준다. GIF 는 ffmpeg 없이 동작.- **대처**: 서버 머신에 ffmpeg 설치 (`brew install ffmpeg` 등).++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex 81121a9..b071c9f 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -1,5 +1,7 @@# Video → sprite pipeline (engine SSoT)+> Owns: Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, the batch · Index: [docs/README.md](README.md)+One still becomes a whole motion set: the still is padded into the canvas a stateneeds, Grok Imagine animates it in place, the clip is keyed frame by frame, and oneseamless cycle is cut out as a strip, a transparent GIF and a WebP — every stage@@ -109,8 +111,9 @@ Outputs:- `cycle/frame-NNN.png` — the cycle frames, RGB under alpha 0 scrubbed, detached specksbelow 1 % of the body erased.- `<name>.strip.png` + `<name>.strip.json` — a horizontal strip (union-cropped, **no bottom- pad** so feet meet the floor, bottom-aligned, ≤ 64 cells because Chrome caps image- dimensions near 32 767 px, ≤ 520 px tall) with `frames · w · h · body_h · delay_ms ·+ pad** so feet meet the floor, bottom-aligned, ≤ 64 cells **and ≤ 32 000 px wide** because+ Chrome refuses images near 32 767 px — the cap is on pixels, so a 650 px cell allows 49+ cells and the meta says `subsampled`; ≤ 520 px tall) with `frames · w · h · body_h · delay_ms ·cycle_frames · cycle_seconds`. `body_h` is the standing body height (median per-framebbox height): scale a jump strip — whose cells include air room — by `body_h`, not `h`,and it reads the same size as a walk strip. `delay_ms = cycle_seconds / frames`, so a@@ -143,3 +146,7 @@ bounce was faster than any gait) and the assumption that an action state repeatsquadruped jumped once). Everything else held unchanged, and the original biped setstill resolves to the same periods afterwards. The subjects are not in this repository;the synthetic fixtures under `tests/video/` pin every rule named here.++## Related++- [docs/README.md](README.md) — documentation indexdiff --git a/docs/video.md b/docs/video.mdindex 5d922fa..e29b3cc 100644--- a/docs/video.md+++ b/docs/video.md@@ -1,5 +1,7 @@# `sprite-gen video` — image to video with your own Grok login (engine SSoT)+> Owns: `sprite-gen video`: image to mp4 through Grok Imagine with the user's own credential · Index: [docs/README.md](README.md)+`sprite-gen video` animates one still into a short mp4 through **Grok Imagine**(xAI `POST /v1/videos/generations`). It is the video counterpart of[`sprite-gen gen`](gen.md): one call = one still (+ prompt) → one **verified** mp4@@ -94,3 +96,7 @@ never printed or written** — only the download host (`vidgen.x.ai`).- Output is whatever the model returns (typically H.264 mp4 with audio unless`--no-audio`). Downstream frame extraction is a separate step and not part ofthis command.++## Related++- [docs/README.md](README.md) — documentation index