pixelkiln 0.30.0 → 0.32.0

package/docs/CLI.md

@@ -142,7 +142,10 @@ provider result should take ownership. `gen --force` applies the same rule.
 
 Repair missing generated files without buying new generations. It prefers
 validated local content-addressed cache bytes and otherwise reuses provider
-references. It never replaces a destination whose bytes disagree with the lock.
+references. It never replaces a destination whose bytes disagree with the lock
+unless `--force` says to: `restore --force` puts the recorded bytes back over
+a file that was changed after download (an `orphaned` plan entry), discarding
+that change — copy it aside, or declare it with [`edit`](#edit), first.
 
 The paid-work states have one safe next step:
 
@@ -344,6 +347,13 @@ pixelkiln gallery --edit
 pixelkiln gallery --edit --workspace pixelkiln.workspace.json
 ```
 
+An `orphaned` record — its file gone, or changed after download — offers
+**Restore** (the recorded bytes back from the cache or the provider, no cost)
+and, for a changed file, **Regenerate**; both replacements say what they
+discard and ask first, and the way to keep the change is **Edit by hand** or
+**Edit in browser**, which copies it beside the record. An `untracked` file
+can be replaced by a generation the same way.
+
 `--budget <n|provider=n>` enables generation from the page under that session
 ceiling. It is the same `--budget` `gen` takes: one unkeyed amount when a run
 involves a single provider, or one keyed amount per provider for a mixed run,
@@ -405,10 +415,13 @@ that click or `tools install editor`. **Save to project** (or ⌘S / Ctrl+S in
 the editor) hands the flattened image back to the page, which writes the same
 `edits/` file `pixelkiln edit` would and declares it; the sheet stays open for
 the next change, **Save & close** does both, and closing with unsaved changes
-asks first. A set opens as one Pixelorama project with a frame per member —
-an animation at its fps, a tile set as one frame per tile — and saving writes
-every member back under its role; a set that comes back with a different
-number of frames is refused rather than guessed at. A browser save also keeps Pixelorama's layered `.pxo`
+asks first. Opening an existing edit also lays the generated art on a locked
+**Generated (PixelKiln reference)** layer at 50% — an onion skin for seeing
+what changed — that the sheet's **show generated** box hides and shows and
+that a save never flattens in. A set opens as one Pixelorama project with a
+frame per member — an animation at its fps, a tile set as one frame per tile —
+and saving writes every member back under its role; a set that comes back with
+a different number of frames is refused rather than guessed at. A browser save also keeps Pixelorama's layered `.pxo`
 beside the edit — the next **Edit in browser** hands it back, so layers and
 frames come back as they were (the flattened PNG is used only if the file
 cannot be read, and the sheet says which) — and writes `<edit>.edit.json`

package/docs/GETTING_STARTED.md

@@ -196,7 +196,8 @@ With `gallery --edit`, a record's **Hand edit** section offers the same
 [Pixelorama](https://pixelorama.org) build the gallery serves itself, opened
 in a sheet with the sprite and the style's palette loaded. Save writes the edit
 back, keeps the layered `.pxo` beside it for the next time, and records which
-generation it was based on. A ComfyUI frame set or a PixelLab tile set opens as
+generation it was based on; reopening the edit shows the generated art through
+it at 50% on a locked reference layer, so what changed is always in view. A ComfyUI frame set or a PixelLab tile set opens as
 one project with a frame per member and saves every member back. The 46 MB
 editor is fetched once per PixelKiln release into a user cache, on the first
 click or with `tools install editor`; see [`tools`](CLI.md#tools).

package/docs/RECOVERY.md

@@ -13,7 +13,9 @@ pixelkiln restore --style neon --only anvil
 
 `restore` repairs a missing lock output from validated content-cache bytes or a
 durable provider reference. It does not submit generation and refuses to
-replace a file whose current bytes differ from the recorded hash.
+replace a file whose current bytes differ from the recorded hash; `--force`
+overrides that for a file changed after download, and the gallery's
+**Restore** button on an `orphaned` record does the same after asking.
 
 Generation and download failures are separate lock states. A CDN failure after
 successful generation becomes `download-failed`; the next `fetch` or `restore`

package/package.json

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