Recovery and account safety

PixelKiln separates local file recovery, account reconciliation, unclaimed-work review, and irreversible deletion. A failed download never needs to become a new paid generation, and salvage never deletes by implication.

Restore missing output

pixelkiln restore
pixelkiln restore --style neon --only anvil

restore repairs a missing lock output from validated content-cache bytes or the provider URL. It does not submit generation and refuses to replace a file whose current bytes differ from the recorded hash.

Generation and download failures are separate lock states. A CDN failure after successful generation becomes download-failed; the next fetch or restore retries at zero generation cost.

Local caches

Two ignored caches accelerate recovery:

• .pixelkiln/cache/<sha256>.png or <sha256>.gif: content-addressed, structurally validated generated media bytes;
• pixelkiln.cache.json: provider object id → remote image hash.

pixelkiln cache
pixelkiln cache --check
pixelkiln cache --prune

Cache checks verify filenames/hashes and fully decode PNG chunks, checksums, palettes, scanlines, and decompressed size. Pruning removes corrupt/partial and unreferenced content plus malformed object-hash entries. Caches are disposable and should not be committed.

Adopt existing art

pixelkiln init --from assets/sprites --generator map
pixelkiln adopt --write-prompts

adopt hashes local files and provider objects, then maps exact matches into the lockfile. --write-prompts recovers the real upstream prompts. Retouched files remain untracked: provenance is unknown, but the art is not overwritten or automatically scheduled for paid regeneration.

The account object-hash cache avoids repeated full downloads. It is pruned for deleted remote ids only after adopt has seen the provider's complete object list.

Salvage unclaimed work

An account can contain paid objects that no current project lockfile claims. Inventory them before generating replacements:

pixelkiln salvage --claims ../other-project/pixelkiln.lock.json --dry-run
pixelkiln salvage --claims ../other-project/pixelkiln.lock.json

On shared accounts, supply every other project lockfile with repeatable --claims. Missing claim files are errors. PixelKiln loads sibling manifests where available to recognize another project's style patterns; incomplete claims could otherwise make shipped art look unowned.

Multi-style manifests group matching objects into one review session per style. Unmatched objects are listed separately. --style deliberately overrides grouping when a human wants to force one destination.

Review verdicts:

Verdict	Effect
import	Download, add a manifest asset and lock entry, and recover its prompt.
keep	Add pixelkiln:keep upstream; no local change.
discard	Add pixelkiln:discard; does not delete.

--dry-run --all lists the full inventory. --dry-run --json writes the JSON 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:

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. This is 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 because the project 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:

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. This helps 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:

pixelkiln purge --dry-run
pixelkiln purge
pixelkiln purge --yes

Only objects already tagged pixelkiln:discard are eligible. The command lists targets, asks interactively, and refuses non-interactive deletion without --yes. A shared account should be fully adopted/salvaged before purge.

Accept intentional spec prose changes

pixelkiln accept --style base --only anvil

accept re-baselines an intact output against the current spec hash when prose changed but the existing pixels are intentionally retained. It does not modify art and skips missing or hash-mismatched files.

Derived output recovery

Pack, mount, and export bundles have a separate ownership and crash-recovery system based on .pixelkiln.json companions and transaction journals. See derived artifacts.

What to commit

Commit manifests, lockfiles, generated art, derived output used by the application, and its .pixelkiln.json companions. Do not commit credentials, .pixelkiln/, pixelkiln.cache.json, or short-lived transaction/stage/backup files.