pixelkiln 0.2.0 → 0.3.0

package/docs/AGENTS.md

@@ -28,7 +28,7 @@ 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

package/docs/ARCHITECTURE.md

@@ -41,7 +41,8 @@ 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
+Cost units that differ are never summed. `generations`, `usd`, and `free`
+stay separate. Candidate
 count also belongs to the provider estimate rather than being assumed globally.
 
 ## State machine
@@ -79,7 +80,8 @@ output or recovery cache data.
 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

package/docs/CLI.md

@@ -141,6 +141,50 @@ Show the provider's remaining balance and cost unit.
 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` sets the provider id (default `pixellab`); `--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 — rather than silently omitting a project — when any registered lock is missing, unreadable, or the catalog itself has a duplicate id or duplicate 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 — the same hazard class as an incomplete claim
+set. In `--json` output, the `workspace` key always names the catalog *file*;
+`status` additionally 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 unions with both — the combined lockfile claim set
+and the combined sibling-manifest list. A missing or unreadable registered
+lock is a hard error there too — never silently skipped — because it is
+precisely the account-wide claim completeness this catalog exists to
+guarantee. See
+[Recovery and account safety](./RECOVERY.md#shared-workspace-catalog).
+
 ## Local quality and derived output
 
 ### `audit`
@@ -217,6 +261,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 `pixellab`. |
+| `--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

@@ -114,7 +114,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/RECOVERY.md

@@ -86,6 +86,50 @@ array to stdout and human diagnostics to stderr for piping into `jq`.
 Imported ids are derived from prompts and land under `_salvaged/`; review and
 rename them before treating them as stable application ids.
 
+## Shared workspace catalog
+
+For a single project, its own lockfile is the whole claim set. On a shared
+account with several sibling projects, repeating `--claims` on every salvage
+run is easy to get wrong — a forgotten lockfile makes another project's paid
+art look unclaimed. `workspace` fixes that by registering every sibling once,
+outside any one manifest:
+
+```bash
+pixelkiln workspace add ../other-game/pixelkiln.manifest.json
+pixelkiln workspace add ../another-game/pixelkiln.manifest.json --name another
+pixelkiln workspace status
+pixelkiln workspace claims
+```
+
+`workspace status` reports aggregate provider, spend-by-unit, and plan state
+per project, offline. `workspace claims` validates the catalog and emits the
+exact union of `objectId`/`reviewObjectId`/`jobId` across every registered
+lock — the same union rule `--claims` uses, so the two paths cannot drift.
+
+A registered lockfile that is missing or unreadable is a hard error for
+`claims`, never a silent skip: an incomplete claim set is precisely what makes
+another project's shipped art look orphaned. `workspace add` still lets you
+register a brand-new project before its first `gen` — it warns rather than
+refusing, since the project genuinely has no lock yet — but `claims` and
+`salvage --workspace` both refuse until every registered project has one.
+
+Salvage accepts the catalog directly instead of a repeated `--claims` list:
+
+```bash
+pixelkiln salvage --workspace pixelkiln.workspace.json --dry-run
+pixelkiln salvage --workspace pixelkiln.workspace.json
+```
+
+`--claims` still works and unions with a workspace's claim set — useful for a
+one-off lockfile that isn't part of the catalog. Choose one workflow per
+account: `--claims` for an occasional cross-project check, `workspace` once
+sibling projects are a standing arrangement worth registering once.
+
+The catalog stores paths and project identity, never a credential — each
+project still loads its own provider key from its own `.env`. `workspace
+remove` only edits the catalog file; it never touches art, a lock, or the
+provider account.
+
 ## Confirmed purge
 
 Deletion is a separate command:

package/docs/TILES.md

@@ -53,7 +53,7 @@ The companion record is engine-neutral: it stores portable source paths and
 SHA-256s, export options (including raw provider rules), output hashes, and a
 canonical fingerprint. `verifyArtifactBundle()` can detect changed inputs,
 edited/missing outputs, or altered provenance offline without rebuilding the
-atlas. The project manifest and lockfile are conservative inputs, ensuring that
+atlas. The project manifest and lockfile are conservative inputs, so
 newly declared or recorded tiles also make an older export stale. The TSJ/TRES
 contracts therefore remain free of PixelKiln-only fields.
 

package/examples/minimal/README.md

@@ -22,5 +22,5 @@ Add a second entry under `styles` with a different `outDir`, then:
 pixelkiln gen --style neon
 ```
 
-Every asset re-derives under the new style. The original files are untouched —
-styles are separate namespaces in both the output tree and the lockfile.
+Every asset re-derives under the new style. The original files are untouched.
+Styles are separate namespaces in both the output tree and the lockfile.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,

package/schema/workspace.schema.json

@@ -0,0 +1,54 @@
+{
+  "$ref": "#/definitions/PixelkilnWorkspace",
+  "definitions": {
+    "PixelkilnWorkspace": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "number",
+          "const": 1
+        },
+        "projects": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "manifest": {
+                "type": "string",
+                "minLength": 1
+              },
+              "lock": {
+                "type": "string",
+                "minLength": 1
+              },
+              "provider": {
+                "type": "string",
+                "minLength": 1,
+                "default": "pixellab"
+              },
+              "account": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "manifest",
+              "lock"
+            ],
+            "additionalProperties": false
+          },
+          "default": []
+        }
+      },
+      "required": [
+        "version"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}