pixelkiln 0.4.0 → 0.5.0

package/CONTRIBUTING.md

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

package/PROVIDERS.md

@@ -80,6 +80,55 @@ 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.
 
+## Use both providers in one project
+
+One manifest selects one provider. PixelKiln does not currently support a
+provider override on an individual style or asset. The boundary is deliberate:
+one command constructs one account adapter, and one `--budget` must have one
+meaning. PixelLab generations and Retro Diffusion dollars cannot share a safe
+ceiling.
+
+A repository can still use both providers today. Give each provider its own
+manifest, lockfile, and output directory:
+
+```text
+art/
+  pixelkiln.pixellab.manifest.json
+  pixelkiln.pixellab.lock.json
+  pixelkiln.retrodiffusion.manifest.json
+  pixelkiln.retrodiffusion.lock.json
+pixelkiln.workspace.json
+```
+
+Plan and authorize each manifest separately:
+
+```bash
+pixelkiln plan --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json
+pixelkiln gen --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json --budget <generations>
+
+pixelkiln plan --manifest art/pixelkiln.retrodiffusion.manifest.json --lock art/pixelkiln.retrodiffusion.lock.json
+pixelkiln gen --manifest art/pixelkiln.retrodiffusion.manifest.json --lock art/pixelkiln.retrodiffusion.lock.json --budget <usd>
+```
+
+Register both manifests in the workspace catalog for aggregate status and
+complete claim checks. Keep the provider lockfiles separate. Package their
+reviewed outputs independently, or combine explicit files with `pixelkiln pack
+--inputs <file> --out <path>`.
+
+This is a useful split when PixelLab handles prompt-sensitive buildings and
+account recovery while Retro Diffusion handles environment-styled backdrops,
+clean cutouts, or native animation. Retro Diffusion is not a higher-resolution
+route through PixelKiln today: its useful environment styles cap at 384×384,
+while PixelLab `map` reaches 400×400. Its advantage is the model/style and
+output type, not raw dimensions.
+
+Native mixed-provider support inside one manifest would be a larger feature,
+not a schema-only change. It needs provider selection on each style, plans and
+confirmations grouped by provider and cost unit, separate budget ceilings,
+per-provider polling and downloads, and an explicit provider for account-wide
+commands. The lockfile already records a provider on every entry, so the state
+format can support that direction without merging provider identities.
+
 ## Cost comparison
 
 The services use different billing units, so PixelKiln never adds their costs
@@ -129,6 +178,8 @@ estimate and hard budget remain enforced.
 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.
+6. Evaluate per-style provider selection with provider-keyed budgets; do not
+   overload the current scalar `--budget` or silently sum incompatible units.
 
 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

@@ -25,9 +25,9 @@ tileset, GIF, and spritesheet live runs remain. See
 large environment and building workflows.
 `FakeProvider` exercises the same contract deterministically in tests.
 
-> **Release status:** the package is pre-1.0 and the first npm publication is
-> tracked in [issue #1](https://github.com/gfargo/pixelkiln/issues/1). Until it
-> is live, use a repository checkout.
+> **Release status:** PixelKiln is published on npm. Merges to `main` use
+> Semantic Release and npm Trusted Publishing, with signed provenance and no
+> long-lived npm publishing token.
 
 ## Why PixelKiln
 
@@ -76,21 +76,18 @@ a row unresolved. Nothing is applied when the window is closed without using
 **Apply selections**. See the [CLI reference](docs/CLI.md#pick) for the complete
 review workflow.
 
-## Install from a checkout
+## Install
 
 Requires Node.js 20 or newer.
 
 ```bash
-git clone https://github.com/gfargo/pixelkiln.git
-cd pixelkiln
-npm ci
-npm run pixelkiln -- help
-npm test
+npm install --save-dev pixelkiln
+npx pixelkiln --help
 ```
 
-`npm run pixelkiln -- …` executes the TypeScript source. `npm run build`
-creates the ESM, CommonJS, declarations, and CLI distribution used by the
-published package.
+For library use, both `import("pixelkiln")` and `require("pixelkiln")` are
+supported. Contributors can still run `npm run pixelkiln -- …` from a checkout
+to execute the TypeScript source directly.
 
 ## Five-minute start
 
@@ -114,14 +111,11 @@ RD_API_KEY=...
 Validate locally, inspect exact work/cost, then generate with a hard ceiling:
 
 ```bash
-/path/to/pixelkiln/node_modules/.bin/tsx /path/to/pixelkiln/src/cli.ts doctor --dry-run
-/path/to/pixelkiln/node_modules/.bin/tsx /path/to/pixelkiln/src/cli.ts plan
-/path/to/pixelkiln/node_modules/.bin/tsx /path/to/pixelkiln/src/cli.ts gen --budget 120
+npx pixelkiln doctor --dry-run
+npx pixelkiln plan
+npx pixelkiln gen --budget 120
 ```
 
-Once installed from npm, those commands become `pixelkiln doctor`,
-`pixelkiln plan`, and `pixelkiln gen`.
-
 `gen` submits, polls, opens the candidate-review sheet when necessary,
 downloads validated output, populates the recovery cache, and updates
 `pixelkiln.lock.json`. Commit the manifest, lockfile, generated art, and any

package/docs/AGENTS.md

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

package/docs/GETTING_STARTED.md

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

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "pixelkiln",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "pixelkiln": "./bin/pixelkiln.js"
+    "pixelkiln": "bin/pixelkiln.js"
   },
   "exports": {
     ".": {
@@ -29,6 +29,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:docs": "node scripts/check-docs.mjs",
+    "test:release": "node scripts/check-release.mjs",
     "test:package": "node scripts/smoke-package.mjs",
     "test:watch": "vitest",
     "schema": "tsx scripts/gen-schema.ts",

package/skills/pixelkiln/SKILL.md

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

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

@@ -0,0 +1,43 @@
+# Mixed-provider projects
+
+Read this reference when one game or repository needs assets from both PixelLab
+and Retro Diffusion.
+
+One manifest selects one top-level `provider`. Do not add undocumented
+per-style provider fields: the current CLI constructs one account adapter for a
+manifest run, and a single `--budget` has one provider-specific unit.
+
+Use one manifest and lockfile per provider inside the same project:
+
+```text
+art/
+  pixelkiln.pixellab.manifest.json
+  pixelkiln.pixellab.lock.json
+  pixelkiln.retrodiffusion.manifest.json
+  pixelkiln.retrodiffusion.lock.json
+pixelkiln.workspace.json
+```
+
+Keep their output directories distinct. Plan and authorize them separately:
+
+```bash
+pixelkiln plan --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json
+pixelkiln gen --manifest art/pixelkiln.pixellab.manifest.json --lock art/pixelkiln.pixellab.lock.json --budget <generations>
+
+pixelkiln plan --manifest art/pixelkiln.retrodiffusion.manifest.json --lock art/pixelkiln.retrodiffusion.lock.json
+pixelkiln gen --manifest art/pixelkiln.retrodiffusion.manifest.json --lock art/pixelkiln.retrodiffusion.lock.json --budget <usd>
+```
+
+Register both manifests in the workspace catalog so aggregate status and claim
+checks see the whole project. A mixed-provider warning is expected because it
+prevents account-wide commands from silently assuming one backend.
+
+Package each manifest's reviewed outputs independently, or use `pixelkiln pack
+--inputs <file> --out <path>` with an explicit JSON list when the final sheet
+must combine files from both providers. Never merge the two lockfiles or add
+generation counts to USD. Each entry must retain the provider that produced it.
+
+A practical split is PixelLab for prompt-sensitive buildings and mature account
+recovery, then Retro Diffusion for environment-styled backdrops, clean cutouts,
+or native animation. The committed benchmark is evidence for those tendencies,
+not a guarantee; run one representative asset before expanding either batch.

package/skills/pixelkiln/references/pixellab.md

@@ -0,0 +1,35 @@
+# PixelLab
+
+Read this reference when a manifest selects `pixellab`, when choosing between
+providers, or before any PixelLab account operation.
+
+## Operational boundary
+
+- Credential: `PIXELLAB_API_KEY` in `.env.local` beside the manifest or in the
+  process environment. Never print or commit it.
+- Status: production adapter. Generation and account workflows have live
+  coverage.
+- Cost unit: subscription generations. Copy the exact `pixelkiln plan` total
+  into `--budget`; do not translate it into dollars.
+- Account operations: balance, adopt, salvage, tag, and separately confirmed
+  purge are supported. Read `docs/RECOVERY.md` before using them.
+
+## Generator choice
+
+| Generator | Use it for | Measured cost |
+|---|---|---:|
+| `map` | One prop, icon, building, or landmark, up to 400×400 | 1 generation |
+| `pixflux` | Closed palettes or full-bleed backgrounds | 1 generation |
+| `1dir` | Reference-guided work or several candidates | 20–40 generations |
+| `tiles` | Ground variations or connected structures | 20–40 generations |
+
+In the committed environment benchmark, PixelLab followed complex building
+prompts more closely and produced the stronger scenic background. Its 256px map
+objects were opaque despite the route's transparency claim, so inspect alpha on
+one representative result before a batch.
+
+For setup and current field constraints, use
+<https://pixelkiln.griffen.codes/docs/pixellab>. When working in the PixelKiln
+repository, `docs/PIXELLAB.md` and `docs/ENDPOINTS.md` are the canonical local
+sources. The provider sources are <https://www.pixellab.ai/> and
+<https://api.pixellab.ai/v2/docs>.

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

@@ -0,0 +1,40 @@
+# Retro Diffusion
+
+Read this reference when a manifest selects `retrodiffusion`, when evaluating
+large scene work, or when using native animation and tileset output.
+
+## Operational boundary
+
+- Credential: `RD_API_KEY` in `.env.local` beside the manifest or in the
+  process environment. Never print or commit it.
+- Status: experimental adapter. RD Fast and RD Plus single-candidate stills are
+  live-tested through quote, submit, download, provenance, and recovery.
+  Multi-candidate, tileset, GIF, and spritesheet paths remain mock-tested.
+- Cost unit: USD. PixelKiln enforces the offline plan, then checks Retro
+  Diffusion's free authoritative quote before submission.
+- Account operations: balance is supported. Listing, adopt, salvage, tagging,
+  and deletion are not exposed by the current adapter.
+
+## Where it earns a place
+
+- `rd_plus__environment` for one-point-perspective scenic backgrounds.
+- `rd_plus__topdown_map` for 3/4 top-down maps.
+- `rd_tile__scene_object` for 64–384px objects placed on tile maps.
+- `rd_plus__topdown_asset` or `rd_plus__isometric_asset` for isolated assets.
+- `rd_animation__*` and `rd_advanced_animation__*` for GIF or PNG spritesheet
+  output.
+
+The useful environment styles currently top out at 384×384. PixelLab's `map`
+route reaches 400×400, so Retro Diffusion is not the higher-resolution option
+through PixelKiln today. Choose it for its scene styles, cleaner transparent
+cutouts, smaller palettes, cinematic framing, or native animation. Build truly
+large scenes from separately generated terrain, backdrop, landmark, building,
+and foreground layers, then integer-upscale with nearest-neighbor filtering.
+
+For setup, selectors, and option constraints, use
+<https://pixelkiln.griffen.codes/docs/retro-diffusion>. The matched visual
+evidence is at <https://pixelkiln.griffen.codes/docs/provider-benchmark>. When
+working in the PixelKiln repository, the same canonical sources are
+`docs/RETRO_DIFFUSION.md` and `docs/PROVIDER_BENCHMARK.md`. The provider sources
+are <https://www.retrodiffusion.ai/> and
+<https://www.retrodiffusion.ai/app/guide/api>.