pixelkiln 0.4.1 → 0.6.0

package/CONTRIBUTING.md

@@ -11,6 +11,7 @@ Requires Node.js 20 or newer.
 
 ```bash
 npm ci
+npm run test:release
 npm run typecheck
 npm run test:docs
 npm test
@@ -114,6 +115,17 @@ short-lived credential, and the npm CLI performs the exchange itself during
 signed provenance attestation linking the tarball to its source commit and
 workflow run.
 
+The release job is serialized so two quick merges cannot publish concurrently,
+and it times out after 20 minutes rather than holding publishing permission
+indefinitely. `npm run test:release` checks the repository-side trust contract:
+the OIDC permission, GitHub-hosted runner, registry configuration, full checkout
+history, absence of an npm publishing token, and the expected release plugins.
+
+The public `gfargo/skills` tap watches PixelKiln releases on an hourly schedule.
+When a new tag appears, it mirrors the tagged `skills/pixelkiln/` directory,
+bumps the games plugin, and publishes a games release. PixelKiln remains the
+source of truth; the source repository needs no cross-repository write token.
+
 Two conditions have to hold on the npm side, and neither lives in this
 repository:
 

package/PROVIDERS.md

@@ -78,7 +78,58 @@ provider unit. Seeds are provider-specific, so equal seed numbers do not make
 the outputs directly reproducible across services.
 
 See the [environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) for the
-twelve generated images, prompts, manifests, measured costs, and review.
+twenty generated images, prompts, manifests, measured costs, and review. The
+384×384 additions test a larger cliffside building and a full volcanic
+background.
+
+## Use both providers in one project
+
+One manifest selects one provider. PixelKiln does not currently support a
+provider override on an individual style or asset. The boundary is deliberate:
+one command constructs one account adapter, and one `--budget` must have one
+meaning. PixelLab generations and Retro Diffusion dollars cannot share a safe
+ceiling.
+
+A repository can still use both providers today. Give each provider its own
+manifest, lockfile, and output directory:
+
+```text
+art/
+  pixelkiln.pixellab.manifest.json
+  pixelkiln.pixellab.lock.json
+  pixelkiln.retrodiffusion.manifest.json
+  pixelkiln.retrodiffusion.lock.json
+pixelkiln.workspace.json
+```
+
+Plan and authorize each manifest separately:
+
+```bash
+pixelkiln plan --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json
+pixelkiln gen --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json --budget <generations>
+
+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>
+```
+
+Register both manifests in the workspace catalog for aggregate status and
+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
+account recovery while Retro Diffusion handles environment-styled backdrops,
+clean cutouts, or native animation. 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.
+
+Native mixed-provider support inside one manifest would be a larger feature,
+not a schema-only change. It needs provider selection on each style, plans and
+confirmations grouped by provider and cost unit, separate budget ceilings,
+per-provider polling and downloads, and an explicit provider for account-wide
+commands. The lockfile already records a provider on every entry, so the state
+format can support that direction without merging provider identities.
 
 ## Cost comparison
 
@@ -118,16 +169,56 @@ is interpreted in the active provider's unit. Providers without a balance or
 account-management endpoint can still generate safely because the offline
 estimate and hard budget remain enforced.
 
-## Next validation and expansion
-
-1. Complete representative paid Retro Diffusion multi-candidate, tileset, GIF,
-   and spritesheet smoke tests without logging credentials. Single-candidate RD
-   Fast and RD Plus still paths have passed end to end.
-2. Promote only the workflows proven against the live service; keep unsupported
-   account operations explicit capability errors.
-3. Evaluate Scenario as another hosted game-asset provider.
-4. Add a local ComfyUI adapter for GPU-backed, no-per-call-cost generation.
-5. Consider general raster providers only with explicit nearest-neighbor,
+## What to build next
+
+The highest-value next feature is native per-style provider routing, not a third
+adapter. The benchmark now shows a useful split: PixelLab follows dense
+building briefs more reliably, while Retro Diffusion returns cleaner cutouts
+and strong close environment framing. Two manifests make that combination
+possible, but awkward. One manifest should be able to send a building style to
+PixelLab and a background or animation style to Retro Diffusion.
+
+This needs provider-keyed budgets and confirmations, not a provider field added
+in isolation. A safe plan must keep `4 generations` and `$0.40` separate,
+construct and rate-limit each adapter independently, and require an explicit
+provider for account-wide commands. The lockfile already records the provider
+on each entry, so its identity model is ready for the change.
+
+After that, Scenario is the best next hosted provider candidate.
+
+| Candidate | What it adds | Fit with PixelKiln | Main cost or risk | Priority |
+|---|---|---|---|---:|
+| Scenario | Custom-trained style models, references, image editing, background removal, upscaling, and managed assets | Async jobs, asset IDs, and free `dryRun` cost estimates map closely to PixelKiln's plan/submit/poll/download lifecycle | API access requires a paid plan; auth uses both an API key and secret, so the provider factory must describe more than one credential | 1 |
+| ComfyUI local/cloud | Reproducible workflow graphs, broad model choice, local GPU execution, and a cloud path using a compatible API | Workflow JSON could become a durable provenance input; jobs and output downloads already resemble the current provider boundary | Local cost has no universal provider unit; the cloud API is marked experimental and requires a subscription | 2 |
+| fal | A large hosted model catalog, including pixel-art style controls, LoRAs, editing, upscaling, and background removal | Queue-based requests and model schemas are accessible through one client | Model-specific schemas and prices move the adapter toward a marketplace abstraction rather than one stable art workflow | 3 |
+
+Scenario deserves the first spike because its [custom generation API](https://docs.scenario.com/get-started/generation/third-party-model-generation)
+returns an asynchronous job ID, its [generation surface](https://docs.scenario.com/get-started/documentation/key-capabilities-at-a-glance)
+supports custom models and image references, and its
+[Compute Unit guidance](https://help.scenario.com/articles/7934059476-api-usage-and-credits-compute-units)
+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.
+
+ComfyUI should follow. Its [local server API](https://docs.comfy.org/development/overview)
+would cover private or offline GPU workflows, while the
+[cloud API](https://docs.comfy.org/development/cloud/overview) accepts the same
+workflow-shaped requests and exposes asynchronous jobs. The adapter needs an
+explicit budget policy before implementation. A local run could report planned
+image count and measured execution time, but it must not pretend those values
+are a portable dollar estimate.
+
+Recommended order:
+
+1. Add per-style provider selection, provider-keyed budgets, and mixed-provider
+   integration tests.
+2. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
+   smoke tests.
+3. Build a narrow Scenario still-image spike with dry-run cost, submit, poll,
+   download, and one custom-model or reference-image benchmark.
+4. Define local and cloud budget semantics for ComfyUI, then prototype one
+   versioned workflow.
+5. 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

@@ -25,9 +25,9 @@ tileset, GIF, and spritesheet live runs remain. See
 large environment and building workflows.
 `FakeProvider` exercises the same contract deterministically in tests.
 
-> **Release status:** the package is pre-1.0 and the first npm publication is
-> tracked in [issue #1](https://github.com/gfargo/pixelkiln/issues/1). Until it
-> is live, use a repository checkout.
+> **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.
 
 ## Why PixelKiln
 
@@ -76,21 +76,18 @@ 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
 review workflow.
 
-## Install from a checkout
+## Install
 
 Requires Node.js 20 or newer.
 
 ```bash
-git clone https://github.com/gfargo/pixelkiln.git
-cd pixelkiln
-npm ci
-npm run pixelkiln -- help
-npm test
+npm install --save-dev pixelkiln
+npx pixelkiln --help
 ```
 
-`npm run pixelkiln -- …` executes the TypeScript source. `npm run build`
-creates the ESM, CommonJS, declarations, and CLI distribution used by the
-published package.
+For library use, both `import("pixelkiln")` and `require("pixelkiln")` are
+supported. Contributors can still run `npm run pixelkiln -- …` from a checkout
+to execute the TypeScript source directly.
 
 ## Five-minute start
 
@@ -114,14 +111,11 @@ RD_API_KEY=...
 Validate locally, inspect exact work/cost, then generate with a hard ceiling:
 
 ```bash
-/path/to/pixelkiln/node_modules/.bin/tsx /path/to/pixelkiln/src/cli.ts doctor --dry-run
-/path/to/pixelkiln/node_modules/.bin/tsx /path/to/pixelkiln/src/cli.ts plan
-/path/to/pixelkiln/node_modules/.bin/tsx /path/to/pixelkiln/src/cli.ts gen --budget 120
+npx pixelkiln doctor --dry-run
+npx pixelkiln plan
+npx pixelkiln gen --budget 120
 ```
 
-Once installed from npm, those commands become `pixelkiln doctor`,
-`pixelkiln plan`, and `pixelkiln gen`.
-
 `gen` submits, polls, opens the candidate-review sheet when necessary,
 downloads validated output, populates the recovery cache, and updates
 `pixelkiln.lock.json`. Commit the manifest, lockfile, generated art, and any
@@ -342,7 +336,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) | Twelve matched outputs comparing buildings, landmarks, backgrounds, cost, and file readiness. |
+| [Environment provider benchmark](./docs/PROVIDER_BENCHMARK.md) | Twenty matched outputs comparing buildings, landmarks, large backgrounds, cost, 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

@@ -59,6 +59,13 @@ new project or a large environment asset. Once chosen, follow
 [Set up PixelLab](./PIXELLAB.md) or
 [Set up Retro Diffusion](./RETRO_DIFFUSION.md).
 
+The installed skill keeps the shared safety workflow in `SKILL.md` and loads a
+focused reference only when needed: PixelLab, Retro Diffusion, or a project that
+uses both. Mixed-provider repositories should use separate manifests and
+lockfiles so each plan and budget keeps its provider-specific unit. The
+[provider comparison](../PROVIDERS.md#use-both-providers-in-one-project) has a
+complete layout and command example.
+
 ## Recommended first prompt
 
 ```text

package/docs/GETTING_STARTED.md

@@ -11,18 +11,16 @@ checks need provider access.
 - Node.js 20 or newer
 - A credential for the manifest's selected provider: `PIXELLAB_API_KEY` for
   PixelLab or `RD_API_KEY` for experimental Retro Diffusion support
-- A repository checkout until the first npm release in
-  [issue #1](https://github.com/gfargo/pixelkiln/issues/1) is complete
 
-From a checkout:
+Install the published package in the project that owns the art:
 
 ```bash
-npm ci
-npm run pixelkiln -- help
+npm install --save-dev pixelkiln
+npx pixelkiln --help
 ```
 
-The rest of this guide uses `pixelkiln` for readability. In the checkout,
-replace it with `npm run pixelkiln --`.
+The rest of this guide uses `pixelkiln` for readability. With a project-local
+installation, prefix commands with `npx` or call them from an npm script.
 
 ## Using an agent
 
@@ -71,6 +69,9 @@ provider options and current limits, or
 [PixelLab vs. Retro Diffusion](../PROVIDERS.md) for selection guidance.
 The provider setup guides give the shortest complete path for
 [PixelLab](PIXELLAB.md) and [Retro Diffusion](RETRO_DIFFUSION.md).
+If one repository needs both, use separate provider-specific manifests and
+lockfiles. See
+[Use both providers in one project](../PROVIDERS.md#use-both-providers-in-one-project).
 
 Before spending anything, validate and price the selected work:
 

package/docs/PROVIDER_BENCHMARK.md

@@ -1,8 +1,10 @@
 # Environment provider benchmark
 
-This benchmark compares PixelLab and Retro Diffusion on three 256×256 game-art
-briefs. Each brief has two attempts. The test uses the same prompt text and seed
-numbers for both providers, but seeds are not portable between models.
+This benchmark compares PixelLab and Retro Diffusion on five game-art briefs.
+Three briefs use 256×256 output; two use 384×384 to test larger buildings and
+environment backgrounds. Each brief has two attempts. The test uses the same
+prompt text and seed numbers for both providers, 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.
@@ -14,10 +16,12 @@ model or endpoint sold by either provider.
 | Mountain observatory | `map`, high top-down view | `rd_plus__isometric_asset` | Isolated building on a snowy ridge |
 | River gate | `map`, low top-down view | `rd_plus__topdown_asset` | Isolated landmark spanning water |
 | Alpine valley | `pixflux`, background kept | `rd_plus__environment` | Full scenic background |
+| Cliffside fortress | `map`, high top-down view | `rd_plus__isometric_asset` | Large isolated building complex |
+| Volcanic pass | `pixflux`, background kept | `rd_plus__environment` | Full scenic background with reusable depth planes |
 
-Both manifests request 256×256 output with seeds `31415` and `27182`. The
-provider-specific route or style is allowed to do its job. No image was picked,
-edited, cropped, or post-processed.
+Both manifests use seeds `31415` and `27182`. The provider-specific route or
+style is allowed to do its job. No image was picked, edited, cropped, or
+post-processed.
 
 PixelLab rejected `view: "isometric"` on the `map` endpoint with HTTP 422. The
 successful observatory attempts use the supported `high top-down` view while
@@ -93,15 +97,67 @@ For this brief, PixelLab wins on prompt coverage, graphic clarity, consistency,
 and cost. Retro Diffusion wins if the desired result is a closer, more cinematic
 scene.
 
+## Cliffside fortress at 384×384
+
+Prompt: `a large fortified monastery built into a sheer mountain cliff,
+isometric three-quarter view, central stone keep, two side towers, terraced
+stairs, copper roofs, isolated with no scenery`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab cliffside fortress attempt A](../website/public/benchmarks/provider-environments/pixellab/isolated/a/cliffside-fortress.png) | ![PixelLab cliffside fortress attempt B](../website/public/benchmarks/provider-environments/pixellab/isolated/b/cliffside-fortress.png) | ![Retro Diffusion cliffside fortress attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/isolated/a/cliffside-fortress.png) | ![Retro Diffusion cliffside fortress attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/isolated/b/cliffside-fortress.png) |
+
+The larger canvas helped both providers. PixelLab used most of the frame and
+kept the cliff, stairs, central keep, and tower structure legible. Attempt B is
+the clearest match for a fortified monastery. Both outputs still include an
+opaque gray field, and their 246 and 249 colors would need deliberate cleanup
+for a tightly controlled palette.
+
+Retro Diffusion improved markedly over its 256×256 observatory attempts. Both
+results read as substantial cliffside compounds, and attempt B makes good use
+of the full canvas. They are ready-to-place transparent cutouts with 75% and
+52% transparent pixels and only 55 and 49 colors. PixelLab is more reliable on
+the exact architectural brief. Retro Diffusion is closer to a finished modular
+map asset.
+
+## Volcanic pass at 384×384
+
+Prompt: `a wide volcanic mountain pass at dawn, layered black peaks, glowing
+lava river, basalt fortress in the middle distance, smoke plumes, full-bleed
+parallax background with open sky`
+
+| PixelLab A | PixelLab B | Retro Diffusion A | Retro Diffusion B |
+|---|---|---|---|
+| ![PixelLab volcanic pass attempt A](../website/public/benchmarks/provider-environments/pixellab/background/a/volcanic-pass.png) | ![PixelLab volcanic pass attempt B](../website/public/benchmarks/provider-environments/pixellab/background/b/volcanic-pass.png) | ![Retro Diffusion volcanic pass attempt A](../website/public/benchmarks/provider-environments/retrodiffusion/background/a/volcanic-pass.png) | ![Retro Diffusion volcanic pass attempt B](../website/public/benchmarks/provider-environments/retrodiffusion/background/b/volcanic-pass.png) |
+
+PixelLab produced broader compositions with open sky and visibly separated
+mountain planes. Attempt A includes the smoke plume and a clear volcano; attempt
+B simplifies the scene into a graphic basin. Neither attempt includes a
+recognizable fortress. Attempt A also contains a generated signature-like mark
+in the lower-right corner, so it is not usable without cleanup. The files use
+44 and 26 colors.
+
+Retro Diffusion made the pass and lava river unmistakable in both attempts. Its
+narrow canyon framing is strong for a scene the player enters, but it leaves
+less open sky and fewer obvious planes for a distant backdrop. It also dropped
+the fortress and most of the smoke detail. The files use 26 and 25 colors.
+
+None of these four files is a finished parallax package. They are flattened,
+opaque scenes. PixelLab gives an artist clearer depth bands to cut apart; Retro
+Diffusion gives the stronger single-frame canyon. A production workflow should
+generate or extract the sky, distant peaks, middle ground, and foreground as
+separate assets.
+
 ## Cost and operational results
 
 | Provider | Successful images | Charged amount | Final balance |
 |---|---:|---:|---:|
-| PixelLab | 6 | 6 generations | 4,415 generations |
-| Retro Diffusion | 6 | $0.348 | $0.135 |
+| PixelLab | 10 | 10 generations | 4,411 generations |
+| Retro Diffusion | 10 | $0.744 | $9.73 |
 
 PixelLab charged one generation per image. Retro Diffusion quoted and charged
-$0.058 per RD Plus image.
+$0.058 for each 256px RD Plus image and $0.099 for each 384px RD Plus image;
+PixelKiln's hard ceiling rounds the latter to $0.10 per image.
 
 The run also caught two integration details:
 
@@ -111,15 +167,16 @@ The run also caught two integration details:
   $0.057768 to $0.058. PixelKiln now rounds offline estimates up to the live
   quote precision, so planning remains a safe ceiling.
 
-Both manifests now pass `doctor`, report a current plan, and have six healthy
+Both manifests now pass `doctor`, report a current plan, and have ten healthy
 PNG cache entries.
 
 ## Recommendation
 
 For large isolated buildings or landmarks, start with PixelLab when prompt
 coverage matters most. Budget for background cleanup. Start with Retro
-Diffusion when a transparent, compact, low-color asset matters more than
-capturing every noun in a complex prompt.
+Diffusion when a transparent, low-color asset matters more than capturing every
+noun in a complex prompt. At 384×384, Retro Diffusion can fill the frame with a
+substantial structure rather than the compact cutouts seen in the first brief.
 
 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
@@ -130,5 +187,7 @@ background, buildings, landmarks, and foreground pieces separately. Compose
 them in the engine, 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. Rerun the
-committed manifests when either provider changes its models.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,
@@ -29,6 +29,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:docs": "node scripts/check-docs.mjs",
+    "test:release": "node scripts/check-release.mjs",
     "test:package": "node scripts/smoke-package.mjs",
     "test:watch": "vitest",
     "schema": "tsx scripts/gen-schema.ts",

package/skills/pixelkiln/SKILL.md

@@ -12,9 +12,7 @@ submission, reviewed by a human, and recorded with exact provenance.
 
 - Locate `pixelkiln.manifest.json` first. Paths are manifest-relative.
 - Never inspect, print, or commit provider credentials. Read the manifest's
-  top-level `provider`: PixelKiln loads `PIXELLAB_API_KEY` for `pixellab` and
-  `RD_API_KEY` for experimental `retrodiffusion` from `.env.local` beside the
-  manifest or from the current working directory.
+  top-level `provider`, then load the matching provider reference below.
 - Run `pixelkiln doctor --dry-run` and `pixelkiln plan` before paid work. Report
   actionable, recoverable, and estimated cost figures with their provider unit.
 - Do not regenerate recoverable work. Use `pixelkiln restore` first.
@@ -43,11 +41,18 @@ debugging one phase. Use `restore` for missing bytes, `adopt` for exact matches
 already in the provider account, and `salvage` for reviewed unclaimed objects.
 Use `pack`, `mount`, or `export` only for the artifact format the project needs.
 
-PixelKiln's orchestration is provider-neutral. PixelLab is its production and
-paid-generation-tested adapter. Retro Diffusion stills, tileset sheets,
-animated GIFs, and PNG spritesheets are experimental. Authenticated RD Fast and
-RD Plus single-candidate stills have passed from quote through validated output
-and recovery. Advanced workflows remain mock-tested.
+## Provider routing
+
+Read only the reference needed for the current decision:
+
+- For PixelLab configuration, generators, costs, alpha behavior, or account
+  operations, read [references/pixellab.md](references/pixellab.md).
+- 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
+  [references/mixed-providers.md](references/mixed-providers.md).
+
 `FakeProvider` is the deterministic test adapter. Do not describe Retro
 Diffusion as production-ready until representative multi-candidate, tileset,
 GIF, and spritesheet live smoke tests pass.

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

@@ -0,0 +1,43 @@
+# Mixed-provider projects
+
+Read this reference when one game or repository needs assets from both PixelLab
+and Retro Diffusion.
+
+One manifest selects one top-level `provider`. Do not add undocumented
+per-style provider fields: the current CLI constructs one account adapter for a
+manifest run, and a single `--budget` has one provider-specific unit.
+
+Use one manifest and lockfile per provider inside the same project:
+
+```text
+art/
+  pixelkiln.pixellab.manifest.json
+  pixelkiln.pixellab.lock.json
+  pixelkiln.retrodiffusion.manifest.json
+  pixelkiln.retrodiffusion.lock.json
+pixelkiln.workspace.json
+```
+
+Keep their output directories distinct. Plan and authorize them separately:
+
+```bash
+pixelkiln plan --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json
+pixelkiln gen --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json --budget <generations>
+
+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>
+```
+
+Register both manifests 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.
+
+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.

package/skills/pixelkiln/references/pixellab.md

@@ -0,0 +1,37 @@
+# PixelLab
+
+Read this reference when a manifest selects `pixellab`, when choosing between
+providers, or before any PixelLab account operation.
+
+## Operational boundary
+
+- Credential: `PIXELLAB_API_KEY` in `.env.local` beside the manifest or in the
+  process environment. Never print or commit it.
+- Status: production adapter. Generation and account workflows have live
+  coverage.
+- Cost unit: subscription generations. Copy the exact `pixelkiln plan` total
+  into `--budget`; do not translate it into dollars.
+- Account operations: balance, adopt, salvage, tag, and separately confirmed
+  purge are supported. Read `docs/RECOVERY.md` before using them.
+
+## Generator choice
+
+| Generator | Use it for | Measured cost |
+|---|---|---:|
+| `map` | One prop, icon, building, or landmark, up to 400×400 | 1 generation |
+| `pixflux` | Closed palettes or full-bleed backgrounds | 1 generation |
+| `1dir` | Reference-guided work or several candidates | 20–40 generations |
+| `tiles` | Ground variations or connected structures | 20–40 generations |
+
+In the committed environment benchmark, PixelLab followed complex building
+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
+repository, `docs/PIXELLAB.md` and `docs/ENDPOINTS.md` are the canonical local
+sources. The provider sources are <https://www.pixellab.ai/> and
+<https://api.pixellab.ai/v2/docs>.

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

@@ -0,0 +1,47 @@
+# Retro Diffusion
+
+Read this reference when a manifest selects `retrodiffusion`, when evaluating
+large scene work, or when using native animation and tileset output.
+
+## Operational boundary
+
+- Credential: `RD_API_KEY` in `.env.local` beside the manifest or in the
+  process environment. Never print or commit it.
+- Status: experimental adapter. RD Fast and RD Plus single-candidate stills are
+  live-tested through quote, submit, download, provenance, and recovery.
+  Multi-candidate, tileset, GIF, and spritesheet paths remain mock-tested.
+- Cost unit: USD. PixelKiln enforces the offline plan, then checks Retro
+  Diffusion's free authoritative quote before submission.
+- Account operations: balance is supported. Listing, adopt, salvage, tagging,
+  and deletion are not exposed by the current adapter.
+
+## Where it earns a place
+
+- `rd_plus__environment` for one-point-perspective scenic backgrounds.
+- `rd_plus__topdown_map` for 3/4 top-down maps.
+- `rd_tile__scene_object` for 64–384px objects placed on tile maps.
+- `rd_plus__topdown_asset` or `rd_plus__isometric_asset` for isolated assets.
+- `rd_animation__*` and `rd_advanced_animation__*` for GIF or PNG spritesheet
+  output.
+
+The useful environment styles currently top out at 384×384. PixelLab's `map`
+route reaches 400×400, so Retro Diffusion is not the higher-resolution option
+through PixelKiln today. Choose it for its scene styles, cleaner transparent
+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
+working in the PixelKiln repository, the same canonical sources are
+`docs/RETRO_DIFFUSION.md` and `docs/PROVIDER_BENCHMARK.md`. The provider sources
+are <https://www.retrodiffusion.ai/> and
+<https://www.retrodiffusion.ai/app/guide/api>.