pixelkiln 0.6.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,10 +1,11 @@
 # Environment provider benchmark
 
-This benchmark compares PixelLab and Retro Diffusion on five game-art briefs.
-Three briefs use 256×256 output; two use 384×384 to test larger buildings and
-environment backgrounds. 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.
@@ -34,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
 
@@ -148,12 +152,39 @@ 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 | 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 for each 256px RD Plus image and $0.099 for each 384px RD Plus image;
@@ -167,8 +198,9 @@ 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 ten 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
 
@@ -182,7 +214,13 @@ 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.
 

package/docs/README.md

@@ -12,6 +12,7 @@ This source also renders at
 | [Getting started](./GETTING_STARTED.md) | Install from a checkout, create or adopt a project, run the everyday workflow, and decide what belongs in Git. |
 | [Set up PixelLab](./PIXELLAB.md) | Configure the production provider, choose a generator, and use its account workflows. |
 | [Set up Retro Diffusion](./RETRO_DIFFUSION.md) | Configure the experimental provider, choose a style, and understand its live-tested boundary. |
+| [Set up ComfyUI](./COMFYUI.md) | Connect a self-hosted server, install the tested SDXL pixel-art stack, and bind a committed workflow. |
 | [CLI reference](./CLI.md) | Every command and flag, offline/provider requirements, JSON output, and exit behavior. |
 | [Manifest reference](./MANIFEST.md) | Every style and asset field, inheritance, generator-specific constraints, mounting, and schema validation. |
 | [Agent workflows](./AGENTS.md) | Install the official skill and pair agent guidance with the deterministic CLI. |
@@ -21,7 +22,7 @@ This source also renders at
 | Guide | Use it for |
 |---|---|
 | [Generators](./GENERATORS.md) | Choose between `map`, `1dir`, `pixflux`, and `tiles`; understand measured costs and capability trade-offs. |
-| [Environment provider benchmark](./PROVIDER_BENCHMARK.md) | Compare PixelLab and Retro Diffusion on buildings, landmarks, backgrounds, cost, transparency, and prompt coverage. |
+| [Environment provider benchmark](./PROVIDER_BENCHMARK.md) | Compare PixelLab, Retro Diffusion, and a named ComfyUI model stack on buildings and backgrounds. |
 | [Derived artifacts](./ARTIFACTS.md) | Pack, mount, and export; provenance companions; ownership; force takeover; transactional and crash recovery. |
 | [Recovery and account safety](./RECOVERY.md) | Restore, caches, adopt, salvage, cross-project claims, tagging, and confirmed purge. |
 | [Quality gates](./QUALITY.md) | Plan, doctor, audit, cache checks, JSON contracts, and CI usage. |
@@ -34,7 +35,7 @@ This source also renders at
 | [Library API](./LIBRARY.md) | Public TypeScript imports for planning, auditing, providers, packing, exporting, and managed artifact writes. |
 | [Tiles and engine exports](./TILES.md) | Structural tile roles, provider rule preservation, generic JSON, Tiled Wang sets, and Godot terrain sets. |
 | [Measured PixelLab endpoints](./ENDPOINTS.md) | Live-account cost and payload research, endpoint recipes, limits, and unresolved API behavior. |
-| [PixelLab vs. Retro Diffusion](../PROVIDERS.md) | Provider selection, costs, adapter capabilities, confidence, and next work. Start with the provider-specific setup guides above when you are ready to configure a project. |
+| [Provider comparison](../PROVIDERS.md) | Provider selection, costs, adapter capabilities, confidence, and next work. Start with the provider-specific setup guides above when you are ready to configure a project. |
 
 ## Project policies
 

package/docs/RETRO_DIFFUSION.md

@@ -103,7 +103,7 @@ building, landmark, and foreground layers.
 
 The [environment benchmark](./PROVIDER_BENCHMARK.md) found clean transparent,
 low-color Retro Diffusion cutouts, while PixelLab followed the more complex
-building prompts more closely. Read [PixelLab vs. Retro Diffusion](../PROVIDERS.md)
+building prompts more closely. Read the [provider comparison](../PROVIDERS.md)
 before committing to a large batch.
 
 Retro Diffusion publishes its API examples and pricing formulas in the

package/examples/comfyui/README.md

@@ -0,0 +1,24 @@
+# ComfyUI smoke project
+
+This example uses only ComfyUI core nodes and the public Stable Diffusion 1.5
+checkpoint from Comfy's first-generation guide. It exists to verify the local
+submit, poll, download, provenance, and recovery path. It is not the visual
+benchmark model.
+
+Install `v1-5-pruned-emaonly-fp16.safetensors` in ComfyUI's `checkpoints`
+model folder, then copy this directory into a scratch project. From the copy:
+
+```bash
+pixelkiln doctor --dry-run
+pixelkiln doctor
+pixelkiln plan
+pixelkiln gen --budget 0
+pixelkiln audit --check
+```
+
+The workflow is already in API format. Its bindings match the node and input
+IDs in `pixelkiln.manifest.json`. Editing either file changes the resolved asset
+identity.
+
+The checkpoint is not part of this repository. Its model card and license are
+published by [Comfy Org on Hugging Face](https://huggingface.co/Comfy-Org/stable-diffusion-v1-5-archive).