summer-engine 2.7.0 → 2.8.0

package/skills/2d-assets/ui-graphics/SKILL.md

@@ -11,7 +11,9 @@ paths: ["assets/**", "ui/**", "art/ui/**"]
 
 # ui-graphics — Icons, Buttons, Panels, HUD
 
-This skill generates flat, game-UI-style graphics: icons (skill / item / status), buttons (idle / hover / pressed states), panels and frames (NinePatch-friendly), HUD widgets (health frames, minimaps, badges). Output is **transparent PNG** by default and wires via Godot's `TextureRect`, `NinePatchRect`, or `AtlasTexture`.
+This skill generates flat game-UI graphics: icons, button states, panels,
+frames, and HUD widgets. Output is **transparent PNG** by default and wires
+through Summer Engine `TextureRect`, `NinePatchRect`, or `AtlasTexture` nodes.
 
 UI graphics succeed or fail on **two specific things**: a clean transparent background (no checkerboard residue) and a consistent visual language across the set (all icons share line weight, color treatment, lighting). This skill encodes both.
 
@@ -52,18 +54,20 @@ Every icon / button / panel re-uses this anchor verbatim. Skipping this step pro
 ### 2. Search before generating
 
 ```
-summer_search_assets(query="<subject> icon", filter={ kind: "image" })
+summer_search_assets(query="<subject> icon", assetType="2d_image", source="all")
 ```
 
 ### 3. Pick the right pattern (icon vs button vs panel)
 
-| Asset class | Image size | Wiring node | Notes |
+`summer_generate_image` has no size or aspect argument — every MCP image comes back at the server's 1:1 default. Square suits icons, panels, and badges; for wide assets (buttons, HUD bar frames) describe the proportions in the prompt and crop after, or generate in the Summer dashboard where aspect ratio is exposed.
+
+| Asset class | Framing | Wiring node | Notes |
 |---|---|---|---|
-| Icon (ability, item, status) | `square_hd` | `TextureRect` (or `AtlasTexture` if part of an icon sheet) | Centered subject, generous padding |
-| Button (idle / hover / pressed) | `landscape_4_3` | `Button` with custom theme OR `TextureButton` | Generate 3 variants of the same shape |
-| Panel / frame (NinePatch-friendly) | `square_hd` | `NinePatchRect` | Border + center MUST be visually separable for 9-slicing |
-| HUD bar frame | `landscape_16_9` | `NinePatchRect` over `ProgressBar` | Frame only — bar fill is a separate gradient texture |
-| Badge / emblem | `square_hd` | `TextureRect` | Symmetric, centered, no text |
+| Icon (ability, item, status) | square (default) | `TextureRect` (or `AtlasTexture` if part of an icon sheet) | Centered subject, generous padding |
+| Button (idle / hover / pressed) | wide — prompt for it, crop after | `Button` with custom theme OR `TextureButton` | Generate 3 variants of the same shape |
+| Panel / frame (NinePatch-friendly) | square (default) | `NinePatchRect` | Border + center MUST be visually separable for 9-slicing |
+| HUD bar frame | wide — prompt for it, crop after | `NinePatchRect` over `ProgressBar` | Frame only — bar fill is a separate gradient texture |
+| Badge / emblem | square (default) | `TextureRect` | Symmetric, centered, no text |
 
 ### 4. Build the prompt — subject + anchor + transparent
 
@@ -73,20 +77,22 @@ Pattern:
 <asset class> of <subject>, game UI, <anchor style>, flat design, clean edges, transparent background, centered, isolated
 ```
 
-`transparent background` and `isolated` are the load-bearing words. Without them, you get a square card with a textured background that defeats the purpose.
+`isolated` is load-bearing. For the background, **do not rely on the prompt** — pass `options.removeBackground: true`, which runs a real background-removal pass after generation and returns a PNG with true alpha. That is the single highest-value argument in this skill, and it is the actual fix for the checkerboard failure listed below: models asked for a "transparent background" in text frequently paint the checkerboard.
 
 ### 5. Generate
 
 **Icon example:**
 ```
 summer_generate_image(
-  prompt="ability icon for a fire spell, glowing flame in cupped hand, game UI, flat design with subtle gradient and soft inner shadow, 2px deep navy outline, gold and parchment palette, rounded square frame, transparent background, centered, isolated",
+  prompt="ability icon for a fire spell, glowing flame in cupped hand, game UI, flat design with subtle gradient and soft inner shadow, 2px deep navy outline, gold and parchment palette, rounded square frame, centered, isolated on a plain background. Not photorealistic, no 3D render, no scene background, not busy, no multiple objects.",
   model="nano-banana-2",
   style="none",
-  options={ image_size: "square_hd", negative_prompt: "photorealistic, 3D render, scene background, busy, multiple objects" }
+  options={ removeBackground: true }
 )
 ```
 
+`image_size` and `negative_prompt` do not exist on this tool and are dropped without an error — the negations have to live in the prompt text, and the size is fixed. `removeBackground` is the one `options` key here that does real work.
+
 **Button (3 states in 3 calls):**
 ```
 summer_generate_image(prompt="<subject>, idle state, ...")
@@ -114,22 +120,25 @@ Verify in the import dock: `Mipmaps: off` (UI shouldn't mipmap), `Filter: Linear
 
 ### 7. Wire into the scene
 
+Every scene-mutating tool takes an explicit `scenePath`, node paths are relative to that scene's root (`./`) rather than absolute `/root/...` runtime paths, and the property argument is named `key`, not `property`.
+
 **Icon as TextureRect:**
 ```
-summer_add_node(parentPath="/root/UI/AbilityBar", type="TextureRect", name="FireSpellIcon")
-summer_set_prop(path="/root/UI/AbilityBar/FireSpellIcon", property="texture", value="res://ui/icons/fire_spell.png")
-summer_set_prop(path="/root/UI/AbilityBar/FireSpellIcon", property="expand_mode", value=1)  # KEEP_SIZE → 1 = STRETCH
-summer_set_prop(path="/root/UI/AbilityBar/FireSpellIcon", property="stretch_mode", value=5)  # KEEP_ASPECT_CENTERED
+summer_add_node(scenePath="res://ui/hud.tscn", parent="./AbilityBar", type="TextureRect", name="FireSpellIcon")
+summer_set_prop(scenePath="res://ui/hud.tscn", path="./AbilityBar/FireSpellIcon", key="texture", value="res://ui/icons/fire_spell.png")
+summer_set_prop(scenePath="res://ui/hud.tscn", path="./AbilityBar/FireSpellIcon", key="expand_mode", value=1)  # EXPAND_IGNORE_SIZE
+summer_set_prop(scenePath="res://ui/hud.tscn", path="./AbilityBar/FireSpellIcon", key="stretch_mode", value=5)  # STRETCH_KEEP_ASPECT_CENTERED
 ```
 
 **Panel as NinePatchRect:**
 ```
-summer_add_node(parentPath="/root/UI", type="NinePatchRect", name="InventoryPanel")
-summer_set_prop(path="/root/UI/InventoryPanel", property="texture", value="res://ui/panels/parchment.png")
-summer_set_prop(path="/root/UI/InventoryPanel", property="patch_margin_left", value=24)
-summer_set_prop(path="/root/UI/InventoryPanel", property="patch_margin_right", value=24)
-summer_set_prop(path="/root/UI/InventoryPanel", property="patch_margin_top", value=24)
-summer_set_prop(path="/root/UI/InventoryPanel", property="patch_margin_bottom", value=24)
+summer_add_node(scenePath="res://ui/hud.tscn", parent=".", type="NinePatchRect", name="InventoryPanel")
+summer_set_prop(scenePath="res://ui/hud.tscn", path="./InventoryPanel", key="texture", value="res://ui/panels/parchment.png")
+summer_set_prop(scenePath="res://ui/hud.tscn", path="./InventoryPanel", key="patch_margin_left", value=24)
+summer_set_prop(scenePath="res://ui/hud.tscn", path="./InventoryPanel", key="patch_margin_right", value=24)
+summer_set_prop(scenePath="res://ui/hud.tscn", path="./InventoryPanel", key="patch_margin_top", value=24)
+summer_set_prop(scenePath="res://ui/hud.tscn", path="./InventoryPanel", key="patch_margin_bottom", value=24)
+summer_save_scene(scenePath="res://ui/hud.tscn")
 ```
 
 Tune patch margins to match the actual border width in the generated texture. Open the texture in the editor's NinePatch preview to verify.
@@ -155,26 +164,30 @@ If you generate a 4×4 grid of icons in one image, each icon becomes an `AtlasTe
 | Bad | Failure mode |
 |---|---|
 | `cool button` | No subject, no anchor. Returns a generic button on a card background. |
-| `transparent button with icon` (no negative prompt) | Model often renders a checkerboard "transparent" pattern as the actual fill. Add `no checkerboard pattern` to negative. |
+| `transparent button with icon` | Model often renders a checkerboard "transparent" pattern as the actual fill. There is no negative-prompt argument to counter it — drop the word "transparent" from the prompt entirely and pass `options.removeBackground: true` instead. |
 | `8 ability icons in one image` | Inconsistent style across the 8. Generate one at a time with the same anchor. |
 | `realistic 3D rendered button` | Conflicts with flat-UI. Stay flat. |
-| `button with the word "Play"` on it | Models render text badly. Add text in Godot via a `Label` over the button, not in the texture. |
+| `button with the word "Play"` on it | Models render text badly. Add text in Summer Engine via a `Label` over the button, not in the texture. |
 
 ## Anti-patterns
 
 - **Skipping the anchor.** A 12-icon ability bar with no anchor looks like 12 unrelated games. Define the anchor on icon #1.
-- **Letting the model render text.** Diffusion models can't render reliable text. Always overlay text in Godot via a `Label` node. The button texture is the frame; the label is the word.
-- **Forgetting `transparent background` in the prompt.** Default is opaque. Without the keyword, you import an icon with a 200×200 white square around the actual icon.
-- **Using `style: "realistic"` for UI.** UI is flat. `style: "none"` lets the prompt's "flat design" land cleanly.
+- **Letting the model render text.** Diffusion models cannot render reliable
+  text. Always overlay text in Summer Engine with a `Label` node. The button
+  texture is the frame; the label is the word.
+- **Forgetting `options.removeBackground: true`.** Default is opaque. Prompting for "transparent background" instead is what produces the painted-checkerboard failure below — the option runs a real alpha pass and does not.
+- **Expecting `style` to do the work.** Only `cartoon` and `anime` append anything; `realistic` and `none` append nothing, and any other value is coerced to `none`. `style: "none"` is right for UI, but "flat design" has to be in the prompt regardless.
 - **NinePatch with no border-vs-center distinction.** The 9-slice scaling smears the border into the center.
 - **Mipmaps on UI.** UI textures shouldn't mipmap — they're displayed at 1:1 or near it. Mipmaps waste memory and blur sharp edges.
 
 ## Edge cases
 
-- **User wants the same icon at multiple sizes (32, 64, 128).** Generate once at high res. Godot's `TextureRect` with `STRETCH_KEEP_ASPECT_CENTERED` scales it down cleanly. Don't generate three sizes.
+- **User wants the same icon at multiple sizes (32, 64, 128).** Generate once
+  at high resolution. Summer Engine's `TextureRect` with
+  `STRETCH_KEEP_ASPECT_CENTERED` scales it down cleanly.
 - **User wants pixel-style UI.** Route to `summer:2d-assets/pixel-art` — different prompt pattern, different filter, different anchor.
 - **User wants animated UI (spinning loading icon).** Generate the static frame here. Animate via `AnimationPlayer` rotating the `TextureRect`, not as a sprite sheet.
-- **Transparency comes back as a checkerboard pattern in the image.** The model rendered the checkerboard literally. Regenerate with `no checkerboard pattern, true alpha transparency` in the negative prompt.
+- **Transparency comes back as a checkerboard pattern in the image.** The model rendered the checkerboard literally because the prompt asked for transparency. Remove every mention of transparency from the prompt, generate on a plain background, and pass `options.removeBackground: true` to cut the alpha server-side.
 - **Icons need to read at very small size (16-24px in a packed bar).** Bias prompts toward bold silhouette + minimal interior detail. Ornate detail is invisible at 16px and adds noise.
 
 ## Fallback (no MCP)
@@ -183,10 +196,10 @@ Print the call:
 
 ```
 summer_generate_image(
-  prompt="<asset + anchor + transparent>",
+  prompt="<asset + anchor>, isolated on a plain background. No scene background, not photorealistic, no 3D, not busy.",
   model="nano-banana-2",
   style="none",
-  options={ image_size: "square_hd", negative_prompt: "scene background, photorealistic, 3D, busy" }
+  options={ removeBackground: true }
 )
 ```
 
@@ -198,7 +211,8 @@ After the UI graphic is wired:
 
 - **More icons in the same set** → re-invoke this skill with the same anchor.
 - **Button states (hover/pressed)** → re-invoke for each state.
-- **Theme assembly (combining icons + panels into a Godot Theme resource)** → `summer:scene-composition` for the Theme resource wiring.
+- **Theme assembly (combining icons + panels into a Summer Engine Theme
+  resource)** → `summer:scene-composition` for the resource wiring.
 - **Pixel-art UI** → `summer:2d-assets/pixel-art`.
 - **Dialogue UI with portraits** → `summer:2d-assets/character-portrait` for the portrait, then back here for the surrounding panel.
 
@@ -207,4 +221,4 @@ After the UI graphic is wired:
 - `summer:2d-assets/character-portrait` — for in-UI character images.
 - `summer:2d-assets/pixel-art` — pixel-style UI.
 - `summer:scene-composition` — Theme and Control hierarchy.
-- `references/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/2d-assets/use-widget-asset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: use-widget-asset
-description: Use when consuming a widget slice (panel, button, slider, progress bar, or toggle pair) from a `create-asset-sheet` pack into a Godot scene. The pack's metadata.sliceMeta carries 9-slice margins, fill rects, and on/off pair links per slice — this skill explains how to wire those into NinePatchRect / TextureProgressBar / TextureRect so the asset behaves like a real UI control instead of a static texture.
+description: Use when consuming a widget slice (panel, button, slider, progress bar, or toggle pair) from a `create-asset-sheet` pack in a Summer Engine scene. The pack's metadata.sliceMeta carries 9-slice margins, fill rects, and on/off pair links per slice. This skill explains how to wire those into NinePatchRect, TextureProgressBar, or TextureRect so the asset behaves like a real UI control instead of a static texture.
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
@@ -9,9 +9,9 @@ allowed-tools: Read Grep Glob Write Edit summer_add_node summer_set_prop summer_
 paths: ["assets/**", "art/**", "ui/**", "scenes/**"]
 ---
 
-# use-widget-asset — Wire a sliced widget into a real Godot control
+# use-widget-asset — Wire a sliced widget into a Summer Engine control
 
-When the `create-asset-sheet` wizard sees a stretchable UI element (a panel, a slider, a progress bar, a toggle), it returns more than a flat PNG. It returns geometry: **9-slice frame margins** for stretchable rectangles, and a **fill rect** for value-driven widgets. It also pairs ON/OFF toggle slices via `pairWith`. This skill is the runtime side: how to read that metadata and wire the asset into the right Godot node.
+When the `create-asset-sheet` wizard sees a stretchable UI element (a panel, a slider, a progress bar, a toggle), it returns more than a flat PNG. It returns geometry: **9-slice frame margins** for stretchable rectangles, and a **fill rect** for value-driven widgets. It also pairs ON/OFF toggle slices via `pairWith`. This skill is the runtime side: how to read that metadata and wire the asset into the right Summer Engine node.
 
 If a slice has no widget metadata, treat it as a static texture (`TextureRect`) and skip this skill.
 
@@ -57,7 +57,7 @@ metadata.sliceMeta:   { "0": { category, widget?, pairWith?, parentSliceIndex? }
 }
 ```
 
-Margins and rect are **percentages of the SLICE's own pixel dimensions** (not the source sheet). Convert to pixels with `Math.round(pct * sliceWidth / 100)` before applying to a Godot node.
+Margins and rect are **percentages of the SLICE's own pixel dimensions** (not the source sheet). Convert to pixels with `Math.round(pct * sliceWidth / 100)` before applying to a Summer Engine node.
 
 ## Decision tree
 
@@ -132,7 +132,9 @@ Set `value` from 0 to 100 to drive the bar.
 
 ### 3. Slider — HSlider with TextureRect overlays
 
-`Slider` in Godot is a behavioral node (drag input + value range); it doesn't ship visuals on its own. Combine it with two `TextureRect`s underneath: one for the track (the slice texture, optionally as NinePatchRect for stretch) and one for the knob (a separate small slice cut from the slider's `fillRect` end).
+`Slider` in Summer Engine is a behavioral node (drag input + value range); it
+does not ship visuals on its own. Combine it with two `TextureRect`s underneath:
+one for the track and one for the knob.
 
 Simplest wiring: NinePatchRect for the track using `frameMargins`, an HSlider on top with `flat = true` and `theme_override_styles/grabber_area = null`, and a child `TextureRect` for the knob positioned via `slider.ratio`.
 
@@ -181,7 +183,7 @@ The wizard's Break-down pass produces two new per-slice fields the runtime must
 | `zOrder` | number | Back-to-front paint order on children. Lower = behind. Matches Godot `z_index`, Unity `sortingOrder`, CSS `z-index`. |
 | `parentSliceIndex` | number | Set on each child, points at the composite parent. Used to group children. |
 
-The full schema lives at `publicsummerengine/public/knowledge/asset_pack_schema.json`. Read it once if you need to know every field.
+The full schema is the zod definition at `publicsummerengine/src/lib/asset-packs/schema.ts` (`SliceMetaSchema`, `PACK_SCHEMA_VERSION`, and the legacy-migration helper). Read it once if you need to know every field.
 
 ### Consume recipe
 

package/skills/3d-assets/character-model/SKILL.md

@@ -19,7 +19,7 @@ The whole flow:
 1. T-pose reference image    →  summer_generate_image                          (~$0.05, ~10s)
 2. Un-rigged 3D mesh         →  summer_generate_3d(image-to-3d)                (~$0.50, ~60s)
 3. ── USER REVIEW GATE ──
-4. Rigged .glb               →  summer_generate_3d(image-to-3d, rig: true)     (~$1.00, ~90s)
+4. Rigged .glb               →  summer_generate_3d(image-to-3d, rig=true)      (~$1.00, ~90s)
 5. Import → editor RESTART → wire as CharacterBody3D / Node3D
 6. Hand off to summer:animation/generate-motion for clips
 ```
@@ -133,10 +133,13 @@ If the user wants changes, loop back to step 1 or 2. Do NOT silently run the rig
 summer_generate_3d({
   kind: "image-to-3d",
   imageUrl: "<image url from step 1>",
-  options: { rig: true, polyTarget: 12000 }   // polyTarget is best-effort; backend may use options.target_polycount
+  rig: true,
+  options: { target_polycount: 12000 }
 })
 ```
 
+`rig` is a **top-level boolean argument** on `summer_generate_3d` (the tool also merges it into `options.rig`, so `options: { rig: true }` works too). There is no `polyTarget` — the polycount key is `target_polycount` inside `options`, exactly as in step 2. Related top-level arguments worth knowing here: `riggingHeightMeters` for character height, and `animationNames` / `actionIds` to have the shared animated-character pipeline produce clips in the same job instead of a separate `summer_generate_motion` pass.
+
 Returns a job whose result includes `assetId`, `fileUrl`, and `rigAssetId`.
 If you ran with `wait: false`, poll via `summer_check_job(jobId)`. The
 `rigAssetId` is the handle `summer:animation/generate-motion` needs — store it.
@@ -154,11 +157,11 @@ summer_import_asset_by_id(
 
 ### 5. ⚠️ Restart the editor
 
-**Known Godot 4.5 gotcha:** after importing a rigged `.glb`, the `Skeleton3D` node appears stale in the scene dock — bones are missing, `skeleton.get_bone_count()` returns 0, and `AnimationPlayer` libraries fail to bind. The fix:
+**Known gotcha:** after importing a rigged `.glb`, the `Skeleton3D` node appears stale in the scene dock — bones are missing, `skeleton.get_bone_count()` returns 0, and `AnimationPlayer` libraries fail to bind. The fix:
 
 > The rigged mesh is imported. Please restart the Summer Engine editor (close and reopen) so the Skeleton3D rebuilds correctly. Without the restart, animations will fail to bind.
 
-There is no programmatic workaround as of Godot 4.5.x. Tell the user, wait, then continue.
+No programmatic workaround is known. Tell the user, wait, then continue.
 
 ### 6. Wire as CharacterBody3D or Node3D — pick the right parent
 
@@ -169,25 +172,33 @@ There is no programmatic workaround as of Godot 4.5.x. Tell the user, wait, then
 | Pure-visual character (background extra, dialogue head) | `Node3D` | Same as above |
 | Ragdoll-on-death enemy | `CharacterBody3D` while alive, swap to `RigidBody3D` skeleton on death | Two-mode rig; see `summer:animation/procedural-animation` |
 
+Four things the call shapes below encode:
+
+- **Every scene-mutating tool takes an explicit `scenePath`** and the scene need not be the active editor tab.
+- **Node paths are relative to that scene's root (`./`)**, not absolute `/root/...` runtime paths.
+- **`summer_set_prop`'s property argument is named `key`**, not `property`.
+- **A `.glb` is instantiated, not assigned.** There is no `scene` property on `Node3D`, and an imported `.glb` is a scene rather than a `Mesh` — on the shipped 4.6.1 binary `ResourceLoader.get_recognized_extensions_for_type("Mesh")` returns `["tres", "mesh", "res"]`, with no `glb`. Use `summer_instantiate_scene`.
+
 **CharacterBody3D wiring (player / enemy):**
 
 ```
-summer_add_node(parent="./World", type="CharacterBody3D", name="Knight")
-summer_set_prop(path="./World/Knight", property="position", value="Vector3(0, 0, 0)")
-summer_add_node(parent="./World/Knight", type="Node3D", name="Mesh")
-# Instantiate the imported scene as a child of the Mesh node
-summer_set_prop(path="./World/Knight/Mesh", property="scene", value="res://assets/characters/knight.glb")
-summer_add_node(parent="./World/Knight", type="CollisionShape3D", name="Collider")
-# Add a CapsuleShape3D resource (height ~1.7m, radius ~0.4m) to the collider
-summer_save_scene
+summer_add_node(scenePath="res://main.tscn", parent="./World", type="CharacterBody3D", name="Knight")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Knight", key="position", value="Vector3(0, 0, 0)")
+summer_instantiate_scene(scenePath="res://main.tscn", parent="./World/Knight", scene="res://assets/characters/knight.glb", name="Mesh")
+summer_add_node(scenePath="res://main.tscn", parent="./World/Knight", type="CollisionShape3D", name="Collider")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Knight/Collider", key="shape", value="CapsuleShape3D")
+summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Knight/Collider", resourceProperty="shape", subProperty="height", value=1.7)
+summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Knight/Collider", resourceProperty="shape", subProperty="radius", value=0.4)
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
+Assigning a bare class name like `"CapsuleShape3D"` to a resource property auto-instantiates it, which is how you get a shape you can then size. `summer_set_resource_property` needs all five of `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value`.
+
 **Node3D wiring (cinematic NPC):**
 
 ```
-summer_add_node(parent="./World/Tavern", type="Node3D", name="OldWizard")
-summer_set_prop(path="./World/Tavern/OldWizard", property="scene", value="res://assets/characters/wizard.glb")
-summer_save_scene
+summer_instantiate_scene(scenePath="res://main.tscn", parent="./World/Tavern", scene="res://assets/characters/wizard.glb", name="OldWizard")
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
 The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty library). The animation skill writes into that AnimationPlayer.
@@ -196,7 +207,11 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 
 > Knight is wired at `./World/Knight` with a Meshy-rigged skeleton. `rigAssetId` saved.
 >
-> Next: `summer:animation/generate-motion` to add idle / walk / run / attack clips. Example call: `summer_generate_motion(rigAssetId: "<saved id>", backend: "meshy-library", motionName: "walk")`. The animation skill uses Meshy's curated mocap library (~70 standard motions). Custom prompt-driven motion is on the roadmap; for one-off signature moves not on the curated list, fall back to hand-authoring in the Godot editor or importing from Mixamo.
+> Next: `summer:animation/generate-motion` to add idle / walk / run / attack
+> clips. Example call: `summer_generate_motion(rigAssetId: "<saved id>",
+> backend: "meshy-library", motionName: "walk")`. Custom prompt-driven motion
+> is not shipped; hand-author one-off moves in Summer Engine or import a
+> licensed clip.
 
 ## Anti-patterns
 
@@ -221,9 +236,9 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 1. Generate the T-pose reference at the Summer dashboard (or any image gen — Midjourney, nano-banana web, DALL-E).
 2. Upload to Meshy at meshy.ai → Image to 3D → enable rigging.
 3. Download the `.glb`.
-4. Drop into `res://assets/characters/` — Godot's import dock picks it up.
+4. Drop into `res://assets/characters/`; Summer Engine's Import dock picks it up.
 5. Restart the editor.
-6. Wire as CharacterBody3D / Node3D in the Godot editor manually.
+6. Wire as CharacterBody3D / Node3D in Summer Engine manually.
 
 The output is identical to the MCP path — same Meshy skeleton, same compatibility with `summer:animation/generate-motion` (which has its own dashboard fallback).
 
@@ -244,4 +259,4 @@ After the rigged character is wired:
 - `summer:asset-pipeline/asset-strategy` — meta-router; this skill is the canonical drill-down of its "Image-to-3D for characters" path.
 - `summer:3d-assets/prop-model` — for non-character props.
 - `summer:scene-composition` — for the CharacterBody3D + Mesh + Collider parent pattern.
-- `references/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.
+- `../../../references/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.

package/skills/3d-assets/environment-kit/SKILL.md

@@ -113,13 +113,18 @@ Polycount targets per kit piece: walls/floors 800–1500 tris (placed dozens of
 Don't dump the kit into the level scene. Make a `kit_dungeon.tscn` that holds one of every piece, labelled, positioned next to each other on the snap grid. The level designer instantiates from there.
 
 ```
-summer_add_node(parent="./KitRoot", type="Node3D", name="Wall")
-summer_set_prop(path="./KitRoot/Wall", property="scene", value="res://assets/kits/dungeon/wall.glb")
-summer_set_prop(path="./KitRoot/Wall", property="position", value="Vector3(0, 0, 0)")
+summer_instantiate_scene(scenePath="res://assets/kits/dungeon/kit_dungeon.tscn", parent="./KitRoot", scene="res://assets/kits/dungeon/wall.glb", name="Wall")
+summer_set_prop(scenePath="res://assets/kits/dungeon/kit_dungeon.tscn", path="./KitRoot/Wall", key="position", value="Vector3(0, 0, 0)")
 # ...repeat for floor, pillar, door, corner, arch with positions Vector3(2,0,0), Vector3(4,0,0), ...
-summer_save_scene
+summer_save_scene(scenePath="res://assets/kits/dungeon/kit_dungeon.tscn")
 ```
 
+Three things the shape of those calls encodes:
+
+- **A `.glb` is instantiated, not assigned.** There is no `scene` property on `Node3D`, and an imported `.glb` is a scene, not a `Mesh` — `ResourceLoader.get_recognized_extensions_for_type("Mesh")` on the shipped 4.6.1 binary returns `["tres", "mesh", "res"]`, with no `glb`. Use `summer_instantiate_scene`, which adds the model as a child in one op.
+- **Every scene-mutating tool takes an explicit `scenePath`**, and node paths are relative to that scene's root (`./`).
+- **`summer_set_prop`'s property argument is named `key`**, not `property`.
+
 ### 5. Verify scale and pivots
 
 ```
@@ -149,7 +154,8 @@ Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the
 1. Run each prompt at the Summer dashboard (or Hunyuan / Trellis web UIs), keeping the locked suffix.
 2. Download each `.glb`.
 3. Drop into `res://assets/kits/<kit-name>/`.
-4. Build the kit-display scene manually in Godot — one of each piece, snapped to grid.
+4. Build the kit-display scene manually in Summer Engine, with one of each piece
+   snapped to the grid.
 5. Hand to the level designer.
 
 ## Handoff

package/skills/3d-assets/organic-model/SKILL.md

@@ -129,11 +129,14 @@ Then scatter all five with random rotation. Five unique meshes + rotation = look
 **Hero tree:**
 
 ```
-summer_add_node(parent="./World/Forest", type="MeshInstance3D", name="HeroOak")
-summer_set_prop(path="./World/Forest/HeroOak", property="mesh", value="res://assets/organic/oak_tree.glb")
-summer_save_scene
+summer_instantiate_scene(scenePath="res://main.tscn", parent="./World/Forest", scene="res://assets/organic/oak_tree.glb", name="HeroOak")
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
+A `.glb` cannot be assigned to `MeshInstance3D.mesh`. An imported `.glb` is a scene, not a `Mesh` — on the shipped 4.6.1 binary `ResourceLoader.get_recognized_extensions_for_type("Mesh")` returns `["tres", "mesh", "res"]`, with no `glb`. `summer_instantiate_scene` adds it as a child in one op. (For the `MultiMeshInstance3D` path below you do need a real `Mesh`: pull it out of the instantiated scene's `MeshInstance3D` in script, or save it as a `.tres`.)
+
+Every scene-mutating tool takes an explicit `scenePath`; node paths are relative to that scene's root (`./`).
+
 **Forest scatter (MultiMesh):** create a `MultiMeshInstance3D`, assign a `MultiMesh` resource referencing the tree mesh, set `instance_count` to e.g. 100, and populate `set_instance_transform()` from a script with random positions + rotations. See `summer:scene-composition` for the scatter pattern.
 
 ### 6. LOD and billboards
@@ -169,7 +172,7 @@ For a 200-tree forest, ~10 close trees are real meshes, 190 are billboards. Fram
 
 1. Run prompts at the Summer dashboard or any 3D-gen web playground (Hunyuan, Trellis, Meshy).
 2. Download `.glb` files into `res://assets/organic/`.
-3. Build scatter scenes manually in Godot.
+3. Build scatter scenes manually in Summer Engine.
 
 For totally free / offline alternatives: **Quaternius** (free stylized organics), **AmbientCG** (rocks + textures), **Sketchfab** free filter, **Polyhaven** (HDRIs + scans).
 
@@ -190,4 +193,4 @@ After the organic models are scattered:
 - `summer:3d-assets/environment-kit` — pair with this skill: kit pieces give the architecture, organic gives the natural softness.
 - `summer:asset-pipeline/asset-strategy` — meta-router; ground textures and skyboxes go to Pipeline 2 / panoramic gen.
 - `summer:scene-composition` — MultiMeshInstance3D scatter pattern.
-- `references/mcp-tools-reference.md` — `summer_generate_3d` schema.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_3d` schema.

package/skills/3d-assets/prop-model/SKILL.md

@@ -94,11 +94,14 @@ summer_import_asset_by_id(
   assetId="<assetId>",
   path="res://assets/models/viking_axe.glb",
   parent="./World/Props",
+  scenePath="res://main.tscn",
   name="VikingAxe"
 )
-summer_save_scene
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
+`scenePath` is **required whenever `parent` is set** — it names the exact scene that receives the model, and the scene does not have to be the active editor tab. Omitting it fails the import with a `pass the exact scenePath when parent is set` hint. `summer_save_scene` likewise takes an explicit `scenePath`; there is no bare form.
+
 For interactive props (chest the player opens, lantern the player picks up),
 wrap the instantiated model in a `StaticBody3D` (or `RigidBody3D` for physics
 props) with a `CollisionShape3D` sibling — see `summer:scene-composition` for
@@ -122,7 +125,10 @@ the parent-shape pattern.
 
 ## Fallback (no MCP)
 
-The user can run the same prompt at the Summer dashboard (or directly via the Hunyuan / Trellis web UIs), download the `.glb`, drop it into `res://assets/models/`, and Godot's import dock will pick it up. Then add a MeshInstance3D manually in the Godot editor and assign the mesh.
+The user can run the same prompt in the Summer dashboard or a supported
+provider UI, download the `.glb`, and drop it into `res://assets/models/`.
+Summer Engine's Import dock will pick it up. Then add a MeshInstance3D and
+assign the mesh.
 
 ## Handoff
 
@@ -138,4 +144,4 @@ After the prop is wired:
 - `summer:asset-pipeline/asset-strategy` — the meta-router that decides between this skill and Pipeline 2 (textures).
 - `summer:3d-assets/character-model` — for humanoids.
 - `summer:3d-assets/environment-kit` — for style-locked sets.
-- `references/mcp-tools-reference.md` — `summer_generate_3d` parameter schema.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_3d` parameter schema.

package/skills/3d-assets/vehicle-model/SKILL.md

@@ -43,17 +43,26 @@ Vehicles benefit more from polycount than props — flat panels need edge densit
 
 ## Multi-angle reference — the single biggest quality lever
 
-Vehicles are highly view-dependent. A front-only reference produces a mesh with great front detail and a melted rear. The fix: generate a **front + 3/4 side composite reference** before the 3D pass.
+Vehicles are highly view-dependent. A front-only reference produces a mesh with great front detail and a melted rear. There are two ways to give the mesher more than one angle, and they are not the same thing:
+
+**(a) A real multi-image request — prefer this.** `summer_generate_3d` takes an `imageUrls` array of up to four views. These are passed through as separate views, not fused into one picture.
 
 ```
-summer_generate_image(
-  prompt="A sleek red sports car, front view AND 3/4 rear-side view side by side, two angles in one image, white background, studio lighting, clean references for 3D modeling, isolated, no scenery."
+summer_generate_3d(
+  kind="image-to-3d",
+  imageUrls=["<front url>", "<3/4 rear-side url>", "<profile url>"],
+  model="hunyuan",
+  options={ target_polycount: 25000 }
 )
 ```
 
-Most image models will produce a two-view composite. Then feed it to image-to-3D:
+**(b) A composite reference image**, when you only have one slot to work with:
 
 ```
+summer_generate_image(
+  prompt="A sleek red sports car, front view AND 3/4 rear-side view side by side, two angles in one image, white background, studio lighting, clean references for 3D modeling, isolated, no scenery."
+)
+
 summer_generate_3d(
   kind="image-to-3d",
   imageUrl="<composite reference url>",
@@ -62,7 +71,7 @@ summer_generate_3d(
 )
 ```
 
-If the user has reference images already (concept art, photos), prefer those — composite them into a single image first if they aren't already.
+If the user has reference images already (concept art, photos), pass them straight to `imageUrls` — do not composite them down into one image first; that throws away the multi-view path.
 
 ## Steps
 
@@ -88,7 +97,7 @@ Pattern: `<vehicle type> + <silhouette / era / style> + <materials> + <surface s
 | Mech | `A 4 meter tall bipedal combat mech, blocky armored torso, articulated arms with rifle and missile pod, thick legs with hydraulic pistons, painted olive drab with hazard stripes. Front and 3/4 side views. Game asset, hard-surface stylized, white background, isolated vehicle.` |
 | Background sedan | `A generic 90s civilian sedan, four doors, beige paint, slightly worn. Front and 3/4 side views. Game asset, low-detail stylized, white background, isolated vehicle.` |
 
-The phrase `front and 3/4 side views` is what triggers the multi-angle composite reference internally.
+Nothing in the prompt text "triggers" multi-view. The phrase `front and 3/4 side views` only shapes what the *image* model draws; the 3D tool has no prompt-sniffing and sees whatever pixels you hand it. Multi-view comes from the `imageUrls` array, nothing else.
 
 ### 4. Confirm and call
 
@@ -135,7 +144,7 @@ This re-textures the existing mesh with sharper detail — panel lines, decals,
 
 | Use case | Parent type | Notes |
 |---|---|---|
-| Player-driven (car, bike, hover) | `VehicleBody3D` (Godot 4.5 wheeled) or `RigidBody3D` (free physics) | Add `VehicleWheel3D` children for wheeled vehicles |
+| Player-driven (car, bike, hover) | `VehicleBody3D` (wheeled) or `RigidBody3D` (free physics) | Add `VehicleWheel3D` children for wheeled vehicles |
 | Player-driven (spaceship, mech) | `RigidBody3D` or `CharacterBody3D` | Custom thrust / walk code, see `summer:character-controllers` |
 | Background scenery (parked, flyby) | `MeshInstance3D` under a `Node3D` | No physics, no collision needed for distant traffic |
 | Background traffic (moving but not interactive) | `Node3D` + `AnimationPlayer` driving the position | Cheap, no physics overhead |
@@ -143,26 +152,30 @@ This re-textures the existing mesh with sharper detail — panel lines, decals,
 **Player car wiring:**
 
 ```
-summer_add_node(parent="./World", type="VehicleBody3D", name="RaceCar")
-summer_add_node(parent="./World/RaceCar", type="MeshInstance3D", name="Body")
-summer_set_prop(path="./World/RaceCar/Body", property="mesh", value="res://assets/vehicles/race_car.glb")
-summer_add_node(parent="./World/RaceCar", type="CollisionShape3D", name="Collider")
-# Add a BoxShape3D resource matched to the AABB
+summer_add_node(scenePath="res://main.tscn", parent="./World", type="VehicleBody3D", name="RaceCar")
+summer_instantiate_scene(scenePath="res://main.tscn", parent="./World/RaceCar", scene="res://assets/vehicles/race_car.glb", name="Body")
+summer_add_node(scenePath="res://main.tscn", parent="./World/RaceCar", type="CollisionShape3D", name="Collider")
+summer_set_prop(scenePath="res://main.tscn", path="./World/RaceCar/Collider", key="shape", value="BoxShape3D")
+summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/RaceCar/Collider", resourceProperty="shape", subProperty="size", value="Vector3(4.5, 1.1, 1.9)")
 # Add VehicleWheel3D children at each wheel position
-summer_save_scene
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
+A `.glb` cannot be assigned to `MeshInstance3D.mesh` — an imported `.glb` is a scene, not a `Mesh` (`ResourceLoader.get_recognized_extensions_for_type("Mesh")` on the shipped 4.6.1 binary returns `["tres", "mesh", "res"]`, no `glb`). Instantiate it. Assigning a bare class name like `"BoxShape3D"` to a resource property auto-instantiates it, which is how you get a shape you can then size.
+
+Every scene-mutating tool takes an explicit `scenePath`; node paths are relative to that scene's root (`./`); `summer_set_prop`'s property argument is `key`; and `summer_set_resource_property` needs all five of `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value`.
+
 **Background scenery wiring:**
 
 ```
-summer_add_node(parent="./World/Street", type="MeshInstance3D", name="ParkedSedan")
-summer_set_prop(path="./World/Street/ParkedSedan", property="mesh", value="res://assets/vehicles/sedan.glb")
-summer_save_scene
+summer_instantiate_scene(scenePath="res://main.tscn", parent="./World/Street", scene="res://assets/vehicles/sedan.glb", name="ParkedSedan")
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
 ## Anti-patterns
 
-- **Single-angle reference for a hero vehicle.** Front-only → melted rear. Always go multi-angle for anything the player gets close to.
+- **Single-angle reference for a hero vehicle.** Front-only → melted rear. Pass an `imageUrls` array (up to four views) for anything the player gets close to.
+- **Expecting the prompt to request multi-view.** It cannot. `imageUrls` is the only multi-view mechanism.
 - **Flat-shaded prompt for hard surfaces.** "Smooth shading", "rounded edges" → loses the panel-line crispness that defines vehicles. Prefer "hard-surface", "panel-lined", "crisp edges".
 - **Skipping symmetry callouts.** Vehicles are bilaterally symmetric — without `symmetric, mirrored` you get one headlight bigger than the other 30% of the time.
 - **Asking the mesh pass to invent decals / liveries.** It can't — the mesh has the silhouette but the decals get geometry-baked weirdly. Use the texture pass for liveries.
@@ -182,7 +195,7 @@ summer_save_scene
 1. Generate the multi-angle reference at the Summer dashboard (or Midjourney / nano-banana web).
 2. Upload to Hunyuan or Trellis web playground → image-to-3D → download `.glb`.
 3. Drop into `res://assets/vehicles/`.
-4. Wire as VehicleBody3D / MeshInstance3D in the Godot editor manually.
+4. Wire as VehicleBody3D / MeshInstance3D in Summer Engine manually.
 
 ## Handoff
 
@@ -200,4 +213,4 @@ After the vehicle is wired:
 - `summer:3d-assets/prop-model` — for separable parts (rotors, decals as decals, modular kit pieces).
 - `summer:asset-pipeline/asset-strategy` — meta-router.
 - `summer:character-controllers` — for player-driven vehicle input wiring.
-- `references/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.

package/skills/README.md

@@ -70,7 +70,7 @@ Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
 
 1. **SKILL.md ≤ 500 lines.** Push detail into `references/`. Progressive disclosure.
 2. **MCP-preferred + file-edit-fallback.** Every code-touching skill must show both paths so the skill works without Summer MCP installed.
-3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `references/collaborative-protocol.md`.
+3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `../references/collaborative-protocol.md`.
 4. **Template cross-link.** When a working starter exists, link via `template-id` and the section "Want a working starter?".
 5. **Test spec.** Every non-`_meta` skill ships `tests/spec.md` with at least one Test Case.