pixelkiln 0.11.0 → 0.12.1

package/CONTRIBUTING.md

@@ -15,6 +15,7 @@ npm ci
 npm run test:release
 npm run typecheck
 npm run test:docs
+npm run test:security
 npm test
 npm run build
 npm run test:package
@@ -36,7 +37,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.
 
@@ -72,6 +73,9 @@ wire contracts.
   workflow detail in `docs/`, and link every guide from `docs/README.md`.
 - Run `npm run test:docs` after changing Markdown or the CLI command/flag
   surface. It checks local links, the docs index, README size, and CLI coverage.
+- Run `npm run test:security` after changing provider source handling, lockfile
+  fixtures, or benchmark state. It scans tracked JSON without printing a
+  credential-bearing value.
 - Run the website lint and build checks when changing `website/` or the
   canonical Markdown it renders.
 - Run the package smoke test when changing exports, build configuration, the
@@ -85,6 +89,8 @@ wire contracts.
   I/O and estimates must carry their cost unit.
 - Provider responses are untrusted input and need runtime validation before
   entering the lockfile.
+- Temporary signed URLs must not settle in a committed lockfile. Persist a
+  refreshable provider reference and keep storage credentials transient.
 - Lockfile writes must remain atomic and resumable. Additive defaults should
   preserve valid v2 files when extending lock entries.
 - Unknown flags and ambiguous output selection are errors. Silent widening is

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.
@@ -27,6 +26,8 @@ them.
 Live tests now cover single-candidate RD Fast and RD Plus stills from cost quote
 through submit, poll, PNG download, lockfile provenance, and cache validation.
 The RD Plus run covered isometric-asset, top-down-asset, and environment styles.
+Lockfiles retain refreshable `retrodiffusion://` result references rather than
+temporary signed storage URLs.
 Retro Diffusion's multi-candidate review, tileset, GIF, and spritesheet paths
 have mocked integration coverage but still need representative paid live runs.
 
@@ -41,7 +42,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 +75,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 +93,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 +153,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 +208,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
@@ -61,7 +57,7 @@ PixelKiln supplies the missing project model:
 | Plan and budget | Offline manifest/lock/disk diff, provider-unit estimates, hard `--budget` ceiling, JSON/CI gate. |
 | Generate and review | Resumable submit/poll/pick/fetch pipeline with a fast local candidate sheet. |
 | Existing-art onboarding | Manifest scaffolding, exact-hash account adoption, and prompt recovery. |
-| Recovery | Validated local content cache, provider URL restore, account object-hash cache, and resumable jobs. |
+| Recovery | Validated local content cache, durable provider-reference restore, account object-hash cache, and resumable jobs. |
 | Shared-account safety | Cross-project claim files or a registered workspace catalog, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
 | Quality control | Palette distance, transparency, color-count, relative outlier, cache-integrity, and doctor gates. |
 | Sprite packaging | Deterministic RGBA packing, stable-cell mounting, explicit external input lists, structural output roles. |
@@ -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
 
@@ -30,10 +29,19 @@ reporter.
 
 PixelKiln handles provider credentials, paid API actions, remote object deletion,
 local output paths, a localhost review server, and generated HTML containing
-provider data. Reports involving authentication leakage, path traversal,
+provider data. Temporary provider result URLs can also contain signing
+credentials in their query string. Reports involving authentication leakage, path traversal,
 cross-origin review actions, HTML/script injection, unsafe overwrite/delete
 behavior, lockfile corruption, or budget bypass are security relevant.
 
 Never attach a real `PIXELLAB_API_KEY`, `RD_API_KEY`, `.env` file, private
 provider URL, or unredacted lockfile from a confidential project to a public
 report.
+
+PixelKiln keeps durable provider references in lockfiles when an adapter can
+refresh an expiring result. After successful ingestion it removes signed URLs,
+inline data URLs, and local file URLs from settled lock entries. A failed
+download may retain its source locally so `fetch` can retry, but that in-flight
+lockfile should not be committed. `npm run test:security` checks every tracked
+JSON file for credential-bearing URLs and reports only the file and JSON path,
+never the sensitive value.

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,