pixelkiln 0.5.0 → 0.7.0

package/docs/AGENTS.md

@@ -48,22 +48,24 @@ not a replacement:
 | PixelKiln library/CLI | Budgets, state, provenance, review, recovery, audit, and packaging. |
 | PixelLab adapter | The current production and live-tested generation backend. |
 | Retro Diffusion adapter | Experimental backend; authenticated paid single-still lifecycle plus mocked advanced-workflow tests. |
+| ComfyUI adapter | Experimental self-hosted still-image backend using a committed API-format workflow. |
 
 PixelKiln's core is provider-neutral, but PixelLab remains the only production
 and paid-generation-tested adapter. Retro Diffusion generation support is
 experimental. Paid RD Fast and RD Plus single-candidate stills have passed from
 quote through validated download and recovery. Multi-candidate, tileset, GIF,
 and spritesheet workflows still need representative live smoke tests. See
-[PixelLab vs. Retro Diffusion](../PROVIDERS.md) before choosing a provider for a
+[provider comparison](../PROVIDERS.md) before choosing a provider for a
 new project or a large environment asset. Once chosen, follow
 [Set up PixelLab](./PIXELLAB.md) or
-[Set up Retro Diffusion](./RETRO_DIFFUSION.md).
+[Set up Retro Diffusion](./RETRO_DIFFUSION.md), or
+[Set up ComfyUI](./COMFYUI.md).
 
 The installed skill keeps the shared safety workflow in `SKILL.md` and loads a
-focused reference only when needed: PixelLab, Retro Diffusion, or a project that
-uses both. Mixed-provider repositories should use separate manifests and
+focused reference only when needed: PixelLab, Retro Diffusion, ComfyUI, or a
+project that uses more than one. Mixed-provider repositories should use separate manifests and
 lockfiles so each plan and budget keeps its provider-specific unit. The
-[provider comparison](../PROVIDERS.md#use-both-providers-in-one-project) has a
+[provider comparison](../PROVIDERS.md#use-multiple-providers-in-one-project) has a
 complete layout and command example.
 
 ## Recommended first prompt

package/docs/ARCHITECTURE.md

@@ -5,7 +5,7 @@ PixelKiln separates provider mechanics from the project state machine:
 ```text
 manifest + lock + planning + review + recovery + artifact pipelines
 ──────────────────── Provider interface ─────────────────────────
-PixelLabProvider      RetroDiffusionProvider      FakeProvider      future adapters
+PixelLabProvider      RetroDiffusionProvider      ComfyUIProvider      FakeProvider
 ```
 
 Everything above the provider boundary is backend-neutral. URL shapes, auth
@@ -18,7 +18,10 @@ The committed manifest is intent. Resolution combines one style and one asset,
 loads/reference-hashes style images, applies overrides, chooses a provider-
 supported generator, and computes a deterministic spec hash. The hash excludes
 project root, output location, and tags but includes every pixel-affecting
-setting.
+setting. A provider may resolve local files before hashing. ComfyUI uses this
+hook to parse and hash workflow JSON without making a network request. The
+runtime graph can then be submitted without putting a machine-specific path in
+the stable identity.
 
 See [manifest reference](./MANIFEST.md).
 
@@ -126,7 +129,13 @@ an undefined method.
 an experimental still, tileset, and animation adapter. Authenticated RD Fast
 and RD Plus single-candidate still lifecycles have passed end to end. Its
 multi-candidate, tileset, GIF, and spritesheet paths retain mocked coverage
-pending paid live smokes. `FakeProvider` implements the same contract in memory, which
-keeps the paid pipeline testable without credentials or network access. See
-[library API](./LIBRARY.md) and
-[PixelLab vs. Retro Diffusion](../PROVIDERS.md).
+pending paid live smokes. `ComfyUIProvider` is an experimental self-hosted
+adapter. It resolves and hashes an API-format workflow offline, submits an
+input-bound clone, polls local history, and stores portable `comfyui://` output
+references so a lockfile does not retain a workstation hostname. It supports
+one still-image output node today. A core-node Stable Diffusion 1.5 graph has
+passed single-image generation, four-candidate queue detection, and cache-only
+recovery on Apple MPS. `FakeProvider` implements the same contract
+in memory, which keeps the pipeline testable without credentials or network
+access. See [library API](./LIBRARY.md) and
+[provider comparison](../PROVIDERS.md).

package/docs/CLI.md

@@ -10,9 +10,10 @@ separated values work too. This strict parsing prevents a misspelled filter
 from widening a paid run.
 
 The manifest's top-level `provider` field selects the provider for `plan`,
-`doctor`, and pipeline commands. It defaults to `pixellab`; the built-in
-`retrodiffusion` adapter is experimental and supports still-image
-`map`/`pixflux`, `tiles` sheets, and `animation` GIF/spritesheet work.
+`doctor`, and pipeline commands. It defaults to `pixellab`. The experimental
+`retrodiffusion` adapter supports still-image `map`/`pixflux`, `tiles` sheets,
+and `animation` GIF/spritesheet work. The experimental `comfyui` adapter runs
+committed API-format `map` workflows on a self-hosted server.
 
 ## Everyday pipeline
 
@@ -141,7 +142,8 @@ or download artwork.
 ### `balance`
 
 Show the manifest-selected provider's remaining balance and cost unit. Reports
-a capability error when an installed provider has no balance endpoint.
+a capability error when an installed provider, such as local ComfyUI, has no
+balance endpoint.
 
 ### `status`
 

package/docs/COMFYUI.md

@@ -0,0 +1,191 @@
+# Set up ComfyUI
+
+PixelKiln can run a committed ComfyUI workflow on a self-hosted server. This
+adapter is experimental. It supports still-image `map` jobs, one or more review
+candidates, local provenance, and cache-backed recovery. A core-node Stable
+Diffusion 1.5 workflow has passed single-image generation and a four-candidate
+review queue on Apple MPS. A higher-quality SDXL workflow has also passed four
+building and environment renders. ComfyUI Cloud is not part of this release.
+
+## Start ComfyUI
+
+Install and start ComfyUI using its
+[official installation guide](https://docs.comfy.org/installation/overview).
+PixelKiln connects to `http://127.0.0.1:8188` by default. Set a different URL
+only when ComfyUI listens elsewhere:
+
+```dotenv
+COMFYUI_BASE_URL=http://127.0.0.1:8188
+```
+
+No API key is required for the standard local server. Keep an unauthenticated
+server on loopback. If you expose it to another machine, put authentication and
+TLS in front of it, then point `COMFYUI_BASE_URL` at that protected endpoint.
+
+Check the connection without generating an image:
+
+```bash
+pixelkiln doctor
+```
+
+## Export an API-format workflow
+
+Build and test the workflow in ComfyUI first. Enable developer mode in ComfyUI
+settings, then use **Save (API Format)**. Commit the exported JSON beside the
+manifest or in a project workflow directory. PixelKiln reads the file during
+planning and hashes its parsed JSON, so a node or model change marks dependent
+assets stale even if the filename stays the same.
+
+The output node must expose an `images` array in ComfyUI history. A standard
+`SaveImage` node does this. Record these node IDs and input names from the
+exported JSON:
+
+- the positive text encoder's prompt input;
+- the latent image width, height, and batch-size inputs;
+- the sampler seed input, when the PixelKiln style declares a seed;
+- the final `SaveImage` node.
+
+Node IDs are workflow-specific. Do not copy IDs from an example without
+checking the exported file.
+
+The repository includes a working core-node
+[smoke project](../examples/comfyui/README.md). It uses the public checkpoint
+from ComfyUI's official first-generation guide to test plumbing, not to claim
+pixel-art quality.
+
+## Install the tested quality stack
+
+The committed quality benchmark uses two public model files:
+
+| File | ComfyUI folder | SHA-256 | License named by the model card |
+|---|---|---|---|
+| [`sd_xl_base_1.0.safetensors`](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors) | `models/checkpoints` | `31e35c80fc4829d14f90153f4c74cd59c90b779f6afe05a74cd6120b893f7e5b` | CreativeML Open RAIL++-M |
+| [`pixel-art-xl.safetensors`](https://huggingface.co/nerijs/pixel-art-xl/blob/main/pixel-art-xl.safetensors) | `models/loras` | `4234637cb80c998f41e348e6a6cb6bc20d8d038b2b0f256b6129b3b5e353eef7` | CreativeML OpenRAIL-M |
+
+Download each file into the named folder, verify its checksum, then confirm the
+checkpoint and LoRA appear in ComfyUI. The files are about 6.9 GB and 171 MB.
+They are not bundled with PixelKiln. Read both model cards before distributing
+the models or their outputs.
+
+The benchmark renders at 1024×1024, where SDXL has enough room to compose the
+scene, then uses ComfyUI's core `ImageScale` node with `nearest-exact` to write
+the requested 256px or 384px PNG. Asset width and height are therefore bound to
+the scale node, not the latent node. This is the useful trick: keep the model at
+its working resolution while PixelKiln still validates the exact game-ready
+output dimensions.
+
+You can reproduce the four samples with the committed
+[ComfyUI benchmark project](../benchmarks/provider-environments/comfyui/README.md).
+
+## Configure the manifest
+
+Put dimensions on each asset. Put workflow configuration under
+`providerOptions.comfyui` on the style:
+
+```jsonc
+{
+  "name": "my-game",
+  "provider": "comfyui",
+  "styles": {
+    "local-environment": {
+      "generator": "map",
+      "outDir": "assets/generated/environments",
+      "seed": 31415,
+      "providerOptions": {
+        "comfyui": {
+          "workflowFile": "workflows/pixel-environment-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" }
+          }
+        }
+      }
+    }
+  },
+  "assets": {
+    "cliffside_fortress": {
+      "prompt": "a fortified monastery carved into a mountain cliff",
+      "width": 768,
+      "height": 512
+    }
+  }
+}
+```
+
+| Option | Meaning |
+|---|---|
+| `workflowFile` | API-format workflow JSON, relative to the manifest. |
+| `outputNodeId` | Node whose completed history contains the final `images` array. |
+| `numImages` | Expected candidates, from 1 to 16. Defaults to 1. |
+| `bindings.prompt` | Workflow input replaced with the resolved PixelKiln prompt. |
+| `bindings.width` / `height` | Inputs replaced with the asset dimensions. |
+| `bindings.batchSize` | Input replaced with `numImages`. |
+| `bindings.seed` | Optional sampler seed input. Required when the style declares `seed`. |
+
+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.
+
+## Plan, generate, and review
+
+```bash
+pixelkiln doctor --dry-run
+pixelkiln plan
+pixelkiln gen --style local-environment --only cliffside_fortress --budget 0
+```
+
+Local ComfyUI work uses the `free` PixelKiln cost unit and therefore requires a
+zero budget. That means there is no metered provider charge. It does not claim
+that GPU time, electricity, hosted hardware, or model licenses are free.
+
+When `numImages` is greater than one, `pixelkiln pick` opens the same local
+candidate review used by hosted providers. The lockfile stores the ComfyUI
+prompt ID, output node, workflow hash, and selected output. Durable source
+references use `comfyui://` rather than embedding a workstation hostname.
+`pixelkiln restore` first uses the validated local content cache, then resolves
+the portable reference against the current `COMFYUI_BASE_URL`.
+
+## Current boundary
+
+- Supported generator: `map`.
+- Supported output: PNG images returned by one output node.
+- Supported dimensions: 16–4096px per edge, subject to the workflow, model,
+  sampler, VRAM, and node constraints.
+- PixelKiln `styleImages` and `palette` are rejected. Put image references,
+  ControlNet, LoRA, palette, and other controls inside the committed workflow.
+- Video, animation, masks, multiple output nodes, uploads, and ComfyUI Cloud
+  authentication are not implemented.
+- PixelKiln does not install checkpoints or custom nodes. Every machine running
+  the project must provide the models and nodes named by the workflow. The
+  benchmark workflows use only core ComfyUI nodes.
+
+For large mountains, buildings, and backgrounds, model choice and working
+resolution matter more than the provider label. The SDXL benchmark produced a
+coherent 384px cliff fortress and two layered environments where the starter
+SD1.5 workflow did not. It still returned opaque isolated assets and thousands
+of source colors, so transparency and palette reduction remain separate art
+pipeline steps. Benchmark the exact committed workflow before assigning it a
+production batch.
+
+## Troubleshooting
+
+- **Connection refused:** start ComfyUI or correct `COMFYUI_BASE_URL`.
+- **Missing node or input:** export the workflow again and update the manifest
+  bindings to match its API JSON.
+- **Prompt validation failed:** open the workflow in ComfyUI and check missing
+  custom nodes, checkpoints, VAEs, LoRAs, and invalid node values.
+- **Wrong image count:** make the bound batch input and `numImages` describe the
+  same final output count. PixelKiln fails the job rather than recording a
+  partial candidate set.
+- **Out of memory:** lower asset dimensions or batch size, or change the
+  workflow. PixelKiln's 4096px ceiling is a schema limit, not a promise that a
+  particular machine can render that canvas.
+
+ComfyUI's official server route reference documents the `/prompt`,
+`/history/{prompt_id}`, `/view`, and `/system_stats` endpoints used by this
+adapter: <https://docs.comfy.org/development/comfyui-server/comms_routes>.

package/docs/GETTING_STARTED.md

@@ -9,8 +9,9 @@ checks need provider access.
 ## Requirements
 
 - Node.js 20 or newer
-- A credential for the manifest's selected provider: `PIXELLAB_API_KEY` for
-  PixelLab or `RD_API_KEY` for experimental Retro Diffusion support
+- A credential for the selected hosted provider: `PIXELLAB_API_KEY` for
+  PixelLab or `RD_API_KEY` for Retro Diffusion. Self-hosted ComfyUI needs a
+  reachable server instead of an API key.
 
 Install the published package in the project that owns the art:
 
@@ -45,8 +46,8 @@ cp examples/minimal/pixelkiln.manifest.json pixelkiln.manifest.json
 ```
 
 Set each style's generator, dimensions, prompt prefix/suffix, reference images,
-and output directory. Then add one manifest entry per asset. Put the credential
-in `.env.local` beside the manifest:
+and output directory. Then add one manifest entry per asset. For PixelLab, put
+the credential in `.env.local` beside the manifest:
 
 ```dotenv
 PIXELLAB_API_KEY=...
@@ -66,12 +67,18 @@ Multi-candidate, tileset, GIF, and spritesheet live runs remain, so PixelLab
 remains the production adapter. See
 [Manifest reference](MANIFEST.md#experimental-retro-diffusion) for
 provider options and current limits, or
-[PixelLab vs. Retro Diffusion](../PROVIDERS.md) for selection guidance.
+[provider comparison](../PROVIDERS.md) for selection guidance.
+For self-hosted generation, set `provider` to `comfyui`, commit an API-format
+workflow, and bind the inputs PixelKiln may replace. Local ComfyUI jobs use a
+zero `free` budget, which describes the lack of a metered provider charge, not
+the cost of hardware or electricity. See [Set up ComfyUI](COMFYUI.md).
+
 The provider setup guides give the shortest complete path for
-[PixelLab](PIXELLAB.md) and [Retro Diffusion](RETRO_DIFFUSION.md).
+[PixelLab](PIXELLAB.md), [Retro Diffusion](RETRO_DIFFUSION.md), and
+[ComfyUI](COMFYUI.md).
 If one repository needs both, use separate provider-specific manifests and
 lockfiles. See
-[Use both providers in one project](../PROVIDERS.md#use-both-providers-in-one-project).
+[Use multiple providers in one project](../PROVIDERS.md#use-multiple-providers-in-one-project).
 
 Before spending anything, validate and price the selected work:
 

package/docs/LIBRARY.md

@@ -29,10 +29,11 @@ if (plan.actionable.length) {
 ```
 
 Planning performs no provider calls and spends nothing. Passing a provider lets
-its synchronous `supports()` and `estimate()` methods determine cost unit and
-candidate count; no credentials are required for those methods. A resolved
-spec has the fully inherited style and asset settings plus its deterministic
-spec hash.
+its `supports()` and `estimate()` methods determine cost unit and candidate
+count. A provider may also resolve local files before hashing. The ComfyUI
+adapter uses that hook to parse and hash a workflow JSON file without contacting
+the server. A resolved spec has the fully inherited style and asset settings
+plus its deterministic spec hash.
 
 ## Audit and gate generated art
 
@@ -116,8 +117,9 @@ See [TILES.md](./TILES.md) for file contracts and engine details.
 ## Provider integrations
 
 `Provider` is the capability boundary. Generation pipelines accept that
-interface rather than importing PixelLab directly; `FakeProvider` implements it
-in memory for deterministic tests.
+interface rather than importing PixelLab directly; `PixelLabProvider`,
+`RetroDiffusionProvider`, and `ComfyUIProvider` are built in, while
+`FakeProvider` implements it in memory for deterministic tests.
 
 ```ts
 import { FakeProvider, fetchAssets, poll, submit } from "pixelkiln"
@@ -131,7 +133,7 @@ await fetchAssets(provider, specs, lock, lockPath)
 
 Provider-backed operations mutate the supplied lock object; persist at the
 workflow boundary with `saveLock`. See
-[PixelLab vs. Retro Diffusion](../PROVIDERS.md) before selecting or implementing
+[provider comparison](../PROVIDERS.md) before selecting or implementing
 another backend, especially its optional capabilities and cost units.
 
 `submit` validates adapter estimates again at the spending boundary and returns

package/docs/MANIFEST.md

@@ -32,7 +32,7 @@ Unknown properties are rejected at every level.
 |---|---|---|
 | `$schema` | no | Editor schema URL/path. It does not affect generation identity. |
 | `name` | yes | Project/account tag namespace. |
-| `provider` | no | Provider registry id. Defaults to `pixellab`; `retrodiffusion` is experimental. |
+| `provider` | no | Provider registry id. Defaults to `pixellab`; `retrodiffusion` and `comfyui` are experimental. |
 | `styles` | yes | Map of style id to inherited generation/output settings. |
 | `assets` | yes | Map of stable asset id to subject and per-asset overrides. |
 
@@ -49,7 +49,7 @@ not merely a label edit.
 | `promptPrefix` | `""` | Prepended to every participating asset prompt. |
 | `promptSuffix` | `""` | Appended to every participating asset prompt. |
 | `styleImages` | `[]` | `{ "path": "..." }` reference images. Paths are manifest-relative. |
-| `size` | integer 32–256 | Square size for `1dir`; a style reference's dimensions take precedence when present. |
+| `size` | integer 16–8192 | Square size. Each provider and generator applies its own narrower limits. For PixelLab `1dir`, a style reference's dimensions take precedence. |
 | `view` | string | PixelLab `map`: `low top-down`, `high top-down`, or `side`. Other generators interpret this separately. |
 | `outline` | string | PixelLab `map`: `single color outline`, `selective outline`, or `lineless`. |
 | `shading` | string | PixelLab `map`: `flat shading`, `basic shading`, `medium shading`, or `detailed shading`. |
@@ -112,10 +112,9 @@ the correct extension and validates the correct structure.
 
 `promptStyle` accepts a live Retro Diffusion still-style selector,
 `numImages` accepts 1–16 candidates, and `removeBg` overrides
-`noBackground`. The Retro Diffusion API accepts 16–512px output, while the
-shared PixelKiln manifest currently limits arbitrary width and height to
-16–400px and square `size` to 32–256px. Selected styles can impose smaller
-limits. RD Pro and user styles accept up to nine reference images. Costs are
+`noBackground`. The Retro Diffusion API accepts 16–512px output. Selected
+styles can impose smaller limits. RD Pro and user styles accept up to nine
+reference images. Costs are
 planned in USD and checked again with Retro Diffusion's free authoritative
 quote endpoint before the paid request is sent. Authenticated single-candidate
 RD Fast and RD Plus paths have passed from quote through validated output and
@@ -175,14 +174,61 @@ For a Wang-style tileset sheet:
 `rd_tile__tile_variation` requires one style image. Provider-specific size and
 input constraints are checked during the free planning phase.
 
+## Experimental ComfyUI
+
+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.
+
+```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" }
+          }
+        }
+      }
+    }
+  },
+  "assets": {
+    "mountain": {
+      "prompt": "a snowbound mountain pass",
+      "width": 768,
+      "height": 512
+    }
+  }
+}
+```
+
+Node IDs come from the exported workflow; they are not stable across unrelated
+workflows. The current adapter supports `map`, PNG output from one node, 1–16
+candidates, and dimensions from 16–4096px. It rejects manifest `styleImages`
+and `palette`; keep those controls inside the workflow. See
+[Set up ComfyUI](COMFYUI.md) for the complete procedure and limits.
+
 ## Asset fields
 
 | Field | Type/default | Meaning |
 |---|---|---|
 | `prompt` | string, required | Subject-specific prompt. It may be empty only during existing-art onboarding. |
 | `category` | string | Human grouping metadata. |
-| `width` | integer 16–400 | Per-asset width override for arbitrary-size generators. |
-| `height` | integer 16–400 | Per-asset height override. |
+| `width` | integer 16–8192 | Per-asset width override. Each provider applies its own ceiling. |
+| `height` | integer 16–8192 | Per-asset height override. Each provider applies its own ceiling. |
 | `size` | integer 32–256 | Per-asset square size override. |
 | `file` | string | Filename/path override beneath the style output root. |
 | `styles` | string array, `[]` | If non-empty, generate this asset only in the named styles. |

package/docs/PROVIDER_BENCHMARK.md

@@ -1,8 +1,11 @@
 # Environment provider benchmark
 
-This benchmark compares PixelLab and Retro Diffusion on three 256×256 game-art
-briefs. Each brief has two attempts. The test uses the same prompt text and seed
-numbers for both providers, but seeds are not portable between models.
+This benchmark compares PixelLab and Retro Diffusion on five game-art briefs,
+with a four-brief ComfyUI extension using a named SDXL stack. Three briefs use
+256×256 output; two use 384×384 to test larger buildings and environment
+backgrounds. The hosted providers have two attempts per brief. ComfyUI has one
+attempt on each supported brief. Prompt text and seed numbers match, but seeds
+are not portable between models.
 
 The benchmark tests the adapters that PixelKiln ships. It does not rank every
 model or endpoint sold by either provider.
@@ -14,10 +17,12 @@ model or endpoint sold by either provider.
 | Mountain observatory | `map`, high top-down view | `rd_plus__isometric_asset` | Isolated building on a snowy ridge |
 | River gate | `map`, low top-down view | `rd_plus__topdown_asset` | Isolated landmark spanning water |
 | Alpine valley | `pixflux`, background kept | `rd_plus__environment` | Full scenic background |
+| Cliffside fortress | `map`, high top-down view | `rd_plus__isometric_asset` | Large isolated building complex |
+| Volcanic pass | `pixflux`, background kept | `rd_plus__environment` | Full scenic background with reusable depth planes |
 
-Both manifests request 256×256 output with seeds `31415` and `27182`. The
-provider-specific route or style is allowed to do its job. No image was picked,
-edited, cropped, or post-processed.
+Both manifests use seeds `31415` and `27182`. The provider-specific route or
+style is allowed to do its job. No image was picked, edited, cropped, or
+post-processed.
 
 PixelLab rejected `view: "isometric"` on the `map` endpoint with HTTP 422. The
 successful observatory attempts use the supported `high top-down` view while
@@ -30,6 +35,9 @@ The committed manifests and lockfiles are here:
 - [PixelLab lockfile](../benchmarks/provider-environments/pixellab/pixelkiln.lock.json)
 - [Retro Diffusion manifest](../benchmarks/provider-environments/retrodiffusion/pixelkiln.manifest.json)
 - [Retro Diffusion lockfile](../benchmarks/provider-environments/retrodiffusion/pixelkiln.lock.json)
+- [ComfyUI benchmark project](../benchmarks/provider-environments/comfyui/README.md)
+- [ComfyUI manifest](../benchmarks/provider-environments/comfyui/pixelkiln.manifest.json)
+- [ComfyUI lockfile](../benchmarks/provider-environments/comfyui/pixelkiln.lock.json)
 
 ## Mountain observatory
 
@@ -93,15 +101,94 @@ For this brief, PixelLab wins on prompt coverage, graphic clarity, consistency,
 and cost. Retro Diffusion wins if the desired result is a closer, more cinematic
 scene.
 
+## Cliffside fortress at 384×384
+
+Prompt: `a large fortified monastery built into a sheer mountain cliff,
+isometric three-quarter view, central stone keep, two side towers, terraced
+stairs, copper roofs, isolated with no scenery`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab cliffside fortress attempt A](../website/public/benchmarks/provider-environments/pixellab/isolated/a/cliffside-fortress.png) | ![PixelLab cliffside fortress attempt B](../website/public/benchmarks/provider-environments/pixellab/isolated/b/cliffside-fortress.png) | ![Retro Diffusion cliffside fortress attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/isolated/a/cliffside-fortress.png) | ![Retro Diffusion cliffside fortress attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/isolated/b/cliffside-fortress.png) |
+
+The larger canvas helped both providers. PixelLab used most of the frame and
+kept the cliff, stairs, central keep, and tower structure legible. Attempt B is
+the clearest match for a fortified monastery. Both outputs still include an
+opaque gray field, and their 246 and 249 colors would need deliberate cleanup
+for a tightly controlled palette.
+
+Retro Diffusion improved markedly over its 256×256 observatory attempts. Both
+results read as substantial cliffside compounds, and attempt B makes good use
+of the full canvas. They are ready-to-place transparent cutouts with 75% and
+52% transparent pixels and only 55 and 49 colors. PixelLab is more reliable on
+the exact architectural brief. Retro Diffusion is closer to a finished modular
+map asset.
+
+## Volcanic pass at 384×384
+
+Prompt: `a wide volcanic mountain pass at dawn, layered black peaks, glowing
+lava river, basalt fortress in the middle distance, smoke plumes, full-bleed
+parallax background with open sky`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab volcanic pass attempt A](../website/public/benchmarks/provider-environments/pixellab/background/a/volcanic-pass.png) | ![PixelLab volcanic pass attempt B](../website/public/benchmarks/provider-environments/pixellab/background/b/volcanic-pass.png) | ![Retro Diffusion volcanic pass attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/background/a/volcanic-pass.png) | ![Retro Diffusion volcanic pass attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/background/b/volcanic-pass.png) |
+
+PixelLab produced broader compositions with open sky and visibly separated
+mountain planes. Attempt A includes the smoke plume and a clear volcano; attempt
+B simplifies the scene into a graphic basin. Neither attempt includes a
+recognizable fortress. Attempt A also contains a generated signature-like mark
+in the lower-right corner, so it is not usable without cleanup. The files use
+44 and 26 colors.
+
+Retro Diffusion made the pass and lava river unmistakable in both attempts. Its
+narrow canyon framing is strong for a scene the player enters, but it leaves
+less open sky and fewer obvious planes for a distant backdrop. It also dropped
+the fortress and most of the smoke detail. The files use 26 and 25 colors.
+
+None of these four files is a finished parallax package. They are flattened,
+opaque scenes. PixelLab gives an artist clearer depth bands to cut apart; Retro
+Diffusion gives the stronger single-frame canyon. A production workflow should
+generate or extract the sky, distant peaks, middle ground, and foreground as
+separate assets.
+
+## ComfyUI SDXL extension
+
+The local extension uses
+[SDXL Base 1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0)
+with [Pixel Art XL](https://huggingface.co/nerijs/pixel-art-xl). Both committed
+workflows use core ComfyUI nodes, generate at 1024×1024, and finish with
+`nearest-exact` reduction. There was no manual image edit or candidate choice.
+
+| Mountain observatory, 256px | Cliffside fortress, 384px | Alpine valley, 256px | Volcanic pass, 384px |
+|---|---|---|---|
+| ![ComfyUI mountain observatory](../website/public/benchmarks/provider-environments/comfyui/isolated/a/mountain-observatory.png) | ![ComfyUI cliffside fortress](../website/public/benchmarks/provider-environments/comfyui/isolated/a/cliffside-fortress.png) | ![ComfyUI alpine valley](../website/public/benchmarks/provider-environments/comfyui/background/a/alpine-valley.png) | ![ComfyUI volcanic pass](../website/public/benchmarks/provider-environments/comfyui/background/a/volcanic-pass.png) |
+
+The observatory and fortress are the strongest architectural results in this
+small sample. The fortress has a clear entrance, tower hierarchy, stairs, and a
+single readable footprint. The alpine scene keeps the river, village, tree
+line, and distant ridges separate. The volcanic scene is dramatic and legible,
+but it drops the requested basalt fortress, the same prompt-coverage failure
+seen in both hosted providers.
+
+The trade-off is production cleanup. All four ComfyUI PNGs are opaque. The two
+isolated files use 16,811 and 31,572 RGB colors, while the backgrounds use
+36,248 and 50,985. They look pixelated because of the LoRA and nearest-exact
+reduction, but they are not indexed, low-palette sprites. Add explicit
+background removal and palette quantization when the target art direction
+requires them.
+
 ## Cost and operational results
 
 | Provider | Successful images | Charged amount | Final balance |
 |---|---:|---:|---:|
-| PixelLab | 6 | 6 generations | 4,415 generations |
-| Retro Diffusion | 6 | $0.348 | $0.135 |
+| PixelLab | 10 | 10 generations | 4,411 generations |
+| Retro Diffusion | 10 | $0.744 | $9.73 |
+| ComfyUI | 4 | 0 `free` PixelKiln units | No account balance |
 
 PixelLab charged one generation per image. Retro Diffusion quoted and charged
-$0.058 per RD Plus image.
+$0.058 for each 256px RD Plus image and $0.099 for each 384px RD Plus image;
+PixelKiln's hard ceiling rounds the latter to $0.10 per image.
 
 The run also caught two integration details:
 
@@ -111,24 +198,34 @@ The run also caught two integration details:
   $0.057768 to $0.058. PixelKiln now rounds offline estimates up to the live
   quote precision, so planning remains a safe ceiling.
 
-Both manifests now pass `doctor`, report a current plan, and have six healthy
-PNG cache entries.
+All three manifests now pass `doctor` and report a current plan. The hosted
+projects have ten healthy PNG cache entries each; the ComfyUI extension has
+four.
 
 ## Recommendation
 
 For large isolated buildings or landmarks, start with PixelLab when prompt
 coverage matters most. Budget for background cleanup. Start with Retro
-Diffusion when a transparent, compact, low-color asset matters more than
-capturing every noun in a complex prompt.
+Diffusion when a transparent, low-color asset matters more than capturing every
+noun in a complex prompt. At 384×384, Retro Diffusion can fill the frame with a
+substantial structure rather than the compact cutouts seen in the first brief.
 
 For full scenic backgrounds, start with PixelLab Pixflux. These two attempts
 were cheaper and more faithful to the brief. Try Retro Diffusion when you want
 foreground framing and a closer illustrated scene.
 
-Do not ask either provider for one giant finished level. Generate terrain,
+Try the tested ComfyUI SDXL stack when local control and larger compositions
+matter more than ready-to-place transparency. It produced the best large
+building in this run and a strong layered valley, with no provider charge. It
+also took roughly 90 seconds per 1024px render on the tested Apple MPS machine,
+and every output still needs palette review.
+
+Do not ask any provider for one giant finished level. Generate terrain,
 background, buildings, landmarks, and foreground pieces separately. Compose
 them in the engine, then use integer nearest-neighbor scaling for display.
 
 This sample is useful, not definitive. Two attempts expose obvious tendencies,
-but they do not measure every style, prompt family, or model update. Rerun the
-committed manifests when either provider changes its models.
+but they do not measure every style, prompt family, or model update. The new
+volcanic brief also shows why prompt coverage needs review at the object level:
+all four images lost the requested fortress. Rerun the committed manifests when
+either provider changes its models.