pixelkiln 0.1.0

package/docs/AGENTS.md

@@ -0,0 +1,64 @@
+# Agent workflows
+
+PixelKiln includes an official agent skill for tools that support the open
+`SKILL.md` format. It teaches the operational decisions that matter: plan before
+spending, cap every paid run, restore before regenerating, keep selection human,
+and preserve provenance through packaging.
+
+## Install the skill
+
+From any project directory:
+
+```bash
+npx skills add gfargo/pixelkiln@pixelkiln
+```
+
+Then ask your agent to use `$pixelkiln` while working with a PixelKiln manifest.
+The skill is provider-neutral and does not contain credentials or make provider
+calls by itself.
+
+## What the skill changes
+
+With the skill loaded, an agent should:
+
+1. Find and validate `pixelkiln.manifest.json`.
+2. Run `doctor --dry-run` and `plan` before paid work.
+3. Report actionable, recoverable, and cost totals in the provider's unit.
+4. Use `restore` instead of regenerating recoverable assets.
+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
+   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
+
+The [official PixelLab MCP server](https://github.com/pixellab-code/pixellab-mcp)
+gives an agent direct PixelLab creation tools. It is complementary to PixelKiln,
+not a replacement:
+
+| Layer | Responsibility |
+|---|---|
+| PixelLab MCP | Agent-facing access to PixelLab generation capabilities. |
+| 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.
+
+## Recommended first prompt
+
+```text
+Use $pixelkiln to inspect this project's manifest, run the free checks and plan,
+then tell me the exact provider-unit budget required before generating anything.
+```
+
+For command details, continue with the [CLI reference](./CLI.md). For recovery
+and account-level operations, read [Recovery and account safety](./RECOVERY.md)
+before making changes.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,120 @@
+# Architecture
+
+PixelKiln separates provider mechanics from the project state machine:
+
+```text
+manifest + lock + planning + review + recovery + artifact pipelines
+──────────────────── Provider interface ─────────────────────────
+PixelLabProvider             FakeProvider             future adapters
+```
+
+Everything above the provider boundary is backend-neutral. URL shapes, auth
+headers, request/response schemas, and optional account capabilities remain in
+the adapter.
+
+## Manifest and resolved specs
+
+The committed manifest is intent. Resolution combines one style and one asset,
+loads/reference-hashes style images, applies overrides, chooses a provider-
+supported generator, and computes a deterministic spec hash. The hash excludes
+project root, output location, and tags but includes every pixel-affecting
+setting.
+
+See [manifest reference](./MANIFEST.md).
+
+## Lockfile
+
+`pixelkiln.lock.json` is the committed paid-work record. Version 2 entries
+retain:
+
+- style/asset identity and spec hash;
+- 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;
+- provider-specific metadata under a provider-id namespace;
+- successful submission cost and cost unit.
+
+Lock keys are `styleId/assetId`. Output paths use manifest-relative `/`
+separators so a clone or moved checkout remains valid. Legacy absolute v2 paths
+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.
+
+## State machine
+
+The provider pipeline is deliberately resumable:
+
+```text
+plan → submit → poll → pick (when needed) → fetch
+                    └──────── structural/inline outputs ────────┘
+```
+
+Remote ids are saved immediately after submission. Generation and download
+failures remain separate, so paid work with a temporary CDN failure is
+recoverable at zero generation cost. Each stage can be rerun independently;
+`gen` is only their everyday orchestration.
+
+Provider responses are runtime-validated before entering lock state. A 2xx
+response with a missing object id, malformed URL set, invalid estimate, or
+changed field type becomes an explicit adapter error rather than corrupted
+durable state.
+
+## Output identity
+
+One manifest asset may produce multiple structural members. Roles such as
+`tile-03` are load-bearing identity, not presentation. Audits, packs, mounts,
+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.
+
+## 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.
+Stale advisory locks are recoverable after their safety window.
+
+## Derived artifact transactions
+
+Pack, mount, and export use a separate managed bundle writer:
+
+1. Recover an interrupted prior transaction.
+2. Validate provenance ownership and manual edits.
+3. Compare every desired member and skip identical bytes.
+4. Write an immutable transaction journal.
+5. Stage all changing members beside their destinations.
+6. Move existing members to unique backups.
+7. Promote every stage.
+8. Write a durable commit marker.
+9. Remove backups, stages, journal, and marker.
+
+Before the marker, recovery restores the old complete set. After the marker,
+recovery keeps the new complete set and finishes cleanup. Journal paths are
+validated against current destinations and reserved same-directory temp names.
+See [derived artifacts](./ARTIFACTS.md).
+
+## Caches
+
+The project content cache is keyed by output SHA-256. The account cache maps
+provider object ids to remote content hashes for adoption/salvage. Neither is
+authoritative or committed; both can be deleted and rebuilt. Every recovery
+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).

package/docs/ARTIFACTS.md

@@ -0,0 +1,162 @@
+# Derived artifacts
+
+PixelKiln turns validated source PNGs into application-ready bundles without a
+provider call:
+
+- `pack`: deterministic grid sheet plus frame atlas;
+- `mount`: declared stable cells in a new or existing sheet;
+- `export`: structural tile atlas plus generic, Tiled, or Godot metadata.
+
+Every CLI bundle includes generated output, metadata, and a
+`<base>.pixelkiln.json` provenance companion.
+
+## Pack
+
+```bash
+pixelkiln pack --style neon
+pixelkiln pack --style ground --output-role tile-00 --output-role tile-01
+pixelkiln pack --style mixed --primary-only
+```
+
+Manifest mode reads exactly the outputs recorded by the lockfile. Frames sort
+by asset id for byte-stable layouts. Structural sets preserve provider order
+and qualify ids by role (`terrain/tile-03`). The grid cell is the largest source
+sprite; smaller frames retain their real dimensions at the cell's top-left.
+
+All standard non-interlaced PNG color modes and bit depths are decoded and
+normalized to RGBA. Corrupt/interlaced inputs are reported as skipped. If no
+input is readable, packing fails rather than emitting an empty sheet.
+
+Explicit mode packs sources from any project and requires no manifest:
+
+```bash
+pixelkiln pack --inputs sprites.json --out dist/sheet
+```
+
+```json
+[
+  { "id": "effect_euphoric", "path": "art/effect_euphoric.png" },
+  { "id": "aura_golden", "path": "../shared/aura_golden.png" }
+]
+```
+
+Paths resolve from the inputs JSON directory. Duplicate ids fail before file
+decoding because consumers must have one unambiguous frame per id.
+
+## Mount
+
+`pack` moves cells when the sorted input set changes. `mount` is for sheets
+whose cell coordinates are already load-bearing in scene files, saved data, or
+engine configuration.
+
+Declare `style.mount` and per-asset `cell` values in the manifest. A base sheet
+is optional and may equal the output. Only declared cells are cleared/replaced;
+all other base pixels survive byte-for-byte. A sprite larger than its cell is
+reported and skipped rather than cropped. Two assets cannot own one cell.
+
+Use asset `source` when mounting a palette-remapped, aligned, hand-touched, or
+otherwise post-processed file instead of the raw lock output. Use `outputRole`
+to choose one member of a structural set. See [manifest reference](./MANIFEST.md).
+
+## Export
+
+```bash
+pixelkiln export --style ground --only terrain --format generic
+pixelkiln export --style ground --only terrain --format tiled
+pixelkiln export --style ground --only terrain --format godot
+```
+
+Generic JSON retains all provider rules and normalized masks. Tiled and Godot
+translate recognized four-edge/four-corner semantics and reject unknown or
+lossy mappings. See [TILES.md](./TILES.md) for the format contracts.
+
+## Provenance companion
+
+The companion is engine-neutral and versioned:
+
+```jsonc
+{
+  "format": "pixelkiln-artifact-bundle",
+  "version": 1,
+  "kind": "pack",
+  "fingerprint": "…",
+  "sources": [
+    { "id": "anvil", "path": "../art/anvil.png", "sha256": "…", "included": true }
+  ],
+  "options": { "columns": 8, "order": "id", "style": "base" },
+  "outputs": [
+    { "path": "sheet.png", "sha256": "…" },
+    { "path": "sheet.json", "sha256": "…" }
+  ]
+}
+```
+
+Source paths are relative to the companion. Options are recursively key-sorted
+before hashing. The fingerprint covers sources, options, and output hashes.
+Manifest-driven bundles conservatively include the project manifest and
+lockfile, so newly declared or recorded sources make an older artifact stale.
+
+Verify without rebuilding:
+
+```ts
+import { verifyArtifactBundle } from "pixelkiln"
+
+const verification = await verifyArtifactBundle("dist/sheet.pixelkiln.json")
+if (!verification.current) {
+  console.error(verification.changedSources, verification.changedOutputs)
+}
+```
+
+## Ownership and manual edits
+
+PixelKiln never silently claims a differing existing destination:
+
+- No companion + identical desired bytes: adopt it, preserve its mtime, and
+  add provenance.
+- No companion + differing bytes: refuse the entire bundle.
+- Valid companion + matching recorded output: update normally.
+- Valid companion + manually changed output: refuse the entire bundle.
+- Invalid or altered companion: refuse takeover.
+
+After reviewing the difference, `--force` explicitly replaces and takes
+ownership of every changing member:
+
+```bash
+pixelkiln pack --style neon --force
+```
+
+Library consumers get the same policy from
+`writeManagedArtifactBundle(..., { force: true })`.
+
+## Transactional writes
+
+Changed members are compared first, staged beside their destinations, and only
+then promoted. Duplicate normalized destinations fail before mutation.
+Byte-identical members are not rewritten. If an ordinary write/promotion error
+occurs, newly promoted files are removed and previous backups are restored.
+Any recovery failure retains the backup and reports its exact path.
+
+## Abrupt termination recovery
+
+Managed writes create an immutable `<companion>.transaction` journal before
+staging. After every member is promoted, a separate durable commit marker is
+created before cleanup.
+
+On the next invocation:
+
+- journal without marker: restore the prior complete bundle and remove stages;
+- journal with marker: retain the fully committed new bundle and finish cleanup;
+- live owning process: refuse concurrent recovery;
+- destination or temp path outside the current bundle: refuse unsafe recovery
+  and retain the journal for inspection.
+
+The journal is short-lived and should not normally appear in Git status. A
+hard-exit integration test covers both sides of the commit boundary.
+
+## Library persistence
+
+`packSprites`, `packStyle`, `mountSprites`, `mountStyle`, and `exportTileset`
+return bytes, metadata, skipped-input details, and source hashes. Use
+`writeManagedArtifactBundle` for the CLI's ownership, provenance, transaction,
+and recovery policy. `writeArtifactBundle` is the lower-level staged/rollback
+primitive for callers that supply their own ownership policy.

package/docs/CLI.md

@@ -0,0 +1,248 @@
+# CLI reference
+
+```text
+pixelkiln <command> [options]
+```
+
+Unknown commands, positional arguments, and flags are errors. Repeated
+`--style`, `--only`, `--claims`, and `--output-role` values accumulate; comma-
+separated values work too. This strict parsing prevents a misspelled filter
+from widening a paid run.
+
+## Everyday pipeline
+
+### `init`
+
+Scaffold a manifest from an existing PNG tree.
+
+```bash
+pixelkiln init --from assets/sprites --exclude characters,gifs --generator map
+```
+
+Prompts are deliberately empty because plausible text is not provenance. Use
+`adopt --write-prompts` to recover exact provider prompts for byte matches.
+
+### `plan`
+
+Diff the resolved manifest against the lockfile and disk without calling a
+provider. It reports current, missing, untracked, stale, failed, recoverable,
+in-flight, and orphaned entries plus estimated cost in the provider's unit.
+
+```bash
+pixelkiln plan
+pixelkiln plan --style neon --only anvil,hammer --json --check
+```
+
+`--check` exits nonzero unless every selected entry is current.
+
+### `doctor`
+
+Validate the manifest, references, lockfile recovery sources, output ownership,
+writability, stale jobs, current plan, API-key configuration, and provider
+connectivity. `--dry-run` skips only live connectivity. Supports `--json` and
+exits nonzero for unsafe state.
+
+### `gen`
+
+Run `submit` → `poll` → `pick` → `fetch`. This is the normal paid workflow.
+Use `--budget` as a hard ceiling and filters to limit scope.
+
+```bash
+pixelkiln gen --style neon --only anvil,hammer --budget 80
+```
+
+### `submit`
+
+Queue selected missing/stale generation work without polling it. Enforces the
+provider spacing and concurrency limits, validates estimates at the spending
+boundary, and saves each remote id immediately.
+
+### `poll`
+
+Advance submitted jobs to completed, failed, or selection-ready states. It can
+be rerun safely after an interrupted session.
+
+### `pick`
+
+Open the local candidate-review UI for jobs with alternatives. Arrow keys
+navigate, Enter selects, 1–9 choose directly, and 0 leaves a row unresolved.
+Only rows submitted with **Apply selections** are written to the lockfile;
+unchosen rows remain ready for later review, and closing the window applies
+nothing. See the [Getting started guide](GETTING_STARTED.md#start-a-new-project)
+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.
+
+### `restore`
+
+Repair missing generated files without buying new generations. It prefers
+validated local content-addressed cache bytes and otherwise reuses provider
+URLs. It never replaces a destination whose bytes disagree with the lock.
+
+## Reconciliation and lifecycle
+
+### `adopt`
+
+Match local files to existing provider objects by SHA-256. `--write-prompts`
+copies recovered prompts into the manifest; `--tag` pushes project tags. Local
+retouches remain untracked rather than being regenerated or overwritten.
+
+### `accept`
+
+Re-baseline intact existing art after prompt/style prose changes. Artwork bytes
+do not change; only the recorded spec hash moves. Missing or modified output is
+not accepted.
+
+### `salvage`
+
+Review remote objects no supplied lockfile claims. On shared accounts, pass
+every other project lock via repeatable `--claims`; sibling manifests are used
+to exclude objects matching another project's styles. `--dry-run --json`
+provides a scriptable inventory. Import, keep, and discard are review decisions;
+discard only tags an object.
+
+### `purge`
+
+Delete provider objects previously tagged `pixelkiln:discard`. It is separate
+from salvage, lists targets, asks for confirmation, and refuses non-interactive
+deletion without `--yes`. Use `--dry-run` first.
+
+### `prune`
+
+Remove lock entries no style/asset pair in the manifest resolves to. These
+accumulate when an asset is renamed or moved between styles: the old entry keeps
+claiming the output path the new one now owns, which is what `doctor` reports as
+`lock-outputs`.
+
+Offline. It lists what it would remove, asks for confirmation, and refuses
+non-interactive removal without `--yes`. Use `--dry-run` first. The artwork on
+disk is untouched and nothing is deleted from the provider account, but the
+pruned entries' provenance is gone, so those objects read as unclaimed the next
+time you run `salvage`.
+
+`--style` and `--only` are rejected: prune compares the lockfile against the
+whole manifest, so a filter would make every entry it excluded look undeclared.
+
+### `tag`
+
+Push current manifest tags to tracked provider objects. This does not generate
+or download artwork.
+
+### `balance`
+
+Show the provider's remaining balance and cost unit.
+
+### `status`
+
+Summarize lock entries by state and successful submission spend by cost unit.
+Supports `--json`; unlike units are never added together.
+
+## Local quality and derived output
+
+### `audit`
+
+Measure palette distance, transparent canvas share, and opaque color count for
+every selected output. Structural sets are evaluated member-by-member.
+
+```bash
+pixelkiln audit --style neon --json --check \
+  --max-distance 35 --min-transparency 0.1 --max-colors 128 --sigma 1.5
+```
+
+### `cache`
+
+Inspect the local content cache and account object-hash cache. `--check` exits
+nonzero for unsafe state. `--prune` removes malformed, corrupt, partial, and
+unreferenced cache data; it does not delete provider objects.
+
+### `pack`
+
+Build a deterministic RGBA sprite sheet, JSON atlas, and `.pixelkiln.json`
+provenance companion. Manifest mode reads lock outputs. Explicit-input mode
+needs no manifest:
+
+```bash
+pixelkiln pack --style neon --columns 8
+pixelkiln pack --inputs sprites.json --out dist/sheet
+```
+
+Use repeatable `--output-role` for structural members or `--primary-only` for
+unambiguous single outputs. These modes are mutually exclusive.
+
+### `mount`
+
+Write sprites into manifest-declared cells, optionally over an existing base
+sheet. Undeclared cells survive byte-for-byte; each declared cell is cleared
+before its sprite is placed.
+
+### `export`
+
+Build a structural tile atlas plus generic JSON, Tiled TSJ, or Godot TRES
+metadata and a provenance companion.
+
+```bash
+pixelkiln export --style ground --only terrain --format tiled --columns 8
+```
+
+See [derived artifacts](./ARTIFACTS.md) and [tiles](./TILES.md).
+
+## Utility commands
+
+### `help`
+
+Print the built-in command and option summary. `--help` and `-h` are aliases.
+
+### `--version`
+
+Print the package version. `-v` is an alias.
+
+## Options
+
+| Option | Applies to | Meaning |
+|---|---|---|
+| `--manifest <path>` | manifest commands | Manifest path; defaults to `pixelkiln.manifest.json`. |
+| `--lock <path>` | manifest commands | Lock path; defaults beside the manifest. |
+| `--style a,b` | most workflows | Restrict styles; repeatable. |
+| `--only id1,id2` | most workflows | Restrict asset ids; repeatable. |
+| `--budget <n>` | submit/gen | Refuse work above this provider-unit cost. |
+| `--force` | gen/derived commands | Regenerate current work or explicitly take ownership of modified/unowned derived output. |
+| `--dry-run` | supported mutating commands | Inspect without spending or mutating provider state. |
+| `--json` | plan/doctor/audit/cache/status/salvage | Machine-readable stdout where supported. |
+| `--check` | plan/audit/cache | Exit nonzero when selected state is unsafe. |
+| `--yes`, `-y` | confirmed operations | Skip an interactive confirmation. |
+| `--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. |
+| `--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. |
+| `--generator <name>` | init | Generator assigned to the scaffolded style. |
+| `--name <name>` | init | Project name for the scaffolded manifest. |
+| `--write-prompts` | adopt | Recover provider prompts into the manifest. |
+| `--port <n>` | pick/salvage | Local review server port; otherwise chooses a free port. |
+| `--out <path>` | pack/export | Output base override. Export requires one selected tileset. |
+| `--inputs <path>` | pack | JSON array of `{ id, path }`; requires `--out`. |
+| `--columns <n>` | pack/export | Grid columns, 1–1024; default is near-square. |
+| `--format <name>` | export | `generic` (default), `tiled`, or `godot`. |
+| `--output-role <role>` | pack | Include named structural roles; repeatable. |
+| `--primary-only` | pack | Include only unambiguous primary/single outputs. |
+| `--max-distance <n>` | audit | Absolute palette-distance ceiling. |
+| `--min-transparency <0..1>` | audit | Minimum transparent canvas share. |
+| `--max-colors <n>` | audit | Maximum distinct opaque colors. |
+| `--sigma <n>` | audit | Relative outlier cutoff; defaults to 1.5. |
+| `--prune` | cache | Remove invalid and unreferenced cache data. |
+
+## Exit and output contract
+
+- 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.
+- Human progress goes to stderr when `salvage --dry-run --json` reserves stdout
+  for JSON.
+- `plan --check`, `audit --check`, and `cache --check` are intended as CI gates.
+- Commands that can spend or delete expose their scope before doing so; budget
+  and confirmation are separate protections.