pixelkiln 0.5.0 → 0.7.0

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).

package/examples/comfyui/pixelkiln.manifest.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "../../schema/manifest.schema.json",
+  "name": "pixelkiln-comfyui-smoke",
+  "provider": "comfyui",
+  "styles": {
+    "smoke": {
+      "generator": "map",
+      "outDir": "output/smoke",
+      "promptPrefix": "pixel art game asset",
+      "promptSuffix": "isolated on a plain background, crisp silhouette, limited color palette",
+      "seed": 31415,
+      "providerOptions": {
+        "comfyui": {
+          "workflowFile": "workflow-api.json",
+          "outputNodeId": "9",
+          "numImages": 1,
+          "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": {
+    "anvil": {
+      "prompt": "a compact blacksmith anvil",
+      "width": 256,
+      "height": 256
+    }
+  }
+}

package/examples/comfyui/workflow-api.json

@@ -0,0 +1,59 @@
+{
+  "3": {
+    "class_type": "KSampler",
+    "inputs": {
+      "seed": 31415,
+      "steps": 24,
+      "cfg": 7,
+      "sampler_name": "euler_ancestral",
+      "scheduler": "normal",
+      "denoise": 1,
+      "model": ["4", 0],
+      "positive": ["6", 0],
+      "negative": ["7", 0],
+      "latent_image": ["5", 0]
+    }
+  },
+  "4": {
+    "class_type": "CheckpointLoaderSimple",
+    "inputs": {
+      "ckpt_name": "v1-5-pruned-emaonly-fp16.safetensors"
+    }
+  },
+  "5": {
+    "class_type": "EmptyLatentImage",
+    "inputs": {
+      "width": 256,
+      "height": 256,
+      "batch_size": 1
+    }
+  },
+  "6": {
+    "class_type": "CLIPTextEncode",
+    "inputs": {
+      "text": "pixel art game asset",
+      "clip": ["4", 1]
+    }
+  },
+  "7": {
+    "class_type": "CLIPTextEncode",
+    "inputs": {
+      "text": "photograph, text, watermark, signature, blurry",
+      "clip": ["4", 1]
+    }
+  },
+  "8": {
+    "class_type": "VAEDecode",
+    "inputs": {
+      "samples": ["3", 0],
+      "vae": ["4", 2]
+    }
+  },
+  "9": {
+    "class_type": "SaveImage",
+    "inputs": {
+      "filename_prefix": "pixelkiln/comfyui-smoke",
+      "images": ["8", 0]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,
@@ -80,6 +80,7 @@
     "game-assets",
     "pixellab",
     "retro-diffusion",
+    "comfyui",
     "image-generation",
     "asset-pipeline",
     "generative",

package/schema/manifest.schema.json

@@ -33,8 +33,8 @@
               },
               "size": {
                 "type": "integer",
-                "minimum": 32,
-                "maximum": 256
+                "minimum": 16,
+                "maximum": 8192
               },
               "view": {
                 "type": "string"
@@ -191,12 +191,12 @@
               "width": {
                 "type": "integer",
                 "minimum": 16,
-                "maximum": 400
+                "maximum": 8192
               },
               "height": {
                 "type": "integer",
                 "minimum": 16,
-                "maximum": 400
+                "maximum": 8192
               },
               "size": {
                 "type": "integer",

package/skills/pixelkiln/SKILL.md

@@ -50,7 +50,9 @@ Read only the reference needed for the current decision:
 - For Retro Diffusion styles, USD budgets, environment assets, animation, or
   experimental limits, read
   [references/retro-diffusion.md](references/retro-diffusion.md).
-- When one game or repository needs both providers, read
+- For a self-hosted ComfyUI workflow, node bindings, local cost semantics, or
+  portable output recovery, read [references/comfyui.md](references/comfyui.md).
+- When one game or repository needs more than one provider, read
   [references/mixed-providers.md](references/mixed-providers.md).
 
 `FakeProvider` is the deterministic test adapter. Do not describe Retro
@@ -58,6 +60,6 @@ Diffusion as production-ready until representative multi-candidate, tileset,
 GIF, and spritesheet live smoke tests pass.
 
 When working in the PixelKiln repository, consult `docs/GETTING_STARTED.md` for
-the full workflow, `docs/PIXELLAB.md` or `docs/RETRO_DIFFUSION.md` for provider
-setup, `docs/CLI.md` for flags, `docs/MANIFEST.md` for the schema, and
+the full workflow, the matching provider setup guide, `docs/CLI.md` for flags,
+`docs/MANIFEST.md` for the schema, and
 `docs/RECOVERY.md` before account adoption, salvage, discard, or purge.

package/skills/pixelkiln/references/comfyui.md

@@ -0,0 +1,46 @@
+# ComfyUI
+
+Read this reference before operating a PixelKiln manifest whose provider is
+`comfyui`.
+
+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.
+
+The style's `providerOptions.comfyui` must name a committed API-format workflow,
+one image output node, the expected candidate count, and bindings for prompt,
+width, height, and batch size. A seed binding is required when the style
+declares a seed. Node IDs and model filenames are workflow-specific. Check the
+exported JSON instead of guessing them.
+
+Planning parses and hashes the workflow file without contacting ComfyUI. A
+workflow content change makes affected assets stale. The adapter supports only
+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
+`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
+core nodes only. Its workflows sample at 1024×1024, then use `ImageScale` with
+`nearest-exact`; width and height bindings point to the scale node so the saved
+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 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.
+
+The lockfile records a prompt ID, output node, workflow hash, and portable
+`comfyui://` source. Restore from the validated content cache first. If the
+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
+`docs/COMFYUI.md` or
+<https://pixelkiln.griffen.codes/docs/comfyui>.

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

@@ -1,7 +1,7 @@
 # Mixed-provider projects
 
-Read this reference when one game or repository needs assets from both PixelLab
-and Retro Diffusion.
+Read this reference when one game or repository needs assets from PixelLab,
+Retro Diffusion, ComfyUI, or another combination of providers.
 
 One manifest selects one top-level `provider`. Do not add undocumented
 per-style provider fields: the current CLI constructs one account adapter for a
@@ -15,6 +15,8 @@ art/
   pixelkiln.pixellab.lock.json
   pixelkiln.retrodiffusion.manifest.json
   pixelkiln.retrodiffusion.lock.json
+  pixelkiln.comfyui.manifest.json
+  pixelkiln.comfyui.lock.json
 pixelkiln.workspace.json
 ```
 
@@ -26,18 +28,24 @@ pixelkiln gen --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelki
 
 pixelkiln plan --manifest art/pixelkiln.retrodiffusion.manifest.json --lock art/pixelkiln.retrodiffusion.lock.json
 pixelkiln gen --manifest art/pixelkiln.retrodiffusion.manifest.json --lock art/pixelkiln.retrodiffusion.lock.json --budget <usd>
+
+pixelkiln plan --manifest art/pixelkiln.comfyui.manifest.json --lock art/pixelkiln.comfyui.lock.json
+pixelkiln gen --manifest art/pixelkiln.comfyui.manifest.json --lock art/pixelkiln.comfyui.lock.json --budget 0
 ```
 
-Register both manifests in the workspace catalog so aggregate status and claim
+Register every manifest in the workspace catalog so aggregate status and claim
 checks see the whole project. A mixed-provider warning is expected because it
 prevents account-wide commands from silently assuming one backend.
 
 Package each manifest's reviewed outputs independently, or use `pixelkiln pack
 --inputs <file> --out <path>` with an explicit JSON list when the final sheet
-must combine files from both providers. Never merge the two lockfiles or add
-generation counts to USD. Each entry must retain the provider that produced it.
+must combine files from multiple providers. Never merge their lockfiles or add
+generation counts, USD, and `free` plans. Each entry must retain the provider
+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. The committed benchmark is evidence for those tendencies,
-not a guarantee; run one representative asset before expanding either batch.
+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.

package/skills/pixelkiln/references/pixellab.md

@@ -24,9 +24,11 @@ providers, or before any PixelLab account operation.
 | `tiles` | Ground variations or connected structures | 20–40 generations |
 
 In the committed environment benchmark, PixelLab followed complex building
-prompts more closely and produced the stronger scenic background. Its 256px map
-objects were opaque despite the route's transparency claim, so inspect alpha on
-one representative result before a batch.
+prompts more closely and produced broader, more separable depth bands in scenic
+backgrounds. Its 256px and 384px map objects were opaque despite the route's
+transparency claim, so inspect alpha on one representative result before a
+batch. Inspect scenic outputs for stray marks too: one untouched 384px attempt
+contained a generated signature-like glyph.
 
 For setup and current field constraints, use
 <https://pixelkiln.griffen.codes/docs/pixellab>. When working in the PixelKiln

package/skills/pixelkiln/references/retro-diffusion.md

@@ -31,6 +31,13 @@ cutouts, smaller palettes, cinematic framing, or native animation. Build truly
 large scenes from separately generated terrain, backdrop, landmark, building,
 and foreground layers, then integer-upscale with nearest-neighbor filtering.
 
+The committed 384px benchmark produced substantially larger isometric
+buildings than the earlier 256px brief while retaining 52% to 75%
+transparency and 49 to 55 colors. Its volcanic backgrounds made the pass and
+lava path clear, but dropped a requested fortress and favored close canyon
+framing over separable distant planes. Use a representative large asset before
+assuming prompt details or layerability will survive a batch.
+
 For setup, selectors, and option constraints, use
 <https://pixelkiln.griffen.codes/docs/retro-diffusion>. The matched visual
 evidence is at <https://pixelkiln.griffen.codes/docs/provider-benchmark>. When