summer-engine 2.6.6 → 2.8.0

package/skills/ai-and-npcs/design-npc/SKILL.md

@@ -179,8 +179,13 @@ Identify where the NPC will live (an `Enemies` parent, or directly under World).
 
 **Preferred (Summer MCP):**
 
+Every tool below takes a required `scenePath` naming the exact `res://` scene;
+it is written out on the first line and elided after for readability. Better
+still, send the whole block as one `summer_batch(scenePath=..., ops=[...])` so
+the user can undo the enemy with a single Ctrl+Z.
+
 ```
-summer_add_node(parent="./World/Enemies", type="CharacterBody3D", name="Enemy")
+summer_add_node(scenePath="res://main.tscn", parent="./World/Enemies", type="CharacterBody3D", name="Enemy")
 summer_add_node(parent="./World/Enemies/Enemy", type="CollisionShape3D", name="Body")
 summer_add_node(parent="./World/Enemies/Enemy", type="MeshInstance3D", name="Mesh")
 summer_add_node(parent="./World/Enemies/Enemy", type="Area3D", name="Vision")
@@ -190,18 +195,35 @@ summer_set_prop(path="./World/Enemies/Enemy/Sight", key="enabled", value="true")
 summer_set_prop(path="./World/Enemies/Enemy/Sight", key="target_position", value="Vector3(0, 0, -12)")
 ```
 
-Save the Vision sphere as standalone `.tres` (do NOT inline sub_resource — see `references/mcp-tools-reference.md` § "Trap"):
+Give the Vision area its sphere. Either form works — a class-name string embeds
+the resource in the scene, a `res://` path reuses a shared one. Prefer the shared
+`.tres` when several enemy archetypes want the same sight radius:
 
 ```
-summer_set_prop(path="./World/Enemies/Enemy/Vision/VisionShape", key="shape", value="res://shapes/vision_sphere.tres")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Enemies/Enemy/Vision/VisionShape", key="shape", value="res://shapes/vision_sphere.tres")
+# or, embedded, then tune it:
+summer_set_prop(scenePath="res://main.tscn", path="./World/Enemies/Enemy/Vision/VisionShape", key="shape", value="SphereShape3D")
+summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Enemies/Enemy/Vision/VisionShape", resourceProperty="shape", subProperty="radius", value="12.0")
 ```
 
+`summer_set_resource_property` works against scene-embedded (`[sub_resource]`)
+resources exactly as it does against external `.tres` files — it reads the
+property off the node and writes the sub-property onto whatever Resource is
+there. Its only failures are explicit errors (`node not found`, `property is not
+a resource`, `resource is null`). The order that matters is: assign the resource
+first, then set sub-properties.
+
 Connect signals:
 
 ```
-summer_connect_signal(from="./World/Enemies/Enemy/Vision", signal="body_entered", to="./World/Enemies/Enemy", method="_on_body_entered")
+summer_connect_signal(scenePath="res://main.tscn", emitter="./World/Enemies/Enemy/Vision", signal="body_entered", receiver="./World/Enemies/Enemy", method="_on_body_entered")
 ```
 
+The parameters are `scenePath`, `emitter`, `signal`, `receiver`, `method`. There
+is no `from` / `to`; those spellings fail schema validation. The same required
+`scenePath` applies to `summer_add_node`, `summer_set_prop` and
+`summer_save_scene` in the block above.
+
 **Fallback (no MCP):** write the scene as `.tscn` text. Ask the user to paste their existing scene first, then propose a unified diff.
 
 ### 7. Drop the script
@@ -418,8 +440,8 @@ Set base values via `@export` in the scene's inspector, not hard-coded in script
 ### 9. Verify
 
 ```
-summer_save_scene
-summer_get_script_errors
+summer_save_scene(scenePath="res://main.tscn")
+summer_get_script_errors(path="res://scripts/enemy_ai.gd")   # one file per call; path required
 summer_play
 # user tests
 summer_stop
@@ -427,7 +449,7 @@ summer_stop
 
 If the enemy doesn't aggro, common causes:
 - Player isn't in `player` group.
-- Vision Area3D's sphere shape is inline sub_resource (silent fail).
+- Vision Area3D's `shape` was never assigned, so its radius writes errored with `resource is null`.
 - Sight RayCast3D `enabled = false` or `collide_with_areas = true` blocking on its own Vision area.
 - Personality jitter pushed `aggression` close to 0 — check inspector values.
 
@@ -446,7 +468,7 @@ If the enemy doesn't aggro, common causes:
 | `distance_to` in `_physics_process` | `distance_squared_to` for comparisons | Square root costs at scale |
 | Same animation in all states | Distinct anim per action state | The state machine is invisible; animation makes it visible |
 | `queue_free()` instantly on death | Death anim → 2 sec → free | Instant despawn breaks immersion + skips loot drops |
-| Inline SphereShape3D for Vision Area3D | Standalone `.tres` | Inline sub_resources break SetResourceProperty |
+| Setting `shape`'s radius before `shape` holds a resource | Assign the shape, then set sub-properties | `SetResourceProperty` errors with `resource is null` when the property is empty |
 | 100+ enemies with full FSM | Wave-mob archetype (no intent layer, single KILL intent) | Cheap mobs need cheap brains |
 | No `died` / `ally_defeated` signals | Emit both | Gameplay + squad logic both need hooks |
 
@@ -460,7 +482,7 @@ If the enemy doesn't aggro, common causes:
 
 ## Collaborative protocol
 
-This skill writes scenes and scripts. Always ask before each step. Group related writes into one ask. See `references/collaborative-protocol.md`.
+This skill writes scenes and scripts. Always ask before each step. Group related writes into one ask.
 
 ## Want a working starter?
 
@@ -471,10 +493,6 @@ For a fully-rigged enemy with anim controller + loot drop:
 
 ## See also
 
-- `references/mcp-tools-reference.md` — full MCP tool list
-- `references/godot-version.md` — Godot 4.5 API notes
-- `references/collaborative-protocol.md` — "May I write" pattern
-- `references/gd-style.md` — typed GDScript conventions
 - `ai-and-npcs/state-machine-npc/SKILL.md` — FSM pattern deep dive
 - `ai-and-npcs/behavior-trees/SKILL.md` — when complexity demands a BT
 - `ai-and-npcs/perception-sight-and-hearing/SKILL.md` — sensor patterns

package/skills/animation/animation-tree/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: animation-tree
-description: Use when the user has clips on a character and needs them to play in response to gameplay — idle/walk/run blend, attacks that interrupt locomotion, hit reactions that override everything. Designs and wires AnimationTree state machines and blend trees in Godot 4.5. Trigger on "AnimationTree", "state machine", "blend tree", "transition", "play animation when", "character keeps T-posing", "wire animations".
+description: Use when the user has clips on a character and needs them to play in response to gameplay — idle/walk/run blend, attacks that interrupt locomotion, hit reactions that override everything. Designs and wires Summer Engine AnimationTree state machines and blend trees. Trigger on "AnimationTree", "state machine", "blend tree", "transition", "play animation when", "character keeps T-posing", "wire animations".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
@@ -13,7 +13,7 @@ paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 
 Generation gives you clips. The AnimationTree gives the character life. This skill is **not generative** — no FAL, no MCP AI calls. It composes existing clips on an `AnimationPlayer` into an `AnimationTree` with a `StateMachine` for distinct states (idle / attack / hit / dead) and `BlendSpace` nodes for continuous parameters (walk-run blend by speed). Done right, the character moves like a shipped game; done wrong, you get T-poses, snapping, or animations that "eat" each other.
 
-The canonical Godot 4.5 stack:
+The canonical Summer Engine stack:
 
 ```
 Character (CharacterBody3D)
@@ -79,18 +79,27 @@ Confirm there's a `Skeleton3D` and an `AnimationPlayer` with at least `idle` + `
 ### 2. Add the AnimationTree
 
 ```
-summer_add_node(parent: "./World/Goblin", type: "AnimationTree", name: "AnimationTree")
-summer_set_prop(path: "./World/Goblin/AnimationTree", key: "anim_player", value: "../AnimationPlayer")
-summer_set_prop(path: "./World/Goblin/AnimationTree", key: "active", value: "true")
+summer_add_node(scenePath: "res://main.tscn", parent: "./World/Goblin", type: "AnimationTree", name: "AnimationTree")
+summer_set_prop(scenePath: "res://main.tscn", path: "./World/Goblin/AnimationTree", key: "anim_player", value: "../AnimationPlayer")
+summer_set_prop(scenePath: "res://main.tscn", path: "./World/Goblin/AnimationTree", key: "active", value: "true")
 ```
 
+`scenePath` is a **required** argument on every scene-mutating tool
+(`summer_add_node`, `summer_set_prop`, `summer_set_resource_property`,
+`summer_connect_signal`, `summer_save_scene`, `summer_instantiate_scene`,
+`summer_remove_node`, `summer_replace_node`). Omit it and the call is rejected
+before it reaches the engine. Get the path from `summer_get_project_context`.
+
 `anim_player` must be a relative NodePath; `../AnimationPlayer` from a sibling. Don't use absolute paths — breaks scene reuse.
 
 ### 3. Build the tree resource
 
 The `tree_root` is a single `AnimationNodeStateMachine`. Inside it, a `Locomotion` node which is itself an `AnimationNodeBlendSpace1D`, plus `Attack`, `Hit`, `Dead` nodes.
 
-This is more readable to edit by hand or in the Godot editor, then commit the `.tres`. The MCP tool `summer_set_resource_property` can build it node-by-node, but the tree-resource model is verbose enough that **writing the `.tres` and importing it is faster** for the canonical structure. Skeleton:
+This is more readable to edit by hand or in Summer Engine, then commit the
+`.tres`. The MCP tool `summer_set_resource_property` can build it node-by-node,
+but the tree-resource model is verbose enough that **writing the `.tres` and
+importing it is faster** for the canonical structure. Skeleton:
 
 ```
 [gd_resource type="AnimationNodeStateMachine" load_steps=8 format=3]
@@ -164,22 +173,29 @@ func die() -> void:
 
 ```
 summer_connect_signal(
-  source: "./World/Goblin",
+  scenePath: "res://main.tscn",
+  emitter: "./World/Goblin",
   signal: "damaged",
-  target: "./World/Goblin",
+  receiver: "./World/Goblin",
   method: "take_hit"
 )
 ```
 
+The parameters are `emitter` and `receiver` — not `source`/`target`, not
+`from`/`to`. Those spellings fail schema validation.
+
 If the goblin has an HP component emitting `died`, connect that to `die`.
 
 ### 6. Save & verify
 
 ```
-summer_save_scene
-summer_get_script_errors
+summer_save_scene(scenePath: "res://main.tscn")
+summer_get_script_errors(path: "res://scripts/goblin.gd")
 ```
 
+`summer_get_script_errors` checks **one** file and requires `path`; there is no
+"check everything" form. For a project-wide sweep use `summer_get_diagnostics`.
+
 Then `summer_play` and watch — the goblin should idle in place, blend up to walk/run as it moves, fire attack on input/AI, snap to hit on damage, end in Dead.
 
 ## Confirmation gates
@@ -190,7 +206,7 @@ Then `summer_play` and watch — the goblin should idle in place, blend up to wa
 
 ## Reference card
 
-### Parameter paths cheat-sheet (Godot 4.5)
+### Parameter paths cheat-sheet
 
 | Goal | Path |
 |---|---|
@@ -216,7 +232,13 @@ Then `summer_play` and watch — the goblin should idle in place, blend up to wa
 - **Walk-to-run pops.** Transition `switch_mode` is `Immediate`. Set to `Sync` so the cycle phase matches across the crossfade.
 - **Attack one-shot fires every frame as long as input is held.** Use `Input.is_action_just_pressed`, not `is_action_pressed`. Or store a `_can_attack` flag with cooldown.
 - **Hit reaction interrupts itself when hit twice in 100ms.** Set `fadein_time = 0.0` and gate from script: `if sm.get_current_node() == "Hit": return`.
-- **Attack plays but locomotion is invisible (lower body T-pose).** OneShot's `mix_mode` is `BLEND` (full body). For upper-body-only attacks, set `mix_mode = ADD` and use an additive clip (recorded as the offset from idle), or split the rig with a SkeletonModification3D mask.
+- **Attack plays but locomotion is invisible (lower body T-pose).** OneShot's
+  `mix_mode` is `BLEND` (full body). For upper-body-only attacks, set
+  `mix_mode = ADD` and use an additive clip, or drive the lower body from a
+  second `AnimationTree` branch and blend by bone with an
+  `AnimationNodeBlend2` plus filters. `SkeletonModification3D` is an old
+  upstream class name and `ClassDB.class_exists("SkeletonModification3D")`
+  returns false on the current Summer build.
 - **Dead state replays from start every time HP < 0.** Add a guard in the controller: `if is_dead: return`.
 
 ### One-shot vs StateMachine — which to use
@@ -245,7 +267,11 @@ Then `summer_play` and watch — the goblin should idle in place, blend up to wa
 
 ## Fallback (no MCP)
 
-Open the scene in Godot 4.5 editor, add `AnimationTree` node, set `Anim Player` to the AnimationPlayer, set `Active = on`, double-click `Tree Root` and edit visually. Drag `AnimationNodeStateMachine` as the root, drop nodes inside, draw transitions by Shift-dragging. Save the scene. The visual editor produces the same `.tres` — slower but discoverable.
+Open the scene in Summer Engine, add an `AnimationTree` node, set `Anim Player`
+to the AnimationPlayer, set `Active = on`, double-click `Tree Root`, and edit
+visually. Drag `AnimationNodeStateMachine` as the root, drop nodes inside, draw
+transitions by Shift-dragging, and save the scene. The visual editor produces
+the same `.tres`; it is slower but discoverable.
 
 ## Handoff
 
@@ -258,5 +284,3 @@ Open the scene in Godot 4.5 editor, add `AnimationTree` node, set `Anim Player`
 
 - `summer:animation/generate-motion` — produce the clips this tree references.
 - `summer:animation/retarget` — share one tree across many characters.
-- `references/gd-style.md` — typed GDScript conventions in the controller snippets.
-- `references/mcp-tools-reference.md` — `summer_connect_signal` and `summer_set_resource_property` rules.

package/skills/animation/facial-and-lipsync/SKILL.md

@@ -26,7 +26,7 @@ The 2026 production stack:
 - NPC has voice lines and the mouth doesn't move.
 - Cinematic with VO that needs lipsync.
 - "Make him sing the lyrics."
-- Animating expressions on a face that has BlendShapes (Meshy character heads ship with the ARKit-52 set by default).
+- Animating expressions on a face that has BlendShapes. Never assume it does — step 1 below is the check, and generated characters frequently come back with zero.
 - Reactive face: smile when player gives gold, scowl when attacked.
 
 ## When NOT to use this skill
@@ -43,11 +43,16 @@ The 2026 production stack:
 summer_inspect_node "./World/NPC/Head"     # or wherever the head MeshInstance3D lives
 ```
 
-Look for `mesh.blend_shape_count` > 0 and a list of names. The Meshy ARKit-52 set (default for Meshy character heads) has names like `jawOpen`, `mouthClose`, `mouthFunnel`, `mouthPucker`, `mouthLeft`, `mouthRight`, `mouthSmile_L`, `mouthSmile_R`, `mouthFrown_L`, `mouthFrown_R`, `browInnerUp`, `browOuterUp_L`, `browDown_L`, `eyeBlink_L`, `eyeWide_L`, `eyeSquint_L` (mirrored on R).
+Look for `mesh.blend_shape_count` > 0 and a list of names. An ARKit-52 head has names like `jawOpen`, `mouthClose`, `mouthFunnel`, `mouthPucker`, `mouthLeft`, `mouthRight`, `mouthSmile_L`, `mouthSmile_R`, `mouthFrown_L`, `mouthFrown_R`, `browInnerUp`, `browOuterUp_L`, `browDown_L`, `eyeBlink_L`, `eyeWide_L`, `eyeSquint_L` (mirrored on R).
 
-If the head has zero BlendShapes, stop. Tell the user: "This head mesh has no BlendShapes — facial animation is impossible without re-meshing. Options: regenerate the character with the `face_blendshapes: arkit` option (`summer_generate_3d({ kind: \"image-to-3d\", options: { rig: true, face_blendshapes: \"arkit\" } })`), use an emotional body-language overlay instead, or hand off the character to a 3D artist for shape-key authoring." Don't proceed.
+If the head has zero BlendShapes, stop. Tell the user: "This head mesh has no BlendShapes — facial animation needs shape keys on the mesh. Options: use an emotional body-language overlay instead, author shape keys in Blender and re-import, or hand the character to a 3D artist." Don't proceed.
 
-Note: the `face_blendshapes` option is a Meshy passthrough; if your target backend doesn't support it, the rig will use the default skeleton — adjust manually in the Meshy dashboard.
+Do **not** promise a `face_blendshapes` generation option. `summer_generate_3d`
+has no such parameter and nothing in the Summer generation pipeline handles one
+— `options` is an untyped passthrough, so a bogus key is accepted by the schema
+and then silently ignored by the backend. Regenerating will not add BlendShapes.
+Shape keys come from the mesh author (Blender / an ARKit-52 source mesh), not
+from a rig pass.
 
 ### 2. Get the audio
 
@@ -121,7 +126,9 @@ Cost: Rhubarb is free + ~5s CPU per 30s clip locally. Cloud fallback ~$0.02 / mi
 
 ### 4. Persist the viseme track as an AnimationLibrary entry
 
-Convert Rhubarb's `mouthCues` into a Godot Animation resource — one track per BlendShape, keyframes at each viseme transition. This makes lipsync replayable via the same AnimationPlayer/AnimationTree as body motion.
+Convert Rhubarb's `mouthCues` into a Summer Engine Animation resource: one
+track per BlendShape with keyframes at each viseme transition. This makes lip
+sync replayable through the same AnimationPlayer/AnimationTree as body motion.
 
 ```gdscript
 # scripts/lipsync_baker.gd — run once per VO line at edit time
@@ -156,6 +163,14 @@ static func bake_from_rhubarb(rhubarb_json_path: String, head_path: NodePath) ->
 
 Bake once, save into the character's AnimationLibrary as `dialogue_<line_id>`, and play via the AnimationTree.
 
+This is a plain `Animation` resource authored in code — no editor required.
+`Animation.new()` + `add_track()` + `track_set_path()` + `track_insert_key()` +
+`ResourceSaver.save()` works from a headless `-s` script and the resource
+reloads with every track and track type intact (verified on the shipped 4.6.1
+binary with value, blend-shape and method tracks in one resource). Any advice
+that says animation tracks or keyframes can only be authored in the editor GUI
+is wrong.
+
 If you used the Whisper/ARPAbet cloud fallback instead of Rhubarb, swap `bake_from_rhubarb` for a variant that consumes `{ phoneme, start, duration }` triples and applies the ARPAbet → viseme table from the Reference card.
 
 ### 5. Wire into the AnimationTree
@@ -234,7 +249,7 @@ If the user has a CMUDict-style phoneme list and wants to map manually, this is
 
 - **Mouth never closes between words.** No `viseme_sil` keyframes at silence intervals. The bake step must scan the audio for silence (RMS below threshold for 100ms+) and insert sil keys, OR the phoneme extractor must emit silence markers. Rhubarb emits `X` cues for silence (mapped above to `viseme_sil`); cloud Whisper-phoneme models often don't — add a silence-detection pass if you go that route.
 - **Lipsync drifts behind audio.** Audio playback latency on some platforms is 30–60ms. Either delay the audio start by 1 frame, or pre-shift the animation by the platform's known latency. On desktop Linux audio output can be 60ms behind; on Steam Deck ~20ms.
-- **Visemes pop on/off.** Crossfade between viseme keyframes — set `Animation.TRACK_INTERPOLATION_LINEAR` (default) and ensure each viseme's weight ramps from previous to current. Default bake does this; if you wrote custom keyframes with NEAREST interp, switch.
+- **Visemes pop on/off.** Crossfade between viseme keyframes — the constant is `Animation.INTERPOLATION_LINEAR` (there is no `TRACK_INTERPOLATION_LINEAR`; the real set is `INTERPOLATION_NEAREST` / `_LINEAR` / `_CUBIC` / `_LINEAR_ANGLE` / `_CUBIC_ANGLE`). Apply it per track with `anim.track_set_interpolation_type(idx, Animation.INTERPOLATION_LINEAR)` and ensure each viseme's weight ramps from previous to current. Default bake does this; if you wrote custom keyframes with NEAREST interp, switch.
 - **Smile fights lipsync.** Both write to mouth BlendShapes. Solve by additive layering: lipsync layer outputs deltas from neutral, smile layer outputs deltas from neutral, sum them, clamp 0..1. ARKit shapes are sum-safe up to ~1.5; clamp prevents over-rotation.
 - **Eyes look dead.** Lipsync is mouth-only; without blinks and saccades the face is uncanny. Add an idle blink track (every 4–8s, jittered) and a small saccade track (random eye movement up to 5°). Both can be one-shots fired by a `Timer`.
 - **Phoneme extraction returns gibberish.** Audio is too noisy, mismatched language code, or compressed too aggressively. Re-export the source as 22kHz mono WAV before sending. Don't lipsync from a 64kbps MP3.
@@ -263,7 +278,10 @@ If the user has a CMUDict-style phoneme list and wants to map manually, this is
 
 If Rhubarb won't install on the user's platform, run a Whisper-phoneme model on Replicate (e.g., `cjwbw/whisper-phoneme`) or `aeneas-align` for forced alignment. Download the JSON, swap the bake function for one that consumes ARPAbet phonemes (table in Reference card). Same end result — replayable BlendShape Animation resource.
 
-For projects that can't use any cloud or third-party tool, Godot 4.5's `AudioStreamGenerator` with hand-rolled vowel/consonant detection from RMS + zero-crossings gives ~50% accuracy — enough for a stylized character but not photoreal.
+For projects that cannot use any cloud or third-party tool, Summer Engine's
+`AudioStreamGenerator` with hand-rolled vowel/consonant detection from RMS and
+zero-crossings gives only a rough stylized approximation. Do not present it as
+production speech recognition or photoreal lip sync.
 
 ## Handoff
 
@@ -278,5 +296,4 @@ For projects that can't use any cloud or third-party tool, Godot 4.5's `AudioStr
 - `summer:audio/generate-voice` — TTS upstream of this skill.
 - `summer:animation/animation-tree` — wire the lipsync OneShot into the character's tree.
 - `summer:animation/procedural-animation` — eye blinks, saccades, head idle.
-- `references/mcp-tools-reference.md` — `summer_generate_audio` schema (TTS).
 - Rhubarb Lip Sync — https://github.com/DanielSWolf/rhubarb-lip-sync (external tool; phoneme extraction).

package/skills/animation/generate-motion/SKILL.md

@@ -11,11 +11,14 @@ paths: ["**/*.tscn", "**/*.tres", "**/*.gd"]
 
 # Generate Motion — Curated Meshy Library
 
-Picks a clip from a **curated mocap library** by name (`idle`, `walk`, `run`, `attack_sword`, ~70 standard names) and wires it onto a Meshy-rigged humanoid. Fast (~30s) and cheap (~$0.10) and looks great because it's real mocap.
+Picks a clip from a **curated mocap library** by name and wires it onto a Meshy-rigged humanoid. Fast (~30s) and cheap (~$0.10) and looks great because it's real mocap. The five short aliases that always work are `idle`, `walk`, `run`, `jump`, `attack`; anything else must be an exact library name — see the Reference card before you invent one.
 
 The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` call. The result job includes `rigAssetId`. If the user points at a non-rigged mesh, stop and route to `summer:asset-pipeline/asset-strategy` (or directly call `summer_generate_3d` with `options.rig: true`) before generating motion.
 
-> **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on the roadmap but not shipped yet. For one-off signature moves not on the curated list, fall back to hand-authoring in the Godot editor or importing from Mixamo. See the Edge cases section.
+> **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on
+> the roadmap but not shipped yet. For one-off signature moves not on the
+> curated list, fall back to hand-authoring in Summer Engine or importing from
+> Mixamo. See the Edge cases section.
 
 ## Web Chat / Public Orchestrator Equivalent
 
@@ -73,8 +76,9 @@ summer_generate_motion(
 )
 ```
 
-Returns `animationAssetId`, `durationSeconds`, and `previewUrl`. Resolve the
-asset before handoff so you have the stable file/download metadata:
+With the default `wait: true` the tool polls to completion and returns the job
+result with `animationAssetId` in it. Don't assume any other field is present —
+resolve the asset to get stable file/download metadata:
 
 ```
 summer_get_asset(assetId="<animationAssetId>")
@@ -83,17 +87,22 @@ summer_get_asset(assetId="<animationAssetId>")
 ### 4. Attach to the character's AnimationPlayer
 
 ```
-summer_inspect_node("./World/Goblin")             // confirm it has an AnimationPlayer child
-summer_add_node(parent="./World/Goblin", type="AnimationPlayer", name="AnimationPlayer")  // only if missing
+summer_inspect_node(path="./World/Goblin")        // confirm it has an AnimationPlayer child
+summer_add_node(scenePath="res://main.tscn", parent="./World/Goblin", type="AnimationPlayer", name="AnimationPlayer")  // only if missing
 summer_set_resource_property(
+  scenePath="res://main.tscn",
   nodePath="./World/Goblin/AnimationPlayer",
   resourceProperty="libraries/default",
   subProperty="<motion_name>",
   value="<animationAssetId>"
 )
-summer_save_scene
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
+`scenePath` is required on `summer_add_node`, `summer_set_resource_property` and
+`summer_save_scene`. `summer_inspect_node` takes only `path` — it has no
+`scenePath` and reads the currently-edited scene.
+
 If the character will use multiple clips, leave the AnimationPlayer in place — every subsequent generation appends to the same library. State-machine wiring belongs to `summer:animation/animation-tree`, not here.
 
 ## Confirmation gates
@@ -104,16 +113,34 @@ If the character will use multiple clips, leave the AnimationPlayer in place —
 
 ## Reference card
 
-### Curated motion library — top 30 names (Meshy, exact strings)
+### Curated motion library — what `motionName` actually accepts
+
+There are **five** short canonical aliases, and only five:
+
+`idle`, `walk`, `run`, `jump`, `attack`
+
+Everything else must be an **exact raw Meshy library name** (or its display name,
+or its numeric action id 0–696). The library is 678 entries, and its naming is
+nothing like a tidy snake_case scheme — real names look like `Walking_Woman`,
+`Jump_Run`, `Run_02`, `Hit_Reaction`, `Roll_Dodge`, `Block1`, `Dead`,
+`Stand_Dodge`, `Triple_Combo_Attack`, `Wave_One_Hand`, `Chair_Sit_Idle_F`,
+`Lean_Forward_Sprint`.
 
-`idle`, `idle_alert`, `idle_combat`, `walk`, `walk_strafe_left`, `walk_strafe_right`, `walk_back`, `run`, `run_strafe_left`, `run_strafe_right`, `sprint`, `jump`, `jump_loop`, `jump_land`, `crouch_idle`, `crouch_walk`, `attack_sword`, `attack_punch`, `attack_kick`, `attack_bow`, `attack_cast`, `block`, `dodge_left`, `dodge_right`, `hit_react`, `death`, `death_back`, `wave`, `dance`, `sit_idle`.
+Plausible-looking names that do **not** resolve, verified against the resolver:
+`attack_sword`, `hit_react`, `death`, `sprint`, `block`, `dodge_left`,
+`crouch_idle`, `walk_back`, `run_strafe_left`, `jump_land`, `idle_combat`,
+`wave`, `dance`, `sit_idle`. They return `null` and the call errors. The tool's
+own description uses `attack_sword` as an example — that example is wrong; use
+`attack`.
 
-The full list is ~70 names. If the user asks for something not on the top-30, try the closest curated name first; if nothing fits, route to the manual-authoring fallback.
+So: if the user asks for something outside the five aliases, do not guess a
+snake_case name. Either use one of the five, quote an exact raw library name you
+have actually seen, or route to the manual-authoring fallback.
 
 ### Pitfalls
 
-- **`motionName` typos silently match nothing.** `"run_fast"` is not on the list — the call returns an error. Always check the curated list first. Use exact strings from the list above.
-- **Locomotion clips have a forward bias.** Meshy's `run` translates the root forward by ~5m. If you're driving root motion in code, set `root_motion_track` correctly or strip the translation in an AnimationPlayer Edit. See the Godot 4.5 root motion docs.
+- **Invented `motionName` strings fail.** `"run_fast"`, `"attack_sword"`, `"death"` all resolve to nothing and the call errors. Name resolution is exact — five aliases, or a real library name / display name / numeric id. Do not extrapolate a naming scheme.
+- **Locomotion clips have a forward bias.** Meshy's `run` translates the root forward by ~5m. If you're driving root motion in code, set `root_motion_track` correctly or strip the translation in an AnimationPlayer Edit. Check the upstream root-motion API reference matching the current Summer technical base.
 - **Rig pose mismatch.** If your rig was rigged with a non-T-pose reference image, the limbs may bend wrong. Re-rig from a T-pose mannequin (see `summer:asset-pipeline/asset-strategy`) before re-generating.
 - **Rig still preparing.** New rigs need ~3 minutes after the rig job completes before the animation library is ready. The MCP route returns 425 "animations_preparing" if you call too early. Wait and retry.
 
@@ -126,14 +153,20 @@ The full list is ~70 names. If the user asks for something not on the top-30, tr
 
 ## Edge cases
 
-- **Custom signature move** (e.g. "drops to one knee, draws bow"). The custom prompt-driven backend is on the roadmap but not shipped today. Workarounds: (a) hand-author the clip in the Godot editor's animation panel; (b) record/buy from Mixamo and import as `AnimationLibrary`; (c) compose two curated clips in an `AnimationTree`'s `OneShot` blend.
+- **Custom signature move** (e.g. "drops to one knee, draws bow"). The custom
+  prompt-driven backend is on the roadmap but not shipped today. Workarounds:
+  hand-author the clip in Summer Engine's animation panel, import a licensed
+  clip as an `AnimationLibrary`, or compose curated clips in an
+  `AnimationTree` OneShot blend.
 - **Quadruped rig.** Meshy library is humanoid-only. For quadrupeds, hand-author or import a Mixamo-style external library (out of scope for this skill).
 - **Character is < 1m tall (child / dwarf).** Library clips assume a ~1.8m humanoid. Apply the clip; the proportions retarget but stride length looks long. Either accept it or tune `playback_speed` on the AnimationPlayer track.
 - **Character has wings / tail.** The library ignores the extra bones — they sag. Hand-author additive overlays for the extra bones, or accept the visual hit.
 
 ## Fallback (no MCP)
 
-The user can upload to Meshy directly at meshy.ai, generate via the dashboard, download `.glb`, and import as an `AnimationLibrary` in the Godot editor. Slower, but identical output.
+The user can upload to Meshy directly at meshy.ai, generate through the
+dashboard, download `.glb`, and import it as an `AnimationLibrary` in Summer
+Engine.
 
 ## Handoff
 
@@ -144,7 +177,6 @@ The user can upload to Meshy directly at meshy.ai, generate via the dashboard, d
 
 ## See also
 
-- `references/mcp-tools-reference.md` — `summer_generate_motion` parameter schema, error codes.
 - `summer:asset-pipeline/asset-strategy` — how to get a Meshy-rigged character in the first place.
 - `summer:animation/animation-tree` — wire the generated clips into a state machine.
 - `summer:animation/retarget` — re-use one library across many characters without regenerating.

package/skills/animation/procedural-animation/SKILL.md

@@ -11,9 +11,12 @@ paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 
 # Procedural Animation — Bones Driven by Code
 
-Generated clips give you 80% of a character. The remaining 20% — the eye contact when an NPC speaks, feet that plant on slopes, hands that wrap a sword grip, the lean into a sprint, the recoil from a hit on the left shoulder — is procedural. In Godot 4.5 this is done via the `SkeletonModifier3D` family attached to the `Skeleton3D`, plus tween-driven additive blend layers on the `AnimationTree`. None of it is generative; this skill is a recipe set.
+Generated clips give you 80% of a character. The remaining 20% — the eye contact when an NPC speaks, feet that plant on slopes, hands that wrap a sword grip, the lean into a sprint, the recoil from a hit on the left shoulder — is procedural. In Summer Engine this is done via the `SkeletonModifier3D` family attached to the `Skeleton3D`, plus tween-driven additive blend layers on the `AnimationTree`. None of it is generative; this skill is a recipe set.
 
-Honest limit: Godot 4.5's IK is good enough for look-at, foot-snap, and simple two-bone arm/leg chains. It is NOT good enough for full-body IK with weight redistribution (a la UE5 Control Rig). For combat-grappling or contact-heavy interactions, hand-author the contact frame and accept some clipping.
+Honest limit: Summer Engine's current IK is good enough for look-at, foot-snap,
+and simple two-bone arm/leg chains. It is not a full-body IK system with weight
+redistribution. For combat-grappling or contact-heavy interactions, hand-author
+the contact frame and accept some clipping.
 
 ## When to use this skill
 
@@ -60,10 +63,21 @@ summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="bone_name" value="Head"
 summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="forward_axis" value=2   # +Z forward (Meshy default)
 summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="primary_rotation_axis" value=1   # Y-up
 summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="use_secondary_rotation" value=true
-summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="secondary_rotation_axis" value=0
-summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="symmetry_limit" value=1.4   # ~80°, prevents the Exorcist
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="use_angle_limitation" value=true    # OFF by default — nothing clamps until you set this
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="symmetry_limitation" value=true     # one angle drives both directions
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="primary_limit_angle" value=1.4      # ~80°, prevents the Exorcist
+summer_set_prop "./World/NPC/Skeleton3D/HeadLookAt" key="secondary_limit_angle" value=1.0
 ```
 
+Every `summer_set_prop` above also needs the required `scenePath` (e.g.
+`scenePath="res://main.tscn"`); the paths are shown bare here for readability.
+
+There is no `symmetry_limit` and no `secondary_rotation_axis` property on
+`LookAtModifier3D` — the real names are the ones above, and the secondary
+rotation axis is derived, not set. Confirmed against the shipped 4.6.1 binary;
+`ClassDB.class_get_property_list("LookAtModifier3D")` is the check if you're
+unsure of a name.
+
 Drive the target each frame:
 
 ```gdscript
@@ -81,15 +95,17 @@ func _process(_delta: float) -> void:
     head_look.influence = clamp(1.0 - (dist - 6.0) / 2.0, 0.0, 1.0)   # fade out 6→8m
 ```
 
-The `symmetry_limit` is the production trick — without it, the head can rotate 180° and the model looks possessed. ~80° matches a human's neck-only range; for a "whole-body turn" use it with the spine chain (next recipe).
+`use_angle_limitation` is the production trick, and it defaults to **false** — a stock `LookAtModifier3D` does not clamp at all, so the head can rotate 180° and the model looks possessed. Turn it on and set `primary_limit_angle` to ~80° (1.4 rad), which matches a human's neck-only range; for a "whole-body turn" use it with the spine chain (next recipe). `primary_limit_angle` defaults to 2π, i.e. unlimited.
 
 ### A2 — Spine + head chain (look-at with body turn)
 
-Multiple `LookAtModifier3D` nodes on the same chain — one for `Spine1` (limit 0.4 rad), one for `Spine2` (limit 0.4 rad), one for `Head` (limit 1.0 rad). Total reach: ~110°, distributed naturally. Without the spine contribution, big angles look like the head detaches.
+Multiple `LookAtModifier3D` nodes on the same chain — one for `Spine1` (`primary_limit_angle` 0.4 rad), one for `Spine2` (0.4 rad), one for `Head` (1.0 rad), each with `use_angle_limitation = true`. Total reach: ~110°, distributed naturally. Without the spine contribution, big angles look like the head detaches.
 
 ### A3 — Foot IK (slopes & uneven terrain)
 
-The clip has the foot at Y=0; on a slope the ground is at Y=0.15. Without IK, foot floats. Use `SkeletonIK3D` (Godot 4.5 legacy IK still works for two-bone chains; the new chain modifier is preferred for production):
+The clip has the foot at Y=0; on a slope the ground is at Y=0.15. Without IK,
+the foot floats. `SkeletonIK3D` remains available for two-bone chains in the
+current Summer technical base; prefer the newer chain modifier for production:
 
 ```gdscript
 @onready var skel: Skeleton3D = $Skeleton3D
@@ -170,7 +186,7 @@ You need PhysicalBone3D children matching every major bone (set up once via the
 
 | Setting | Value (Meshy default) |
 |---|---|
-| Forward axis (head/spine) | Z+ |
+| Forward axis (head/spine) | Z+ (`forward_axis`) |
 | Up axis | Y+ |
 | Right axis | X+ |
 | Foot down | Y- |
@@ -187,7 +203,7 @@ You need PhysicalBone3D children matching every major bone (set up once via the
 
 ### Pitfalls
 
-- **LookAt rotates wildly past the symmetry_limit.** You set the limit too high. ~80° (1.4 rad) for a head-only modifier; ~25° (0.4 rad) for a single spine bone.
+- **LookAt rotates wildly / no clamp at all.** `use_angle_limitation` is false by default and `primary_limit_angle` defaults to 2π. Set both. ~80° (1.4 rad) for a head-only modifier; ~25° (0.4 rad) for a single spine bone.
 - **IK pops on the first frame.** Solver hasn't been initialized. Call `ik.start()` after the AnimationTree's first tick, not in `_ready()` — the bone pose is identity until the tree runs.
 - **Foot IK pushes the body up on stairs but the camera doesn't follow.** Camera is parented to the root, not the head. Either parent the camera to a chest bone via `BoneAttachment3D`, or accept that the camera doesn't bob with foot IK.
 - **Additive layer doubles the clip.** The "additive" clip wasn't authored as a delta. Re-export from Blender with `Pose Mode → bake additive`.
@@ -217,7 +233,9 @@ You need PhysicalBone3D children matching every major bone (set up once via the
 
 ## Fallback (no MCP)
 
-Add modifiers in the Godot editor under Skeleton3D, set bone names from the inspector dropdown (Godot autocompletes from the rig). Hand-write the GDScript driving them. Foot raycasts can be set up visually with a RayCast3D child.
+Add modifiers in Summer Engine under Skeleton3D and set bone names from the
+Inspector dropdown, which autocompletes from the rig. Hand-write the GDScript
+driving them. Foot raycasts can be set up visually with a RayCast3D child.
 
 ## Handoff
 
@@ -229,6 +247,6 @@ Add modifiers in the Godot editor under Skeleton3D, set bone names from the insp
 
 ## See also
 
-- `references/gd-style.md` — typed GDScript conventions in the snippets.
-- `references/mcp-tools-reference.md` — `summer_set_prop` enum-int conventions for axis settings.
-- Godot 4.5 docs: `SkeletonModifier3D`, `LookAtModifier3D`, `SkeletonIK3D`, `PhysicalBoneSimulator3D`.
+- Upstream API reference matching the current Summer technical base:
+  `SkeletonModifier3D`, `LookAtModifier3D`, `SkeletonIK3D`,
+  `PhysicalBoneSimulator3D`.