pixelkiln 0.92.1 → 0.92.3

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

@@ -26,6 +26,11 @@ 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.
 
+For which PixelLab endpoints PixelKiln already calls, and how much is measured
+about each (so a live run can be chosen by risk), read the [validation
+ledger](https://pixelkiln.griffen.codes/docs/endpoints#validation-ledger)
+(`docs/ENDPOINTS.md`).
+
 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.
 
@@ -52,7 +57,8 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   `mode: "skeleton-v3"` poses a template with the skeleton video model
   (2 to 4 generations and 3 to 5 minutes per direction, beta, Tier 1 and
   up). Now a character loop's `mode: "skeleton-v3"`; see
-  `docs/CHARACTERS.md`. Not yet billed live.
+  `docs/CHARACTERS.md`. A template loop on a v3 character billed 3
+  generations live (October 2026).
 
 - **Masked inpainting and whole-image editing** — was the single largest gap
   found (routine in at least 6 of the 26 tutorials). Now the `revision` asset
@@ -118,8 +124,8 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   generating a 384×216 scene background in "How to Make Animated Pixel Art
   Scenes with PixelLab." Closed by the `imagePro` generator; see
   `pixellab.md`. Reference images and a style image
-  (`reference_images`/`style_image`) remain unmodeled, and the completed
-  job's response shape has not itself been exercised live yet.
+  (`reference_images`/`style_image`) remain unmodeled. The completed job's
+  response shape has been read live (a 64×64 call billed 10).
 - **A standalone single isometric tile** (`/create-isometric-tile`, a third,
   separate path to isometric content distinct from both `tiles`'
   `tileType: "isometric"` and `terrain`'s `/create-tileset`, which is
@@ -147,11 +153,11 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   rotation, states, or animation for a plain object. Closed by the
   `objectPro` generator; see `pixellab.md`. It reuses `character`'s own
   `asset.state`/`asset.animation` authoring shapes and mirror handling
-  rather than inventing parallel ones. **Cost is not independently
-  measured**: assumed identical to `character` pro-flash's own measured
-  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
+  rather than inventing parallel ones. **The base is measured**: a 32px
+  base billed 6 and returned 8 files (November 2026), matching `character`
+  pro-flash's formula, which the estimate assumes since the request bodies
+  are near-identical minus `template_id`. States and `pro` animations remain
+  that assumption pending a live check. Batch "pack" generation (N distinct objects from
   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
@@ -203,17 +209,21 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   `pixellab.md`. `lastFrame` covers both the "pin an ending pose" and the
   "chain from a prior animation's final frame" cases — it is just a
   manifest-relative image, which can be any earlier asset's own generated
-  output file. **Neither endpoint's cost or completed-response shape is
-  measured against a live account** — cost borrows `character`'s own
-  measured v3-loop formula, and the frame list is extracted defensively from
-  several plausible field names rather than one confirmed shape, the way
-  `pollRevision` already handles `image-to-image`/`inpaint`. The dedicated
+  output file. **Both ran live in November 2026**: `animate` at 64×64 and 4 frames
+  billed 1 (5 frames back, input included), `animate-pixminimax` billed 1 at 8
+  frames and 2 at 16 (9 and 17 frames back), and the completed jobs were read
+  correctly. `animate`'s cost borrows `character`'s measured v3-loop formula;
+  `animate-pixminimax` follows PixelLab's published table. The frame list is
+  still extracted defensively from several plausible field names. The dedicated
   **Interpolate** endpoint (`/interpolation-v2`, a separate "Pro" two-keyframe
   tool distinct from `last_frame` pinning on the animate endpoints above) is
   now wrapped too, as the `interpolate` revision mode (parent = start
   keyframe, required `lastFrame` = end keyframe), alongside
   `/edit-animation-v2` as `edit-animation` (one text edit across a whole
-  frame set). Both unmeasured, both borrowing the 10/15/25 Pro canvas tiers.
+  frame set). Both ran live in November 2026 and billed 10 each (a 64×64
+  `interpolate` returning 14 frames; an `edit-animation` of a 9-frame 64×64
+  set), on the 10/15/25 Pro canvas tiers; the planner used to read them as 25
+  and is calibrated. Larger canvases are unbilled.
   Real demonstrated demand for Interpolate: "Level Up Your Game: Custom
   Sprite Animation Tutorial" used it
   repeatedly, in Aseprite via PixelLab's own extension, as the fix for an
@@ -278,7 +288,8 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   `/generate-ui-v2` ("Generate UI (Pro)": one element from a description,
   16px and up, with an optional concept image and palette hint), found on a
   later full read of the path list and now wrapped as the `uiElement`
-  generator; see `docs/GENERATORS.md#uielement`. Unmeasured. **Splitting into individual elements and
+  generator; see `docs/GENERATORS.md#uielement`. A 32×32 call billed 10 and
+  returned 64 candidates (November 2026). **Splitting into individual elements and
   nine-slice are not buildable at all**: `GET /ui-assets/{id}` returns one
   flat composited image with no per-piece sub-image or bounding-box data in
   its response schema, regardless of how many `pieces` the request declared.
@@ -297,10 +308,11 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   this one. **Cost confirmed live, and it overturned the borrowed
   formula**: a real 256x192 call against a Tier 2 account billed exactly 20
   generations (balance 4979.8 → 4959.8), the low end of the `create_ui_asset`
-  MCP tool description's "20-40 generations" claim. No dedicated cost branch
+  MCP tool description's then "20-40 generations" claim (10-25 since the
+  October 2026 cut). No dedicated cost branch
   exists, so `uiAsset` still falls through to the same canvas-tier formula
   `1dir`/`tiles` use, which — given this generator's 192px floor — always
-  predicts the 40 ceiling; the measured call billed the floor price at an
+  predicts the 25 ceiling; the measured call billed the floor price at an
   area well past where that formula would bill the ceiling, so it does not
   actually describe `uiAsset`'s pricing. Left unpatched from one data point:
   over-reading stays the safe `--budget` direction, but a real call likely
@@ -325,9 +337,8 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   `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.
+  automates. Both endpoints have run live (see above); request field names
+  came from the MCP tool schema, and the live run found `description` is required.
 - **Remove background** (`/remove-background`, a transparent cutout of one
   image up to 400x400, `simple` or `complex` task, optional foreground text
   hint) — closed by the `revision` asset shape's `remove-background` mode.
@@ -451,7 +462,8 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   - 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.
+    pixelkiln's measured `proFlashCharacterCost`. Only `create` has been billed
+    live (a 32×32 still with a palette, 5); `edit` and `inpaint` have not.
 
   Still unmodeled: `edit`'s `"reference"` method, the
   `use_color_palette_correction` flag (snap the edit back to the source's
@@ -536,15 +548,17 @@ missing:
 - **Trimming a loop's repeated frame.** The video deletes the last frame of
   a fireball loop because it repeats the first. `animate_image_pixminimax`
   says `get_image` returns `frame_count + 1` images with index 0 the input
-  unchanged. pixelkiln's frame extraction for this mode is unexercised live,
-  so whether the input frame lands in the set is unknown. There is no
-  manifest way to drop a frame either way.
-- **The cost estimate under-reads long clips.** The MCP tool now prices
-  PixMiniMax by generation time: 64×64 at 4, 8, 16, and 40 frames costs 1, 1,
-  2, and 6 generations. pixelkiln's placeholder,
-  `ceil(width × height × frames / 65536)`, gives 1, 1, 1, and 3 for the same
-  clips. Unlike every other unmeasured estimate here, this one under-reads,
-  so `--budget` can be too low.
+  unchanged. Confirmed live (November 2026): an 8-frame clip came back as 9
+  frames and a 16-frame clip as 17, with pixelkiln's frame extraction reading
+  all of them, so the input frame is in the set. There is no manifest way to
+  drop a frame.
+- **The cost estimate used to under-read long clips (fixed).** The MCP tool
+  prices PixMiniMax by generation time: 64×64 at 4, 8, 16, and 40 frames costs
+  1, 1, 2, and 6 generations. pixelkiln's old placeholder,
+  `ceil(width × height × frames / 65536)`, gave 1, 1, 1, and 3, and a live
+  16-frame clip billed 2 against a plan of 1. The estimate (`pixMiniMaxCost`)
+  now follows the published points and extrapolates above them; the 40-frame
+  point has not been billed.
 - **Joining two clips.** The video joins two orb animations end to end in
   Aseprite. pixelkiln has no frame-set concatenation; `lastFrame` can pin a
   clip's ending to another clip's frame file, but the two sets stay separate.

package/skills/pixelkiln/references/pixellab.md

@@ -26,11 +26,11 @@ providers, or before any PixelLab account operation.
 | `tiles` | Ground variations or connected structures | 10–25 generations |
 | `terrain` | A two-terrain Wang tileset for elevation (grass-to-water, floor-to-cliff), or a sidescroller platform set | Sidescroller **3**, measured. Pro **15** at 32px, measured (a connected second set also billed 15). Pro **25** at 64px and standard **3** measured too; standard plans at 4, the top of PixelLab's quoted 1–4 |
 | `imagePro` | A larger or non-square background/scene, or real style transfer; takes the style `palette` as a hard constraint | **10–25 generations** by canvas (64px billed 10; a flat 40 before October 2026) |
-| `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 (2–4 as `skeleton-v3`), 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 |
+| `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`), 10–25 per pose or portrait (20–40 before the October 2026 cut), 1 per template loop per direction (2–4 as `skeleton-v3`), 20 per outfit (measured once, before the cut) |
+| `objectPro` | A prop, creature, or vehicle that needs rotations, states, or loops but has no character rig | 6 per base (billed 6 at 32px, November 2026; 1 from a `reference`, unmeasured); states and animations 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 | 10–25 generations, **unmeasured** |
+| `uiAsset` | A UI panel, button, health bar, or other chrome, from precise `pieces` and/or named `elements` | **20 generations, measured once** (256×192, before the October 2026 cut); the borrowed canvas-tier estimate still predicts the 25 ceiling |
+| `uiElement` | One UI element (button, slot, bar, dialogue box) from the prompt, 16px and up, with an optional concept image | 10–25 generations (a 32×32 call billed 10; 64 candidates at 32×32) |
 | `vfx` | An animated effect (explosion, aura, lightning, status icons) from a `vfx` block: a `preset` or `recipe`, `parts`, an optional `sprite` to build around; cut into an ordered frame set. Or a `description` (+ `artist`: `lite`/`pro`, a local PNG `sprite`) for PixelLab's paid VFX artist | workbench **free** (a renderer, not a model); `description`: lite 1–5, pro 6–28 by sprite size, billed up to 2× the quote, which is what plan counts (a lite effect with no sprite billed its quote of 1, measured once) |
 | `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 |
 
@@ -221,10 +221,9 @@ mapping is not wrapped: it is "single images only", and this endpoint
 returns a grid of candidates below 171px. Reference
 images and a style image (`reference_images`, `style_image` +
 `style_options`, up to 4 subject references plus one style reference) exist
-on this endpoint but are not modeled yet, and the completed job's exact
-response shape has not been exercised against a live account — see
-`pollImagePro` in `src/providers/pixellab.ts` if a real call ever
-contradicts what it assumes.
+on this endpoint but are not modeled yet. The completed job has been read
+live (a 64×64 call billed 10); `pollImagePro` in `src/providers/pixellab.ts`
+still reads it defensively.
 
 `objectPro` wraps `/create-object-pro-flash` — the same base → state →
 animation family `character` uses (`docs/CHARACTERS.md`), for PixelLab's
@@ -244,11 +243,12 @@ target `south` — passing any other direction, or `directions` at all to the
 API for a 1-direction object, is what the endpoint itself 400s on.
 Regenerating an already-animated direction is simpler than `character`'s
 own "find and delete the prior take" dance: `/objects/{id}/animations` has
-its own `replace_existing` flag, which PixelKiln always passes. **Cost is
-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.
+its own `replace_existing` flag, which PixelKiln always passes. **Cost: the
+base is measured** (32px billed 6 and returned 8 files, November 2026) —
+`objectProCost()` prices it identically to `character` pro-flash's own
+measured formula (`proFlashCharacterCost`), since the request bodies are
+near-identical minus `template_id`. States and `pro` animations are still
+that assumption, pending a live check.
 `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
@@ -318,10 +318,11 @@ dedicated "state" mechanism — it is a plain `revision` (image-to-image) of
 the base panel, the same mechanism every other generator already has.
 **Cost: confirmed live at one data point.** A real 256×192 call against a
 Tier 2 account billed exactly 20 generations (balance 4979.8 → 4959.8),
-matching the low end of the `create_ui_asset` MCP tool's "20–40 generations"
-claim. No dedicated cost branch exists, so pixelkiln still estimates it with
-the same canvas-tier formula `1dir`/`tiles` use — which predicts the 40
-ceiling for every valid `uiAsset` size, since the 192px floor already clears
+matching the low end of the `create_ui_asset` MCP tool's then "20–40
+generations" claim (PixelLab cut it to 10–25 in October 2026). No dedicated
+cost branch exists, so pixelkiln still estimates it with the same
+canvas-tier formula `1dir`/`tiles` use — which predicts the 25 ceiling
+for every valid `uiAsset` size, since the 192px floor already clears
 that formula's own top tier. The measured call disproves the formula for
 this generator (it billed the floor price at an area where `1dir`/`tiles`
 would bill the ceiling), but the estimate is left as-is, an intentional
@@ -332,9 +333,10 @@ the prompt, no `pieces`/`elements` layout, sizes from 16×16 (up to 792 wide,
 688 tall, aspect-gated upstream). A style's one `styleImages` entry becomes
 the `concept_image` (design guidance); `uiColorPalette` is sent as
 `color_palette`. Reach for it over `uiAsset` for icons, slots, and small
-widgets under `uiAsset`'s 192px floor. Unmeasured: the plan borrows the
-10/15/25 canvas tiers, and the completed job's shape has not been observed
-live.
+widgets under `uiAsset`'s 192px floor. A 32×32 call billed 10 and returned
+64 candidates (November 2026); the plan borrows the 10/15/25 canvas tiers and
+counts candidates by size (`uiElementCandidateCount`), and sizes other than
+32px are unbilled.
 
 `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
@@ -529,17 +531,17 @@ written as a set (a character's directions, an animation's frames) goes to
 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
+at a 32×32 source — `animate`/`animate-pixminimax`/`interpolate`/
+`edit-animation` remain schema-only and unexercised.
+`animate-skeleton` has run live (8 frames billed exactly 3); its request
+field names come from the `animate_with_skeleton_v3` MCP tool schema, a more
+authoritative source than the OpenAPI document the others are taken from, and
+the run found `description` is required. `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.
+animation entry for why composing two 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
@@ -621,7 +623,11 @@ high-fidelity showcase asset) rather than a default, read
 [pixellab-fidelity.md](./pixellab-fidelity.md) before choosing `size`,
 `detail`, `shading`, or `outline`. For what PixelLab can do that this adapter
 does not yet reach at all, read [pixellab-roadmap.md](./pixellab-roadmap.md)
-before proposing new work.
+before proposing new work. To pick which PixelLab endpoint to spend a live run
+on, read the [validation
+ledger](https://pixelkiln.griffen.codes/docs/endpoints#validation-ledger)
+(`docs/ENDPOINTS.md`): it rates each endpoint by what has been measured and
+what a wrong guess could cost.
 
 For setup and current field constraints, use
 <https://pixelkiln.griffen.codes/docs/pixellab>. When working in the PixelKiln