pixelkiln 0.11.0 → 0.12.0

package/CONTRIBUTING.md

@@ -36,7 +36,7 @@ build time. Do not create a second documentation copy under `website/`.
 Website sprites are generated from `website/art/pixelkiln.manifest.json`.
 Treat those requests as paid work: run `plan` and `audit` first, use an explicit
 hard budget, and commit the manifest, lockfile, and reviewed outputs together.
-The Review UI showcase should be captured at 1280×720 only after every asset
+Capture the Review UI at 1280×720 only after every asset
 loads. Give a replacement capture a new public filename and update the page
 reference so deployed image caches cannot retain the old version.
 

package/PROVIDERS.md

@@ -1,16 +1,15 @@
 # Provider comparison
 
-PixelKiln can route one manifest through PixelLab, Retro Diffusion, or a
-self-hosted ComfyUI server.
-The project model keeps planning, hard budgets, lockfile provenance, human
-review, recovery, and packaging. Each adapter owns its service's
-authentication, pricing, validation, request lifecycle, and output formats.
+PixelKiln can run one manifest through PixelLab, Retro Diffusion, or a
+self-hosted ComfyUI server. Planning, budgets, review, recovery, and packaging
+stay the same. Each adapter handles its service's authentication, prices,
+request lifecycle, and file formats.
 
 PixelLab remains the default so existing manifests and spec hashes remain
 compatible. Select another backend with the manifest's top-level `provider`
 field and keep its settings under the matching `providerOptions` key.
 
-Ready to configure a project? Use [Set up PixelLab](./docs/PIXELLAB.md),
+To configure a project, use [Set up PixelLab](./docs/PIXELLAB.md),
 [Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), or
 [Set up ComfyUI](./docs/COMFYUI.md). This page focuses on choosing between
 them.
@@ -41,7 +40,7 @@ the providers offer directly.
 
 | Decision | PixelLab | Retro Diffusion |
 |---|---|---|
-| Best fit today | Established PixelKiln projects, account reconciliation, and fully live-tested generation | Native pixel-art styles, cash-denominated cost control, animation, and alternate tileset workflows |
+| Best fit today | Existing PixelKiln projects, account reconciliation, and live-tested generation | Native pixel-art styles, USD budgets, animation, and alternate tileset workflows |
 | PixelKiln generators | `map`, `pixflux`, `1dir`, `tiles` | `map` and `pixflux` stills, `tiles`, `animation` |
 | Output | PNG stills, candidates, and structural tile members | PNG stills/tiles/spritesheets or animated GIF |
 | Candidate review | Yes; count varies by generator and size | Yes for 1–16 still candidates; animations and tilesets currently use one result |
@@ -74,11 +73,11 @@ prompt, size, batch, and optional seed inputs PixelKiln may replace.
 | Account lifecycle | Read-only connectivity check; no balance, remote object listing, tagging, or purge |
 | Confidence | Full mocked coverage plus live generation, four-candidate review, cache-only restore, and three provider-neutral refinement runs on Apple MPS; background removal stays in the graph and aesthetic approval remains human |
 
-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.
+Choose ComfyUI when control over the graph is worth the extra validation. Start
+with a hosted provider when you want less cleanup. Two ComfyUI machines can run
+the same graph and still differ because their checkpoint bytes, custom nodes,
+or sampler settings differ. Commit the workflow and record the model stack used
+to test it.
 
 ## Large environments, mountains, and buildings
 
@@ -92,11 +91,11 @@ background. That distinction matters more than raw canvas size.
 | 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. |
 
-For production environments, prefer a kit over a monolith: seamless terrain,
-separate landmarks/buildings, foreground occluders, and a distant backdrop.
-This produces reusable assets, cleaner parallax, easier collision/lighting, and
-cheaper targeted re-rolls. Generate at the intended native pixel resolution,
-then scale by an integer with nearest-neighbor filtering.
+For a production environment, build a kit: seamless terrain, separate
+landmarks and buildings, foreground occluders, and a distant backdrop. You can
+rerun one weak piece, set collision per object, and move layers independently
+for parallax. Generate each piece at its native pixel resolution, then use
+integer nearest-neighbor scaling.
 
 A visual benchmark should use the same briefs for an isolated building, a
 top-down landmark, and a full scenic background. Use the same intended native
@@ -152,7 +151,7 @@ complete claim checks. Keep the provider lockfiles separate. Package their
 reviewed outputs independently, or combine explicit files with `pixelkiln pack
 --inputs <file> --out <path>`.
 
-This is a useful split when PixelLab handles prompt-sensitive buildings and
+This split works 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 experiments that can absorb manual cleanup. Retro Diffusion is not a higher-resolution
@@ -207,12 +206,11 @@ estimate and hard budget remain enforced.
 
 ## What to build next
 
-The first ComfyUI release has a live, versioned core-node reference workflow.
-Transport, candidate review, provenance, cache recovery, native-grid recovery,
-final palette enforcement, and a fail-closed approval record now work. The
-tested SDXL plus Pixel Art XL graph is useful for composition, but it is not a
-production preset. Background removal stays in the graph. Prompt coverage,
-pixel clusters, and aesthetic approval still require a person.
+The ComfyUI adapter now has a live, versioned core-node workflow. Generation,
+candidate review, cache recovery, native-grid recovery, palette enforcement,
+and the approval record work. The tested SDXL plus Pixel Art XL graph can find
+a composition, but it is not a production preset. Background removal stays in
+the graph. A person must still check the brief, pixel clusters, and drawing.
 
 Native per-style provider routing remains the highest-value orchestration
 feature. One manifest should be able to send a building style to PixelLab, an

package/README.md

@@ -6,42 +6,38 @@
 [Documentation](https://pixelkiln.griffen.codes/docs) ·
 [GitHub](https://github.com/gfargo/pixelkiln)
 
-Manifest-driven pixel-art generation, review, recovery, quality control, and
-game-ready asset packaging.
-
-PixelKiln treats generated art like a build pipeline: declare assets once,
-preview cost and drift, generate only the missing work, review candidates in a
-local contact sheet, and commit exact provenance beside the files. No LLM is in
-the orchestration loop; provider calls, polling, hashing, downloads, and filing
-are deterministic software mechanics.
-
-The orchestration layer is provider-neutral. PixelLab is the production,
-live-tested backend. An experimental Retro Diffusion adapter supports native
-pixel-art stills, candidate batches, tileset sheets, animated GIFs, and PNG
-spritesheets. Authenticated RD Fast and RD Plus single-candidate still paths
-have passed from quote through validated output and recovery. Multi-candidate,
-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 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.
-
-> **Release status:** PixelKiln is published on npm. Merges to `main` use
-> Semantic Release and npm Trusted Publishing, with signed provenance and no
-> long-lived npm publishing token.
+Generate pixel art from a manifest, review it locally, recover paid work, and
+package the accepted files for a game engine.
+
+PixelKiln treats generated art as build output. Declare assets once, inspect the
+cost and changed work, generate only what is missing, choose candidates in a
+local contact sheet, and commit the source and output hashes. No LLM chooses
+what to run or which image wins. The CLI handles provider calls, polling,
+hashing, downloads, and file placement.
+
+PixelLab is the production backend. Retro Diffusion and self-hosted ComfyUI are
+experimental. The Retro Diffusion adapter has live coverage for RD Fast and RD
+Plus stills; its multi-candidate, tileset, GIF, and spritesheet paths are tested
+with fixtures but still need paid live runs. ComfyUI has passed local generation,
+four-candidate review, cache recovery, and native-grid refinement on Apple MPS.
+Its tested SDXL workflow can find a composition, but it is not a finished
+pixel-art preset. The [provider comparison](./PROVIDERS.md) lists the tested
+limits and the best route for buildings and environments. `FakeProvider` covers
+the same contract in automated tests.
+
+## Release
+
+PixelKiln is published on npm. Merges to `main` use Semantic Release and npm
+Trusted Publishing, with signed provenance and no long-lived npm token.
 
 ## Why PixelKiln
 
-A typical image-generation account becomes two unrelated piles: remote objects
-that cost money and local files with no durable explanation of where they came
-from. Handwritten prompts drift, failed downloads look like failed generations,
-and regenerating a whole set is easier than determining what is actually stale.
+Image generators leave two piles behind: remote jobs that cost money and local
+files that no longer explain where they came from. Prompts drift. Failed
+downloads look like failed generations. Teams rerun whole sets because they
+cannot tell which asset changed.
 
-PixelKiln supplies the missing project model:
+PixelKiln keeps the missing record:
 
 - a committed manifest defines assets, styles, generators, budgets, and output;
 - a committed lockfile maps each style/asset to paid provider work and exact
@@ -69,7 +65,7 @@ PixelKiln supplies the missing project model:
 | Artifact integrity | Portable source/output hashes, canonical fingerprints, manual-edit protection, transactional promotion, crash journal recovery. |
 | Library/extension | Public TypeScript primitives, provider capability interface, and deterministic `FakeProvider`. |
 
-### Human review, kept local
+### Local human review
 
 `pixelkiln pick` opens an actual local candidate sheet; the orchestration layer
 never asks a model to choose artwork for you.
@@ -78,7 +74,7 @@ never asks a model to choose artwork for you.
 
 Use Left/Right to inspect alternatives, Enter or 1–9 to select, and 0 to leave
 a row unresolved. Nothing is applied when the window is closed without using
-**Apply selections**. See the [CLI reference](docs/CLI.md#pick) for the complete
+**Apply selections**. See the [CLI reference](docs/CLI.md#pick) for the full
 review workflow.
 
 ## Install
@@ -202,6 +198,10 @@ still need the graph and a person. `pixelkiln refine` now handles grid recovery,
 final palette enforcement, measurable checks, and the hash-bound approval
 record.
 
+Versioned recipes capture tested workflows, model hashes, license links, and
+manifest-ready styles with quality boundaries. Start with `pixelkiln recipe install comfyui/pixel-art-xl-environment@1.0.0`.
+Recipes install no models and make no provider calls. See [Versioned recipes](./docs/RECIPES.md).
+
 The schema rejects unknown fields and invalid generator combinations before
 planning. See the [Manifest reference](./docs/MANIFEST.md).
 
@@ -347,7 +347,7 @@ const plan = await buildPlan(specs, await loadLock("pixelkiln.lock.json"))
 console.log(plan.cost, plan.costUnit, plan.actionable.length)
 ```
 
-The package also exports audit gates, provider-neutral refinement, lock/output
+The package also exports audit and image-regression gates, provider-neutral refinement, lock/output
 helpers, provider contracts, pipeline stages, sprite packing/mounting, tile
 exporters, managed artifact writes, and offline provenance verification. See
 [Library API](./docs/LIBRARY.md).
@@ -361,6 +361,7 @@ exporters, managed artifact writes, and offline provenance verification. See
 | [Set up PixelLab](./docs/PIXELLAB.md) | Production-provider credentials, manifest, generators, and account workflows. |
 | [Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md) | Experimental-provider credentials, styles, formats, cost checks, and limits. |
 | [Set up ComfyUI](./docs/COMFYUI.md) | Experimental self-hosted server, workflow bindings, local cost semantics, and limits. |
+| [Versioned recipes](./docs/RECIPES.md) | Pinned workflow packs, model hashes, manifest templates, and quality contracts. |
 | [CLI reference](./docs/CLI.md) | Every command, flag, JSON mode, and exit contract. |
 | [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. |
@@ -368,7 +369,7 @@ exporters, managed artifact writes, and offline provenance verification. See
 | [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Thirty provider outputs plus native-grid and final-palette results comparing large scenes, transparency, palette size, and file readiness. |
 | [Derived artifacts](./docs/ARTIFACTS.md) | Refine, 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, refine, audit, cache, human approval, JSON, and CI. |
+| [Quality gates](./docs/QUALITY.md) | Image baselines, plan, doctor, refine, audit, cache, human approval, JSON, and CI. |
 | [Architecture](./docs/ARCHITECTURE.md) | State model, lockfile, providers, concurrency, and output identity. |
 | [Library API](./docs/LIBRARY.md) | Public TypeScript contracts and examples. |
 | [Tiles](./docs/TILES.md) | Structural outputs and generic/Tiled/Godot formats. |

package/SECURITY.md

@@ -2,9 +2,8 @@
 
 ## Supported versions
 
-Until the first npm release, security fixes are applied to `main`. After
-publication, the latest released line and `main` are supported; older versions
-may be asked to upgrade before a fix is backported.
+Security fixes target `main` and the latest npm release. Older versions may
+need to upgrade before a fix is backported.
 
 ## Reporting a vulnerability
 

package/dist/cli.d.ts

@@ -42,11 +42,13 @@ interface Args {
     minGridConfidence?: GridConfidence;
     reviewer?: string;
     note?: string;
-    /** `workspace`: add/remove/list/status/claims. */
+    /** ComfyUI `models` directory used for offline recipe model verification. */
+    modelRoot?: string;
+    /** Subcommand for `quality`, `recipe`, `refine`, or `workspace`. */
     subcommand?: string;
     /** Path to a workspace catalog. Defaults to `pixelkiln.workspace.json` in cwd. */
     workspace?: string;
-    /** `workspace add`: manifest path. `workspace remove`: project id or manifest path. */
+    /** Positional target for recipe and workspace subcommands. */
     target?: string;
     /** `workspace add`: provider id to register the project under. Defaults to "pixellab". */
     provider?: string;
@@ -60,7 +62,7 @@ interface Args {
      */
     explicitLock?: string;
 }
-declare const COMMANDS: readonly ["init", "plan", "doctor", "gen", "submit", "poll", "pick", "fetch", "restore", "adopt", "accept", "salvage", "purge", "prune", "audit", "cache", "pack", "mount", "export", "tag", "balance", "status", "refine", "workspace", "help", "--help", "-h", "--version", "-v"];
+declare const COMMANDS: readonly ["init", "plan", "doctor", "gen", "submit", "poll", "pick", "fetch", "restore", "adopt", "accept", "salvage", "purge", "prune", "audit", "cache", "pack", "mount", "export", "tag", "balance", "status", "quality", "refine", "recipe", "workspace", "help", "--help", "-h", "--version", "-v"];
 /**
  * Strict parsing. Unknown flags are a hard error rather than being ignored,
  * because a silently-dropped filter is expensive here: `--styles neon` (plural,