summer-engine 2.6.6 → 2.8.0

package/skills/animation/retarget/SKILL.md

@@ -5,15 +5,30 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
 user-invocable: false
-allowed-tools: Read Grep summer_search_assets summer_inspect_resource summer_retarget_motion summer_get_scene_tree summer_set_resource_property summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_inspect_resource summer_generate_motion summer_get_scene_tree summer_set_resource_property summer_save_scene
 paths: ["**/*.tscn", "**/*.tres"]
 ---
 
 # Retarget Motion — One Library, Many Characters
 
-Generating a "run" clip costs ~$0.10 and 30s. If you have ten enemies, regenerating ten runs is ten generations of wasted money and clock time when one Meshy retarget call would cost ~$0.05 and take ~10s. Retarget is the right answer the moment a project has more than one rigged humanoid character.
+## There is no retarget MCP tool. Read this before promising one.
 
-The Meshy retarget pipeline takes a source `animationAssetId` and a target `rigAssetId`, both of which must be **Meshy-rigged humanoids**. It re-projects the animation onto the target's bone hierarchy, preserves timing and root motion, and emits a new `animationAssetId` against the target rig. The source clip is unchanged.
+Summer ships **no** `summer_retarget_motion` tool, and no other MCP tool that
+re-projects an existing animation asset onto a second rig. Verify it yourself:
+`grep -rn 'summer_' tools/summer-cli/src/mcp/tools/*.ts` lists every registered
+tool and there is no retarget entry. Never call one — the MCP server rejects
+unknown tool names outright, and inventing a cost table for it ("$0.05 a clip")
+is worse than saying nothing.
+
+Two real paths exist. Pick by whether the target rig is Meshy-rigged.
+
+| Situation | Path |
+|---|---|
+| Target is Meshy-rigged and the clip name is on the curated list | Re-run `summer_generate_motion` against the target's `rigAssetId`. Same clip, ~$0.10, ~30s. |
+| Target is not Meshy-rigged, or the clip is hand-authored / Mixamo / bought | In-engine retargeting: `BoneMap` + `SkeletonProfileHumanoid` + `RetargetModifier3D`. No credits, no network, but you configure the bone mapping. |
+
+The rest of this skill covers both. The cost math that used to live here assumed a
+retarget API that does not exist; the honest math is below.
 
 ## When to use this skill
 
@@ -24,149 +39,182 @@ The Meshy retarget pipeline takes a source `animationAssetId` and a target `rigA
 
 ## When NOT to use this skill
 
-- Source and target are not both Meshy-rigged humanoids — retarget will fail. Route to `summer:animation/generate-motion` to regenerate, or to `summer:asset-pipeline/asset-strategy` to re-rig.
-- Target is a quadruped or non-humanoid (wings-only, mech, blob). Meshy retarget is humanoid-skeleton-locked. Hand-author or regenerate.
-- The user wants ONE new clip on ONE character — just call `summer:animation/generate-motion`. Retarget is for fan-out.
+- The user wants ONE new clip on ONE character — just call `summer:animation/generate-motion`.
 - The user wants to retime, edit, or layer the animation — that's `summer:animation/animation-tree` and the `summer:animation/procedural-animation` additive layers.
+- Target is a quadruped or non-humanoid (wings-only, mech, blob). The curated Meshy
+  library is humanoid-only and `SkeletonProfileHumanoid` is a humanoid profile.
+  Hand-author instead.
 
-## The compatibility check (do this BEFORE calling retarget)
-
-The dominant failure mode is retargeting between rigs that look humanoid but have different bone counts, names, or hierarchies. Meshy auto-rigs use a fixed 52-bone humanoid skeleton — every Meshy rig is interchangeable. Mixamo / VRoid / hand-rigged FBX imports are NOT — even if they're "humanoid", the bone names differ and the retarget call rejects them.
-
-Before calling `summer_retarget_motion`, verify:
-
-```
-summer_inspect_resource(<source_rigAssetId>)
-summer_inspect_resource(<target_rigAssetId>)
-```
-
-Both responses should include `rig_provider: "meshy"` and `bone_count: 52`. If either is missing those fields or shows a different provider, **stop**. Tell the user: "Target rig isn't Meshy-rigged — retarget will fail. Either re-rig the target via `summer_generate_3d({ kind: \"image-to-3d\", imageUrl: \"...\", options: { rig: true } })` or regenerate motion directly on it via `summer:animation/generate-motion`. Which?"
-
-If both are Meshy-rigged but the target's mesh has wildly different proportions (e.g., source is a 1.8m human, target is a 2.5m ogre with arms-down-to-knees), retarget will succeed but the *result* will look wrong — clipping, foot-floating, or limb-twisting. Warn the user before spending: "Proportions differ a lot — retarget will run but you'll likely need procedural foot IK on the result. Continue?" Hand off to `summer:animation/procedural-animation` after.
+## Path A — regenerate on the target rig (Meshy-rigged targets)
 
-## Steps
+This is the path for the common case: several characters that all came out of
+`summer_generate_3d(... rig: true)`.
 
-### 1. Find the source library
+### 1. Find the source clip names
 
 ```
-summer_search_assets(query: "<source character>", kind: "animation")
+summer_search_assets(query: "<source character>", assetType: "animation", source: "my_assets")
 ```
 
-Returns a list of `{ animationAssetId, name, durationSeconds }`. Cache the IDs.
+You want the *names* (`idle`, `walk`, `run`, ...), not the asset IDs — the IDs
+belong to the source rig and cannot be transplanted.
 
 ### 2. Find the target rig
 
 ```
-summer_search_assets(query: "<target character>", kind: "model")
+summer_search_assets(query: "<target character>", assetType: "3d_model", source: "my_assets")
 ```
 
-Confirm `rigAssetId` is present and Meshy-provider.
+Confirm a `rigAssetId` is present. If it is null the model was never rigged —
+stop and propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })`
+first, or route to `summer:asset-pipeline/asset-strategy`.
 
 ### 3. Confirm with user before spending
 
-Always batch-ask. Retargets are cheap individually but $0.05 × 30 clips × 5 enemies = $7.50, which deserves consent.
+Regeneration is a real generation per clip per character. Say the total.
 
-> I'm about to retarget 12 clips (idle, walk, run, attack, ...) from `goblin_rigged` onto `orc_rigged` — about 12 × $0.05 = $0.60, ~2 minutes total. OK?
+> I'm about to generate 12 clips (idle, walk, run, attack, ...) on `orc_rigged` —
+> 12 × ~$0.10 = ~$1.20, a few minutes total. OK?
 
-### 4. Loop the retarget calls
+### 4. Loop the generation calls
 
 ```
-for clip in source_clips:
-  summer_retarget_motion(
-    sourceAnimationAssetId: clip.animationAssetId,
-    targetRigAssetId: <target_rigAssetId>,
-    name: clip.name              // preserve the slot name (idle, walk, run...)
+for name in source_clip_names:
+  summer_generate_motion(
+    rigAssetId: "<target_rigAssetId>",
+    backend: "meshy-library",
+    motionName: name          // exact curated name — see generate-motion's list
   )
-  // returns { animationAssetId, durationSeconds }
+  // returns animationAssetId in the job result
 ```
 
 Save the returned IDs as a map `{ name: animationAssetId }` for the target.
 
 ### 5. Attach to the target's AnimationPlayer
 
-Same pattern as `summer:animation/generate-motion`: ensure an `AnimationPlayer` child exists, then write each clip into `libraries/default`.
+`summer_set_resource_property` requires the target scene path — it is not optional.
 
 ```
 summer_set_resource_property(
+  scenePath: "res://main.tscn",
   nodePath: "./World/Orc/AnimationPlayer",
   resourceProperty: "libraries/default",
   subProperty: "<clip_name>",
-  value: "<retargeted_animationAssetId>"
+  value: "<animationAssetId>"
 )
 ```
 
-`summer_save_scene` once at the end, not per clip.
+`summer_save_scene(scenePath: "res://main.tscn")` once at the end, not per clip.
+
+## Path B — in-engine retargeting (non-Meshy rigs, bought or hand-authored clips)
+
+The current Summer Engine build ships the retargeting stack that the MCP layer
+does not wrap. Verified
+instantiable on the shipped binary: `BoneMap`, `SkeletonProfileHumanoid`
+(56 bones), `RetargetModifier3D`.
+
+The shape:
+
+1. Create a `BoneMap` resource per rig, with `profile` set to a
+   `SkeletonProfileHumanoid`. Map each profile bone name to that rig's actual
+   bone name. Save as `.tres` — one per distinct skeleton, reused forever.
+2. On import, set the source `.glb`'s import options to use the source rig's
+   `BoneMap` so its animation tracks are expressed against the humanoid profile.
+3. On the target character, add a `RetargetModifier3D` under the `Skeleton3D`
+   and set its `profile` to the same `SkeletonProfileHumanoid`. It re-projects
+   the profile-space pose onto the target's bones each frame.
+
+This costs no credits and works with any humanoid skeleton, including Mixamo and
+hand-rigged FBX. The cost is the bone-mapping pass: a few minutes per distinct
+skeleton, once.
 
 ## Confirmation gates
 
-- **Before any retarget call:** show the full list and total cost.
-- **After the first retarget:** preview the result. If it looks wrong, stop the loop and re-evaluate (proportions, T-pose, missing bones).
+- **Before any generation call:** show the full clip list and total cost.
+- **After the first clip:** preview the result. If it looks wrong, stop the loop
+  and re-evaluate (proportions, T-pose, missing bones).
 - **Before saving the scene:** confirm the AnimationPlayer additions you're about to write.
 
 ## Reference card
 
-### When retarget fails — the 5 common causes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| API returns `incompatible_rig` | Target isn't Meshy-rigged | Re-rig target via `summer_generate_3d({ kind: "image-to-3d", options: { rig: true } })` |
-| API returns `bone_mismatch` | Source rigged with custom bones (extra wings, etc.) | Strip extras or regenerate motion natively on target |
-| Clip plays but limbs twist 180° | T-pose vs A-pose mismatch | Re-rig source from T-pose reference |
-| Feet float / clip into ground | Target is much taller/shorter | Apply foot IK — see `summer:animation/procedural-animation` |
-| Root motion drifts | Source had baked root translation, target scale differs | Strip root track in AnimationPlayer or scale `playback_speed` |
-
 ### Cost math (decision rule)
 
-| Scenario | Generate fresh | Retarget |
+There is no cheaper "retarget" rate to compare against, so the real decision is
+generate-per-character versus spend the time on a `BoneMap`.
+
+| Scenario | Regenerate (Path A) | In-engine BoneMap (Path B) |
 |---|---|---|
-| 1 character, 1 clip | $0.10 | n/a |
-| 1 character, 12 clips | $1.20 | n/a |
-| 5 characters, same 12 clips | $6.00 (5 × $1.20) | $1.80 ($1.20 + 4 × $0.60 retarget) |
-| 30 NPCs, same 8-clip set | $24.00 | $6.40 ($0.80 + 29 × $0.40) |
+| 1 character, 12 clips | ~$1.20 | n/a — nothing to share yet |
+| 5 characters, same 12 clips | ~$6.00 | $0, plus ~1 bone-map pass per distinct skeleton |
+| 30 NPCs sharing one skeleton | ~$36.00 | $0 — same rig, so the clips already play on all of them |
 
-The break-even is two characters. Past that, retarget is always cheaper.
+Note the case that makes most of this moot: **NPCs that share one rig share one
+animation library already.** If the user's 30 enemies are 30 instances of the
+same rigged `.glb`, nothing needs retargeting — instance the scene.
 
 ### Pitfalls
 
-- **Not preserving clip names.** If you don't pass `name:` to `summer_retarget_motion`, the target gets clips named `retargeted_001`, `retargeted_002` and your AnimationTree state machine breaks. Always pass the source name.
-- **Retargeting one clip at a time interactively.** Batch the loop; each call has a few seconds of overhead. Sequential is fine; parallel via `summer_batch` is faster if the project supports it.
-- **Forgetting the source library still owns the clips.** Source character's AnimationPlayer is unchanged. Don't accidentally re-attach the *source* IDs to the target.
-- **Retargeting then regenerating "to clean it up".** If retarget produced bad output, the fix is procedural foot IK or a bone-correction modifier — not regeneration. Regeneration only makes sense if the source itself is bad.
-- **Mixing Meshy and Mixamo libraries on the same character.** They have different bone-naming conventions; the AnimationPlayer tries to play tracks against bones that don't exist. Pick one rig provider per character and stick with it.
+- **Assuming a retarget tool exists.** It does not. Check the tool list before
+  promising a capability; a hallucinated tool name fails the call outright.
+- **Reusing the source `animationAssetId` on the target.** Animation assets are
+  bound to the rig they were generated against. Generate against the target's own
+  `rigAssetId` (Path A) or go through a `BoneMap` (Path B).
+- **Omitting `scenePath`.** `summer_set_resource_property`, `summer_save_scene`,
+  `summer_add_node`, and `summer_set_prop` all take a required `scenePath`.
+- **Mixing Meshy and Mixamo libraries on one character without a BoneMap.** The
+  bone-naming conventions differ; the AnimationPlayer plays tracks against bones
+  that don't exist. One rig provider per character, or map both through the
+  humanoid profile.
+- **Proportion mismatch.** A library authored on a 1.8m humanoid on a 2.5m ogre
+  runs, but you get foot-float and limb-twist. Layer foot IK afterwards — see
+  `summer:animation/procedural-animation`.
 
 ### Quality bar
 
-- Library was originally generated on a 1.8m humanoid → target between 1.5m and 2.2m: retarget is production-ready.
-- Target is 2.2m–3m: retarget runs, expect foot-clipping; layer foot IK.
-- Target is < 1.5m or has cartoon proportions (big head, short limbs): retarget runs, expect noticeable limb-pop; consider regenerating natively.
+- Library authored on a 1.8m humanoid → target between 1.5m and 2.2m: production-ready.
+- Target 2.2m–3m: expect foot-clipping; layer foot IK.
+- Target < 1.5m or cartoon proportions (big head, short limbs): expect limb-pop.
 
 ## Anti-patterns
 
-- Calling `summer_retarget_motion` without first verifying both rigs are Meshy-provider.
-- Retargeting from a hand-authored animation library (Mixamo `.fbx`, etc.). The MCP wraps Meshy's retarget, which only accepts Meshy-rig source clips. For external libraries, use Godot's built-in `BoneMap` retargeting in the editor — out of scope for this skill.
-- Retargeting on every gameplay session. Retarget once, persist the resulting `animationAssetId`, and reference from the scene file. The asset library survives session restarts.
-- Generating motion on each enemy separately because you forgot retarget existed. The first time the project has two rigged characters, point at this skill.
+- Calling a `summer_retarget_motion` / `summer_retarget_*` tool. None exists.
+- Quoting a retarget price. There is no retarget SKU to price.
+- Passing an asset ID to `summer_inspect_resource`. That tool takes a `res://`
+  **path** to a resource in the project, not a cloud asset ID. Use
+  `summer_get_asset(assetId: ...)` for asset metadata.
+- Generating motion on each enemy separately when they are instances of the same
+  rig. Instance the scene; the library comes with it.
 
 ## Edge cases
 
-- **Source library uses additive blend tracks.** Additive clips (e.g., a "lean left" overlay) retarget but the additive flag is preserved only on Meshy-native rigs. Verify the `track_type` survived: `summer_inspect_resource(<retargeted_animationAssetId>)`.
-- **Source has facial blendshape tracks.** Meshy retarget only handles skeleton. Facial tracks are stripped. Hand off to `summer:animation/facial-and-lipsync` to re-author per character.
-- **Target rig was generated months ago and Meshy updated their skeleton schema.** Rare but happens. Symptom: bone-count mismatch even though both rigs are Meshy. Re-rig the target with a fresh `summer_generate_3d({ kind: "image-to-3d", options: { rig: true } })` call.
-- **The user wants to retarget *to* the source rig as a sanity test.** Allowed and useful — round-trips should be near-identical.
+- **Source has facial blendshape tracks.** Skeleton retargeting only handles
+  bones. Facial tracks do not transfer. Hand off to `summer:animation/facial-and-lipsync`
+  to re-author per character.
+- **Target rig is a different Meshy skeleton generation.** Symptom: bone-count
+  mismatch even though both are Meshy. Re-rig the target with a fresh
+  `summer_generate_3d({ kind: "image-to-3d", options: { rig: true } })` call.
+- **The clip the user wants is not on the curated list.** Path A cannot produce
+  it. Either hand-author it, or import a Mixamo clip and take Path B.
 
 ## Fallback (no MCP)
 
-Open the source `.glb` in Blender, export the animation, then in Godot 4.5 use the BoneMap-based humanoid retargeting workflow (Project → Tools → Bone Map). Set both source and target as humanoid profile, configure the bone mapping if names differ, save the retargeted clip into the target's `AnimationLibrary`. ~5 minutes per clip vs ~10 seconds via MCP. Documented in the Godot 4.5 character animation docs.
+Path B is the fallback and does not need MCP at all. In Summer Engine: select
+the source `.glb` in the FileSystem dock, open the Import tab, create/assign a
+`BoneMap` with a `SkeletonProfileHumanoid` profile, re-import. On the target
+character add a `RetargetModifier3D` under `Skeleton3D` with the same profile.
+Documented in the Godot 4.x "Retargeting 3D Skeletons" docs.
 
 ## Handoff
 
-- After retarget, the wiring is identical to a freshly-generated clip — hand off to `summer:animation/animation-tree` for state-machine integration.
-- If retarget produced foot-clipping or hand-pen-through-prop issues, hand off to `summer:animation/procedural-animation` for IK correction.
+- After the clips are on the target, the wiring is identical to a freshly-generated
+  clip — hand off to `summer:animation/animation-tree` for state-machine integration.
+- If the result shows foot-clipping or hand-pen-through-prop issues, hand off to
+  `summer:animation/procedural-animation` for IK correction.
 - For NPC behavior driving these clips, hand off to `summer:ai-and-npcs/design-npc`.
 
 ## See also
 
-- `summer:animation/generate-motion` — to create the source library.
-- `summer:asset-pipeline/asset-strategy` — to ensure all characters are Meshy-rigged before retargeting.
-- `summer:animation/animation-tree` — wire the retargeted clips into a state machine.
-- `summer:animation/procedural-animation` — fix proportional mismatches with foot IK after retarget.
+- `summer:animation/generate-motion` — the tool that actually produces clips, and the curated name list.
+- `summer:asset-pipeline/asset-strategy` — getting characters rigged in the first place.
+- `summer:animation/animation-tree` — wire the clips into a state machine.
+- `summer:animation/procedural-animation` — fix proportional mismatches with foot IK.

package/skills/audio/adaptive-music/SKILL.md

@@ -56,7 +56,7 @@ For 90% of indie games, **horizontal sequencing** is correct. It's cheaper to au
 ### 3. Confirm stems exist (or generate them)
 
 ```
-summer_search_assets(query="music", filter={ kind: "audio" })
+summer_search_assets(query="music", assetType="music", source="all")
 ```
 
 You need (typical case):
@@ -100,25 +100,27 @@ For ducking, add a sidechain compressor on the `Music` bus with the `Voice` bus
 For horizontal sequencing, instantiate one `AudioStreamPlayer` per state, all on the Music bus, all autoplay, all looping, all starting at `-60 dB` except the active state:
 
 ```
-summer_add_node(parentPath="/root/Game/Music", type="AudioStreamPlayer", name="Calm")
-summer_set_prop(path="/root/Game/Music/Calm", property="stream", value="res://audio/music/calm.mp3")
-summer_set_prop(path="/root/Game/Music/Calm", property="bus", value="Music")
-summer_set_prop(path="/root/Game/Music/Calm", property="volume_db", value=0.0)
-summer_set_prop(path="/root/Game/Music/Calm", property="autoplay", value=true)
-
-summer_add_node(parentPath="/root/Game/Music", type="AudioStreamPlayer", name="Tension")
-summer_set_prop(path="/root/Game/Music/Tension", property="stream", value="res://audio/music/tension.mp3")
-summer_set_prop(path="/root/Game/Music/Tension", property="bus", value="Music")
-summer_set_prop(path="/root/Game/Music/Tension", property="volume_db", value=-60.0)
-summer_set_prop(path="/root/Game/Music/Tension", property="autoplay", value=true)
-
-summer_add_node(parentPath="/root/Game/Music", type="AudioStreamPlayer", name="Combat")
-summer_set_prop(path="/root/Game/Music/Combat", property="stream", value="res://audio/music/combat.mp3")
-summer_set_prop(path="/root/Game/Music/Combat", property="bus", value="Music")
-summer_set_prop(path="/root/Game/Music/Combat", property="volume_db", value=-60.0)
-summer_set_prop(path="/root/Game/Music/Combat", property="autoplay", value=true)
+summer_add_node(scenePath="res://main.tscn", parent="./Music", type="AudioStreamPlayer", name="Calm")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Calm", key="stream", value="res://audio/music/calm.mp3")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Calm", key="bus", value="Music")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Calm", key="volume_db", value=0.0)
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Calm", key="autoplay", value=true)
+
+summer_add_node(scenePath="res://main.tscn", parent="./Music", type="AudioStreamPlayer", name="Tension")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Tension", key="stream", value="res://audio/music/tension.mp3")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Tension", key="bus", value="Music")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Tension", key="volume_db", value=-60.0)
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Tension", key="autoplay", value=true)
+
+summer_add_node(scenePath="res://main.tscn", parent="./Music", type="AudioStreamPlayer", name="Combat")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Combat", key="stream", value="res://audio/music/combat.mp3")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Combat", key="bus", value="Music")
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Combat", key="volume_db", value=-60.0)
+summer_set_prop(scenePath="res://main.tscn", path="./Music/Combat", key="autoplay", value=true)
 ```
 
+Every scene-mutating tool takes an explicit `scenePath`; node paths are relative to that scene's root (`./`), not absolute `/root/...` runtime paths; and the property argument is named `key`, not `property`.
+
 All three play simultaneously, in sync, but only one is audible. State transitions tween volumes — the music never restarts, only fades.
 
 This is why same BPM / same key / same bar length matter: all three are at the same playhead at all times.
@@ -309,7 +311,8 @@ Master
 
 ## Fallback (no MCP)
 
-Print the bus layout, the node tree, and the GDScript. User constructs in the Godot editor manually.
+Print the bus layout, node tree, and GDScript. The user constructs it manually
+in Summer Engine.
 
 ## Handoff
 
@@ -323,4 +326,5 @@ Print the bus layout, the node tree, and the GDScript. User constructs in the Go
 - `audio/audio-direction` — defines the dynamic music plan and bus layout
 - `audio/music-track` — generates the stems
 - `audio/voice-line` — the voice bus that triggers ducking
-- `references/godot-version.md` — Godot 4.5 AudioServer and Tween API
+- `../../../references/godot-version.md` — Summer compatibility for AudioServer
+  and Tween APIs

package/skills/audio/ambient-bed/SKILL.md

@@ -17,7 +17,8 @@ An ambient bed is the *air* of a place. Forest at dawn, dungeon corridor, spaces
 
 This is **not** music. Use `summer_generate_audio({capability: 'sound_effects'})`, not `{capability: 'music'}`. SFX renders textures; Music renders melody. You want texture.
 
-Generated at 15–22 seconds (the SFX duration ceiling) and looped seamlessly with a Godot loop point and optional crossfade.
+Generated at 15–22 seconds (the SFX duration ceiling) and looped with a Summer
+Engine import loop point and optional crossfade.
 
 ## When to use
 
@@ -102,38 +103,43 @@ If the user wants a busier bed (market, party), still prevent foreground events:
 ```
 summer_generate_audio(
   capability: "sound_effects",
-  prompt: "forest at dawn, gentle wind through leaves, distant bird calls every 6 seconds, soft creaking branches, no music, no human sound, 22s seamless loop",
+  text: "forest at dawn, gentle wind through leaves, distant bird calls every 6 seconds, soft creaking branches, no music, no human sound, 22s seamless loop",
   durationSeconds: 22
 )
-// Result: { asset: { fileUrl, ... } }
 // Then: summer_import_from_url(url: "<fileUrl>", path: "res://audio/ambient/forest_dawn.wav")
 ```
 
+`sound_effects` reads from **`text`**, not `prompt` — passing `prompt` is a 400 `text_required`. (`prompt` is the `music` capability's field.) The clip comes back as WAV, so a `.wav` target path is correct.
+
 22s is the SFX ceiling. Always generate at the ceiling for ambient — longer cycle means less recognized repetition.
 
 If the model returns a clip with a loud event near the start or end (a sudden bird right at 0:00), regenerate. That kills loop seamlessness.
 
-### 6. Mark the seamless loop in Godot's import dock
+### 6. Mark the seamless loop in Summer Engine's Import dock
 
 This step is what makes the bed sound like a place rather than a 22-second sample.
 
-In the Godot editor, select the `.wav`, open the Import dock:
+WAV and MP3 use **different importers with different option names** — do not copy the MP3 block from `audio/music-track` here. The WAV importer has no `loop` / `loop_offset`; it has an `edit/loop_mode` enum plus sample-frame bounds.
+
+In Summer Engine, select the `.wav` and open the Import dock:
 
 | Setting | Value |
 |---|---|
-| Loop | On |
-| Loop Mode | Forward |
-| Loop Begin | 0 (or 0.5 if there's a fade-in artifact) |
+| Edit > Loop Mode | Forward |
+| Edit > Loop Begin | 0 |
+| Edit > Loop End | -1 (end of file) |
 
 The `.import` file:
 
 ```
 [params]
-loop = true
-loop_offset = 0.0
-loop_mode = 1
+edit/loop_mode = 2
+edit/loop_begin = 0
+edit/loop_end = -1
 ```
 
+`edit/loop_mode` is `0 = Detect From WAV, 1 = Disabled, 2 = Forward, 3 = Ping-Pong, 4 = Backward` — Forward is **2**, not 1. `edit/loop_begin` / `edit/loop_end` are integer sample frames, not seconds; to skip a 0.5 s fade-in artifact at 44.1 kHz set `edit/loop_begin = 22050`.
+
 After changing, click `Reimport`.
 
 ### 7. Crossfade-loop pattern for seamlessness
@@ -190,11 +196,11 @@ This eliminates the click and adds variation through phase-overlap (the loop ove
 For most beds, non-positional is correct (the player is *in* the place; the bed isn't an emitter):
 
 ```
-summer_add_node(parentPath="/root/Game/Level", type="AudioStreamPlayer", name="AmbientBed")
-summer_set_prop(path="/root/Game/Level/AmbientBed", property="stream", value="res://audio/ambient/forest_dawn.wav")
-summer_set_prop(path="/root/Game/Level/AmbientBed", property="bus", value="Ambient")
-summer_set_prop(path="/root/Game/Level/AmbientBed", property="volume_db", value=-12.0)
-summer_set_prop(path="/root/Game/Level/AmbientBed", property="autoplay", value=true)
+summer_add_node(scenePath="res://levels/level_01.tscn", parent="./Level", type="AudioStreamPlayer", name="AmbientBed")
+summer_set_prop(scenePath="res://levels/level_01.tscn", path="./Level/AmbientBed", key="stream", value="res://audio/ambient/forest_dawn.wav")
+summer_set_prop(scenePath="res://levels/level_01.tscn", path="./Level/AmbientBed", key="bus", value="Ambient")
+summer_set_prop(scenePath="res://levels/level_01.tscn", path="./Level/AmbientBed", key="volume_db", value=-12.0)
+summer_set_prop(scenePath="res://levels/level_01.tscn", path="./Level/AmbientBed", key="autoplay", value=true)
 ```
 
 Or attach the script in step 7 to a Node, set its `stream` to the imported audio, and skip the `AudioStreamPlayer` node — the script provides its own.

package/skills/audio/audio-direction/SKILL.md

@@ -139,7 +139,8 @@ Rules:
 
 ### 8. Configure the audio bus layout
 
-Real audio in Godot needs a bus layout. Default Godot has Master only — configure the buses now.
+Real audio in Summer Engine needs a bus layout. A new project starts with only
+the Master bus, so configure the remaining buses now.
 
 **Preferred (Summer MCP):** Buses are typically in `default_bus_layout.tres`. Modify project setting:
 
@@ -151,7 +152,8 @@ Ask the user:
 
 > May I create `audio/default_bus_layout.tres` with these buses: Master / Music / SFX / UI / Voice / Ambient / Reverb_Small / Reverb_Large / Reverb_Outdoor?
 
-On yes, write the `.tres` directly via `Write` (it's plain Godot resource format the host can produce):
+On yes, write the `.tres` directly via `Write` (it is the engine's plain-text
+resource format):
 
 ```
 Write audio/default_bus_layout.tres
@@ -204,11 +206,13 @@ Ask:
 If the user wants to start generating, propose 3-5 SFX seeds aligned with the vocabulary. These are starting points, not finals.
 
 ```
-summer_generate_audio(prompt="soft woody UI click, 80ms, no reverb, neutral pitch", duration=0.1)
-summer_generate_audio(prompt="warm major-third coin pickup, 300ms, light reverb", duration=0.3)
-summer_generate_audio(prompt="punchy low-mid player damage hit, slight detune, 200ms, no tail", duration=0.2)
+summer_generate_audio(capability="sound_effects", text="soft woody UI click, 80ms, no reverb, neutral pitch", durationSeconds=0.5)
+summer_generate_audio(capability="sound_effects", text="warm major-third coin pickup, 300ms, light reverb", durationSeconds=0.5)
+summer_generate_audio(capability="sound_effects", text="punchy low-mid player damage hit, slight detune, 200ms, no tail", durationSeconds=0.5)
 ```
 
+`capability` is required; `sound_effects` reads from `text` (not `prompt`), and the length argument is `durationSeconds` (not `duration`) with a floor of 0.5 s. Ask for the character you want inside the text and let the player only use the front of the clip — you cannot request 80 ms.
+
 Ask first:
 
 > May I generate first-pass SFX seeds for UI, pickup, and damage classes? They're starting points, not finals.
@@ -235,11 +239,11 @@ End with:
 | Pure sine "ding" for pickup | Reads as cheap mobile game. Use a major-third interval with character. |
 | Same footstep sample for all surfaces | Material-aware footsteps are 80% of the perceived audio quality. |
 | No master ceiling / true peak | Audio clips on console builds without `-1 dBTP` ceiling. Always set it. |
-| Calling SetResourceProperty on inline sub_resources | Silent fail. See `references/mcp-tools-reference.md` § Trap. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `../../../references/mcp-tools-reference.md` § Trap. |
 
 ## Collaborative protocol
 
-This skill writes one bible (`.summer/audio-bible.md`), creates a bus layout (`audio/default_bus_layout.tres`), modifies `project.godot`, and may generate audio (metered). Always ask before writing or generating. See `references/collaborative-protocol.md`.
+This skill writes one bible (`.summer/audio-bible.md`), creates a bus layout (`audio/default_bus_layout.tres`), modifies `project.godot`, and may generate audio (metered). Always ask before writing or generating. See `../../../references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -247,9 +251,10 @@ No template — this is a workflow that produces the bible the rest of the proje
 
 ## See also
 
-- `references/collaborative-protocol.md`
-- `references/godot-version.md` — Godot 4.5 audio API notes
-- `references/mcp-tools-reference.md`
+- `../../../references/collaborative-protocol.md`
+- `../../../references/godot-version.md` — Summer compatibility and
+  version-sensitive audio API notes
+- `../../../references/mcp-tools-reference.md`
 - `scene-and-project/brainstorm-game/SKILL.md` — produces the brief that anchors the bible
 - `rendering-and-lighting/art-direction/SKILL.md` — the visual counterpart; audio must rhyme with it
 - `audio/audio-bus-setup/SKILL.md` (NEXT) — implements the bus layout in detail

package/skills/audio/music-track/SKILL.md

@@ -13,7 +13,7 @@ paths: ["audio/music/**", "scripts/**", "**/*.tscn"]
 
 ## Overview
 
-ElevenLabs Music renders 10–300 seconds of music from a prompt. The output quality depends entirely on prompt specificity: tempo (BPM), key, instrumentation, mood, structural cue. "Epic orchestral" returns generic stock music. "85 BPM, D minor, solo cello and detuned upright piano, sparse, melancholic, no drums, 4/4" returns a usable score for a melancholic exploration scene.
+ElevenLabs Music renders a track from a prompt. Summer clamps the requested length to **3–600 seconds** before sending it, so anything outside that range is silently pulled to the nearest bound. The output quality depends entirely on prompt specificity: tempo (BPM), key, instrumentation, mood, structural cue. "Epic orchestral" returns generic stock music. "85 BPM, D minor, solo cello and detuned upright piano, sparse, melancholic, no drums, 4/4" returns a usable score for a melancholic exploration scene.
 
 This skill produces one track aligned with the audio bible's music style and dynamic music plan, then wires it as an `AudioStreamPlayer` on the `Music` bus with a marked loop point if it's a loop, or as a linear cinematic stream if it's a one-shot.
 
@@ -126,21 +126,26 @@ Show the prompt:
 > `85 BPM, D minor, 4/4, solo cello and detuned upright piano, sparse, melancholic exploration loop, no drums, gentle reverb, 60s loop`
 > Duration 60s. Cost: ~12 credits. Generate?
 
+The `music` capability reads the description from **`prompt`**, not `text` — the mirror image of `sound_effects`. Passing `text` here is a 400 `prompt_required`.
+
 ```
 summer_generate_audio(
   capability: "music",
   prompt: "85 BPM, D minor, 4/4, solo cello and detuned upright piano, sparse, melancholic exploration loop, no drums, gentle reverb, 60s loop",
   durationSeconds: 60
 )
-// Result: { asset: { fileUrl, ... } }
 // Then: summer_import_from_url(url: "<fileUrl>", path: "res://audio/music/calm_exploration.mp3")
 ```
 
-`durationSeconds` range is 10–300.
+`durationSeconds` is clamped to 3–600. Music comes back as MP3 (`audio/mpeg`), so a `.mp3` target path is correct.
+
+### 7. Mark the loop point in Summer Engine
 
-### 7. Mark the loop point in Godot
+ElevenLabs Music does not return a loop-clean cut. You must mark the loop point
+in Summer Engine's Import dock so playback returns to the loop point on
+completion, not to 0:00.
 
-ElevenLabs Music does not return a loop-clean cut. You must mark the loop point in Godot's import dock so playback returns to the loop point on completion, not to 0:00.
+The MP3 importer exposes exactly five options — `loop`, `loop_offset`, `bpm`, `beat_count`, `bar_beats`. There is **no `loop_mode`** on MP3 or OGG; `loop_mode` belongs to the WAV importer, where it is spelled `edit/loop_mode`.
 
 In `audio/music/calm_exploration.mp3.import`:
 
@@ -148,21 +153,22 @@ In `audio/music/calm_exploration.mp3.import`:
 [params]
 loop = true
 loop_offset = 0.0
-loop_mode = 0  # 0=disabled, 1=forward, 2=ping-pong, 3=backward
 ```
 
-If the start has a fade-in but the body is loopable, set `loop_offset = 4.0` (4 seconds of intro skipped on loop, plays full track first time).
+If the start has a fade-in but the body is loopable, set `loop_offset = 4.0` (4 seconds of intro skipped on loop, plays full track first time). `bpm` + `beat_count` + `bar_beats` are what you set if you want beat-synced transitions later — see `audio/adaptive-music`.
 
 For seamless looping, the cleaner option is to ask the model to generate a cell (one bar / one phrase) and concatenate; or generate at 60s and trust the model's structural cue. Crossfade looping in code is the practical fallback (see step 9).
 
 ### 8. Wire it as `AudioStreamPlayer` on the `Music` bus
 
+Every scene-mutating tool takes an explicit `scenePath`, node paths are relative to the scene root (`./`), and the property argument is named `key`, not `property`:
+
 ```
-summer_add_node(parentPath="/root/Game", type="AudioStreamPlayer", name="MusicCalm")
-summer_set_prop(path="/root/Game/MusicCalm", property="stream", value="res://audio/music/calm_exploration.mp3")
-summer_set_prop(path="/root/Game/MusicCalm", property="bus", value="Music")
-summer_set_prop(path="/root/Game/MusicCalm", property="volume_db", value=-8.0)
-summer_set_prop(path="/root/Game/MusicCalm", property="autoplay", value=true)
+summer_add_node(scenePath="res://main.tscn", parent=".", type="AudioStreamPlayer", name="MusicCalm")
+summer_set_prop(scenePath="res://main.tscn", path="./MusicCalm", key="stream", value="res://audio/music/calm_exploration.mp3")
+summer_set_prop(scenePath="res://main.tscn", path="./MusicCalm", key="bus", value="Music")
+summer_set_prop(scenePath="res://main.tscn", path="./MusicCalm", key="volume_db", value=-8.0)
+summer_set_prop(scenePath="res://main.tscn", path="./MusicCalm", key="autoplay", value=true)
 ```
 
 Music is `AudioStreamPlayer` (not 2D / 3D) — non-positional. The bible's `Music -8 dB` mix sits the music behind SFX where it belongs.