pixelkiln 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+Thanks for improving pixelkiln. The project is deliberately conservative around
+paid generation, file ownership, and provider state: a convenient failure must
+never widen a paid run, overwrite hand-edited art, or lose the identity of work
+that already cost money.
+
+## Development setup
+
+Requires Node.js 20 or newer.
+
+```bash
+npm ci
+npm run typecheck
+npm run test:docs
+npm test
+npm run build
+npm run test:package
+```
+
+The Next.js marketing/documentation site is isolated in `website/`:
+
+```bash
+npm ci --prefix website
+npm run website:check
+npm run website:lint
+npm run website:build
+npm run website:dev
+```
+
+The site reads canonical Markdown from `docs/` and the root policy files at
+build time. Do not create a second documentation copy under `website/`.
+
+Website sprites are generated from `website/art/pixelkiln.manifest.json`.
+Treat those requests as paid work: run `plan` and `audit` first, use an explicit
+hard budget, and commit the manifest, lockfile, and reviewed outputs together.
+The Review UI showcase should be captured at 1280×720 only after every asset
+loads. Give a replacement capture a new public filename and update the page
+reference so deployed image caches cannot retain the old version.
+
+Run the source CLI without a global install:
+
+```bash
+npm run pixelkiln -- help
+npm run pixelkiln -- plan --manifest examples/minimal/pixelkiln.manifest.json
+```
+
+Tests must not require a live provider account or API key. Use `FakeProvider`
+for pipeline behavior and mocked HTTP responses for PixelLab wire contracts.
+
+## Change guidelines
+
+- 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.
+- 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
+  behavior.
+- Keep README as the concise product landing page. Put durable reference and
+  workflow detail in `docs/`, and link every guide from `docs/README.md`.
+- Run `npm run test:docs` after changing Markdown or the CLI command/flag
+  surface. It checks local links, the docs index, README size, and CLI coverage.
+- Run the website lint and build checks when changing `website/` or the
+  canonical Markdown it renders.
+- Run the package smoke test when changing exports, build configuration, the
+  executable, package metadata, or the `files` allowlist.
+
+## Architectural boundaries
+
+- Provider-specific URLs, authentication, response schemas, and quirks belong
+  below `Provider`.
+- Planning stays offline. Provider `supports()` and `estimate()` must perform no
+  I/O and estimates must carry their cost unit.
+- Provider responses are untrusted input and need runtime validation before
+  entering the lockfile.
+- Lockfile writes must remain atomic and resumable. Additive defaults should
+  preserve valid v2 files when extending lock entries.
+- Unknown flags and ambiguous output selection are errors. Silent widening is
+  especially dangerous when a command can spend provider quota.
+- Never overwrite a generated file whose current bytes differ from its recorded
+  hash, and never make deletion an implicit side effect of recovery/triage.
+
+## Pull requests
+
+Describe the user-visible outcome, any compatibility impact, and the exact
+checks run. Keep generated `dist/` files out of commits; packaging builds them
+from source. If hosted CI is unavailable, include the local Node version and
+full check results in the PR description.
+
+Security-sensitive findings should follow [SECURITY.md](./SECURITY.md), not a
+public issue with exploit details.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gfargo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NAMING.md

@@ -0,0 +1,87 @@
+# Naming — resolved: `pixelkiln`
+
+**The name is settled.** The project ships as `pixelkiln`. `package.json` is
+no longer `private`.
+
+## The original blocker was a factual error
+
+The prior version of this file claimed `pixelkiln` "is an established npm
+package (v3.5.1, the CSS spritesheet builder) and `pixelsmith` is its
+engine," and blocked the name on that basis. Re-verified directly against
+the npm registry (2026-08-18):
+
+```
+GET https://registry.npmjs.org/pixelkiln    → 404 "Not found"
+GET https://registry.npmjs.org/spritesmith  → 200, latest 3.5.1, "Utility that
+                                                takes images and creates a
+                                                spritesheet with JSON sprite data"
+GET https://registry.npmjs.org/pixelsmith   → 200, latest 2.6.0, "Node based
+                                                engine for spritesmith"
+```
+
+`pixelkiln` was never published. The "v3.5.1 CSS spritesheet builder" is
+**`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.)
+
+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
+done.
+
+## What the space already looks like
+
+The "manifest-driven AI asset generation CLI" idea is not novel. Prior art found:
+
+| Project | Overlap | Backend |
+|---|---|---|
+| [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 |
+| [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.
+
+## What is actually differentiated here
+
+Worth knowing, because the name should point at it:
+
+1. **PixelLab-native.** Everything above wraps a general image model and
+   downscales. PixelLab generates on a real pixel grid. Nothing found targets it.
+2. **Exploits the candidate economics.** Cost is fixed per call while candidates
+   returned scale inversely with canvas size. Nothing found treats "generate
+   small, pick from 16" as the core loop.
+3. **`adopt`.** Retroactively reconciling an existing account and repo by image
+   hash. Not found anywhere.
+4. **A true lockfile.** `sprite-foundry` uses SQLite, `ralphy` uses a pointer
+   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)
+
+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
+2026-08-18 per the resolution above).
+
+| 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. |
+| 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
+Resolution), `spritemill`, `pixelloom`, `bitforge`, `spritelab`.

package/PROVIDERS.md

@@ -0,0 +1,96 @@
+# Multi-provider — status and notes
+
+**The seam is built.** `src/provider.ts` defines the interface;
+`src/providers/pixellab.ts` is the reference implementation and
+`src/providers/fake.ts` is the in-memory test double. Nothing above the
+interface knows about PixelLab.
+
+That is an architectural guarantee, not a compatibility claim: PixelLab is the
+only production adapter and the only backend exercised against a live account
+today. `FakeProvider` verifies the contract without network access. Until a
+second production adapter ships, describe PixelKiln as **provider-neutral by
+design and proven with PixelLab**, not as already multi-provider.
+
+Both concerns this file previously flagged as blockers are resolved:
+
+- **Cost is no longer assumed to be "generations."** `CostEstimate` carries a
+  `unit` of `generations | usd | free`, `plan` prints it, and `--budget` is
+  interpreted in it. `resolveSpecs(..., { provider })` asks the adapter for its
+  offline estimate, submission validates it again, and lock/status accounting
+  keeps fractional values separated by unit.
+- **Free multi-candidate returns are no longer assumed universal.**
+  `estimate().candidates` is a provider property; `candidateCount()` moved
+  behind the interface.
+
+What remains is writing a second adapter. This file records which one and why.
+
+## Midjourney is the wrong first target
+
+Verified 2026-07-29: **Midjourney has no public developer API.** API keys are
+restricted to the Enterprise dashboard and require applying for access. Every
+third-party "Midjourney API" works by automating the Discord or web interface,
+which violates Midjourney's terms of service and risks the underlying account
+being banned.
+
+Building that adapter would mean shipping something fragile, unsupported, and
+capable of getting a user's account terminated. Not worth it.
+
+## The right first target: Retro Diffusion
+
+[Retro Diffusion](https://retrodiffusion.ai/) is PixelLab's closest competitor
+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.
+- Supports seamless tiles, sprite-sheet animation, and free cost estimates,
+  which map onto `plan` almost directly.
+
+Other candidates, in rough order of fit:
+
+| Provider | API | Pixel-native | Notes |
+|---|---|---|---|
+| Retro Diffusion | yes | yes | Recommended first adapter |
+| [Scenario](https://www.scenario.com/) | yes | partly | Game-asset focused, hosts Retro Diffusion models |
+| OpenAI `gpt-image-1` | yes | no | Raster; needs downscale + palette quantization |
+| Google Gemini image | yes | no | Same caveat |
+| Local ComfyUI + pixel LoRA | n/a | yes | No per-call cost, but a GPU dependency |
+| Midjourney | **no** | no | See above |
+
+## Resolved: the two economic assumptions
+
+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.
+
+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
+   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.
+
+See `src/provider.ts` for the shipped interface. Lock entries carry a
+`provider` field plus `costUnit`, defaulted to `pixellab` and `generations` so
+pre-provider/pre-unit v2 lockfiles stay readable. The CLI reports both the
+successful-submission estimate and the provider balance delta observed across
+the run; those are deliberately separate because provider balances may settle
+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:
+breaking the output hashes, the budget check, or the v1 lock rejection each
+fails tests.
+
+The contact-sheet request paths are covered through the picker and salvage
+integration tests as well as their HTML unit tests.

package/README.md

@@ -0,0 +1,333 @@
+# pixelkiln
+
+![PixelKiln](https://wp.griffen.codes/wp-content/uploads/2026/08/download.png)
+
+[Website](https://pixelkiln.griffen.codes) ·
+[Documentation](https://pixelkiln.griffen.codes/docs) ·
+[GitHub](https://github.com/gfargo/pixelkiln)
+
+Manifest-driven pixel-art generation, review, recovery, quality control, and
+game-ready asset packaging.
+
+PixelKiln treats generated art like a build pipeline: declare assets once,
+preview cost and drift, generate only the missing work, review candidates in a
+local contact sheet, and commit exact provenance beside the files. No LLM is in
+the orchestration loop; provider calls, polling, hashing, downloads, and filing
+are deterministic software mechanics.
+
+The orchestration layer is provider-neutral by design. PixelLab is currently
+the only production adapter and the only live-tested generation backend;
+`FakeProvider` exercises the same contract deterministically in tests. A second
+production adapter is roadmap work, not current compatibility.
+
+> **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.
+
+## Why PixelKiln
+
+A typical image-generation account becomes two unrelated piles: remote objects
+that cost money and local files with no durable explanation of where they came
+from. Handwritten prompts drift, failed downloads look like failed generations,
+and regenerating a whole set is easier than determining what is actually stale.
+
+PixelKiln supplies the missing project model:
+
+- a committed manifest defines assets, styles, generators, budgets, and output;
+- a committed lockfile maps each style/asset to paid provider work and exact
+  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;
+- content-addressed recovery prevents a transient URL failure from buying the
+  same image twice;
+- derived artifact bundles retain source provenance and recover across ordinary
+  write failures or abrupt process termination.
+
+## Capabilities
+
+| Workflow | What PixelKiln provides |
+|---|---|
+| Plan and budget | Offline manifest/lock/disk diff, provider-unit estimates, hard `--budget` ceiling, JSON/CI gate. |
+| 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. |
+| 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. |
+| Artifact integrity | Portable source/output hashes, canonical fingerprints, manual-edit protection, transactional promotion, crash journal recovery. |
+| Library/extension | Public TypeScript primitives, provider capability interface, and deterministic `FakeProvider`. |
+
+### Human review, kept local
+
+`pixelkiln pick` opens an actual local candidate sheet; the orchestration layer
+never asks a model to choose artwork for you.
+
+![PixelKiln candidate review UI](./website/public/review-ui-showcase.jpg)
+
+Use Left/Right to inspect alternatives, Enter or 1–9 to select, and 0 to leave
+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
+
+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 run pixelkiln -- …` executes the TypeScript source. `npm run build`
+creates the ESM, CommonJS, declarations, and CLI distribution used by the
+published package.
+
+## Five-minute start
+
+Copy the minimal example into a project and edit its output path and prompts:
+
+```bash
+cp examples/minimal/pixelkiln.manifest.json ../my-game/pixelkiln.manifest.json
+cd ../my-game
+```
+
+Put the provider credential in `.env.local` beside the manifest:
+
+```dotenv
+PIXELLAB_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
+```
+
+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
+derived artifact companions. Do not commit credentials or `.pixelkiln/`.
+
+For an existing art tree:
+
+```bash
+pixelkiln init --from assets/sprites --exclude characters,gifs --generator map
+pixelkiln adopt --write-prompts
+pixelkiln plan
+```
+
+See [Getting started](./docs/GETTING_STARTED.md) for new and existing projects.
+
+## Agent skill
+
+Install the official PixelKiln skill so Codex, Claude Code, Cursor, and other
+compatible agents know the safe plan → budget → generate → review → recover
+workflow:
+
+```bash
+npx skills add gfargo/pixelkiln@pixelkiln
+```
+
+The skill guides an agent around PixelKiln; it does not replace a generation
+provider. PixelLab's MCP server is a complementary direct-generation surface,
+while PixelKiln remains the project state, budget, provenance, review, and
+packaging layer.
+
+## Manifest
+
+```jsonc
+{
+  "$schema": "./node_modules/pixelkiln/schema/manifest.schema.json",
+  "name": "my-game",
+  "styles": {
+    "base": {
+      "generator": "map",
+      "promptPrefix": "Pixel-art game prop: ",
+      "promptSuffix": ", isolated, transparent background",
+      "outDir": "assets/generated/base",
+      "tags": ["my-game"]
+    }
+  },
+  "assets": {
+    "anvil": { "prompt": "a compact blacksmith anvil" },
+    "hammer": { "prompt": "a worn forging hammer" }
+  }
+}
+```
+
+Styles are namespaces. Adding a second style re-derives the same asset ids into
+a separate output directory and separate lock keys without clobbering the first
+set. Generator choice, reference-image bytes, dimensions, palette, seed, and
+prompt settings participate in deterministic spec identity.
+
+The schema rejects unknown fields and invalid generator combinations before
+planning. See the [Manifest reference](./docs/MANIFEST.md).
+
+## Everyday workflow
+
+```bash
+# Free: validate and inspect drift, recovery, and estimated spend.
+pixelkiln doctor --dry-run
+pixelkiln plan
+
+# Generate only an intended slice with a provider-unit ceiling.
+pixelkiln gen --style base --only anvil,hammer --budget 80
+
+# Repair paid output without regenerating.
+pixelkiln restore
+
+# Optional local gates.
+pixelkiln audit --check --max-distance 35 --min-transparency 0.1
+pixelkiln cache --check
+```
+
+Repeated `--style`, `--only`, `--claims`, and `--output-role` filters
+accumulate; comma-separated values also work. Unknown flags are hard errors, so
+a typo cannot silently widen paid work.
+
+## Choose the right generator
+
+Measured PixelLab economics vary by 40×:
+
+| Need | Generator | Measured cost |
+|---|---|---:|
+| Standalone arbitrary-size prop/icon | `map` (default) | 1 generation |
+| Exact closed palette | `pixflux` | 1 generation |
+| Candidate variety/reference anchoring/future animation | `1dir` | 20–40 generations |
+| Independent or connectable ground tiles | `tiles` | 20–40 generations |
+
+Start with the required capability, not the most expensive endpoint. Forty
+`map` re-rolls cost the same as one 64×64 `1dir` call; conversely, `map` cannot
+replace a hard palette or reference-image constraint. See
+[Generator selection](./docs/GENERATORS.md) and the
+[measured endpoint reference](./docs/ENDPOINTS.md).
+
+## Derived artifacts
+
+```bash
+# Deterministic sheet + atlas + provenance.
+pixelkiln pack --style base
+
+# Stable declared cells in an existing sheet.
+pixelkiln mount --style ground
+
+# Structural atlas + engine metadata + provenance.
+pixelkiln export --style ground --only terrain --format tiled
+```
+
+Pack, mount, and export write managed bundles. A `.pixelkiln.json` companion
+records portable source paths/hashes, layout/export options, output hashes, and
+a canonical fingerprint. Existing unowned output is adopted only when already
+byte-identical; manual edits stop the whole write unless `--force` explicitly
+takes ownership.
+
+All changing members stage before promotion. Ordinary failures roll back.
+Abrupt termination leaves a validated transaction journal: the next invocation
+restores an incomplete old bundle or finishes cleanup for a committed new one.
+See [Derived artifacts](./docs/ARTIFACTS.md) and
+[Tiles and engine exports](./docs/TILES.md).
+
+## Recovery and shared accounts
+
+```bash
+# Reconcile existing files with account objects.
+pixelkiln adopt --write-prompts
+
+# Review paid account objects no known project claims.
+pixelkiln salvage --claims ../other-game/pixelkiln.lock.json --dry-run
+pixelkiln salvage --claims ../other-game/pixelkiln.lock.json
+
+# Deletion is deliberately separate and confirmed.
+pixelkiln purge --dry-run
+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).
+
+## Automation
+
+```bash
+pixelkiln doctor --dry-run --json
+pixelkiln plan --json --check
+pixelkiln audit --json --check --max-distance 35 --max-colors 128
+pixelkiln cache --check
+```
+
+Pipeline stages exit nonzero after partial failures or timeouts. JSON modes
+separate machine output from human diagnostics where necessary. Generation
+should remain an explicit budgeted action; CI should prove committed state and
+artifacts agree rather than regenerate them. See
+[Quality and automation gates](./docs/QUALITY.md).
+
+## TypeScript library
+
+```ts
+import {
+  buildPlan,
+  loadLock,
+  loadManifest,
+  PixelLabProvider,
+  resolveSpecs,
+} from "pixelkiln"
+
+const loaded = await loadManifest("pixelkiln.manifest.json")
+const provider = PixelLabProvider.forOffline()
+const specs = await resolveSpecs(loaded, { provider })
+const plan = await buildPlan(specs, await loadLock("pixelkiln.lock.json"))
+
+console.log(plan.cost, plan.costUnit, plan.actionable.length)
+```
+
+The package also exports audit gates, lock/output helpers, provider contracts,
+pipeline stages, sprite packing/mounting, tile exporters, managed artifact
+writes, and offline provenance verification. See [Library API](./docs/LIBRARY.md).
+
+## Documentation
+
+| Guide | Covers |
+|---|---|
+| [Documentation index](./docs/README.md) | All user, workflow, reference, and architecture guides. |
+| [Getting started](./docs/GETTING_STARTED.md) | First project, existing-art onboarding, everyday workflow, and what to commit. |
+| [CLI reference](./docs/CLI.md) | Every command, flag, JSON mode, and exit contract. |
+| [Manifest reference](./docs/MANIFEST.md) | Every style/asset field and generator constraint. |
+| [Agent workflows](./docs/AGENTS.md) | Official skill install, operating model, and PixelLab MCP pairing. |
+| [Generators](./docs/GENERATORS.md) | Capability choice, measured costs, palettes, style references, and tiles. |
+| [Derived artifacts](./docs/ARTIFACTS.md) | Pack, mount, export, provenance, ownership, transactions, and recovery. |
+| [Recovery](./docs/RECOVERY.md) | Restore, caches, adopt, salvage, claims, and purge safety. |
+| [Quality gates](./docs/QUALITY.md) | Plan, doctor, audit, cache, JSON, and CI. |
+| [Architecture](./docs/ARCHITECTURE.md) | State model, lockfile, providers, concurrency, and output identity. |
+| [Library API](./docs/LIBRARY.md) | Public TypeScript contracts and examples. |
+| [Tiles](./docs/TILES.md) | Structural outputs and generic/Tiled/Godot formats. |
+| [Endpoint research](./docs/ENDPOINTS.md) | Measured PixelLab API behavior and recipes. |
+
+The [public documentation site](https://pixelkiln.griffen.codes/docs) is built by
+the application in [`website/`](./website/README.md). It reads these Markdown
+files directly at build time, so the website and published package share one
+documentation source.
+
+Project policies: [Contributing](./CONTRIBUTING.md),
+[Security](./SECURITY.md), and [provider notes](./PROVIDERS.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.
+
+## License
+
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,38 @@
+# Security policy
+
+## Supported versions
+
+Until the first npm release, security fixes are applied to `main`. After
+publication, the latest released line and `main` are supported; older versions
+may be asked to upgrade before a fix is backported.
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability report for this repository when it is
+available under the **Security** tab. If that option is unavailable, open a
+minimal issue asking for a private contact channel and do not include exploit
+steps, credentials, private URLs, or affected user data in the issue.
+
+Useful reports include:
+
+- the affected version or commit;
+- the smallest safe reproduction;
+- expected and observed behavior;
+- impact and whether provider quota, local files, credentials, or account
+  objects are at risk;
+- suggested mitigation, if known.
+
+Please allow the maintainer time to reproduce and coordinate a fix before
+public disclosure. Credit and disclosure timing will be coordinated with the
+reporter.
+
+## Sensitive areas
+
+Pixelkiln handles provider credentials, paid API actions, remote object deletion,
+local output paths, a localhost review server, and generated HTML containing
+provider data. Reports involving authentication leakage, path traversal,
+cross-origin review actions, HTML/script injection, unsafe overwrite/delete
+behavior, lockfile corruption, or budget bypass are security relevant.
+
+Never attach a real `PIXELLAB_API_KEY`, `.env` file, private provider URL, or
+unredacted lockfile from a confidential project to a public report.

package/bin/pixelkiln.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js"