pixelkiln 0.2.0 → 0.4.0

package/docs/AGENTS.md

@@ -28,14 +28,14 @@ With the skill loaded, an agent should:
 5. Pass an explicit `--budget` within the amount the user authorized.
 6. Leave artwork selection in the local `pick` page unless the user gives a
    specific selection rule.
-7. Commit the manifest, lockfile, generated output, and artifact companions—but
+7. Commit the manifest, lockfile, generated output, and artifact companions, but
    never credentials or `.pixelkiln/` caches.
 
 The skill guides the workflow; PixelKiln remains the deterministic execution
 layer. This separation keeps agent reasoning out of polling, hashing, downloads,
 state transitions, and output placement.
 
-## PixelLab MCP and PixelKiln
+## Providers, PixelLab MCP, and PixelKiln
 
 The [official PixelLab MCP server](https://github.com/pixellab-code/pixellab-mcp)
 gives an agent direct PixelLab creation tools. It is complementary to PixelKiln,
@@ -47,10 +47,17 @@ not a replacement:
 | PixelKiln skill | Agent guidance for safe project-level operations. |
 | PixelKiln library/CLI | Budgets, state, provenance, review, recovery, audit, and packaging. |
 | PixelLab adapter | The current production and live-tested generation backend. |
-
-PixelKiln's core is provider-neutral by design, but PixelLab is the only
-production adapter today. Do not claim compatibility with another backend until
-its adapter and live integration tests ship.
+| Retro Diffusion adapter | Experimental backend; authenticated paid single-still lifecycle plus mocked advanced-workflow tests. |
+
+PixelKiln's core is provider-neutral, but PixelLab remains the only production
+and paid-generation-tested adapter. Retro Diffusion generation support is
+experimental. Paid RD Fast and RD Plus single-candidate stills have passed from
+quote through validated download and recovery. Multi-candidate, tileset, GIF,
+and spritesheet workflows still need representative live smoke tests. See
+[PixelLab vs. Retro Diffusion](../PROVIDERS.md) before choosing a provider for a
+new project or a large environment asset. Once chosen, follow
+[Set up PixelLab](./PIXELLAB.md) or
+[Set up Retro Diffusion](./RETRO_DIFFUSION.md).
 
 ## Recommended first prompt
 

package/docs/ARCHITECTURE.md

@@ -5,7 +5,7 @@ PixelKiln separates provider mechanics from the project state machine:
 ```text
 manifest + lock + planning + review + recovery + artifact pipelines
 ──────────────────── Provider interface ─────────────────────────
-PixelLabProvider             FakeProvider             future adapters
+PixelLabProvider      RetroDiffusionProvider      FakeProvider      future adapters
 ```
 
 Everything above the provider boundary is backend-neutral. URL shapes, auth
@@ -31,7 +31,8 @@ retain:
 - provider and remote object/job ids;
 - explicit lifecycle status and errors;
 - source URLs/candidates/selections;
-- `outputs[]` with portable path, SHA-256, and optional structural role;
+- `outputs[]` with portable path, SHA-256, optional structural role, and
+  optional PNG/GIF media type;
 - provider-specific metadata under a provider-id namespace;
 - successful submission cost and cost unit.
 
@@ -41,8 +42,10 @@ are rebased in memory and rewritten portably on the next save. The current
 manifest remains destination authority; a stale lock path cannot redirect
 restore into an unrelated project file.
 
-Unlike cost units—`generations`, `usd`, and `free`—are never summed. Candidate
-count also belongs to the provider estimate rather than being assumed globally.
+Cost units that differ are never summed. Built-in adapters currently use
+`generations`, `usd`, and `free`; custom adapters may register another
+non-empty unit. Candidate count also belongs to the provider estimate rather
+than being assumed globally.
 
 ## State machine
 
@@ -71,15 +74,17 @@ and exporters all use the same role model. A consumer must request a role when
 there is no unambiguous primary output.
 
 PNG ingestion validates signature, chunks, CRCs, palettes, compressed data,
-scanlines, dimensions, and supported color modes before bytes become durable
-output or recovery cache data.
+scanlines, dimensions, and supported color modes. GIF ingestion walks the
+logical screen, color tables, extensions, image-data blocks, and trailer. Both
+formats are validated before bytes become durable output or recovery cache data.
 
 ## Concurrency and lock saves
 
 Lock writes use a same-directory temporary file and rename. An advisory writer
 lock serializes separate processes. In-process saves queue per path, and
 field-level dirty patches merge separate snapshots so updates to different
-assets—or different fields of one asset—do not silently lose the earlier write.
+assets, or to different fields of one asset, do not silently lose the earlier
+write.
 Stale advisory locks are recoverable after their safety window.
 
 ## Derived artifact transactions
@@ -110,11 +115,18 @@ byte is structurally validated before use.
 
 ## Provider capability boundary
 
-Required provider members cover support/estimate, submit, poll, selection where
-applicable, and download. Account-wide listing, tagging, deletion, and balance
-are optional. Commands such as adopt or salvage report a capability gap rather
-than failing through an undefined method.
-
-`FakeProvider` implements the same contract in memory, which keeps the paid
-pipeline testable without credentials or network access. See
-[library API](./LIBRARY.md) and [provider notes](../PROVIDERS.md).
+Providers are selected from a registry by the manifest's top-level `provider`
+id. Required members cover support/estimate, submit, poll, and download;
+candidate selection is required only when an adapter can return alternatives.
+Account-wide listing, tagging, deletion, and balance are optional. Commands
+such as adopt or salvage report a capability gap rather than failing through
+an undefined method.
+
+`PixelLabProvider` is production and live-tested. `RetroDiffusionProvider` is
+an experimental still, tileset, and animation adapter. Authenticated RD Fast
+and RD Plus single-candidate still lifecycles have passed end to end. Its
+multi-candidate, tileset, GIF, and spritesheet paths retain mocked coverage
+pending paid live smokes. `FakeProvider` implements the same contract in memory, which
+keeps the paid pipeline testable without credentials or network access. See
+[library API](./LIBRARY.md) and
+[PixelLab vs. Retro Diffusion](../PROVIDERS.md).

package/docs/CLI.md

@@ -9,6 +9,11 @@ Unknown commands, positional arguments, and flags are errors. Repeated
 separated values work too. This strict parsing prevents a misspelled filter
 from widening a paid run.
 
+The manifest's top-level `provider` field selects the provider for `plan`,
+`doctor`, and pipeline commands. It defaults to `pixellab`; the built-in
+`retrodiffusion` adapter is experimental and supports still-image
+`map`/`pixflux`, `tiles` sheets, and `animation` GIF/spritesheet work.
+
 ## Everyday pipeline
 
 ### `init`
@@ -73,9 +78,10 @@ for a screenshot of the actual interface.
 
 ### `fetch`
 
-Download completed or selected outputs, validate complete PNG structure, write
-the manifest-authoritative destinations, populate the content cache, and update
-output hashes. `--tag` also pushes manifest tags after successful downloads.
+Download completed or selected outputs, validate complete PNG or GIF structure,
+write the manifest-authoritative destinations, populate the content cache, and
+update output hashes. `--tag` also pushes manifest tags after successful
+downloads when the provider supports tagging.
 
 ### `restore`
 
@@ -134,13 +140,57 @@ or download artwork.
 
 ### `balance`
 
-Show the provider's remaining balance and cost unit.
+Show the manifest-selected provider's remaining balance and cost unit. Reports
+a capability error when an installed provider has no balance endpoint.
 
 ### `status`
 
 Summarize lock entries by state and successful submission spend by cost unit.
 Supports `--json`; unlike units are never added together.
 
+### `workspace`
+
+Register sibling projects in a schema-versioned catalog file, outside any one
+manifest, so a shared provider account's complete claim set no longer depends
+on remembering every `--claims` path. Offline throughout.
+
+```bash
+pixelkiln workspace add ../other-game/pixelkiln.manifest.json
+pixelkiln workspace add ../another-game/pixelkiln.manifest.json --name another
+pixelkiln workspace list
+pixelkiln workspace status --json
+pixelkiln workspace claims
+pixelkiln workspace remove another
+```
+
+Subcommands:
+
+| Subcommand | Effect |
+|---|---|
+| `add <manifest>` | Registers a project. Id defaults to the manifest's `name`; `--name` overrides it. Lock defaults to `pixelkiln.lock.json` beside the manifest; `--lock` overrides it. `--provider` overrides the manifest's provider id; `--account` sets a free-form account label. Refuses a duplicate id or a lockfile already registered under another id. Warns, but does not refuse, when the lock does not exist yet. |
+| `remove <id-or-manifest>` | Drops a registration by project id or by manifest path. Touches no art, no lock, no provider account. |
+| `list` | Lists registered projects and catalog diagnostics. Refuses if the catalog file does not exist. |
+| `status` | Aggregate provider, spend-by-unit, plan state, and claim count, offline. Provider cost units are never summed across each other. Refuses if the catalog file does not exist. |
+| `claims` | Validates the catalog and emits the exact union of `objectId`/`reviewObjectId`/`jobId` across every registered lock. Refuses to omit a project when any registered lock is missing or unreadable, or when the catalog has a duplicate id or lock path. |
+
+`--workspace <path>` selects the catalog file; it defaults to
+`pixelkiln.workspace.json` in the current directory. Stored paths are relative
+to the catalog file's own directory, so a catalog survives a clone or move.
+`list`/`status` support `--json` and `--check` (nonzero exit on any error-level
+diagnostic); both treat a nonexistent catalog file as a hard error rather than
+an empty, vacuously-safe one. This is the same hazard class as an incomplete
+claim set. In `--json` output, the `workspace` key always names the catalog *file*;
+`status` also reports `dir`, the catalog's own directory that
+registered paths resolve against.
+
+Passing `--workspace <path>` to `salvage` derives its claim set and its
+sibling-manifest style signal from every project the catalog registers.
+`--claims` still works and joins both the lockfile claim set and sibling
+manifest list. A missing or unreadable registered lock is a hard error there
+too. PixelKiln never skips one because the catalog exists to guarantee a
+complete account-wide claim set. See
+[Recovery and account safety](./RECOVERY.md#shared-workspace-catalog).
+
 ## Local quality and derived output
 
 ### `audit`
@@ -217,6 +267,9 @@ Print the package version. `-v` is an alias.
 | `--no-open` | pick/salvage | Do not automatically open the browser. |
 | `--tag` | fetch/adopt | Also push tags after the command's primary work. |
 | `--claims <paths>` | salvage | Other project lockfiles; repeatable and comma-separated. |
+| `--workspace <path>` | workspace/salvage | Workspace catalog path; defaults to `pixelkiln.workspace.json`. On salvage, derives the claim set instead of repeated `--claims`. |
+| `--provider <id>` | workspace add | Provider id to register the project under; defaults to the target manifest's provider. |
+| `--account <label>` | workspace add | Free-form account label, e.g. distinguishing sandboxes. |
 | `--all` | salvage dry run | List every unclaimed object rather than the first 30. |
 | `--from <dir>` | init | Existing source tree to scan. |
 | `--exclude <names>` | init | Directory/name fragments to exclude; repeatable. |

package/docs/ENDPOINTS.md

@@ -1,4 +1,4 @@
-# PixelLab API — measured reference
+# Measured PixelLab API reference
 
 Every cost here was **measured against a live Tier 2 account**, not read from
 documentation. Where a figure came from docs rather than a meter, it says so.
@@ -10,7 +10,7 @@ Auth is one long-term key for everything: `Authorization: Bearer $PIXELLAB_API_K
 
 ---
 
-## The API surface
+## Endpoint families
 
 | Family | Paths | What it covers |
 |---|---|---|
@@ -27,7 +27,7 @@ listed so it is obvious what exists.
 
 ---
 
-## Single-image generators — measured
+## Single-image generators, measured
 
 The endpoints that produce one standalone image. This is the decision that
 matters most for icon and prop work.
@@ -50,12 +50,12 @@ regardless of size.
 
 **`pixflux` is the workhorse.** 1 generation, returns the PNG inline, and its
 `color_image` parameter is a genuine constraint. A two-colour palette produced
-130 badges containing **only** `#000000` and `#ffffff` — verified 65/65 in each
+130 badges containing **only** `#000000` and `#ffffff`, verified 65/65 in each
 of two sets. Prose asking for the same thing gave a yellow star and a brown
 chocolate bar.
 
 **`bitforge` disappoints.** It is the only single-image endpoint with palette
-*and* style reference *and* synchronous delivery, all for 1 generation — which
+*and* style reference *and* synchronous delivery, all for 1 generation, which
 should make it ideal. In practice it returned unrecognisable blobs for a simple
 "blacksmith anvil" prompt at `style_strength` 0, 10, 25 and 50. The first
 failure looked like the style reference overwhelming the prompt; sweeping the
@@ -63,7 +63,7 @@ strength proved otherwise. Possibly tuned for a different kind of subject (docs
 call it "Create S-M image", max area 200×200). **Do not reach for it on this
 evidence alone.**
 
-**`pixen` gave the best unconstrained detail** of anything at 1 generation — a
+**`pixen` gave the best unconstrained detail** of anything at 1 generation, a
 properly rendered anvil with sparks where others produced flat shapes. It has no
 palette parameter, so it suits styles carried entirely by the prompt.
 
@@ -96,15 +96,15 @@ A palette swatch must also be **chunky**: a 4×1 image was rejected outright wit
 
 ---
 
-## Post-processing utilities — measured
+## Post-processing utilities, measured
 
 Five endpoints take an image in and give one back. All are **synchronous**, all
-return `{usage, image}` inline, and all cost **1 generation** — including the
+return `{usage, image}` inline, and all cost **1 generation**, including the
 ones that sound like pure image manipulation.
 
 | Endpoint | Cost | Palette survives? | What it actually does |
 |---|---|---|---|
-| `remove-background` | 1 | **yes** | Genuine cleanup — the only safe one |
+| `remove-background` | 1 | **yes** | Genuine cleanup, the only safe one |
 | `rotate` | 1 | no | Re-renders from a new angle |
 | `resize` | 1 | no | **Re-generates**, does not resample |
 | `image-to-pixelart` | 1 | no | Destroys alpha too |
@@ -115,7 +115,7 @@ Measured on one 64×64 riso badge with an exact 4-colour palette
 
 | | colours out | transparency | result |
 |---|---|---|---|
-| source | 4 | 0.57 | — |
+| source | 4 | 0.57 | n/a |
 | `remove-background` | **3** | 0.60 | dropped a stray fringe, kept the rest |
 | `rotate` | 30 | 0.58 | anti-aliased new angle |
 | `resize` → 32px | 38 | 0.57 | cream+rust came back **gold** |
@@ -123,7 +123,7 @@ Measured on one 64×64 riso badge with an exact 4-colour palette
 
 **`remove-background` is a de-fringe pass, not just a matte.** It removed the
 scattered sage-green speckles around the badge outline and left the three real
-inks untouched — colour count went *down*, transparency went *up*. It is the one
+inks untouched. Colour count went *down*, transparency went *up*. It is the one
 utility safe to run on palette-locked art.
 
 **`resize` is generative, not a resampler.** The name is misleading: it takes a
@@ -131,7 +131,7 @@ utility safe to run on palette-locked art.
 badge came back as 38 colours of gold.
 
 **`color_image` does not rescue it.** `resize` accepts the parameter in its
-schema; passing the exact same swatch that `pixflux` honours changed nothing —
+schema; passing the exact same swatch that `pixflux` honours changed nothing.
 56 colours, still gold. The forced palette works on **`pixflux` and `bitforge`
 only**, and being in another endpoint's schema is not evidence it is wired up.
 
@@ -146,7 +146,7 @@ prevent that.
 
 ---
 
-## Tilesets — schema only, not yet measured
+## Tilesets: schema only, not yet measured
 
 Called out separately because these are the most capable endpoints for level art
 and they are relevant to the disc-golf game. **Costs below are unmeasured.**
@@ -155,17 +155,17 @@ and they are relevant to the disc-golf game. **Costs below are unmeasured.**
 versions; `/create-tileset*` are the older aliases with identical schemas.
 
 They take `lower_description` + `upper_description` (+ optional
-`transition_description`) — you describe two terrains and the transition between
+`transition_description`). You describe two terrains and the transition between
 them, and get a tileset that blends them. Distinctively, they accept **both**
 `color_image` *and* per-layer reference images (`lower_reference_image`,
-`upper_reference_image`, `transition_reference_image`) — the only family that
-combines palette forcing with style anchoring.
+`upper_reference_image`, `transition_reference_image`). They are the only
+family that combines palette forcing with style anchoring.
 
 Useful knobs: `tile_size`, `tileset_adherence` / `tileset_adherence_freedom`
 (how strictly tiles must fit together), `raggedness` and `slope_size` for edge
 character, plus the usual `outline` / `shading` / `detail`.
 
-`create-tiles-pro` is a different shape — a single `description` plus
+`create-tiles-pro` is a different shape, a single `description` plus
 `style_images`, `tile_view`, `building_*` fields for structures.
 
 Its `style_images` is a **fourth** convention, and not the one two lines up:
@@ -178,14 +178,14 @@ Its `style_images` is a **fourth** convention, and not the one two lines up:
 
 Sending `generate-with-style-v2`'s nested `{image: {...}}` here is rejected as
 an extra field. Passing style images at all makes the endpoint ignore
-`tile_type` and `tile_view` and copy the reference's tile geometry instead —
-which is the only way to land new art on an existing sheet's ground plane.
+`tile_type` and `tile_view` and copy the reference's tile geometry instead.
+That is the only way to land new art on an existing sheet's ground plane.
 
 `GET /tiles-pro/{id}` carries no `status` field. It answers **423 while the set
 is still drawing** and 200 with `storage_urls` when it is done, so the HTTP code
 is the status. Cost is reported at submit time and lands on the same 20/25/40
 canvas tiers as `1dir`, but the canvas is tile size x variation count, not one
-sprite — a small tile in a large set still reaches the top tier.
+sprite. A small tile in a large set still reaches the top tier.
 
 All response shapes used by the client are validated at runtime. The TypeScript
 interfaces alone are not trusted at the HTTP boundary: missing ids, invalid
@@ -195,18 +195,19 @@ produce an `Invalid PixelLab response` error before pipeline state is updated.
 `outline_mode` defaults to `outline`, which draws a dark border around every
 tile. For ground tiles that is wrong: laid on a grid the borders read as
 quilting, with a seam at every cell edge. `segmentation` omits them and the
-same set tiles seamlessly — measured on a fairway-to-rough terrain set, where
+same set tiles seamlessly, measured on a fairway-to-rough terrain set, where
 it was the difference between usable and unusable.
 
-`tile_feature` and `style_images` are **mutually exclusive** — "Connectable
-features (roads/tileset/building) cannot be combined with style tiles". So the
+`tile_feature` and `style_images` are **mutually exclusive**. The API says
+"Connectable features (roads/tileset/building) cannot be combined with style
+tiles". So the
 geometry-anchoring trick above is unavailable for a connectable set, and its
 tiles land on whatever ground plane the view angle implies (measured: 32x24
 with the diamond midline at y=7, against a 32x32 sheet wanting y=15).
 
 `tile_feature` turns it from independent variations into a connectable set:
 `roads` (18-configuration path set), `tileset` (16-tile Wang corner set for a
-terrain transition — describe it as the transition, not one terrain), and
+terrain transition; describe it as the transition, not one terrain), and
 `building` (floor/wall/doorway kit). These are sliced by index, so the returned
 order is load-bearing. They are structural multi-output results, not candidates
 to choose between: PixelKiln persists every URL in numeric order and labels the
@@ -230,12 +231,12 @@ committing to a set**.
 ## Recipes
 
 **Lock a palette.** Use `pixflux` with a `color_image` swatch. Build the swatch
-with `paletteSwatch()` — 64×64 blocks, one band per colour. It is a real
+with `paletteSwatch()`: 64×64 blocks, one band per colour. It is a real
 constraint, not a hint: 130 badges across two sets came back containing *only*
 the requested colours.
 
 **Re-roll one bad asset.** 1 generation. `gen --only <id> --force`. Cheaper than
-asking for more candidates — a `1dir` call that yields 16 candidates costs 20–40.
+asking for more candidates. A `1dir` call that yields 16 candidates costs 20–40.
 
 **Clean up fringing.** `remove-background` at 1 generation, and it will not
 disturb the palette.
@@ -245,7 +246,7 @@ size. Do not use `resize`.
 
 **Anchor to an existing look rather than a palette.** `generate-with-style-v2`
 (20) or `generate-image-v2` (40). `bitforge` claims to do this for 1, but see
-above. `map` has no style anchoring at all — a 1-bit set generated through it
+above. `map` has no style anchoring at all. A 1-bit set generated through it
 came back with a yellow star and a brown chocolate bar.
 
 **Write prompts for a monochrome style.** Strip colour words from the prompt
@@ -263,7 +264,7 @@ whole set. Put the medium in the *suffix*, after the subject.
 ## Candidates
 
 Only `create-1-direction-object` returns multiple candidates, and the count is
-derived from size — it cannot be requested:
+derived from size, and cannot be requested:
 
 | size | candidates |
 |---|---|
@@ -285,8 +286,8 @@ once a 1-generation re-roll exists: forty re-rolls cost one `1dir` call.
   **image survives**: a March 2026 sprite still resolved from `/v2/objects` four
   months on while `/v2/map-objects/{id}` returned 404. pixelkiln's `poll` checks
   the objects collection on a 404 rather than writing the work off.
-- `pixflux`/`pixen`/`bitforge` results are **not account objects** at all —
-  bytes come back inline and are never listed. `adopt` and `salvage` cannot see
+- `pixflux`/`pixen`/`bitforge` results are **not account objects** at all.
+  Bytes come back inline and are never listed. `adopt` and `salvage` cannot see
   them, and they cannot be tagged.
 
 ---
@@ -309,15 +310,15 @@ once a 1-generation re-roll exists: forty re-rolls cost one `1dir` call.
 
 Listed so the gaps are known rather than assumed away:
 
-- `inpaint`, `inpaint-v3`, `edit-image`, `edit-images-v2` — targeted edits.
+- `inpaint`, `inpaint-v3`, `edit-image`, `edit-images-v2`, for targeted edits.
   Both `inpaint` and `edit-image` accept `color_image`, but given that `resize`
   accepts and ignores it, assume nothing until measured.
-- `image-to-pixelart-pro` — takes only `image` + `description`, no size fields.
+- `image-to-pixelart-pro` takes only `image` + `description`, no size fields.
   The non-Pro version is characterised above.
-- the tileset family — schema documented above, costs unmeasured
-- `create-isometric-tile`, `create-ui-asset`, `generate-font-pro` — job-based,
-  response shapes not in the simple `{usage, image}` form
-- the character family (23 paths) — out of pixelkiln's scope by design
+- the tileset family, with schema documented above and costs unmeasured
+- `create-isometric-tile`, `create-ui-asset`, `generate-font-pro`, all job-based,
+  with response shapes not in the simple `{usage, image}` form
+- the character family (23 paths), out of pixelkiln's scope by design
 
 ---
 
@@ -328,7 +329,7 @@ curl -s -H "Authorization: Bearer $PIXELLAB_API_KEY" \
   https://api.pixellab.ai/v2/balance
 ```
 
-The count lives at **`subscription.generations`**, not at the top level — a
+The count lives at **`subscription.generations`**, not at the top level. A
 probe reading `.generations` gets `undefined` and silently reports every cost as
 `NaN` rather than failing:
 
@@ -340,5 +341,5 @@ probe reading `.generations` gets `undefined` and silently reports every cost as
 ```
 
 Take a balance reading, make one call, wait a few seconds, read again. Prefer
-the response's `usage` field where present — it is inline, exact, and immune to
+the response's `usage` field where present. It is inline, exact, and immune to
 the billing lag.

package/docs/GENERATORS.md

@@ -32,6 +32,11 @@ It does not accept style images or a forced palette. On a measured 1-bit restyle
 switching from reference-anchored generation to `map` changed median palette
 distance from 6.6 to 41.9; cheap output is not cheap when unusable.
 
+The API describes map objects as transparent, but both 256px isolated-object
+attempts in the [environment provider benchmark](./PROVIDER_BENCHMARK.md) were
+opaque. `map` has no `noBackground` control in PixelKiln. Check alpha before
+assuming the file can be placed directly over a map.
+
 ## `1dir`
 
 `1dir` is the single-facing sibling of PixelLab's rotatable/animated object
@@ -114,7 +119,7 @@ instead creates a structural set in provider order:
 | `tileset` | 16-tile Wang-corner terrain transition. |
 | `building` | Floor/wall/doorway/pillar/stair construction kit. |
 
-Describe a `tileset` asset as the transition—“fairway grass to rough meadow”—
+Describe a `tileset` asset as the transition, "fairway grass to rough meadow",
 rather than one terrain. Every returned member is required, so PixelKiln
 records numerical roles such as `tile-00` rather than treating them as choices.
 

package/docs/GETTING_STARTED.md

@@ -1,6 +1,6 @@
 # Getting started
 
-Pixelkiln turns a committed asset manifest into generated files with a
+PixelKiln turns a committed asset manifest into generated files with a
 committed provenance lockfile. Planning, auditing, packing, mounting, and
 exporting are local operations. Only generation, provider polling, candidate
 selection, downloads, tagging, account adoption, salvage, purge, and balance
@@ -9,7 +9,8 @@ checks need provider access.
 ## Requirements
 
 - Node.js 20 or newer
-- A PixelLab API key for provider-backed commands
+- 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
 
@@ -53,6 +54,24 @@ in `.env.local` beside the manifest:
 PIXELLAB_API_KEY=...
 ```
 
+For experimental Retro Diffusion generation, set the manifest's
+top-level `provider` to `retrodiffusion` and use:
+
+```dotenv
+RD_API_KEY=...
+```
+
+Its still, tileset-sheet, animated-GIF, and PNG-spritesheet workflows are
+implemented. Authenticated single-candidate RD Fast and RD Plus stills have
+passed from quote through validated download, provenance, and cache.
+Multi-candidate, tileset, GIF, and spritesheet live runs remain, so PixelLab
+remains the production adapter. See
+[Manifest reference](MANIFEST.md#experimental-retro-diffusion) for
+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).
+
 Before spending anything, validate and price the selected work:
 
 ```bash
@@ -134,8 +153,8 @@ pipeline stages also exit nonzero after partial failures or timeouts.
 - `restore` repairs missing generated outputs without buying new generations.
 - `.pixelkiln/cache/` stores downloaded PNG bytes by SHA-256, so restoration can
   still work after a temporary provider URL expires.
-- `cache --check` verifies hashes and fully decodes cached PNG structure before
-  trusting recovery bytes, then validates the account object-hash cache.
+- `cache --check` verifies hashes and structurally validates cached PNG/GIF
+  media before trusting recovery bytes, then validates the account object-hash cache.
   `cache --prune` removes corrupt, partial, and unreferenced project content
   plus invalid hash entries. It does not mistake
   objects belonging to another project for disposable account data.
@@ -143,7 +162,7 @@ pipeline stages also exit nonzero after partial failures or timeouts.
 - `salvage --claims <every-other-lockfile>` reviews remote objects no project
   currently claims. `salvage` never deletes; `purge` is a separate confirmed
   operation.
-- Pixelkiln refuses to overwrite a file whose bytes differ from its recorded
+- PixelKiln refuses to overwrite a file whose bytes differ from its recorded
   hash. Resolve intentional hand edits explicitly.
 
 ## What belongs in Git

package/docs/LIBRARY.md

@@ -1,6 +1,6 @@
 # Library API
 
-Pixelkiln's public package entry point exposes the same provider-independent
+PixelKiln's public package entry point exposes the same provider-independent
 primitives used by the CLI. Use these when a build tool, editor integration, or
 game pipeline needs structured results instead of terminal output.
 
@@ -130,9 +130,9 @@ await fetchAssets(provider, specs, lock, lockPath)
 ```
 
 Provider-backed operations mutate the supplied lock object; persist at the
-workflow boundary with `saveLock`. See [PROVIDERS.md](../PROVIDERS.md) before
-implementing another backend, especially its optional capabilities and cost
-units.
+workflow boundary with `saveLock`. See
+[PixelLab vs. Retro Diffusion](../PROVIDERS.md) before selecting or implementing
+another backend, especially its optional capabilities and cost units.
 
 `submit` validates adapter estimates again at the spending boundary and returns
 `{ spent, unit }` for successful submissions. Lock entries retain fractional