pixelkiln 0.7.0 → 0.9.0

package/PROVIDERS.md

@@ -66,19 +66,19 @@ prompt, size, batch, and optional seed inputs PixelKiln may replace.
 
 | Decision | ComfyUI through PixelKiln |
 |---|---|
-| Best fit today | Private assets, local models, custom graph control, and teams that already maintain ComfyUI workflows |
+| Best fit today | Local composition experiments, private inputs, and teams prepared to maintain and manually validate custom graphs |
 | PixelKiln generator | `map` stills |
 | Output | One PNG output node, with 1–16 review candidates |
 | Cost model | `0 free`; local compute and hosting are outside PixelKiln's estimate |
 | Reproducibility | Workflow content is hashed; model files, custom-node versions, and runtime settings must still be managed outside PixelKiln |
 | Account lifecycle | Read-only connectivity check; no balance, remote object listing, tagging, or purge |
-| Confidence | Full mocked coverage plus a live core-node single-image lifecycle, four-candidate queue, and cache-only restore on Apple MPS; pixel-art model benchmark pending |
+| Confidence | Full mocked coverage plus live generation, four-candidate review, and cache-only restore on Apple MPS; cleanup and native-grid experiments remain manual, and aesthetic approval remains human |
 
-ComfyUI is the strongest option when workflow ownership matters more than a
-managed service. It is also the easiest provider to make irreproducible by
-accident. Two machines can share the same graph but differ in checkpoint bytes,
-custom-node versions, or sampler behavior. Commit the workflow and document the
-external model stack used to validate it.
+Choose ComfyUI when workflow ownership is worth manual validation. If the goal
+is the least cleanup between a prompt and usable pixel art, start with a
+specialized hosted provider. Two ComfyUI machines can share the same graph but
+differ in checkpoint bytes, custom-node versions, or sampler behavior. Commit
+the workflow and document the external model stack used to validate it.
 
 ## Large environments, mountains, and buildings
 
@@ -87,8 +87,8 @@ background. That distinction matters more than raw canvas size.
 
 | Asset type | PixelLab | Retro Diffusion | ComfyUI |
 |---|---|---|---|
-| Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. The adapter accepts up to 4096px per edge, but useful size depends on the model and VRAM. |
-| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene. Current PixelKiln routes top out at 400×400. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | A custom workflow can use composition controls, tiled diffusion, or a generate-then-downscale path. PixelKiln does not configure those nodes; it binds the final size and records the graph hash. |
+| Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. |
+| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene. Current PixelKiln routes top out at 400×400. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. |
 | Style consistency across a set | `1dir` accepts a style reference and returns size-dependent candidates, but it is more expensive and capped at the square-object range. | RD Pro accepts up to nine references and has stronger prompt following, but its common styles top out at 256×256 and cost $0.18 per image. Environment-specific RD Plus styles trade references for a larger 384px canvas. | LoRAs, reference adapters, ControlNet, and shared latent settings can live in the committed workflow. Reproducibility also depends on external model and custom-node versions. |
 | Very large final scene | Generate reusable objects, terrain, and background layers separately; assemble them deterministically and integer-upscale the result. | Use the same layered approach. The API has a 512px overall ceiling, but the useful environment and scene-object styles currently cap at 384px. | The graph can tile, upscale, or composite beyond hosted-provider limits, but memory and seam quality become workflow concerns. Prefer reusable layers unless the scene truly needs one render. |
 
@@ -155,7 +155,7 @@ reviewed outputs independently, or combine explicit files with `pixelkiln pack
 This is a useful split when PixelLab handles prompt-sensitive buildings and
 account recovery, Retro Diffusion handles environment-styled backdrops, clean
 cutouts, or native animation, and ComfyUI handles private or project-specific
-model workflows. Retro Diffusion is not a higher-resolution
+model experiments that can absorb manual cleanup. Retro Diffusion is not a higher-resolution
 route through PixelKiln today: its useful environment styles cap at 384×384,
 while PixelLab `map` reaches 400×400. Its advantage is the model/style and
 output type, not raw dimensions.
@@ -207,11 +207,11 @@ estimate and hard budget remain enforced.
 
 ## What to build next
 
-The first ComfyUI release now has a live, versioned core-node reference
-workflow. The remaining confidence gap is visual rather than transport: choose
-and pin a pixel-art model or LoRA, then benchmark a large building and scenic
-background against the hosted-provider briefs. A human still needs to complete
-the live four-candidate selection and fetch path.
+The first ComfyUI release has a live, versioned core-node reference workflow.
+Transport, candidate review, provenance, and cache recovery work. Art quality is
+still the gap. The tested SDXL plus Pixel Art XL graph is useful for composition,
+but it is not a production preset. Native-grid recovery, final palette
+enforcement, prompt coverage, and aesthetic approval remain manual.
 
 Native per-style provider routing remains the highest-value orchestration
 feature. One manifest should be able to send a building style to PixelLab, an
@@ -240,15 +240,18 @@ captured before submission.
 
 Recommended order:
 
-1. Select and benchmark a pinned pixel-art ComfyUI workflow, including a human-reviewed candidate fetch.
-2. Add per-style provider selection, provider-keyed budgets, and mixed-provider
+1. Build a provider-neutral post-processing record for background removal,
+   native-grid recovery, final palette enforcement, and human approval.
+2. Benchmark pinned ComfyUI models and prompt patterns across at least two scene
+   families. Reject any supposed improvement that helps only one subject.
+3. Add per-style provider selection, provider-keyed budgets, and mixed-provider
    integration tests.
-3. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
+4. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
    smoke tests.
-4. Build the Scenario still-image spike from issue #52 with dry-run cost, submit, poll,
+5. Build the Scenario still-image spike from issue #52 with dry-run cost, submit, poll,
    download, and one custom-model or reference-image benchmark.
-5. Design ComfyUI Cloud as a separate authenticated and billable adapter.
-6. Consider general raster marketplaces only with explicit nearest-neighbor,
+6. Design ComfyUI Cloud as a separate authenticated and billable adapter.
+7. Consider general raster marketplaces only with explicit nearest-neighbor,
    palette, transparency, and reproducibility checks.
 
 Midjourney is not an adapter target without an official public API. Automating

package/README.md

@@ -24,7 +24,8 @@ tileset, GIF, and spritesheet live runs remain. An experimental ComfyUI adapter
 runs committed API-format still-image workflows on a self-hosted server. Its
 core-node smoke project has passed live generation, candidate queueing, and
 cache-only recovery on Apple MPS. An SDXL plus Pixel Art XL workflow also has
-four committed building and environment samples. See
+four baseline samples and four diagnostic cleanup samples. It is source
+material, not a production-ready pixel-art preset. See
 [provider comparison](./PROVIDERS.md) for the trade-offs, including large
 environment and building workflows.
 `FakeProvider` exercises the same contract deterministically in tests.
@@ -189,7 +190,14 @@ select another provider and pass namespaced `providerOptions`; see
 [Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), and
 [Set up ComfyUI](./docs/COMFYUI.md). The
 [provider comparison](./PROVIDERS.md) covers costs,
-current confidence, and limitations.
+current confidence, and limitations. The committed ComfyUI projects now include
+transparent cutouts, palette-controlled backgrounds, wide environment canvases,
+and native-grid recovery for model output that only looks like pixel art. The
+ComfyUI guidance is quality-first: start with 48–128px native components,
+apply the final palette after grid recovery, require prompt-coverage and human
+cluster-and-silhouette review, and compose larger scenes from accepted parts
+instead of chasing a larger raster. Those cleanup and approval steps are manual
+today.
 
 The schema rejects unknown fields and invalid generator combinations before
 planning. See the [Manifest reference](./docs/MANIFEST.md).
@@ -347,7 +355,7 @@ writes, and offline provenance verification. See [Library API](./docs/LIBRARY.md
 | [Manifest reference](./docs/MANIFEST.md) | Every style/asset field and generator constraint. |
 | [Agent workflows](./docs/AGENTS.md) | Official skill install, operating model, and provider-aware safety. |
 | [Generators](./docs/GENERATORS.md) | Capability choice, measured costs, palettes, style references, and tiles. |
-| [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Twenty-four outputs comparing buildings, landmarks, large backgrounds, cost, and file readiness. |
+| [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Thirty provider outputs plus three deterministic native-grid results comparing large scenes, transparency, palette size, and file readiness. |
 | [Derived artifacts](./docs/ARTIFACTS.md) | Pack, mount, export, provenance, ownership, transactions, and recovery. |
 | [Recovery](./docs/RECOVERY.md) | Restore, caches, adopt, salvage, claims, and purge safety. |
 | [Quality gates](./docs/QUALITY.md) | Plan, doctor, audit, cache, JSON, and CI. |

package/docs/AGENTS.md

@@ -28,7 +28,9 @@ With the skill loaded, an agent should:
 5. Pass an explicit `--budget` within the amount the user authorized.
 6. Leave artwork selection in the local `pick` page unless the user gives a
    specific selection rule.
-7. Commit the manifest, lockfile, generated output, and artifact companions, but
+7. Treat ComfyUI output as source material until native-grid, final-palette,
+   prompt-coverage, and human 1× checks pass.
+8. Commit the manifest, lockfile, generated output, and artifact companions, but
    never credentials or `.pixelkiln/` caches.
 
 The skill guides the workflow; PixelKiln remains the deterministic execution
@@ -48,7 +50,7 @@ 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. |
+| ComfyUI adapter | Experimental self-hosted still-image backend; generated PNGs need manual structural and visual approval. |
 
 PixelKiln's core is provider-neutral, but PixelLab remains the only production
 and paid-generation-tested adapter. Retro Diffusion generation support is

package/docs/COMFYUI.md

@@ -4,9 +4,44 @@ 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
+review queue on Apple MPS. An SDXL composition workflow has also passed four
 building and environment renders. ComfyUI Cloud is not part of this release.
 
+[Visit ComfyUI](https://www.comfy.org/) or continue with the local setup below.
+
+## Decide whether ComfyUI fits
+
+Use this adapter when local control, private inputs, or a custom graph justifies
+maintaining the workflow. It is not a turnkey route to game-ready pixel art.
+The tested SDXL plus Pixel Art XL graph can produce useful source compositions,
+but the result still needs native-grid recovery, a final palette pass, and human
+art review.
+
+If the main goal is the shortest path to usable pixel art, compare PixelLab and
+Retro Diffusion first. Choose ComfyUI when owning the workflow is worth the
+extra model testing and cleanup.
+
+### Minimal safe path
+
+1. Generate two to four candidates at the model's normal working size.
+2. Reject missing subjects, weak silhouettes, and bad composition before doing
+   any cleanup.
+3. For isolated art, remove the background at full resolution.
+4. Recover one native pixel per detected cell.
+5. Quantize the recovered native image to the final project palette. Start with
+   16–32 colors and no dithering.
+6. Review the native file at 1× and an integer zoom.
+7. Keep the smallest clear result. Start with 48–128px native components and
+   compose larger scenes from accepted parts.
+
+Stop after step 2 when the image misses the brief. Background removal,
+pixel-grid recovery, and palette reduction cannot restore a missing building or
+repair a weak composition.
+
+PixelKiln currently automates generation, candidate review, provenance, and
+recovery from its local cache. It does not automate steps 3–6. Treat every
+ComfyUI output as source material until those checks pass.
+
 ## Start ComfyUI
 
 Install and start ComfyUI using its
@@ -53,30 +88,191 @@ The repository includes a working core-node
 from ComfyUI's official first-generation guide to test plumbing, not to claim
 pixel-art quality.
 
-## Install the tested quality stack
+## Install the tested composition stack
 
-The committed quality benchmark uses two public model files:
+The committed composition and post-processing benchmarks use three 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 |
+| [`birefnet.safetensors`](https://huggingface.co/Comfy-Org/BiRefNet/blob/main/background_removal/birefnet.safetensors) | `models/background_removal` | `9ab37426bf4de0567af6b5d21b16151357149139362e6e8992021b8ce356a154` | MIT |
 
 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.
+checkpoint, LoRA, and background-removal model appear in ComfyUI. The files are
+about 6.9 GB, 171 MB, and 444 MB. They are not bundled with PixelKiln. Read the
+model cards before distributing the models or their outputs.
+
+The environment 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. Those files
+prove exact delivery dimensions; they do not prove a native pixel grid. The
+separate native-grid benchmark saves the model canvas and reconstructs its
+implied cells afterward.
 
 You can reproduce the four samples with the committed
 [ComfyUI benchmark project](../benchmarks/provider-environments/comfyui/README.md).
 
+## Background removal and palette experiments
+
+ComfyUI 0.34.3 has the required nodes in core. No custom-node package is needed.
+The tested isolated-asset graph runs these nodes in this order:
+
+1. Decode the 1024×1024 SDXL image.
+2. Run `RemoveBackground` with the loaded BiRefNet model.
+3. Invert the returned background mask for use as foreground alpha.
+4. Run `ImageQuantize` on the RGB image with 64 colors and no dithering.
+5. Join the quantized RGB image with the alpha mask.
+6. Reduce the RGBA result with `ImageScale` set to `nearest-exact`.
+
+This graph is a diagnostic experiment, not the recommended finished pipeline.
+It proves the cleanup nodes run and preserves the alpha mask by letting BiRefNet
+see the full-resolution, full-color image. Its pre-scale quantization does not
+guarantee the color count of a later native-grid reconstruction, because grid
+recovery can introduce averaged colors.
+
+For an isolated production candidate, use this order instead:
+
+1. decode the full-resolution model output;
+2. remove its background and preserve the alpha mask;
+3. recover the native pixel grid without resampling the alpha edge;
+4. quantize the recovered native RGB image to the final project palette;
+5. audit and review the final native RGBA file.
+
+Scenic backgrounds skip background removal. They still need grid recovery,
+final palette enforcement, and review.
+
+The [post-processing benchmark](../benchmarks/provider-postprocessing/comfyui/README.md)
+reuses the same prompts, seeds, SDXL settings, and LoRA strengths as the first
+ComfyUI run. Its two isolated assets have 60% and 62% transparent pixels and 55
+and 58 RGB colors. The two backgrounds use 64 and 60 colors. The original
+files ranged from 16,811 to 50,985 colors.
+
+Use PixelKiln to keep those requirements enforceable:
+
+```bash
+pixelkiln audit --style isolated-refined --min-transparency 0.5 --max-colors 64 --check
+pixelkiln audit --style background-refined --max-colors 64 --check
+```
+
+Start without dithering for compact game art. Floyd-Steinberg can soften bands,
+but it adds noisy pixel patterns. Ordered Bayer dithering is easier to art-direct
+when a project needs deliberate texture. Whichever mode you choose becomes part
+of the committed workflow hash.
+
+## Recover a native pixel grid
+
+File size is not pixel-art resolution. Keep these three measurements separate:
+
+1. The **generation canvas** is the raster SDXL produces, such as 1024×1024.
+2. The **native art grid** has one stored pixel for each editable pixel-art cell.
+3. The **display size** is an integer-scaled view of the native art.
+
+Pixel Art XL can draw convincing pixel-shaped texture without producing a
+consistent one-pixel grid. Our 1024×1024 test image carried an implied 8px cell
+and resolved to 128×128 native art. Its 1344×768 wide version resolved to 168×96.
+Nearest-neighbor scaling preserved those fake cells but did not fix them.
+
+Retro Diffusion's MIT-licensed
+[Pixel Art Fixer](https://github.com/Retro-Diffusion/pixel-art-fixer) detects the
+implied grid and reconstructs one output pixel per cell. Both benchmark sources
+returned the high-confidence `fast:ac+rl(S)` decision. The checked-in
+[native-grid boundary benchmark](../benchmarks/provider-hires/comfyui/README.md) includes
+the source PNGs, native reconstructions, dimensions, hashes, and pinned fixer
+revision.
+
+Treat the native PNG as the canonical asset. Edit and compose it at 1×. Scale it
+only for display, using integer dimensions and nearest-neighbor rendering. A
+2048px file made from a 1024px pseudo-pixel source is not higher-quality pixel
+art, even when every source pixel becomes an exact 2×2 block.
+
+The open fixer is deterministic image processing. Its maintainers also offer a
+[hosted neural fixer](https://www.retrodiffusion.ai/tools/pixel-art-fixer/) for
+damaged inputs where a reliable grid no longer exists. PixelKiln does not yet
+run either fixer automatically.
+
+### Quality-first resolution policy
+
+Use 48×48 through 128×128 as the default native range for an independently
+generated component with this tested stack. This is an operating range, not an
+adapter restriction: ComfyUI may work on a 1024px canvas internally, and a wide
+or tall asset may exceed one native axis when review supports it. Do not grow
+both native dimensions merely because the machine can render them. This matches
+the [Aseprite Diffusion author's published working range](https://www.reddit.com/r/PixelArt/comments/yv2q51/making_high_quality_game_tiles_in_less_than_a/)
+of 48–128px, centered on a 64px native target, and our current 128px recovery.
+
+Start with a deliberate 16–32 color project palette. Add colors only when they
+improve readable depth, material, or lighting. After grid recovery, review the
+asset at 1× and an integer zoom for silhouette, clusters, contours, single-pixel
+noise, palette separation, and seams. High-confidence grid detection only
+proves structure; it is not an aesthetic approval.
+
+Test a proposed graph and prompt pattern on at least two different scene
+families. One prompt can clean up one subject and damage another. Generate a
+small candidate set, reject any image that misses required objects, and keep the
+prompt and workflow only when the final native files improve consistently.
+
+Stop increasing resolution when clusters become soft, gradients replace
+intentional ramps, or important forms stop reading at 1×. Keep the smaller
+result when it is clearer. See the [quality gates](./QUALITY.md) for the human
+review checklist.
+
+## Build larger environments
+
+Do not ask the model for one enormous finished level. Generate and review the
+scene as 48–128px native-grid parts:
+
+- sky and atmosphere;
+- distant mountains;
+- midground terrain and forest;
+- buildings and landmarks;
+- foreground framing and gameplay tiles.
+
+Keep one grid origin, native scale, and palette contract across the parts, then
+compose them at 1×. This preserves editable clusters and lets you regenerate one
+weak region without touching the rest of the scene.
+
+ComfyUI's official [outpainting workflow](https://docs.comfy.org/tutorials/basic/outpaint)
+can extend a canvas. The official
+[crop-and-stitch nodes](https://github.com/comfyorg/comfyui-crop-and-stitch) can
+sample a region at the model's working size and blend it back.
+[Tiled diffusion](https://github.com/comfyorg/comfyui-tiled-diffusion) can cover
+a larger semantic canvas with overlapping windows. These techniques help
+composition and regional detail; none guarantees a native pixel grid. Run grid
+recovery after accepting each layer or the final composite. Check licenses
+before shipping: the linked tiled implementation marks its MultiDiffusion,
+Mixture of Diffusers, and tiled VAE code as non-commercial share-alike.
+
+Do not add a latent refinement pass by default. We tested `LatentUpscale` to
+1536px and 2048px, low-denoise resampling, and tiled VAE decode. Every version
+completed on the 64 GB M1 Max, but the extra interpolation, diffusion, and VAE
+round trip visibly blurred the shapes. Reducing the result to 64 colors did not
+restore the lost structure.
+
+The neural [ComfyUI Pixelization](https://github.com/DarioFT/ComfyUI-Pixelization)
+node is another possible raster-to-pixel-art step, but its underlying model is
+limited to non-commercial research use. It is not a safe default for a general
+game-asset pipeline.
+
+### What each technique can and cannot do
+
+| Technique | Useful for | Limitation |
+|---|---|---|
+| [Pixel Art Fixer](https://github.com/Retro-Diffusion/pixel-art-fixer) | Recovering a native grid from softened, non-integer, or oversized pseudo-pixel art | Classical detection can fail when the grid is badly damaged or cells are very small |
+| [ComfyUI Pixelization](https://github.com/DarioFT/ComfyUI-Pixelization) | Turning ordinary digital art into sharper, cell-controlled pixel art | Underlying model is non-commercial research only and may damage existing pixel art |
+| [Outpainting](https://docs.comfy.org/tutorials/basic/outpaint) | Extending the scene beyond its current borders | Produces more raster canvas, not a guaranteed pixel grid |
+| [Crop and Stitch](https://github.com/comfyorg/comfyui-crop-and-stitch) | Repairing one region at the model's preferred resolution | Blending and resampling still need native-grid normalization |
+| [Tiled diffusion](https://github.com/comfyorg/comfyui-tiled-diffusion) | Panoramas, regional prompts, and canvases larger than working memory | The linked implementation has non-commercial components and does not enforce pixel cells |
+| [MMPX](https://jcgt.org/published/0010/02/04/paper.pdf) | Magnifying true native pixel art while preserving its style | Assumes the input is already real pixel art; it cannot recover a fake grid |
+
+That makes the deterministic fixer the best current structural fallback after
+ComfyUI, not a quality generator. Use outpainting, regional generation, or tiles
+to solve composition first. Recover the grid next, enforce palette and alpha
+rules after that, perform the human art review, and reserve nearest-neighbor or
+MMPX for presentation of an already-valid native asset.
+
 ## Configure the manifest
 
 Put dimensions on each asset. Put workflow configuration under
@@ -163,14 +359,16 @@ the portable reference against the current `COMFYUI_BASE_URL`.
 - 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.
+- PixelKiln does not yet run background removal, native-grid recovery, final
+  palette enforcement, or aesthetic review as one automated pipeline. Until
+  those external or manual steps pass, a generated PNG remains source material.
 
 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.
+SD1.5 workflow did not. Those results still required manual structural and
+visual review. Benchmark the exact committed workflow on more than one subject
+before assigning it a production batch.
 
 ## Troubleshooting
 
@@ -185,6 +383,9 @@ production batch.
 - **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.
+- **The result looks pixelated but muddy:** reject it as source material. Do not
+  upscale it or accept it because grid detection succeeds. Compare a different
+  model, prompt pattern, or smaller native target on at least two scene types.
 
 ComfyUI's official server route reference documents the `/prompt`,
 `/history/{prompt_id}`, `/view`, and `/system_stats` endpoints used by this

package/docs/GETTING_STARTED.md

@@ -71,7 +71,9 @@ provider options and current limits, or
 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 cost of hardware or electricity. ComfyUI is not the shortest path to
+game-ready pixel art: use it only when local control justifies manual grid
+recovery, palette enforcement, and art review. See [Set up ComfyUI](COMFYUI.md).
 
 The provider setup guides give the shortest complete path for
 [PixelLab](PIXELLAB.md), [Retro Diffusion](RETRO_DIFFUSION.md), and

package/docs/MANIFEST.md

@@ -178,7 +178,9 @@ input constraints are checked during the free planning phase.
 
 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.
+part of the spec hash. Adapter success proves transport and output structure,
+not pixel-art quality. The tested workflows still need manual native-grid,
+final-palette, prompt-coverage, and human 1× checks.
 
 ```jsonc
 {
@@ -219,7 +221,9 @@ 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.
+[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.
 
 ## Asset fields
 

package/docs/PROVIDER_BENCHMARK.md

@@ -4,8 +4,8 @@ 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.
+baseline and one post-processed 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.
@@ -164,19 +164,75 @@ workflows use core ComfyUI nodes, generate at 1024×1024, and finish with
 |---|---|---|---|
 | ![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
+The observatory and fortress have the clearest architecture 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.
+seen in both hosted providers. These composition strengths do not make the
+files finished pixel art.
 
 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.
+background removal, native-grid recovery, final palette quantization, and human
+review before treating them as game assets.
+
+### ComfyUI post-processing result
+
+The follow-up graph keeps the generation settings fixed and changes only the
+cleanup nodes. BiRefNet removes the isolated backgrounds, and ComfyUI's core
+quantizer limits every image to 64 colors without dithering.
+
+| Original observatory | Cleanup experiment | Original fortress | Cleanup experiment |
+|---|---|---|---|
+| ![Original opaque ComfyUI mountain observatory](../website/public/benchmarks/provider-environments/comfyui/isolated/a/mountain-observatory.png) | ![Transparent 64-color ComfyUI mountain observatory](../website/public/benchmarks/provider-postprocessing/comfyui/isolated/mountain-observatory.png) | ![Original opaque ComfyUI cliffside fortress](../website/public/benchmarks/provider-environments/comfyui/isolated/a/cliffside-fortress.png) | ![Transparent 64-color ComfyUI cliffside fortress](../website/public/benchmarks/provider-postprocessing/comfyui/isolated/cliffside-fortress.png) |
+
+| Original alpine valley | 64-color alpine valley | Original volcanic pass | 64-color volcanic pass |
+|---|---|---|---|
+| ![Original ComfyUI alpine valley](../website/public/benchmarks/provider-environments/comfyui/background/a/alpine-valley.png) | ![64-color ComfyUI alpine valley](../website/public/benchmarks/provider-postprocessing/comfyui/background/alpine-valley.png) | ![Original ComfyUI volcanic pass](../website/public/benchmarks/provider-environments/comfyui/background/a/volcanic-pass.png) | ![64-color ComfyUI volcanic pass](../website/public/benchmarks/provider-postprocessing/comfyui/background/volcanic-pass.png) |
+
+The cutouts retained their silhouettes while reaching 60% and 62% transparent
+pixels. They use 55 and 58 RGB colors instead of 16,811 and 31,572. The scenic
+images fell to 64 and 60 colors without losing their main depth bands. The
+committed [post-processing project](../benchmarks/provider-postprocessing/comfyui/README.md)
+contains the workflows, manifest, audit commands, and provenance. These outputs
+still need native-grid recovery and final palette enforcement. They are not a
+finished production path.
+
+### ComfyUI resolution result
+
+A second benchmark keeps the alpine brief and seed fixed while separating the
+model's generation canvas from the actual editable pixel grid.
+
+| SDXL source | Recovered native art | Wide SDXL source | Recovered wide art |
+|---|---|---|---|
+| ![ComfyUI 1024px raster with pseudo-pixel texture](../website/public/benchmarks/provider-hires/comfyui/baseline-64/alpine-valley.png) | ![ComfyUI alpine valley reconstructed onto a 128 by 128 pixel grid](../website/public/benchmarks/provider-hires/comfyui/native-grid/alpine-valley-128x128.png) | ![ComfyUI 1344 by 768 wide raster with pseudo-pixel texture](../website/public/benchmarks/provider-hires/comfyui/native-wide-64/alpine-valley-wide.png) | ![ComfyUI wide alpine valley reconstructed onto a 168 by 96 pixel grid](../website/public/benchmarks/provider-hires/comfyui/native-grid/alpine-valley-wide-168x96.png) |
+
+The 1024×1024 source carried an implied 8px cell and resolved to a 128×128
+native grid. The 1344×768 source used the same cell step and resolved to 168×96.
+Retro Diffusion Pixel Art Fixer reported high-confidence consensus for both.
+The reconstructed outputs contain 48 colors and one stored pixel per recovered
+cell.
+
+That is a structural result, not an aesthetic endorsement. Grid recovery cannot
+turn weak composition, painterly gradients, or muddy source clusters into good
+pixel art. These files remain review candidates, and the 1024px source should
+not be presented as a high-resolution pixel-art deliverable. For this tested
+stack, 48–128px native components are the default operating range; larger
+environments should be assembled from reviewed parts with one palette and grid.
+
+This invalidated our earlier 2048px nearest-neighbor result. That file perfectly
+duplicated the source raster, including its fake, softened cells. It was a larger
+delivery file, not better pixel art, and has been removed from the showcase.
+
+Earlier 1536px and 2048px latent refinements also looked blurred. The extra
+interpolation and resampling softened the structure; color quantization could
+not repair it. The committed
+[resolution project](../benchmarks/provider-hires/comfyui/README.md) contains
+the two provider workflows, source outputs, native reconstructions, fixer
+report, audit instructions, and lock provenance.
 
 ## Cost and operational results
 
@@ -184,7 +240,7 @@ requires them.
 |---|---:|---:|---:|
 | PixelLab | 10 | 10 generations | 4,411 generations |
 | Retro Diffusion | 10 | $0.744 | $9.73 |
-| ComfyUI | 4 | 0 `free` PixelKiln units | No account balance |
+| ComfyUI | 10 | 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;
@@ -199,8 +255,9 @@ The run also caught two integration details:
   quote precision, so planning remains a safe ceiling.
 
 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.
+projects have ten healthy PNG cache entries each; the ComfyUI projects have
+four baseline, four cleanup, and two resolution-test entries. Three additional
+native-grid PNGs are deterministic post-processing results, not provider jobs.
 
 ## Recommendation
 
@@ -214,18 +271,28 @@ 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.
 
-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.
+Try ComfyUI when local control and custom composition work matter enough to
+justify manual cleanup. The tested SDXL stack produced a strong building and
+layered valley, but its large files only imitated a pixel grid. Its cleanup
+graph and native-grid recovery are diagnostic steps, not a production preset.
+A one-pass 1024px render took roughly 60 to 90 seconds on the tested Apple MPS
+machine. Recover the native grid, enforce the final palette afterward, and
+review prompt coverage and pixel clusters by hand. The tested latent-upscale
+passes blurred the art, while nearest-neighbor scaling only duplicated its
+pseudo-pixels.
+
+Do not choose the current ComfyUI stack only because it has no provider charge.
+It carries the most local setup and manual validation in this comparison. Test
+any proposed prompt pattern on at least two scene families; a universal cleanup
+prompt can improve one subject while degrading another.
 
 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.
+background, buildings, landmarks, and foreground pieces separately. Normalize
+them to one native grid, compose at 1×, 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. 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.
+all providers lost the requested fortress. Rerun the committed manifests when
+a provider or local model changes.

package/docs/QUALITY.md

@@ -63,6 +63,29 @@ measured member-by-member with stable role-qualified ids. Standard
 non-interlaced greyscale, indexed, RGB, greyscale-alpha, and RGBA PNGs are
 normalized to RGBA before measurement.
 
+## Human pixel-art gate
+
+The audit catches measurable drift; it does not decide whether an image is good
+pixel art. A grid-aligned file can still contain painterly gradients, noisy
+single-pixel marks, weak silhouettes, or clusters inherited from a blurred
+source. Review every candidate at its native 1× size and at an integer zoom.
+
+For each candidate, verify:
+
+- every required subject and landmark from the brief is present and readable;
+- the silhouette and focal point read at 1×;
+- clusters look deliberate instead of averaged or smeared;
+- contours do not contain accidental stair-steps or isolated noise;
+- the palette separates depth and gameplay-relevant shapes;
+- transparency and tile seams are clean when applicable;
+- the asset still fits the project's shared grid, palette, and perspective.
+
+Reject a candidate that fails those checks even when dimensions, hashes,
+transparency, palette count, and grid recovery all pass. For the tested ComfyUI
+pixel-art stack, begin with 48–128px native components and compose larger scenes
+from reviewed parts. Apply the final palette after grid recovery. Resolution is
+a ceiling imposed by quality, not a target.
+
 ## Cache integrity gate
 
 ```bash

package/docs/README.md

@@ -12,7 +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. |
+| [Set up ComfyUI](./COMFYUI.md) | Bind a local composition workflow and understand the manual quality boundary. |
 | [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. |
@@ -22,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, Retro Diffusion, and a named ComfyUI model stack on buildings and backgrounds. |
+| [Environment provider benchmark](./PROVIDER_BENCHMARK.md) | Compare PixelLab, Retro Diffusion, and ComfyUI on buildings, backgrounds, cleanup, and native-grid recovery. |
 | [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. |

package/package.json

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

package/skills/pixelkiln/SKILL.md

@@ -20,6 +20,9 @@ submission, reviewed by a human, and recorded with exact provenance.
   explicit `--budget` no higher than the authorized estimate.
 - Leave visual selection to the local `pixelkiln pick` review page unless the
   user explicitly provides a selection rule. Closing it applies nothing.
+- Treat every ComfyUI output as source material until it passes the native-grid,
+  final-palette, prompt-coverage, and human 1× checks in the ComfyUI reference.
+  A successful PNG or high-confidence grid result is not quality approval.
 - Preserve manual edits and ownership errors. Inspect the difference before any
   `--force` operation.
 - Commit the manifest, lockfile, generated outputs, and derived artifact

package/skills/pixelkiln/references/comfyui.md

@@ -3,12 +3,46 @@
 Read this reference before operating a PixelKiln manifest whose provider is
 `comfyui`.
 
+## Position it honestly
+
+The ComfyUI adapter automates a committed graph, candidate review, provenance,
+and recovery. It does not make a general image model produce good pixel art.
+Use it when local control, private inputs, or a custom graph justify manual art
+direction. Do not call the current SDXL plus Pixel Art XL setup production-ready
+or game-ready.
+
+If the user mainly wants the shortest path to usable pixel art, compare the
+specialized hosted providers first. Choose ComfyUI when owning the workflow is
+worth the extra model testing and cleanup.
+
+## Minimal safe path
+
+1. Generate two to four candidates on the model's normal working canvas.
+2. Reject weak composition and missing prompt elements before post-processing.
+3. For isolated art, remove the background at full resolution.
+4. Recover one native pixel per detected cell.
+5. Quantize the recovered native image to the project's final palette, usually
+   16–32 colors without dithering to start.
+6. Review the native file at 1× and an integer zoom. Check silhouette, clusters,
+   contours, single-pixel noise, palette separation, alpha, and seams.
+7. Accept the smallest clear result. For the tested stack, start with 48–128px
+   native components and compose larger scenes from reviewed parts.
+
+PixelKiln does not automate steps 3–6 yet. Say so. Do not present the generated
+working canvas, a nearest-neighbor resize, or a grid-recovery result as the
+finished asset.
+
+Test a workflow on at least two different scene families before recommending
+it. A prompt that reduced noise in the alpine benchmark increased noise in the
+volcanic benchmark and still missed the requested fortress.
+
+## Connection and workflow contract
+
 ComfyUI is self-hosted and needs no provider credential. Never assume the
-server is running or reachable. `pixelkiln doctor --dry-run` validates the
-workflow and bindings offline; `pixelkiln doctor` checks the configured server
-through its read-only system-stats route. The default URL is
-`http://127.0.0.1:8188`; `COMFYUI_BASE_URL` overrides it. Do not advise exposing
-an unauthenticated ComfyUI server to a public network.
+server is reachable. `pixelkiln doctor --dry-run` validates workflow bindings
+offline; `pixelkiln doctor` checks the read-only system-stats route. The default
+URL is `http://127.0.0.1:8188`; `COMFYUI_BASE_URL` overrides it. Keep an
+unauthenticated server off public networks.
 
 The style's `providerOptions.comfyui` must name a committed API-format workflow,
 one image output node, the expected candidate count, and bindings for prompt,
@@ -22,7 +56,9 @@ the `map` generator, PNG output from one node, 1–16 candidates, and dimensions
 from 16–4096px. Manifest `styleImages` and `palette` are unsupported; those
 controls belong in the workflow.
 
-For the tested higher-quality pixel-art stack, use SDXL Base 1.0 as
+## Tested evidence, not a preset
+
+The diagnostic stack uses SDXL Base 1.0 as
 `sd_xl_base_1.0.safetensors` and Pixel Art XL as
 `pixel-art-xl.safetensors`. The repository's
 `benchmarks/provider-environments/comfyui/` project names both files and uses
@@ -32,6 +68,30 @@ PNG still matches the manifest dimensions. The isolated workflow uses LoRA
 strength 1.0, while the environment workflow uses 0.85. Read
 `docs/COMFYUI.md` for download links, checksums, licenses, and measured limits.
 
+The cleanup experiment in
+`benchmarks/provider-postprocessing/comfyui/` runs BiRefNet on the decoded
+full-resolution image, quantizes RGB separately, joins the inverted background
+mask as alpha, and scales last. It proves those nodes run; it is not the complete
+recommended pipeline. Background removal belongs before grid recovery. Final
+palette quantization belongs after grid recovery. Always audit the final native
+file, because reconstruction can introduce averaged colors.
+
+The boundary experiment in
+`benchmarks/provider-hires/comfyui/` keeps generation canvas, native art grid,
+and display size separate. Pixel Art XL can make a 1024px raster whose implied
+cells resolve to a much smaller editable grid. Nearest-neighbor scaling
+preserves those fake cells; it does not repair them. Reconstruct accepted output
+at 1× with a grid-aware tool such as Retro Diffusion Pixel Art Fixer, then
+compose and edit the native PNG. Record the fixer revision, source and output
+hashes, detected grid, confidence, and dimensions.
+
+Do not add `LatentUpscale` and a second sampling pass by default. The tested
+1536px and 2048px variants blurred the output. Nearest-neighbor scaling preserves
+existing cells but cannot repair them. Grid recovery proves structure, not good
+clusters or prompt coverage.
+
+## Operation and recovery
+
 The plan reports `0 free` and generation uses `--budget 0`. Explain that this
 means no metered API charge. Hardware, electricity, hosting, and model licenses
 can still cost money.
@@ -41,6 +101,6 @@ The lockfile records a prompt ID, output node, workflow hash, and portable
 cache is missing, the current ComfyUI server must still retain the history
 output so PixelKiln can resolve the portable source.
 
-For the complete setup, quality stack, benchmark, and troubleshooting, use
+For the complete setup, composition stack, benchmark, and troubleshooting, use
 `docs/COMFYUI.md` or
 <https://pixelkiln.griffen.codes/docs/comfyui>.

package/skills/pixelkiln/references/mixed-providers.md

@@ -46,6 +46,8 @@ that produced it.
 A practical split is PixelLab for prompt-sensitive buildings and mature account
 recovery, then Retro Diffusion for environment-styled backdrops, clean cutouts,
 or native animation. ComfyUI fits private work, local models, and custom graph
-control, but its result depends on the exact workflow, model, nodes, and
-hardware. The committed hosted-provider benchmark is evidence for tendencies,
-not a guarantee. Run one representative asset before expanding any batch.
+control when the user accepts manual native-grid recovery, final palette
+enforcement, and art review. Start with a specialized hosted provider when
+minimizing cleanup matters more than local control. The committed benchmark is
+evidence for tendencies, not a guarantee. Run one representative asset before
+expanding any batch, and test a ComfyUI graph on at least two scene families.