pixelkiln 0.86.2 → 0.87.0

package/docs/CHARACTERS.md

@@ -69,7 +69,7 @@ asset, that PixelLab draws facing 4 or 8 directions. `mode` picks the
 engine: `standard` (1 generation, the skeleton template, `outline`,
 `shading`, and `detail` as soft guidance, and `palette` sent as a colour
 reference), `v3` (2 to 9 by size, the highest quality, up to 256px),
-`pro` (20 to 40 by size), or `pro-flash` (6 to 17 by size: PixelLab's
+`pro` (10 to 25 by size), or `pro-flash` (6 to 17 by size: PixelLab's
 newest image model draws the south sprite and v3 rotates it; sizes are
 multiples of 4 up to 256, `template` may be `custom`, and a `reference`
 pays for the rotations only, 1 at 64px). `size` is the character's size;
@@ -380,7 +380,7 @@ attached to that character's own PixelLab record:
 result sizes (16, 32, 48, 64, 128, or 160 — 128 and 160 render at 2K and cost
 more), independent of the style's own `size`. A portrait takes no prompt: it
 is drawn from the parent's pixels, not text, so it is priced and generated
-like a state, 20 to 40 generations by the size tier (a 16px portrait billed
+like a state, 10 to 25 generations by the size tier (a 16px portrait billed
 exactly 20, the floor, in a live test; see [`docs/ENDPOINTS.md`](ENDPOINTS.md)).
 It lands as `<asset>.png`, one file like a single-direction generator, and
 `pixelkiln fetch` also attaches it to the parent's character record upstream

package/docs/CLI.md

@@ -53,6 +53,7 @@ Which command:
 | 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` |
+| turn a photo, painting, or render into pixel art | `pixelkiln pixelate --from renders/lodge.png --out art/lodge.png` |
 | generate a pixel font (`.ttf` plus glyph atlas) | `pixelkiln font --description "warm orange arcade font" --out fonts/arcade` |
 | start an `animate-skeleton` keypoints file from an image | `pixelkiln estimate-skeleton poses/hero.png --out poses/hero-swing.json` |
 | see a keypoints file's poses over the source before paying | `pixelkiln skeleton-preview hero-swing` |
@@ -163,11 +164,14 @@ native aspect ratios, uses exact integer zoom for small art, fits large work,
 and centers the decision surface on wide displays. A revision row shows its
 parent source beside the new candidates, and a regeneration (`gen --force`)
 shows the art it would replace beside them while that file is still on disk,
-so the question is "is this better?" rather than "is this good?". A ComfyUI
-frame set appears as an
+so the question is "is this better?" rather than "is this good?". A frame set
+(a ComfyUI frame set, a PixelLab animation, or a frame-set revision such as
+`animate-skeleton`) appears as an
 animated ordered strip and is accepted or left unresolved as a unit. Its preview
 can be paused, starts paused when reduced motion is enabled, and stops while it
-is offscreen. Arrow keys navigate, Enter selects, 1–9 choose directly, and 0
+is offscreen. Frames and candidates the provider decoded to a local cache are
+served by the review server itself, since a localhost page may not load a
+`file://` image. Arrow keys navigate, Enter selects, 1–9 choose directly, and 0
 leaves a row unresolved. Only rows submitted
 with **Apply selections** are written to the lockfile. Closing the window applies
 nothing. See the [Getting started guide](GETTING_STARTED.md#start-a-new-project)
@@ -989,6 +993,36 @@ common cause of disappointing output from every endpoint that takes one.
 - `--json` prints the detected zoom factor and both sizes; `--dry-run` sends
   nothing.
 
+### `pixelate`
+
+```bash
+pixelkiln pixelate --from renders/lodge.png --out art/lodge.png --description "light dithering"
+```
+
+Converts a photo, painting, or render into pixel art with PixelLab's Image to
+Pixel Art Pro Flash (`/image-to-pixelart-pro-flash`). It works on source art
+that was never pixel art. For pixel art that was only upscaled, use `unzoom`,
+which recovers the grid instead of redrawing it.
+
+- PixelLab picks the output size from the source's detected pixel scale; there
+  is no size option. A 256x256 render came back 108x109 and a 384x384 render
+  84x110. Sources over 2048px on the longer side are scaled down upstream.
+- The result keeps transparency: both opaque renders measured came back with
+  the subject cut out.
+- `--description` optionally steers the style, e.g. `"retro vibes with light
+  dithering"`.
+- A flat **6 generations**, confirmed against a live bill. The command prints
+  that and asks first; `--yes` skips the question, `--budget <n>` refuses when
+  `n` is below it, and `--dry-run` sends nothing.
+- `--out` defaults to `<input>.pixel.png` beside the input, and the input is
+  never overwritten. An existing `--out` is replaced only with `--force`.
+- `--json` prints the job id, both sizes, the PixelLab gallery `imageId`, and
+  the billed usage.
+
+Like `unzoom`, it writes a loose file and leaves the lockfile alone. Declare
+the result as an asset's `source`, or use it as a `styleImages` or
+`reference` path, to bring it into a manifest.
+
 ### `font`
 
 ```bash
@@ -1004,8 +1038,8 @@ writes the same two files.
 - `--weight` is `Bold` or `Regular` (default); `--glyph-px` is the native glyph
   size, `8`, `16` (default), `32`, or `64`; `--name` sets the font family name
   (PixelLab otherwise uses the description plus the weight).
-- Costs PixelLab's documented 25 generations, not yet confirmed against a
-  live bill. The command prints that and asks first; `--yes` skips the
+- Costs PixelLab's documented 15 generations (25 before PixelLab's October
+  2026 Pro price cut), not yet confirmed against a live bill. The command prints that and asks first; `--yes` skips the
   question, `--budget <n>` refuses when `n` is below it, and `--dry-run` sends
   nothing.
 - It waits for the job (PixelLab documents 30-80 s) and then downloads both
@@ -1092,13 +1126,13 @@ Print the package version. `-v` is an alias.
 | `--provider <id>` | balance/adopt/salvage/purge/workspace add | Select the account provider for a mixed manifest, or set the workspace catalog's default provider hint. |
 | `--account <label>` | workspace add | Free-form account label, e.g. distinguishing sandboxes. |
 | `--all` | salvage dry run | List every unclaimed object rather than the first 30. |
-| `--from <path>` | init/refine/quality check/unzoom | Existing source tree for init; source PNG or quality record for one-file refine mode; baseline for quality check; the upscaled image for unzoom. Omit it to use manifest `style.quality`. |
+| `--from <path>` | init/refine/quality check/unzoom | Existing source tree for init; source PNG or quality record for one-file refine mode; baseline for quality check; the upscaled image for unzoom; the photo or render for pixelate. Omit it to use manifest `style.quality`. |
 | `--exclude <names>` | init | Directory/name fragments to exclude; repeatable. |
 | `--generator <name>` | init | Generator assigned to the scaffolded style. |
 | `--name <name>` | init/font | Project name for the scaffolded manifest, or the generated font's family name. |
 | `--write-prompts` | adopt | Recover provider prompts into the manifest. |
 | `--port <n>` | pick/salvage/gallery | Local review or gallery server port; otherwise chooses a free port. |
-| `--out <path>` | pack/export/refine/recipe install/quality snapshot/unzoom/font | Output base override, final native PNG for path-mode refine, exact recipe destination, quality baseline path, the unzoomed PNG, or the font's `<base>.ttf`/`<base>.png`. Export requires one selected tileset. |
+| `--out <path>` | pack/export/refine/recipe install/quality snapshot/unzoom/pixelate/font | Output base override, final native PNG for path-mode refine, exact recipe destination, quality baseline path, the unzoomed or pixelated PNG, or the font's `<base>.ttf`/`<base>.png`. Export requires one selected tileset. |
 | `--inputs <path>` | pack/quality snapshot | JSON input array; requires `--out`. Quality cases use `{ id, path, record?, tolerances? }`. |
 | `--columns <n>` | pack/export | Grid columns, 1–1024; default is near-square. |
 | `--format <name>` | export, pack, mount | `export`: `generic` (default), `tiled`, or `godot` (TileSet). `pack` and `mount`: `generic` (default), `aseprite` (sheet JSON), or `godot` (SpriteFrames). |
@@ -1117,7 +1151,7 @@ Print the package version. `-v` is an alias.
 | `--note <text>` | refine approve | Optional review note stored in the quality companion. |
 | `--model-root <path>` | recipe verify | ComfyUI `models` directory. Enables streamed hash checks for every external model declared by the recipe. |
 | `--quantize <n>` | unzoom | `0` auto-detects a palette (default), `-1` keeps every color, `2`-`256` quantizes to exactly that many. |
-| `--description <text>` | font | The font's style, e.g. `"warm orange arcade font"`. |
+| `--description <text>` | font/pixelate | The font's style, e.g. `"warm orange arcade font"`, or an optional style steer for pixelate. |
 | `--weight <w>` | font | `Bold` or `Regular` (default). |
 | `--glyph-px <n>` | font | Native glyph size: `8`, `16` (default), `32`, or `64`. |
 | `--generation <n\|hash>` | restore | Bring a replaced generation back: `1` is the most recently replaced, or a prefix of one of its output hashes. One asset at a time. |

package/docs/ENDPOINTS.md

@@ -38,17 +38,22 @@ matters most for icon and prop work.
 | `create-image-pixen` | **1** | sync (~40s) | no | no | Best raw detail at 1 generation |
 | `create-image-bitforge` | **1** | sync (~20s) | yes | yes | Best on paper, poor in practice |
 | `map-objects` | **1** | job (~30s) | rejected | no | Fine when the prompt carries the style |
-| `create-1-direction-object` | **20–40** | job | no | yes | Only when you need rotations |
+| `create-1-direction-object` | **10–25** | job | no | yes | Only when you need rotations |
 | `generate-with-style-v2` (Pro) | **20** | job (~150s) | no | yes | Real style transfer |
-| `generate-image-v2` (Pro) | **40** | job (~150s) | no | yes | Real style transfer |
+| `generate-image-v2` (Pro) | **10–25** | job (~150s) | no | yes | Real style transfer |
 
-`1dir` prices by canvas area: ≤1024 px = 20, ≤2048 px = 25, larger = 40. A
-64×64 icon therefore costs 40. Every other generator above is a flat 1–40
-regardless of size.
+`1dir` prices by canvas area: ≤1024 px = 10, ≤2048 px = 15, larger = 25. A
+64×64 icon therefore costs 25. These are October 2026 prices; see [the Pro
+price cut](#october-2026-pro-price-cut) below for what changed and what was
+re-measured. `generate-with-style-v2`'s 20 predates the cut and has not been
+re-measured.
+
+`generate-image-v2` was a flat 40 at any size until the cut. It now tiers by
+canvas like the other Pro tools: a 64×64 call billed exactly 10.
 
 `generate-image-v2` is wrapped by pixelkiln's `imagePro` generator
 (skills/pixelkiln/references/pixellab.md): non-square and larger canvases
-than `pixflux` allows, at the flat 40 above. Its `reference_images` and
+than `pixflux` allows, at the 10–25 above. Its `reference_images` and
 `style_image` are not modeled, and its completed job's response shape is
 inferred from `edit-images-v2`'s (also unmeasured for this endpoint
 specifically) rather than confirmed live — see `pollImagePro` in
@@ -188,6 +193,76 @@ description claims 0.1 generations, the same as the rest of the tier.
 
 ---
 
+## Image to Pixel Art Pro Flash, measured
+
+`POST /image-to-pixelart-pro-flash` (added in PixelLab 0.4.128, October
+2026) converts a photo, painting, or render into pixel art. Unlike
+`image-to-pixelart` above, it takes no size: PixelLab detects the source's
+pixel scale and picks the output size. The only other fields are an optional
+`description` that steers the style and a `seed`. Sources over 2048px on the
+longer side are scaled down upstream.
+
+Measured live, October 2026:
+
+| Source | Description | Output | Billed |
+|---|---|---|---|
+| 256×256 opaque render (a knight) | none | 108×109, transparent background | **6** |
+| 384×384 opaque render (a mountain keep) | "light dithering" | 84×110, transparent background | **6** |
+
+- It is a background job. The submit response carries `estimated_generations:
+  6`, `pricing_provisional: true`, and `image_id`/`source_image_id` (the result
+  is also saved to the PixelLab gallery). `usage` on the submit is null.
+- The completed job has `usage: {type: "generations", generations: 6}` and the
+  image at `last_response.images[0]` as `{type, base64, width, height}`.
+  `last_response.original_images[0]` is the same size, before PixelLab's
+  final "touching up pixels" pass. pixelkiln reads `images[0]`.
+- Unlike `image-to-pixelart`, it keeps alpha: both opaque renders came back
+  with the subject cut out on transparency.
+
+Wired up as `pixelkiln pixelate`, a standalone command on a loose file like
+`unzoom`; see [the CLI reference](./CLI.md#pixelate). Use `unzoom` instead
+for art that is already pixel art and was only upscaled.
+
+---
+
+## October 2026 Pro price cut
+
+PixelLab 0.4.128 (October 2026) cut every Pro tool's price ladder from
+20/25/40 to **10/15/25** generations. The release notes give the new tiers
+by side: 16–256px is 10, 256–384px is 15, 384–512px is 25. PixelLab's
+OpenAPI now quotes "10–25 generations" for 1- and 8-direction objects, Pro
+characters, and Pro object animations, and 15 for `generate-font-pro`
+(previously 25).
+
+**Only the prices moved, not the breakpoints.** The release notes put
+352px and 384px in the middle tier, but both billed the top tier (25) when
+re-measured on `inpaint-v3` after the cut, exactly where the old bisection
+below put the boundary. pixelkiln's estimates use the new prices on those
+measured breakpoints. Every historical measurement on this page that says
+20, 25, or 40 predates the cut and is kept as a record.
+
+Re-measured after the cut:
+
+| Endpoint | Canvas | Before | After |
+|---|---|---|---|
+| `generate-image-v2` | 64×64 | 40 (flat at any size) | **10** |
+| `inpaint-v3` | 256×256 | 20 | **10** |
+| `inpaint-v3` | 288×288 | 25 | **15** |
+| `inpaint-v3` | 352×352 | 40 | **25** |
+| `inpaint-v3` | 384×384 | 40 | **25** |
+
+`generate-image-v2` is no longer flat; pixelkiln now prices it with
+`proTierCost` (≤65536px² is 10, ≤102400px² is 15, larger is 25), the same
+function `inpaint-v3` and `edit-images-v2` revisions use.
+
+**Create VFX** shipped in the same release as an experimental web tool
+(`pixellab.ai/create-vfx`). As of October 2026 it has no REST endpoint in
+`/v2/openapi.json` and no MCP tool; PixelLab says the MCP tool is coming.
+pixelkiln cannot wrap it until one of those exists; see the
+[roadmap](../skills/pixelkiln/references/pixellab-roadmap.md).
+
+---
+
 ## Tilesets: schema only, not yet measured
 
 Called out separately because these are the most capable endpoints for level art
@@ -385,7 +460,7 @@ constraint, not a hint: 130 badges across two sets came back containing *only*
 the requested colours.
 
 **Re-roll one bad asset.** 1 generation. `gen --only <id> --force`. Cheaper than
-asking for more candidates. A `1dir` call that yields 16 candidates costs 20–40.
+asking for more candidates. A `1dir` call that yields 16 candidates costs 10–25.
 
 **Clean up fringing.** `remove-background` at 1 generation, and it will not
 disturb the palette.
@@ -394,7 +469,8 @@ disturb the palette.
 size. Do not use `resize`.
 
 **Anchor to an existing look rather than a palette.** `generate-with-style-v2`
-(20) or `generate-image-v2` (40). `bitforge` claims to do this for 1, but see
+(20 before the October 2026 cut, not re-measured) or `generate-image-v2`
+(10–25). `bitforge` claims to do this for 1, but see
 above. `map` has no style anchoring at all. A 1-bit set generated through it
 came back with a yellow star and a brown chocolate bar.
 
@@ -562,8 +638,8 @@ Listed so the gaps are known rather than assumed away:
   neither schema carries a usage example.
 - `/generate-font-pro` (+ `GET /generate-font-pro/{job_id}`) — an 80-glyph
   atlas PNG plus a `.ttf` from a style description, `weight`
-  (`Bold`/`Regular`), and `glyph_px` (8/16/32/64). Documented at 25
-  generations, unmeasured. Wired up as `pixelkiln font`, outside the
+  (`Bold`/`Regular`), and `glyph_px` (8/16/32/64). Documented at 15
+  generations since the October 2026 cut (25 before), unmeasured. Wired up as `pixelkiln font`, outside the
   manifest; see [the CLI reference](./CLI.md#font).
 - Everything else PixelLab's own tutorials demonstrate that this file has no
   entry for at all — "animation to animation" motion transfer,
@@ -575,7 +651,8 @@ Listed so the gaps are known rather than assumed away:
   `uiAsset` generator; cost confirmed live at one data point, 20 generations
   for a 256x192 canvas).
 - `image-to-pixelart-pro` takes only `image` + `description`, no size fields.
-  The non-Pro version is characterised above.
+  The non-Pro version is characterised above, and the Pro Flash version,
+  which pixelkiln wraps, [below](#image-to-pixel-art-pro-flash-measured).
 - the tileset family, with schema documented above and costs unmeasured
   (the standalone isometric tile endpoint alongside it now has one real
   measured data point — see above)

package/docs/GENERATORS.md

@@ -10,17 +10,17 @@ account; [ENDPOINTS.md](./ENDPOINTS.md) contains the detailed experiments.
 |---|---|---:|---|
 | Standalone prop or icon with arbitrary dimensions | `map` (default) | 1 generation | 1 |
 | 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 |
+| Candidate variety, richer rendering, future rotation/animation | `1dir` | 10–25 generations | 4–64 by size |
+| Ground tiles or connectable structural sets | `tiles` | 10–25 generations | variations or complete set |
+| Two-terrain Wang tileset for elevation (grass to water, floor to cliff) | `terrain` | 10–25 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 |
+| Larger or non-square scene or background, up to 792 wide and 688 tall | `imagePro` | 10–25 generations by canvas | 1–64 by size |
 | Controlled pose/expression sequence in ComfyUI | `frames` | 0 `free` provider units | one atomic ordered set |
 | 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 (2–4 as `skeleton-v3`), 20 per outfit (measured once) | one set of directions, one ordered loop, or one portrait |
+| A character facing 4 or 8 directions, its poses, and its animations | `character` | 1 per base (standard), 10–25 per pose or portrait, 1 per template loop (2–4 as `skeleton-v3`), 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 |
+| One UI element from a description, 16px and up, optionally guided by a concept image | `uiElement` | 10–25 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`
@@ -275,13 +275,13 @@ and regenerating the parent makes the child stale.
 |---|---:|---:|
 | base, `mode: standard` | create-character-with-4/8-directions | 1 |
 | base, `mode: v3` | create-character-v3 | 1 + ceil(size² × 8 / 65536): 2 at 64px, 3 at 128px; from a `reference`, the rotations alone on its canvas: 1 at 64px |
-| base, `mode: pro` | create-character-pro | 20–40 by canvas |
+| base, `mode: pro` | create-character-pro | 10–25 by canvas |
 | base, `mode: pro-flash` | create-character-pro-flash | image tier (5 to 96px, 6 to 208px, 9 above) + ceil(size² × 8 / 65536): 6 at 64px, 8 at 128px, 17 at 256px; rotations only from a `reference` |
-| state | create-character-state | 20–40 by canvas |
+| state | create-character-state | 10–25 by canvas |
 | animation with a `template` | animate-character | 1 |
 | animation from text (v3) | animate-character | ceil(size² × frames / 65536): 1 at 64px, 2 at 128px |
-| animation, `mode: pro` | animate-character | 20–40 by canvas |
-| portrait | portrait-character-pro | 20–40 by `size` (16px billed exactly 20 live) |
+| animation, `mode: pro` | animate-character | 10–25 by canvas |
+| portrait | portrait-character-pro | 10–25 by `size` (16px billed exactly 20 live, before the October 2026 cut) |
 | outfit | transfer-outfit-v2 | 20 (a 2-frame, 92×92 job billed exactly this live; not yet measured at other frame counts or canvases) |
 
 The 20–40 tiers are PixelLab's; the tier is resolved from the canvas when
@@ -450,7 +450,7 @@ Left as an over-read for `--budget` until a second size is measured; see
 `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):
+`pixflux`/`map` (1 generation, no style reference) and `imagePro` (10–25 by canvas):
 
 ```jsonc
 {
@@ -530,7 +530,7 @@ to 16×16, which suits icons and small widgets:
   `imagePro`'s.
 
 **Unmeasured.** The schema carries no usage example and no call has been
-billed yet. The plan prices it on the same 20/25/40 canvas tiers as
+billed yet. The plan prices it on the same 10/15/25 canvas tiers as
 `1dir`/`tiles`, the safe over-read for a Pro endpoint, and the completed
 job's shape is read defensively (`pollUiElement` names the keys it got if
 the shape is not the documented `images` list).

package/docs/LIBRARY.md

@@ -153,7 +153,13 @@ against `buildPlan` and the session budget and runs `submit`, `poll`, and
 and `applyReview` host the `pick` sheet for a job's waiting keys. The sheet
 itself comes from `prepareReview`, which `runPicker` also uses: it gathers the
 candidate groups, the local files the sheet may load, and the apply step,
-without an HTTP server of its own.
+without an HTTP server of its own. Those files (`session.assets`, exact route →
+path and content type) are revision sources, the art a regeneration replaces,
+and any frame or candidate the provider cached on local disk, such as
+PixelLab's decoded animation frames. A browser will not load a `file://` image
+into a page served over HTTP, so the sheet names each of those by its route,
+under `routePrefix` when one is given; a host that embeds the sheet must serve
+every route in `assets`. Hosted provider URLs reach the sheet unchanged.
 
 ## Hand edits and the in-browser editor
 

package/docs/MANIFEST.md

@@ -492,7 +492,7 @@ their own page: [Characters](./CHARACTERS.md) and
 | `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`: what the subject *looks like* (colours, clothing, held items) — the asset's own `prompt` is sent as the motion's short label instead. `remove-background`: a hint naming the foreground. Rejected on other modes. |
-| `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. |
+| `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 10–25, 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

@@ -69,16 +69,16 @@ unapproved files. See [Manifest quality profiles](./MANIFEST.md#quality-profiles
 |---|---|---:|
 | `map` | You need one prop, icon, building, or landmark at arbitrary dimensions | 1 generation |
 | `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) |
+| `1dir` | You need references or several candidates for human review | 10 to 25 generations |
+| `tiles` | You need ground variations or a connected structural set | 10 to 25 generations |
+| `terrain` | You need a two-terrain Wang tileset (grass to water, floor to cliff) | 10 to 25 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 |
+| `imagePro` | You need a larger or non-square scene, up to 792 wide and 688 tall | 10 to 25 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) |
+| `uiElement` | You need one UI element from a description, 16px and up | 10 to 25 generations (unmeasured) |
 
 `map` accepts these values:
 
@@ -93,7 +93,7 @@ channel before building a production batch. For a scenic background, use
 `pixflux` with `noBackground: false`.
 
 Read [Generator selection](./GENERATORS.md) for the full constraints and
-measured economics. "20 to 40 generations" is a tier, not an exact figure:
+measured economics. "10 to 25 generations" is a tier, not an exact figure:
 `poll` reads what a completed job actually billed and records it as `billed`
 beside the submit-time `cost` estimate a wave budget spends against;
 `pixelkiln history`, `plan --json`, and the gallery show both when they

package/docs/REVISIONS.md

@@ -593,7 +593,7 @@ 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.
+6 up to 208px, 9 beyond) instead of the 10–25 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
@@ -635,7 +635,7 @@ further — there is nothing to ask.
 - `interpolate` (`/interpolation-v2`) and `edit-animation`
   (`/edit-animation-v2`) are both documented "Pro" endpoints with no usage
   example in the schema and no live measurement. `estimate()` borrows the
-  same 20/25/40 canvas tiers the other unmeasured Pro edits use, sized on the
+  same 10/15/25 canvas tiers the other unmeasured Pro edits use, sized on the
   keyframe for `interpolate` and on the packed frame grid for
   `edit-animation` (four 32×32 frames price as a 64×64 canvas, the 40 tier).
   Over-reading is the safe direction for `--budget`; expect a live bill at or

package/package.json

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

package/skills/pixelkiln/SKILL.md

@@ -56,7 +56,10 @@ hashes.
 - 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.
+  takes a reference, and the unzoomed result is opaque. For outside art that
+  was never pixel art (a photo, painting, or render), `pixelkiln pixelate
+  --from <file> --out <file>` converts it with PixelLab's Image to Pixel Art
+  Pro Flash for 6 generations and asks first.
 - 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.
@@ -111,7 +114,7 @@ Read only the reference needed for the current decision:
 
 - For PixelLab configuration, generators (including `uiElement` for single UI
   pieces and `imageProFlash` for styled stills), costs, alpha behavior,
-  account operations, or the `unzoom`, `font`, `estimate-skeleton`, and
+  account operations, or the `unzoom`, `pixelate`, `font`, `estimate-skeleton`, and
   `skeleton-preview` utilities, read [references/pixellab.md](references/pixellab.md). For a
   PixelLab style aimed at a specific resolution or fidelity tier (retro,
   high-detail, or matching an existing set's look), read

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

@@ -55,7 +55,7 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   — a real gap, not a docs fix: `tiles`'s own `tileFeature: "tileset"` draws
   one terrain's edges, not two named, connected terrain levels with their own
   transition prompt. Closed by the `terrain` generator; see
-  `pixellab.md`. Cost is unmeasured (borrows the same 20/25/40 canvas tiers
+  `pixellab.md`. Cost is unmeasured (borrows the same 10/15/25 canvas tiers
   already confirmed for `tiles` and `1dir`); `/create-tileset-sidescroller`,
   reference images, `color_image`, and the `pro` pipeline's own tunables
   beyond `spreadX`/`slopeSize`/`raggedness` remain unmodeled.
@@ -161,7 +161,7 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   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 20/25/40 Pro canvas tiers.
+  frame set). Both unmeasured, both borrowing the 10/15/25 Pro canvas tiers.
   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
@@ -291,16 +291,30 @@ and which tutorial(s) demonstrated real (not hypothetical) demand for it.
   unconfirmed beyond the endpoint's existence. Closed by `pixelkiln font`, a
   standalone command rather than a generator: a font has no style suffix,
   candidates, or image-shaped primary output for the lockfile to track. The
-  documented 25-generation price is unmeasured.
+  documented price (15 since October 2026, 25 before) is unmeasured.
 - **Unzoom** (`/unzoom`, recover the native grid of upscaled pixel art) —
   PixelLab's own API overview calls upscaled reference art "the most common
   cause of disappointing output" from every reference-taking endpoint.
   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.
+- **Image to Pixel Art Pro Flash** (`/image-to-pixelart-pro-flash`, added in
+  PixelLab 0.4.128, October 2026) — converts a photo, painting, or render
+  into pixel art, choosing the output size itself. Closed by `pixelkiln
+  pixelate`, a standalone command on a loose file like `unzoom`, since its
+  input comes from outside the manifest. Billed a flat 6 generations live,
+  and unlike `image-to-pixelart` it keeps transparency
+  (docs/ENDPOINTS.md, "Image to Pixel Art Pro Flash, measured").
+- **October 2026 Pro price cut** — PixelLab 0.4.128 moved every Pro tool from
+  20/25/40 to 10/15/25 generations. Cost estimates now use the new prices,
+  and `imagePro` (`generate-image-v2`) is tiered instead of a flat 40: a
+  64x64 call billed 10 live. Re-measured `inpaint-v3` calls (256, 288, 352,
+  and 384px billed 10, 15, 25, 25) show the breakpoints did not move, despite
+  the release notes putting 352-384px in the middle tier (docs/ENDPOINTS.md,
+  "October 2026 Pro price cut").
 - **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
+  `imagePro`'s `generate-image-v2` (a flat 40 then, 10–25 since October 2026), 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
@@ -349,6 +363,18 @@ and 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.
 
+## Create VFX (experimental, no API yet)
+
+PixelLab 0.4.128 (October 2026) added Create VFX, an experimental web tool
+for pixel-art visual effects (`pixellab.ai/create-vfx`). As of that release it
+has no endpoint in `/v2/openapi.json` and no MCP tool; PixelLab's release
+notes say it "will be added for MCP". Effects are a real gap for game work
+(hit sparks, spell bursts, dust puffs), and pixelkiln's closest substitutes
+are an `animate` revision or an `objectPro` animation, neither built for it.
+Revisit once an endpoint appears: check its request shape, whether the
+result is a frame set or a sheet, and its cost, then decide between a
+generator (frames into a `pack`able set) and a loose-file command.
+
 ## Map Workshop (scene composition)
 
 PixelLab's actual scene-building surface: lay out a tile floor, place

package/skills/pixelkiln/references/pixellab.md

@@ -22,15 +22,15 @@ providers, or before any PixelLab account operation.
 |---|---|---:|
 | `map` | One prop, icon, building, or landmark, up to 400×400 | 1 generation |
 | `pixflux` | Closed palettes or full-bleed backgrounds up to 400×400 | 1 generation |
-| `1dir` | Reference-guided work or several candidates | 20–40 generations |
-| `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 |
+| `1dir` | Reference-guided work or several candidates | 10–25 generations |
+| `tiles` | Ground variations or connected structures | 10–25 generations |
+| `terrain` | A two-terrain Wang tileset for elevation (grass-to-water, floor-to-cliff) | Unmeasured; borrows the same 10–25 canvas tiers |
+| `imagePro` | A larger or non-square background/scene, or real style transfer | **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 |
 | `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** |
+| `uiElement` | One UI element (button, slot, bar, dialogue box) from the prompt, 16px and up, with an optional concept image | 10–25 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
@@ -140,9 +140,10 @@ ceiling in a corner also depends on aspect ratio, e.g. 512×512 for square or
 688×384 for 16:9), where `pixflux` tops out at 400×400 with no style
 reference at all. Set the asset's `width`/`height` for anything other than
 the style's default square. Unlike every other multi-candidate generator
-here, its cost is a **flat 40 generations regardless of size** (measured;
-`docs/ENDPOINTS.md`, "Single-image generators, measured") — `1dir` and
-`tiles` scale with canvas area, this does not. One call still returns
+here, it was a flat 40 generations at any size until PixelLab's October 2026
+Pro price cut; it now tiers by canvas at 10/15/25 like the other Pro tools,
+and a 64×64 call billed exactly 10 (`docs/ENDPOINTS.md`, "October 2026 Pro
+price cut"). One call still returns
 several candidates to pick from by the same size tiering as `1dir` (up to
 42px: 64, 43–85px: 16, 86–170px: 4, above 170px: 1), reached through the
 generic background-job endpoint the same way a `revision` is. Reference
@@ -260,7 +261,7 @@ the prompt, no `pieces`/`elements` layout, sizes from 16×16 (up to 792 wide,
 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
-20/25/40 canvas tiers, and the completed job's shape has not been observed
+10/15/25 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
@@ -270,7 +271,7 @@ provisional `/pro-flash/cost` quotes). Its lock entry keeps PixelLab's
 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.
+of 4, no `strength`), at the Pro Flash tier instead of the Pro endpoints' 10–25.
 
 Do not confuse pixelkiln's `map` generator with PixelLab's own "Map
 Workshop": `map` returns one static prop, icon, or building in a single
@@ -466,12 +467,16 @@ 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
+Four 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
+cost unmeasured). `pixelkiln pixelate --from <file> --out <file>` converts a
+photo, painting, or render into pixel art with Image to Pixel Art Pro Flash:
+PixelLab picks the output size, the result keeps transparency, an optional
+`--description` steers the style, and it costs a flat 6 generations
+(measured) after asking first. `pixelkiln font --description <text> --out <base>` writes a
+`.ttf` and an 80-glyph atlas for PixelLab's documented 15 generations, and
 asks first. `pixelkiln estimate-skeleton <image> --out <file>` starts an
 `animate-skeleton` keypoints file, and `pixelkiln skeleton-preview <asset>`
 draws its poses over the source for free. See `docs/CLI.md`, "PixelLab utilities".

package/skills/pixelkiln/references/revisions.md

@@ -17,7 +17,7 @@ Read this reference when an asset declares `revision`.
 - 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
+  against 10–25. The parent must be 32–256px per side in multiples of 4, and
   `strength` is refused. Other modes reject `engine`.
 - `remove-background` (PixelLab, one image up to 400x400, `removalTask`
   `simple` or `complex`, optional `description` hint) cuts the background out
@@ -71,7 +71,7 @@ Read this reference when an asset declares `revision`.
   `edit-animation` applies one prompt across a whole frame set (a cape added
   to every frame of a walk); its frame ceiling falls with frame size (16 up
   to 64px, 9 up to 80px, 4 up to 256px). Both land in candidate review and
-  are unmeasured; their plan cost borrows the 20/25/40 Pro tiers.
+  are unmeasured; their plan cost borrows the 10/15/25 Pro tiers.
 - Both PixelLab and ComfyUI can back a `revision`, not just ComfyUI.
   PixelLab's `reduce-colors`/`correct-pixelart` calls its own
   `/reduce-colors`/`/correct-pixelart` endpoints synchronously (no background