pixelkiln 0.35.0 → 0.36.0

package/docs/CLI.md

@@ -17,6 +17,38 @@ work. The experimental `comfyui` adapter runs committed API-format `map` and
 ordered still-frame workflows on a self-hosted server. The experimental `scenario` adapter runs
 hosted still models with Compute Unit preflight and durable asset recovery.
 
+## Which command
+
+| I want to | Run |
+|---|---|
+| see what a run would do and cost, spending nothing | `pixelkiln plan` |
+| generate everything the manifest still needs | `pixelkiln gen --budget 40` |
+| generate one asset, or one style | `pixelkiln gen --only anvil --budget 2`, `pixelkiln gen --style neon --budget 20` |
+| finish a run that was interrupted | `pixelkiln plan`, then the `next:` command it prints (`poll`, `pick`, or `fetch`) |
+| choose among candidates the provider returned | `pixelkiln pick` |
+| get back a generated file I deleted or lost | `pixelkiln restore` |
+| bring back the generation a regeneration replaced | `pixelkiln history`, then `pixelkiln restore --only anvil --generation 1` |
+| look at everything the project has made | `pixelkiln gallery` |
+| change prompts and sizes, or regenerate, from the browser | `pixelkiln gallery --edit --budget 10` |
+| touch a sprite up by hand and keep the edit | `pixelkiln edit --only anvil` |
+| stop tracking a hand edit | `pixelkiln edit detach --only anvil` |
+| build a sprite sheet | `pixelkiln pack --style base` |
+| place sprites on a sheet at declared cells | `pixelkiln mount --style base` |
+| export a tileset for Tiled or Godot | `pixelkiln export --style ground --format tiled` |
+| check the art against the style's palette and grid | `pixelkiln audit --style base` |
+| produce the palette-clean, grid-true final art | `pixelkiln refine` then `pixelkiln refine approve --from <record> --reviewer "Name"` |
+| claim art already on my provider account | `pixelkiln adopt` |
+| find paid work on the account that no lockfile claims | `pixelkiln salvage` |
+| accept reworded prompts without regenerating | `pixelkiln accept` |
+| drop lock entries the manifest no longer declares | `pixelkiln prune` |
+| check the project before committing or in CI | `pixelkiln doctor`, `pixelkiln plan --check` |
+| see the account balance | `pixelkiln balance` |
+| work across several projects | `pixelkiln workspace add ../other/pixelkiln.manifest.json`, then `--workspace` on `gallery` and `salvage` |
+
+Every command takes `--manifest <file>` when the manifest is not in the
+working directory. Commands that spend take `--budget`; commands that replace
+a file you changed take `--force`.
+
 ## Everyday pipeline
 
 ### `init`
@@ -790,6 +822,23 @@ Print the package version. `-v` is an alias.
 
 ## Exit and output contract
 
+A command that stops on an error prints `error: <message>` to stderr and
+exits with a code that says what kind of error it was, so a script can branch
+without matching message text.
+
+| Exit code | Kind | Example |
+|---|---|---|
+| 1 | anything else | a file the OS would not let PixelKiln write |
+| 2 | usage | an unknown flag, a `--style` that the manifest does not define |
+| 3 | project | no manifest at the path, an invalid manifest, a malformed lockfile or workspace catalog |
+| 4 | provider | the provider rejected a request or answered with something unusable |
+| 5 | refused overwrite | a file on disk differs from its record; nothing was replaced (`--force` overrides) |
+| 6 | budget | the run would spend past `--budget`, or the balance cannot cover it |
+| 7 | capability | the recorded provider does not offer the operation (for example `purge` on a backend with no delete) |
+
+Commands that finish with some items failed, such as `fetch` with one
+download refused, exit 1 after printing their totals.
+
 - Parse, schema, ownership, provider, and filesystem errors exit nonzero.
 - `submit`, `poll`, `fetch`, and `gen` exit nonzero on partial failure or
   timeout; automation cannot mistake an incomplete batch for success.

package/docs/LIBRARY.md

@@ -447,6 +447,38 @@ costs with their unit; use `spendByUnit(lock)` for history. Use
 `measureBalanceChange(before, after)` when the provider exposes authoritative
 balance readings and keep that observed delta distinct from the estimate.
 
+## Errors a caller can branch on
+
+Most failures are plain `Error`s whose message is written for a person. The
+kinds a program might handle differently extend `PixelKilnError` and carry a
+`code`:
+
+| Class | `code` | Thrown by |
+|---|---|---|
+| `UsageError` | `usage` | `parseArgs`, `resolveSpecs` when a filter names an unknown style or asset |
+| `ProjectError` | `project` | `loadManifest`, `loadLock`, `loadWorkspace`, `openProject` |
+| `ProviderError` | `provider` | every built-in client on a failed request; `provider` and `status` say which and what. `PixelLabError` is one with the response `body`. |
+| `OverwriteRefusedError` | `refused-overwrite` | `revertGeneration`, `writeManagedArtifactBundle`, `installRecipe`, `snapshotQualityBaseline`; `files` lists what was left alone |
+| `BudgetError` | `budget` | `submit` and the CLI's balance checks |
+| `UnsupportedCapabilityError` | `capability` | `requireList`, `requireDelete`, `requireBalance` |
+
+`errorCode(err)` returns the code or `undefined`, and `exitCodeFor(err)` the
+exit code the CLI uses (`EXIT_CODES` is the table). A new code is added only
+when some caller would branch on it; a message that is merely different is
+still a plain `Error`.
+
+```ts
+import { errorCode, ProviderError } from "pixelkiln"
+
+try {
+  await submit(provider, project.loaded, plan.actionable, project.lock, project.lockPath)
+} catch (err) {
+  if (err instanceof ProviderError && err.status === 402) console.error("top up", err.provider)
+  else if (errorCode(err) === "budget") console.error("raise the budget or narrow the run")
+  else throw err
+}
+```
+
 ## Stability and file paths
 
 - Public imports come from `pixelkiln`; internal `src/` paths are not part of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,
@@ -33,6 +33,7 @@
     "test:security": "tsx scripts/check-source-url-hygiene.ts",
     "test:quality": "tsx src/cli.ts quality check --from benchmarks/provider-hires/comfyui/pixelkiln.quality-baseline.json",
     "test:package": "node scripts/smoke-package.mjs",
+    "test:gallery": "tsx scripts/smoke-gallery.ts",
     "test:watch": "vitest",
     "schema": "tsx scripts/gen-schema.ts",
     "website:dev": "npm run dev --prefix website",
@@ -65,6 +66,7 @@
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/node": "^22.10.0",
+    "puppeteer-core": "^24.43.1",
     "semantic-release": "^25.0.9",
     "tsup": "^8.5.1",
     "tsx": "^4.19.2",