pixelkiln 0.2.0 → 0.3.0

package/CONTRIBUTING.md

@@ -53,6 +53,14 @@ for pipeline behavior and mocked HTTP responses for PixelLab wire contracts.
 - 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 +98,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,4 +1,4 @@
-# Multi-provider — status and notes
+# Multi-provider status and notes
 
 **The seam is built.** `src/provider.ts` defines the interface;
 `src/providers/pixellab.ts` is the reference implementation and
@@ -42,9 +42,9 @@ 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.
+- Purpose-built for pixel art, with grid-aligned output and 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.
 
@@ -65,13 +65,13 @@ 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.
+   number meaning PixelLab subscription generations. It now carries a unit: USD
+   for OpenAI, generations for PixelLab, free for local. `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
+2. **Free candidates were a PixelLab quirk.** The core loop is to generate
+   small, get 16 candidates for one fixed price, and pick the best. It 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.
@@ -86,9 +86,9 @@ 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:
+17 integration tests now cover `submit → poll → fetch`, `pushTags` and `adopt`.
+Those are 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.
 

package/README.md

@@ -38,7 +38,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 +52,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. |
@@ -253,9 +253,20 @@ 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` — never a silent skip. Purge only
+targets objects already tagged discard and requires an explicit confirmation.
+See [Recovery and account safety](./docs/RECOVERY.md).
 
 ## Automation
 
@@ -323,10 +334,12 @@ Project policies: [Contributing](./CONTRIBUTING.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/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,