pixelkiln 0.68.0 → 0.68.1

package/PROVIDERS.md

@@ -57,19 +57,20 @@ the providers offer directly.
 | Decision | PixelLab | Retro Diffusion |
 |---|---|---|
 | Best fit today | Existing PixelKiln projects, account reconciliation, and live-tested generation | Native pixel-art styles, USD budgets, animation, and alternate tileset workflows |
-| PixelKiln generators | `map`, `pixflux`, `1dir`, `tiles`, `character` | `map` and `pixflux` stills, `tiles`, `animation` |
-| Output | PNG stills, candidates, and structural tile members | PNG stills/tiles/spritesheets or animated GIF |
+| PixelKiln generators | `map`, `pixflux`, `1dir`, `imagePro`, `imageProFlash`, `tiles`, `terrain`, `isometricTile`, `character`, `objectPro`, `uiAsset`, `uiElement` | `map` and `pixflux` stills, `tiles`, `animation` |
+| Output | PNG stills, candidates, structural tile members, and ordered frame sets | PNG stills/tiles/spritesheets or animated GIF |
 | Candidate review | Yes; count varies by generator and size | Yes for 1–16 still candidates; animations and tilesets currently use one result |
-| References | `1dir` and tile style modes | Up to nine for supported RD Pro/user still styles; constrained inputs for animation and tiles |
+| References | `1dir` and tile style modes; a character or `objectPro` reference sprite; a `pro` character concept image; one `imageProFlash` style image; one `uiElement` concept image | Up to nine for supported RD Pro/user still styles; constrained inputs for animation and tiles |
 | Cost model | Subscription generations | Prepaid USD balance |
 | Cost safety | Offline estimate plus hard generation budget | Offline estimate, hard USD budget, then a free authoritative quote before submission |
 | Account lifecycle | Balance, list, adopt, salvage, tag, and confirmed purge | Balance only in the current adapter |
 | Live confidence | Full paid generation workflows exercised | RD Fast and RD Plus single-candidate stills exercised end to end; multi-candidate, tileset, GIF, and spritesheet runs pending |
 
 Choose PixelLab when mature account-object recovery and reconciliation matter,
-or when the measured one-generation `map`/`pixflux` routes fit the work. Choose
-Retro Diffusion when a native animation or spritesheet is required, an RD style
-is the desired look, or a USD quote is easier to budget. For a production batch,
+when the measured one-generation `map`/`pixflux` routes fit the work, or when an
+animation belongs to a character, an object, or an existing image. Choose
+Retro Diffusion when a GIF or spritesheet from one prompt fits, an RD style is
+the desired look, or a USD quote is easier to budget. For a production batch,
 run one representative asset through the selected provider before expanding the
 scope.
 
@@ -96,9 +97,12 @@ the same graph and still differ because their checkpoint bytes, custom nodes,
 or sampler settings differ. Commit the workflow and record the model stack used
 to test it.
 
-The revision manifest and dependency gate are provider-neutral, but ComfyUI is
-the only built-in adapter that currently opts in. PixelLab, Retro Diffusion,
-and Scenario reject revision assets offline. See
+The revision manifest and dependency gate are provider-neutral. ComfyUI and
+PixelLab opt in; Retro Diffusion and Scenario reject revision assets offline.
+PixelLab covers `image-to-image`, `inpaint`, `reduce-colors`,
+`correct-pixelart`, `animate`, `animate-pixminimax`, `animate-skeleton`,
+`interpolate`, and `edit-animation`, but not `outpaint`. ComfyUI covers the
+single-image modes through its workflow bindings. See
 [Controlled asset revisions](./docs/REVISIONS.md) before using the bundled
 square image-to-image graph.
 
@@ -131,7 +135,7 @@ background. That distinction matters more than raw canvas size.
 | Asset type | PixelLab | Retro Diffusion | ComfyUI | Scenario |
 |---|---|---|---|---|
 | Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | The live BFL smoke produced a readable 512px keep, but it was opaque and used 19,619 colors. Use that profile for concepts or refinement input, not a finished limited-palette asset. A project-specific model may improve consistency but needs its own smoke. |
-| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene. Current PixelKiln routes top out at 400×400. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
+| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene; both top out at 400×400. `imagePro` reaches 792 wide or 688 tall for a flat 40 generations. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
 | Style consistency across a set | `1dir` accepts a style reference and returns size-dependent candidates, but it is more expensive and capped at the square-object range. | RD Pro accepts up to nine references and has stronger prompt following, but its common styles top out at 256×256 and cost $0.18 per image. Environment-specific RD Plus styles trade references for a larger 384px canvas. | LoRAs, reference adapters, ControlNet, and shared latent settings can live in the committed workflow. Reproducibility also depends on external model and custom-node versions. | Scenario's project models and LoRAs are the main reason to use it for a set. PixelKiln can pin the model ID and parameters, but its first live run covers only the public BFL profile. |
 | Very large final scene | Generate reusable objects, terrain, and background layers separately; assemble them deterministically and integer-upscale the result. | Use the same layered approach. The API has a 512px overall ceiling, but the useful environment and scene-object styles currently cap at 384px. | The graph can tile, upscale, or composite beyond hosted-provider limits, but memory and seam quality become workflow concerns. Prefer reusable layers unless the scene truly needs one render. | Scenario can request a larger raster from a compatible model, but the same rule applies: generate reusable layers at their useful native detail, compose at 1×, and integer-upscale only the final scene. |
 
@@ -194,18 +198,29 @@ not share one runtime.
 The services use different billing units, so PixelKiln never adds their costs
 together.
 
-PixelLab figures below are measurements from the endpoints PixelKiln currently
-uses; they are not a conversion to dollars:
+PixelLab figures below come from the endpoints PixelKiln currently uses. Rows
+marked unmeasured or quoted are `plan` estimates, not bills. None is a
+conversion to dollars:
 
-| PixelLab route | Measured cost |
+| PixelLab route | Cost |
 |---|---:|
 | `map` | 1 generation |
 | `pixflux` | 1 generation |
 | `1dir` | 20–40 generations |
+| `imagePro` | 40 generations |
+| `imageProFlash` | 5–9 generations (provisional quote) |
 | `tiles` | 20–40 generations |
-| `character` base | 1 (standard), 2–9 (v3), 20–40 (pro) |
-| `character` state | 20–40 generations |
+| `terrain` | 20–40 generations (unmeasured) |
+| `isometricTile` | 1 generation (measured once) |
+| `character` base | 1 (standard), 2–9 (v3), 20–40 (pro), 6–17 (pro-flash; rotations only from a reference) |
+| `character` state or portrait | 20–40 generations |
 | `character` animation | 1 (template), 1 at 64px from text, 20–40 (pro) |
+| `character` outfit | 20 generations (one 2-frame, 92×92 job) |
+| `objectPro` base | 6 at 64px (unmeasured) |
+| `uiAsset` | 20 generations (measured once, at 256×192) |
+| `uiElement` | 20–40 generations (unmeasured) |
+| `image-to-image` / `inpaint` revision | 20–40 generations; 5–9 with `engine: "pro-flash"` (provisional quote) |
+| `reduce-colors` / `correct-pixelart` revision | 0.1 generations (measured at 32×32) |
 
 Retro Diffusion publishes USD formulas and fixed prices. Examples relevant to
 PixelKiln include RD Fast from about $0.015 per image, RD Plus from about $0.025,

package/README.md

@@ -53,8 +53,9 @@ provenance and no long-lived npm token.
 | Plan and budget | Offline manifest/lock/disk diff, provider-grouped estimates, keyed mixed-provider budget ceilings, JSON/CI gate. |
 | Generate and review | Resumable submit/poll/pick/fetch pipeline, exact next-step hints, candidate or atomic frame-set review, and a provenance gallery that can edit intent, generate under a budget, and compare records. |
 | Hand edits | Touch-ups in your own editor or a pinned in-browser Pixelorama, kept beside the generated art with the generation still the record; frame and tile sets member by member. |
-| Controlled inputs | Hashed image-to-image/inpaint lineage, fail-closed parent approval, source-versus-candidate review, and content-addressed per-asset ComfyUI bindings. |
-| Characters | A base in 4 or 8 directions from a prompt or your own sprite (four PixelLab engines), poses and loops as dependent assets generated in waves, free mirrored directions, account adoption, and SpriteFrames export. |
+| Controlled inputs | Hashed revision lineage (image-to-image and inpaint; on PixelLab also palette reduction, pixel cleanup, animation, skeleton posing, interpolation, and animation edits), fail-closed parent approval, source-versus-candidate review, and content-addressed per-asset ComfyUI bindings. |
+| Characters | A base in 4 or 8 directions from a prompt or your own sprite (four PixelLab engines), poses, loops, portraits, and outfit transfers as dependent assets generated in waves, free mirrored directions (one `directions` list declares a loop and mirrors the rest), account adoption and salvage, and SpriteFrames export. |
+| PixelLab utilities | `unzoom` returns upscaled reference art to its native grid, `font` generates a `.ttf` and glyph atlas, and `estimate-skeleton` starts a keypoints file for skeleton animation. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
 | Recovery | Safe stale-output replacement, validated caches, durable references, resumable paid jobs, and per-asset generation history with free restores. |
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
@@ -258,18 +259,17 @@ Measured PixelLab economics vary by 40×:
 | Independent or connectable ground tiles | `tiles` | 20–40 generations |
 | A character in 4 or 8 directions, its poses, its loops | `character` | 1 per base, 20–40 per pose, 1 per template loop per direction; a `mirror` of a loop is free |
 
-Start with the required capability, not the most expensive endpoint. Forty
-`map` re-rolls cost the same as one 64×64 `1dir` call; conversely, `map` cannot
-replace a hard palette or reference-image constraint. See
-[Generator selection](./docs/GENERATORS.md) and the
-[measured endpoint reference](./docs/ENDPOINTS.md).
+Start with the required capability, not the most expensive endpoint. Forty `map`
+re-rolls cost the same as one 64×64 `1dir` call; conversely, `map` cannot replace a
+hard palette or reference-image constraint. PixelLab has seven more generators
+(`imagePro`, `imageProFlash`, `terrain`, `isometricTile`, `objectPro`, `uiAsset`,
+`uiElement`); see [Generator selection](./docs/GENERATORS.md) and the [measured endpoint reference](./docs/ENDPOINTS.md).
 
-Generator names describe PixelKiln workflows; their exact capabilities and
-prices depend on the selected provider. Retro Diffusion also supports the
-provider-specific `animation` generator. ComfyUI supports `map` plus atomic
-still-image `frames` through an operator-supplied workflow. Scenario supports `map`
-with a required offline CU ceiling and a live quote before each paid call.
-Compare the adapters in the [provider comparison](./PROVIDERS.md).
+Generator names describe PixelKiln workflows; their exact capabilities and prices
+depend on the selected provider. Retro Diffusion also supports the provider-specific
+`animation` generator. ComfyUI supports `map` plus atomic still-image `frames` through
+an operator-supplied workflow. Scenario supports `map` with a required offline CU
+ceiling and a live quote before each paid call. Compare the adapters in the [provider comparison](./PROVIDERS.md).
 
 ## Derived artifacts
 
@@ -368,12 +368,13 @@ verification. See [Library API](./docs/LIBRARY.md).
 | [Set up ComfyUI](./docs/COMFYUI.md) | Self-hosted stills, revisions, ordered frame sets, per-asset inputs, and quality limits. |
 | [Set up Scenario](./docs/SCENARIO.md) | Experimental hosted models, two-part credentials, CU preflight, review, and durable downloads. |
 | [Versioned recipes](./docs/RECIPES.md) | Pinned workflow packs, model hashes, manifest templates, and quality contracts. |
-| [Controlled revisions](./docs/REVISIONS.md) | Image-to-image/inpaint parents, masks, fail-closed readiness, provenance, and ComfyUI bindings. |
+| [Controlled revisions](./docs/REVISIONS.md) | Image-to-image, inpaint, palette cleanup, animation, and interpolation from a parent; masks, fail-closed readiness, provenance, and ComfyUI bindings. |
 | [CLI reference](./docs/CLI.md) | Every command, flag, JSON mode, and exit contract. |
 | [Manifest reference](./docs/MANIFEST.md) | Style/asset fields, quality profiles, and generator constraints. |
 | [Mixed-provider projects](./docs/MIXED_PROVIDERS.md) | Per-style routing, provider-keyed budgets, recovery, and account commands. |
 | [Agent workflows](./docs/AGENTS.md) | Official skill install, operating model, and provider-aware safety. |
 | [Generators](./docs/GENERATORS.md) | Capability choice, measured costs, palettes, style references, and tiles. |
+| [Characters](./docs/CHARACTERS.md) | Bases, states, loops, mirrors, portraits, outfits, the `directions` shorthand, and per-engine costs. |
 | [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Thirty provider outputs plus native-grid and final-palette results comparing large scenes, transparency, palette size, and file readiness. |
 | [Derived artifacts](./docs/ARTIFACTS.md) | Refine, pack, mount, export, provenance, ownership, transactions, and recovery. |
 | [Recovery](./docs/RECOVERY.md) | Restore, caches, adopt, salvage, claims, and purge safety. |
@@ -384,10 +385,9 @@ verification. See [Library API](./docs/LIBRARY.md).
 | [Endpoint research](./docs/ENDPOINTS.md) | Measured PixelLab API behavior and recipes. |
 | [Provider comparison](./PROVIDERS.md) | Provider selection, costs, supported workflows, confidence, and limitations. |
 
-The [public documentation site](https://pixelkiln.griffen.codes/docs) is built from
-these Markdown files by [`website/`](./website/README.md), so the site and the
-package share one source. Policies: [Contributing](./CONTRIBUTING.md),
-[Security](./SECURITY.md), [provider comparison](./PROVIDERS.md).
+The [public documentation site](https://pixelkiln.griffen.codes/docs) is built from these Markdown
+files by [`website/`](./website/README.md), so the site and the package share one source.
+Policies: [Contributing](./CONTRIBUTING.md), [Security](./SECURITY.md).
 
 ## Scope
 

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) and `estimate-skeleton`'s one image
+path. 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,9 @@ 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` |
 | 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 +351,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 +872,10 @@ 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.
 
 ### `unzoom`
 
@@ -936,6 +926,23 @@ 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]
+```
+
+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.
+
 ## Utility commands
 
 ### `help`
@@ -953,7 +960,7 @@ Print the package version. `-v` is an alias.
 | `--manifest <path>` | manifest commands | Manifest path; defaults to `pixelkiln.manifest.json`. |
 | `--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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.68.0",
+  "version": "0.68.1",
   "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`, and `estimate-skeleton`
+  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,19 @@ 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. 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,15 @@ 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`), then edit the frame poses by hand. 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 +67,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 +81,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