pixelkiln 0.63.0 → 0.65.0

package/docs/ARCHITECTURE.md

@@ -57,18 +57,23 @@ Tiles and provider-native animation remain outside this contract.
 
 ## Dependency graph
 
-Four kinds of asset draw from another asset's generated bytes, and all four
+Six kinds of asset draw from another asset's generated bytes, and all six
 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.
+`revision` (image-to-image or inpaint from a still), a character `state`,
+`animation`, or `portrait` (drawn by PixelLab from the character it holds
+or its south-facing file, so the edge is to that one file), a `mirror` (a
+local left-to-right flip of the parent's files), an `outfit` (PixelLab
+re-clothing a loop's whole frame set from a reference image, so the edge
+is to every one of the parent's files, not one), 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 for the
+single-file edges, so a regenerated parent makes its children stale rather
+than silently mismatched. A mirror and an outfit depend on the parent's
+*whole* output set instead, tracked outside `specHash` (see below), since
+there is no one file to hash at resolve time.
 
 Planning walks the graph from the child and reports `blocked` unless each
 parent is committed source, an intact current download, or a current approved
@@ -78,7 +83,10 @@ 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.
+parent's output hashes, and the plan compares those directly. An outfit
+records the same kind of hash over the parent's output set, but does call
+a provider (`transfer-outfit-v2`) and costs generations; `billed` and the
+usual lock lifecycle apply to it exactly as they do to a state or loop.
 
 Providers opt into revision modes through `supportsRevision`. The first
 implementation is ComfyUI: it uploads content-addressed inputs, binds only the

package/docs/CHARACTERS.md

@@ -340,6 +340,67 @@ Engines that flip sprites at draw time (Godot's `flip_h`, Unity's
 you generate and flip in the engine; mirrors are for pipelines that want
 every direction on disk.
 
+## Portraits
+
+A `portrait` asset is a bust made from a base or state's south sprite, and
+attached to that character's own PixelLab record:
+
+```json
+"mira.bust": { "portrait": { "of": "mira", "size": 64 } }
+```
+
+`of` names the base or state to portray; `size` is one of PixelLab's fixed
+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
+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
+(a separate, free call PixelLab does not make on its own) — useful for
+PixelLab's own tools, since the API otherwise has no way to read a
+character's portrait back once set.
+
+A portrait blocks until its parent is downloaded and current, and goes
+`stale` when the parent is regenerated, exactly like a state. It takes no
+`reference` or `concept` (those belong on a base) and no `state` or
+`animation` (a portrait is not one of those, and the three are mutually
+exclusive). Its view comes from the style, but only `low top-down`, `high
+top-down`, or `side` are valid — narrower than a `standard` base's own
+options, since the underlying endpoint takes a smaller set.
+
+The reverse tool, drawing a full character from a portrait image, is not
+implemented; see the open items in [`docs/ENDPOINTS.md`](ENDPOINTS.md).
+
+## Outfit transfer
+
+An `outfit` asset re-clothes an existing loop's frames with a reference
+outfit image, PixelLab's `transfer-outfit-v2`:
+
+```json
+"mira.walk.armored": {
+  "outfit": { "of": "mira.walk", "reference": "refs/armor.png" }
+}
+```
+
+`of` names the loop (an `animation` asset) to re-clothe; `reference` is a
+manifest-relative image of the outfit, 32 to 256px per side. An outfit takes
+no prompt (drawn from pixels, not text) and reads its source loop's own
+downloaded frames — 2 to 16 of them, PixelLab's own limit — rather than the
+character record, so it works even once the source's PixelLab job record
+has expired. It shares its source's width, height, and directions, and is
+priced and generated like a state or loop, not for free like a `mirror`:
+measured live at 20 generations for a 2-frame, 92×92 job (see
+[`docs/ENDPOINTS.md`](ENDPOINTS.md)), the floor of the same tier a state
+uses, not yet confirmed at other frame counts or canvases.
+
+An outfit blocks until its source loop is downloaded and current — the
+same rule a mirror's source follows, since both depend on a whole frame
+set rather than one file — and goes `stale` when the source is
+regenerated. It takes no `state`, `animation`, `portrait`, `reference`, or
+`concept` (those describe a different shape or belong on a base); a
+reference image change alone also makes it stale.
+
 ## Working with a cast
 
 - `pixelkiln plan` shows a state or loop as `blocked` until its parent is

package/docs/CLI.md

@@ -304,12 +304,15 @@ Review remote objects that no supplied lockfile claims. On shared accounts, pass
 every other project lock via repeatable `--claims`; sibling manifests are used
 to exclude objects matching another project's styles. `--dry-run --json`
 provides a scriptable inventory. Import, keep, and discard are review decisions;
-discard only tags an object. Pass `--provider` when the manifest uses more than
-one provider.
+discard only tags an object. Unclaimed characters are reviewed too, one card per
+base and its states, in the manifest's `character` styles; importing one writes
+its base, states, and loops and adopts them (see
+[Recovery](./RECOVERY.md#characters)). Pass `--provider` when the manifest uses
+more than one provider.
 
 ### `purge`
 
-Delete provider objects previously tagged `pixelkiln:discard`. It is separate
+Delete provider objects and characters previously tagged `pixelkiln:discard`. It is separate
 from salvage, lists targets, asks for confirmation, and refuses non-interactive
 deletion without `--yes`. Use `--dry-run` first. Pass `--provider` when the
 manifest uses more than one provider.

package/docs/ENDPOINTS.md

@@ -582,12 +582,11 @@ Listed so the gaps are known rather than assumed away:
 - `generate-font-pro`, job-based, with a response shape not in the simple
   `{usage, image}` form (wrapped by `pixelkiln font`, but its cost is not
   yet measured)
-- 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.
+- the character family beyond what the `character` generator uses: lip-sync,
+  skeleton animation, `portrait_to_character` (a full character from a bust),
+  and `source_image_id` on Pro Flash. The four creation engines, states,
+  `animate-character`, portraits, and outfit transfer are covered in full; see
+  the September 2026 measurements below.
 
 ## Characters, measured
 
@@ -615,6 +614,27 @@ Listed so the gaps are known rather than assumed away:
   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.
+- **`portrait-character-pro`** (`direction: character_to_portrait`, a full-body
+  sprite in, a bust out) is job-based: `POST` returns `background_job_id`,
+  `GET /portrait-character-pro/{job_id}` answers 423 while drawing and, once
+  `status: "completed"`, a `download_url` (its own `usage` is always `null`;
+  read the billed amount from `GET /background-jobs/{background_job_id}`
+  instead, same as every other job here). Not the couple-generations
+  "conversion" the name suggests: the smallest `result_size` (16px) billed
+  **20 generations**, the same order of magnitude as a state or `1dir`.
+  `POST /characters/{id}/portrait` (attaching a portrait image to a character
+  record) is a separate, synchronous, **free** call (`usage.generations: 0`);
+  its response is the only place the stored portrait's URL appears; the
+  character's own `GET /characters/{id}` never gains a portrait field, so
+  PixelKiln has to remember the URL itself. `character_to_portrait` and
+  `SetPortrait` are two independent calls with no automatic link between them.
+- **`transfer-outfit-v2`** (a reference outfit image plus 2–16 existing
+  frames back wearing it) is job-based the same way, polled through
+  `GET /background-jobs/{id}` only (no dedicated status endpoint). A 2-frame,
+  92×92 job billed **20 generations** — again a real generation cost, not a
+  cheap frame edit. The completed job returns the result frames inline as
+  base64 in `last_response.quantized_images`, not as storage URLs like every
+  other multi-frame result here.
 
 ---
 

package/docs/GENERATORS.md

@@ -221,12 +221,14 @@ system requests reduced motion and stops while it is offscreen. After approval,
 
 `character` is PixelLab's character family as managed assets: a base drawn
 facing 4 or 8 directions (from a prompt, or from your own south-facing
-sprite with `reference`), states (a pose, an outfit) that PixelLab applies
-to every direction of an existing character, and animations, one loop of
-one character in one direction. The three share one PixelLab character. A state
-or animation depends on its parent the way a revision does: the parent must
-be downloaded and current before the child can be submitted, and
-regenerating the parent makes the child stale.
+sprite with `reference`), states (a pose or a text-edited outfit) that
+PixelLab applies to every direction of an existing character, animations,
+one loop of one character in one direction, portraits, a bust made from
+the south sprite, and outfit transfers, an existing loop's frames
+re-clothed from a reference image instead of text. A state, animation,
+portrait, or outfit depends on its parent the way a revision does: the
+parent must be downloaded and current before the child can be submitted,
+and regenerating the parent makes the child stale.
 
 | Asset | PixelLab call | Cost |
 |---|---:|---:|
@@ -238,6 +240,8 @@ regenerating the parent makes the child stale.
 | 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) |
+| 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
 the job runs and reserved against the floor, so `plan` reports the tier the

package/docs/MANIFEST.md

@@ -436,7 +436,9 @@ their own page: [Characters](./CHARACTERS.md) and
       "prompt": "walking in place, short legs stepping",
       "animation": { "of": "bot", "direction": "west", "frames": 12, "fps": 12 }
     },
-    "bot.walk.east": { "mirror": "bot.walk.west" }     // flipped locally, 0 generations
+    "bot.walk.east": { "mirror": "bot.walk.west" },     // flipped locally, 0 generations
+    "bot.bust": { "portrait": { "of": "bot", "size": 64 } },  // no prompt; drawn from bot's pixels
+    "bot.walk.west.armored": { "outfit": { "of": "bot.walk.west", "reference": "refs/armor.png" } }
   }
 }
 ```

package/docs/PIXELLAB.md

@@ -156,10 +156,11 @@ comparing notes with someone using a different one:
 
 ## What is outside this adapter
 
-PixelLab offers more than PixelKiln currently exposes. Portraits, outfit
-transfer, lip-sync, and skeleton-driven animation are not part of this
-adapter. Characters, their states, and their animations are the `character`
-generator, with all four creation engines (standard, v3, pro, pro-flash),
+PixelLab offers more than PixelKiln currently exposes. Lip-sync and
+skeleton-driven animation are not part of this adapter. Characters, their
+states, their animations, their portraits, and outfit transfer onto their
+loops are the `character` generator, with all four creation engines
+(standard, v3, pro, pro-flash),
 reference sprites, concept images, style anchors, mirrors, and every
 `animate-character` control; see [Characters](./CHARACTERS.md). Masked
 inpainting and whole-image editing are the `revision` asset shape, not the

package/docs/RECOVERY.md

@@ -128,6 +128,37 @@ array to stdout and human diagnostics to stderr for piping into `jq`.
 Imported ids are derived from prompts and land under `_salvaged/`; review and
 rename them before treating them as stable application ids.
 
+### Characters
+
+Characters are account records of their own, outside the object listing, and
+salvage reviews them too. A base and the states made from it share a group
+upstream, so each unclaimed group is one card: the base's south rotation, with
+a line counting its directions, states, and loops. A group is unclaimed when
+none of its characters is in any supplied lockfile. A group with some members
+claimed (a project uses the base, say, but not a state) is left out and
+reported, since discarding the rest would delete states of a character in use;
+declare those states and run `pixelkiln adopt` instead.
+
+Groups go to the manifest's `character` styles, never to other styles: the
+only character style when there is one, otherwise the style whose prompt
+prefix or suffix the base's prompt carries. `--style <character style>` takes
+every unclaimed group. A manifest with no character style reports the groups
+and triages none of them. Account objects likewise never route to a character
+style, where an import would become a character base with nothing upstream.
+
+| Verdict | Effect on a character group |
+|---|---|
+| import | Add a base asset, one asset per state, and one loop asset per animation direction to the manifest, each with a `remoteId`, then adopt them: every rotation and frame is downloaded and gets a lock entry. |
+| keep | Add `pixelkiln:keep` to the base and every state. |
+| discard | Add `pixelkiln:discard` to the base and every state; does not delete. |
+
+An imported base is named from the character's name, its states
+`<base>_<state name>`, and its loops `<parent>.<animation>.<direction>`. A loop
+PixelLab recorded without an animation group id cannot be adopted by
+`remoteId` and is left out, with a line saying so. A base whose size differs
+from the style's gets its own `size`; a 4-direction character imported into an
+8-direction style keeps its four rotations.
+
 ## Shared workspace catalog
 
 For a single project, its own lockfile is the whole claim set. On a shared
@@ -190,9 +221,11 @@ pixelkiln purge
 pixelkiln purge --yes
 ```
 
-Only objects already tagged `pixelkiln:discard` are eligible. The command lists
-targets, asks interactively, and refuses non-interactive deletion without
-`--yes`. A shared account should be fully adopted/salvaged before purge.
+Only objects and characters already tagged `pixelkiln:discard` are eligible.
+The command lists targets, asks interactively, and refuses non-interactive
+deletion without `--yes`. A shared account should be fully adopted/salvaged
+before purge. A deleted character takes its animations with it; each state is
+its own record upstream, tagged and deleted on its own.
 
 ## Accept intentional spec prose changes
 

package/package.json

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

package/schema/manifest.schema.json

@@ -1388,6 +1388,53 @@
                 },
                 "minItems": 1
               },
+              "portrait": {
+                "type": "object",
+                "properties": {
+                  "of": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "size": {
+                    "type": "number",
+                    "enum": [
+                      16,
+                      32,
+                      48,
+                      64,
+                      128,
+                      160
+                    ],
+                    "default": 64
+                  }
+                },
+                "required": [
+                  "of"
+                ],
+                "additionalProperties": false
+              },
+              "outfit": {
+                "type": "object",
+                "properties": {
+                  "of": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "reference": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "additionalInstructions": {
+                    "type": "string",
+                    "maxLength": 2000
+                  }
+                },
+                "required": [
+                  "of",
+                  "reference"
+                ],
+                "additionalProperties": false
+              },
               "proportions": {
                 "anyOf": [
                   {

package/skills/pixelkiln/SKILL.md

@@ -94,7 +94,8 @@ ceilings copied from each plan group.
 Use the staged `submit` → `poll` → `pick` → `fetch` commands when resuming or
 debugging one phase. Use the plan's printed stage for paid work and `restore`
 for missing downloaded bytes, `adopt` for exact matches
-already in the provider account, and `salvage` for reviewed unclaimed objects.
+already in the provider account, and `salvage` for reviewed unclaimed objects
+and characters.
 Use `pack`, `mount`, or `export` only for the artifact format the project needs.
 Prefer a manifest quality profile when a whole style shares the final-art rule.
 Use `refine --from` only for a one-off candidate outside that contract, after

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

@@ -388,7 +388,8 @@ previously catalogued anywhere.
   `agent_inspect`/`agent_feedback`/`agent_help`) manage a *separate* PixelLab
   product — "deploy your own agent," confirmed directly from the live tool
   schemas — unrelated to game-asset generation. Nothing to build here.
-- Portraits, outfit transfer, and lip-sync/vocal-animation/talking-gif are
-  already named as out of scope in docs/PIXELLAB.md. Portrait and
-  outfit-transfer support exist on an internal branch stack not yet merged;
-  lip-sync and vocal animation have no in-flight work.
+- Lip-sync/vocal-animation/talking-gif are named as out of scope in
+  docs/PIXELLAB.md, with no in-flight work. Portraits (`portrait`) and outfit
+  transfer (`outfit`) are character asset kinds; see docs/CHARACTERS.md. They
+  were built and live-measured in September 2026 on a stacked branch that
+  never reached `main`, and were ported onto it later.