pixelkiln 0.68.0 → 0.69.0

package/docs/AGENTS.md

@@ -67,7 +67,7 @@ not a replacement:
 | PixelLab MCP | Agent-facing access to PixelLab generation capabilities. |
 | PixelKiln skill | Agent guidance for safe project-level operations. |
 | PixelKiln library/CLI | Budgets, state, provenance, review, recovery, audit, and packaging. |
-| PixelLab adapter | The current production and live-tested generation backend: stills, tiles, and the character family (four engines, states, loops, mirrors, adoption). |
+| PixelLab adapter | The current production and live-tested generation backend: stills, tiles, UI panels and elements, `objectPro` objects, controlled revisions, and the character family (four engines, states, loops, mirrors, portraits, outfits, adoption). |
 | Retro Diffusion adapter | Experimental backend; authenticated paid single-still lifecycle plus mocked advanced-workflow tests. |
 | ComfyUI adapter | Experimental self-hosted still, controlled-revision, and atomic frame-set backend; PixelKiln automates lineage and mechanical quality checks while a person retains visual approval. |
 | Scenario adapter | Experimental hosted still-image backend; BFL Flux 2 Dev quote, paid single/two-output generation, human review, and durable recovery live-tested. |

package/docs/CHARACTERS.md

@@ -264,7 +264,10 @@ Characters that already exist on the account come under the manifest with
 PixelLab's own tools shows both) and run `pixelkiln adopt`: it records the
 character, writes every direction and frame that is not on disk, and costs
 nothing. A base can also be matched by the bytes of its south-facing file.
-See [`adopt`](CLI.md#adopt).
+See [`adopt`](CLI.md#adopt). Characters no lockfile claims go through
+`pixelkiln salvage`, one card per base with its states and loops, and a
+character tagged for discard is deleted by `pixelkiln purge`; see
+[Recovery](RECOVERY.md#characters).
 
 ## Mirrors
 

package/docs/CLI.md

@@ -4,9 +4,11 @@
 pixelkiln <command> [options]
 ```
 
-Unknown commands, positional arguments, and flags are errors. Repeated
-`--style`, `--only`, `--claims`, and `--output-role` values accumulate; comma-
-separated values work too. This strict parsing prevents a misspelled filter
+Unknown commands, positional arguments, and flags are errors. The only
+positional words accepted are a command's own subcommands (`refine approve`,
+`workspace add <manifest>`, and the like), `estimate-skeleton`'s one image
+path, and `skeleton-preview`'s keypoints file or asset id. Repeated `--style`, `--only`, `--claims`, and `--output-role` values
+accumulate; comma-separated values work too. This strict parsing prevents a misspelled filter
 from widening a paid run.
 
 The manifest's top-level `provider` is the default; each style may select a
@@ -27,6 +29,8 @@ Which command:
 | draw a character in 8 directions, then its poses and loops | a `character` style with `state` and `animation` assets; one `pixelkiln gen` runs the waves |
 | rotate your own sprite into 8 directions | `"reference": "refs/bot-south.png"` on the base; `mode: pro-flash` does it for 1 generation at 64px |
 | get the east-facing loop without paying for it | `"bot.walk.east": { "mirror": "bot.walk.west" }` |
+| declare one loop for several directions, mirroring the rest | `"animation": { "of": "bot", "directions": ["south", "west", "north"] }`; `--only bot.walk` selects the whole family |
+| make a bust portrait, or re-clothe a loop from an outfit image | `"portrait": { "of": "mira", "size": 64 }`, `"outfit": { "of": "mira.walk", "reference": "refs/armor.png" }` |
 | generate one asset, or one style | `pixelkiln gen --only anvil --budget 2`, `pixelkiln gen --style neon --budget 20` |
 | finish a run that was interrupted | `pixelkiln plan`, then the `next:` command it prints (`poll`, `pick`, or `fetch`) |
 | choose among candidates the provider returned | `pixelkiln pick` |
@@ -48,6 +52,10 @@ Which command:
 | drop lock entries the manifest no longer declares | `pixelkiln prune` |
 | check the project before committing or in CI | `pixelkiln doctor`, `pixelkiln plan --check` |
 | see the account balance | `pixelkiln balance` |
+| shrink upscaled outside art to its native grid before using it as a reference | `pixelkiln unzoom --from refs/knight-512.png --out refs/knight.png` |
+| generate a pixel font (`.ttf` plus glyph atlas) | `pixelkiln font --description "warm orange arcade font" --out fonts/arcade` |
+| start an `animate-skeleton` keypoints file from an image | `pixelkiln estimate-skeleton poses/hero.png --out poses/hero-swing.json` |
+| see a keypoints file's poses over the source before paying | `pixelkiln skeleton-preview hero-swing` |
 | work across several projects | `pixelkiln workspace add ../other/pixelkiln.manifest.json`, then `--workspace` on `gallery` and `salvage` |
 
 Every command takes `--manifest <file>` when the manifest is not in the
@@ -344,23 +352,6 @@ Show one provider's remaining balance and cost unit. A mixed manifest requires
 `--provider`; a single-provider manifest infers it. Reports a capability error
 when an installed provider, such as local ComfyUI, has no balance endpoint.
 
-### `estimate-skeleton`
-
-```bash
-pixelkiln estimate-skeleton <image> [--out keypoints.json]
-```
-
-PixelLab only. Derives an 18-joint skeleton from an image via
-`/estimate-skeleton` and prints the keypoints JSON, or writes it with `--out`.
-Same category as `balance`: a direct, un-budgeted account call outside the
-manifest/plan/lock pipeline — no manifest is read beyond locating
-`.env.local`, and nothing is written to a lockfile. This is how to bootstrap
-an `animate-skeleton` revision's `keypointsFile` (see
-[Controlled asset revisions](./REVISIONS.md#skeleton-driven-animation)):
-estimate once, sanity-check the result, hand-tweak a few joints for
-in-between frames, rather than hand-authoring 18 joints of
-`{label, x, y, z_index}` from scratch.
-
 ### `status`
 
 Summarize lock entries by state and successful submission spend by cost unit.
@@ -882,10 +873,11 @@ See [derived artifacts](./ARTIFACTS.md) and [tiles](./TILES.md).
 
 ## PixelLab utilities
 
-Two commands call PixelLab on loose files rather than manifest assets. Neither
-reads the manifest or touches the lockfile; both load `PIXELLAB_API_KEY` from
-the environment or a `.env.local`/`.env` beside `--manifest` or in the working
-directory, the same as every other command.
+Three commands call PixelLab on loose files rather than manifest assets. None
+reads the manifest or touches the lockfile; all three load `PIXELLAB_API_KEY`
+from the environment or a `.env.local`/`.env` beside `--manifest` or in the
+working directory, the same as every other command. A fourth,
+`skeleton-preview`, is their local companion and calls nothing.
 
 ### `unzoom`
 
@@ -936,6 +928,48 @@ A font is deliberately not a manifest generator: it has no style suffix to
 share, no prompt-per-asset, no candidates to pick, and its main output is not
 an image, so there is nothing for the lockfile's provenance model to hold.
 
+### `estimate-skeleton`
+
+```bash
+pixelkiln estimate-skeleton <image> [--out keypoints.json] [--frames 4] [--force]
+```
+
+PixelLab only. Derives an 18-joint skeleton from an image via
+`/estimate-skeleton`. The image must be square at 16, 32, 64, 128, or 256
+pixels, the sizes the endpoint takes; anything else is refused before the
+call. Same category as `balance`: a direct, un-budgeted account call outside
+the manifest/plan/lock pipeline — no manifest is read beyond locating
+`.env.local`, and nothing is written to a lockfile.
+
+The output is a whole keypoints file, the shape an `animate-skeleton`
+revision's `keypointsFile` must be (see
+[Controlled asset revisions](./REVISIONS.md#skeleton-driven-animation)): the
+estimated pose as `firstFrameKeypoints`, and `--frames` copies of it (3–15,
+default 4) as the frames to move into the motion. It prints, or writes to
+`--out`; `--out` refuses to replace an existing file, which is usually hand
+edits, unless `--force` is given.
+
+### `skeleton-preview`
+
+```bash
+pixelkiln skeleton-preview <keypoints.json> [--from image.png] [--out sheet.png]
+pixelkiln skeleton-preview <asset> [--style <id>] [--out sheet.png]
+```
+
+Draws every pose of a keypoints file over its source image as one PNG, the
+starting pose first at full strength and each frame after it over a dimmed
+copy. Right-side bones are orange, left-side blue, the head and spine white.
+Local and free: nothing is sent anywhere. Given an `animate-skeleton` asset
+id, it reads the revision's `keypointsFile` and source image from the
+manifest; given a file, `--from` names the image (without one, poses are drawn
+on a plain ground). The sheet is written beside the keypoints file as
+`<name>.preview.png` unless `--out` says otherwise. A file that does not parse
+fails with the same message `plan` would give.
+
+Use it after `estimate-skeleton` and after every hand edit: PixelKiln cannot
+check that the starting pose matches what the image shows, and a mismatch
+degrades every generated frame without an error.
+
 ## Utility commands
 
 ### `help`
@@ -951,9 +985,10 @@ Print the package version. `-v` is an alias.
 | Option | Applies to | Meaning |
 |---|---|---|
 | `--manifest <path>` | manifest commands | Manifest path; defaults to `pixelkiln.manifest.json`. |
+| `--frames <n>` | `estimate-skeleton` | Frames to scaffold after the estimated pose, 3–15; default 4. |
 | `--lock <path>` | manifest commands | Lock path; defaults beside the manifest. |
 | `--style a,b` | most workflows | Restrict styles; repeatable. |
-| `--only id1,id2` | most workflows | Restrict asset ids; repeatable. |
+| `--only id1,id2` | most workflows | Restrict asset ids; repeatable. An `animation.directions` shorthand id selects every loop and mirror it expands into. |
 | `--budget <n\|provider=n>` | submit/gen/gallery | Refuse work above this cost. Repeat `provider=n` for every provider in a mixed run; do not mix keyed and unkeyed forms. For `gallery`, the session ceiling that enables generation from the page. |
 | `--force` | gen/fetch/derived commands/recipe install/quality snapshot | Regenerate current work, replace a changed or untracked fetch destination, rebuild current quality-profile output, take ownership of modified/unowned derived output, replace changed recipe files, or replace a changed quality baseline. A refinement rebuild resets approval. |
 | `--dry-run` | supported mutating commands | Inspect without spending or mutating provider state. |

package/docs/GENERATORS.md

@@ -12,9 +12,13 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 | Exact fixed palette | `pixflux` | 1 generation | 1 inline image |
 | Candidate variety, richer rendering, future rotation/animation | `1dir` | 20–40 generations | 4–64 by size |
 | Ground tiles or connectable structural sets | `tiles` | 20–40 generations | variations or complete set |
+| Two-terrain Wang tileset for elevation (grass to water, floor to cliff) | `terrain` | 20–40 generations (unmeasured) | 16 or 25 tiles |
 | A single elevation tile — a raised mesa, a cliff block | `isometricTile` | 1 generation | 1 |
+| Larger or non-square scene or background, up to 792 wide and 688 tall | `imagePro` | 40 generations flat | 1–64 by size |
 | Controlled pose/expression sequence in ComfyUI | `frames` | 0 `free` provider units | one atomic ordered set |
-| A character facing 4 or 8 directions, its poses, and its animations | `character` | 1 per base (standard), 20–40 per pose, 1 per template loop | one set of directions, or one ordered loop |
+| Animated GIF or spritesheet from Retro Diffusion | `animation` | $0.07–$0.25 per animation (published price) | 1 GIF or PNG sheet |
+| A character facing 4 or 8 directions, its poses, and its animations | `character` | 1 per base (standard), 20–40 per pose or portrait, 1 per template loop, 20 per outfit (measured once) | one set of directions, one ordered loop, or one portrait |
+| A prop, creature, or vehicle with rotations, states, or loops but no character rig | `objectPro` | about 6 per base at 64px (unmeasured) | one set of directions, or one ordered loop |
 | UI chrome — panels, buttons, health bars, toolbars | `uiAsset` | 20 generations (measured once, at 256x192) | 1 composited image |
 | One UI element from a description, 16px and up, optionally guided by a concept image | `uiElement` | 20–40 generations (unmeasured) | 1 image |
 | A styled still on the Pro Flash model, or the south sprite a Pro Flash character will rotate | `imageProFlash` | 5–9 generations (PixelLab's provisional quote) | 1 image |
@@ -22,6 +26,11 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 Start with `map` unless a required capability points elsewhere. Forty `map`
 re-rolls cost the same as one 64×64 `1dir` call.
 
+`terrain` and `imagePro` have no section below: their fields and limits are in
+the [PixelLab skill reference](../skills/pixelkiln/references/pixellab.md), and
+a `terrain` set's export shape is in [Tiles](./TILES.md). Retro Diffusion
+`animation` styles are in [Set up Retro Diffusion](./RETRO_DIFFUSION.md).
+
 ## `map`
 
 `map` calls PixelLab's map-object endpoint. It is purpose-built for isolated

package/docs/MANIFEST.md

@@ -56,7 +56,7 @@ not merely a label edit.
 
 | Field | Type/default | Meaning |
 |---|---|---|
-| `prompt` | string, required unless `mirror` | The subject wording wrapped by the selected style's prompt prefix and suffix. |
+| `prompt` | string, required unless `mirror`, `portrait`, or `outfit` | The subject wording wrapped by the selected style's prompt prefix and suffix. |
 | `width` / `height` | integer 16–8192 | Per-asset dimensions for generators that accept rectangular output. Provider limits may be lower. |
 | `size` | integer 16–8192 | Per-asset square size where the generator uses one dimension. |
 | `file` | string | Output path below the style's `outDir`; defaults to `<category>/<assetId>.png`. |
@@ -64,9 +64,11 @@ not merely a label edit.
 | `source` | string | Manifest-relative committed art used instead of generation. For a set of PNG outputs (a `frames` animation, a `tiles` set) a path that is not a file is the stem of a hand edit laid beside the generated members (`<stem>-<role>.png` each); the set still generates. Mutually exclusive with `revision`. |
 | `sourceByStyle` | object | Per-style `source`, keyed by style id; wins over `source` for that style. Written by `pixelkiln edit` for a hand edit of an asset that is in several styles. |
 | `remoteId` | string | The provider's own id for art that already exists on the account, so `adopt` maps it without matching bytes: an object id, a character id, or `<character id>#<animation group id>`. Not part of the spec's identity. |
-| `revision` | object | Controlled image-to-image or inpaint dependency. See [controlled revisions](REVISIONS.md). |
+| `revision` | object | Controlled dependency on another asset: `image-to-image`, `inpaint`, or `outpaint`; on PixelLab also `reduce-colors`, `correct-pixelart`, the animate modes (`animate`, `animate-pixminimax`, `animate-skeleton`), `interpolate`, and `edit-animation`. `engine: "pro-flash"` selects PixelLab's Pro Flash tier for `image-to-image`/`inpaint`. See [controlled revisions](REVISIONS.md). |
 | `state` | object | `character` styles: a pose or outfit of another character asset. See [Characters](./CHARACTERS.md). |
 | `animation` | object | `character` styles: a loop of another character asset in one direction. `directions` (a list, instead of `direction`) declares the loop for several directions at once and fills the unnamed flips with mirrors; see [One loop, several directions](./CHARACTERS.md#one-loop-several-directions). |
+| `portrait` | object | `character` styles: a bust of a base or state's south sprite, `{ "of": "<asset>", "size": 64 }`; `size` is 16, 32, 48, 64 (default), 128, or 160. See [Portraits](./CHARACTERS.md#portraits). |
+| `outfit` | object | `character` styles: an existing loop's frames re-clothed from an outfit image, `{ "of": "<loop asset>", "reference": "<image>" }`, with optional `additionalInstructions`. See [Outfit transfer](./CHARACTERS.md#outfit-transfer). |
 | `mirror` | string | Another asset of the same style flipped left to right, made locally at no cost. See [Mirrors](./CHARACTERS.md#mirrors). |
 | `scene` | object | `map` styles, PixelLab only: draw this object into a scene image, in its style. `{ "image": "scene.png", "placement": { "oval": 0.3 } }`; `placement` is `oval` or `rectangle` (a fraction, 0.05–0.95) or `mask` (a PNG the size of the scene). See [Drawing into a scene](./GENERATORS.md#drawing-into-a-scene). |
 | `batch` | object | `1dir` styles: rides along on another `1dir` asset's `item_descriptions` submission instead of generating on its own — `{ "of": "<leader asset id>", "index": <1-based slot> }`. See [`1dir`](./GENERATORS.md#1dir). |

package/docs/PIXELLAB.md

@@ -71,6 +71,14 @@ unapproved files. See [Manifest quality profiles](./MANIFEST.md#quality-profiles
 | `pixflux` | You need a closed palette or a full-bleed background | 1 generation |
 | `1dir` | You need references or several candidates for human review | 20 to 40 generations |
 | `tiles` | You need ground variations or a connected structural set | 20 to 40 generations |
+| `terrain` | You need a two-terrain Wang tileset (grass to water, floor to cliff) | 20 to 40 generations (unmeasured) |
+| `isometricTile` | You need one standalone isometric tile, 16 to 64px | 1 generation (measured once) |
+| `imagePro` | You need a larger or non-square scene, up to 792 wide and 688 tall | 40 generations |
+| `imageProFlash` | You need a still on the Pro Flash model, optionally styled from one image, 16 to 256px | 5 to 9 generations (provisional quote) |
+| `character` | You need a character in 4 or 8 directions, with states, loops, portraits, or outfits | See [Characters](./CHARACTERS.md) |
+| `objectPro` | You need a prop or creature with rotations, states, or loops but no character rig | about 6 at 64px (unmeasured) |
+| `uiAsset` | You need a UI panel composited from pieces and named elements, 192px and up | 20 generations (measured once) |
+| `uiElement` | You need one UI element from a description, 16px and up | 20 to 40 generations (unmeasured) |
 
 `map` accepts these values:
 
@@ -123,9 +131,9 @@ recorded, and records the new URLs. A refreshed base makes its states and
 animations stale, because their identity hashes the base's south file;
 `pixelkiln gen` regenerates them.
 
-## Three ways to drive PixelLab, and why this one
+## Four ways to drive PixelLab, and why this one
 
-PixelLab is reachable three ways, and it is easy to conflate them when
+PixelLab is reachable four ways, and it is easy to conflate them when
 comparing notes with someone using a different one:
 
 - **PixelLab's Game Builder**, a hosted web IDE with its own chat agent and a
@@ -167,7 +175,10 @@ reference image frame-by-frame from a supplied keypoint skeleton, not a text
 description) are the `revision` asset shape, not the `character` generator;
 see [Controlled asset revisions](./REVISIONS.md). The same revision shape
 animates, interpolates, recolors, and cleans up any asset, a whole character
-or loop at once where the endpoint takes a set. Object Creator is the
+or loop at once where the endpoint takes a set; `pixelkiln estimate-skeleton`
+starts a skeleton file from an image. Pro Flash stills are the
+`imageProFlash` generator, and Pro Flash edit and inpaint are a revision's
+`"engine": "pro-flash"`. Object Creator is the
 `objectPro` generator, UI panels and elements are `uiAsset` and `uiElement`,
 and fonts and unzooming reference art are the standalone `pixelkiln font` and
 `pixelkiln unzoom` commands. Map Workshop

package/docs/README.md

@@ -22,10 +22,10 @@ provider you are using. These Markdown files also render at
 
 | Guide | Use it for |
 |---|---|
-| [Characters](./CHARACTERS.md) | A base in 4 or 8 directions from a prompt or your own sprite, states, loops, mirrors, the four PixelLab engines, and what each costs. |
+| [Characters](./CHARACTERS.md) | A base in 4 or 8 directions from a prompt or your own sprite, states, loops, mirrors, portraits, outfit transfer, the four PixelLab engines, and what each costs. |
 | [Generators](./GENERATORS.md) | Choose between still, tile, character, hosted animation, and ComfyUI frame-set workflows. |
 | [Environment provider benchmark](./PROVIDER_BENCHMARK.md) | Compare PixelLab, Retro Diffusion, and ComfyUI on buildings, backgrounds, cleanup, and native-grid recovery. |
-| [Controlled asset revisions](./REVISIONS.md) | Use image-to-image/inpaint parents, masks, approval gates, side-by-side review, and ComfyUI bindings. |
+| [Controlled asset revisions](./REVISIONS.md) | Image-to-image and inpaint edits, PixelLab palette cleanup, animation, skeleton posing, and interpolation from a parent asset; masks, approval gates, side-by-side review, and ComfyUI bindings. |
 | [Derived artifacts](./ARTIFACTS.md) | Refine, pack, mount, and export; provenance, approval gates, ownership, and crash recovery. |
 | [Recovery and account safety](./RECOVERY.md) | Restore, caches, adopt, salvage, cross-project claims, tagging, and confirmed purge. |
 | [Quality gates](./QUALITY.md) | Manifest quality profiles, image baselines, human review, audit, cache, and CI usage. |

package/docs/REVISIONS.md

@@ -344,10 +344,16 @@ inline pixels. It must match the shape `src/skeleton.ts`'s `SkeletonSetSchema`
 validates: `{"firstFrameKeypoints": [...18 joints], "frames": [[...18
 joints], ...3 to 15 of them]}`, each joint `{"label": "RIGHT KNEE", "x": 0.52,
 "y": 0.71, "z_index": 9, "depth": 4}` (`depth` optional — PixelLab fills it
-from `skeletonTemplate`, default `mannequin`, when omitted). Bootstrap this
-file with `pixelkiln estimate-skeleton <image> --out poses/hero-swing.json`
-(see [CLI reference](./CLI.md#estimate-skeleton)) rather than hand-typing 18
-joints from scratch, then hand-tweak individual joints for in-between frames.
+from `skeletonTemplate`, default `mannequin`, when omitted). `label` is one
+of PixelLab's 18 joints (`NOSE`, `NECK`, `RIGHT`/`LEFT` `SHOULDER`, `ELBOW`,
+`ARM` for the wrist, `HIP`, `KNEE`, `LEG` for the ankle, `EYE`, `EAR`), each
+exactly once per pose; a misspelled or repeated joint fails when the manifest
+loads. Bootstrap this file with
+`pixelkiln estimate-skeleton <image> --out poses/hero-swing.json` (see
+[CLI reference](./CLI.md#estimate-skeleton)), which writes the estimated pose
+and four copies of it as frames, then move joints frame by frame. Check each
+edit with `pixelkiln skeleton-preview hero-swing`, which draws every pose
+over the source image, locally and for free.
 
 `direction` is **required** for this mode (unlike `animate-pixminimax`,
 where it is optional). `frames`/`fps`/`lastFrame`/`enhancePrompt` are all

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/skills/pixelkiln/SKILL.md

@@ -44,8 +44,8 @@ hashes.
 - When an asset declares `revision`, read the revision reference, require its
   parent gate to pass, and never bypass a `blocked` plan. Generate or approve
   the parent explicitly before re-planning the child.
-- A character `state`, `animation`, `mirror`, or pro `styleCharacter` is a
-  dependent asset the same way: one `pixelkiln gen` runs the waves in order
+- A character `state`, `animation`, `portrait`, `outfit`, `mirror`, or pro
+  `styleCharacter` is a dependent asset the same way: one `pixelkiln gen` runs the waves in order
   and stops when the budget cannot cover the next one. Before declaring the
   east-facing loop of a character, check whether a `mirror` of the west one
   does the job for nothing (an animation's `directions` list declares the
@@ -53,6 +53,10 @@ hashes.
   selects the whole family); before drawing a base from text, ask whether the
   user has a south-facing sprite to `reference` instead (1 generation on
   `pro-flash` at 64px). Mirrors swap handedness.
+- Before an outside or upscaled sprite becomes a `reference` or `styleImages`
+  path, run `pixelkiln unzoom --from <file> --out <file>` to bring it back to
+  its native pixel grid. Upscaled input degrades every PixelLab endpoint that
+  takes a reference, and the unzoomed result is opaque.
 - Treat every ComfyUI output as source material until it passes the native-grid,
   final-palette, prompt-coverage, and human 1× checks in the ComfyUI reference.
   A successful PNG or high-confidence grid result is not quality approval.
@@ -105,8 +109,10 @@ composition review and, for an isolated asset, background removal.
 
 Read only the reference needed for the current decision:
 
-- For PixelLab configuration, generators, costs, alpha behavior, or account
-  operations, read [references/pixellab.md](references/pixellab.md). For a
+- For PixelLab configuration, generators (including `uiElement` for single UI
+  pieces and `imageProFlash` for styled stills), costs, alpha behavior,
+  account operations, or the `unzoom`, `font`, `estimate-skeleton`, and
+  `skeleton-preview` utilities, read [references/pixellab.md](references/pixellab.md). For a
   PixelLab style aimed at a specific resolution or fidelity tier (retro,
   high-detail, or matching an existing set's look), read
   [references/pixellab-fidelity.md](references/pixellab-fidelity.md) first.

package/skills/pixelkiln/references/pixellab-roadmap.md

@@ -1,7 +1,8 @@
-# PixelLab surface this adapter does not cover
+# PixelLab coverage and remaining gaps
 
-A catalog of PixelLab capabilities confirmed absent from PixelKiln, built by
-reading all 29 tutorials on PixelLab's official YouTube channel (the original
+A catalog of PixelLab capabilities checked against PixelKiln: what this
+adapter now covers, and what is still absent. It was built by reading all 29
+tutorials on PixelLab's official YouTube channel (the original
 26 — the 12 featured on pixellab.ai plus 14 more from the channel's "PixelLab
 Tutorial" playlist, filtered to ~12 months back from that pass — plus 3 more
 published since: "Level Up Your Game: Custom Sprite Animation Tutorial,"
@@ -16,8 +17,8 @@ confirmed gap with real demand rather than a guess. Nothing here is a
 commitment to build it — it is what is missing, with the evidence for why it
 might matter, so that decision can be made deliberately.
 
-Each entry names the PixelLab tool, why pixelkiln doesn't have it today, and
-which tutorial(s) demonstrated real (not hypothetical) demand for it.
+Each open entry names the PixelLab tool, why pixelkiln doesn't have it today,
+and which tutorial(s) demonstrated real (not hypothetical) demand for it.
 
 ## Already closed since this catalog's research began
 
@@ -93,7 +94,7 @@ which tutorial(s) demonstrated real (not hypothetical) demand for it.
   formula, since the request bodies are near-identical minus `template_id` —
   a real assumption pending a live check, not a confirmed number the way
   `isometricTile`'s now is. Batch "pack" generation (N distinct objects from
-  one call) remains unmodeled — see above.
+  one call) is covered on `1dir` by its `batch` field — see below.
 - **Pixel correction** (`/correct-pixelart`, a dedicated cleanup pass distinct
   from `image-to-pixelart` — the latter is documented, docs/ENDPOINTS.md, as
   being "for photographs and 3-D renders, not for reprocessing" pixel art)
@@ -281,6 +282,50 @@ which tutorial(s) demonstrated real (not hypothetical) demand for it.
   Closed by `pixelkiln unzoom`, a standalone command on a loose file, since
   the art it is for comes from outside the manifest. Its result is opaque
   (transparency is composited onto white first). Cost unmeasured.
+- **Pro Flash for plain image create, edit, and inpaint** — a third image
+  tier, distinct from `pixflux`/`map`'s 1-generation endpoints and
+  `imagePro`'s flat-40 `generate-image-v2`, on the same model
+  `character`/`objectPro` already use for their `pro-flash` engine
+  (`gpt-image-2.5-flare`), confirmed against PixelLab's MCP tool schemas.
+  Demonstrated in "Pixel Art Animation Tutorial: Images Pro Flash, Skeleton
+  V3 & PixMiniMax": a styled character from a style image, re-edited
+  repeatedly ("give him a winter outfit," then a thicker one from *that*
+  result), then inpainted hair, shirt, and pants as separate masked passes.
+  Closed by the `imageProFlash` generator (`create`, one style image +
+  `styleTraits`, 16–256px in multiples of 4) and a revision's
+  `"engine": "pro-flash"`, which sends `image-to-image` to `edit` (text
+  method) and `inpaint` to `inpaint` (32–256px in multiples of 4, no
+  `strength`). A still's `source_image_id` is recorded and reused when a Pro
+  Flash character or object base's `reference` is that still's exact file
+  (issue #145). Shape, via `get_pro_flash_capabilities` (a free quote, not
+  billed):
+  - `create`: native 16×16 (experimental, always grid-corrected), 24×24,
+    32×32, 32×48, 64×64, 96×64, 96×96; custom (beta) 16–256 in steps of 4.
+    One output, no reference images.
+  - `edit`: native 32×32 up to 128×128, custom 32–256 step 4. Two
+    `edit_methods`: `"text"` or `"reference"` (one `reference_image` that
+    must fit the edit canvas natively). Canvas never grows.
+  - `inpaint`: same sizes as `edit`; a rectangle or a same-size mask PNG
+    (white = generate, black = preserve). Always crops to the mask.
+  - Cost quotes (provisional): `create` 5 at 32 and 64px, 9 at 256px;
+    `edit`/`inpaint` 5 at 64px, `inpaint` 6 at 128px; `character` and
+    `object` at 64px `image: 5, rotations: 1, total: 6`, matching
+    pixelkiln's measured `proFlashCharacterCost`. None billed live yet.
+
+  Still unmodeled: `edit`'s `"reference"` method, the
+  `use_color_palette_correction` flag (snap the edit back to the source's
+  palette), inpaint's three `output_methods` (`"New layer with changes"`,
+  `"Modify current layer, only changes"`, `"Modify current layer"`), and
+  `context_image` + a required `bounding_box`, which lets the model see up to
+  3× the native canvas of surrounding context — the problem
+  `docs/REVISIONS.md`'s "select a sub-region" workaround for `inpaint-v3`'s
+  512px ceiling solves by hand today.
+- **Portraits and outfit transfer** (`portrait-character-pro`,
+  `transfer-outfit-v2`) — closed as the `character` asset kinds `portrait`
+  (a bust of a base or state's south sprite) and `outfit` (an existing
+  loop's frames re-clothed from a reference image); see
+  `docs/CHARACTERS.md`. Both were live-measured: a 16px portrait billed 20,
+  a 2-frame 92×92 outfit transfer billed 20.
 - **`/create-8-direction-object`** is deliberately left unwrapped. `objectPro`
   already covers what it does (8 rotations from a prompt or a reference
   image, a `view`, a style image) on `/create-object-pro-flash` at roughly 6
@@ -288,76 +333,6 @@ which tutorial(s) demonstrated real (not hypothetical) demand for it.
   from an existing 8-direction object's sprites), is not worth a second,
   pricier engine on its own.
 
-## Pro Flash for plain image create, edit, and inpaint
-
-PixelLab ships a **third image-generation tier**, distinct from both
-pixelkiln's already-modeled ones — `pixflux`/`map`'s cheap 1-generation
-non-Pro endpoints, and `imagePro`'s Pro tier (`generate-image-v2`, flat 40
-generations) — confirmed directly against PixelLab's own MCP tool schemas
-(`create_image_pro_flash`, `edit_image_pro_flash`, `inpaint_image_pro_flash`,
-`get_pro_flash_capabilities`), not just a tutorial's framing, the same
-standard this catalog holds itself to elsewhere. It is the **same underlying
-model** `character`/`objectPro` already use for their `pro-flash` engine
-(`gpt-image-2.5-flare`, "medium" provider quality per
-`get_pro_flash_capabilities`), but exposed here for **plain images** — create,
-edit, and inpaint — with no character or object involved. Demonstrated at
-length in "Pixel Art Animation Tutorial: Images Pro Flash, Skeleton V3 &
-PixMiniMax": creating a styled character from a reference-image "style
-image," then repeatedly re-editing the same asset ("give him a winter
-outfit," then, from *that* result, "a thicker royal winter outfit with a
-bigger sword" — evolving the previous edit rather than restarting from the
-original each time), then inpainting new hair, a shirt, and pants as separate
-masked passes, each isolated onto its own layer.
-
-**Confirmed shape, via `get_pro_flash_capabilities` (a free, no-generation
-quote/identity lookup — not billed):**
-
-- **`create`**: native sizes 16×16 (experimental, always pixel-grid-corrected
-  by `image-to-pixel-art`'s own fixer), 24×24, 32×32, 32×48, 64×64, 96×64,
-  96×96; custom sizes (beta) 16–256 in steps of 4 on both sides. Takes a
-  `style_image` (URL/base64/owned image id) with `style_options`
-  (`color_palette`/`outline`/`detail`/`shading` toggles) — the same
-  style-copying mechanic as `character` pro-flash's `styleTraits`, just not
-  yet exposed for a plain image. One output, no reference images.
-- **`edit`**: native sizes 32×32 up to **128×128** (a larger ceiling than
-  `create`'s 96×96), custom 32–256 step 4. Two distinct `edit_methods`:
-  `"text"` (a description) or `"reference"` (a `reference_image`, max 1,
-  which must fit the edit canvas natively — no resizing). No style options.
-  Canvas never grows. An optional `use_color_palette_correction` flag snaps
-  the edited result back to the source's own palette.
-- **`inpaint`**: same size range as `edit`. Mask is a rectangle
-  (`mask_x`/`y`/`width`/`height`) or a same-size mask PNG, white = generate /
-  black = preserve / alpha ignored — the same convention `inpaint-v3` already
-  uses. Always crops to the mask. Three `output_methods`: `"New layer with
-  changes"`, `"Modify current layer, only changes"`, `"Modify current
-  layer"` — matching exactly what the tutorial's Aseprite/Pixelorama UI
-  offers, and a real choice the already-modeled `inpaint-v3` does not expose
-  at all today (pixelkiln's `inpaint` revision always gets one behavior). A
-  new, genuinely unmodeled mechanic: `context_image` + a required
-  `bounding_box` lets the model see up to **3×** the native canvas in either
-  dimension of surrounding context beyond the masked region itself — for
-  inpainting a sub-region of a larger scene coherently, the same problem
-  `docs/REVISIONS.md`'s existing "select a sub-region" workaround for
-  `inpaint-v3`'s 512px ceiling solves by hand today.
-- **Cost, from live (but not billed — `get_pro_flash_capabilities`'s quotes
-  are provisional) queries**: `create` 32×32 and 64×64 both quote 5
-  generations flat; 256×256 quotes 9. `edit`/`inpaint` at 64×64 quote 5;
-  `inpaint` at 128×128 quotes 6. `character` and `object` at 64×64 (8
-  directions) both quote `image: 5, rotations: 1, total: 6` — matching
-  pixelkiln's own already-measured `proFlashCharacterCost` (6 at 64px)
-  exactly, reassuring cross-validation of the quote endpoint even though it
-  is a quote, not a bill.
-
-**Now modeled, in part:** the `imageProFlash` generator wraps `create`
-(style image + `styleTraits`, 16–256px in multiples of 4), and a revision's
-`"engine": "pro-flash"` sends `image-to-image` to `edit` (text method) and
-`inpaint` to `inpaint`. A still's `source_image_id` is recorded and reused
-when a Pro Flash character or object base's `reference` is that still's exact
-file (issue #145). Still unmodeled: `edit`'s `"reference"` method, the
-`use_color_palette_correction` flag, inpaint's `output_method` choice and the
-`context_image` + `bounding_box` mechanism. Costs use the provisional quotes
-above; none has been billed live yet.
-
 ## Map Workshop (scene composition)
 
 PixelLab's actual scene-building surface: lay out a tile floor, place
@@ -418,7 +393,4 @@ result into a `SkeletonSetSchema` file) — worth scoping once the base
   product — "deploy your own agent," confirmed directly from the live tool
   schemas — unrelated to game-asset generation. Nothing to build here.
 - Lip-sync/vocal-animation/talking-gif are named as out of scope in
-  docs/PIXELLAB.md, with no in-flight work. Portraits (`portrait`) and outfit
-  transfer (`outfit`) are character asset kinds; see docs/CHARACTERS.md. They
-  were built and live-measured in September 2026 on a stacked branch that
-  never reached `main`, and were ported onto it later.
+  docs/PIXELLAB.md, with no in-flight work.

package/skills/pixelkiln/references/pixellab.md

@@ -12,7 +12,9 @@ providers, or before any PixelLab account operation.
 - Cost unit: subscription generations. Copy the exact `pixelkiln plan` total
   into `--budget`; do not translate it into dollars.
 - Account operations: balance, adopt, salvage, tag, and separately confirmed
-  purge are supported. Read `docs/RECOVERY.md` before using them.
+  purge are supported, for characters as well as objects (salvage reviews a
+  base with its states and loops as one group). Read `docs/RECOVERY.md`
+  before using them.
 
 ## Generator choice
 
@@ -24,7 +26,9 @@ providers, or before any PixelLab account operation.
 | `tiles` | Ground variations or connected structures | 20–40 generations |
 | `terrain` | A two-terrain Wang tileset for elevation (grass-to-water, floor-to-cliff) | Unmeasured; borrows the same 20–40 canvas tiers |
 | `imagePro` | A larger or non-square background/scene, or real style transfer | **40 generations flat**, any size |
-| `character` | A character in 4 or 8 directions, its poses (`state`), and its loops (`animation`) | 1 per standard base, 6 per pro-flash base at 64px (1 from a `reference`), 20–40 per pose, 1 per template loop per direction |
+| `character` | A character in 4 or 8 directions, its poses (`state`), its loops (`animation`), bust `portrait`s, and `outfit` transfers onto a loop | 1 per standard base, 6 per pro-flash base at 64px (1 from a `reference`), 20–40 per pose or portrait, 1 per template loop per direction, 20 per outfit (measured once) |
+| `objectPro` | A prop, creature, or vehicle that needs rotations, states, or loops but has no character rig | 6 per base at 64px (1 from a `reference`), **unmeasured**; assumed to match `character` pro-flash |
+| `isometricTile` | One standalone isometric tile (a raised mesa, a cliff block), 16–64px | **1 generation, measured once** (32px `block`) |
 | `uiAsset` | A UI panel, button, health bar, or other chrome, from precise `pieces` and/or named `elements` | **20 generations, measured once** (256×192); the borrowed canvas-tier estimate still predicts 40 |
 | `uiElement` | One UI element (button, slot, bar, dialogue box) from the prompt, 16px and up, with an optional concept image | 20–40 generations, **unmeasured** |
 | `imageProFlash` | A styled still on the Pro Flash model (style image + `styleTraits`), 16–256px in multiples of 4; also the natural source for a Pro Flash character's south sprite | 5–9 generations, PixelLab's provisional quote |
@@ -172,9 +176,9 @@ not independently measured** — `objectProCost()` assumes it prices
 identically to `character` pro-flash's own measured formula
 (`proFlashCharacterCost`), since the request bodies are near-identical minus
 `template_id`; treat it as a working assumption pending a live check.
-Batch "pack" generation (PixelLab's Object Creator can make N distinct
-objects from one call) and `objectPro`'s own place in `pixelkiln adopt` are
-not modeled yet. `pixelkiln gallery --edit` offers "+ New state" and
+`objectPro`'s own place in `pixelkiln adopt` is not modeled yet. (N distinct
+objects from one call, PixelLab's Object Creator "pack", is the `1dir`
+`batch` field above.) `pixelkiln gallery --edit` offers "+ New state" and
 "+ New animation" on a `character` or `objectPro` base/state's drawer, same
 family, same manifest-only write "+ New revision" does — it writes the
 `asset.state`/`asset.animation` fields above (minus `startFrame`/`endFrame`
@@ -444,12 +448,20 @@ the `direction` value. The same tutorial states outright that PixMiniMax
 "allows up to 40 frames," a second, independent (though still not
 live-billed) confirmation of the ceiling above.
 
-PixelLab ships a further image-generation tier beyond what this adapter
-models: "Pro Flash" for plain image create/edit/inpaint, the same
-`gpt-image-2.5-flare` model `character`/`objectPro` pro-flash already use,
-now exposed for images with no character or object involved — see
-[pixellab-roadmap.md](./pixellab-roadmap.md) for the confirmed shape and
-cost.
+Parts of Pro Flash image editing are still outside this adapter: `edit`'s
+reference-image method, palette correction, inpaint's output-method choice,
+and inpainting with surrounding `context_image`. See
+[pixellab-roadmap.md](./pixellab-roadmap.md) for the confirmed shape.
+
+Three commands call PixelLab on loose files, outside the manifest and
+lockfile. `pixelkiln unzoom --from <file> --out <file>` returns upscaled
+pixel art to its native grid; run it before outside art becomes a
+`reference` or `styleImages` entry (input at least 256×256, result opaque,
+cost unmeasured). `pixelkiln font --description <text> --out <base>` writes a
+`.ttf` and an 80-glyph atlas for PixelLab's documented 25 generations, and
+asks first. `pixelkiln estimate-skeleton <image> --out <file>` starts an
+`animate-skeleton` keypoints file, and `pixelkiln skeleton-preview <asset>`
+draws its poses over the source for free. See `docs/CLI.md`, "PixelLab utilities".
 
 For a style aimed at a specific look (a
 retro/console feel or a

package/skills/pixelkiln/references/revisions.md

@@ -12,6 +12,11 @@ Read this reference when an asset declares `revision`.
 - An inpaint mask must be a PNG and match the available parent dimensions.
 - Start image-to-image strength around `0.2`–`0.4`; explain that the exact
   effect belongs to the model and graph.
+- On PixelLab, `"engine": "pro-flash"` sends an `image-to-image` or `inpaint`
+  revision to the Pro Flash edit/inpaint endpoints instead of the Pro ones:
+  5 generations up to 96px, 6 up to 208px, 9 beyond (provisional quotes),
+  against 20–40. The parent must be 32–256px per side in multiples of 4, and
+  `strength` is refused. Other modes reject `engine`.
 - `reduce-colors` and `correct-pixelart` send no prompt to the provider — the
   asset's `prompt` stays a manifest-only label. `numColors`/`paletteImage`
   are mutually exclusive; a `paletteImage` has no size relationship to the
@@ -40,6 +45,19 @@ Read this reference when an asset declares `revision`.
   while cardinal ones in the same batch generate fine — suspect the enhanced
   prompt's wording, not the model, when only some directions of a
   multi-directional set come out wrong.
+- `animate-skeleton` (PixelLab, beta, tier 1+) poses the parent from a
+  committed `keypointsFile`: the parent's current pose plus 3–15 per-frame
+  poses. It needs `direction`; `prompt` names the motion and the optional
+  `description` says what the subject looks like. Bootstrap the file with
+  `pixelkiln estimate-skeleton <image> --out <file>` (a direct call, outside
+  any budget, like `balance`; square 16–256px images only), which writes the
+  estimated pose plus `--frames` copies (default 4) to edit. Joint labels are
+  PixelLab's 18 names, each once per pose. After every edit, run
+  `pixelkiln skeleton-preview <asset>` (local, free) and look at the sheet:
+  the starting pose must match the sprite, or every frame degrades silently. Plan cost
+  interpolates PixelLab's documented anchors (3 frames = 2, 8 = 3, 15 = 4);
+  like the other animate modes it lands in candidate review and is
+  unmeasured live.
 - `interpolate` needs `lastFrame` (the end keyframe; the parent is the
   start) and lets the model pick the frame count. Suggest it for motion one
   `animate` pass can't produce cleanly: build the key poses first as
@@ -53,8 +71,8 @@ Read this reference when an asset declares `revision`.
   `/reduce-colors`/`/correct-pixelart` endpoints synchronously (no background
   job); everything else in this file about the dependency gate, hashing, and
   candidate review applies identically regardless of provider. ComfyUI
-  cannot back `animate`, `animate-pixminimax`, `interpolate`, or
-  `edit-animation` at all (`supportsRevision` refuses them) — its revision
+  cannot back `animate`, `animate-pixminimax`, `animate-skeleton`,
+  `interpolate`, or `edit-animation` at all (`supportsRevision` refuses them) — its revision
   path always writes a single output image, and an animation is a frame
   set; that's a structural gap, not a missing binding.
 - A filtered child resolves its parents for safety but does not generate them.
@@ -67,8 +85,8 @@ Read this reference when an asset declares `revision`.
   from a parent's drawer ("+ New revision" under "Revisions from this
   asset"), once the parent has usable pixels; it does not offer `inpaint`
   (needs a mask upload), `outpaint`, `reduce-colors`, `correct-pixelart`,
-  `animate`, `animate-pixminimax`, `interpolate`, or `edit-animation` yet,
-  so add those by hand.
+  `animate`, `animate-pixminimax`, `animate-skeleton`, `interpolate`, or
+  `edit-animation` yet, so add those by hand.
 - Before an outside image becomes a `styleImages` or `reference` path,
   suggest `pixelkiln unzoom --from <file>`: upscaled pixel art (every art
   pixel a block of screen pixels) degrades every reference-taking PixelLab