evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/game-art/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: game-art
+description: "Determine and produce game art in phases: in the first phase, confirm the overall style and deliver game prototype concept art and an element design set; in the second phase, deliver a brief asset requirements list based on the design document and design sheets; in the third phase, deliver a technical art requirements list for rendering, lighting, animation, materials, effects, performance presentation, and similar needs for a 2D or 3D game; in the fourth phase, call available tools item by item according to the developer's selections to generate game assets. Use when game art direction needs to be determined, concept art or design sheets need to be made, assets need to be inventoried, technical art requirements need to be planned, or final game assets need to be generated."
+---
+
+# Game Art
+
+## Goal
+
+Deliver game art outputs in phases: first determine the visual direction, then organize asset requirements and technical art requirements, and finally generate final assets according to the developer's selections.
+
+## Establish Context
+
+Read the game concept, game design document, existing art materials, and reference images provided by the developer. Understand the gameplay, worldview, target platform, aspect ratio, camera perspective, main interfaces, game elements, and the actual use of assets in the game.
+
+Use already confirmed information as the design basis, and confirm key choices that will affect the overall visual direction with the developer.
+
+## Image Generation Confirmation
+
+Before generating game prototype concept art, element design sheets, final assets, or any other images, first explain to the user the images to be generated in this round, the quantity, and the visual direction, and call the image generation tool only after obtaining the user's explicit consent. Reconfirm when the generation scope changes.
+
+After each round of game prototype concept art or element design sheets is generated and shown, the current process must stop immediately and wait for user feedback. Subsequent adjustments, the next round of images, and generation of the asset requirements list, technical art requirements list, or final assets all begin only after explicit user feedback or confirmation is received.
+
+### Parallel Generation Principles
+
+After obtaining the user's explicit consent for the generation scope in this round, use asynchronous MCP calls as much as possible to generate the same batch of mutually independent image assets in parallel; do not wait for one image to finish before starting the next one. First fix the asset ID, prompt, reference image, and output requirements for each call, then start the tasks simultaneously, and after results return, archive and display them by asset ID to shorten the waiting time for the whole batch of assets.
+
+Execute serially only when there is a real dependency, such as when a later item must reference the generation result of an earlier item, cutout must wait for the original image, or the next round must first obtain the user's feedback on the current result. Parallelization must not bypass the image generation confirmation requirements in this section, and must not confuse the correspondence between assets and returned results.
+
+## Phase 1: Art Style and Concept Design
+
+### 1. Determine the Overall Art Style
+
+Determine the game's overall visual direction together with the developer, including:
+
+- art style and subject matter;
+- color, lighting, and visual atmosphere;
+- shapes, linework, materials, and detail density;
+- proportion relationships between characters and environments;
+- camera perspective, perspective method, and composition;
+- a unified visual language across different interfaces and game elements.
+
+When the visual direction still has multiple possibilities, organize a small number of candidate directions with clear differences, explain each one's visual characteristics, and let the developer choose.
+
+### 2. Generate Game Prototype Concept Art
+
+Select game interfaces that can represent the main experience and visual changes, such as the start screen, core gameplay screen, key scenes, pause screen, or results screen. After obtaining the user's explicit consent, call the image generation tools available in the current environment to generate game prototype concept art for different interfaces and show it to the developer.
+
+Concept art presents an overall image close to the finished game, and is used to determine the relationships among composition, color, lighting, scene, characters, UI, and atmosphere. Adjust the concept art according to developer feedback until the overall art direction is confirmed.
+
+### 3. Generate Game Element Design Sheets
+
+Based on the design document and confirmed concept art, identify the characters, enemies, props, buildings, vehicles, mechanisms, environmental objects, and other game elements in the game. After obtaining the user's explicit consent, call the available image generation tools to generate three-view design sheets showing the front, side, and back of each element.
+
+Design sheets use a clear, unified presentation background and accurately show the element's silhouette, proportions, structure, colors, materials, and key details. Elements with different forms, equipment, or growth stages should show their corresponding variants separately.
+
+In subsequent design sheets, continue referencing the confirmed concept art and design sheets so different elements maintain the same art style. Use images confirmed by the developer as visual references when generating final assets.
+
+This phase delivers the confirmed game prototype concept art, game element design set, and overall art direction.
+
+## Phase 2: Asset Requirements List
+
+Before generating final assets, list all identifiable asset requirements based on the game design document, prototype concept art, and element design sheets. The asset list should cover the visual content actually used by the game, and expand concrete types according to gameplay, for example:
+
+- game background images;
+- independently movable multilayer parallax background images;
+- game maps;
+- tiles used by tile maps;
+- static game element images such as characters, objects, props, and environmental decorations;
+- sequence-frame animations for dynamic elements such as characters, enemies, and mechanisms;
+- effects, icons, and other visual assets needed by gameplay;
+- static 3D models;
+- dynamic 3D models with skeletons and animations.
+
+For dynamic elements, separately list idle, movement, attack, hit, death, or other motion states actually needed by gameplay. Each state is an independent asset item.
+
+The asset list keeps only the information needed to identify assets. Assign a stable ID to each asset, and write its type and name; add action state, direction, or variant only when needed to distinguish assets.
+
+```markdown
+# Game Asset List
+
+- [ ] ART001 [<type>] <asset name>
+- [ ] ART002 [<type>] <asset name> (<action state, direction, or variant>)
+```
+
+This phase delivers the asset list and has the developer confirm which assets need to be generated.
+
+## Phase 3: Technical Art Requirements List
+
+Based on the target engine, technology stack, runtime platform, visual target, and the already confirmed concept art and design sheets, organize the technical art requirements needed for a 2D or 3D game to achieve the target art effects.
+
+The requirements list is determined according to the game's actual presentation and may include:
+
+- sequence frames, skeletal animation, UI transitions, and feedback animations;
+- layers, masks, blend modes, cameras, and parallax presentation;
+- render pipeline, color space, resolution, pixel density, and anti-aliasing;
+- realtime lighting, baked lighting, shadows, ambient light, reflections, and fog effects;
+- material system, shaders, surface presentation, and special material effects;
+- tone mapping, bloom, depth of field, ambient occlusion, and other post-processing effects;
+- particles, trails, decals, and other realtime visual effects;
+- model polygon count, texture size, texture channels, compression, LOD, and lightmaps;
+- frame rate, video memory, batches, and visual quality tiers on the target platform.
+
+The technical art list keeps only ID, type, requirement name, and target effect. Key engine, platform, or performance constraints are added only when they affect the implementation method.
+
+Output the requirements list in the following format:
+
+```markdown
+# Technical Art Requirements List
+
+- TA001 [<animation / rendering / lighting / material / post-processing / effects / performance>] <requirement name>: <target effect>
+- TA002 [<type>] <requirement name>: <target effect> (<necessary constraints>)
+```
+
+Assign stable IDs to technical art requirements. This phase delivers the technical art requirements list and has the developer confirm it.
+
+## Phase 4: Generate Assets Item by Item
+
+According to the items selected by the developer from the asset list, after obtaining the user's explicit consent, call the generation or image editing tools suitable in the current environment to generate assets. For the same batch of mutually independent items, prefer asynchronous MCP parallel calls; items with reference image, cutout, or confirmation dependencies should be executed in dependency order. During generation, reference the confirmed concept art, element design sheets, and related technical art requirements, and determine aspect ratio, size, transparent background, perspective, layering method, and frame layout according to the asset's use in the game.
+
+After each asset is completed, directly show the generated result, mark the corresponding asset ID, and continue adjusting or generating the next item according to developer feedback. Completed assets are marked with `[x]` in the asset list.

package/dist/skills/en-US/game-art/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Game Art"
+  short_description: "Determine the game art style in phases, organize asset and technical art requirements, and generate final assets"
+  default_prompt: "Please use $game-art to help me determine the overall art direction for the game, first confirm the image generation plan with me, and stop after each round of concept art or design sheet generation to wait for my feedback."
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/en-US/game-asset-align/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: game-asset-align
+description: Maintain 3D canonical asset alignment among Three.js, Godot, and Blender. Whenever Tripo/generated model intake, orientation/scale/pivot repair, visual and semantic checks, cross-engine import inconsistencies, asset repair status, or ongoing acceptance are involved, this skill must be used first.
+---
+
+# Game Asset Align
+
+## Ownership
+
+This skill owns the scene export contract and the asset alignment and repair lifecycle. `godot-3d-game` and `threejs-3d-game` consume the package confirmed for the current target; Blender provides the modeling source scene, and the exporter is responsible for generating verifiable snapshots.
+
+Only Three.js, Godot 4, and Blender within the current plugin scope are supported. Do not add Unity or Unreal branches.
+
+## Required workflow
+
+Use the local CLI by default. Read the [CLI contract](references/tool-contract.md) for the launcher: `evomeme` below abbreviates `npx -y evomeme@latest` or a local build of the same version. Supply `--workspace` and use `--json` for machine-readable results. Keep Stage running in a persistent session; return its URL when startup completes and run subsequent commands in another terminal.
+
+1. Save a complete Blender scene as `.blend` first, then call `evomeme scene export "<scene.blend>" --id <id>` to automatically generate a source snapshot, GLB, camera reference images, and scene contract; see [Blender scene modeling and export](references/blender-scene-pipeline.md) for the flow. Existing standalone GLB/GLTF files are ingested with `evomeme asset import "<model.glb>" --id <id>`.
+2. **After Blender modeling or modification, the Stage board must be opened first, and the next engine-import step is allowed only after the user confirms the current version.** Call `evomeme asset review <id> --workspace "<workspace>" --json` to check format and dependencies, then call `evomeme stage --asset <id> --workspace "<workspace>" --target <target> --json`. `target` is `three_js` or `godot`. View Blender and the target engine's native image from the same camera position, and check space, structure, materials, and lighting.
+3. Use `evomeme asset repair <id>` for origin/grounding repair; perform other mesh edits in Blender and re-export, following the [repair policy](references/repair-policy.md). Repair invalidates old recipes and requires Stage acceptance again.
+4. Only after the user clicks **"Confirm current version, allow import"** in Stage may export/sync/handoff be called. Tool returns indicating that the board has launched, the model loaded successfully, the format check passed, or `alignment.ready=true` cannot replace confirmation. Do not click on the user's behalf, fabricate view/confirmation records, bypass the gate with `verified_by=spec/user_board`, or manually copy assets into the engine. While waiting for confirmation, work that does not depend on import may continue.
+5. Only one alignment root node is allowed in the engine; adding rotation, scale, or position compensation again in gameplay, animation, or entity scripts is prohibited.
+
+`asset.json` v1 can be read, but cannot enter the engine directly. After being saved again, it is upgraded to v2 repair status.
+
+Both export and sync forcibly check confirmation for the current Stage version; Godot sync also requires the corresponding confirmation from the Godot native preview, and a Three.js image cannot replace it. After modifying the model, contract, textures, Godot profile, materials, lighting, or display implementation, Stage must be reopened, viewed, and confirmed; old handoff packages retain their original version. For Godot configuration and preview flow, see [Godot basic visual alignment](../godot-3d-game/references/appearance-alignment.md).
+
+## Routing references
+
+- For current single-scene comparison and historical compatibility interface notes: read [lightweight-review.md](references/lightweight-review.md).
+- For image-reference modeling, complete Blender scene export, and procedural material baking: read [blender-scene-pipeline.md](references/blender-scene-pipeline.md).
+- When v2 fields, status derivation, or version invalidation need to be understood: read [alignment-contract.md](references/alignment-contract.md).
+- When deciding whether to change metadata, wrapper, or Blender geometry: read [repair-policy.md](references/repair-policy.md).
+- When judging "looks consistent" or saving acceptance evidence: read [visual-review.md](references/visual-review.md).
+- When comparing what Three.js, Godot, and Blender can do: read [engine-capabilities.md](references/engine-capabilities.md).
+- When creating, replacing, or migrating canonical packages: read [canonical-package.md](references/canonical-package.md).
+- When choosing CLI commands, parameters, or handling gate errors: read [tool-contract.md](references/tool-contract.md).
+
+## Completion gates
+
+- `asset.json` is `evomeme.canonical_asset.v2`.
+- The current target engine has been shown in Stage, and the user confirmation record is for the current revision; only actual confirmation by the original task user allows import to continue.
+- `alignment.overall_status` is `aligned`, and `alignment.ready` is `true`.
+- The recipe binds the current `model.glb` SHA-256 and current intent revision, and includes translation, quaternion, and scale.
+- The four items spatial, structural, semantic, and render are all `aligned` or explicitly justified `waived`.
+- The current single viewport must not describe a loaded display as the visual contract fully passed. If the task separately requires export, continue verifying source, intent, recipe, and the unique wrapper, without compensating Transform in gameplay code.
+- Visual conclusions come from target-engine screenshots or clearly labeled board approximations; do not pass off Blender/Three.js screenshots as Godot results.

package/dist/skills/en-US/game-asset-align/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Game Asset Align"
+  short_description: "Maintain auditable alignment state for generated models across Three.js, Godot, and Blender"
+  default_prompt: "Please use $game-asset-align to inspect this 3D asset package, repair cross-engine orientation, scale, and visual-semantic deviations, and provide a sustainably maintainable acceptance state."
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/en-US/game-asset-align/references/alignment-contract.md

@@ -0,0 +1,61 @@
+# Alignment contract v2
+
+## Source of truth
+
+`asset.json` keeps the v1 flat fields for UI compatibility, but `alignment` is authoritative for engine readiness.
+
+```json
+{
+  "schema": "evomeme.canonical_asset.v2",
+  "forward_axis": "+z",
+  "up_axis": "+y",
+  "pivot": "ground_center",
+  "scale_hint_metres": 1.8,
+  "alignment": {
+    "schema": "evomeme.asset_alignment.v1",
+    "source": { "model_file": "model.glb", "sha256": "…", "bytes": 123 },
+    "recipe": {
+      "source_revision": "…",
+      "intent_revision": "…",
+      "translation_metres": [0, 0, 0],
+      "rotation_quaternion_xyzw": [0, 1, 0, 0],
+      "scale_xyz": [1, 1, 1],
+      "algorithm_version": "evomeme.stage.v2"
+    },
+    "conditions": {
+      "spatial": { "status": "aligned" },
+      "structural": { "status": "aligned" },
+      "semantic": { "status": "aligned" },
+      "render": { "status": "aligned" }
+    },
+    "overall_status": "aligned",
+    "ready": true,
+    "revisions": {
+      "source": "…",
+      "intent": "…",
+      "recipe": "…",
+      "alignment_key": "…"
+    }
+  }
+}
+```
+
+## Four conditions
+
+- `spatial`: position, pivot, grounding, facing, up-axis and size are correct.
+- `structural`: hierarchy, mesh parts, skeleton, sockets and animation bindings remain usable.
+- `semantic`: the object identity and functional details match the request.
+- `render`: materials, visibility, normals, texture assignment and target-engine presentation are acceptable.
+
+Allowed states are `aligned`, `needs_review`, `misaligned`, `stale`, and `waived`. A required aspect is ready only when `aligned` or explicitly `waived` with evidence.
+
+## Revision invariant
+
+An accepted recipe must reference the current source SHA-256 and current intent revision. `alignment_key` binds source + intent + recipe. A model replacement, Blender geometry edit, or intent field change invalidates the prior key. Never copy an old key into a new package.
+
+`ready` and `overall_status` are derived values. Export/sync recomputes the invariant and compares the current model bytes; editing `ready: true` by hand cannot bypass the gate.
+
+## v1 migration
+
+v1 flat fields are parsed for inspection, then represented as `needs_review` with no accepted recipe. Open the Stage, inspect the actual model, and save to produce v2. Do not bulk-mark legacy assets ready without visual evidence.
+

package/dist/skills/en-US/game-asset-align/references/blender-scene-pipeline.md

@@ -0,0 +1,35 @@
+# Blender Source Scene -> Stage -> Engine
+
+## Starting from Images
+
+First read the image, and clarify the subject, proportions, materials, key light, and reference camera position. Model the back side and occluded areas not shown in a single image according to reasonable assumptions, and explain them on delivery. Prefer completing modeling through the currently available Blender MCP; this plugin provides export and acceptance flows, and does not bundle external Blender MCP installation or image-to-3D-model services. When there is no Blender MCP, if local Blender is available, Python modeling may be used; report a concrete blocker only when paths are missing or cannot be executed.
+
+First build the space and camera, output low-cost references for iteration, then refine the model, materials, and lighting. After saving `.blend`, perform the following export. The source scene uses metric units, unit scale=1, and preserves the scene origin; the exporter performs the Blender Z-up to glTF Y-up conversion. Do not rotate the whole world again. Cycles/Eevee and perspective cameras are supported; non-unit camera scale and lens shift will error and must be handled first. External linked libraries and sequences/caches that cannot be packaged should be localized in Blender before export.
+
+## Unified Export Entry
+
+```sh
+npx -y evomeme@latest scene export "<scene.blend>" --id courtyard --workspace "<workspace>" --camera-names Reference,MaterialDetail --quality preview --width 960 --bake-materials --texture-size 1024 --godot-project-dir "<godot-project>" --json
+```
+
+See the [CLI contract](tool-contract.md) for launcher/version and path rules; JSON results are under `data`. Camera names and the Godot project path may be omitted; when there is no camera, a reference camera position is created automatically and overview is completed. At most 6 specified perspective cameras are allowed. `--width` is 320-1920; `--texture-size` is 256/512/1024/2048. When no target project is specified, Godot defaults to Compatibility; `--godot-renderer` may specify mobile/forward_plus/gl_compatibility; preview and sync projects must be consistent.
+
+The exporter reads the saved source file in an isolated Blender process, disables automatic script execution, saves a self-contained source snapshot, and generates the GLB, per-camera Blender native reference images, source feature manifest, and two target profiles. The original file is not modified; unsaved changes in active Blender will not enter the export. Failure does not replace the current package. Use `--replace-existing` to update the same scene; the old package is kept in the returned `data.backup_dir`, and the new version must be confirmed again.
+
+preview uses fast sampling; final preserves the source scene sampling settings. Free-view native preview is still in fast mode and disables depth of field, and cannot be used to prove that the final offline render is fully identical.
+
+## Baking and Source Contract
+
+`--bake-materials` is optional, and only processes supported procedural surfaces directly connected to Principled BSDF; it generates base color, roughness, metallic, and tangent normal maps by object, and creates UVs when necessary. The source `.blend` keeps the original nodes; the exported model uses the baked version. Complex closures, mixed shaders, volumes, and indirect light are not automatically converted by this baking path. Keep the skipped reasons in the report, and do not describe partial object baking as completion of the entire material set.
+
+`scene.contract.json.source_features` uses evomeme.source_scene_features.v1, recording node IDs, object/material associations, procedural nodes, unconverted nodes, baked channels/objects, volumes, world environment, and source render settings. IDs preferably reuse evomeme_node_id; when it is not set, they are derived from asset and object names. If stable IDs across renaming are needed, this property should be set in the source scene.
+
+Standard PBR and lighting facts share one source contract. `runtime/three.profile.json` and `runtime/godot.profile.json` store engine overrides; re-export preserves existing overrides that match the schema, while uncovered lighting is derived from the new source facts. After modifying a profile, update the byte counts and SHA-256 values in contract.files.
+
+Baked materials create an independent runtime material for each object; their exact names are recorded in source_features.materials[].runtime_materials. Use that material_name when setting engine material overrides. The unbaked version uses the actual material names inside the GLB.
+
+## Review and Delivery
+
+Run `evomeme stage --asset courtyard --workspace "<workspace>" --target <target> --json` with target three_js/godot. Keep the foreground session alive and give `data.url` to the user. The board displays mapped, baked, approximated, not yet implemented, and pending-verification items one by one, provides related camera positions, and offers "record repair request." Repair requests are written into the feedback record and require the agent to read and continue modifying; the button does not complete the repair by itself.
+
+After the user views and confirms the current target-engine version, run `evomeme asset sync courtyard --workspace "<workspace>" --target <target> --project "<project>" --json` in another terminal. Three.js games use the generated loadReviewedScene and runtime.render, sharing the display implementation with Stage; Godot uses load_scene and the same native display adapter. After import is complete, re-verify in the actual project. visual_equivalence=not_evaluated in the confirmation record means cross-renderer pixel equivalence was not computed; it does not erase already recorded approximations or missing items.

package/dist/skills/en-US/game-asset-align/references/canonical-package.md

@@ -0,0 +1,26 @@
+# Canonical package
+
+## Required layout
+
+```text
+assets/canonical/<asset_id>/
+  model.glb
+  asset.json
+  preview/
+```
+
+`asset_id` is normalized and stable. `model_file` remains package-relative. Do not reference files outside the package.
+
+An optional `scene.contract.json` may define camera, world-coordinate and display-profile supplements. Its file manifest uses relative paths, byte sizes and SHA-256 hashes. Export/sync verifies the whole manifest and rejects traversal, missing files, stale hashes and coordinate conflicts.
+
+For a complete Blender source scene, `evomeme scene export "<scene.blend>" --id <id>` creates this contract, `source/scene.blend`, per-camera references and both engine profiles automatically. See [Blender scene pipeline](blender-scene-pipeline.md). `source_features` makes unsupported/approximate effects visible in Stage; a loaded GLB alone does not demonstrate material or lighting equivalence.
+
+## World-coordinate scenes
+
+For a complete meter-scale map already exported as Y-up, use `up_axis=+y`, `forward_axis=-z`, `pivot=origin`, `scale_hint_metres=null` and zero offsets unless evidence says otherwise. Do not center a whole world or normalize it by height.
+
+## Replacement and history
+
+`replace_existing=true` may reuse the asset ID and descriptive metadata, but new model bytes create a new source revision. Previous recipes and evidence become stale. Keep repair reports/backups inside the package repair area; never treat a backup as the active `model.glb`.
+
+The bounded alignment history explains creation, migration, acceptance and invalidation. It is an audit aid, not a substitute for current revision checks.

package/dist/skills/en-US/game-asset-align/references/engine-capabilities.md

@@ -0,0 +1,14 @@
+# Engine capabilities
+
+| Component | Owns | Must not own |
+|---|---|---|
+| Stage | Three.js live preview, native Godot/Blender preview, bounds/TRS, explicit user confirmation before import | substituting Three.js frames for Godot, agent acceptance on behalf of the user |
+| Blender | topology, normals, origin baking, mesh cleanup, GLB re-export | final engine readiness, hidden per-engine orientation |
+| Godot 4 | GLB import, one runtime wrapper, gameplay integration, target render/physics QA | guessing authored axes, accumulating compensation transforms |
+| Three.js game | one runtime wrapper, web presentation and gameplay QA | a second canonical schema or per-entity hard rotations |
+
+Tripo and other generators are sources, not alignment authorities. Preserve their task/model/version metadata in provenance, but compute readiness from the emitted file and current user intent.
+
+Use GLB as the canonical mesh payload. Blender source files may be retained as provenance or repair artifacts, but engines consume the package, not an arbitrary `.blend` working file.
+
+Unity and Unreal are intentionally outside this plugin plan. Do not add placeholder adapters that appear supported but bypass validation.

package/dist/skills/en-US/game-asset-align/references/lightweight-review.md

@@ -0,0 +1,34 @@
+# Stage Board Confirmation and Engine Import
+
+After Blender modeling or modification, the Stage board must be opened to view the current version, and the user must click "Confirm current version, allow import" before the next import step can proceed. Merely launching the board, passing the format check, saving the technical alignment state, or ready=true cannot release the gate.
+
+Use the launcher in the [CLI contract](tool-contract.md). Keep Stage in its own persistent foreground session; share `data.url` from the JSON startup result immediately. Exit 0 from `asset review` only means inspection completed; read `data.technical_ok` and `data.confirmation.status`.
+
+## Sequence
+
+1. A complete Blender scene uses `evomeme scene export "<scene.blend>" --id <id>` to generate a canonical package, source snapshot, contract, and native reference images; an existing GLB can be ingested separately.
+2. `evomeme asset review <id> --workspace "<workspace>" --json` checks the model format and file digests.
+3. `evomeme stage --asset <id> --workspace "<workspace>" --target <target> --json` opens the single-scene viewport. `target` is three_js or godot.
+4. Compare Blender and target-engine native render from the same camera position and with the same aspect ratio, checking space, structure, materials, and lighting. Godot uses a temporary native preview project and does not write to the final game project in advance.
+   View the mapping, baking, approximation, and missing states under "effect conversion and pending-verification items"; related camera positions can be jumped to, or repair requests can be recorded. The states come from source features and adapter capabilities, not from image similarity scoring.
+5. The user confirms on the page. Tools and agents must not click on the user's behalf, and must not directly construct confirmation files.
+6. Run `evomeme asset sync <id> --target <target> --project "<project>" --workspace "<workspace>" --json`. Three.js confirmation cannot replace Godot confirmation; export likewise requires the current Stage confirmation.
+
+When modification is needed, return to Blender or update the engine profile, then reload, view, and confirm again. The page keeps a single-scene scope and does not add asset lists, part editing, or gameplay.
+
+## Environment
+
+Blender is configured through EVOMEME_BLENDER / BLENDER_PATH; Godot is configured through EVOMEME_GODOT / GODOT_PATH or godot on PATH. While waiting for native preview, do not pass off an old image as the current view; if it fails, the current image cannot be confirmed.
+
+## Records and Invalidation
+
+.review/stage-view.json records the actual board camera position, target engine, and version. Godot views also bind the native render receipt and profile key.
+.review/confirmation.json records user confirmation, current resource/display implementation summary, complete TRS, camera position, screenshot summary, and technical report.
+
+Changes to the model, asset.json, scene contract, textures, Godot profile, material/lighting configuration, or display module make confirmation stale. export/sync checks the current confirmation and alignment recipe before writing to the target; setting verified_by or directly changing ready cannot bypass it.
+
+## Handoff and Scope
+
+Browser handoff only reproduces the confirmed Three.js image; Godot uses `evomeme asset sync <id> --target godot --project "<project>"` to output the native loader and display adapter, and does not treat the Three.js handoff image as Godot acceptance.
+
+The Godot basic flow preserves GLB PBR, rebuilds lighting, environment, exposure, and camera, and supports material parameter calibration. Area lights use explicitly marked approximations; Three.js-specific baked shaders/LUTs will not be executed automatically in Godot. After the user confirms asset display, game integration and gameplay still require target-engine re-verification.

package/dist/skills/en-US/game-asset-align/references/repair-policy.md

@@ -0,0 +1,30 @@
+# Repair policy
+
+Choose the shallowest layer that fixes the actual defect while preserving one canonical result.
+
+## Metadata repair
+
+Use the Stage or `evomeme asset align <id>` when geometry is sound but authored axes, pivot intent, scale target, semantic type or review evidence are wrong. Save a complete wrapper TRS. Do not bake a rotation into gameplay code.
+
+## Wrapper repair
+
+Use the canonical recipe for non-destructive translation, quaternion rotation and scale. The wrapper must be applied exactly once. It is appropriate for grounding, recentering, authored-forward conversion and size normalization.
+
+If `pivot=origin` and `scale_hint_metres=null`, a deterministic identity translation/unit scale recipe is possible. Bounds-dependent pivots or height normalization require a measured recipe from the board or another adapter.
+
+## Blender geometry repair
+
+Use `evomeme asset repair <id> --ground true` for the supported origin/grounding repair. It backs up the prior model and writes into the same canonical package. It is not a general topology or normals repair command. Edit detached/duplicate parts, normals, topology, or other export defects in Blender, then re-export. See the [CLI contract](tool-contract.md) for launcher, workspace, and JSON conventions.
+
+Any Blender result changes the source revision and invalidates all prior review states. Reopen the Stage and accept a new recipe before export or sync.
+
+## Never repair here
+
+- player/controller yaw offsets;
+- AnimationTree or animation-track compensations;
+- per-scene scale overrides;
+- a second Godot/Three wrapper;
+- a material tweak claimed as canonical without updating review evidence.
+
+These hide drift and cannot be maintained when the asset is regenerated.
+

package/dist/skills/en-US/game-asset-align/references/tool-contract.md

@@ -0,0 +1,69 @@
+# Local asset CLI contract
+
+## Launching and reading results
+
+Use the CLI by default for local packages, Blender scene export, Stage, and engine sync. Below, `evomeme` is shorthand for `npx -y evomeme@latest`; installing the IDE plugin does not imply a global executable. An available local build can instead use `node "<plugin_client>/dist/index.js"`. Check `asset --help` through the chosen launcher first. Keep the same version for review and sync so display implementation changes do not invalidate confirmation.
+
+All commands accept `--workspace "<workspace>" --json`. The workspace defaults to the current directory. Relative source, `--input`, and `--project` paths resolve from the **command's working directory**, not `--workspace`. Prefer absolute paths when working across directories.
+
+- JSON success: `{"ok":true,"data":...}`; failure: `{"ok":false,"error":{"code":"...","message":"..."}}`.
+- Exit codes: `0` completed, `2` invalid arguments (`INVALID_ARGUMENT`), `1` operation/file failure (`OPERATION_FAILED`).
+- Exit `0` from `asset review` only means inspection completed. Read `data.technical_ok` and `data.confirmation.status` (`unconfirmed` / `confirmed` / `stale`) before proceeding.
+- Stage remains in the foreground. Start it in a persistent terminal/session, return `data.url` when startup output arrives, and keep the session alive during review. Do not wait for process exit. Run subsequent commands in another terminal; Ctrl+C stops Stage when finished. There is no background `start/status/stop` interface.
+
+## Local commands
+
+These 12 asset/Stage capabilities use the CLI and existing business layer. Their MCP implementations and legacy aliases have been removed; there is no compatibility switch or MCP fallback. If the installed version lacks the CLI, use a version containing the commands or an available local build. Gate failures require repair or review.
+
+| CLI (common options omitted) | Purpose |
+| --- | --- |
+| `asset import "<model.glb>" --id <id>` | Import GLB/GLTF |
+| `asset list` | List packages |
+| `asset show <id>` | Read a package |
+| `asset align <id> --input "<alignment.json>"` | Technical alignment |
+| `scene export "<scene.blend>" --id <id>` | Export a saved Blender scene |
+| `stage --asset <id> --target <target>` (three_js / godot) | Stage review |
+| `asset review <id>` | Inspect validity and confirmation |
+| `asset repair <id> --ground true` | Origin/grounding repair |
+| `asset export <id>` | Validate and return the package directory |
+| `asset sync <id> --target three_js --project "<project>"` | Sync to Three.js |
+| `asset sync <id> --target godot --project "<project>"` | Sync to Godot |
+| `asset handoff <id>` | Three.js handoff |
+
+`import` accepts GLB/GLTF; new packages are normally `needs_review`. Add `--replace-existing` only when replacing an existing ID is intended. `show` reads the full package record; `list` reports `alignment_status` and `alignment_ready`. See [blender-scene-pipeline.md](blender-scene-pipeline.md) for scene export options, baking, and backups.
+
+## Technical alignment
+
+`evomeme asset align <id> --input "<alignment.json>" --workspace "<workspace>" --json` writes technical alignment only; it cannot replace Stage user confirmation. The UTF-8 JSON file (optional BOM) contains alignment fields, not `workspace_dir` or `asset_id`. Explicit CLI options override matching file fields. Example:
+
+```json
+{
+  "forward_axis": "-z",
+  "up_axis": "+y",
+  "pivot": "origin",
+  "scale_hint_metres": null,
+  "alignment_recipe": {
+    "translation_metres": [0, 0, 0],
+    "rotation_quaternion_xyzw": [0, 0, 0, 1],
+    "scale_xyz": [1, 1, 1],
+    "algorithm_version": "adapter-name.v1"
+  },
+  "alignment_conditions": {
+    "spatial": { "status": "aligned", "evidence": "measured against reference" }
+  }
+}
+```
+
+Replace example values and evidence with actual measurements. If supplied, a recipe requires complete translation, a nonzero quaternion, and positive scale; `algorithm_version` is optional. Conditions are `spatial`, `structural`, `semantic`, and `render`, with status `aligned`, `needs_review`, `misaligned`, `stale`, or `waived`. Bounds-dependent pivots or scale remain non-ready without a complete recipe; measure through Stage rather than inventing values.
+
+Simple intent can use `--forward-axis -z --up-axis +y --pivot origin --scale-hint-metres null`. Other options include `--type`, `--verified-by`, `--notes`, and `--yaw-offset-degrees` / `--pitch-offset-degrees` / `--roll-offset-degrees`. `verified_by` defaults to `agent_vision`. Consult `asset --help` for command syntax and `asset align --help` for the JSON shape.
+
+## Repair and delivery
+
+- `asset repair` uses local Blender for supported origin/grounding repairs, changes the source, and invalidates alignment. General mesh edits require editing in Blender and re-exporting.
+- `asset export` validates source bytes, readiness, and current Stage confirmation; it returns the package directory rather than creating an archive.
+- Three.js sync writes `public/assets/canonical/<id>/` and generates `src/evomeme-stage/<id>/canonical_loader.js`. Use Three.js 0.170.0, `loadReviewedScene`, and `runtime.render` to retain the reviewed appearance pipeline.
+- Godot sync requires an existing `project.godot`, a matching renderer, and current native Godot Stage confirmation. It writes `assets/canonical/<id>/` and generates the guarded loader and display adapter. Use `load_scene` for scenes and `load_package` for props.
+- Browser `asset handoff` only supports confirmed Three.js versions; use `asset sync <id> --target godot --project "<project>"` for Godot.
+
+Blender modeling/changes require target-engine Stage viewing and user confirmation. Agents must not click for the user or fabricate records. On a gate failure, inspect pending/stale reasons, repair or review, then sync again; do not edit confirmation JSON directly.

package/dist/skills/en-US/game-asset-align/references/visual-review.md

@@ -0,0 +1,26 @@
+# Visual review
+
+## Review sequence
+
+1. Load the exact current `model.glb`; confirm the displayed source revision.
+2. Compare against the user request or versioned reference, not memory.
+3. Inspect front/back/side/top and a gameplay camera view.
+4. Check spatial, structural, semantic and render conditions separately.
+5. Save the measured wrapper TRS and concise evidence.
+6. Verify again in the target engine after sync.
+
+## Practical checks
+
+- Spatial: feet/wheels/base touch the expected plane; forward direction is unambiguous; height and world scale are plausible; maps retain their intended origin.
+- Structural: named parts exist, transforms are not unexpectedly nested, skeleton and sockets remain attached, animations do not jump on frame zero.
+- Semantic: silhouette, part count, handedness, openings, controls, weapon muzzle, seats, doors and other requested affordances are correct.
+- Render: normals face outward, textures resolve, alpha/culling are correct, material response is credible and no parts disappear under the target camera/light setup.
+
+## Evidence quality
+
+Prefer a user-approved board view or target-engine screenshot. Agent visual review is acceptable when the comparison and limitations are recorded. Heuristics alone do not close structural, semantic or render review.
+
+Three.js Stage is a neutral inspection surface, not proof of Godot render parity. Blender Cycles, Three.js and Godot use different shading pipelines. Describe approximations explicitly; do not promise pixel identity unless a target-engine capture was compared.
+
+For `scene.contract.json`, keep reference camera, aspect ratio, near/far and framing fixed during comparison. Do not let auto-frame controls overwrite a contract camera.
+