Project lifecycle: apply-diff, upgrade, deploy

Three vgai verbs cover a project’s life after scaffolding (for scaffolding itself, see Scaffold a project).

The three lifecycle verbs — validated edits, engine re-sync, and shipping.

vgai apply-diff — the blessed scene-edit primitive

Applies a JSON diff to a .vscn.json with validation before write — the sanctioned way for scripts and agents to edit scenes without hand-rolling JSON surgery. The scene, the patch, and the result are all schema-validated, and every asset reference the diff introduces is dereferenced: the file must exist under the project’s asset root, and JSON asset formats (.mat.json, referenced prefabs) must parse through their own schemas — other referenced files (GLTF meshes, textures, audio) are existence-checked. A failing diff is rejected with the issues named and nothing is written. (Pre-existing broken references don’t block unrelated repairs — npm run validate-scenes is the whole-project gate.)

npm run vgai -- apply-diff public/scenes/level.vscn.json my-edit.json   # validate, then write back
npm run vgai -- apply-diff public/scenes/level.vscn.json my-edit.json --report   # validate + summarize only — never writes

vgai upgrade — re-sync a project against the engine checkout

Reports, re-syncs, and re-pins a scaffolded project against the engine checkout it lives beside, using the scaffold baseline (.vgai/scaffold-baseline.json) for three-way comparison — your local edits to template files are surfaced as diffs, never clobbered.

npm run vgai -- upgrade            # report + re-sync + re-pin
npm run vgai -- upgrade --report   # report only, never writes

Pin-ahead is blocked by default

If the project’s engine.version pin is newer than the current checkout’s engine (classic wrong-worktree or rolled-back-checkout situation), upgrade refuses — proceeding would silently downgrade your pin and baseline. The report names both versions (blockedReason: "pin-ahead: …", exit code 1). If the downgrade is really what you want, pass --force-downgrade.

vgai deploy — ship to Cloudflare Pages

Discovers the project, runs the pre-flight walls, builds, stages, and pushes the static bundle to Cloudflare Pages with wrangler:

npm run vgai -- deploy                     # full pipeline
npm run vgai -- deploy --report            # stop after staging — zero remote calls
npm run vgai -- deploy --project my-game   # explicit Pages project name

The default Pages project name is vgai-<slug of the manifest name>.

See also

• CLI, SDK & scaffolding — the editor-control verbs.
• Validate & schema tooling — the validation the same pipeline runs.