pixelkiln 0.24.0 → 0.26.0

package/docs/CLI.md

@@ -123,6 +123,16 @@ write the manifest-authoritative destinations, populate the content cache, and
 update output hashes. `--tag` also pushes manifest tags after successful
 downloads when the provider supports tagging.
 
+`fetch --refresh` re-downloads already-downloaded outputs from their durable
+provider reference and replaces the local file only when the object's bytes
+changed upstream — after editing it in the provider's own editor, for
+example. Unchanged objects are reported as such and left alone; a changed
+object replaces the local file only if that file still hashes to what
+PixelKiln wrote, so a local hand edit is never overwritten without `--force`.
+The lockfile then records the new bytes as this generation. Objects with no
+durable reference (PixelLab pixflux images, for one) are not eligible; use
+`pixelkiln edit` for those.
+
 After a stale spec is deliberately regenerated, `fetch` replaces the prior file
 only if its hash still proves PixelKiln wrote it. A changed or untracked
 destination is refused; inspect it, then pass `fetch --force` only when the new
@@ -348,6 +358,13 @@ based on an older generation because the art was regenerated since — plus
 **Open in editor** and **Detach edit**. A card whose edit differs from the
 generated art shows the edit, since that is what ships, with a ✎ mark.
 
+A PixelLab `map` or `1dir` record also links to its account object (**Open in
+pixellab ↗**), where PixelLab's own editor can change it; with `--budget`
+(any amount — `--budget 0` allows provider contact and no spend) the record
+and its style header offer **Pull upstream changes**, the page's form of
+`fetch --refresh`, which re-downloads the object and replaces the local file
+only if it changed upstream.
+
 ```bash
 pixelkiln gallery --edit --budget 80
 pixelkiln gallery --budget pixellab=40 --budget retrodiffusion=1.25 --workspace pixelkiln.workspace.json
@@ -621,6 +638,7 @@ Print the package version. `-v` is an alias.
 | `--no-open` | pick/salvage/gallery/edit | Do not automatically open the browser, or the editor for `edit`. |
 | `--edit` | gallery | Let the page change asset prompts, sizes, category, and tags, and add assets. Rewrites the manifest only; never contacts a provider or spends. |
 | `--tag` | fetch/adopt | Also push tags after the command's primary work. |
+| `--refresh` | fetch | Re-download downloaded outputs and replace files whose object changed upstream; never generates, never overwrites a local edit without `--force`. |
 | `--claims <paths>` | salvage | Other project lockfiles; repeatable and comma-separated. |
 | `--workspace <path>` | workspace/salvage/gallery | Workspace catalog path; defaults to `pixelkiln.workspace.json` for `workspace`. On salvage, derives the claim set instead of repeated `--claims`; on gallery, shows every registered project. |
 | `--provider <id>` | balance/adopt/salvage/purge/workspace add | Select the account provider for a mixed manifest, or set the workspace catalog's default provider hint. |

package/docs/PIXELLAB.md

@@ -95,6 +95,18 @@ one provider account or when existing local art needs its original provenance.
 Read [Recovery and account safety](./RECOVERY.md) before changing remote
 objects.
 
+### Editing an object in PixelLab's editor
+
+A `map` or `1dir` generation is an object in your PixelLab account, and the
+web app can edit it in place with its built-in editor. `pixelkiln gallery`
+links each such record to the object (`https://www.pixellab.ai/objects/<id>`),
+and `pixelkiln fetch --refresh --only <asset>` pulls the edited bytes back
+down: the local file is replaced only if the object changed upstream and the
+local file is still exactly what PixelKiln wrote, and the lockfile records the
+new bytes as this generation. A `pixflux` image is returned inline and keeps no
+account object, so it cannot be edited upstream; use `pixelkiln edit` to touch
+it up locally.
+
 PixelLab's official
 [MCP server](https://github.com/pixellab-code/pixellab-mcp) gives agents direct
 access to PixelLab generation tools. It complements PixelKiln: the MCP handles

package/package.json

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