evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/game-video-cycle/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: game-video-cycle
+description: Use evomeme_extract_video_cycle to extract a candidate loop from an existing video using its first frame as reference, saving one new MP4. Use for repeating idle, walking or rotation actions and looping video backgrounds. Explains detection and extraction, output files, similarity threshold, minimum gap, detection frame rate and seam inspection. Not for generating new motion, finding arbitrary middle sections, repairing seams or exporting frame sheets.
+---
+
+# Video Cycle Extraction
+
+Use `evomeme_extract_video_cycle` to extract a candidate loop from the beginning of an existing video. Inspect whether it starts at a suitable loop pose and contains a complete return to that pose before selecting a similarity threshold and minimum gap. Success means an endpoint met the algorithm's threshold; playback inspection is still needed.
+
+## What it does and produces
+
+MCP and canvas share the `video_cycle` task and `extractVideoCycleAsset`, with the existing `extractVideoCycle` coordinating detection and extraction. Processing is local, without MCP-to-MCP calls or changes to shared task/image algorithms or prompts.
+
+One call:
+
+1. Read the existing workspace video's duration and dimensions.
+2. Generate analysis grayscale thumbnails at a fixed **24 frames/second**, default width 96 pixels with proportional height and a minimum height of 8. These are analysis dimensions, not export dimensions.
+3. Use the first sampled frame as reference. Skip candidate endpoints before `min_gap_sec`, compare each remaining frame's structural similarity to the reference, and stop at the first `score >= threshold`.
+4. Extract **from 0 seconds to the matched time**, re-encode as H.264 and save **one MP4** into `assets/`. Usable audio is encoded as AAC with the segment. Preserve the source and register the task.
+
+The output name is based on `cycle.mp4` with a unique identifier; use the returned path. This is not lossless copying of compressed source bytes. No AI, automatic upload, GIF, transparent video or frame-sheet output. It does not regenerate motion or create a loop through interpolation, reversal, crossfades or audio repair.
+
+In this implementation, “first complete cycle” means **the candidate interval from the video start to the first qualifying match**. It does not skip intros to search arbitrary middle sections, seek the highest score in the entire video or verify a semantically complete action. Similar poses with different velocities, directions or action phases can still match.
+
+## When to use it
+
+| Need or source | Guidance |
+| --- | --- |
+| Repeating idle, walking or rotating motion that returns to its initial pose | Use this tool and check camera, position and background stability. |
+| Multiple repetitions in an existing video, needing the first one | Start with defaults and choose minimum gap from the actual cycle. Exactly one repetition is not guaranteed. |
+| A repeating video background or effect | Try extraction, but camera motion, lighting changes or random particles may prevent a match or leave a visible seam. |
+| A fade-in, title, static hold or unrelated intro at the start | Trim that intro separately, then process the trimmed video. There is no start-time input. |
+| Trimming to specified start/end times only | Use existing video editing capabilities; this tool detects its endpoint and accepts no `start` / `end` inputs. |
+| Generate new looping motion | Use the [video generation skill](../game-video-generator/SKILL.md), setting the first and last frame to copies of the same image or the same asset URL. Extract and inspect afterward when needed. |
+| Convert video into a game sprite frame sheet | This tool supplies only a candidate-loop MP4; frame extraction and sheet layout are separate work. Do not claim a frame sheet was produced. |
+
+Large static backgrounds can mask a small subject's changes, while nearly uniform frames may provide no useful correlation signal. Camera movement, changing backgrounds, subject displacement and brief pauses can affect detection; lowering the threshold does not repair these conditions.
+
+## Parameters and terminology
+
+| Parameter | Actual meaning |
+| --- | --- |
+| `id` | Required existing video asset ID inside workspace `assets/`, such as `assets/idle.mp4`. No images, URLs, absolute paths or Base64. |
+| `threshold` | Default `0.98`, range `0.5–0.999`. Pass a fraction, not `98`. The canvas value 98 corresponds to 0.98 here. |
+| `min_gap_sec` | Default `0.4`, range `0.1–10`, in seconds. How long after the first frame to start comparing candidate endpoints. |
+| `workspace_dir` | Optional absolute workspace root; set explicitly when possible. Defaults to the MCP working directory. |
+
+- **Loop / cycle**: A segment intended to connect naturally when replayed. Similar endpoint images are a useful reference, but motion speed, direction, background and audio must also be continuous. This tool uses only visual similarity to select a candidate endpoint.
+- **Similarity score / NCC (normalized cross-correlation)**: Subtract average brightness from each grayscale thumbnail, divide by its brightness variation, then compare light/dark structure at corresponding positions. Scores nearer 1 indicate more similar structure. This is not an identical-pixel percentage, AI confidence or action-recognition probability. Grayscale downsampling can hide color, small objects and fine detail differences.
+- **Threshold**: Required candidate score. Higher is generally stricter and more likely to fail; lower may accept incomplete actions or visible seams. It does not apply a similarity repair to the video.
+- **Minimum gap**: Avoids immediately treating similar adjacent frames as a full loop. It is not desired duration, maximum search duration or trim start. Too large a value may skip the first real cycle, include multiple cycles or cause failure.
+- **Detection fps**: Analysis samples per second, fixed at 24, with candidate time steps of approximately 1/24 second. Returned `fps` is this analysis value, not the source or exported video's actual frame rate. There is no configurable `fps` input.
+- **Re-encoding**: Compress the extracted images as H.264 and usable audio as AAC inside MP4. Quality, bitrate and file bytes may change. Audio endpoints are not chosen from waveform or beat analysis, and no fades are added automatically.
+
+Source duration must exceed `min_gap_sec + 1/24` seconds or a too-short error is returned. There are no `prompt`, `model`, desired duration, candidate count, audio repair, mute, quality, resolution or custom start/end inputs.
+
+## Invocation
+
+Call `evomeme_extract_video_cycle`:
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "id": "assets/idle.mp4",
+  "threshold": 0.98,
+  "min_gap_sec": 0.4
+}
+```
+
+If inspection confirms that a full action cannot finish within 1.2 seconds, set `min_gap_sec=1.2` to exclude earlier similar frames. This does not set output duration to 1.2 seconds: the tool still finds the first qualifying frame at or after that time. Do not increase the gap arbitrarily just because a short result looks wrong.
+
+If an upstream video generation tool returns only `local_path`, verify it is inside this workspace's `assets/` and derive its actual `assets/...` relative asset ID. Do not pass a remote URL or full local path as `id`, or assume the upstream tool necessarily returned an `asset_id`.
+
+## Outputs
+
+Returns text metadata without embedded video bytes or Base64:
+
+| Field | Meaning |
+| --- | --- |
+| `asset_id`, `local_path`, `mime_type` | New MP4's workspace ID, absolute local path and `video/mp4`. |
+| `source_id`, `operation_id`, `status` | Source video ID, local operation ID and success status. No remote AI `job_id`. |
+| `start`, `end` | Candidate trim times in source-video seconds. `start` is currently always 0. `end-start` is the requested segment duration, not a probe of the exact muxed file duration. |
+| `score` | Correlation of the matched endpoint with the reference frame, not the best score in the whole video. |
+| `fps` | Detection sampling rate, fixed at 24. |
+| `scanned` | Number of candidate frames actually compared, excluding the reference and frames skipped before the minimum gap. Not the source's total frame count. |
+| `threshold`, `min_gap_sec` | Actual similarity threshold and minimum gap. |
+
+No additional width/height, actual export frame rate, `duration`, frame sheet, candidate list or public URL is returned. The shared task's `minGapSec` becomes `min_gap_sec` in MCP output. A similar detection endpoint does not mean the exported last frame is pixel-identical to the first.
+
+## Inspection and integration
+
+Play at least two consecutive repetitions. Check for jumps, pauses, position changes, speed discontinuities, background or lighting flicker, and audio clicks or interrupted rhythm when audio exists. Do not declare a seamless loop based solely on a high `score`.
+
+For an unexpectedly short result, inspect whether static background, an initial hold or a similar half-cycle pose caused an early match. Adjust the minimum gap or raise the threshold only with evidence. When no match is found, check whether the full action returns to the first frame and whether the source is long enough. A modestly lower threshold requires renewed inspection; do not report failure as a successful copy of the full source or automatically use paid generation to replace it.
+
+Use the output MP4 in the webpage or game and enable repeat playback at runtime. That setting controls playback behavior; the file itself does not guarantee an infinite seamless loop. Configure muting in the project if needed, since this tool has no mute parameter. For a public URL, upload the output `local_path` through `evomeme_upload_game_asset`, not the source video's URL.
+
+On failure, inspect the error and task records. No match means no candidate MP4 is exported; an encoding failure may leave an incomplete file. Do not treat residual files as successful outputs.

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Video Cycle Extraction"
+  short_description: "Extract candidate loops and explain scores, timing and seams"
+  default_prompt: "Use $game-video-cycle to inspect an existing video, extract a candidate loop, and explain the interval, similarity score and seam checks."
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/en-US/game-video-generator/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: game-video-generator
+description: Generate one video with evomeme_generate_game_video from a prompt, first/last frames or image/video/audio references. Use for game demonstrations, cutscenes and source footage for character actions. Explains using copies of the same image as both endpoint frames for looping animation, reference URLs, parameters and local video output; does not automatically extract frames, cut out subjects or repair loop seams.
+---
+
+# Game Video Generation
+
+## Action, Output and Use Cases
+
+`evomeme_generate_game_video` (Video Generation) shares the canvas video client functions. It submits a prompt and optional references, waits for completion, downloads one video under workspace `assets/`, and returns its local path and cloud URL. Read the actual format from `mime_type`. Use it for cutscenes, promotional demonstrations or source footage for character actions.
+
+A video contains images changing over time. This tool does not directly produce a character sprite sheet, extract frames, cut out backgrounds or guarantee a seamless loop. Use [Game Images](../game-asset-image-generator/SKILL.md) for static images and [Character Views](../game-character-view-generator/SKILL.md) for multiple orientations.
+
+## References and Terminology
+
+- **First frame**: the desired image at the beginning of the video; use an image reference with `role="first_frame"`.
+- **Last frame**: the desired image at the end; use an image reference with `role="last_frame"`. For looping animation, use a copy of the first-frame image as described below.
+- **Reference image**: constrains appearance, style or setting, using `role="reference_image"`; it does not designate the first frame.
+- **Reference video/audio**: supplies motion or sound references, using `type="video"` or `type="audio"`; the effect depends on model support.
+
+Each `references` item is `{type,url,role?}`. `url` must be an accessible HTTP/HTTPS URL, not an asset ID, local path or Base64. For uploaded attachments or local assets, locate a readable file and copy it under workspace `assets/` without overwriting different content. Upload it through [Cloud Asset Upload](../evomeme-tos-upload/SKILL.md) and use the returned `asset_url`. Reuse existing accessible URLs.
+
+## Key Looping Technique: Use the Same Image for Both Endpoint Frames
+
+**For looping animation, use copies of the same image as the first and last frames so both endpoint references are identical and the action can return to its starting point.** Do not generate two merely similar endpoint images: small differences in pose, position, composition or lighting can disrupt the loop.
+
+In the MCP request, repeat the same actual image URL in two image references, with `role="first_frame"` and `role="last_frame"`. This expresses the identical-copy technique without uploading the image twice. Ask for one complete action cycle, a return to the starting pose and position, and continuous motion across the loop boundary. In-place idle, walk or attack loops should usually also use a fixed camera and consistent background.
+
+```json
+{
+  "prompt": "The reference character completes one full idle breathing cycle in place, fixed camera and consistent background, returning to the first-frame pose and position with continuous motion across the boundary for repeated looping playback",
+  "references": [
+    {"type": "image", "url": "https://example.com/hero-idle.png", "role": "first_frame"},
+    {"type": "image", "url": "https://example.com/hero-idle.png", "role": "last_frame"}
+  ],
+  "generate_audio": false,
+  "workspace_dir": "D:/my-game"
+}
+```
+
+Replace both example URLs with the same real image link. After generation, play at least two consecutive cycles and inspect the join for jumps, pauses or abrupt speed changes. Identical endpoint references constrain the endpoint images; the intervening action and final loop still need inspection.
+
+## Inputs
+
+| Parameter | Required | Meaning |
+| --- | --- | --- |
+| `prompt` | Yes | Describe the subject, start/end of the action, camera motion, scene and style. |
+| `references` | No | Array of `{type,url,role?}`; `type` is `image`, `video` or `audio`. |
+| `ratio` | No | Width-to-height ratio: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` or `adaptive` (service-selected adaptation). |
+| `duration` | No | Seconds: 4, 5, 6, 8, 10, 12 or 15; `-1` selects automatic duration. |
+| `resolution` | No | Resolution tier: `480p`, `720p` or `1080p`. |
+| `generate_audio` | No | Generate audio; default `true`. Set `false` for silent footage. |
+| `watermark` | No | Add a watermark; default `false`. |
+| `seed` | No | Nonnegative integer random seed; controls randomness without guaranteeing identical repeated outputs. |
+| `video_model` | No | Currently supports `doubao-seedance-2-5-260628`, also the default. |
+| `workspace_dir` | No | Absolute current workspace root; pass it explicitly. |
+
+The service selects defaults for omitted ratio, duration and resolution. Pass explicit values when requirements are known.
+
+```json
+{
+  "prompt": "The reference character swings its sword once in place, fixed camera, consistent design and background",
+  "references": [{"type": "image", "url": "https://example.com/hero.png", "role": "first_frame"}],
+  "ratio": "1:1",
+  "duration": 4,
+  "resolution": "720p",
+  "generate_audio": false,
+  "workspace_dir": "D:/my-game"
+}
+```
+
+The example URL illustrates the format. Use an actual upload result or accessible reference URL for calls.
+
+## Outputs and Errors
+
+Success returns text containing `job_id`, `local_path`, `mime_type`, `bytes`, `asset_url`/`tos_url`, `status`, `attempts`, `model`, `ratio`, `duration` and `resolution`. Record the path and URL; do not put video bytes or Base64 into the conversation. This video tool does not return the image tools' `asset_id` field.
+
+Failures return `isError: true` with the specific error. Use [Login Recovery](../evomeme-login/SKILL.md) for authentication errors. Do not report failed generation as successful or blindly repeat a submission after an interrupted wait.

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Game Video Generation"
+  short_description: "Generate game videos with clear references and outputs"
+  default_prompt: "Use $game-video-generator to generate a game video with a clear purpose, action, optional frame references and output path."
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/en-US/godot-3d-game/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: godot-3d-game
+description: Build and maintain 3D games with Godot 4, and consume EvoMeme canonical asset packages. Use when the work involves Godot scene structure, GLB import, alignment wrappers, skeleton animation, colliders, builds, or 3D runtime QA; when assets are not ready, you must return to game-asset-align.
+---
+
+# Godot 3D Game
+
+## Responsibility boundary
+
+Godot is the shipping runtime, not an asset-orientation guesser. The source of truth for asset alignment belongs to `game-asset-align`; this skill is responsible for import gates, the single wrapper, game-scene integration, and real-device Godot validation.
+
+## Required workflow
+
+Use the local CLI by default. Read the [CLI contract](../game-asset-align/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. Confirm that the project root contains `project.godot`, and read the reference files relevant to the task.
+2. **After Blender modeling, you must open the Stage board first, and only import into Godot after confirmation.** Read the canonical `asset.json` and run format checks, call `evomeme stage --asset <id> --workspace "<workspace>" --target godot --json`, and compare space, structure, materials, and lighting between Blender and the native Godot view in Stage. The user clicks "Confirm current version, allow import". You must not click for the user, write confirmation files, or skip this using a technical ready status.
+3. Call `evomeme asset sync <id> --target godot --project "<project>" --workspace "<workspace>" --json`; do not manually copy some files.
+4. Use `CanonicalAssetLoader.load_scene(parent, package_dir)` for complete scenes, while also connecting the Stage-confirmed PBR material calibration, lights, environment, exposure, and camera. Use `load_package` when a prop enters an existing level to avoid stacking scene environments. A model may only be under one `A3AlignmentRoot` with `canonical_alignment_key`.
+5. Layer gameplay nodes, animation, collision, and the visible model separately; do not compensate the canonical Transform in the character controller or animation tree.
+6. Check composition, grounding, orientation, scale, materials, and interactive collision in the real Godot runtime view.
+
+## Routing references
+
+- Project directory and scene layering: read [project-structure.md](references/project-structure.md).
+- Materials, lighting, exposure, camera, and Stage native preview: read [appearance-alignment.md](references/appearance-alignment.md).
+- v2 loader, revision, and single-wrapper rules: read [canonical-asset-runtime.md](references/canonical-asset-runtime.md).
+- Pre-import/runtime/delivery gates: read [alignment-gates.md](references/alignment-gates.md).
+- GLB import, inherited scenes, and wrapper maintenance: read [import-and-wrapper-scenes.md](references/import-and-wrapper-scenes.md).
+- Character skeletons and animation: read [skeleton-animation.md](references/skeleton-animation.md).
+- Physics bodies and collision layers: read [physics-colliders.md](references/physics-colliders.md).
+- Build, runtime, and screenshot QA: read [build-and-qa.md](references/build-and-qa.md).
+
+## Completion gates
+
+- The sync result has `alignment_status=aligned` and a non-empty `alignment_key`.
+- Stage confirmation comes from the current native Godot view; after changing the model or display configuration, view and confirm again, then sync.
+- The same asset has only one canonical alignment root in the Godot scene.
+- Model nodes preserve the original imported Transform, and game logic does not apply repair recipes repeatedly.
+- Skeleton, animation, collision, and visual nodes have separated responsibilities.
+- Accept using actual Godot runtime screenshots; when deviations are found, update the canonical package and do not patch locally in Godot.

package/dist/skills/en-US/godot-3d-game/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Godot 3D Game"
+  short_description: "Build Godot 4 3D games and safely consume continuously aligned canonical assets"
+  default_prompt: "Please use $godot-3d-game to integrate the accepted canonical assets into this Godot 4 project, and complete scene, runtime, and build validation."
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/en-US/godot-3d-game/references/alignment-gates.md

@@ -0,0 +1,26 @@
+# Alignment gates
+
+## Before sync
+
+- Godot root contains `project.godot`.
+- Blender modeling/changes MUST be followed by opening Stage with target=godot and explicit user confirmation of the current native Godot view. Opening the page or setting ready/spec metadata is insufficient; no manual-copy bypass.
+- Package is v2 and all required conditions are aligned or explicitly waived.
+- Current `model.glb` bytes match the recorded SHA-256 and byte count.
+- Recipe binds current source and intent revisions.
+- Scene supplement, when present, passes coordinate, camera, manifest and path validation.
+- Current confirmation binds the Godot profile, native screenshot, shared adapter, camera and source revision. A Three.js confirmation cannot authorize a Godot sync.
+
+`evomeme asset sync <id> --target godot --project "<project>" --workspace "<workspace>" --json` performs these checks before creating or overwriting destination files.
+
+## At runtime
+
+The loader repeats lightweight schema/revision assertions before loading the PackedScene. It does not recompute SHA-256 inside Godot; host-side sync owns byte validation. A package edited after sync is unsupported—resync it.
+
+## Before delivery
+
+- inspect the remote scene tree for one `A3AlignmentRoot` per asset instance;
+- verify intended forward motion, ground contact, scale and camera framing;
+- exercise animation and physics so they do not reapply the wrapper transform;
+- record a Godot run capture for render acceptance.
+
+If any gate fails, use `game-asset-align`. Do not turn off assertions or hard-code fallback rotations.

package/dist/skills/en-US/godot-3d-game/references/appearance-alignment.md

@@ -0,0 +1,54 @@
+# Godot Basic Material and Lighting Alignment
+
+Launch commands according to the [CLI contract](../../game-asset-align/references/tool-contract.md); keep Stage in a persistent foreground session. JSON results are under `data`.
+
+## Required Order
+
+**Model/modify and save with Blender MCP -> `evomeme scene export "<scene.blend>" --id <id>` -> select Godot in Stage -> user reviews and confirms -> `evomeme asset sync <id> --target godot --project "<project>"` -> Godot project integration and revalidation.** For the source contract, optional procedural material baking, and parameters, see [scene export workflow](../../game-asset-align/references/blender-scene-pipeline.md).
+
+`evomeme stage --asset <id> --workspace "<workspace>" --target godot --json` opens the target-engine viewport. The host provides `godot` through `EVOMEME_GODOT` / `GODOT_PATH` (absolute executable path) or PATH. The PNG on the right comes from an independent native Godot process, and the model snapshot is written to `.evomeme/godot-previews/`; it is not written into the final game project early. The left side uses the Blender baseline that matches the contract camera or a native render from the current camera position. You cannot confirm an old frame when Godot is not installed, native rendering fails, or the camera position changes.
+
+## Data and Adjustable Parameters
+
+By default, preserve standard GLB PBR materials and textures, normals, and transparency; enable linear vertex colors for meshes with COLOR_0. By default, rebuild SUN/POINT/SPOT from `scene.contract.json.blender_lights`, converting positions and Blender Euler XYZ light directions as `[x,y,z]->[x,z,-y]`. AREA is approximated with a spotlight, and the interface shows this clearly; power is a basic conversion and must be visually calibrated.
+
+When calibration is needed, write `runtime/godot.profile.json` inside the package, add the file byte count and SHA-256 to `scene.contract.json.files`, and set `display_profiles.godot.profile_file` to that path. For example:
+
+```json
+{
+  "schema": "evomeme.godot_scene_profile.v1",
+  "asset_id": "my_scene",
+  "renderer": "gl_compatibility",
+  "environment": {
+    "background_srgb": [0.10, 0.14, 0.16],
+    "ambient_srgb": [0.75, 0.82, 0.85],
+    "ambient_energy": 0.5,
+    "exposure": 1.0,
+    "tonemapper": "filmic",
+    "fog": {"enabled": false, "color_srgb": [0.6, 0.7, 0.8], "density": 0.01}
+  },
+  "materials": [{"material_name": "Stone", "roughness": 0.8, "metallic": 0.0}]
+}
+```
+
+Materials are overridden by exact name. Missing names cause native preview failure to avoid silent no-ops. You can also specify `albedo_srgb` RGBA, `emission_srgb` RGB, `emission_energy`, and `double_sided`; unspecified fields preserve GLB values and textures.
+
+You can explicitly provide a `lights` array to replace derived lights. Each item's `type` is `directional/omni/spot`, using Godot Y-up metric `position`, `quaternion_xyzw`, `color_linear` RGB, `energy`, `range`, `spot_angle_degrees` (half-angle, 0.1-89), and `shadow_enabled`. `lights:[]` explicitly disables extra lights. Explicit configuration uses Godot energy values and no longer performs Blender power conversion.
+
+## Comparison and Modification Loop
+
+Color ambient light is fixed at `ambient_light_sky_contribution=0`, preventing the default sky contribution value from making the profile's color ambient light ineffective. Compatibility vertex colors participate in shading as sRGB and cannot rely only on the `vertex_color_is_srgb` switch: the shared adapter encodes glTF linear COLOR_0 into a private mesh copy, updates only RGB bytes, and preserves Alpha, UVs, indices, skeletons, LOD, and source resources; Forward+/Mobile keep linear data. Native Stage hides `-colonly` / `-convcolonly` helper meshes (including copy suffixes) to prevent GLTFDocument runtime loading from drawing colliders as physical objects.
+
+1. Fix the camera quaternion, vertical FOV, and frame, and check front/back faces, normals, transparency, textures, and vertex colors.
+2. Check key light direction, light/dark relationships, shadows, roughness, metallic highlights, emission, ambient color, and exposure.
+3. Fix geometry/node materials back in Blender; make basic engine calibration changes in the Godot profile, and update the manifest summary.
+4. Reload Stage and click confirm in the current native Godot view. `ready=true`, passing spec checks, or Three.js confirmation cannot replace this step.
+5. After sync, use `CanonicalAssetLoader.load_scene(parent, package_dir)` for complete scenes. It applies the same `canonical_appearance.gd`, `godot.appearance.json`, and camera as the preview; `load_package` only handles prop models and spatial transforms.
+
+## Runtime and Scope
+
+profile.renderer supports gl_compatibility (default), mobile, and forward_plus. During export, the actual renderer of an existing project can be read; Stage uses the same mode for native preview and does not silently fall back to OpenGL; during sync, it verifies that the target project mode is consistent. Choosing a more advanced renderer does not automatically implement volumetric or GI resource conversion, and the board still clearly shows missing items. Camera3D keeps vertical FOV; callers use SubViewport or margins to preserve the confirmed frame. The scene environment is connected only once to avoid stacking with the level's existing WorldEnvironment/lights. The gameplay camera can take over after integration, and after changes, composition and materials must be revalidated.
+
+Godot export settings must include `*.json` non-resource files to ensure asset.json/godot.appearance.json are packaged into the game. Three.js shaders, Cycles full-scene baked display modules, and LUTs in the spec are not executed by Godot. Basic PBR and real-time lights/fog do not promise pixel-by-pixel equivalence for Blender procedural nodes, volumetric light, or indirect light.
+
+API basis: [GLTFDocument](https://docs.godotengine.org/en/stable/classes/class_gltfdocument.html), [Environment](https://docs.godotengine.org/en/stable/classes/class_environment.html), [SpotLight3D](https://docs.godotengine.org/en/stable/classes/class_spotlight3d.html).

package/dist/skills/en-US/godot-3d-game/references/build-and-qa.md

@@ -0,0 +1,22 @@
+# Build and QA
+
+## Minimum verification
+
+1. Let Godot finish GLB import with no resource errors.
+2. Run the scene that instances the asset through `CanonicalAssetLoader`.
+3. Confirm one alignment root and the expected alignment key in the remote scene tree.
+4. Exercise movement, animation, collision, camera and material visibility.
+5. Restart the scene or load the asset twice to confirm idempotency.
+6. Capture the actual Godot viewport/build for visual acceptance.
+
+## Failure routing
+
+- schema/readiness/revision assertion: resync or return to `game-asset-align`;
+- missing PackedScene/import failure: inspect GLB export and Godot import log, then repair/re-export the canonical source;
+- wrong pose or missing parts: structural review/Blender path;
+- wrong identity/detail: semantic review/source regeneration;
+- material/culling/texture mismatch: render review, with Godot capture as evidence;
+- collision or gameplay transform issue: fix the authored Godot scene above/beside the visual root without modifying canonical TRS.
+
+Do not claim completion from a successful file copy alone. A successful run and target-engine visual check are required.
+

package/dist/skills/en-US/godot-3d-game/references/canonical-asset-runtime.md

@@ -0,0 +1,27 @@
+# Canonical asset runtime
+
+Before any engine sync, open Stage with `target=godot` after Blender modeling and obtain the user's explicit confirmation of the current native frame. Technical alignment metadata alone cannot authorize import.
+
+For a complete scene, call `CanonicalAssetLoader.load_scene(parent, package_dir)`. It applies the same material overrides, native lights, environment/exposure and reference camera reviewed in Stage. Use `load_package` below for props in a level with its own lighting. See [appearance-alignment.md](appearance-alignment.md).
+
+Call:
+
+```gdscript
+var visual := CanonicalAssetLoader.load_package(
+    visual_parent,
+    "res://assets/canonical/hero"
+)
+```
+
+The generated loader verifies:
+
+- canonical asset and alignment schema versions;
+- `alignment.ready=true` and `overall_status=aligned`;
+- source fingerprint revision equality;
+- recipe source and intent revision equality;
+- a non-empty `alignment_key`;
+- complete translation, quaternion and positive scale values.
+
+It creates `<asset_id>_A3AlignmentRoot`, tags it with the asset ID and alignment key, and places the raw imported model below it. A second call with the same key returns the existing root. A newer key replaces that one root; calling it below another canonical root is rejected.
+
+Do not copy recipe values into a `.tscn`, animation track or controller. The generated loader remains the only application point. Gameplay transform belongs above the canonical root; model-local animation remains below it.

package/dist/skills/en-US/godot-3d-game/references/import-and-wrapper-scenes.md

@@ -0,0 +1,20 @@
+# Import and wrapper scenes
+
+Godot imports GLB as a `PackedScene`. Keep that import generated and reproducible. Put scripts, collision, navigation, interaction markers and gameplay signals in a separate authored scene.
+
+Recommended hierarchy:
+
+```text
+EntityRoot (gameplay/world transform)
+  CollisionRoot
+  VisualParent
+    <asset_id>_A3AlignmentRoot (canonical recipe)
+      ImportedGLBRoot (unchanged)
+```
+
+Do not edit the imported GLB child transform to fix orientation. Do not put the canonical recipe on `EntityRoot`, because its transform changes during gameplay. Do not wrap an inherited scene and then call the loader again inside it.
+
+When the canonical asset changes, resync and let the alignment key replace the visual root. Preserve authored gameplay nodes outside that root.
+
+For full scenes/maps with `pivot=origin`, instance under a world parent with identity transform. A level streaming offset is gameplay/world placement and belongs above the canonical root; it must not be written back as asset repair.
+

package/dist/skills/en-US/godot-3d-game/references/physics-colliders.md

@@ -0,0 +1,13 @@
+# Physics and colliders
+
+Collision belongs to the gameplay scene, not inside the generated canonical package unless the source contract explicitly carries collider data.
+
+- Use simple authored primitives for dynamic actors where possible.
+- Use trimesh collision only for appropriate static environment geometry.
+- Keep collision and visual roots as siblings under the entity so visual alignment does not silently scale physics twice.
+- Validate collision layers, masks, ground clearance and center of mass after every source/recipe revision.
+
+If the canonical wrapper scale is not `[1,1,1]`, size authored colliders against the accepted world dimensions. Do not copy the wrapper scale onto both the collision root and its shapes.
+
+Physics mismatch can reveal a spatial or semantic defect. If the visual object cannot align with a reasonable collider without local hacks, mark the relevant canonical condition non-ready and repair the source or recipe.
+

package/dist/skills/en-US/godot-3d-game/references/project-structure.md

@@ -0,0 +1,22 @@
+# Godot project structure
+
+Use a stable separation between imported assets, authored wrapper scenes and gameplay systems.
+
+```text
+res://
+  assets/canonical/<asset_id>/
+    model.glb
+    asset.json
+    canonical_loader.gd
+  scenes/assets/
+  scenes/levels/
+  scripts/gameplay/
+  scripts/presentation/
+```
+
+The synchronized package is generated input. Do not hand-edit it in the Godot project; update the workspace canonical package and sync again.
+
+Keep gameplay state on a stable parent such as `CharacterBody3D` or an entity root. Add the canonical visual root as a child. This lets control, networking and save state remain stable when the visual package revision changes.
+
+Use authored `.tscn` scenes for gameplay composition, signals and engine-specific components. Keep the imported GLB scene read-only or inherited. Never save canonical compensation transforms into multiple scene layers.
+

package/dist/skills/en-US/godot-3d-game/references/skeleton-animation.md

@@ -0,0 +1,16 @@
+# Skeleton and animation
+
+Keep the canonical wrapper above the imported skeleton. Never apply alignment rotation to individual bones or bake it into animation clips.
+
+After sync, verify:
+
+- Skeleton3D and skinned meshes share the expected imported hierarchy;
+- animations bind to existing node/bone paths;
+- root motion is handled by one gameplay policy, not both AnimationTree and entity movement;
+- frame zero does not snap because an animation track overwrites the wrapper;
+- sockets for weapons or effects attach to bones/markers below the imported root as intended.
+
+Retargeting, missing bones, broken weights and unusable clip naming are structural problems. Mark structural review non-ready and return to the canonical/Blender repair flow. A Godot AnimationTree state machine is not a geometry repair mechanism.
+
+When replacing a character source, repeat structural and semantic review even if the silhouette appears unchanged; bone names and clip bindings are part of the maintained state.
+

package/dist/skills/en-US/phaser-2d-game/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: phaser-2d-game
+description: Implement 2D browser games with Phaser, TypeScript, and Vite. Use when scenes, gameplay systems, cameras, sprite animation, Arcade physics, tilemaps, DOM-overlay HUDs, or portrait touch controls are needed.
+---
+
+# Phaser 2D Game Implementation
+
+## Overview
+
+This skill is used for the concrete implementation phase of 2D browser games.
+
+Tech stack: **Phaser 3 + TypeScript + Vite + pnpm**. Production HUDs/menus use a **DOM overlay** (usually React) layered over the Canvas.
+
+## Architecture Principles
+
+1. **Separate Systems and Scenes**
+   - Systems own game rules, turn order, movement, combat, inventory, objectives, and progress logic. (Aligned with `game/simulation` in the 3D skill: the rules source-of-truth layer)
+   - Phaser Scene only maps system state to sprite positions, camera movement, animation playback, and effects; it does not hold game truth.
+
+2. **Keep Scenes Lightweight**
+   - Boot Scene: configuration initialization and asset preloading
+   - Menu Scene: main menu or shell layer (complex menus can still use DOM)
+   - Gameplay Scene: main game-loop view
+   - Optional: parallel debug Scene (does not replace the production HUD)
+
+3. **Renderable Objects Are Disposable**
+   - Sprite containers, particles, Tweens, and camera rigs are view state, not data sources.
+
+4. **Asset Keys Are Stable**
+   - Reference assets through a manifest / `public/config.json`; business code must not hardcode scattered URLs.
+
+## Implementation Guidance
+
+- Scene reads System through a single boundary and sends input intents back to System.
+- Prefer deterministic system updates; avoid piling complete rules into `update`.
+- Use DOM, not dense Canvas text, for text-heavy HUDs/menus with complex state.
+- Derive animation state from game state.
+- **Use only Phaser Scale Manager for viewport scaling**; CSS/`transform` hand-rolled scaling is forbidden (see `references/engine-runtime.md`).
+- **Measure the image before writing a spritesheet loader** (see `references/engine-spritesheets.md`).
+
+## Engine References (Load As Needed)
+
+When writing/modifying Phaser runtime code, load references by task in addition to `file-structure.md`; do not preread all of them at once:
+
+| Task | Load |
+| --- | --- |
+| Scene lifecycle, Scale, delta, scene switching | `references/engine-runtime.md` |
+| Arcade/Matter selection, collisions, object pools | `references/engine-physics.md` |
+| Any spritesheet / atlas / nine-slice | `references/engine-spritesheets.md` (before loading the sheet) |
+| Tiled maps, collision layers, spawning objects | `references/engine-tilemaps.md` |
+| Stutter, pooling, culling, update allocations | `references/engine-performance.md` |
+
+## Covered 2D Game Types
+
+- Turn-based grids and tactical chess-like games
+- Top-down exploration maps
+- Side-scrolling action platformers
+- Character action combat (sprite animation frames)
+- Lightweight management or card/command-battle scenes
+
+## Camera and Presentation
+
+- Decide the camera model early: locked, follow, room switching, tactical panning.
+- Keep camera logic completely separate from game rules.
+- Shake, hit-stop, and parallax must improve readability and must not obscure key information.
+- Large maps: align `cameras.setBounds` with `physics.world.setBounds`.
+
+## UI Integration
+
+- Use DOM overlays for HUDs, command menus, settings, and narrative.
+- Canvas is responsible for the game world, combat readability, and motion presentation.
+- Unless the project explicitly requires it, do not render dense text or complex settings UI inside Phaser.
+
+## Asset Directory Convention
+
+```
+assets/
+  characters/   sprites, frame animations
+  environment/  backgrounds, tiles, scene props
+  ui/           HUD images, icons, buttons
+  fx/           particles, effects
+  audio/        BGM, SFX
+  data/         level config, dialogue data, Tiled JSON
+```
+
+## Scaffolding and Configuration
+
+New project entry points: `index.html`, `src/main.ts`, `public/config.json`. The package manager is **pnpm**. Build output includes `dist/index.html` and `dist/config.json`. The directory and config schema use `references/file-structure.md` as the only normative source.
+
+## Common Anti-Patterns
+
+When React and Phaser coexist, calling `createGame()` immediately after `root.render()` creates a startup race: React has not yet committed `#game-container`, so Phaser may mount the Canvas at the wrong layer and cover the menu, while the game still remains in the `menu` or `inputLocked` state; the result is a visible screen that cannot be operated. Use `flushSync`, `useLayoutEffect`, a callback ref, or an explicit container-ready signal, start in the order "React container commit complete -> container exists and has valid dimensions -> create Phaser", and check the container and Canvas mount relationship before initialization; when clicks are ineffective, first confirm UI state, input locks, and DOM structure, then adjust the event path.
+
+React development mode performs one extra mount cleanup and restart. If an old Phaser Scene is destroyed without unregistering its event listeners, a button may receive the click, but the event may first hit the already-destroyed old Scene, then throw and interrupt the new Scene's click handling. It is forbidden to destroy only the Phaser instance while leaving Scene listeners registered on the input system, DOM, `window`, a shared EventEmitter, or the React bridge layer; every `on`, `addEventListener`, or subscription must have a corresponding `off`, `removeEventListener`, or unsubscribe, and cleanup must be completed in the Scene's `SHUTDOWN`/`DESTROY` and React effect cleanup. In development mode, you must verify that after repeated "create -> cleanup -> create", only the current Scene responds to a click once.
+
+- Game rules are written in Scene `update` with no system boundary
+- Scenes pass state through mutable `window` globals
+- CSS scaling is used for Canvas instead of Scale Manager
+- spritesheet frameWidth/Height are guessed without measurement
+- Matter is used for simple AABB
+- Bullets/enemies are constantly created and destroyed without pooling
+- Production HUD is drawn on Canvas just for convenience
+- Asset paths are hardcoded in many places
+- A generic React dashboard pattern is applied to game UI
+- CRA / Next.js / npm-only scaffolding replaces this specification (unless the user explicitly requests it)
+
+## References
+
+**Engine (This Skill)**
+- File structure and layering: `references/file-structure.md`
+- Runtime / scaling: `references/engine-runtime.md`
+- Physics and object pools: `references/engine-physics.md`
+- Spritesheet / atlas: `references/engine-spritesheets.md`
+- Tilemap: `references/engine-tilemaps.md`
+- Performance: `references/engine-performance.md`
+
+**Cross-Skill**
+- Art style: `../game-art/references/art-styles.md`
+- Spatial composition patterns: `../game-art/references/scene-profiles.md`
+- 2D visual quality improvement: `../phaser-2d-graphics-builder/SKILL.md`
+- Animation specs: `../game-art/references/animation-specs.md`
+- UI style: `../game-ui/references/ui-styles.md`
+- Game feel: `../game-designer/references/game-feel.md`
+- Level design: `../game-designer/references/game-design-level-design.md`
+- New game DoD: `../game-designer/references/checklists/new-game-definition-of-done.md`
+- Game feel checklist: `../game-designer/references/checklists/game-feel.md`
+- Level checklist: `../game-designer/references/checklists/game-design-level-design.md`

package/dist/skills/en-US/phaser-2d-game/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Phaser 2D Game"
+  short_description: "Build clearly structured 2D browser games, handling scenes, gameplay, input, and UI integration"
+  default_prompt: "Please use $phaser-2d-game to implement this 2D browser game according to my requirements, and keep the scene, gameplay system, and UI boundaries clear."
+
+policy:
+  allow_implicit_invocation: true
+