pixelkiln 0.2.0 → 0.4.0

package/CONTRIBUTING.md

@@ -46,13 +46,22 @@ npm run pixelkiln -- plan --manifest examples/minimal/pixelkiln.manifest.json
 ```
 
 Tests must not require a live provider account or API key. Use `FakeProvider`
-for pipeline behavior and mocked HTTP responses for PixelLab wire contracts.
+for pipeline behavior and mocked HTTP responses for PixelLab or Retro Diffusion
+wire contracts.
 
 ## Change guidelines
 
 - Start from `main` and keep one coherent change per pull request.
 - Use conventional commit subjects (`feat:`, `fix:`, `docs:`, `refactor:`,
   `test:`, `chore:`). Semantic Release derives versions from them.
+- **Scope website-only work as `chore(website):`.** `website/` is not in the
+  package `files` allowlist, so nothing under it can reach the published
+  tarball. Semantic Release cannot see that, and a `feat(website):`
+  subject cuts a minor release whose contents are byte-identical to the one
+  before it. That happened once already: 0.2.0 is a favicon and an Open Graph
+  image. Any `website` scope is also refused a release by `releaseRules` in
+  `.releaserc.json`, so a slip is caught rather than published, but the right
+  subject keeps the changelog honest.
 - Add regression coverage for bug fixes and behavior coverage for new public
   options or exports.
 - Update README/help text and focused docs in the same change as user-facing
@@ -90,3 +99,43 @@ full check results in the PR description.
 
 Security-sensitive findings should follow [SECURITY.md](./SECURITY.md), not a
 public issue with exploit details.
+
+## Releases
+
+Merging to `main` is the release. Semantic Release derives the version from the
+conventional commit subjects in the range, publishes to npm, tags the commit,
+writes the GitHub release, prepends to `CHANGELOG.md`, and commits the changelog
+and version back to `main` with `[skip ci]`. Contributors do not run anything.
+
+**There is no npm token.** Publishing authenticates over OIDC trusted
+publishing: the workflow grants `id-token: write`, npm exchanges that for a
+short-lived credential, and the npm CLI performs the exchange itself during
+`npm publish`. A side effect worth keeping is that every release carries a
+signed provenance attestation linking the tarball to its source commit and
+workflow run.
+
+Two conditions have to hold on the npm side, and neither lives in this
+repository:
+
+- the package must exist on the registry, and
+- it must have a Trusted Publisher entry naming this repository and the
+  `release.yml` workflow.
+
+When one is missing, the token exchange reports `404 OIDC token exchange error
+- package not found`, and Semantic Release then falls through to token auth and
+fails with `EINVALIDNPMTOKEN`. **That 404 does not necessarily mean the package
+is absent.** It reads identically when the package is published but has no
+Trusted Publisher entry, which is the more likely cause once a release has ever
+succeeded. Check the entry before doubting the publish.
+
+Because the exchange cannot authenticate against a package that does not exist
+yet, `0.1.0` was published by hand to bootstrap that trust, and its changelog
+section was written by hand for the same reason. Every release from `0.2.0`
+onward is automated.
+
+A failed release opens an issue labelled `semantic-release`, which the next
+successful run closes. That label must exist in the repository or the reporting
+step itself fails with a validation error and hides the original failure.
+
+See the website scoping rule under [change guidelines](#change-guidelines) for
+the one commit convention that changes whether a release happens at all.

package/NAMING.md

@@ -1,4 +1,4 @@
-# Naming — resolved: `pixelkiln`
+# Naming resolved: `pixelkiln`
 
 **The name is settled.** The project ships as `pixelkiln`. `package.json` is
 no longer `private`.
@@ -20,19 +20,19 @@ GET https://registry.npmjs.org/pixelsmith   → 200, latest 2.6.0, "Node based
 ```
 
 `pixelkiln` was never published. The "v3.5.1 CSS spritesheet builder" is
-**`spritesmith`**, a real and long-established package — `pixelsmith` really
+**`spritesmith`**, a real and long-established package. `pixelsmith` really
 is its engine, exactly as claimed, but neither of them is `pixelkiln`. The
 original research conflated the two real packages into a collision that
 didn't exist. (`pixelsmith` also appears, separately and correctly, in the
-rejected-candidates list below — a real name in a different, adjacent
-project — which should have been the tell.)
+rejected-candidates list below. It is a real name in a different, adjacent
+project, which should have been the tell.)
 
 A GitHub search for `pixelkiln` returns nothing but this repository, and a
 general web search turns up no product, tool, or project by that name
 anywhere. Nothing else needs to change: `bin/pixelkiln.js`, `package.json`'s
 `name`/`bin`, the README, `scripts/gen-schema.ts`'s schema title, and
-heybud-admin's `package.json` badge scripts already all say `pixelkiln` —
-there is no rename to do, only the `private: true` flag to drop, which is
+heybud-admin's `package.json` badge scripts already all say `pixelkiln`.
+There is no rename to do, only the `private: true` flag to drop, which is
 done.
 
 ## What the space already looks like
@@ -44,13 +44,13 @@ The "manifest-driven AI asset generation CLI" idea is not novel. Prior art found
 | [pickbitsai/sprite-generator](https://github.com/pickbitsai/sprite-generator) | Closest. JSON manifest, `assets[]` with id/category/description, `defaultStyle`, `--dry-run`, `--category`, `--concurrency` | OpenAI `gpt-image-1` |
 | [mcp-tool-shop-org/sprite-foundry](https://github.com/mcp-tool-shop-org/sprite-foundry) | SQLite lifecycle tracking, review/accept/reject, provenance, deterministic export with manifest + checksums | ComfyUI (local GPU) |
 | [lx-0/restyle-sprites](https://github.com/lx-0/restyle-sprites) | Restyle a whole pack from source + style reference | Gemini / OpenAI |
-| [trebeljahr/sprite-tools](https://github.com/trebeljahr/sprite-tools) | Post-processing toolkit — atlas, collision, palette | n/a |
+| [trebeljahr/sprite-tools](https://github.com/trebeljahr/sprite-tools) | Post-processing toolkit for atlas, collision, and palette | n/a |
 | [dt-pirate/openrender](https://github.com/dt-pirate/openrender) | Installs generated assets into engines, manifests, rollback | n/a |
 | [freema/pixelforge-mcp](https://github.com/freema/pixelforge-mcp) | MCP server for pixel art | Gemini |
 | [ralphy](https://ralphy.mintlify.app/advanced/asset-manifest) | `asset-manifest.json` slot pointers + `generations.jsonl` audit log | multi |
 
-**Implication for naming:** the `sprite-*` namespace is crowded — `sprite-generator`,
-`sprite-foundry`, `sprite-tools`, `restyle-sprites` all exist. Avoid it.
+**Implication for naming:** the `sprite-*` namespace is crowded. `sprite-generator`,
+`sprite-foundry`, `sprite-tools`, and `restyle-sprites` all exist. Avoid it.
 
 ## What is actually differentiated here
 
@@ -67,7 +67,7 @@ Worth knowing, because the name should point at it:
    table plus a log. A committed, sorted, hash-on-both-sides lockfile in the npm
    sense was not found.
 
-## Shortlist (historical — kept for context, decision is above)
+## Shortlist (historical, kept for context)
 
 All verified free on npm, zero GitHub repos by that name, no web presence
 (checked 2026-07-29 for the alternates; `pixelkiln` itself re-verified
@@ -75,13 +75,13 @@ All verified free on npm, zero GitHub repos by that name, no web presence
 
 | Candidate | Note |
 |---|---|
-| **pixelkiln** ✅ **chosen** | Firing/baking metaphor fits pixel art, avoids the crowded `sprite-*` space. The npm collision this was shelved for turned out not to exist — see Resolution. |
-| pixelquarry | Extraction metaphor — you quarry many candidates and keep the good ones. Still free, not needed. |
+| **pixelkiln** ✅ **chosen** | Firing/baking metaphor fits pixel art, avoids the crowded `sprite-*` space. The npm collision this was shelved for turned out not to exist. See Resolution. |
+| pixelquarry | Extraction metaphor, since you quarry many candidates and keep the good ones. Still free, not needed. |
 | pixelcrate | Packaging/inventory feel; leans toward the lockfile idea. Still free, not needed. |
 | dithermill | Most pixel-art-native word available; "mill" carries batch production. Still free, not needed. |
 | spriteledger | Points hardest at provenance, but inherits the crowded `sprite-` prefix. Still free, not needed. |
 
-Rejected after checking: `pixelwright` (three live businesses use it — an AI app
-builder, an iOS audit firm, a UI developer's brand), `spritefoundry` (taken by a
-real project), `pixelsmith` (real package, `spritesmith`'s engine — see
+Rejected after checking: `pixelwright` (three live businesses use it: an AI app
+builder, an iOS audit firm, and a UI developer's brand), `spritefoundry` (taken by a
+real project), `pixelsmith` (real package, `spritesmith`'s engine, see
 Resolution), `spritemill`, `pixelloom`, `bitforge`, `spritelab`.

package/PROVIDERS.md

@@ -1,96 +1,134 @@
-# Multi-provider — status and notes
+# PixelLab and Retro Diffusion
 
-**The seam is built.** `src/provider.ts` defines the interface;
-`src/providers/pixellab.ts` is the reference implementation and
-`src/providers/fake.ts` is the in-memory test double. Nothing above the
-interface knows about PixelLab.
+PixelKiln can route one manifest through either PixelLab or Retro Diffusion.
+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.
 
-That is an architectural guarantee, not a compatibility claim: PixelLab is the
-only production adapter and the only backend exercised against a live account
-today. `FakeProvider` verifies the contract without network access. Until a
-second production adapter ships, describe PixelKiln as **provider-neutral by
-design and proven with PixelLab**, not as already multi-provider.
+PixelLab remains the default so existing manifests and spec hashes remain
+compatible. Select Retro Diffusion with the manifest's top-level `provider`
+field and keep its settings under `providerOptions.retrodiffusion`.
 
-Both concerns this file previously flagged as blockers are resolved:
+Ready to configure a project? Use [Set up PixelLab](./docs/PIXELLAB.md) for the
+production provider or
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md) for the experimental
+adapter. This page focuses on choosing between them.
 
-- **Cost is no longer assumed to be "generations."** `CostEstimate` carries a
-  `unit` of `generations | usd | free`, `plan` prints it, and `--budget` is
-  interpreted in it. `resolveSpecs(..., { provider })` asks the adapter for its
-  offline estimate, submission validates it again, and lock/status accounting
-  keeps fractional values separated by unit.
-- **Free multi-candidate returns are no longer assumed universal.**
-  `estimate().candidates` is a provider property; `candidateCount()` moved
-  behind the interface.
+## Support status
 
-What remains is writing a second adapter. This file records which one and why.
-
-## Midjourney is the wrong first target
-
-Verified 2026-07-29: **Midjourney has no public developer API.** API keys are
-restricted to the Enterprise dashboard and require applying for access. Every
-third-party "Midjourney API" works by automating the Discord or web interface,
-which violates Midjourney's terms of service and risks the underlying account
-being banned.
-
-Building that adapter would mean shipping something fragile, unsupported, and
-capable of getting a user's account terminated. Not worth it.
-
-## The right first target: Retro Diffusion
-
-[Retro Diffusion](https://retrodiffusion.ai/) is PixelLab's closest competitor
-and the natural second provider:
-
-- A real, documented developer API, with
-  [published examples](https://github.com/Retro-Diffusion/api-examples).
-- Purpose-built for pixel art — grid-aligned output, no blur or anti-aliasing —
-  so it shares this tool's domain model rather than needing a downscale and
-  quantize pass bolted on.
-- Supports seamless tiles, sprite-sheet animation, and free cost estimates,
-  which map onto `plan` almost directly.
-
-Other candidates, in rough order of fit:
-
-| Provider | API | Pixel-native | Notes |
+| Provider | PixelKiln status | Credential | Cost unit |
 |---|---|---|---|
-| Retro Diffusion | yes | yes | Recommended first adapter |
-| [Scenario](https://www.scenario.com/) | yes | partly | Game-asset focused, hosts Retro Diffusion models |
-| OpenAI `gpt-image-1` | yes | no | Raster; needs downscale + palette quantization |
-| Google Gemini image | yes | no | Same caveat |
-| Local ComfyUI + pixel LoRA | n/a | yes | No per-call cost, but a GPU dependency |
-| Midjourney | **no** | no | See above |
-
-## Resolved: the two economic assumptions
-
-Both were global assumptions baked into `plan`; both are now provider-owned.
-Kept here as the rationale, since a second adapter has to honour them.
-
-1. **Cost is not universally "generations".** `Plan.cost` used to be a bare
-   number meaning PixelLab subscription generations. It now carries a unit —
-   USD for OpenAI, generations for PixelLab, free for local — so `plan` prints
-   an honest figure and `--budget` means something in every backend.
-
-2. **Free candidates were a PixelLab quirk.** The core loop — generate small,
-   get 16 candidates for one fixed price, pick the best — works because
-   PixelLab charges per *call* and scales candidates inversely with canvas
-   size. OpenAI charges per *image*, so 16 candidates costs 16×. The picker
-   still works either way, but the strategy advice in the README does not
-   generalise, which is why `candidateCount()` moved behind the interface.
-
-See `src/provider.ts` for the shipped interface. Lock entries carry a
-`provider` field plus `costUnit`, defaulted to `pixellab` and `generations` so
-pre-provider/pre-unit v2 lockfiles stay readable. The CLI reports both the
-successful-submission estimate and the provider balance delta observed across
-the run; those are deliberately separate because provider balances may settle
-asynchronously.
-
-## Done: the integration tests it unblocked
-
-`FakeProvider` turned out to be exactly the better test double predicted here.
-17 integration tests now cover `submit → poll → fetch`, `pushTags` and `adopt`
-— the stages that spend money and previously had zero coverage, where four of
-the five real bugs in this project lived. Verified non-vacuous by mutation:
-breaking the output hashes, the budget check, or the v1 lock rejection each
-fails tests.
-
-The contact-sheet request paths are covered through the picker and salvage
-integration tests as well as their HTML unit tests.
+| PixelLab | Production; paid generation and account workflows live-tested | `PIXELLAB_API_KEY` | generations |
+| Retro Diffusion | Experimental; authenticated paid still generation, download, provenance, and recovery live-tested; advanced workflows pending | `RD_API_KEY` | USD |
+| FakeProvider | Test-only deterministic lifecycle | none | free |
+
+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.
+Retro Diffusion's multi-candidate review, tileset, GIF, and spritesheet paths
+have mocked integration coverage but still need representative paid live runs.
+
+## PixelLab vs. Retro Diffusion
+
+This comparison describes the adapters PixelKiln ships today, not every feature
+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 |
+| 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 |
+| References | `1dir` and tile style modes | Up to nine for supported RD Pro/user still styles; constrained inputs for animation and tiles |
+| Cost model | Subscription generations | Prepaid USD balance |
+| Cost safety | Offline estimate plus hard generation budget | Offline estimate, hard USD budget, then a free authoritative quote before submission |
+| Account lifecycle | Balance, list, adopt, salvage, tag, and confirmed purge | Balance only in the current adapter |
+| Live confidence | Full paid generation workflows exercised | RD Fast and RD Plus single-candidate stills exercised end to end; multi-candidate, tileset, GIF, and spritesheet runs pending |
+
+Choose PixelLab when mature account-object recovery and reconciliation matter,
+or when the measured one-generation `map`/`pixflux` routes fit the work. Choose
+Retro Diffusion when a native animation or spritesheet is required, an RD style
+is the desired look, or a USD quote is easier to budget. For a production batch,
+run one representative asset through the selected provider before expanding the
+scope.
+
+## Large environments, mountains, and buildings
+
+Start by deciding whether the result is an isolated map object or a complete
+background. That distinction matters more than raw canvas size.
+
+| Asset type | PixelLab through PixelKiln | Retro Diffusion through PixelKiln |
+|---|---|---|
+| Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is specifically intended for 64–384px objects placed on tile maps. |
+| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene. Current PixelKiln routes top out at 400×400. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. |
+| 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. |
+| 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. |
+
+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.
+
+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
+size and review count. Score silhouette readability, perspective, palette,
+edge cleanliness, tiling/layerability, prompt adherence, and usable results per
+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.
+
+## Cost comparison
+
+The services use different billing units, so PixelKiln never adds their costs
+together.
+
+PixelLab figures below are measurements from the endpoints PixelKiln currently
+uses; they are not a conversion to dollars:
+
+| PixelLab route | Measured cost |
+|---|---:|
+| `map` | 1 generation |
+| `pixflux` | 1 generation |
+| `1dir` | 20–40 generations |
+| `tiles` | 20–40 generations |
+
+Retro Diffusion publishes USD formulas and fixed prices. Examples relevant to
+PixelKiln include RD Fast from about $0.015 per image, RD Plus from about $0.025,
+RD Pro at $0.18, animations from $0.07–$0.25, and tilesets at $0.10. Pixel count,
+style, and candidate count affect the exact still-image quote. Treat
+`pixelkiln plan` as the offline ceiling and the provider's free preflight quote
+as the authoritative submit-time check. See Retro Diffusion's
+[official API examples and pricing formulas](https://github.com/Retro-Diffusion/api-examples#pricing).
+
+## Capability boundary
+
+The provider boundary owns behavior that differs between services:
+
+- supported generators and provider-specific validation;
+- offline estimates, arbitrary non-empty cost units, and candidate counts;
+- submit/poll response schemas and candidate selection when applicable;
+- downloads and optional account capabilities such as balance, listing,
+  tagging, and deletion.
+
+Planning groups costs by unit instead of adding incompatible values. A budget
+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,
+   palette, transparency, and reproducibility checks.
+
+Midjourney is not an adapter target without an official public API. Automating
+its consumer UI would be fragile and could violate provider terms.

package/README.md

@@ -15,10 +15,15 @@ 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 by design. PixelLab is currently
-the only production adapter and the only live-tested generation backend;
-`FakeProvider` exercises the same contract deterministically in tests. A second
-production adapter is roadmap work, not current compatibility.
+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. See
+[PixelLab vs. Retro Diffusion](./PROVIDERS.md) for the trade-offs, including
+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
@@ -38,7 +43,7 @@ PixelKiln supplies the missing project model:
   output hashes;
 - planning distinguishes missing, stale, recoverable, in-flight, untracked, and
   manually changed files before money is spent;
-- local review keeps human judgment where it matters—choosing artwork;
+- local review keeps human judgment where it matters, choosing artwork;
 - content-addressed recovery prevents a transient URL failure from buying the
   same image twice;
 - derived artifact bundles retain source provenance and recover across ordinary
@@ -52,7 +57,7 @@ PixelKiln supplies the missing project model:
 | 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. |
-| Shared-account safety | Cross-project claim files, sibling-style exclusion, reviewed salvage, keep/discard tags, separate confirmed purge. |
+| 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. |
 | Engine export | Lossless generic tile contract, Tiled Wang sets, and Godot 4 terrain sets. |
@@ -99,7 +104,11 @@ cd ../my-game
 Put the provider credential in `.env.local` beside the manifest:
 
 ```dotenv
+# PixelLab (the default provider)
 PIXELLAB_API_KEY=...
+
+# Or Retro Diffusion when `provider` is `retrodiffusion`
+RD_API_KEY=...
 ```
 
 Validate locally, inspect exact work/cost, then generate with a hard ceiling:
@@ -127,6 +136,9 @@ pixelkiln plan
 ```
 
 See [Getting started](./docs/GETTING_STARTED.md) for new and existing projects.
+Use [Set up PixelLab](./docs/PIXELLAB.md) or
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md) for provider-specific
+credentials, manifest examples, and current limits.
 
 ## Agent skill
 
@@ -149,6 +161,7 @@ packaging layer.
 {
   "$schema": "./node_modules/pixelkiln/schema/manifest.schema.json",
   "name": "my-game",
+  "provider": "pixellab",
   "styles": {
     "base": {
       "generator": "map",
@@ -168,7 +181,12 @@ packaging layer.
 Styles are namespaces. Adding a second style re-derives the same asset ids into
 a separate output directory and separate lock keys without clobbering the first
 set. Generator choice, reference-image bytes, dimensions, palette, seed, and
-prompt settings participate in deterministic spec identity.
+prompt settings participate in deterministic spec identity. A manifest may
+select `retrodiffusion` instead and pass namespaced `providerOptions`; see
+[Set up PixelLab](./docs/PIXELLAB.md),
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), and
+[PixelLab vs. Retro Diffusion](./PROVIDERS.md) for configuration, costs,
+current confidence, and limitations.
 
 The schema rejects unknown fields and invalid generator combinations before
 planning. See the [Manifest reference](./docs/MANIFEST.md).
@@ -212,6 +230,11 @@ replace a hard palette or reference-image constraint. See
 [Generator selection](./docs/GENERATORS.md) and the
 [measured endpoint reference](./docs/ENDPOINTS.md).
 
+Generator names describe PixelKiln workflows; their exact capabilities and
+prices depend on the selected provider. Retro Diffusion also supports the
+provider-specific `animation` generator. Compare the adapters in
+[PixelLab vs. Retro Diffusion](./PROVIDERS.md).
+
 ## Derived artifacts
 
 ```bash
@@ -253,9 +276,21 @@ pixelkiln purge
 ```
 
 Salvage imports, keeps, or tags discard; it never deletes. On shared accounts,
-pass every other project lockfile via `--claims` so shipped art cannot appear
-unowned. Purge only targets objects already tagged discard and requires an
-explicit confirmation. See [Recovery and account safety](./docs/RECOVERY.md).
+pass every other project lockfile via `--claims`, or register siblings once in
+a workspace catalog and pass `--workspace`, so shipped art cannot appear
+unowned:
+
+```bash
+pixelkiln workspace add ../other-game/pixelkiln.manifest.json
+pixelkiln workspace status
+pixelkiln salvage --workspace pixelkiln.workspace.json
+```
+
+A registered project's missing or unreadable lockfile is a hard error for
+`workspace claims` and `salvage --workspace`. Missing claims are never skipped.
+Purge only targets objects already tagged discard and requires an explicit
+confirmation.
+See [Recovery and account safety](./docs/RECOVERY.md).
 
 ## Automation
 
@@ -301,10 +336,13 @@ writes, and offline provenance verification. See [Library API](./docs/LIBRARY.md
 |---|---|
 | [Documentation index](./docs/README.md) | All user, workflow, reference, and architecture guides. |
 | [Getting started](./docs/GETTING_STARTED.md) | First project, existing-art onboarding, everyday workflow, and what to commit. |
+| [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. |
 | [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 PixelLab MCP pairing. |
+| [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. |
 | [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. |
@@ -312,6 +350,7 @@ writes, and offline provenance verification. See [Library API](./docs/LIBRARY.md
 | [Library API](./docs/LIBRARY.md) | Public TypeScript contracts and examples. |
 | [Tiles](./docs/TILES.md) | Structural outputs and generic/Tiled/Godot formats. |
 | [Endpoint research](./docs/ENDPOINTS.md) | Measured PixelLab API behavior and recipes. |
+| [PixelLab vs. Retro Diffusion](./PROVIDERS.md) | Provider selection, costs, supported workflows, confidence, and limitations. |
 
 The [public documentation site](https://pixelkiln.griffen.codes/docs) is built by
 the application in [`website/`](./website/README.md). It reads these Markdown
@@ -319,14 +358,16 @@ files directly at build time, so the website and published package share one
 documentation source.
 
 Project policies: [Contributing](./CONTRIBUTING.md),
-[Security](./SECURITY.md), and [provider notes](./PROVIDERS.md).
+[Security](./SECURITY.md), and [provider comparison](./PROVIDERS.md).
 
 ## Scope
 
-Animated eight-direction characters and their ZIP/engine-resource export are not
-currently implemented. See the open
-[roadmap issues](https://github.com/gfargo/pixelkiln/issues) for provider and
-workspace-catalog work.
+Animated eight-direction characters and their ZIP/engine-resource export are
+not currently implemented. Cross-project content-cache reuse and
+`workspace find <hash|asset-id>` are deferred beyond the current read-only
+workspace catalog. See the open
+[roadmap issues](https://github.com/gfargo/pixelkiln/issues) for additional
+provider adapters and this remaining workspace work.
 
 ## License
 

package/SECURITY.md

@@ -28,11 +28,12 @@ reporter.
 
 ## Sensitive areas
 
-Pixelkiln handles provider credentials, paid API actions, remote object deletion,
+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,
 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`, `.env` file, private provider URL, or
-unredacted lockfile from a confidential project to a public report.
+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.

package/dist/cli.d.ts

@@ -34,8 +34,25 @@ interface Args {
     minTransparency?: number;
     maxColors?: number;
     sigma?: number;
+    /** `workspace`: add/remove/list/status/claims. */
+    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. */
+    target?: string;
+    /** `workspace add`: provider id to register the project under. Defaults to "pixellab". */
+    provider?: string;
+    /** `workspace add`: free-form account label, e.g. distinguishing sandboxes. */
+    account?: string;
+    /**
+     * Raw `--lock` value with no manifest-relative default applied. `workspace
+     * add` needs to know whether the user actually passed `--lock`, since the
+     * ambient default (beside `--manifest`, which usually names an unrelated
+     * project) is meaningless for the manifest being registered.
+     */
+    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", "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", "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,