pixelkiln 0.31.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,

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.31.0",
+  "version": "0.32.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,