@jgengine/editor 0.11.0 → 0.12.0

package/skills/jgengine-editor/capabilities.md

@@ -11,8 +11,19 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `EditorCatalogEntry` (interface) · `import { EditorCatalogEntry } from "@jgengine/core/editor"`
 - `findEditorCatalog` (function) · `import { findEditorCatalog } from "@jgengine/core/editor"`
 - `findEditorCatalogEntry` (function) · `import { findEditorCatalogEntry } from "@jgengine/core/editor"`
+- `resolveCatalogDefinitions` (function) · `import { resolveCatalogDefinitions } from "@jgengine/core/editor"`
 - `seedEditorCatalogs` (function) · `import { seedEditorCatalogs } from "@jgengine/core/editor"`
 
+## editor-entities — Author entity stats/movement per catalog row instead of hardcoding TS.
+
+- `entityDefinitionSchema` (const) · `import { entityDefinitionSchema } from "@jgengine/core/editor"`
+- `entityEntryFromCatalog` (function) · `import { entityEntryFromCatalog } from "@jgengine/core/editor"`
+
+## editor-environment — persist sky/fog/lighting knobs on the scene document
+
+- `EditorEnvironment` (interface) · `import { EditorEnvironment } from "@jgengine/core/editor"`
+- `skyFromDocument` (function) · `import { skyFromDocument } from "@jgengine/core/editor"`
+
 ## editor-grid-import — Configure an ASCII/glyph → grid-layer import.
 
 - `AsciiGridImportOptions` (interface) · `import { AsciiGridImportOptions } from "@jgengine/core/editor"`
@@ -65,6 +76,12 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `runtimeEntityMetaWriteBackCommand` (function) · `import { runtimeEntityMetaWriteBackCommand } from "@jgengine/core/editor"`
 - `summarizeRuntimeInspector` (function) · `import { summarizeRuntimeInspector } from "@jgengine/core/editor"`
 
+## minimap-bake — persist a baked minimap PNG + bounds on the scene document
+
+- `EditorMinimapBake` (interface) · `import { EditorMinimapBake } from "@jgengine/core/editor"`
+- `bakeMinimapFromDocument` (function) · `import { bakeMinimapFromDocument } from "@jgengine/core/editor"`
+- `documentBakeZones` (function) · `import { documentBakeZones } from "@jgengine/core/editor"`
+
 ## scene-ownership — audit a whole ownership manifest for boundary violations
 
 - `auditManifest` (function) · `import { auditManifest } from "@jgengine/core/scene/sceneOwnership"`
@@ -72,3 +89,32 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `collectOwnershipDiagnostics` (function) · `import { collectOwnershipDiagnostics } from "@jgengine/core/scene/sceneOwnership"`
 - `isSceneOwnershipManifest` (function) · `import { isSceneOwnershipManifest } from "@jgengine/core/scene/sceneOwnership"`
 - `ownershipKey` (function) · `import { ownershipKey } from "@jgengine/core/scene/sceneOwnership"`
+
+## world-convergence — derive environment coordinate content from the scene document
+
+- `environmentContentFromDocument` (function) · `import { environmentContentFromDocument } from "@jgengine/core/editor"`
+- `lakebedFromWaterVolumes` (function) · `import { lakebedFromWaterVolumes } from "@jgengine/core/editor/environment"`
+- `terrainBoundsFromDocument` (function) · `import { terrainBoundsFromDocument } from "@jgengine/core/editor"`
+
+## world-directives — apply a sparse overlay over materialized directive instances
+
+- `applyDirectiveOverlay` (function) · `import { applyDirectiveOverlay } from "@jgengine/core/editor"`
+- `materializeDirective` (function) · `import { materializeDirective } from "@jgengine/core/editor"`
+- `materializeDirectives` (function) · `import { materializeDirectives } from "@jgengine/core/editor"`
+- `materializePopulationDirective` (function) · `import { materializePopulationDirective } from "@jgengine/core/editor"`
+- `materializeScatterDirective` (function) · `import { materializeScatterDirective } from "@jgengine/core/editor"`
+- `resolveDirectiveFootprint` (function) · `import { resolveDirectiveFootprint } from "@jgengine/core/editor"`
+
+## world-shards — decode an untrusted world manifest with per-field diagnostics
+
+- `decodeWorldManifest` (function) · `import { decodeWorldManifest } from "@jgengine/core/editor"`
+- `loadWorldDocument` (function) · `import { loadWorldDocument } from "@jgengine/core/editor"`
+- `selectWorldShards` (function) · `import { selectWorldShards } from "@jgengine/core/editor"`
+- `shardMatchesQuery` (function) · `import { shardMatchesQuery } from "@jgengine/core/editor"`
+- `singleShardWorldManifest` (function) · `import { singleShardWorldManifest } from "@jgengine/core/editor"`
+- `splitEditorDocumentIntoShards` (function) · `import { splitEditorDocumentIntoShards } from "@jgengine/core/editor"`
+
+## world-streaming — schedule shard load/unload by camera proximity
+
+- `createWorldStreamer` (function) · `import { createWorldStreamer } from "@jgengine/core/editor"`
+- `shardDistance` (function) · `import { shardDistance } from "@jgengine/core/editor"`

package/skills/jgengine-editor/reference.md

@@ -1,3 +1,13 @@
+# Editor RPC/CLI and agent panel
+
+## Headless CLI persistence
+
+`bun packages/editor/src/mcp/cli.ts --game <id> --rpc '<json>' … --save` runs the RPC batch on one
+in-memory session and, when every RPC succeeds, writes the session document to
+`Games/<id>/src/editor.scene.json` (dev-save format: 2-space JSON + trailing newline, identical to
+the GUI's Ctrl+S through `devSavePlugin`). Without `--save`, `--rpc` mutations are discarded on
+exit — use it for read-only inspection only, or capture `export_document` yourself.
+
 # Editor agent panel (embedded)
 
 Toolbar **Agent** opens a dockable chat panel in `EditorChrome`. Tool calls use the same editor RPC verbs as the MCP/CLI bridge and the GUI — one session undo stack, interleaved with human edits.
@@ -30,6 +40,15 @@ Content-Type: application/json
 
 Each `toolCalls[].name` is an editor RPC method (`set_transform`, `select`, …). The panel runs them via `routeToolCall` → `EditorHostApi.handle`.
 
+## Bridge reliability
+
+The bridge is trustworthy so agents author instead of hardcoding — every path is honest about failure:
+
+- **Rejected mutations return `ok:false` with a reason.** A locked/cyclic `set_transform`, a `set_parent` that would form a cycle, a collection/prefab verb targeting a missing id, and a batch verb that matches nothing all fail loudly — never a phantom `{ok:true}`.
+- **One decode/migrate boundary.** `decodeEditorDocument` (`@jgengine/core/editor`) validates every field with a path-specific diagnostic (`$.markers[2].position`) and migrates forward; `import_document` and a `push_document_patch` **snapshot** both clear it, so a malformed or old document fails or migrates loudly rather than corrupting a live session.
+- **Document-global id uniqueness.** Placeable ids (markers/volumes/paths/notes) are one namespace: adds re-id on collision, and a single imported document that reuses an id is rejected with its path — a duplicate-id import is impossible. Combine paths (`mergeEditorDocuments`, duplicate, overlay) re-id instead.
+- **Schema-validated input.** `decodeEditorBridgeRequest` type-checks each field a method understands against the per-method schema before it reaches `handle` — a fuzzed value (string where a number belongs, scalar where an object belongs) is rejected at the `--rpc`/HTTP/stdio/agent-tool boundary, never cast in blind. Missing/unknown fields are left to `handle`'s guards so the boundary stays forward-compatible.
+
 ## Pure API (`@jgengine/editor`)
 
 ```ts
@@ -63,6 +82,53 @@ routeToolCall(api, { id: "1", name: "set_transform", arguments: { id: "boss", x:
 
 Commands: `/help`, `/status`, `/summary`, `/selection`, `/frame`, `/undo`, `/redo`, `/clear`, `/select <id…>`, `/goto <id>`, `move <id> <x> <y> <z>`.
 
+## Data catalogs & entity definitions
+
+The **Data** tab (`CatalogsPanel`) edits gameplay tuning rows that persist on the scene document
+(`EditorDocument.catalogs`). Two kinds of catalog feed the tab, merged by
+`resolveCatalogDefinitions(document, gameDefinitions)`: **game-exported** catalogs whose schema lives
+in code (a game's `editorCatalogs` export, `EditorCatalogDefinition[]`: `{ id, label, schema:
+ParamSchema, entries }`, wired via a `defineGame`-sibling module export passed as the `catalogs` prop —
+the scaffold's `main.tsx` passes `catalogs={editorCatalogs}`), and **editor-authored** catalogs created
+entirely in the editor. A game def always wins on id collision; a document catalog is surfaced only when
+it carries its own `schema`.
+
+Beyond tuning existing rows the tab **authors catalogs and schemas**:
+- **Create a catalog** — the `＋ New catalog` form takes an id (+ optional label) and dispatches
+  `addCatalog` with an empty `schema: { fields: [] }`. The document now *carries the schema*
+  (`EditorCatalogData.schema`/`label`), so an editor-only catalog round-trips through save/reload and
+  drives the default `content.ts` path with no game code.
+- **Author schema fields** — for document-authored catalogs (`data.schema !== undefined`; game-exported
+  catalogs stay read-only since their schema is in code) the field editor adds/renames/removes fields
+  (key, type over `ParamField["type"]`, default, min/max). Every field mutation rebuilds the whole
+  `fields` array and dispatches one `setCatalogSchema`, whose reducer **re-parses every row's `meta`
+  against the new schema** via `parseParams`: removed keys drop, added keys default in, range/number
+  values clamp. One undoable step.
+- **Author rows** — `+ Row` adds a schema-defaulted entry; each row has a remove (`×`).
+
+Agents/CLI drive the same edits: `add_catalog` / `remove_catalog` / `set_catalog_schema` for the
+catalog + schema, and `add_catalog_entry` / `remove_catalog_entry` / `set_catalog_entry` for rows
+(alongside `list_catalogs`, `get_catalog_entry`). A catalog added via `add_catalog` is RPC-addressable
+immediately (the host recomputes merged defs per request). New-row meta is seeded from the catalog
+`ParamSchema` defaults and validated before it lands. Values and document-carried schemas save into
+`editor.scene.json` → `catalogs`.
+
+**Entity definitions** are a data catalog: the well-known `ENTITY_CATALOG_ID` (`"entities"`) catalog,
+whose rows carry role/health/speed/scale per `entityDefinitionSchema`. `entityEntryFromCatalog(document,
+catalogId, definitions?)` (`@jgengine/core/editor`) turns a row into the runtime
+`GameContextEntityEntry` the default `content.ts#entityById` returns — so a `mob`/`boss` marker whose
+`catalogId` names an entities row spawns with the stats/speed tuned in the editor, no game TS. It
+prefers a document-carried `entities` schema over `entityDefinitionSchema` when the document authored
+one, so a re-authored entity field set drives the parse.
+`authoredEntitySpawns(document)` (`@jgengine/core/world/authoredEntities`) yields the spawn plan
+(`{ markerId, catalogId, position, rotationY }`) the scaffold `loop.ts` feeds to
+`ctx.scene.entity.spawn`. Author entities in the editor (place a marker → Data tab → tune the row →
+save); never hardcode entity stats where the document should own them.
+
+## Asset import
+
+Dropping a `.glb`/`.gltf` into the editor persists it durably, but where depends on the project shape (`editorHostPlugin`, `@jgengine/node`). A **standalone folder workspace** copies the bytes into the scanned asset folder and re-lists them under a scan-stable id (`importEditorAsset`); the id comes from the file's workspace-relative path, so a placement referencing it resolves after reload. A **promoted game** (one with a typed `src/game/assets.ts` catalog — `isPromotedProject`) instead copies the bytes into `public/<basePath>/imported/` and rewrites `assets.ts` to add a durable `extras` entry to its `buildCatalog({ extras })` call (`importPromotedAsset` → `upsertCatalogExtra`), so the **shipped** game serves and resolves the asset through its own typed catalog rather than a dev-only route. The id matches what a folder rescan would produce, the rewrite is idempotent (re-import of the same id collapses to a single entry), and an unparseable or multi-`buildCatalog` source throws so the host falls back to the folder-scan import rather than corrupt the file.
+
 ## Grid / tile layers
 
 Grid-addressed content (rooms, tactics maps, farms, nav/rule layers) lives on the scene document as
@@ -88,3 +154,24 @@ author the grid and read it at runtime.
   `importCsvGrid`/`exportCsvGrid` (value id per cell). ASCII/CSV are import paths **into** the grid
   document, never the canonical representation — `migrateGridLayer` normalizes and version-migrates
   any layer from disk or an adapter.
+
+## Minimap bake (#1036)
+
+`bake_minimap` rasterizes the authored terrain into a top-down PNG stored on the document as
+`EditorDocument.minimap: EditorMinimapBake` (`{ background: "data:image/png;…", bounds }`). The pure,
+deterministic core rasterizer is `bakeMinimapFromDocument` (`@jgengine/core/editor/index`); the RPC
+handler composes the live viewport's base ground field with `document.terrain` and dispatches the
+undoable `setMinimapBake` command. Runtime feeds the stored `background`/`bounds` straight into the
+`Minimap`/`WorldMap` props — **no re-rasterization at runtime** (see `jgengine-ui`).
+
+- **Live-viewport only.** The bake needs the mounted editor world's composed height/normal sampler
+  (`EditorHostApi.getTerrainSampler`, registered by `EditorWorldOverlay` while the viewport is
+  mounted). It is **not** a headless CLI/MCP verb: with no viewport the sampler is null and
+  `bake_minimap` returns `{ ok:false, error:"bake_minimap needs the live editor viewport" }`. To bake
+  a committed scene offline, run a deterministic node script that rebuilds the base field with
+  `groundFieldFor(world)` and calls `bakeMinimapFromDocument` (see
+  `scripts/bake-claudecraft-minimap.ts`).
+- GUI: the Terrain panel's **Bake minimap** button calls `bake_minimap` and surfaces any `ok:false`
+  error inline.
+- RPC/CLI verb: `bake_minimap` (optional `padding`, `resolution`, `waterLevel`). The bake path uses
+  no `Date`/`Math.random`, so the same scene + sampler always bakes byte-identical output.

package/skills/level-design/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: level-design
+description: Design, audit, author, implement, and validate readable levels, worlds, encounters, navigation, and pacing.
+---
+
+# Level design
+
+## Ownership
+
+Own the spatial realization of game design: player metrics, topology, routes, landmarks, gates, encounter geometry, challenge sequencing, exploration, pacing, recovery, and spatial storytelling. Use `game-design` for the player promise and loops, `jgengine-editor` to author space, and `jgengine-world` to consume it.
+
+All authorable world content belongs in `editor.scene.json`, changed through the editor GUI or RPC/CLI. Never hand-edit the document or keep geometry, paths, spawns, zones, objectives, terrain, foliage, encounters, or coordinate arrays in code. File an editor `[FEATURE]` issue before any fallback.
+
+Read [references/application-playbook.md](references/application-playbook.md) only when the task explicitly calls for spatial design depth — a level/world design brief, an audit or redesign, or "make this fun/better" work; it is not a mandatory step of creating a game. Read [references/live-editor-loop.md](references/live-editor-loop.md) whenever live captures, an editor-agent handoff, or iterative scene improvement is involved. Read [references/field-guide.md](references/field-guide.md) for metric families, topology, pacing, genre lenses, accessibility, and research.
+
+## Choose the mode
+
+### Greenfield
+
+Measure the real controller, camera, interaction, combat, AI, and network constraints in an authored metric gym. Produce a topology graph, critical/optional route model, beat sheet, learning sequence, encounter cards, authoring plan, and falsifiable completion scenario before art production.
+
+### Existing game
+
+Start with a spatial-truth audit. Inventory every source of coordinates and semantics; report any gameplay placement outside `editor.scene.json` as a blocking ownership defect. Reconstruct the critical path and representative optional path from scene data and live play. Measure travel, decision, encounter, retry, and recovery time. Inspect first-look orientation, reverse navigation, affordances, spawn safety, combat positions, pacing contrast, and visual hierarchy.
+
+“Improve with level design” is an authoring and implementation request. Do not stop at a map critique: select the highest-leverage route/zone/encounter slice, author the change through editor operations, connect runtime semantics, and prove it in play.
+
+For a live editor handoff, send evidence and an executable authoring contract—not an aesthetic request. Require the editor agent to inspect authority, document revision, ids, layers, assets, runtime state, and tool support before mutation; apply one coherent hypothesis through undoable operations; then return the exact revision/change log for replay and comparison. Stop when the live editor is not connected to the runtime's authoritative scene or the required operation is unsupported.
+
+## Required output contract
+
+Make every level-design pass yield:
+
+1. **Spatial truth audit:** scene counts and semantic kinds plus every code-owned coordinate table, generated placement, or duplicated position that must migrate.
+2. **Metric sheet:** measured movement, camera, interaction, weapon/AI, readability, density, performance, multiplayer, and retry constraints with units.
+3. **Topology and journey:** nodes/edges, critical and optional routes, gates, returns, landmarks, expected traversal times, and first-minute/mission/campaign beats.
+4. **Zone/encounter diagnosis:** purpose, entry knowledge/state, choices, geometry, actors, escalation, resources, exits, failure/reset, reward, and downstream change.
+5. **Bottleneck ranking:** observed symptom, player consequence, root cause, evidence, reach, confidence, effort, dependencies, and ownership.
+6. **Editor change set:** exact semantic ids/kinds and operations to add/move/remove for paths, markers, zones, spawns, objectives, checkpoints, props, and terrain—without putting coordinates in code.
+7. **Acceptance evidence:** document assertions, route/encounter tests, fresh-player play scenario, pacing/wayfinding thresholds, inspected screenshots, and before/after comparison.
+
+## Execution rules
+
+- Graph before geometry; graybox before art; gameplay and wayfinding before decoration.
+- Present decision-relevant information before commitment. Make alternate routes differ in risk, cost, verbs, information, reward, or experience.
+- Sequence teaching through cue, safe use, feedback, independent test, combination, transformation, and mastery as the audience requires.
+- Align composition, landmark, value/color, motion, audio, affordance, path shape, and optional UI guidance. No marker can repair contradictory space.
+- Design pacing across separate threat, motor, cognitive, navigation, emotional, resource, and social axes. Constant pressure or empty traversal is not pacing.
+- Make every encounter support intended verbs, counterplay, retreat, fair spawns, recovery, and bounded performance.
+- Populate only after the graybox survives play. Preserve silhouettes, safe footing, goals, threats, interactables, teams, and traversal boundaries through art passes.
+
+## Completion
+
+An audit or prettier screenshot is not completion for a build/improve request. Finish when the scene document owns spatial truth; a fresh target player can orient, choose, act, recover, and complete the scenario without coaching; the route has intentional decisions and pacing; encounter exploits and alternate states are tested; and `jgengine-verify` records document, gameplay, and inspected visual evidence.

package/skills/level-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Level Design"
+  short_description: "Design readable, paced, playable spaces"
+  default_prompt: "Use $level-design to observe this world live, brief and drive the editor agent through an authoritative scene change, then replay the same journey and prove the result."

package/skills/level-design/references/application-playbook.md

@@ -0,0 +1,192 @@
+# Applying level design
+
+Use this playbook to turn spatial intent or an existing world into editor-authored, playable change. Its purpose is to force concrete topology, authoring operations, and evidence rather than aesthetic commentary.
+
+## Contents
+
+1. Greenfield procedure
+2. Existing-world audit
+3. Spatial truth and metrics
+4. Journey, topology, and beats
+5. Zone and encounter diagnosis
+6. Ranking interventions
+7. Editor change set
+8. Implementation and proof
+9. Failure modes
+
+## 1. Greenfield procedure
+
+Before production art:
+
+1. Import the game-design contract: promise, verbs, repeated decision, loops, target player, and completion proof.
+2. Author a metric gym and measure the actual controller, camera, interaction, combat, AI, and network behavior.
+3. Draw the topology graph with starts, goals, critical/optional routes, gates, returns, checkpoints, encounters, safe spaces, and rewards.
+4. Write a beat sheet across threat, motor, cognitive, navigation, emotional, resource, and social intensity.
+5. Map where each mechanic is cued, tried safely, tested, combined, transformed, and mastered.
+6. Specify encounter cards and the semantic scene ids they require.
+7. Graybox one route/zone slice in `editor.scene.json` through GUI or RPC/CLI.
+8. Playtest orientation, decisions, traversal, encounter flow, failure, and retry before population and art.
+
+## 2. Existing-world audit
+
+### Inventory spatial truth
+
+Inspect the editor document and source tree. Report separately:
+
+- authored paths and point counts
+- authored markers grouped by semantic kind and catalog id
+- authored zones/volumes, terrain, foliage, annotations, prefabs, and collections
+- gameplay spawns, objectives, NPCs, vendors, loot, checkpoints, gates, and encounters
+- coordinate arrays, centers, offsets, radii, procedural placement, and duplicated positions in code
+- runtime queries that consume stable scene ids/kinds
+
+If gameplay placement exists in code but not the document, mark the spatial-truth audit failed before discussing polish. The repair is an editor-authored migration with stable semantics, not another adapter around coordinate tables.
+
+### Observe live play
+
+Capture and inspect:
+
+- spawn/first frame and the first ten seconds
+- first decision and first objective
+- one critical-path transition
+- one representative encounter and retry
+- one optional route/POI
+- reverse travel or return after state change
+- a dense/peak gameplay frame
+
+Record what dominates the frame, what the player can infer, where they look, where they move, what they miss, and whether UI/world cues agree. Pixel metrics only reject technical blanks; human inspection judges composition and gameplay readability.
+
+## 3. Spatial truth and metrics
+
+### Metric sheet
+
+| Family | Measured values | Source/build | Design consequence | Extreme/accessibility case |
+| --- | --- | --- | --- | --- |
+| movement | speed, acceleration, stop, turn, jump, slope, radius | | | |
+| camera | perspective, FOV, offset, obstruction, sensitivity | | | |
+| interaction | range, use time, target clarity | | | |
+| combat/AI | weapon bands, projectile time, sensing, attack, group size | | | |
+| navigation | path width, sightline, branch/rejoin, landmark range | | | |
+| pacing | time to action, encounter, rest, reward, retry | | | |
+| multiplayer | spawn, regroup, revive, latency, count | | | |
+| performance | actor/object density, nav, draw, simulation | | | |
+
+Derive dimensions from the measured game. Never paste corridor, cover, jump, or arena numbers from another title.
+
+### Travel-time audit
+
+Measure each route at the actual movement speed, including turns, hazards, encounters, and interaction delay. For every interval, classify the intended value: decision, mastery, anticipation, story, resource planning, combat, exploration, recovery, or deliberate atmosphere. Empty time with no purpose is a pacing defect even when the scenery is attractive.
+
+## 4. Journey, topology, and beats
+
+### Topology table
+
+| Node/edge | Purpose | Entry information | Choice/tradeoff | Gate/return | Expected time | Downstream change |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Validate reachability for relevant quest/world states and the reverse direction. Branches must differ in risk, cost, verb, information, reward, story, or experience.
+
+### Beat sheet
+
+| Time/distance | Beat | Threat | Motor | Cognitive | Navigation | Emotion/resource | Evidence/failure signal |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+Look for long flats, constant peaks, unseen goals, repeated rhythms, rewards without anticipation, combat without aftermath, and failure without fast useful retry.
+
+### First-minute contract
+
+The first minute must deliberately answer:
+
+- Where am I and what fantasy am I inhabiting?
+- What can I do now?
+- What should I notice first?
+- What is my immediate goal and why?
+- Where is the first safe experiment?
+- What consequence teaches the rule?
+- What next decision promises depth?
+
+Do not answer all seven with text. Use space, action, feedback, and only the necessary UI.
+
+## 5. Zone and encounter diagnosis
+
+### Zone card
+
+- role in the game/session loop
+- visual/spatial identity and landmark hierarchy
+- entry/exit states and critical/optional routes
+- mechanics introduced, tested, combined, and mastered
+- decision types and exploration rewards
+- pacing arc, safe spaces, checkpoints, and return value
+- content budget and performance peak
+- spatial story and world-state change
+
+Zones that differ only by palette, enemy level, or kill quota do not provide meaningful progression.
+
+### Encounter card
+
+- purpose and target player behavior
+- entry sightline, knowledge, position, resources, and condition
+- initial decision and viable approaches
+- geometry for every intended verb and counterplay
+- actors/hazards, escalation, reinforcement, peak, and resolution
+- cover/refuge, retreat, flank, exits, and exploit risks
+- reward, failure/reset, retry time, and downstream state change
+- semantic scene ids and performance budget
+
+## 6. Ranking interventions
+
+Rank candidate changes with evidence:
+
+| Candidate | Player behavior changed | Reach | Evidence/confidence | Effort/risk | Dependencies | Editor/runtime owner |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Use three horizons:
+
+- **Minimum correction:** migrate invalid spatial ownership or repair a blocking orientation/flow failure.
+- **Strong target:** make one representative route/zone/encounter deliver the intended promise end to end.
+- **Multiplier:** propagate the proven spatial grammar, semantic kinds, encounter kit, and tests across the world.
+
+Prioritize upstream seams and reusable authoring kinds. Do not spend the first pass scattering props across a structurally unchanged map.
+
+## 7. Editor change set
+
+Specify operations semantically, not as code coordinates:
+
+| Operation | Stable id/kind | Purpose/meta | Runtime consumer | Acceptance |
+| --- | --- | --- | --- | --- |
+| add/move/remove path | | from/to, route role | | |
+| add/move/remove marker | | spawn/objective/NPC/checkpoint/landmark | | |
+| add/move/remove zone | | encounter/settlement/safe/gate/resource | | |
+| terrain/foliage/material pass | | traversal/readability/identity | | |
+| prop/asset pass | | cover/affordance/story/landmark | | |
+
+Execute through `jgengine-editor`. Gameplay code queries ids, kinds, layers, and metadata; it does not receive copied positions. File an editor feature issue if a required semantic kind or operation does not exist.
+
+## 8. Implementation and proof
+
+When the user asks to build or improve:
+
+1. Establish before evidence and the acceptance scenario.
+2. Author the chosen graybox and semantics through the editor.
+3. Connect shared runtime/gameplay primitives to the authored ids.
+4. Migrate superseded coordinate tables without changing unrelated content.
+5. Add document assertions for required paths, zones, markers, and ids.
+6. Add deterministic route, encounter, reset, and state-transition tests.
+7. Run a fresh-player or representative play scenario.
+8. Capture and inspect the same views before/after.
+9. Evaluate timing, choice, comprehension, exploit, accessibility, and performance falsifiers.
+
+Evidence should answer the design claim. Scene counts prove ownership, headless tests prove state, a driven playtest proves progress, and inspected screenshots prove visible composition. No one rung proves all four.
+
+## 9. Failure modes
+
+- praising asset count while gameplay semantics remain in code
+- drawing a map without measuring the real controller/camera
+- calling multiple corridors meaningful choice
+- filling empty travel with collectibles instead of decisions or pacing
+- changing color/lighting while topology and encounter flow remain unchanged
+- using objective markers to compensate for contradictory geometry
+- designing only the critical path or only the plan view
+- making every zone the same objective with new enemies and palette
+- reporting an audit after the user asked for improvement
+- claiming success from scene counts, tests, telemetry, or screenshots alone