pixelkiln 0.10.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 |
@@ -72,13 +71,13 @@ prompt, size, batch, and optional seed inputs PixelKiln may replace.
 | 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 live generation, four-candidate review, and cache-only restore on Apple MPS; cleanup and native-grid experiments remain manual, and aesthetic approval remains human |
+| 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,11 +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, 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.
+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
@@ -238,20 +237,18 @@ documents free cost preflights. That combination adds something the current
 providers do not: a project-specific visual model with a cost check that can be
 captured before submission.
 
-Recommended order:
+Recommended order from here:
 
-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
+1. 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
+2. Add per-style provider selection, provider-keyed budgets, and mixed-provider
    integration tests.
-4. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
+3. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
    smoke tests.
-5. Build the Scenario still-image spike from issue #52 with dry-run cost, submit, poll,
+4. Build the Scenario still-image spike from issue #52 with dry-run cost, submit, poll,
    download, and one custom-model or reference-image benchmark.
-6. Design ComfyUI Cloud as a separate authenticated and billable adapter.
-7. Consider general raster marketplaces only with explicit nearest-neighbor,
+5. Design ComfyUI Cloud as a separate authenticated and billable adapter.
+6. 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

@@ -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
@@ -197,8 +193,14 @@ 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.
+instead of chasing a larger raster. Background removal and the art decision
+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).
@@ -219,6 +221,12 @@ pixelkiln restore
 # Optional local gates.
 pixelkiln audit --check --max-distance 35 --min-transparency 0.1
 pixelkiln cache --check
+
+# Provider-neutral pixel cleanup after selecting a generated candidate.
+pixelkiln refine --from candidate.png --out art/native.png \
+  --palette "#141b1e,#23312a,#384d4f,#526a8d,#709fcf,#865c45,#c6a766,#f1bb70"
+pixelkiln refine approve --from art/native.pixelkiln.json --reviewer "Your Name"
+pixelkiln refine check --from art/native.pixelkiln.json
 ```
 
 Repeated `--style`, `--only`, `--claims`, and `--output-role` filters
@@ -339,9 +347,10 @@ 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, 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).
+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).
 
 ## Documentation
 
@@ -352,14 +361,15 @@ writes, and offline provenance verification. See [Library API](./docs/LIBRARY.md
 | [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. |
 | [Generators](./docs/GENERATORS.md) | Capability choice, measured costs, palettes, style references, and tiles. |
-| [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. |
+| [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, audit, cache, 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

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+type GridConfidence = "low" | "medium" | "high";
+
 type TilesetFormat = "generic" | "tiled" | "godot";
 
 interface Args {
@@ -34,11 +36,19 @@ interface Args {
     minTransparency?: number;
     maxColors?: number;
     sigma?: number;
-    /** `workspace`: add/remove/list/status/claims. */
+    palette: string[];
+    fixerPython?: string;
+    fixerRevision?: string;
+    minGridConfidence?: GridConfidence;
+    reviewer?: string;
+    note?: string;
+    /** 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;
@@ -52,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", "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,