pixelkiln 0.46.0 → 0.47.0

package/docs/AGENTS.md

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

package/docs/ARCHITECTURE.md

@@ -55,19 +55,30 @@ named approval. Planning and doctor inspect the record without changing it.
 Pack and mount require current approval and include the record downstream.
 Tiles and provider-native animation remain outside this contract.
 
-## Revision dependency graph
-
-An asset revision adds an immutable edge from a child spec to a parent spec in
-the same style. Manifest loading rejects missing parents, self-references, and
-cycles. Resolution includes transitive parents even when `--only` selects just
-the child, chooses the parent's approved quality output when one exists, and
-hashes the parent and optional mask bytes into the child identity.
+## Dependency graph
+
+Four kinds of asset draw from another asset's generated bytes, and all four
+are edges from a child spec to a parent spec in the same style: a
+`revision` (image-to-image or inpaint from a still), a character `state` or
+`animation` (drawn by PixelLab from the character it holds, so the edge is
+to the parent's south-facing file), a `mirror` (a local left-to-right flip
+of the parent's files), and a pro base's `styleCharacter` (the look it
+follows). Manifest loading rejects missing parents, self-references, and
+cycles. Resolution includes transitive parents even when `--only` selects
+just the child, chooses the parent's approved quality output when one
+exists, and hashes the parent's bytes (and a revision's optional mask) into
+the child identity, so a regenerated parent makes its children stale rather
+than silently mismatched.
 
 Planning walks the graph from the child and reports `blocked` unless each
 parent is committed source, an intact current download, or a current approved
-quality output. Blocked work is not actionable and has zero planned spend. The
-submit boundary repeats the walk after queue and rate-limit waits, closing the
-gap between a printed plan and provider work.
+quality output. Blocked work is not actionable and has zero planned spend. A
+child whose parent is actionable in the same plan is deferred, and `gen`
+runs the plan in waves until nothing new becomes actionable. The submit
+boundary repeats the walk after queue and rate-limit waits, closing the gap
+between a printed plan and provider work. A mirror is the one edge with no
+provider on the far side: submit flips the files itself and records the
+parent's output hashes, and the plan compares those directly.
 
 Providers opt into revision modes through `supportsRevision`. The first
 implementation is ComfyUI: it uploads content-addressed inputs, binds only the

package/docs/CHARACTERS.md

@@ -0,0 +1,309 @@
+# Characters
+
+A `character` style holds one PixelLab character as three kinds of asset: a
+base drawn facing 4 or 8 directions, states that apply a pose or an outfit
+to every direction at once, and loops, one direction each. Each is an asset
+with its own lockfile record and files, so `plan` prices the cast, one `gen`
+runs it in waves, and `pack` writes every direction and loop for the engine.
+This page is the reference for the manifest shapes; the [manifest
+reference](./MANIFEST.md) covers the fields every asset shares.
+
+## The three shapes
+
+A cast in full, with a base, a state, and two loops. This is the robot on
+the [site](https://pixelkiln.griffen.codes/#characters), drawn the way the
+example says:
+
+![The robot facing south, south-west, west, north-west, north, north-east, east, and south-east](../website/public/sprites/characters/robot-8dir.png)
+
+```json
+{
+  "styles": {
+    "cast": {
+      "generator": "character",
+      "outDir": "art/characters",
+      "view": "side",
+      "size": 96,
+      "mode": "pro-flash",
+      "template": "custom"
+    }
+  },
+  "assets": {
+    "bot": {
+      "prompt": "small round orange robot with one blue eye, short jointed legs"
+    },
+    "bot.dented": {
+      "prompt": "shell dented and scuffed, one arm hanging loose, eye dim",
+      "state": { "of": "bot", "paletteFromReference": true }
+    },
+    "bot.walk": {
+      "prompt": "walking forward in place, short legs stepping, body bobbing slightly",
+      "animation": { "of": "bot", "direction": "south", "frames": 12, "fps": 12 }
+    },
+    "bot.jump": {
+      "prompt": "crouching down, springing up into the air with legs tucked, landing with a small bounce",
+      "animation": { "of": "bot", "direction": "south", "frames": 8, "fps": 12 }
+    }
+  }
+}
+```
+
+![The robot's resting pose and twelve frames of it walking](../website/public/sprites/characters/walk-loop.png)
+
+The robot is round, so its style names the `custom` skeleton template and
+its loops come from a sentence each on the v3 engine; a biped on the
+`mannequin` template could take a template loop instead
+(`"animation": { "of": "bot", "template": "walk" }`), one generation per
+direction. See [Animations](#animations).
+
+### The base
+
+A base is a prompt, wrapped in the style's prefix and suffix like any other
+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
+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;
+`view` is `low top-down` (the default), `high top-down`, or `side`;
+`template` picks the body. Each direction lands as
+`<asset>-<direction>.png`, south first.
+Standard mode draws on a canvas 28px larger than `size`, 14px of room on
+each side for animation (a 64px character comes back as 92px files, a
+104px one as 132px); the lock records the size asked for, and the files
+are what PixelLab drew.
+
+### Proportions, guidance, and isometric view
+
+Three more knobs shape a `standard` base. `proportions` is a preset
+(`chibi`, `heroic`, and so on) or multipliers on the mannequin's head,
+arms, legs, shoulders, and hips; it lives on the style and any base may
+override it, and only the mannequin template has proportions to set.
+`textGuidanceScale` (1 to 20, PixelLab's default 8) is how closely the text
+is followed, and applies to template loops as well. `isometric` draws the
+base and every loop in isometric view. The v3 and pro engines take none of
+the three for a base; a v3 style may still set the last two for its loops.
+A `v3` base takes `enhancePrompt` instead, which has PixelLab expand the
+prompt into a fuller one before drawing.
+
+### Starting from your own sprite
+
+A base can also start from your own sprite. `reference` names a
+manifest-relative PNG or JPEG of the character facing south, and PixelLab
+draws the other directions from it, with the prompt as guidance:
+
+```json
+"bot": { "prompt": "small round orange robot with one blue eye", "reference": "refs/bot-south.png" }
+```
+
+That is how the robot above was made the second time: its own south
+sprite handed back to pro-flash, which rotated it for 2 generations at 96px
+and left the south file pixel for pixel as it was.
+
+`standard` uses each image as it is, centred on its larger canvas, and
+generates the rest, so the image must be the style's `size` exactly; it
+accepts one image per direction
+(`{ "south": ..., "east": ... }`), and a quadruped template needs south and
+east. `v3` rotates one south image of up to 256px (its `template` must
+match the body in the image). `pro` rotates one south image of up to 168px
+through its `rotate_character` method. The reference's bytes are part of
+the base's identity, so a redrawn file makes the base stale, and the file
+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.
+
+### Concept images and style anchors (pro)
+
+The pro engine has two more ways in. `concept` on a base names a concept
+image (a painting, a photo, a sketch, up to 1024px) that seeds the design
+in place of the prompt alone (PixelLab's `create_from_concept`); the
+prompt still guides it. `styleCharacter`, on the style or a base, names a
+generated 8-direction character in the same style whose look the base
+follows (`style_character_id`); its south sprite becomes the style image
+unless a style image is also given. The anchor is a dependency like a
+loop's character: the base is `blocked` until the anchor is downloaded and
+current, `gen` runs it in the wave after the anchor lands, and a
+regenerated anchor makes every base drawn in its style `stale`. The anchor
+itself ignores the setting, so a style can name its own first character.
+PixelLab wants the base at least as large as the anchor's visible sprite
+and fails the job fast otherwise. A base rotating its own `reference`
+takes neither: the rotate method has one image slot and it is the
+character.
+
+### Style images (pro and pro-flash)
+
+Style images on a `character` style are a pro input: one image of up to
+168px that anchors the look of a `pro` base drawn from text or a concept
+(`create_with_style` and `create_from_concept` both take it), or one of
+up to 256px that a `pro-flash` base copies its look from, no larger than
+the character's `size` on either side (crop it to its subject), with
+`styleTraits` (`palette`, `outline`, `detail`, `shading`, each on by
+default) choosing which traits it lends. `standard` and `v3` have no such
+slot and refuse them; a base with a `reference` refuses them too, in
+either engine.
+
+### States
+
+A state is a text edit of an existing character, `state.of`, applied to
+every direction at once: a pose, an outfit, a held object. The prompt is
+the edit and goes to PixelLab as written, without the style's prefix and
+suffix, since the character already carries the look.
+`paletteFromReference` snaps the result to the parent's colours; `canvas`
+asks for a larger frame when the edit adds something big. A state costs 20
+to 40 by canvas and keeps the parent's directions. A state may be a state
+of another state.
+
+### Animations
+
+A template loop moves a skeleton, so it wants a body the skeleton fits: a
+biped on `mannequin`, or one of the quadruped templates. A character that
+is neither (a round robot, a slime) gets a walk from text on the v3
+engine instead; a template on it either fails upstream (`custom`
+template) or redraws the character as the biped it expected.
+
+An animation is one loop of one character (`animation.of`, a base or a
+state) in one `direction`. With a `template` (PixelLab's `walk`,
+`breathing-idle`, `running-8-frames`, and so on) it costs 1 and the
+template decides the frame count; without one the prompt is the motion and
+PixelLab's v3 engine draws `frames` frames (4 to 16, even, default 8) for
+`ceil(size² × frames / 65536)` generations, one at 64px. `keepFirstFrame`
+(on by default) stores the resting pose as frame 0, so 8 frames land as 9
+files, `<asset>-frame-00.png` onwards. `fps` is recorded with the frames
+for the gallery, `pack`, and the Godot and Aseprite formats; PixelLab does
+not keep one. An animation lands in review as an ordered set: `pick` shows
+the loop and accepts or rejects it whole. One asset per direction; declare
+another asset for another direction, or a [mirror](#mirrors) of this one
+for the direction that faces the other way.
+
+### Pose frames and other loop controls
+
+A v3 loop can start and end where you say. `startFrame` is a
+manifest-relative image of the pose to begin from instead of the
+character's rotation; `endFrame` is a pose to reach, and with it the loop
+interpolates from the start frame to that image (both up to 256px, and the
+end frame the same size as the start frame or, without one, as the
+character's rotation, which `plan` checks once the parent is on disk; the
+frames can still come back on a taller canvas when the motion needs it, as
+a 92px crouch did at 92×104). `subject` replaces the character's own description for this loop when it
+would mislead the model (a state that took the armour off), and
+`enhancePrompt` lets PixelLab expand the action into a fuller motion
+description first. A template loop takes none of those; it takes
+`outline`, `shading`, and `detail` overrides instead, over the character's
+own. The style's `palette` goes to every loop as a colour reference, as it
+does to a `standard` base, and `enforcePalette` still snaps the frames
+afterwards. Pose images hash into the loop's identity and are read again
+at submit time, like a base's `reference`.
+
+```json
+"bot.crouch": {
+  "prompt": "folding down onto its legs until it rests on the ground",
+  "animation": { "of": "bot", "direction": "south", "frames": 6, "endFrame": "poses/bot-crouched.png" }
+}
+```
+
+### How the family depends on the base
+
+States and animations depend on their parent the way a revision does. The
+parent must be downloaded and current before the child is actionable;
+`plan` reports the child as `blocked` and names the parent until then, and
+one `gen` runs the waves in order: bases, then states, then animations,
+under one budget. The
+child's identity includes the parent's generated south-facing file, so
+regenerating the parent makes every state and animation of it `stale`. A
+hand edit of the parent does not, because PixelLab draws the child from the
+character it holds, not from local bytes.
+
+Regenerating an animation clears PixelKiln's own earlier take of that
+direction on the character first, since PixelLab skips a direction that
+already exists. The lock records the animation and group ids PixelLab
+assigned, and the delete goes by those (PixelLab keeps the name PixelKiln
+gives a loop only for text animations, not template ones). Nothing else on
+the character is touched, and a base or state is never deleted by
+PixelKiln.
+
+### Palette and packing
+
+`enforcePalette` snaps every direction and every frame. `pack --style cast
+--format godot` writes a `SpriteFrames` with each direction of a base or
+state as a still and each animation as a looping set at its fps;
+`--format aseprite` does the same with `frameTags`.
+
+### Adopting a character from the account
+
+Characters that already exist on the account come under the manifest with
+`adopt`. Declare the asset with `remoteId` (the character id, or
+`<character id>#<animation group id>` for a loop; `get_character` in
+PixelLab's own tools shows both) and run `pixelkiln adopt`: it records the
+character, writes every direction and frame that is not on disk, and costs
+nothing. A base can also be matched by the bytes of its south-facing file.
+See [`adopt`](CLI.md#adopt).
+
+## Mirrors
+
+Each direction of a loop is its own generation, and a sprite walking east
+is the sprite walking west flipped. A `mirror` asset is that flip, made
+locally from the source asset's downloaded files:
+
+```json
+"bot.walk.west": {
+  "prompt": "walking forward in place, short legs stepping, body bobbing slightly",
+  "animation": { "of": "bot", "direction": "west", "frames": 12, "fps": 12 }
+},
+"bot.walk.east": { "mirror": "bot.walk.west" }
+```
+
+A full 8-direction set of one loop is then 5 generations (south, north,
+west, south-west, north-west) and 3 mirrors; a 4-direction set is 3 and 1.
+The mirror takes its shape from the source (a loop of the same character,
+facing the other way, at the same fps), needs no prompt, and costs
+nothing: `plan` lists it under the provider with a cost of 0 and `gen`
+flips it in the wave after the source lands. It has its own lock entry and
+files (`bot.walk.east-frame-00.png` onwards), so `pack`, the gallery, and
+an engine see an ordinary loop. Nothing is sent to the provider, and the
+account holds no east animation.
+
+The lock records a hash over the source's output hashes when the flip was
+made. A source that is regenerated, restored, or re-snapped makes its
+mirrors `stale`, and the next `gen` flips them again for free. A mirror
+whose files went missing is `stale` too; one that was hand-edited is
+`orphaned`, like generated art. A source that is not downloaded, current,
+and untouched blocks its mirrors.
+
+A loop facing south or north cannot be mirrored: the flip would be the same
+direction with its asymmetries swapped, not a new one. A single image or a
+frame set from any generator can be mirrored, and so can a base or state
+(every direction flipped and relabelled, so west becomes east). A tile set
+cannot; its edges carry meaning. Mirroring swaps handedness, so a character
+who holds a sword in the right hand holds it in the left when facing the
+mirrored way. Most games accept that; if yours does not, generate both
+sides. `adopt` skips mirrors, since there is nothing upstream to adopt.
+
+Engines that flip sprites at draw time (Godot's `flip_h`, Unity's
+`flipX`) do not need mirrored files at all. Declare only the directions
+you generate and flip in the engine; mirrors are for pipelines that want
+every direction on disk.
+
+## Working with a cast
+
+- `pixelkiln plan` shows a state or loop as `blocked` until its parent is
+  downloaded and current, and one `pixelkiln gen` runs the waves in order
+  (bases, then states, then loops and mirrors) under one budget; see
+  [`gen`](./CLI.md#gen).
+- Loops land in review as ordered sets; `pixelkiln pick` accepts or rejects
+  a set whole.
+- Characters that already exist on the account come under the manifest with
+  [`adopt`](./CLI.md#adopt), by `remoteId` or by the bytes of a south file.
+- A character edited in PixelLab's own editor comes back with
+  [`fetch --refresh`](./CLI.md#fetch), which re-resolves the character's
+  current URLs first.
+- `pixelkiln gallery` shows the family: states under their base, loops with
+  their direction, mirrors with their source; see
+  [`gallery`](./CLI.md#gallery).
+- `pack --format godot` and `--format aseprite` write each direction as a
+  still and each loop as a looping set at its fps; see
+  [engine formats](./ARTIFACTS.md).
+- Costs per engine are in the [generator table](./GENERATORS.md#character),
+  and what the live runs measured is in [Measured
+  endpoints](./ENDPOINTS.md#characters-measured).

package/docs/CLI.md

@@ -17,7 +17,7 @@ work. The experimental `comfyui` adapter runs committed API-format `map` and
 ordered still-frame workflows on a self-hosted server. The experimental `scenario` adapter runs
 hosted still models with Compute Unit preflight and durable asset recovery.
 
-## Which command
+Which command:
 
 | I want to | Run |
 |---|---|
@@ -25,6 +25,8 @@ hosted still models with Compute Unit preflight and durable asset recovery.
 | generate everything the manifest still needs | `pixelkiln gen --budget 40` |
 | hold every generated file to the style's palette | set `"enforcePalette": true` on the style, then `pixelkiln fetch` |
 | draw a character in 8 directions, then its poses and loops | a `character` style with `state` and `animation` assets; one `pixelkiln gen` runs the waves |
+| rotate your own sprite into 8 directions | `"reference": "refs/bot-south.png"` on the base; `mode: pro-flash` does it for 1 generation at 64px |
+| get the east-facing loop without paying for it | `"bot.walk.east": { "mirror": "bot.walk.west" }` |
 | generate one asset, or one style | `pixelkiln gen --only anvil --budget 2`, `pixelkiln gen --style neon --budget 20` |
 | finish a run that was interrupted | `pixelkiln plan`, then the `next:` command it prints (`poll`, `pick`, or `fetch`) |
 | choose among candidates the provider returned | `pixelkiln pick` |
@@ -113,8 +115,9 @@ PixelKiln validates the complete budget set before submitting the first group.
 
 `gen` runs in waves. A wave is the whole lifecycle for everything the plan
 can act on now. Once its downloads land, assets that were `blocked` on a
-parent (a character's states, then their animations; a revision of a still
-that was just made) become actionable, and the next wave takes them under
+parent (a character's states, then their animations and the mirrors of
+those; a pro base drawn in another character's style; a revision of a
+still that was just made) become actionable, and the next wave takes them under
 what is left of the same budget, asking the same "Spend ...?" question each
 time unless `--yes`. It stops when a wave finds nothing new, when a wave
 submits nothing, or when the remaining budget cannot cover the next wave; in
@@ -416,6 +419,8 @@ pixelkiln gallery --style environment --port 4180 --no-open
 pixelkiln gallery --json > generations.json
 ```
 
+#### What it shows
+
 The gallery is lock-first. A lock entry the manifest no longer declares still
 appears, marked `undeclared`, so paid work is never hidden; a declared asset
 with no entry appears as a placeholder so the page also shows what has not
@@ -431,10 +436,14 @@ provider, and never writes anything. Stop it with Ctrl+C. See the
 [Getting started guide](GETTING_STARTED.md#start-a-new-project) for a
 screenshot.
 
+#### `--json`: the snapshot as data
+
 `--json` prints the same snapshot to stdout without starting a server. It is
 the offline, machine-readable answer to "what has this project generated?" for
 scripts and agents; `--style` and `--only` narrow it the same way.
 
+#### `--edit`: change prompts and style fields
+
 `--edit` lets the page change *intent*: an asset's prompt (for every style or
 only the one being viewed), width, height, size, category, and tags; a style's
 prompt prefix, prompt suffix, palette, whether downloaded art is snapped to
@@ -462,6 +471,8 @@ pixelkiln gallery --edit
 pixelkiln gallery --edit --workspace pixelkiln.workspace.json
 ```
 
+#### Restore and regenerate from a record
+
 An `orphaned` record, one whose file is gone or changed after download, offers
 **Restore** (the recorded bytes back from the cache or the provider, no cost)
 and, for a changed file, **Regenerate**; both replacements say what they
@@ -476,6 +487,8 @@ no cost, the page's form of [`restore --generation`](#restore). Any `--budget`
 enables it, `0` included, and the current generation moves into the list so
 the restore can be undone.
 
+#### `--budget`: generate from the page
+
 `--budget <n|provider=n>` enables generation from the page under that session
 ceiling. It is the same `--budget` `gen` takes: one unkeyed amount when a run
 involves a single provider, or one keyed amount per provider for a mixed run,
@@ -494,6 +507,8 @@ out over the gallery, **Apply selections** writes the lockfile and downloads
 the chosen art, and unchosen rows stay in review exactly as with `pick`. A
 regeneration's sheet shows the current art beside the candidates.
 
+#### Compare records side by side
+
 **Compare** puts two to four records side by side at one shared zoom with
 their fields in rows (provider, generator, candidates, size, cost, prompt,
 dates, quality, hashes) and tints every row whose values differ. Shift-click
@@ -519,6 +534,8 @@ says how many. PixelLab's count follows the generator and size (`map` and
 `pixflux` return one image; a `1dir` style returns 4–64), so the header
 explains that instead of offering a number.
 
+#### Hand edits, in your editor or the browser
+
 With `--edit`, a record also gains **Edit by hand**, the page's form of
 [`pixelkiln edit`](#edit): it creates the edit file, declares it, and opens
 it in `PIXELKILN_EDITOR` or the OS default. The record then shows the generated
@@ -556,6 +573,8 @@ on the same file. The editor page runs same-origin under its own
 content-security policy and never sees the gallery's session token; the page
 does the write. `--no-editor` hides all of it and serves none of its routes.
 
+#### Pull changes made in PixelLab's editor
+
 A PixelLab `map` or `1dir` record also links to its account object (**Open in
 pixellab ↗**), where PixelLab's own editor can change it; with `--budget`
 (any amount; `--budget 0` allows provider contact and no spend) the record
@@ -568,6 +587,8 @@ pixelkiln gallery --edit --budget 80
 pixelkiln gallery --budget pixellab=40 --budget retrodiffusion=1.25 --workspace pixelkiln.workspace.json
 ```
 
+#### `--workspace`: every project in one gallery
+
 `--workspace <catalog>` shows every project the catalog registers in one
 gallery, the way `workspace status` reads them: no manifest is needed in the
 current directory, each project gets its own section and filter chip, and a

package/docs/COMFYUI.md

@@ -619,6 +619,74 @@ PixelKiln refuses missing nodes and inputs during the offline plan. It also
 clones the workflow before applying bindings, so one asset cannot mutate the
 next asset's request.
 
+## Manifest fields
+
+ComfyUI runs a committed API-format workflow on a self-hosted server. The
+workflow file is resolved relative to the manifest and its parsed content is
+part of the spec hash. Adapter success proves transport and output structure,
+not pixel-art quality. Use provider-neutral `pixelkiln refine` for native-grid,
+final-palette, and recorded audit checks. Prompt coverage and human 1× approval
+still require a person.
+
+```jsonc
+{
+  "name": "my-game",
+  "provider": "comfyui",
+  "styles": {
+    "local": {
+      "generator": "map",
+      "outDir": "assets/generated/local",
+      "seed": 31415,
+      "providerOptions": {
+        "comfyui": {
+          "workflowFile": "workflows/pixel-api.json",
+          "outputNodeId": "9",
+          "numImages": 4,
+          "bindings": {
+            "prompt": { "nodeId": "6", "input": "text" },
+            "width": { "nodeId": "5", "input": "width" },
+            "height": { "nodeId": "5", "input": "height" },
+            "batchSize": { "nodeId": "5", "input": "batch_size" },
+            "seed": { "nodeId": "3", "input": "seed" },
+            "composition": { "nodeId": "19", "input": "image" },
+            "controlStrength": { "nodeId": "20", "input": "strength" }
+          }
+        }
+      }
+    }
+  },
+  "assets": {
+    "mountain": {
+      "prompt": "a snowbound mountain pass",
+      "width": 768,
+      "height": 512,
+      "providerInputs": {
+        "composition": "controls/mountain-layout.png",
+        "controlStrength": 0.7
+      }
+    }
+  }
+}
+```
+
+Node IDs come from the exported workflow; they are not stable across unrelated
+workflows. Binding names beyond PixelKiln's built-ins are project-defined and
+an asset overrides one with a matching `providerInputs` value. A custom
+binding aimed at `LoadImage.image` or `LoadImageMask.image` treats its string as
+a manifest-relative PNG/JPEG, hashes it, and uploads it at submission. Other
+custom inputs accept a string, number, or boolean matching the workflow's
+placeholder type. Local paths never enter stable provenance.
+
+The current adapter supports `map` and ordered still-image `frames`, PNG output
+from one node, 1–16 `map` candidates, and dimensions from 16–4096px. A frame
+style uses `numImages: 1`; the varying input supplies 2–64 renders. It rejects
+manifest `styleImages` and `palette`;
+use custom image bindings for per-asset ControlNet or reference images, and keep
+shared model/LoRA/palette controls inside the workflow. See
+[Set up ComfyUI](COMFYUI.md) for the complete procedure, safe workflow, and
+quality limits. The 4096px adapter ceiling is not a recommended generation or
+native-art size.
+
 ## Plan, generate, and review
 
 ```bash

package/docs/ENDPOINTS.md

@@ -325,8 +325,39 @@ Listed so the gaps are known rather than assumed away:
 - the tileset family, with schema documented above and costs unmeasured
 - `create-isometric-tile`, `create-ui-asset`, `generate-font-pro`, all job-based,
   with response shapes not in the simple `{usage, image}` form
-- the character family beyond what the `character` generator uses (portraits,
-  outfit transfer, lip-sync, skeleton animation, Pro Flash)
+- the character family beyond what the `character` generator uses: portraits
+  (`portrait-character-pro` both ways, `/characters/{id}/portrait`), outfit
+  transfer (`transfer-outfit-v2`), lip-sync, skeleton animation, and
+  `source_image_id` on Pro Flash. The four creation engines, states, and
+  `animate-character` are covered in full; see the September 2026 measurements
+  below.
+
+## Characters, measured
+
+- Standard bases draw on a canvas 28px larger than `image_size` (64 → 92,
+  104 → 132). A `directions` reference is placed on it as is, centred, pixel
+  for pixel.
+- Pro Flash returns exactly the requested canvas, and refuses a `style_image`
+  larger than it ("Style image must fit the native canvas"). Its
+  `/pro-flash/cost` answer for `operation=character` was `image` 5 up to 96px,
+  6 from 100 to 208px, 9 at 224px and above, plus `rotations` equal to v3's
+  `ceil(side² × 8 / 65536)` on the padded square canvas; two live jobs (7 and
+  2) billed exactly the estimate. `first_frame` bills the rotations only.
+- A 64px `create-character-state` moved the balance by about 22 against the
+  20 to 40 tier documented; other jobs were running on the account, so it is a
+  rough number.
+- `animate-character` with `custom_start_frame` and `end_frame` may return
+  frames taller than the rotation (92 × 104 for a crouch). `enhance_prompt`
+  writes the expanded text into the animation's `animation_type`. A v3 text
+  loop on a 96px pro-flash base came back at 108 × 108.
+- Template loops need a skeleton template. On a pro-flash base with
+  `template_id: custom` a `walking-8-frames` job failed upstream at once; on
+  a round robot fitted to `mannequin` the same template returned a different,
+  humanoid character standing nearly still. A v3 text loop ("walking forward
+  in place, short legs stepping") kept the robot and walked. For anything
+  that is not a biped or one of the four quadrupeds, animate from text.
+- Request validation is strict: an unknown body field is a 422 listing every
+  problem at once, which is a free way to check a body's shape.
 
 ---
 

package/docs/GENERATORS.md

@@ -189,13 +189,13 @@ onwards, with the resting pose as frame 0 unless `keepFirstFrame` is off.
 `enforcePalette` snaps all of them. Since each direction of a loop is its
 own generation, declare the east-facing loop as a `mirror` of the west one
 (and each diagonal as a mirror of the other) and PixelKiln flips it locally
-for nothing; see [Mirrors](./MANIFEST.md#mirrors). `pack --format godot`
+for nothing; see [Mirrors](./CHARACTERS.md#mirrors). `pack --format godot`
 writes each base direction as a still and each animation as a looping set.
 The gallery
-labels a state or loop with its parent ("state of hero", "loop of
-hero.sit, east"), links parent and children in the record, and counts the
+labels a state or loop with its parent ("state of bot", "loop of
+bot.dented, east"), links parent and children in the record, and counts the
 family in the style header ("3 characters, 4 states, 6 loops"). See
-[Characters](./MANIFEST.md#characters).
+[Characters](./CHARACTERS.md).
 
 ## Style variants
 
@@ -208,8 +208,8 @@ separate output directory and separate lock keys:
   "neon": {
     "generator": "1dir",
     "size": 64,
-    "promptPrefix": "Neon-noir game icon: ",
-    "promptSuffix": ", magenta/cyan rim light, transparent background",
+    "promptPrefix": "neon-noir game icon",
+    "promptSuffix": "magenta/cyan rim light, transparent background",
     "styleImages": [{ "path": "art/style-refs/neon.png" }],
     "outDir": "art/neon"
   }

package/docs/GETTING_STARTED.md

@@ -69,7 +69,7 @@ implemented. Authenticated single-candidate RD Fast and RD Plus stills have
 passed from quote through validated download, provenance, and cache.
 Multi-candidate, tileset, GIF, and spritesheet live runs remain, so PixelLab
 remains the production adapter. See
-[Manifest reference](MANIFEST.md#experimental-retro-diffusion) for
+[Manifest reference](RETRO_DIFFUSION.md#manifest-fields) for
 provider options and current limits, or
 [provider comparison](../PROVIDERS.md) for selection guidance.
 
@@ -260,6 +260,30 @@ Repeated `--style`, `--only`, `--claims`, and `--output-role` flags accumulate;
 comma-separated values also work. Unknown flags are errors, so a misspelled
 filter cannot accidentally widen a paid run.
 
+## A character and its loops
+
+A `character` style holds a base drawn facing 4 or 8 directions, states (a
+pose, an outfit) applied to every direction at once, and loops, one
+direction each. Each is an asset with its own record and files:
+
+```json
+{
+  "styles": { "cast": { "generator": "character", "outDir": "art/cast", "size": 64, "mode": "pro-flash", "template": "custom" } },
+  "assets": {
+    "bot": { "prompt": "small round orange robot with one blue eye", "reference": "refs/bot-south.png" },
+    "bot.walk.west": { "prompt": "walking forward in place, short legs stepping", "animation": { "of": "bot", "direction": "west", "frames": 12, "fps": 12 } },
+    "bot.walk.east": { "mirror": "bot.walk.west" }
+  }
+}
+```
+
+`pixelkiln plan` prices it (1 generation to rotate the sprite, 1 for the
+loop, 0 for the mirror) and one `pixelkiln gen` runs the waves: the base,
+then the loop, then the flip. `pixelkiln pack --style cast --format godot`
+writes a `SpriteFrames` with every direction as a still and both loops.
+Regenerate the base and everything under it goes `stale`. See
+[Characters](./CHARACTERS.md) and [Mirrors](./CHARACTERS.md#mirrors).
+
 ## Automation
 
 Use machine-readable planning and auditing as build gates: