@bitmagic/cli 0.1.65-dev.1 → 0.1.65-dev.10

package/README.md

@@ -202,7 +202,7 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic publish [--visibility public\|private] [--name <name>] [--description <desc>] [--force] [--single-file] [--version-url] [--no-qr]` | Verify-gate, build if needed, and upload straight to GCS. `--single-file` publishes the offline bundle described under `bitmagic build`; switching the flag between runs always rebuilds, since it changes nothing on disk for the reuse check to notice. **Keeps the game's current visibility**; a new game is private until published with `--visibility public`. Prints the link worth sharing: `bitmagic.ai/play/<ID>/` — the game's page, with its name, cover and comments — for a public game, and `bitmagic.ai/games/<ID>/` for a private one. Both always serve the newest publish, so a link handed out today keeps working after tomorrow's publish; `--version-url` also prints the URL of this one build (`.../indexN.html`), for pinning a bug report to it. Shows the shared URL as a QR code so you can scan it onto a phone — drawn in the terminal, or written to `.bitmagic/publish-qr.png` when it cannot be. `--no-qr` skips both. |
 | `bitmagic self-update [--tag latest\|dev]` | Update the **CLI itself** to the newest build of its line, installing into the place this CLI actually lives rather than wherever the `npm` on your `PATH` would put it — which under nvm is routinely somewhere else. Reads the project's line from `bitmagic.json` when there is one, so it also fixes a wrong-line install; `--tag` overrides. Verifies the version on disk moved, and refuses (naming the path) for an `npx` run, a source checkout, or an install shape it cannot recognise. Not to be confused with `upgrade`, which is about the project's engine. |
 | `bitmagic upgrade [--engine <version>] [--force]` | Refresh vendored platform files and the CLI's own skills to the currently published engine. Refuses a dirty git tree unless `--force`. Also records the project's `environment` in `bitmagic.json` if it has none yet — the engine it just vendored came from that api-server — and says so when it does. |
-| `bitmagic generate <skybox\|background\|block-type\|sound\|music\|image\|video\|character\|animation\|model\|prop\|vehicle> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `model` mints a **new** 3D object from a prompt, `prop` upgrades an existing placeholder **in place** (both produce voxels directly; `--mesh` takes the older mesh path; a low-poly project keeps the mesh as a `glb` asset — see **Art style**), `vehicle` adds a new drivable one, `animation` takes a parameter spec rather than a prompt, `block-type` registers a custom voxel block, `video` makes a short clip for a cutscene (played with `engine.playVideo("<id>")`) — see **Cutscene clips** below. `skybox` and `background` write the **same** field: pick one. |
+| `bitmagic generate <skybox\|background\|block-type\|sound\|music\|image\|video\|character\|animation\|model\|prop\|vehicle> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `model` mints a **new** 3D object from a prompt, `prop` upgrades an existing placeholder **in place** (both produce voxels directly; `--mesh` takes the older mesh path; a low-poly project keeps the mesh as a `glb` asset — see **Art style**), `vehicle` adds a new drivable one, `animation` takes a parameter spec rather than a prompt, `block-type` registers a custom voxel block, `video` makes a short clip for a cutscene (played with `engine.playVideo("<id>")`) — see **Cutscene clips** below. `skybox` and `background` write the **same** field: pick one. `character --library-only` takes a ready-made body off the shelf for free instead of generating — see **Taking a character off the shelf**. |
 | `bitmagic assets add <file> [--name <n>] [--asset-id <id>] [--keep-glb\|--voxelize] [--voxel-size <m>] [--max-voxel-size <m>] [--height <m>] [--hollow\|--solid] [--force]` | Upload **your own** file — `.glb`, `.vxl`, `.png/.jpg/.webp`, `.opus/.ogg/.m4a/.mp3`, `.json` — into the game's assets and write its entry into `src/work/world.json`. A `.glb` is voxelized in a headless browser (Chrome + a free port in 3000–3199, like `prop`) unless `--keep-glb` — or unless the project is low-poly (see **Art style**). Free — no sparks. See **Adding your own assets** below. |
 | `bitmagic assets list` | The assets in `world.json`: id, name, type, size, placed instances, and total references. Local, no network. |
 | `bitmagic assets materials <assetId> [--set <file.json>] [--auto] [--clear]` | Show what an asset's voxels look like, or say what they are **made of** — so a sword's steel blade shines and its leather grip does not. With no flag it prints the asset's colour groups; `--set` applies your verdicts; `--auto` lets a model decide (what `generate prop` and `generate model` already do on their own); `--clear` removes them. Free — no sparks, nothing generated. See **Voxel materials** below. |
@@ -215,6 +215,7 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic trailer analyze \| beats \| cut \| render \| merge` | The steps of `make` as separate commands: score a recording into highlight windows with contact sheets; detect a track's beat grid; turn `trailer/shots.json` into a frame-exact `edl.json`; render an EDL (`--ui` redraws the HUD, `--ui-keyframe-rate` caps how often it may change, `--logo`, `--music …`); join recordings from separate sittings. |
 | `bitmagic trailer publish <file.mp4> [--no-attach]` | Upload a trailer (`.mp4`/`.webm`, ≤ 200 MiB, header-checked so a renamed image is refused before upload) to the CDN under `game-media/<gameId>/` and put it at the front of the game page gallery. Re-running replaces the previous trailer (remembered in `.bitmagic/trailer/published.json`); the page is capped at 12 media items. Works before the first publish — the page goes live on the first `bitmagic publish --visibility public`. `--no-attach` uploads only. |
 | `bitmagic forge --prompt "..." [--city\|--dungeon\|--platformer\|--freeform] [--name <name>] [--resume <jobId>]` | Design and bake a whole playable level into `world.json`. Costs sparks, and takes many minutes — the bake alone can take twenty. `--resume <jobId>` picks a failed run back up from the last step that finished, rather than redoing the whole thing. |
+| `bitmagic forge --edit "..." [--level <id or name>]` | Change a detail of a level this project forged — a door style, the light fixtures, a prop — without re-forging it. The stored design is patched and only what the change touches is re-made; the level is replaced in place. See [Editing a forged level](#editing-a-forged-level). |
 | `bitmagic tools <list\|path\|install> [bundle]` | The script bundles the CLI ships for skills that drive Blender or Python (`blender-level`, `unity-import`): what they are, where this install keeps them, and `install` to copy one into the project's `tools/`. Local, no network, no sparks. |
 | `bitmagic levels <list\|add\|rename\|set-start\|remove> ...` | Manage the levels `forge` creates: which one boots, their names, registering a bake you already have, deleting one. Local, no network, no sparks. See **Managing levels** below. |
 
@@ -1207,6 +1208,42 @@ exact `--glb-url … --voxel-size …` command to retry the browser step without
 If the finished asset reports that it will not drive, the project's vendored engine predates
 vehicle-fitment derivation: run `bitmagic upgrade`, then regenerate.
 
+## Editing a forged level
+
+A forged level's design is kept on its record, so a detail can be changed without designing and
+baking the world again:
+
+```bash
+bitmagic forge --edit "make the doors sliding bulkheads"
+bitmagic forge --edit "warm amber lanterns instead of the lamps" --level "Freighter Mk IV"
+bitmagic forge --edit "recolour the hull plating a rusty red" --level level_1788942022362_yujy5i
+```
+
+The change goes to the designer as one small call that returns the handful of edits to the stored
+design — a fraction of a design's cost — and the level is then built from the edited design under
+a new job. What that build re-makes is decided by comparing it with the original, object by object:
+
+| The change touches | What is re-made |
+|---|---|
+| the door style | the door leaves and the key pickups |
+| the light fixture (kind, colour, flicker) | the fixtures |
+| a prop or wall-decor kit piece | that piece |
+| a material colour, a wall/floor/ceiling kit piece, the rooms, the viewports, the terrain | the level bake and most objects |
+
+Everything else — the baked level, every untouched object — is reused, so a door-style edit takes
+about as long as baking three small objects. The run prints what it reused. The level is replaced
+in place: same level id, doors, keys and placed objects rewritten, your other levels untouched. An
+object you have since regenerated in high quality is kept as it is.
+
+One thing it needs: the level must have been forged by a CLI that records the job on the level
+and mirrors its bakes to the server — anything forged before that is re-forged once and editable
+from then on, from any machine. (A forge keeps its resumable state in the project's
+`.bitmagic/forge` and mirrors the browser-baked records to api-server as it goes, so `--resume`
+and `--edit` both work from a clone that never ran the original forge; a mirror that fails is
+said once and the run continues from the local copy.) `--level` takes the level's id or name (`bitmagic levels list`), and
+can be left out when the project has one forged level. `--edit` takes no other forge flag; a 2D
+side-view level cannot be edited yet.
+
 ## Managing levels
 
 `bitmagic forge` bakes levels but could not manage them: only a game's *first* forge became the
@@ -1274,11 +1311,37 @@ read by everything that used to assume cubes:
 | `bitmagic cover`, `bitmagic reference make` | MagicaVoxel-style prompt lead and tail | flat-shaded low-poly lead and tail (same image model) |
 | `bitmagic assets add x.glb` | voxelized in a headless browser | kept as a `glb` asset; `--voxelize` bakes it |
 | `bitmagic generate model` / `prop` | voxel master, baked in the browser | mesh generated, re-uploaded into the project, registered as `glb` (`--height` / the placeholder's fitBox); `--voxelize` bakes it |
-| `bitmagic generate character` | voxelized rig, library search first | the textured low-poly rig, no library; `--voxelize` overrides |
+| `bitmagic generate character` | voxelized rig, library search first | the textured low-poly rig; its own library shelf, searched only where the server has enabled it; `--voxelize` overrides |
 | `bitmagic generate vehicle` | voxel | still voxel — the builder is voxel-native; the command says so |
 | `bitmagic judge` with no `## Art direction` | grades the style it sees | judges within low-poly |
 | the engine on load | sunset hemisphere light and a faint bloom | neither; a `MeshLevel` brings its own lighting |
 
+### Taking a character off the shelf
+
+`bitmagic generate character --library-only` skips generation entirely and hands
+back the closest ready-made body in the library. It is free and takes about a
+second, against $0.15 for a voxel forge or $0.60 for a low-poly one, and several
+minutes either way.
+
+It differs from the ordinary library search in three ways worth knowing:
+
+- **It ignores the quality bar.** Normal generation only substitutes a stored
+  body when it is a close match; this takes the best there is. The output tells
+  you how close it came, and says so plainly when the match is weak.
+- **It never forges.** If the library has nothing usable the command fails and
+  charges nothing, rather than quietly falling back to a paid generation — you
+  ran it to avoid spending, so it does not spend.
+- **It works regardless of whether automatic substitution is enabled.** Asking
+  for a stored body is not the same as the server deciding to give you one.
+
+`--head-scale` cannot be honoured (proportions are baked into a stored body; it
+is reported and ignored), and `--mesh-model` is rejected outright, since it
+selects how a character would be forged and nothing is forged.
+
+The shelf you get depends on the project's art style, like every other character
+request: a voxel game searches voxel bodies, a low-poly game searches low-poly
+ones.
+
 In a low-poly game the textured rig IS the product, so `bitmagic generate character` forges it with
 `runware-meshy-6`: an even remesh with symmetric limbs and an enforced A-pose, rather than a TRELLIS
 reconstruction that is only as low-poly as the concept image happened to be. **That costs about

package/assets/skills/trailer-craft.md

@@ -0,0 +1,180 @@
+# Trailer craft — structure, pacing, and on-screen text
+
+Read this before composing a cut or putting any text on screen. Compressed
+from Derek Lieu's trailer-editing essays (trailer editor for Half-Life: Alyx,
+Dead Cells, Spelunky 2) plus general trailer-typography guidance; sources at
+the bottom.
+
+## Ordering: Genre → Hook → Anchors → Content
+
+- **Genre** in 1–2 shots: the viewer must know what kind of game this is
+  within the first seconds. For our games one gameplay shot usually does it.
+- **Hook** — the thing only this game has — as soon as genre is established:
+  ideally inside the first 10–15 s, never later than the first third.
+  Showing generic-but-good content before the hook makes the game read as
+  "a lesser version of an old game".
+- **Anchors** — the features people expect from the genre (for a racer:
+  overtakes, drifts, crashes, varied tracks) fill the middle.
+- **Content** — breadth (levels, modes, vehicles) comes last, once the viewer
+  already cares.
+
+## Timeline layout: constraints first, footage last
+
+Lay the timeline out as a skeleton and only then hunt for footage — not the
+other way round:
+
+1. Write the section skeleton: **Cold open → Introduction → Escalation →
+   Climax → Breath → Button/End card**. Sections have different lengths and
+   energy; they are not equal slices.
+2. Reserve the **end card** first: 2–3 s, ONE card (logo + tagline + CTA),
+   never a sequence of closing screens.
+3. Place any **body title cards** next, as placeholders with their copy
+   written — each one names what the following footage must prove.
+4. Only now fill footage, chosen to demonstrate whatever the neighbouring
+   card or section claims.
+
+This turns "pick 15 great clips" (squishy, drifts toward sameness) into
+"find the one clip that proves this beat" (constrained, self-diversifying).
+
+## Pacing
+
+- Sections need **ebb and flow**: build to a peak, then give a deliberate
+  breathing shot (~5 s, calmer, wider) before the next build or the finale.
+  The stops emphasize the fast; the fast emphasizes the slow.
+- **Rule of three**: never more than three similar things in a row — three
+  crashes, three drift shots, three of anything. Viewers extrapolate after
+  two; the fourth is dead time.
+- **Do not cut on every beat.** Snap cuts to the grid, but vary clip lengths
+  (2, 3, 4, 6 beats) and sometimes let a musical moment land on an in-clip
+  action (a landing, an impact) instead of a cut. Constant per-beat cutting
+  reads as a sizzle reel, and gets nauseating.
+- Average shot length is a genre statement: ~1.3 s reads as AAA shooter,
+  ~4 s reads as contemplative indie. An arcade racer sits around 1.5–3 s
+  with a few longer holds where one continuous action is the payoff.
+- **More editing is not better editing.** A cut must clarify or escalate;
+  cutting fast to look "like a real trailer" hides the game. If a single
+  take shows the whole stunt, keep the take.
+- Total length: under 90 s unless there's a reason; 30–45 s is a sweet spot
+  for social/store use.
+
+## Variety — the five axes
+
+Audit the cut on each axis; the labels list in the shots file is the tool
+(read the labels top to bottom — repetition is visible in text before you
+ever re-watch):
+
+1. **Content** — different actions, not the same action in new places.
+   Escalate variants (jump → bigger jump) rather than repeating.
+2. **Composition** — vary camera distance and framing; chase cam all the way
+   through is monotone. Watch eye-trace: the viewer's focus point should not
+   teleport across the frame on a cut.
+3. **Energy** — intense vs. quiet moments; contrast matters more than speed.
+4. **Pacing** — vary section tempo, not just shot tempo.
+5. **Shot length** — vary beats-per-clip even inside a fast section.
+
+## Where the shots come from
+
+Played footage is the default and the bulk of any trailer: it is the only
+thing that shows what the game DOES, and a trailer of pure scenery reads as a
+tech demo however pretty it is. But two of the beats above are ones a chase
+camera almost never hands you:
+
+- the **cold open**, which wants the level to look composed and deliberate;
+- the **breath**, which wants one calm wide shot with nothing happening.
+
+Both are what an authored **camera fly-through** is for — a path through the
+level with the game running underneath, so traffic still drives and animations
+still play while the camera moves on rails. Recording one is cheap and nobody
+has to play it, so a fly-through is worth having even when there is plenty of
+gameplay: cut one or two of its shots into a gameplay trailer rather than
+building a trailer out of it.
+
+A fly-through alone is the right whole trailer in a narrow set of cases — a
+world reveal, an architectural or exploration piece, a level that is the
+feature — and whenever there is no one available to play. Otherwise it is a
+source of shots, not a substitute for showing the game.
+
+## On-screen text
+
+When to use text at all: only when footage cannot say it. A card that
+narrates what the next shot visibly shows is noise. Default for our
+gameplay trailers: **end card only**; add body cards only when they carry
+information the footage can't (game name early, a hook that isn't visual,
+release date).
+
+Writing the cards:
+- Copy must sound like this game and no other. Exercise: describe the game
+  in three words; build cards from what's left after cutting everything
+  generic.
+- ≤ 6 words per card. Evocative verbs beat feature lists ("Forge your own
+  path", not "Over 40 unique tracks").
+- Banned: content quantities ("5 unique levels"), genre-descriptor stacks
+  ("a 2D rogue-lite action adventure"), player-verb lists ("Race! Drift!
+  Win!"), and stock phrases ("In a world…", "Get ready…", "Experience…",
+  "…like never before").
+
+Showing the cards:
+- **Intercut, don't overlay**: a card gets its own beat between gameplay
+  shots (dimmed still or plain background). Never ask the viewer to read
+  while action plays — they do neither. Small persistent text (logo bug,
+  date) is the exception.
+- Reading time: ~0.5–0.7 s per word, minimum 2.5 s on screen; end card
+  2–3 s (ours may run longer over a music outro).
+- Cards ride the same beat grid as the cuts — a card is a clip.
+- Typography must match the game's art quality and universe: one typeface
+  family for the whole trailer, generous letter-spacing for all-caps,
+  strong contrast against footage (our title raster already adds shadow),
+  subtle animation only (fade/scale-in) — a static default-font card reads
+  as a last-minute add-on.
+
+## Structure template (30–45 s, gameplay-only, end card close)
+
+| Section | ~share | What goes here |
+|---|---|---|
+| Cold open | 5–15% | The single most striking moment; genre obvious at a glance |
+| Introduction | 15–20% | Clean, readable driving; establish look + one anchor |
+| Escalation | 35–45% | Varied action, rising energy, hook prominent early in it |
+| Climax | 15–20% | Densest, loudest stretch; biggest moments back to back |
+| Breath | ~5% | One calmer, wider shot; lets the climax land |
+| End card | 2–3 s+ | Logo, tagline, CTA — over the music's outro |
+
+## Selection rules already paid for
+
+These came out of review rounds on real cuts. They cost time to learn and
+nothing to apply, so apply them before the first render, not after.
+
+- **Never use slow motion.** On gameplay footage it reads as the game running
+  at a low framerate, not as drama. `speed` stays 1.0.
+- **Numbers are not interest.** Event `severity` / `impactSpeed` ranks
+  car-stops-dead-against-a-wall highest — the worst possible clip. A crash
+  earns its slot only if things visibly break (`destruction` events, debris)
+  and motion continues through the hit.
+- **Low speed can BE the drama.** Wheelspin recoveries throwing dirt or snow,
+  plowing back onto the track, being overtaken while struggling
+  (`position-change` with `gained: false`), `off-track` +
+  `hard-acceleration` clusters — these are among the best clips and score
+  near zero on any speed metric.
+- **"Some shots of X" means a few.** The failure mode is 0-or-100: one
+  standing start is an opener, five is a broken trailer.
+- **Quota check before rendering.** Read the shots list labels top to bottom.
+  Max one standing start; no more than three of any shot type in the whole
+  cut and never three similar in a row; vary track or biome, camera distance
+  and action type (the five axes above).
+- **Menu and selection clips need `"ui": false`** — the HUD replay only knows
+  the gameplay HUD and will paint it over menus.
+- **Verify on pixels.** Contact sheets and stills for every candidate, and
+  stills from the RENDERED file for anything you changed. The timeline knows
+  about events; it cannot see framing, occlusion or beauty.
+- **Iterate cheaply, keep history.** Editing the shots and re-rendering is
+  minutes, and revisions auto-version — so render rather than debate, and
+  compare against the previous `-rN` before delivering.
+
+## Sources
+
+- [How to Hook the Audience and How Quickly to Do it](https://www.derek-lieu.com/blog/2022/10/24/how-to-hook-the-audience-and-how-quickly-to-do-it)
+- [Step Two of Starting a Game Trailer Timeline](https://www.derek-lieu.com/blog/2023/2/19/step-two-of-starting-a-game-trailer-timeline)
+- [How to Think About Pacing in a Trailer](https://www.derek-lieu.com/blog/2020/11/16/how-to-think-about-pacing-in-a-trailer)
+- [Variety is the Spice of Trailers](https://www.derek-lieu.com/blog/2019/3/27/variety-is-the-spice-of-trailers)
+- [More Trailer Editing is not Better Trailer Editing](https://www.derek-lieu.com/blog/2023/4/23/more-trailer-editing-is-not-better-trailer-editing)
+- [How to Write Trailer Title Cards With Strong Messaging](https://www.derek-lieu.com/blog/2020/4/19/how-to-write-trailer-title-cards-with-strong-messaging)
+- [10 Common Indie Game Trailer Mistakes & How to Fix Them](https://www.derek-lieu.com/blog/2020/9/14/10-common-indie-game-trailer-mistakes-and-how-to-fix-them)

package/dist/cli.d.ts

@@ -479,6 +479,14 @@ declare const rawCommands: {
             readonly type: "boolean";
             readonly description: "Boot the game into this level. Without it, only a game's FIRST forge becomes the start level, so a later forge lands in the level list unseen.";
         };
+        readonly edit: {
+            readonly type: "string";
+            readonly description: "Change a detail of a level this project forged (\"make the doors sliding bulkheads\", \"warm amber lanterns instead of the lamps\") without re-forging it: the stored design is patched and only what the change touches is re-made. Replaces the level in place. Takes --level; no other forge flag.";
+        };
+        readonly level: {
+            readonly type: "string";
+            readonly description: "With --edit: the level to change, by id or name (`bitmagic levels list`). Omit when the project has one forged level.";
+        };
         readonly json: {
             readonly type: "boolean";
             readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";

package/dist/commands/forge.d.ts

@@ -11,6 +11,13 @@ type ModeFlag = (typeof MODE_FLAGS)[number];
  * the server receives the answer rather than recomputing it.
  */
 export declare function deriveLevelName(explicit: string | undefined, prompt: string): string;
+/**
+ * `--edit` changes a level as it was designed, so it takes none of a fresh forge's steering: no
+ * prompt, no scene type, no reference image, no revision rounds, no start-level switch, and no
+ * resume (a resumed edit replays its frozen request, which `--edit` would contradict). Refused
+ * before any request, where it is still free.
+ */
+export declare function assertEditFlags(args: Record<string, unknown>): void;
 /** The single selected mode, or undefined for plain terrain. */
 export declare function selectMode(args: Record<string, unknown>): ModeFlag | undefined;
 /**
@@ -144,6 +151,14 @@ export declare const forgeCommand: import("citty").CommandDef<{
         readonly type: "boolean";
         readonly description: "Boot the game into this level. Without it, only a game's FIRST forge becomes the start level, so a later forge lands in the level list unseen.";
     };
+    readonly edit: {
+        readonly type: "string";
+        readonly description: "Change a detail of a level this project forged (\"make the doors sliding bulkheads\", \"warm amber lanterns instead of the lamps\") without re-forging it: the stored design is patched and only what the change touches is re-made. Replaces the level in place. Takes --level; no other forge flag.";
+    };
+    readonly level: {
+        readonly type: "string";
+        readonly description: "With --edit: the level to change, by id or name (`bitmagic levels list`). Omit when the project has one forged level.";
+    };
     readonly json: {
         readonly type: "boolean";
         readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";

package/dist/commands/forge.js

@@ -19,7 +19,8 @@
  * nothing, and is my project still intact?" is the first question.
  */
 import { defineCommand } from 'citty';
-import { buildAssetCatalog, createForgedWorkStore, SIDEON_FORGE_STEPS, } from '@bitmagic/world-forger/pipeline/index.js';
+import { buildAssetCatalog, createForgedWorkStore, describeEditSeed, EDIT_FORGE_STEPS, seedEditStore, SIDEON_FORGE_STEPS, } from '@bitmagic/world-forger/pipeline/index.js';
+import { bakeEverythingPlan, buildEditJobInput, resolveEditTarget } from '../forge/edit-target.js';
 import { CliError } from '../errors.js';
 import { createOutput } from '../output.js';
 import { creatorPromptField, ORIGINAL_PROMPT_FLAG } from '../telemetry/creator-prompt.js';
@@ -43,6 +44,7 @@ import { assertNotOpenWater, describeSideonRegistryLoss, readCharacterRunSpeed,
 import { reserveLanePort } from '../local-port.js';
 import { createForgeProgressTracker } from '../forge/progress.js';
 import { createLocalForgeStorage } from '../forge/local-store.js';
+import { createMirroredForgeStorage } from '../forge/remote-store.js';
 import { describeForgeFailure, requestForge } from '../forge/stream.js';
 import { buildCliForgeDeps, createConsoleForgeLogger, readFrozenInput, runForgePipeline, seedForgeStore, } from '../forge/run-pipeline.js';
 /** Mirrors api-server's `FORGE_JOB_ID_PATTERN` so a typo is rejected here, before a round trip. */
@@ -74,6 +76,27 @@ export function deriveLevelName(explicit, prompt) {
     const derived = prompt.trim().split(/\s+/).slice(0, 6).join(' ').slice(0, 48).trim();
     return derived.length > 0 ? derived : 'level';
 }
+/**
+ * `--edit` changes a level as it was designed, so it takes none of a fresh forge's steering: no
+ * prompt, no scene type, no reference image, no revision rounds, no start-level switch, and no
+ * resume (a resumed edit replays its frozen request, which `--edit` would contradict). Refused
+ * before any request, where it is still free.
+ */
+export function assertEditFlags(args) {
+    const conflicts = [
+        ['prompt', typeof args.prompt === 'string' && args.prompt !== ''],
+        ['resume', typeof args.resume === 'string' && args.resume !== ''],
+        ['reference-image', typeof args['reference-image'] === 'string' && args['reference-image'] !== ''],
+        ['reference-image-url', typeof args['reference-image-url'] === 'string' && args['reference-image-url'] !== ''],
+        ['match-rounds', args['match-rounds'] !== undefined],
+        ['make-start', args['make-start'] === true],
+        ...MODE_FLAGS.map((mode) => [mode, args[mode] === true]),
+    ].filter(([, set]) => set).map(([flag]) => `--${flag}`);
+    if (conflicts.length > 0) {
+        throw new CliError(`--edit changes a forged level as it was designed and cannot be combined with ${conflicts.join(', ')}. `
+            + 'Describe the change alone: `bitmagic forge --edit "make the doors sliding bulkheads" --level <id or name>`.');
+    }
+}
 /** The single selected mode, or undefined for plain terrain. */
 export function selectMode(args) {
     const chosen = MODE_FLAGS.filter((mode) => args[mode] === true);
@@ -291,7 +314,7 @@ async function runBrowserSteps(options) {
         });
         await host.launch();
         await host.loadGame();
-        const storage = createLocalForgeStorage(context.root);
+        const { storage } = options;
         const store = createForgedWorkStore(jobId, storage);
         const forgeDeps = buildCliForgeDeps({
             projectRoot: context.root,
@@ -357,11 +380,14 @@ export async function runForge(args, deps) {
     const runDeps = deps ?? defaultDeps(args.json === true);
     const prepared = await prepareForgeRequest(args, runDeps);
     const { context, environment, storage, input, resumeJobId, token, reference, lane } = prepared;
+    // An edit of a forged level (fresh, or a resumed edit): the frozen request names its parent.
+    const editing = input.parentJobId !== undefined;
     // One advisory line about the reference image, fresh runs only (a resume replays the frozen
-    // request, picture and all): either the project default took effect, or — when there is no
-    // reference at all — a pointer to the command that would give the designer one. Neither is a
-    // prompt; the forge proceeds regardless.
-    if (resumeJobId === null) {
+    // request, picture and all; an edit never sees the picture — it changes a stored design):
+    // either the project default took effect, or — when there is no reference at all — a pointer
+    // to the command that would give the designer one. Neither is a prompt; the forge proceeds
+    // regardless.
+    if (resumeJobId === null && !editing) {
         const referenceLine = describeAppliedReference(reference);
         if (referenceLine)
             runDeps.log(referenceLine);
@@ -396,11 +422,14 @@ export async function runForge(args, deps) {
             onLayout: report.layout,
             // A side-on run is four steps (no level bake) — with the default list the
             // banners would read [n/5] and "Baking level" would sit pending forever.
-            ...(lane === 'sideon' ? { steps: SIDEON_FORGE_STEPS } : {}),
+            // An edit keeps the five, with the design step named for what it does.
+            ...(editing ? { steps: EDIT_FORGE_STEPS } : lane === 'sideon' ? { steps: SIDEON_FORGE_STEPS } : {}),
         });
         log(resumeJobId !== null
-            ? `Resuming forge job ${resumeJobId} for game ${context.metadata.gameId}.`
-            : `Forging a ${lane === 'sideon' ? 'SIDE-ON 2D level' : 'level'} for game ${context.metadata.gameId}: "${input.prompt}"`);
+            ? `Resuming ${editing ? 'edit' : 'forge'} job ${resumeJobId} for game ${context.metadata.gameId}.`
+            : editing
+                ? `Editing level "${input.name}" of game ${context.metadata.gameId}: "${input.editPrompt ?? input.prompt}"`
+                : `Forging a ${lane === 'sideon' ? 'SIDE-ON 2D level' : 'level'} for game ${context.metadata.gameId}: "${input.prompt}"`);
         // Said BEFORE the billed request, never only in the post-forge notes: a
         // side-on forge discards a multi-level registry and the objects in it.
         if (lane === 'sideon' && resumeJobId === null) {
@@ -418,16 +447,24 @@ export async function runForge(args, deps) {
                 else
                     log(`  ${message}`);
             },
-        }, lane === 'sideon'
+        }, editing
             ? {
-                // The sibling route, so an api-server deployed before the side-on lane
-                // 404s LOUDLY here — before any model call and before any charge —
-                // instead of silently running a wrong 3D forge.
-                path: '/api/cli/v1/forge-sideon/stream',
-                notFoundMessage: 'This api-server does not support 2D side-view forging yet (the route is missing). '
-                    + 'Nothing was sent or billed — update later, or build the level from the web creator once it ships there.',
+                // The edit's own route, for the same loud-404 reason as the side-on lane: an older
+                // api-server would otherwise design a whole new level from an edit request and bill it.
+                path: '/api/cli/v1/forge-edit/stream',
+                notFoundMessage: 'This api-server cannot edit forged levels yet (the route is missing). '
+                    + 'Nothing was sent or billed — update later, or re-forge the level with the change in its prompt.',
             }
-            : undefined);
+            : lane === 'sideon'
+                ? {
+                    // The sibling route, so an api-server deployed before the side-on lane
+                    // 404s LOUDLY here — before any model call and before any charge —
+                    // instead of silently running a wrong 3D forge.
+                    path: '/api/cli/v1/forge-sideon/stream',
+                    notFoundMessage: 'This api-server does not support 2D side-view forging yet (the route is missing). '
+                        + 'Nothing was sent or billed — update later, or build the level from the web creator once it ships there.',
+                }
+                : undefined);
         if (!outcome.success) {
             throw new CliError(describeForgeFailure(outcome));
         }
@@ -437,14 +474,36 @@ export async function runForge(args, deps) {
         log(`Design and geometry are saved server-side as job ${jobId}.`);
         // From here on the design and the geometry are PAID FOR and saved server-side. Every failure
         // below must therefore point at the resume rather than at re-running from scratch.
-        await seedForgeStore(createForgedWorkStore(jobId, storage), artifact, input, platformerMovement);
+        if (editing) {
+            // The parent's bakes live in THIS project's store, if it forged the level here. The
+            // server's plan is an upper bound; the seed says what this machine could actually reuse.
+            const parentJobId = outcome.parentJobId ?? input.parentJobId;
+            const world = readWorldJson(projectWorldJsonPath(context.root));
+            const seed = await seedEditStore({
+                store: createForgedWorkStore(jobId, storage),
+                parentStore: createForgedWorkStore(parentJobId, storage),
+                artifact,
+                input,
+                reuse: outcome.reuse ?? bakeEverythingPlan(artifact, 'the server returned no reuse plan'),
+                worldAssets: Array.isArray(world.assets) ? world.assets.filter(isJsonObject) : [],
+            });
+            log(describeEditSeed(seed));
+            if (platformerMovement)
+                await createForgedWorkStore(jobId, storage).put('platformer-movement', platformerMovement);
+        }
+        else {
+            await seedForgeStore(createForgedWorkStore(jobId, storage), artifact, input, platformerMovement);
+        }
         try {
-            await runBrowserSteps({ context, environment, jobId, token, deps: { ...runDeps, log }, tracker, lane });
+            await runBrowserSteps({ context, environment, jobId, token, deps: { ...runDeps, log }, tracker, lane, storage });
         }
         catch (error) {
             throw decorateBrowserStepError(error, jobId);
         }
-        output.result({ ok: true, jobId, gameId: context.metadata.gameId, name: input.name });
+        output.result({
+            ok: true, jobId, gameId: context.metadata.gameId, name: input.name,
+            ...(editing ? { edited: true, levelAssetId: input.assetId, parentJobId: outcome.parentJobId ?? input.parentJobId } : {}),
+        });
     });
 }
 async function prepareForgeRequest(args, deps) {
@@ -455,7 +514,33 @@ async function prepareForgeRequest(args, deps) {
             throw new CliError('--resume takes a job id of 1-64 characters (letters, digits, "_" or "-") — the one printed '
                 + 'by the run you are resuming.');
         }
-        const storage = createLocalForgeStorage(context.root);
+        const environment = resolveEnvironmentForCommand({ cwd: context.root, baseDir: deps.baseDir });
+        // Resolved on first use and shared by the store and the request: the store
+        // behind every read below is MIRRORED to api-server (remote-store.ts), so a
+        // job started on another machine can be resumed or edited here — its frozen
+        // request and bakes are fetched when the local copy lacks them — and only
+        // such a fetch, or the request itself, needs the credential.
+        let tokenPromise;
+        const accessToken = () => {
+            tokenPromise ??= getAccessToken(environment, resolveAuth0ClientId(environment), { fetch: deps.fetch, sleep: deps.sleep, now: deps.now }, deps.baseDir);
+            return tokenPromise;
+        };
+        const storage = createMirroredForgeStorage(createLocalForgeStorage(context.root), {
+            environment, accessToken, fetch: deps.fetch, warn: (message) => deps.log(`warning: ${message}`),
+        });
+        // A resume replays the frozen request — including its reference image — so a file passed
+        // alongside `--resume` would be uploaded and then silently ignored. Refused instead: the
+        // caller clearly wanted the picture to matter, and it cannot here.
+        if (resumeJobId !== null && typeof args['reference-image'] === 'string' && args['reference-image'] !== '') {
+            throw new CliError('A resumed forge replays the original request, reference image and all — --reference-image '
+                + 'cannot change it. Drop --resume to start a fresh forge with this picture.');
+        }
+        // Same rule for the rounds: they are frozen with the job, and a resume that skips the design
+        // step never runs them anyway.
+        if (resumeJobId !== null && args['match-rounds'] !== undefined) {
+            throw new CliError('A resumed forge replays the original request — --match-rounds cannot change it. '
+                + 'Drop --resume to start a fresh forge.');
+        }
         const frozen = resumeJobId !== null ? await readFrozenInput(storage, resumeJobId) : null;
         // Route by the project's dimension HERE, before any token/server work:
         // steps 1-2 bill. 3D projects keep today's pipeline; side-view 2D projects
@@ -468,24 +553,32 @@ async function prepareForgeRequest(args, deps) {
         // Refused here, where it is still free.
         if (lane === 'sideon')
             assertNotOpenWater(context.root);
+        // `--edit`: change a forged level instead of designing one. The request is
+        // frozen from the level's own record (its name, its asset, the job that built
+        // it) and the change; everything a fresh forge steers by is refused.
+        const editPrompt = typeof args.edit === 'string' && args.edit.trim().length > 0 ? args.edit.trim() : null;
+        if (editPrompt !== null) {
+            assertEditFlags(args);
+            if (lane === 'sideon') {
+                throw new CliError('--edit changes a forged 3D level; a 2D side-view level cannot be edited yet — re-forge it with the change in its prompt.');
+            }
+            const target = resolveEditTarget(readWorldJson(projectWorldJsonPath(context.root)), typeof args.level === 'string' ? args.level : undefined);
+            const input = buildEditJobInput({
+                target, editPrompt, gameId: context.metadata.gameId, groundPlane: readGroundPlane(context.root),
+            });
+            return {
+                context, environment, storage, input, resumeJobId: null, token: await accessToken(), lane,
+                reference: resolveReferenceImageUrl(args, context.root),
+            };
+        }
+        if (typeof args.level === 'string' && args.level !== '') {
+            throw new CliError('--level says which level --edit changes; pass --edit "<the change>" with it.');
+        }
         const mode = selectMode(args);
         if (lane === 'sideon' && mode !== undefined) {
             throw new CliError(`--${mode} does not apply to a 2D side-view project — the side-on forge derives the layout `
                 + 'from the prompt (and GAME-DESIGN.md). Drop the flag and describe the level instead.');
         }
-        // A resume replays the frozen request — including its reference image — so a file passed
-        // alongside `--resume` would be uploaded and then silently ignored. Refused instead: the
-        // caller clearly wanted the picture to matter, and it cannot here.
-        if (resumeJobId !== null && typeof args['reference-image'] === 'string' && args['reference-image'] !== '') {
-            throw new CliError('A resumed forge replays the original request, reference image and all — --reference-image '
-                + 'cannot change it. Drop --resume to start a fresh forge with this picture.');
-        }
-        // Same rule for the rounds: they are frozen with the job, and a resume that skips the design
-        // step never runs them anyway.
-        if (resumeJobId !== null && args['match-rounds'] !== undefined) {
-            throw new CliError('A resumed forge replays the original request — --match-rounds cannot change it. '
-                + 'Drop --resume to start a fresh forge.');
-        }
         const referenceMatchRounds = parseNumberFlag('match-rounds', typeof args['match-rounds'] === 'string' ? args['match-rounds'] : undefined, { min: 0, max: 3, integer: true });
         const reference = resumeJobId !== null
             ? resolveReferenceImageUrl(args, context.root)
@@ -523,9 +616,7 @@ async function prepareForgeRequest(args, deps) {
             ...(blockSize !== undefined ? { voxelBlockSize: blockSize } : {}),
             lane,
         };
-        const environment = resolveEnvironmentForCommand({ cwd: context.root, baseDir: deps.baseDir });
-        const clientId = resolveAuth0ClientId(environment);
-        const token = await getAccessToken(environment, clientId, { fetch: deps.fetch, sleep: deps.sleep, now: deps.now }, deps.baseDir);
+        const token = await accessToken();
         return { context, environment, storage, input, resumeJobId, token, reference, lane };
     }
     catch (error) {
@@ -608,6 +699,14 @@ export const forgeCommand = defineCommand({
             type: 'boolean',
             description: 'Boot the game into this level. Without it, only a game\'s FIRST forge becomes the start level, so a later forge lands in the level list unseen.',
         },
+        edit: {
+            type: 'string',
+            description: 'Change a detail of a level this project forged ("make the doors sliding bulkheads", "warm amber lanterns instead of the lamps") without re-forging it: the stored design is patched and only what the change touches is re-made. Replaces the level in place. Takes --level; no other forge flag.',
+        },
+        level: {
+            type: 'string',
+            description: 'With --edit: the level to change, by id or name (`bitmagic levels list`). Omit when the project has one forged level.',
+        },
         json: {
             type: 'boolean',
             description: 'Print the result as JSON on stdout; all progress goes to stderr.',