@bitmagic/cli 0.1.65-dev.2 → 0.1.65-dev.20

package/dist/commands/character.js

@@ -0,0 +1,268 @@
+/**
+ * `bitmagic character` — make one, look through the ready-made ones, or add one.
+ *
+ * Its own noun group rather than three flags on `bitmagic generate character`,
+ * because the shelf and the forge are two different requests that happened to
+ * share a command:
+ *
+ *   generate  costs sparks, makes a new body, may substitute a close stored one
+ *   search    free, read-only, shows what the shelf has and how close it is
+ *   add       free, puts a stored body in the game, never forges
+ *
+ * The old surface expressed "add" as `generate character --library-only`, a
+ * command that generates nothing, and it carried two flags that existed only to
+ * be refused on that path (`--head-scale` was accepted, reported and dropped;
+ * `--mesh-model` was rejected outright). Both refusals disappear here, because a
+ * command that never forges simply does not offer the flags that pick how a
+ * forge runs.
+ *
+ * `search` exists because no similarity floor can do this job. Measured against
+ * the live index, genuine matches score 0.624-0.831 while humanoid prompts the
+ * shelf cannot answer score 0.552-0.698 — overlapping, so a threshold that keeps
+ * the good ones keeps "a humanoid bee" for "a beekeeper" too. A person reading
+ * three captions settles in a second what a number cannot settle at all.
+ */
+import { defineCommand } from 'citty';
+import { CliError } from '../errors.js';
+import { createOutput } from '../output.js';
+import { apiGet } from '../http/client.js';
+import { resolveArtStyle } from '../project/art-style.js';
+import { findCachedCandidate, readCharacterSearch, writeCharacterSearch, } from '../project/character-search.js';
+import { ORIGINAL_PROMPT_FLAG, withParent } from '../telemetry/creator-prompt.js';
+import { JSON_FLAG, resolveRun, runAssetGeneration } from './generate.js';
+import { APPLY_TO_PLAYER_ARG, buildCharacterBody, defaultVoxelizeForProject, FRESH_ARG, HEAD_SCALE_ARG, LIBRARY_ARG, MESH_MODEL_ARG, NAME_ARG, PROMPT_ARG, VOXELIZE_ARG, } from '../generate/character-body.js';
+const generateCommand = defineCommand({
+    meta: {
+        name: 'generate',
+        description: 'Forge a new rigged character and add it to world.json assets. Costs sparks.',
+    },
+    args: {
+        name: NAME_ARG,
+        prompt: PROMPT_ARG,
+        'apply-to-player': APPLY_TO_PLAYER_ARG,
+        'head-scale': HEAD_SCALE_ARG,
+        fresh: FRESH_ARG,
+        library: LIBRARY_ARG,
+        voxelize: VOXELIZE_ARG,
+        'mesh-model': MESH_MODEL_ARG,
+        'original-prompt': ORIGINAL_PROMPT_FLAG,
+        json: JSON_FLAG,
+    },
+    async run({ args }) {
+        const body = buildCharacterBody({
+            name: args.name,
+            prompt: args.prompt,
+            applyToPlayer: args['apply-to-player'],
+            headScale: args['head-scale'],
+            fresh: args.fresh,
+            library: args.library,
+            voxelize: args.voxelize ?? defaultVoxelizeForProject(),
+            meshModel: args['mesh-model'],
+        });
+        await runAssetGeneration('character', 'character', withParent(body), args.json === true);
+    },
+});
+/** `62%` — the only form a similarity is ever shown in, so the table lines up. */
+function percent(value) {
+    return `${Math.round(value * 100)}%`;
+}
+function renderCandidates(candidates, threshold, log) {
+    const width = Math.max(2, ...candidates.map((row) => row.sid.length));
+    log('');
+    log(`  #  ${'id'.padEnd(width)}  match  auto  description`);
+    candidates.forEach((row, index) => {
+        // The "auto" column is why the floor is reported rather than applied: it
+        // says which of these automatic substitution would have taken, so a creator
+        // can see both that a body cleared the bar and that a weaker one exists.
+        const auto = row.similarity >= threshold ? ' yes' : '   -';
+        const label = row.subject ?? row.description ?? '';
+        log(`  ${String(index + 1).padStart(1)}  ${row.sid.padEnd(width)}  ${percent(row.similarity).padStart(5)}  ${auto}  ${label.slice(0, 60)}`);
+    });
+    log('');
+}
+const searchCommand = defineCommand({
+    meta: {
+        name: 'search',
+        description: 'List the ready-made characters closest to a description. Free; changes nothing.',
+    },
+    args: {
+        prompt: {
+            type: 'string',
+            required: true,
+            description: 'What the character should look like.',
+        },
+        limit: {
+            type: 'string',
+            description: 'How many candidates to list, 1-16. Default 5.',
+        },
+        representation: {
+            type: 'string',
+            description: "Which shelf to search: 'voxel' or 'lowpoly'. Omit to follow the project's art style.",
+        },
+        json: JSON_FLAG,
+    },
+    async run({ args }) {
+        const json = args.json === true;
+        const { output, runDeps, context, environment, token } = await resolveRun(json);
+        const representation = (() => {
+            const asked = args.representation;
+            // `resolveArtStyle` also reports a game.json value that is neither word,
+            // which is the same note every other art-style-aware command prints.
+            if (asked === undefined)
+                return resolveArtStyle(context.root, output.info) === 'low-poly' ? 'lowpoly' : 'voxel';
+            if (asked !== 'voxel' && asked !== 'lowpoly') {
+                throw new CliError("--representation must be 'voxel' or 'lowpoly'.", 1, 'invalid_flag');
+            }
+            return asked;
+        })();
+        const query = new URLSearchParams({
+            gameId: context.metadata.gameId,
+            prompt: args.prompt,
+            representation,
+        });
+        if (args.limit !== undefined)
+            query.set('limit', args.limit);
+        const response = await apiGet(environment, `/api/cli/v1/characters/search?${query.toString()}`, token, runDeps);
+        // Written even when empty: "the shelf has nothing like this" is a result a
+        // re-run should not have to rediscover, and an empty cache makes `add --id`
+        // say "search first" rather than "no such id".
+        writeCharacterSearch(context.root, {
+            prompt: response.prompt,
+            representation,
+            threshold: response.threshold,
+            searchedAt: new Date().toISOString(),
+            candidates: response.candidates,
+        });
+        if (response.candidates.length === 0) {
+            const nearest = response.topSimilarity !== undefined
+                ? ` The closest was ${percent(response.topSimilarity)}, which had no usable file.`
+                : '';
+            output.info(`No ready-made ${representation} character matches "${response.prompt}".${nearest}`);
+            output.info(`Forge one instead:  bitmagic character generate --name <name> --prompt "${response.prompt}"`);
+            output.result({ ok: true, kind: 'character search', representation, threshold: response.threshold, candidates: [], ...(response.reason ? { reason: response.reason } : {}) });
+            return;
+        }
+        output.info(`${response.candidates.length} ready-made ${representation} character(s) for "${response.prompt}":`);
+        renderCandidates(response.candidates, response.threshold, output.info);
+        const best = response.candidates[0];
+        if (best.similarity < response.threshold) {
+            // Said plainly rather than hidden: on this corpus a confident-looking
+            // caption can still be the wrong character, and the creator is the only
+            // one who can tell.
+            output.info(`None clears the ${percent(response.threshold)} bar automatic substitution requires — read the captions before adding one.`);
+        }
+        output.info(`Add one:  bitmagic character add --id ${best.sid} --name <name>`);
+        output.result({
+            ok: true,
+            kind: 'character search',
+            representation,
+            threshold: response.threshold,
+            candidates: response.candidates,
+        });
+    },
+});
+/**
+ * What `bitmagic character add` will ask for, from its flags and the cached search.
+ *
+ * Pure, and separated from the command so the branch that matters — which of the
+ * two forms was asked for, and whether the cache can answer it — is testable
+ * without a project, a token or a network. It returns the character args rather
+ * than a body so the shared `buildCharacterBody` still owns the wire shape.
+ */
+export function resolveAddRequest(args) {
+    if (args.id === undefined) {
+        if (args.prompt === undefined) {
+            throw new CliError('Pass --id (from `bitmagic character search`) or --prompt to take the closest match.', 1, 'invalid_flag');
+        }
+        // The no-id form: the server searches with no floor and adds the best usable
+        // body, or fails without charging. Deliberately still available — "any of
+        // these will do" is a real request, and it is one call rather than two.
+        return {
+            name: args.name,
+            prompt: args.prompt,
+            applyToPlayer: args.applyToPlayer,
+            libraryOnly: true,
+            voxelize: defaultVoxelizeForProject(),
+        };
+    }
+    if (args.record === null) {
+        throw new CliError('No character search to pick from. Run `bitmagic character search --prompt "..."` first.', 1, 'no_search');
+    }
+    const candidate = findCachedCandidate(args.record, args.id);
+    if (candidate === null) {
+        const known = args.record.candidates.map((row) => row.sid).join(', ');
+        throw new CliError(`"${args.id}" was not in the last character search`
+            + (known === '' ? ' (it found nothing).' : `. It offered: ${known}.`)
+            + ' Run `bitmagic character search` again to pick from a fresh list.', 1, 'unknown_candidate');
+    }
+    return {
+        name: args.name,
+        // The CREATOR's brief, not the library row's own caption: this is what a
+        // regeneration re-drives, so it must describe what they asked for.
+        prompt: args.prompt ?? args.record.prompt,
+        applyToPlayer: args.applyToPlayer,
+        libraryPick: {
+            sid: candidate.sid,
+            assetUrl: candidate.assetUrl,
+            similarity: candidate.similarity,
+            ...(candidate.description ? { description: candidate.description } : {}),
+        },
+        // The shelf that produced the row decides the medium, not the project's art
+        // style at the moment of adding: mixing them would hand a low-poly game a
+        // pile of cubes.
+        voxelize: args.record.representation === 'voxel',
+    };
+}
+const addCommand = defineCommand({
+    meta: {
+        name: 'add',
+        description: 'Add a ready-made character from the library to world.json assets. Free; never forges.',
+    },
+    args: {
+        name: NAME_ARG,
+        id: {
+            type: 'string',
+            description: 'The id of a candidate from `bitmagic character search`. Omit to take the closest match to --prompt.',
+        },
+        prompt: {
+            type: 'string',
+            description: 'What the character should look like. Required without --id; with --id it defaults to the search that found it.',
+        },
+        'apply-to-player': APPLY_TO_PLAYER_ARG,
+        'original-prompt': ORIGINAL_PROMPT_FLAG,
+        json: JSON_FLAG,
+    },
+    async run({ args }) {
+        const json = args.json === true;
+        const { context } = await resolveRun(json);
+        const output = createOutput(json);
+        // Only the --id form consults the cache; the --prompt form is a fresh ask.
+        const record = args.id === undefined ? null : readCharacterSearch(context.root);
+        const request = resolveAddRequest({
+            name: args.name,
+            id: args.id,
+            prompt: args.prompt,
+            applyToPlayer: args['apply-to-player'],
+            record,
+        });
+        if (request.libraryPick) {
+            // The search's own date, not an expiry: age is worth seeing, and the
+            // catalogue only changes when somebody promotes to it.
+            output.info(`Adding ${request.libraryPick.sid} (${percent(request.libraryPick.similarity)} match`
+                + `${record?.searchedAt ? `, from the search on ${record.searchedAt.slice(0, 10)}` : ''}).`);
+        }
+        await runAssetGeneration('character', 'character', withParent(buildCharacterBody(request)), json);
+    },
+});
+export const characterCommand = defineCommand({
+    meta: {
+        name: 'character',
+        description: 'Forge a character, search the ready-made ones, or add one to your game.',
+    },
+    subCommands: {
+        generate: generateCommand,
+        search: searchCommand,
+        add: addCommand,
+    },
+});
+//# sourceMappingURL=character.js.map

package/dist/commands/character.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"character.js","sourceRoot":"","sources":["../../src/commands/character.ts"],"names":[],"mappings":"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"}

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,8 @@ 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 { pruneForgeStore } from '../forge/prune-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 +77,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);
@@ -224,7 +248,9 @@ async function classifyForgedArchetypes(input) {
     for (const assetId of assetIds.slice(0, MAX_ARCHETYPES_TO_CLASSIFY)) {
         if (!voxelIds.has(assetId))
             continue;
-        await classifyAssetMaterialsQuietly({ context, environment, token, assetId, log, session });
+        // A forged archetype baked with the level's material map already carries its
+        // classes; the model is only asked about the ones the bake could not class.
+        await classifyAssetMaterialsQuietly({ context, environment, token, assetId, log, session, skipIfClassed: true });
     }
 }
 const defaultDeps = (json) => commandRunDeps(json);
@@ -291,7 +317,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 +383,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 +425,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 +450,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 +477,39 @@ 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 });
+        // The level is in world.json: the finished jobs it no longer names (an
+        // edited level keeps only its newest) have nothing left to give.
+        pruneForgeStore({ projectRoot: context.root, world: readWorldJson(projectWorldJsonPath(context.root)), keep: [jobId], log });
+        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 +520,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 +559,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 +622,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 +705,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.',