pixelkiln 0.12.1 → 0.14.0

package/PROVIDERS.md

@@ -1,17 +1,18 @@
 # Provider comparison
 
-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.
+PixelKiln can route one manifest through PixelLab, Retro Diffusion, Scenario,
+and a self-hosted ComfyUI server. Planning, 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.
+compatible. The manifest's top-level `provider` is the default; a style may
+override it. Keep service settings under the matching `providerOptions` key.
 
 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
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md),
+[Set up ComfyUI](./docs/COMFYUI.md), or
+[Set up Scenario](./docs/SCENARIO.md). This page focuses on choosing between
 them.
 
 ## Support status
@@ -21,6 +22,7 @@ them.
 | 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 |
 | ComfyUI | Experimental; local single-image generation, four-candidate queue, provenance, and cache-only recovery live-tested on Apple MPS | none; optional `COMFYUI_BASE_URL` | free |
+| Scenario | Experimental; BFL Flux 2 Dev authentication, CU preflight, paid single/two-output generation, review, download, and durable recovery live-tested | `SCENARIO_SDK_API_KEY` and `SCENARIO_SDK_API_SECRET` | compute-units |
 | FakeProvider | Test-only deterministic lifecycle | none | free |
 
 Live tests now cover single-candidate RD Fast and RD Plus stills from cost quote
@@ -35,6 +37,13 @@ ComfyUI's `free` unit means PixelKiln cannot identify a metered provider
 charge. It does not count hardware, hosting, electricity, or model-license
 costs.
 
+Scenario planning uses the manifest's conservative `maxComputeUnits` value.
+Immediately before paid work, the adapter asks Scenario for a free live quote
+using the identical request. The first live smoke quoted and billed 16 CU for
+one image and 32 CU for two. Human selection and a forced provider restore both
+passed. The smoke is separate from the visual comparison because it uses a
+different brief.
+
 ## PixelLab vs. Retro Diffusion
 
 This comparison describes the adapters PixelKiln ships today, not every feature
@@ -81,17 +90,38 @@ 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.
 
+## Where Scenario fits
+
+Scenario adds hosted third-party models and reusable project-specific models
+without requiring a local GPU. PixelKiln's first adapter intentionally covers
+only the part that fits its existing still-image pipeline.
+
+| Decision | Scenario through PixelKiln |
+|---|---|
+| Best fit today | A controlled one-asset spike using a hosted model or project LoRA with a hard CU ceiling |
+| PixelKiln generator | `map` stills |
+| Output | One to four PNG candidates, 128–2048px in multiples of 16 |
+| Cost model | Manifest `maxComputeUnits`, command budget, then free authoritative preflight before each paid request |
+| Recovery | Durable job and asset IDs refresh temporary signed original-file URLs |
+| Account lifecycle | Read-only connectivity check; no balance, list, adopt, salvage, tag, or purge yet |
+| Confidence | BFL Flux 2 Dev live-tested through quote, billing, single/two-output jobs, human selection, PNG download, and provider-backed restore; other model schemas remain unverified |
+
+Scenario model schemas differ. The current adapter sends prompt, width, height,
+output count, optional seed, and explicitly declared JSON parameters. Verify
+the chosen model accepts that shape before spending. Use
+[Set up Scenario](./docs/SCENARIO.md) for the safe first-run sequence.
+
 ## 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 | Retro Diffusion | ComfyUI |
-|---|---|---|---|
-| 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 intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. |
-| 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. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. |
-| 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. |
+| Asset type | PixelLab | Retro Diffusion | ComfyUI | Scenario |
+|---|---|---|---|---|
+| 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 intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | The live BFL smoke produced a readable 512px keep, but it was opaque and used 19,619 colors. Use that profile for concepts or refinement input, not a finished limited-palette asset. A project-specific model may improve consistency but needs its own smoke. |
+| 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. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
+| 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. | Scenario's project models and LoRAs are the main reason to use it for a set. PixelKiln can pin the model ID and parameters, but its first live run covers only the public BFL profile. |
+| 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. | Scenario can request a larger raster from a compatible model, but the same rule applies: generate reusable layers at their useful native detail, compose at 1×, and integer-upscale only the final scene. |
 
 For a production environment, build a kit: seamless terrain, separate
 landmarks and buildings, foreground occluders, and a distant backdrop. You can
@@ -115,58 +145,37 @@ repeatable.
 
 ## Use multiple 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 multiple 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.comfyui.manifest.json
-  pixelkiln.comfyui.lock.json
-pixelkiln.workspace.json
-```
-
-Plan and authorize each manifest separately:
+Set a provider on any style that differs from the manifest default. Planning
+and confirmations remain grouped by provider and unit, so PixelLab generations,
+Retro Diffusion dollars, Scenario Compute Units, and local free work are never
+added together. A mixed run takes a separate named ceiling for each paid
+provider; the free group may be explicit:
 
 ```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
+pixelkiln gen \
+  --budget pixellab=12 \
+  --budget scenario=60 \
+  --budget comfyui=0
+```
 
-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>
+The same lockfile records which provider accepted each item. Resumed polling,
+review, download, restore, and tagging follow that recorded provider. Account
+operations such as `balance`, `adopt`, `salvage`, and `purge` require an
+explicit `--provider` in a mixed manifest.
 
-pixelkiln plan --manifest art/pixelkiln.comfyui.manifest.json --lock art/pixelkiln.comfyui.lock.json
-pixelkiln gen --manifest art/pixelkiln.comfyui.manifest.json --lock art/pixelkiln.comfyui.lock.json --budget 0
-```
+This works well 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 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.
 
-Register the 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 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
-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.
+See [Mixed-provider projects](./docs/MIXED_PROVIDERS.md) for the manifest,
+budget, recovery, and account-command contract. Separate manifests remain a
+good boundary when different teams, credentials, or release schedules should
+not share one runtime.
 
 ## Cost comparison
 
@@ -191,6 +200,12 @@ style, and candidate count affect the exact still-image quote. Treat
 as the authoritative submit-time check. See Retro Diffusion's
 [official API examples and pricing formulas](https://github.com/Retro-Diffusion/api-examples#pricing).
 
+Scenario uses Compute Units rather than USD in the API contract. Costs vary by
+model and inputs, so the manifest records a conservative per-asset ceiling
+instead of a stale formula. PixelKiln records Scenario's live dry-run quote and
+final job billing separately. The first BFL Flux 2 Dev smoke measured 16 CU for
+one 512px output and 32 CU for two with 28 inference steps.
+
 ## Capability boundary
 
 The provider boundary owns behavior that differs between services:
@@ -201,8 +216,8 @@ The provider boundary owns behavior that differs between services:
 - 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
+Planning groups costs by provider and unit instead of adding incompatible
+values. Mixed runs use provider-keyed ceilings. Providers without a balance or
 account-management endpoint can still generate safely because the offline
 estimate and hard budget remain enforced.
 
@@ -214,43 +229,38 @@ 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
-animation style to Retro Diffusion, and a private model workflow to ComfyUI.
-That requires provider-keyed budgets and confirmations, independently
-rate-limited adapters, and an explicit provider for account-wide commands. The
-lockfile already records the provider on each entry.
+Per-style provider routing now lets one manifest send a building style to
+PixelLab, an animation style to Retro Diffusion, and a private model workflow
+to ComfyUI. Provider-keyed budgets, independent orchestration, lock-authoritative
+recovery, and explicit account-provider selection ship with it.
 
-Scenario remains the best next hosted provider candidate. The implementation
-scope and acceptance criteria are tracked in
-[GitHub issue #52](https://github.com/gfargo/pixelkiln/issues/52).
+The Scenario still-image adapter from
+[GitHub issue #52](https://github.com/gfargo/pixelkiln/issues/52) now has mocked
+edge coverage and a paid BFL Flux 2 Dev lifecycle smoke. It remains
+experimental until more model schemas and representative art briefs pass.
 
 | 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 |
+| Scenario comparable benchmark | Custom-trained style models and hosted third-party generation | Tests the same environment briefs now that CU accounting, review, PNG output, and signed-URL recovery are proven | Model schemas differ, and the first live smoke is not directly comparable to the existing provider set | 1 |
 | ComfyUI Cloud | Managed execution of workflow graphs without running a local GPU | Could reuse part of the workflow model, but authentication, endpoints, billing, and lifecycle must remain separate from the local adapter | Treating cloud as a base-URL swap would hide real security and cost differences | 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 is the next hosted 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
+Scenario's [custom generation API](https://docs.scenario.com/get-started/generation/third-party-model-generation)
+returns asynchronous jobs, while 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.
+documents free cost preflights. PixelKiln now maps those mechanics into its
+normal plan, submit, poll, review, fetch, and restore lifecycle.
 
 Recommended order from here:
 
-1. Benchmark pinned ComfyUI models and prompt patterns across at least two scene
-   families. Reject any supposed improvement that helps only one subject.
-2. Add per-style provider selection, provider-keyed budgets, and mixed-provider
-   integration tests.
-3. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
+1. Finish live Retro Diffusion multi-candidate, tileset, GIF, and spritesheet
    smoke tests.
-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.
-5. Design ComfyUI Cloud as a separate authenticated and billable adapter.
-6. Consider general raster marketplaces only with explicit nearest-neighbor,
+2. Run the shared environment briefs through Scenario, then add one custom-model
+   or project-LoRA benchmark.
+3. Benchmark another pinned ComfyUI model and prompt pattern across at least two
+   scene families. Reject any improvement that helps only one subject.
+4. Design ComfyUI Cloud as a separate authenticated and billable adapter.
+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

@@ -2,9 +2,7 @@
 
 ![PixelKiln](https://wp.griffen.codes/wp-content/uploads/2026/08/download.png)
 
-[Website](https://pixelkiln.griffen.codes) ·
-[Documentation](https://pixelkiln.griffen.codes/docs) ·
-[GitHub](https://github.com/gfargo/pixelkiln)
+[Website](https://pixelkiln.griffen.codes) · [Documentation](https://pixelkiln.griffen.codes/docs) · [GitHub](https://github.com/gfargo/pixelkiln)
 
 Generate pixel art from a manifest, review it locally, recover paid work, and
 package the accepted files for a game engine.
@@ -15,15 +13,17 @@ 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.
+PixelLab is the production backend. Retro Diffusion, self-hosted ComfyUI, and
+Scenario 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. Scenario has live-tested authentication,
+CU preflight, single- and two-output generation, human review, and durable
+restore with BFL Flux 2 Dev. It remains experimental. Styles may use different providers with separate
+budget ceilings. The [provider comparison](./PROVIDERS.md) lists the tested limits
+and best routes. `FakeProvider` covers the same contract in automated tests.
 
 ## Release
 
@@ -54,7 +54,7 @@ PixelKiln keeps the missing record:
 
 | Workflow | What PixelKiln provides |
 |---|---|
-| Plan and budget | Offline manifest/lock/disk diff, provider-unit estimates, hard `--budget` ceiling, JSON/CI gate. |
+| Plan and budget | Offline manifest/lock/disk diff, provider-grouped estimates, keyed mixed-provider budget ceilings, 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, durable provider-reference restore, account object-hash cache, and resumable jobs. |
@@ -105,10 +105,11 @@ Put a hosted provider's 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=...
-
+# Scenario needs both values when `provider` is `scenario`
+SCENARIO_SDK_API_KEY=...
+SCENARIO_SDK_API_SECRET=...
 # Self-hosted ComfyUI needs no key; override its local URL only when needed
 COMFYUI_BASE_URL=http://127.0.0.1:8188
 ```
@@ -136,9 +137,11 @@ pixelkiln plan
 
 See [Getting started](./docs/GETTING_STARTED.md) for new and existing projects.
 Use [Set up PixelLab](./docs/PIXELLAB.md),
-[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), or
-[Set up ComfyUI](./docs/COMFYUI.md) for provider-specific configuration,
-manifest examples, and current limits.
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md),
+[Set up ComfyUI](./docs/COMFYUI.md), or
+[Set up Scenario](./docs/SCENARIO.md) for provider-specific configuration,
+manifest examples, and current limits. See [Mixed-provider projects](./docs/MIXED_PROVIDERS.md)
+when styles in one manifest need different backends.
 
 ## Agent skill
 
@@ -184,8 +187,9 @@ set. Generator choice, reference-image bytes, dimensions, palette, seed, and
 prompt settings participate in deterministic spec identity. A manifest may
 select another provider and pass namespaced `providerOptions`; see
 [Set up PixelLab](./docs/PIXELLAB.md),
-[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md), and
-[Set up ComfyUI](./docs/COMFYUI.md). The
+[Set up Retro Diffusion](./docs/RETRO_DIFFUSION.md),
+[Set up ComfyUI](./docs/COMFYUI.md), and
+[Set up Scenario](./docs/SCENARIO.md). The
 [provider comparison](./PROVIDERS.md) covers costs,
 current confidence, and limitations. The committed ComfyUI projects now include
 transparent cutouts, palette-controlled backgrounds, wide environment canvases,
@@ -253,18 +257,17 @@ replace a hard palette or reference-image constraint. See
 Generator names describe PixelKiln workflows; their exact capabilities and
 prices depend on the selected provider. Retro Diffusion also supports the
 provider-specific `animation` generator. ComfyUI currently supports `map`
-through an operator-supplied workflow. Compare the adapters in the
-[provider comparison](./PROVIDERS.md).
+through an operator-supplied workflow. Scenario currently supports `map`
+with a required offline CU ceiling and a live quote before each paid call.
+Compare the adapters in the [provider comparison](./PROVIDERS.md).
 
 ## Derived artifacts
 
 ```bash
 # Deterministic sheet + atlas + provenance.
 pixelkiln pack --style base
-
 # Stable declared cells in an existing sheet.
 pixelkiln mount --style ground
-
 # Structural atlas + engine metadata + provenance.
 pixelkiln export --style ground --only terrain --format tiled
 ```
@@ -335,16 +338,12 @@ import {
   buildPlan,
   loadLock,
   loadManifest,
-  PixelLabProvider,
   resolveSpecs,
 } from "pixelkiln"
-
 const loaded = await loadManifest("pixelkiln.manifest.json")
-const provider = PixelLabProvider.forOffline()
-const specs = await resolveSpecs(loaded, { provider })
+const specs = await resolveSpecs(loaded)
 const plan = await buildPlan(specs, await loadLock("pixelkiln.lock.json"))
-
-console.log(plan.cost, plan.costUnit, plan.actionable.length)
+console.log(plan.groups, plan.actionable.length)
 ```
 
 The package also exports audit and image-regression gates, provider-neutral refinement, lock/output
@@ -361,9 +360,11 @@ 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. |
+| [Set up Scenario](./docs/SCENARIO.md) | Experimental hosted models, two-part credentials, CU preflight, review, and durable downloads. |
 | [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. |
+| [Mixed-provider projects](./docs/MIXED_PROVIDERS.md) | Per-style routing, provider-keyed budgets, recovery, and account commands. |
 | [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 native-grid and final-palette results comparing large scenes, transparency, palette size, and file readiness. |

package/SECURITY.md

@@ -34,7 +34,8 @@ credentials in their query string. Reports involving authentication leakage, pat
 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
+Never attach a real `PIXELLAB_API_KEY`, `RD_API_KEY`, `SCENARIO_SDK_API_KEY`,
+`SCENARIO_SDK_API_SECRET`, `.env` file, private
 provider URL, or unredacted lockfile from a confidential project to a public
 report.
 

package/dist/cli.d.ts

@@ -12,6 +12,8 @@ interface Args {
     force: boolean;
     yes: boolean;
     budget?: number;
+    /** Repeatable provider-keyed budgets used by a mixed-provider run. */
+    providerBudgets: Record<string, number>;
     dryRun: boolean;
     all: boolean;
     json: boolean;
@@ -50,7 +52,7 @@ interface Args {
     workspace?: string;
     /** Positional target for recipe and workspace subcommands. */
     target?: string;
-    /** `workspace add`: provider id to register the project under. Defaults to "pixellab". */
+    /** Account provider selector; also the `workspace add` catalog provider hint. */
     provider?: string;
     /** `workspace add`: free-form account label, e.g. distinguishing sandboxes. */
     account?: string;