pixelkiln 0.65.0 → 0.67.0

package/docs/CHARACTERS.md

@@ -120,6 +120,16 @@ is read again at submit time and refused if it changed since `plan`.
 States, animations, and mirrors take their look from their parent and
 cannot carry a reference.
 
+A `pro-flash` base's reference can be an image PixelKiln drew with the
+[`imageProFlash`](./GENERATORS.md#imageproflash) generator: point `reference`
+at that asset's downloaded file. When the file is byte-for-byte the output of
+an `imageProFlash` lock entry, submit sends PixelLab that image's
+`source_image_id` instead of uploading the same pixels, and the character is
+drawn from the exact image PixelLab already holds. The price is the same
+either way (the rotations only); the difference is that nothing is
+re-encoded. Generate and fetch the still before planning the character, so
+the file exists. An `objectPro` base's reference is handled the same way.
+
 ### Concept images and style anchors (pro)
 
 The pro engine has two more ways in. `concept` on a base names a concept

package/docs/CLI.md

@@ -344,6 +344,23 @@ 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.

package/docs/GENERATORS.md

@@ -17,6 +17,7 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 | 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 |
 | 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 |
 
 Start with `map` unless a required capability points elsewhere. Forty `map`
 re-rolls cost the same as one 64×64 `1dir` call.
@@ -404,6 +405,49 @@ price at an area well above where `1dir`/`tiles` would bill the ceiling.
 Left as an over-read for `--budget` until a second size is measured; see
 [ENDPOINTS.md](./ENDPOINTS.md) for the full writeup.
 
+## `imageProFlash`
+
+`imageProFlash` wraps PixelLab's `/create-image-pro-flash`: one native
+pixel-art image on the Pro Flash model, the same model the `character` and
+`objectPro` `pro-flash` engines draw with, as a plain still. It sits between
+`pixflux`/`map` (1 generation, no style reference) and `imagePro` (a flat 40):
+
+```jsonc
+{
+  "styles": {
+    "stills": {
+      "generator": "imageProFlash",
+      "styleImages": [{ "path": "refs/house-style.png" }],
+      "styleTraits": { "palette": true, "outline": true, "detail": false, "shading": true },
+      "outDir": "art/stills"
+    }
+  },
+  "assets": {
+    "knight": { "prompt": "a knight in blue armor, facing the viewer", "width": 64, "height": 64 }
+  }
+}
+```
+
+- Sizes run 16 to 256 per side in multiples of 4, and can be non-square.
+  PixelLab's native sizes (24, 32, 32×48, 64, 96×64, 96) are its most
+  reliable; other sizes are its "custom (beta)" range.
+- One `styleImages` entry is the style image, and `styleTraits` choose what
+  it lends (palette, outline, detail, shading; each on by default), the same
+  switches a `pro-flash` character base takes. Traits without a style image
+  are refused.
+- One call returns one image, recorded straight away. The lock also records
+  PixelLab's `image_id` and `source_image_id` for it: a Pro Flash `character`
+  or `objectPro` base whose `reference` is this image's downloaded file
+  reuses it by that id instead of uploading the same pixels again (see
+  [Characters](./CHARACTERS.md#starting-from-your-own-sprite)).
+- **Cost:** 5 generations up to 96px on the longer side, 6 up to 208px, 9
+  beyond, from PixelLab's own `/pro-flash/cost` quotes, which PixelLab calls
+  provisional. The billed amount on the finished job is what the lock keeps.
+
+The same model also edits and inpaints: `"engine": "pro-flash"` on an
+`image-to-image` or `inpaint` revision; see
+[Controlled asset revisions](./REVISIONS.md#pixellab).
+
 ## `uiElement`
 
 `uiElement` wraps PixelLab's `/generate-ui-v2` ("Generate UI (Pro)"): one UI

package/docs/MANIFEST.md

@@ -116,7 +116,7 @@ One asset using the fields most projects reach for:
 |---|---|---|
 | `extends` | style id | Optional parent style. The child inherits resolved settings but must declare its own `outDir`. |
 | `provider` | top-level default | Provider registry id for this style. Assets cannot override it. |
-| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `terrain`, `isometricTile`, `imagePro`, `character`, `objectPro`, `uiAsset`, `uiElement`, or provider-specific `animation`/`frames`. See [GENERATORS.md](./GENERATORS.md). |
+| `generator` | `map` | `map`, `1dir`, `pixflux`, `tiles`, `terrain`, `isometricTile`, `imagePro`, `character`, `objectPro`, `uiAsset`, `uiElement`, `imageProFlash`, or provider-specific `animation`/`frames`. See [GENERATORS.md](./GENERATORS.md). |
 | `outDir` | string, required | Output directory relative to the manifest. |
 | `promptPrefix` | `""` | Prepended to every participating asset prompt. |
 | `promptSuffix` | `""` | Appended to every participating asset prompt. |
@@ -144,7 +144,7 @@ One asset using the fields most projects reach for:
 | `isometric` | `false` | `character` only. Draw `standard` bases and every loop in isometric view. |
 | `enhancePrompt` | `false` | `character` only, `v3` bases. Let PixelLab expand the prompt into a fuller one before drawing. |
 | `styleCharacter` | | `character` only, `pro` bases. The asset id of a generated 8-direction character in this style whose look bases drawn from text or a concept follow. An asset may override it. |
-| `styleTraits` | all true | `character` only, `pro-flash` bases with a style image. `{ palette, outline, detail, shading }` booleans: which traits the style image lends. |
+| `styleTraits` | all true | `character` `pro-flash` bases and `imageProFlash` styles, with a style image. `{ palette, outline, detail, shading }` booleans: which traits the style image lends. |
 | `mount` | object | Stable-cell sheet placement; documented below. |
 | `quality` | object | Optional native-grid, final-palette, and human-approval contract; documented below. |
 | `tags` | string array, `[]` | Tags inherited by every generated provider object in the style. |
@@ -468,7 +468,7 @@ their own page: [Characters](./CHARACTERS.md) and
 
 | Revision field | Type | Meaning |
 |---|---|---|
-| `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `animate`, `animate-pixminimax`, `interpolate`, or `edit-animation`. The selected provider must opt into the mode. |
+| `mode` | enum, required | `image-to-image`, `inpaint`, `outpaint`, `reduce-colors`, `correct-pixelart`, `animate`, `animate-pixminimax`, `animate-skeleton`, `interpolate`, or `edit-animation`. The selected provider must opt into the mode. |
 | `from` | asset id, required | Parent asset in the same style. Self-references, unknown ids, and cycles are rejected. A parent written as a set (a character's directions, an animation's frames) is read as every member: `reduce-colors`, `correct-pixelart`, and `edit-animation` take the whole set in one call; the other modes refuse it. See [Revising a whole set at once](./REVISIONS.md#revising-a-whole-set-at-once). |
 | `mask` | string | Manifest-relative PNG required for `inpaint`; rejected for the other modes. Its dimensions must match an available source. |
 | `strength` | number 0–1 | Workflow edit/denoise strength (`image-to-image`, `correct-pixelart`); rejected for `reduce-colors`, `animate`, `animate-pixminimax`, `interpolate`, and `edit-animation`. Interpretation is provider- and model-specific. |
@@ -476,11 +476,15 @@ their own page: [Characters](./CHARACTERS.md) and
 | `paletteImage` | string | `reduce-colors` only. Manifest-relative image whose colors become the palette; unlike `mask`, no size relationship to the source is required. |
 | `dithering` | enum | `reduce-colors` only. `none` (default), `2x2`, `4x4`, or `8x8`. |
 | `ditheringStrength` | number 0–10 | `reduce-colors` only. Ignored when `dithering` is `none`. |
-| `frames` | integer 4–40, even | `animate`/`animate-pixminimax` only. `animate` caps at 16; `animate-pixminimax` allows up to 40. |
+| `frames` | integer 4–40, even | `animate`/`animate-pixminimax` only. `animate` caps at 16; `animate-pixminimax` allows up to 40. Rejected for `animate-skeleton` (frame count comes from `keypointsFile` instead), `interpolate`, and `edit-animation`. |
 | `fps` | integer 1–60 | `animate`/`animate-pixminimax`/`interpolate`/`edit-animation` only. Playback rate recorded with the frames; the provider does not store one. Defaults to the parent's own rate when it is a loop, else 8. |
 | `lastFrame` | string | `animate`/`animate-pixminimax`: manifest-relative image pinning where the motion ends, turning an open-ended animation into an interpolation. `interpolate`: required, the ending keyframe (the parent is the start); it must match the parent's size. |
-| `direction` | enum | `animate-pixminimax` only. The sprite's facing, used only alongside `enhancePrompt`. |
+| `direction` | enum | `animate-pixminimax`/`animate-skeleton`. Optional (alongside `enhancePrompt`) for the former; **required** for the latter. |
 | `enhancePrompt` | boolean | `animate`/`animate-pixminimax` only. Lets the provider expand the prompt into a fuller motion description first, for an extra documented +0.05-generation surcharge. |
+| `keypointsFile` | string, required for `animate-skeleton` | Manifest-relative JSON file (`src/skeleton.ts`'s `SkeletonSetSchema`): the pose the source is already in, plus 3–15 per-frame poses. See [Skeleton-driven animation](./REVISIONS.md#skeleton-driven-animation). |
+| `skeletonTemplate` | string | `animate-skeleton` only. Body a joint's missing `depth` is taken from: `mannequin` (default), `bear`, `cat`, `dog`, `horse`, or `lion`. |
+| `description` | string | `animate-skeleton` only. What the subject *looks like* (colours, clothing, held items) — the asset's own `prompt` is sent as the motion's short label instead. |
+| `engine` | enum | `image-to-image`/`inpaint` only. `pro-flash` draws the edit with PixelLab's Pro Flash edit or inpaint endpoint instead of the default Pro one: 5–9 generations instead of 20–40, 32 to 256px per side in multiples of 4, no `strength`. Omit for the default. |
 
 The parent may use committed `source`, downloaded generated output, or a
 current approved quality output. Parent and mask hashes participate in the

package/docs/PIXELLAB.md

@@ -156,20 +156,21 @@ comparing notes with someone using a different one:
 
 ## What is outside this adapter
 
-PixelLab offers more than PixelKiln currently exposes. Lip-sync and
-skeleton-driven animation are not part of this adapter. Characters, their
-states, their animations, their portraits, and outfit transfer onto their
-loops are the `character` generator, with all four creation engines
-(standard, v3, pro, pro-flash),
-reference sprites, concept images, style anchors, mirrors, and every
-`animate-character` control; see [Characters](./CHARACTERS.md). Masked
-inpainting and whole-image editing 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 `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
+PixelLab offers more than PixelKiln currently exposes. Lip-sync and vocal
+animation are not part of this adapter. Characters, their states, their
+animations, their portraits, and outfit transfer onto their loops are the
+`character` generator, with all four creation engines (standard, v3, pro,
+pro-flash), reference sprites, concept images, style anchors, mirrors, and
+every `animate-character` control; see [Characters](./CHARACTERS.md). Masked
+inpainting, whole-image editing, and skeleton-driven animation (posing a
+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
+`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
 scene composition (placing objects and characters into a map, in-scene
 inpainting, export) is a separate PixelLab product surface this adapter does
 not model at all — including PixelKiln's own `map` generator, which is

package/docs/REVISIONS.md

@@ -7,11 +7,12 @@ dependencies before submission, and records the lineage in the lockfile.
 
 The manifest and pipeline are provider-neutral. ComfyUI and PixelLab implement
 it; PixelLab covers `image-to-image`, `inpaint`, `reduce-colors`,
-`correct-pixelart`, `animate`, `animate-pixminimax`, `interpolate`, and
-`edit-animation`, not `outpaint` (its API has no canvas-expansion endpoint).
-ComfyUI covers every mode generically except the four frame-set modes
-(`animate`, `animate-pixminimax`, `interpolate`, `edit-animation`), which need
-an ordered frame set its revision path cannot produce. Retro Diffusion and Scenario reject revision
+`correct-pixelart`, `animate`, `animate-pixminimax`, `animate-skeleton`,
+`interpolate`, and `edit-animation`, not `outpaint` (its API has no
+canvas-expansion endpoint). ComfyUI covers every mode generically except the
+five frame-set modes (`animate`, `animate-pixminimax`, `animate-skeleton`,
+`interpolate`, `edit-animation`), which need an ordered frame set its
+revision path cannot produce. Retro Diffusion and Scenario reject revision
 work during offline resolution instead of silently starting a fresh
 text-to-image job.
 
@@ -316,6 +317,81 @@ writes a single output image, and an animation is a frame set — a structural
 gap rather than a missing binding, so `supportsRevision` refuses it up front
 rather than failing partway through submission.
 
+## Skeleton-driven animation
+
+A third mode, `animate-skeleton`, poses the source image frame-by-frame from
+a supplied 18-joint skeleton per frame instead of a text motion description:
+
+```jsonc
+{
+  "assets": {
+    "hero-swing": {
+      "prompt": "swinging the sword downward",
+      "revision": {
+        "mode": "animate-skeleton",
+        "from": "hero-idle",
+        "keypointsFile": "poses/hero-swing.json",
+        "direction": "south"
+      }
+    }
+  }
+}
+```
+
+`keypointsFile` names a manifest-relative committed JSON file, not inline
+manifest data — the same reasoning `mask`/`lastFrame` are files rather than
+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.
+
+`direction` is **required** for this mode (unlike `animate-pixminimax`,
+where it is optional). `frames`/`fps`/`lastFrame`/`enhancePrompt` are all
+rejected — the frame count comes from the keypoints file itself
+(`frames.length`), never a manifest number. `description` (optional: what the
+character *looks like* — colours, clothing, held items) is a new field
+distinct from the asset's own `prompt`, which this mode sends as the motion's
+short label (PixelLab's `action`) — the same `prompt`-as-motion convention
+`animate`/`animate-pixminimax` already use, just under this endpoint's own
+field name.
+
+`firstFrameKeypoints` (inside the keypoints file) describes the pose the
+reference image is *already* in — PixelLab redraws that frame first to learn
+its background and colors before animating forward, and does not return it.
+**PixelKiln cannot verify this against the image's actual content.** A
+mismatch does not error; it silently degrades transparency and color
+accuracy in every generated frame. When in doubt, run `estimate-skeleton` on
+the reference image itself and use that result, rather than hand-authoring
+a guess.
+
+**Deliberately not wired into the manifest pipeline: `estimate-skeleton`
+itself.** `PixelLabClient.estimateSkeleton()` exists and the CLI command above
+calls it directly, but nothing in `resolveSpecs`/`estimate()`/`submitRevision`
+ever calls it — planning stays offline by construction (the keypoints file is
+read like any other manifest input, never a network call), and the only
+PixelLab endpoint `animate-skeleton`'s submission composes is
+`animate-with-skeleton-v3` itself, not two never-tested-live calls chained
+together. A future pipeline stage that budgets and tracks `estimate-skeleton`
+calls the way `gen` does everything else is tracked separately, once this
+mode has shipped and seen real use.
+
+Cost uses PixelLab's own documented anchors (3 frames = 2 generations, 8 = 3,
+15 = 4 — barely moving with length, unlike `animate`/`animate-pixminimax`'s
+canvas-area formula) and interpolates between the nearest two for any
+in-between frame count, ceiling'd — the safe direction for `--budget` — since
+no in-between value is confirmed live. **Neither `animate-with-skeleton-v3`
+nor `estimate-skeleton` has been exercised against a live account**; request
+field names come from the live `animate_with_skeleton_v3` MCP tool schema
+(the same authoritative source already trusted for the character/object
+family), not an observed call.
+
+ComfyUI does not support this mode either, for the same structural reason as
+`animate`/`animate-pixminimax`.
+
 ## Dependency gate
 
 `pixelkiln plan` reports a revision as `blocked` when its parent is not safe to
@@ -399,6 +475,19 @@ approval gate before shipping. See the
 
 ## PixelLab
 
+`"engine": "pro-flash"` on an `image-to-image` or `inpaint` revision sends it to
+PixelLab's Pro Flash tier instead: `/edit-image-pro-flash` (a text edit at the
+source's own size; the canvas never grows) or `/inpaint-image-pro-flash`
+(replaces only the mask's white pixels and keeps the rest exactly). It is the
+same model the `imageProFlash` generator and the `pro-flash` character engine
+use, priced on the same provisional Pro Flash tier (5 generations up to 96px,
+6 up to 208px, 9 beyond) instead of the 20–40 of the default Pro endpoints.
+Sources must be 32 to 256px per side in multiples of 4; `strength` is refused,
+since neither endpoint has one. The finished job is read the same way as the
+default endpoints'. PixelLab also offers reference-image edits, a
+`context_image` around an inpaint, and inpaint output layers; none is modeled
+yet.
+
 PixelLab needs no bindings: `image-to-image` calls `/edit-images-v2`,
 `inpaint` calls `/inpaint-v3`, both as a plain background job polled the same
 way as every other PixelLab submission. `reduce-colors` calls `/reduce-colors`
@@ -451,6 +540,14 @@ further — there is nothing to ask.
   request/response shapes come from PixelLab's live OpenAPI document, not an
   observed call. Treat the exact field names as provisional until a real
   call confirms them.
+- `animate-skeleton` calls `/animate-with-skeleton-v3`, also a real async
+  background job, at most 256 pixels per side and 3-15 frames (the frame
+  count comes from `keypointsFile`, not a manifest field). See
+  [Skeleton-driven animation](#skeleton-driven-animation) above for the full
+  field list, the `keypointsFile` shape, and the `estimateSkeleton`
+  CLI-only-and-never-in-the-submission-path decision. Same unverified-live
+  caveat as `animate`/`animate-pixminimax`, sourced from the live
+  `animate_with_skeleton_v3` MCP tool schema rather than an observed call.
 
 - The mask convention is fixed, not graph-defined like ComfyUI's: white marks
   the area to generate, black the area to preserve. There is no way to flip it.
@@ -522,16 +619,20 @@ hash, strength, and — for `reduce-colors` — `numColors`, the palette image's
 hash, and the dithering settings, or — for `animate`/`animate-pixminimax` —
 `frames`, `fps`, the last frame's hash, `direction`, and `enhancePrompt`
 (`interpolate` records `fps` and the end keyframe's hash; `edit-animation`
-records `fps`). For a set parent, the parent hash is one hash over every
-member's hash in order.
+records `fps`), or — for `animate-skeleton` — the keypoints file's hash,
+`skeletonTemplate`, and `description` (`direction` is recorded the same way;
+`frames` comes from the keypoints file itself, same field, same staleness
+rule as the others). For a set parent, the parent hash is one hash over
+every member's hash in order.
 ComfyUI provider metadata also retains the same lineage beside the workflow
 hash.
 
 Changing the prompt, workflow, mode, strength, parent bytes, mask bytes, color
 count, palette image bytes, dithering settings, frame count, last frame
-bytes, direction, or enhancePrompt makes the child stale. Moving an unchanged
-parent, mask, palette image, or last frame file does not. When a child
-has a quality profile, the new raw output hash also invalidates its old quality
+bytes, direction, enhancePrompt, keypoints file bytes, skeletonTemplate, or
+description makes the child stale. Moving an unchanged parent, mask, palette
+image, last frame file, or keypoints file does not. When a child has a
+quality profile, the new raw output hash also invalidates its old quality
 record, so a revised image cannot inherit approval from an earlier generation.
 
 Commit the parent art or parent lock entry, masks, child output, child lock

package/package.json

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

package/schema/manifest.schema.json

@@ -46,7 +46,8 @@
                       "isometricTile",
                       "objectPro",
                       "uiAsset",
-                      "uiElement"
+                      "uiElement",
+                      "imageProFlash"
                     ],
                     "default": "map"
                   },
@@ -503,7 +504,8 @@
                       "isometricTile",
                       "objectPro",
                       "uiAsset",
-                      "uiElement"
+                      "uiElement",
+                      "imageProFlash"
                     ],
                     "default": "map"
                   },
@@ -1010,6 +1012,7 @@
                       "correct-pixelart",
                       "animate",
                       "animate-pixminimax",
+                      "animate-skeleton",
                       "interpolate",
                       "edit-animation"
                     ]
@@ -1079,6 +1082,24 @@
                   },
                   "enhancePrompt": {
                     "type": "boolean"
+                  },
+                  "keypointsFile": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "skeletonTemplate": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "description": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "engine": {
+                    "type": "string",
+                    "enum": [
+                      "pro-flash"
+                    ]
                   }
                 },
                 "required": [

package/schema/recipe.schema.json

@@ -121,7 +121,8 @@
                 "isometricTile",
                 "objectPro",
                 "uiAsset",
-                "uiElement"
+                "uiElement",
+                "imageProFlash"
               ],
               "default": "map"
             },

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

@@ -246,6 +246,28 @@ which tutorial(s) demonstrated real (not hypothetical) demand for it.
   actually describe `uiAsset`'s pricing. Left unpatched from one data point:
   over-reading stays the safe `--budget` direction, but a real call likely
   costs about half of what `pixelkiln plan` prints, pending a second size.
+- **Skeleton-driven animation** (`POST /animate-with-skeleton-v3`, beta,
+  tier 1+ subscription — pose a reference image frame-by-frame from a
+  supplied 18-joint skeleton per frame, instead of a text motion
+  description) — closed by the `revision` asset shape's `animate-skeleton`
+  mode; see `pixellab.md` and `docs/REVISIONS.md#skeleton-driven-animation`.
+  `POST /estimate-skeleton` (auto-derive a reference image's own keypoints)
+  is wrapped too, but deliberately kept outside the manifest pipeline — a
+  standalone `pixelkiln estimate-skeleton` CLI command, not a
+  `resolveSpecs`/`estimate()`-time call — so `animate-skeleton`'s submission
+  composes exactly one never-tested-live PixelLab endpoint, not two chained
+  together. **Correcting this catalog's own prior research**: this entry
+  used to also claim a distinct "animation to animation" endpoint existed,
+  for transferring an existing walk cycle's motion onto a different
+  character. Checked against the live `animate_with_skeleton_v3` MCP tool
+  schema: **there is no such endpoint.** The real composition is
+  `estimate-skeleton` run once per frame of a source animation, then
+  `animate-with-skeleton-v3` against a *different* reference image reusing
+  those keypoints — a two-endpoint composition a person can now build by
+  hand with the primitives above, not a primitive pixelkiln itself
+  automates. Neither `animate-with-skeleton-v3` nor `estimate-skeleton` has
+  been exercised against a live account; request field names come from the
+  MCP tool schema, not an observed call.
 
 - **Fonts** (`/generate-font-pro`, an 80-glyph atlas plus a `.ttf` from a
   style description) — no tutorial demonstrated it in depth, so demand is
@@ -326,12 +348,15 @@ quote/identity lookup — not billed):**
   exactly, reassuring cross-validation of the quote endpoint even though it
   is a quote, not a bill.
 
-Not modeled at all today: pixelkiln's `imagePro` generator and the `revision`
-asset shape's `image-to-image`/`inpaint` modes only ever call the non-Flash
-endpoints (`generate-image-v2`, `edit-images-v2`, `inpaint-v3`). Adding Pro
-Flash would mean a new generator (or a model/engine choice on the existing
-ones) plus a new inpaint `outputMethod` field and the `context_image`
-mechanism — real, scoped work, not a docs fix.
+**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)
 
@@ -364,22 +389,23 @@ native Godot 4 `TileSet` resource directly, verified in CI — worth knowing if
 Map Workshop parity is ever considered, since the export leg is arguably
 already solved better here than in PixelLab's own reference flow.
 
-## Skeleton-driven animation and animation-to-animation motion transfer
-
-Two more animation mechanisms with no equivalent: **"Animate with skeleton"**
-(fit a rig template — bipedal, realistic, chibi, or quadruped body plans —
-generate two frames at a time with each accepted pair becoming context for
-the next, height/head-size/offset controls) and **"Animation to animation"**
-(transfer the motion/shape structure of an *existing* walk cycle onto a
-newly described or referenced character, frame budget capped by the source's
-canvas size). Both demonstrated in "How to Make Walking Animations for Pixel
-Art Characters in PixelLab." Neither exists in pixelkiln's `character`
-schema, which only knows named templates, v3 text loops, and pro loops — none
-take a user-supplied motion source or expose a skeleton-editing surface.
-Already flagged as explicitly out of scope in docs/PIXELLAB.md
-("skeleton-driven animation"); animation-to-animation is new information not
-previously catalogued anywhere.
+## Animation-to-animation motion transfer
 
+Transferring the motion of an *existing* walk cycle onto a newly described or
+referenced character — demonstrated in "How to Make Walking Animations for
+Pixel Art Characters in PixelLab." As corrected in the now-closed
+skeleton-driven-animation entry above: this is not one endpoint, it is
+`estimate-skeleton` run per frame of the source animation plus
+`animate-with-skeleton-v3` against the new character's reference image
+reusing those keypoints. Both primitives exist in this adapter now
+(`animate-skeleton` revision mode, `pixelkiln estimate-skeleton`), so a
+person can build this by hand today — chaining `estimate-skeleton` calls
+across a source animation's frames into one keypoints file, then pointing an
+`animate-skeleton` revision's `from` at a different character. What remains
+a real gap is automating that chain as its own pixelkiln capability (one
+command, not N manual `estimate-skeleton` calls plus hand-assembling the
+result into a `SkeletonSetSchema` file) — worth scoping once the base
+`animate-skeleton` mode has shipped and seen real use.
 
 ## Not PixelLab gaps at all — different products, no action implied
 

package/skills/pixelkiln/references/pixellab.md

@@ -27,6 +27,7 @@ providers, or before any PixelLab account operation.
 | `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 |
 | `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 |
 
 `tiles` is not limited to top-down ground: `tileType` selects the projection
 (`isometric` — the API default —, `oblique`, `hex`, `hex_pointy`, `octagon`,
@@ -258,6 +259,15 @@ widgets under `uiAsset`'s 192px floor. Unmeasured: the plan borrows the
 20/25/40 canvas tiers, and the completed job's shape has not been observed
 live.
 
+`imageProFlash` wraps `/create-image-pro-flash`, the Pro Flash model as a plain
+still: priced 5 up to 96px, 6 up to 208px, 9 beyond (PixelLab's own
+provisional `/pro-flash/cost` quotes). Its lock entry keeps PixelLab's
+`source_image_id`; a Pro Flash character or object base whose `reference` is
+byte-for-byte that still's file is sent the id instead of the upload (same
+price, no re-encode). The same model edits and inpaints through a revision's
+`"engine": "pro-flash"` (`image-to-image`/`inpaint` only, 32–256px in multiples
+of 4, no `strength`), at the Pro Flash tier instead of the Pro endpoints' 20–40.
+
 Do not confuse pixelkiln's `map` generator with PixelLab's own "Map
 Workshop": `map` returns one static prop, icon, or building in a single
 generation with no scene, canvas, or placement concept. Map Workshop (scene
@@ -378,28 +388,43 @@ contained a generated signature-like glyph.
 An asset that declares `revision` against a PixelLab style calls `inpaint`
 (masked), `image-to-image` (whole-image, no mask), `reduce-colors`
 (palette quantize, `/reduce-colors`), `correct-pixelart` (edge/noise
-cleanup, `/correct-pixelart`), `animate` (`/animate-with-text-v3`), or
+cleanup, `/correct-pixelart`), `animate` (`/animate-with-text-v3`),
 `animate-pixminimax` (`/animate-pixminimax`, beta, tier 1 subscription or
-higher), `interpolate` (`/interpolation-v2`, in-betweens from the parent to
-a required `lastFrame` keyframe), or `edit-animation` (`/edit-animation-v2`,
-one edit across a whole frame set); `outpaint` is refused, since PixelLab has no canvas-expansion
-endpoint. `reduce-colors`/`correct-pixelart` send no prompt to PixelLab at
-all — they are mechanical, not described — and complete synchronously with
-no background job, unlike every other PixelLab call this adapter makes.
-`animate`/`animate-pixminimax` DO send the asset's own prompt, as the motion
-description, and produce an ordered **frame set** landing in candidate
+higher), `animate-skeleton` (`/animate-with-skeleton-v3`, also beta/tier
+1+ — poses the source frame-by-frame from a supplied 18-joint skeleton per
+frame, via a committed `keypointsFile` rather than a text motion
+description), `interpolate` (`/interpolation-v2`, in-betweens from the parent
+to a required `lastFrame` keyframe), or `edit-animation` (`/edit-animation-v2`,
+one edit across a whole frame set); `outpaint` is refused, since PixelLab has
+no canvas-expansion endpoint. `reduce-colors`/`correct-pixelart` send no
+prompt to PixelLab at all — they are mechanical, not described — and complete
+synchronously with no background job, unlike every other PixelLab call this
+adapter makes. `animate`/`animate-pixminimax`/`animate-skeleton` DO send the
+asset's own prompt, as the motion description (`animate-skeleton` calls it
+`action`, alongside a separate optional `description` field for appearance —
+the skeleton carries the motion, the text only names it and what the subject
+looks like), and produce an ordered **frame set** landing in candidate
 review, not a single image — the one revision mode shape that isn't "one
-image in, one image out." Neither animate endpoint's completed-job response
-shape has ever been observed; `pollAnimateRevision` guesses defensively
-rather than assume one. Read `docs/REVISIONS.md`'s PixelLab section before
-using any of these. A parent written as a set (a character's directions, an
-animation's frames) goes to `reduce-colors`, `correct-pixelart`, and
-`edit-animation` whole, in one call, so every member shares one palette or
-edit; the other modes refuse a set parent. `reduce-colors`/`correct-pixelart` cost is **confirmed
-live**: a flat 0.1 generations each (not the schema's dollar-denominated
-example), at least at a 32×32 source — `animate`/`animate-pixminimax` remain
-schema-only and unexercised, taken from PixelLab's live OpenAPI document
-rather than an observed call.
+image in, one image out." None of the animate/interpolate/edit-animation
+endpoints' completed-job response shape has ever been observed;
+`pollAnimateRevision` guesses defensively rather than assume one. Read
+`docs/REVISIONS.md`'s PixelLab section before using any of these. A parent
+written as a set (a character's directions, an animation's frames) goes to
+`reduce-colors`, `correct-pixelart`, and `edit-animation` whole, in one call,
+so every member shares one palette or edit; the other modes refuse a set
+parent. `reduce-colors`/`correct-pixelart` cost is **confirmed live**: a flat
+0.1 generations each (not the schema's dollar-denominated example), at least
+at a 32×32 source — `animate`/`animate-pixminimax`/`animate-skeleton`/
+`interpolate`/`edit-animation` remain schema-only and unexercised.
+`animate-skeleton`'s request field names come from the live
+`animate_with_skeleton_v3` MCP tool schema, a more authoritative source than
+the OpenAPI document the others are taken from, but still not an observed
+call. `estimate-skeleton` (auto-derive a reference image's own keypoints) is
+wrapped too, but deliberately as a standalone `pixelkiln estimate-skeleton`
+CLI command, never inside `submitRevision` — see
+[pixellab-roadmap.md](./pixellab-roadmap.md)'s now-closed skeleton-driven-
+animation entry for why composing two never-tested-live endpoints in one
+submission was rejected.
 
 `animate-pixminimax`'s `direction` + `enhancePrompt` combination has a
 measured-in-practice gotcha, not just a schema quirk: PixelLab's own tutorial