summer-engine 3.8.0 → 4.0.0

package/library/skills/ui-basics/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ui-basics
-description: "Build Summer Engine UI — HUDs, menus, health bars, dialogue boxes, Control trees — anchors, containers, responsive layout, theme vs inline styling."
+description: "Build UI: HUDs, menus, health bars, dialogue boxes, Control trees, anchors, containers and themes."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: ui-and-ux
 user-invocable: false
-allowed-tools: Read Grep summer_add_node summer_set_prop summer_connect_signal summer_save_scene
+allowed-tools: Read Grep summer_run_script summer_add_node summer_set_prop summer_connect_signal summer_save_scene
 paths: ["**/*.tscn", "**/*.gd"]
 ---
 
@@ -40,42 +40,47 @@ Control or CanvasLayer (root)
 
 ## Basic Menu
 
+A menu is a dozen nodes: build it in one `summer_run_script` call (one undo
+step), never as a chain of `summer_add_node` / `summer_set_prop` calls.
+
 ```
-summer_add_node(parent="./", type="Control", name="MainMenu")
-summer_add_node(parent="./MainMenu", type="MarginContainer", name="Margin")
-summer_set_prop(path="./MainMenu/Margin", key="anchors_preset", value="15")  # Full rect
-summer_set_prop(path="./MainMenu/Margin", key="theme_override_constants/margin_left", value="50")
-summer_set_prop(path="./MainMenu/Margin", key="theme_override_constants/margin_right", value="50")
-summer_set_prop(path="./MainMenu/Margin", key="theme_override_constants/margin_top", value="50")
-summer_set_prop(path="./MainMenu/Margin", key="theme_override_constants/margin_bottom", value="50")
-
-summer_add_node(parent="./MainMenu/Margin", type="VBoxContainer", name="VBox")
-summer_add_node(parent="./MainMenu/Margin/VBox", type="Label", name="Title")
-summer_set_prop(path="./MainMenu/Margin/VBox/Title", key="text", value="My Game")
-summer_add_node(parent="./MainMenu/Margin/VBox", type="Button", name="StartButton")
-summer_set_prop(path="./MainMenu/Margin/VBox/StartButton", key="text", value="Start Game")
-summer_add_node(parent="./MainMenu/Margin/VBox", type="Button", name="QuitButton")
-summer_set_prop(path="./MainMenu/Margin/VBox/QuitButton", key="text", value="Quit")
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var menu = ctx.add_node("Control", "MainMenu")
+    menu.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+    var margin = ctx.add_node("MarginContainer", "Margin", menu)
+    margin.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+    for side in ["margin_left", "margin_right", "margin_top", "margin_bottom"]:
+        margin.add_theme_constant_override(side, 50)
+    var column = ctx.add_node("VBoxContainer", "VBox", margin)
+    ctx.add_node("Label", "Title", column, {"text": "My Game"})
+    ctx.add_node("Button", "StartButton", column, {"text": "Start Game"})
+    ctx.add_node("Button", "QuitButton", column, {"text": "Quit"})
+    ctx.save_scene()
+""")
 ```
 
-For nested theme overrides, use `summer_set_resource_property` if the property
-is on a resource. For `theme_override_constants/margin_left`, inspect the live
-node or the upstream API reference matching the current Summer technical base.
-Some constants use `add_theme_constant_override`.
+Container margins are theme constants, not plain properties: set them with
+`add_theme_constant_override` as above. `set_anchors_and_offsets_preset` pins
+a Control the way the editor's layout menu does.
 
 ## HUD (Health Bar)
 
 ```
-summer_add_node(parent="./", type="CanvasLayer", name="HUD")
-summer_add_node(parent="./HUD", type="MarginContainer", name="TopLeft")
-summer_set_prop(path="./HUD/TopLeft", key="anchors_preset", value="0")  # Top-left is 0; 1 is Top-right
-summer_add_node(parent="./HUD/TopLeft", type="HBoxContainer", name="HealthContainer")
-summer_add_node(parent="./HUD/TopLeft/HealthContainer", type="Label", name="HealthLabel")
-summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthLabel", key="text", value="Health:")
-summer_add_node(parent="./HUD/TopLeft/HealthContainer", type="ProgressBar", name="HealthBar")
-summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthBar", key="max_value", value="100")
-summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthBar", key="value", value="100")
-summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthBar", key="size", value="Vector2(200, 20)")
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var hud = ctx.add_node("CanvasLayer", "HUD")
+    var top_left = ctx.add_node("MarginContainer", "TopLeft", hud)
+    top_left.set_anchors_and_offsets_preset(Control.PRESET_TOP_LEFT)
+    var row = ctx.add_node("HBoxContainer", "HealthContainer", top_left)
+    ctx.add_node("Label", "HealthLabel", row, {"text": "Health:"})
+    ctx.add_node("ProgressBar", "HealthBar", row, {
+        "max_value": 100.0,
+        "value": 100.0,
+        "custom_minimum_size": Vector2(200, 20),   # a container sets size; ask for a minimum
+    })
+    ctx.save_scene()
+""")
 ```
 
 ProgressBar uses `value` and `max_value` for the fill. Update `value` from a script when health changes.
@@ -92,7 +97,7 @@ Common preset values in the current Summer Engine UI API:
 | Bottom Right | 3 | Anchor to bottom-right |
 | Full Rect | 15 | Stretch to fill parent |
 
-Set via `summer_set_prop(path, key="anchors_preset", value="15")`.
+Set via `summer_set_prop(scenePath, path, key="anchors_preset", value="15")`.
 
 ## Connecting Buttons
 
@@ -102,10 +107,10 @@ Wire the `pressed` signal to a handler:
 summer_connect_signal(scenePath="res://main.tscn", emitter="./MainMenu/Margin/VBox/StartButton", signal="pressed", receiver="./MainMenu", method="_on_start_pressed")
 ```
 
-`scenePath` is required on every scene-mutating tool in this skill
-(`summer_add_node`, `summer_set_prop`, `summer_connect_signal`,
-`summer_save_scene`). The examples above omit it only for readability — a real
-call without it is rejected before it reaches the engine.
+`scenePath` is required on every scene tool in this skill
+(`summer_run_script`, `summer_set_prop`, `summer_connect_signal`,
+`summer_save_scene`); the examples use `res://main.tscn`. A call without it is
+rejected before it reaches the engine.
 
 The receiver node must have a script with `func _on_start_pressed() -> void:`.
 

package/library/skills/ui-basics/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/ui-basics
 kind: skill
 version: 1.0.3
-summary: Build Summer Engine UI — HUDs, menus, health bars, dialogue boxes, Control trees — anchors, containers, responsive layout, theme vs inline styling.
+summary: "Build UI: HUDs, menus, health bars, dialogue boxes, Control trees, anchors, containers and themes."
 use_when:
   - "building Summer Engine UI: HUDs, main menus, pause menus, health bars, progress bars, dialogue boxes, or any Control-node tree"
   - laying out a pause menu, settings screen, or inventory panel with anchors and containers so it stays responsive

package/library/skills/ui-graphics/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ui-graphics
-description: "Generate game-UI elements — icons, buttons, panels, frames, HUD widgets, badges — flat design, transparent background, wired via TextureRect/NinePatchRect."
+description: "Generate game UI art (icons, buttons, panels, frames, HUD widgets) flat, on a transparent background."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_search_assets summer_import_from_url summer_set_resource_property summer_add_node summer_set_prop
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_search summer_import_from_url summer_set_resource_property summer_add_node summer_set_prop summer_call
 paths: ["assets/**", "ui/**", "art/ui/**"]
 ---
 
@@ -54,19 +54,19 @@ Every icon / button / panel re-uses this anchor verbatim. Skipping this step pro
 ### 2. Search before generating
 
 ```
-summer_search_assets(query="<subject> icon", assetType="2d_image", source="all")
+assets.search({ query: "<subject> icon", assetType: "2d_image", scope: "all" })
 ```
 
 ### 3. Pick the right pattern (icon vs button vs panel)
 
-`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.
+`assets.generate_image` takes `aspectRatio` (`1:1` default, `16:9`, `21:9`, `3:2`, `4:3`, ...) and, for a minimum size, `width` and `height`. Square suits icons, panels, and badges; wide assets (buttons, HUD bar frames) get a wide `aspectRatio`.
 
 | Asset class | Framing | Wiring node | Notes |
 |---|---|---|---|
 | 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 |
+| Button (idle / hover / pressed) | wide — `aspectRatio: "3:2"` or `"21:9"` | `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 |
+| HUD bar frame | wide — `aspectRatio: "21:9"` | `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
@@ -83,29 +83,29 @@ Pattern:
 
 **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, 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",
-  removeBackground=true
-)
+assets.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, 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",
+  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.
+There is no `negative_prompt`: the negations have to live in the prompt text.
 
 **Button (3 states in 3 calls):**
 ```
-summer_generate_image(prompt="<subject>, idle state, ...")
-summer_generate_image(prompt="<subject>, hover state, slightly brighter glow, ...")
-summer_generate_image(prompt="<subject>, pressed state, darker, slight inset shadow, ...")
+assets.generate_image({ prompt: "<subject>, idle state, ...", aspectRatio: "3:2" })
+assets.generate_image({ prompt: "<subject>, hover state, slightly brighter glow, ...", aspectRatio: "3:2" })
+assets.generate_image({ prompt: "<subject>, pressed state, darker, slight inset shadow, ...", aspectRatio: "3:2" })
 ```
 
 **Panel for NinePatch:**
 ```
-summer_generate_image(
-  prompt="parchment scroll panel frame, ornate gold border, weathered tan center, clear distinction between border and center area, game UI, fantasy, transparent background, square format, centered",
+assets.generate_image({
+  prompt: "parchment scroll panel frame, ornate gold border, weathered tan center, clear distinction between border and center area, game UI, fantasy, transparent background, square format, centered",
   ...
-)
+})
 ```
 
 The "clear distinction between border and center" is the NinePatch hint — without it, the border bleeds into the center and 9-slicing produces artifacts.
@@ -120,25 +120,30 @@ 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`.
+One `summer_run_script` call wires each graphic with its settings; `scenePath` is the exact scene to change.
 
 **Icon as TextureRect:**
 ```
-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
+summer_run_script(scenePath="res://ui/hud.tscn", source="""
+func run(ctx):
+    ctx.add_node("TextureRect", "FireSpellIcon", ctx.find("AbilityBar"), {
+        "texture": load("res://ui/icons/fire_spell.png"),
+        "expand_mode": TextureRect.EXPAND_IGNORE_SIZE,
+        "stretch_mode": TextureRect.STRETCH_KEEP_ASPECT_CENTERED,
+    })
+    ctx.save_scene()
+""")
 ```
 
 **Panel as NinePatchRect:**
 ```
-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")
+summer_run_script(scenePath="res://ui/hud.tscn", source="""
+func run(ctx):
+    var panel = ctx.add_node("NinePatchRect", "InventoryPanel", null, {"texture": load("res://ui/panels/parchment.png")})
+    for side in ["patch_margin_left", "patch_margin_right", "patch_margin_top", "patch_margin_bottom"]:
+        panel.set(side, 24)
+    ctx.save_scene()
+""")
 ```
 
 Tune patch margins to match the actual border width in the generated texture. Open the texture in the editor's NinePatch preview to verify.
@@ -190,17 +195,21 @@ If you generate a 4×4 grid of icons in one image, each icon becomes an `AtlasTe
 - **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 `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.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-5 and skip steps 6-7 (import, scene wiring). Pass `out` with the person's folder so each PNG lands there (the `summer-assets` skill says how); keep `removeBackground: true` for icons and buttons that need transparency.
+
 ## Fallback (no MCP)
 
 Print the call:
 
 ```
-summer_generate_image(
-  prompt="<asset + anchor>, isolated on a plain background. No scene background, not photorealistic, no 3D, not busy.",
-  model="nano-banana-2",
-  style="none",
-  removeBackground=true
-)
+assets.generate_image({
+  prompt: "<asset + anchor>, isolated on a plain background. No scene background, not photorealistic, no 3D, not busy.",
+  model: "nano-banana-2",
+  style: "none",
+  removeBackground: true
+})
 ```
 
 User runs via the Summer dashboard, then `summer_import_from_url` to `res://ui/icons/<name>.png` and wires manually.
@@ -221,4 +230,4 @@ After the UI graphic is wired:
 - `character-portrait` — for in-UI character images.
 - `pixel-art` — pixel-style UI.
 - `scene-composition` — Theme and Control hierarchy.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_image`.

package/library/skills/ui-graphics/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/ui-graphics
 kind: skill
 version: 1.0.3
-summary: Generate game-UI elements — icons, buttons, panels, frames, HUD widgets, badges — flat design, transparent background, wired via TextureRect/NinePatchRect.
+summary: "Generate game UI art (icons, buttons, panels, frames, HUD widgets) flat, on a transparent background."
 use_when:
   - generating UI elements — icons, buttons, panels, frames, HUD widgets, badges — in flat-design, transparent-background game-UI style
   - a HUD still uses placeholder icons, buttons, or panels and needs consistent flat-design art

package/library/skills/use-widget-asset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: use-widget-asset
-description: "Wire a widget slice from a create-asset-sheet pack (panel, button, slider, bar, toggle) into NinePatchRect, TextureProgressBar, or TextureRect via sliceMeta."
+description: "Wire a widget slice from an asset pack (panel, button, bar, toggle) into NinePatchRect or TextureRect."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/use-widget-asset/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/use-widget-asset
 kind: skill
 version: 1.0.3
-summary: Wire a widget slice from a create-asset-sheet pack (panel, button, slider, bar, toggle) into NinePatchRect, TextureProgressBar, or TextureRect via sliceMeta.
+summary: "Wire a widget slice from an asset pack (panel, button, bar, toggle) into NinePatchRect or TextureRect."
 use_when:
   - consuming a widget slice (panel, button, slider, progress bar, toggle pair) from a create-asset-sheet pack so it behaves like a real UI control
   - turning a panel, button, slider, or bar slice from a generated UI kit into a working NinePatchRect or TextureProgressBar

package/library/skills/using-summer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-summer
-description: "Session bootstrap for Summer projects — establishes how to find and use Summer skills and the summer-engine MCP before any response."
+description: "Session bootstrap: how to find and use Summer skills and the summer-engine MCP before any response."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
 category: _meta
@@ -33,10 +33,11 @@ If `CLAUDE.md` says "skip the brainstorm, just build it" and a skill says "alway
 
 **Summer Engine** is an AI-native game engine — editor, scene graph, asset pipeline, and runtime are all instrumented for programmatic control by AI agents. **Summer** (this skill set + MCP server) is how your coding agent talks to it.
 
-Two layers:
+Three layers:
 
 - **Skills** — discipline guides that fire on specific situations: brainstorming a game, designing a mechanic, building an FPS controller, debugging a crash, shipping a build. Each one is a SKILL.md you load via the Skill tool.
-- **MCP tools** — `summer_*` tools that talk to the running Summer Engine on `localhost:6550`. Scene mutation (`summer_add_node`, `summer_set_prop`), inspection (`summer_get_scene_tree`, `summer_inspect_node`), play/diagnostics (`summer_play`, `summer_get_diagnostics`), asset import/generation (`summer_import_from_url`, `summer_generate_3d`), and the rest of the `summer_*` set.
+- **MCP tools** — `summer_*` tools that talk to the running Summer Engine on `localhost:6550`. Scene mutation (`summer_add_node`, `summer_set_prop`), inspection (`summer_get_scene_tree`, `summer_inspect_node`), play/diagnostics (`summer_play`, `summer_get_diagnostics`), asset import (`summer_import_from_url`), and the rest of the `summer_*` set.
+- **Operations** — Summer's cloud work (generating images, 3D, audio, video and animation, editing assets, store pages, jobs) is named by operation: `assets.generate_3d`, `jobs.wait`. A call written `area.action({...})` is one operation: use the tool `summer_area_action` when your client lists it, else `summer_call({ op: "area.action", input: {...} })`. `summer_search` finds any operation and its exact input. Long work (3D, video, animation) answers with a job: `jobs.wait({ jobId })` until it finishes. Spending operations accept `dryRun: true`, which returns the person's estimated credits and changes nothing.
 
 **Scripting language:** The user is making a Summer game with the Summer SDK.
 GDScript is the default creator language. Summer Engine follows its upstream
@@ -51,7 +52,7 @@ engine's own version string. You can write game code in either:
   idioms. Confirm that the user wants C# before producing it; switching
   languages mid-project is painful.
 
-Scenes are always `.tscn`/`.scn`. Resources are always `.tres`/`.res`. Drive the engine through `summer_*` tools — do not hand-edit `.tscn` files; the editor holds in-memory state that diverges from disk.
+Scenes are always `.tscn`/`.scn`. Resources are always `.tres`/`.res`. Drive the engine through `summer_*` tools — do not hand-edit `.tscn` files; the editor holds in-memory state that diverges from disk. 3 or more scene edits are one `summer_run_script` with `scenePath` (snapshot, script, diff, screenshot; see `scene-scripting`), not a chain of single calls.
 
 The engine must be running for MCP tools that touch scenes or diagnostics. If it isn't, the tool returns an error pointing the user at `summer run`.
 
@@ -67,7 +68,7 @@ The engine must be running for MCP tools that touch scenes or diagnostics. If it
 
 ## Finding the Right Entry
 
-Not sure which skill, tool, template, or reference covers the task? Ask the library before guessing: call `summer_search_library` with the task in plain words ("make stylized water", "the player falls through the floor"), then `summer_read_library` with the id you pick — it returns the entry itself (a skill's body and metadata, a tool's call recipe, a template's pin) and ends with the `entry_id` line to report through `summer_library_feedback` once the outcome is verified. From a shell the same two are `summer tool search-library --args '{"query":"…"}'` and `summer tool read-library --args '{"id":"…"}'`; neither needs the engine. When search names a skill, invoke it by its bare slug through your host's skill mechanism (`vfx-water-ripple`, `fps-controller`, `design-mechanic`) rather than paraphrasing the body from the read.
+Not sure which skill, tool, template, or reference covers the task? Ask the library before guessing: call `summer_docs_search` with the task in plain words ("make stylized water", "the player falls through the floor"), then `summer_docs_read` with the id you pick — it returns the entry itself (a skill's body and metadata, a tool's call recipe, a template's pin) and ends with the `entry_id` line to report through `summer_call` `{"op":"docs.feedback"}` once the outcome is verified. From a shell the same two are `summer tool search-library --args '{"query":"…"}'` and `summer tool read-library --args '{"id":"…"}'`; neither needs the engine. When search names a skill, invoke it by its bare slug through your host's skill mechanism (`vfx-water-ripple`, `fps-controller`, `design-mechanic`) rather than paraphrasing the body from the read.
 
 ## The Rule
 

package/library/skills/using-summer/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/using-summer
 kind: skill
 version: 1.0.5
-summary: Session bootstrap for Summer projects — establishes how to find and use Summer skills and the summer-engine MCP before any response.
+summary: "Session bootstrap: how to find and use Summer skills and the summer-engine MCP before any response."
 use_when:
   - starting any conversation in a Summer Engine project
   - deciding which Summer skill or summer_* tool applies before answering a game-development request

package/library/skills/vehicle-model/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: vehicle-model
-description: "Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as VehicleBody3D or MeshInstance3D."
+description: "Generate a hard-surface vehicle (car, spaceship, mech, boat, tank) as a static or VehicleBody3D mesh."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene
+allowed-tools: Read Grep summer_assets_search summer_assets_get summer_import_asset_by_id summer_assets_generate_3d summer_assets_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene summer_jobs_wait summer_call
 paths: ["assets/vehicles/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
 # Vehicle Model — Hard-Surface 3D Generation
 
-Vehicles are the hardest 3D-gen category. Hard surfaces (flat panels, sharp edges, symmetrical bodies) expose every flaw the AI mesher has — smoothing-group artifacts on flat panels, asymmetric headlights, melted door seams. This skill exists to push the success rate up by giving the model **multi-angle reference**, picking the right backend, and using a **secondary detail-texture pass** to recover crispness on the body panels.
+Vehicles are the hardest 3D-gen category. Hard surfaces (flat panels, sharp edges, symmetrical bodies) expose every flaw the AI mesher has — smoothing-group artifacts on flat panels, asymmetric headlights, melted door seams. This skill exists to push the success rate up by giving the model **multi-angle reference**, picking the right backend, and using a **secondary detail pass** (decals) to recover crispness on the body panels.
 
-Backing tool: `summer_generate_3d`. Default model is `hunyuan` (best general quality). For pure hard-surface (clean spaceship, F1 car), try `trellis` first — it tends to preserve panel edges better.
+Backing operation: `assets.generate_3d` (it answers with a job: `jobs.wait` until it finishes). Default model is `hunyuan` (best general quality). For pure hard-surface (clean spaceship, F1 car), try `trellis` first — it tends to preserve panel edges better.
 
 ## When to use
 
@@ -34,10 +34,10 @@ Backing tool: `summer_generate_3d`. Default model is `hunyuan` (best general qua
 
 | Use case | Tris | Pass via |
 |---|---|---|
-| Player vehicle (close camera, lots of screen time) | 15k–30k | `target_polycount: 25000` |
-| Hero showpiece (cinematic, garage view) | 30k–60k | `target_polycount: 50000` |
-| Background traffic (mid-range, multiple onscreen) | 2k–5k | `target_polycount: 4000` |
-| Distant flyby / parked scenery | 1k–2k | `target_polycount: 1500` |
+| Player vehicle (close camera, lots of screen time) | 15k–30k | `targetPolycount: 25000` |
+| Hero showpiece (cinematic, garage view) | 30k–60k | `targetPolycount: 50000` |
+| Background traffic (mid-range, multiple onscreen) | 2k–5k | `targetPolycount: 4000` |
+| Distant flyby / parked scenery | 1k–2k | `targetPolycount: 1500` |
 
 Vehicles benefit more from polycount than props — flat panels need edge density to look right. Don't go below 2k for anything the camera will get close to.
 
@@ -45,30 +45,31 @@ Vehicles benefit more from polycount than props — flat panels need edge densit
 
 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.
+**(a) A real multi-image request — prefer this.** `assets.generate_3d` takes an `imageUrls` array of two to four views. These are passed through as separate views, not fused into one picture. Several views run on Meshy (`meshy` or `meshy-7.1`; any other model is switched to Meshy).
 
 ```
-summer_generate_3d(
-  kind="image-to-3d",
-  imageUrls=["<front url>", "<3/4 rear-side url>", "<profile url>"],
-  model="hunyuan",
-  options={ target_polycount: 25000 }
-)
+assets.generate_3d({
+  kind: "image-to-3d",
+  imageUrls: ["<front url>", "<3/4 rear-side url>", "<profile url>"],
+  model: "meshy",
+  targetPolycount: 25000
+})
 ```
 
 **(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."
-)
+assets.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.",
+  aspectRatio: "16:9"
+})
 
-summer_generate_3d(
-  kind="image-to-3d",
-  imageUrl="<composite reference url>",
-  model="hunyuan",
-  options={ target_polycount: 25000 }
-)
+assets.generate_3d({
+  kind: "image-to-3d",
+  imageUrl: "<composite reference url>",
+  model: "hunyuan",
+  targetPolycount: 25000
+})
 ```
 
 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.
@@ -78,7 +79,7 @@ If the user has reference images already (concept art, photos), pass them straig
 ### 1. Search before generating
 
 ```
-summer_search_assets(query="<vehicle type>", assetType="3d_model", source="all")
+assets.search({ query: "<vehicle type>", assetType: "3d_model", scope: "all" })
 ```
 
 ### 2. Pick model and polycount
@@ -97,20 +98,22 @@ 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.` |
 
-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.
+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 operation has no prompt-sniffing and sees whatever pixels you hand it. Multi-view comes from the `imageUrls` array, nothing else.
 
 ### 4. Confirm and call
 
 > About to generate `red_race_car` via `hunyuan`, target ~25k tris, multi-angle ref. Uses credits, ~90s. OK?
 
+The same call with `dryRun: true` first gives the credits for the confirmation (`estimate.credits`, and `enough` against their balance).
+
 ```
-summer_generate_3d(
-  prompt="A sleek modern Formula 1 race car, ...",
-  model="hunyuan",
-  options={ target_polycount: 25000 },
-  wait=true
-)
-summer_get_asset(assetId="<assetId>")
+assets.generate_3d({
+  prompt: "A sleek modern Formula 1 race car, ...",
+  model: "hunyuan",
+  targetPolycount: 25000
+})
+jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 })   // again until finished; result.assetId
+assets.get({ assetId: "<assetId>" })
 summer_import_asset_by_id(assetId="<assetId>", path="res://assets/vehicles/race_car.glb")
 ```
 
@@ -121,24 +124,24 @@ summer_inspect_resource(path="res://assets/vehicles/race_car.glb")
 ```
 
 Open the import preview. Look for:
-- **Smoothing-group artifacts on flat panels** (visible as banding under light) → fix in step 6 with a detail texture, or re-import with `Generate Tangents = on` and a custom shader.
+- **Smoothing-group artifacts on flat panels** (visible as banding under light) → cover with step 6's detail decals, or re-import with `Generate Tangents = on` and a custom shader.
 - **Asymmetric headlights / wheels** → regenerate with `symmetric, mirrored bilateral` added to the prompt.
-- **Melted door seams / panel gaps** → run the detail-texture pass (step 6).
+- **Melted door seams / panel gaps** → regenerate from a cleaner multi-view reference, or paint the seams back with step 6's decals.
 
-### 6. Optional: secondary detail-texture pass
+### 6. Optional: secondary detail pass
 
-For hero vehicles, run a texture-only pass to recover panel-line crispness without re-meshing:
+There is no texture-only 3D pass among the asset operations (`assets.generate_3d` takes `text-to-3d` or `image-to-3d`). For hero vehicles, recover panel-line crispness without re-meshing by drawing the detail as images and laying it on the mesh:
 
 ```
-summer_generate_3d(
-  kind="texture",
-  imageUrl="<original front-view reference>",
-  model="hunyuan",
-  options={ target_polycount: 25000 }  // matched to existing mesh
-)
+assets.generate_image({
+  prompt: "Flat orthographic livery and panel-line decal for a red Formula 1 car side, crisp seams, sponsor stripes, transparent background",
+  referenceImageUrl: "<original front-view reference>",
+  aspectRatio: "16:9",
+  removeBackground: true
+})
 ```
 
-This re-textures the existing mesh with sharper detail — panel lines, decals, weathering. Cheaper than re-meshing. Apply via material override in the editor.
+Import it and apply it with `Decal` nodes or as a detail texture in a material override in the editor. Cheaper than re-meshing.
 
 ### 7. Wire into the scene
 
@@ -149,21 +152,22 @@ This re-textures the existing mesh with sharper detail — panel lines, decals,
 | 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 |
 
-**Player car wiring:**
+**Player car wiring** (one `summer_run_script`; `scenePath` is the exact scene to change):
 
 ```
-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(scenePath="res://main.tscn")
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var car = ctx.add_node("VehicleBody3D", "RaceCar", ctx.find("World"))
+    ctx.instance_scene("res://assets/vehicles/race_car.glb", car, "Body")
+    var box = BoxShape3D.new()
+    box.size = Vector3(4.5, 1.1, 1.9)
+    ctx.add_node("CollisionShape3D", "Collider", car, {"shape": box})
+    # Add one VehicleWheel3D per wheel here, at the hub positions summer_inspect_asset measured on the model.
+    ctx.save_scene()
+""")
 ```
 
-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 engine 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`.
+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 engine returns `["tres", "mesh", "res"]`, no `glb`). Instantiate it (`ctx.instance_scene` in a script, `summer_instantiate_scene` for one model). Build and size the collision shape before you assign it.
 
 **Background scenery wiring:**
 
@@ -178,7 +182,7 @@ summer_save_scene(scenePath="res://main.tscn")
 - **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.
+- **Asking the mesh pass to invent decals / liveries.** It can't — the mesh has the silhouette but the decals get geometry-baked weirdly. Use step 6's decals for liveries.
 - **Wrapping a background sedan in VehicleBody3D.** Wastes physics for a parked car. Use MeshInstance3D under Node3D.
 - **Picking `meshy` (legacy).** Worse hard-surface fidelity than hunyuan or trellis.
 
@@ -190,6 +194,10 @@ summer_save_scene(scenePath="res://main.tscn")
 - **Open-top vehicle (convertible, jeep).** Specify "open top, no roof" — defaults often add a roof.
 - **The user wants the cockpit interior visible.** Generate exterior here, then a separate `prop-model` for the interior, and switch meshes when the camera enters first-person view.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-6 and skip step 7 (scene wiring, `VehicleWheel3D`). Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format. The file is GLB and not at real-world size: give the person the target length (a car about 4.5 m) and tell them where the wheels are, so they can set up their engine's vehicle physics.
+
 ## Fallback (no MCP)
 
 1. Generate the multi-angle reference at the Summer dashboard (or Midjourney / nano-banana web).
@@ -212,4 +220,4 @@ After the vehicle is wired:
 - `character-model` — for the driver/pilot.
 - `prop-model` — for separable parts (rotors, decals as decals, modular kit pieces).
 - `asset-strategy` — meta-router.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_3d`; `summer_search` returns its exact input.

package/library/skills/vehicle-model/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vehicle-model
 kind: skill
 version: 1.0.3
-summary: Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as VehicleBody3D or MeshInstance3D.
+summary: "Generate a hard-surface vehicle (car, spaceship, mech, boat, tank) as a static or VehicleBody3D mesh."
 use_when:
   - generating a hard-surface vehicle — car, motorcycle, spaceship, hover bike, boat, mech, tank, helicopter
   - a racing, flying, or combat game needs a hard-surface vehicle mesh as a VehicleBody3D or MeshInstance3D