summer-engine 3.8.0 → 4.2.0

package/library/skills/tune-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tune-performance
-description: "Profile a slow game with a measurement probe, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations."
+description: "Profile a slow game, find rendering, physics or script hotspots, and propose fixes with expected gains."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: performance
@@ -221,7 +221,7 @@ Compare: was the metric movement at least 50% of what was promised? If yes, ship
 
 ## Collaborative protocol
 
-This skill makes scene/resource/code changes. Always ask before each fix is applied. See `../../references/collaborative-protocol/collaborative-protocol.md`.
+This skill makes scene/resource/code changes. Always ask before each fix is applied. See `summer_docs_read` id `reference/collaborative-protocol`.
 
 ## Want a working starter?
 
@@ -229,10 +229,36 @@ No template — this is a workflow. Performance tuning is project-specific by de
 
 ## See also
 
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full MCP tool list
-- `../../references/godot-version/godot-version.md` — renderer API churn notes (Compositor, RenderSceneBuffers)
-- `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
-- `../../references/gd-style/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
+- `summer_docs_read` id `reference/mcp-tools-reference` — full MCP tool list
+- `summer_docs_read` id `reference/godot-version` — renderer API churn notes (Compositor, RenderSceneBuffers)
+- `summer_docs_read` id `reference/collaborative-protocol` — "May I write" pattern
+- `summer_docs_read` id `reference/gd-style` — GDScript conventions (avoid bare types, use `:=`)
 - `debug` — bug triage (related but different)
 - `diagnosing-perf-regressions` — when it *got* slow rather than always was
 - `3d-lighting` — light setup and bake decisions
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_batch` | `summer engine batch` |
+| `summer_clear_console` | `summer engine clear-console` |
+| `summer_get_console` | `summer engine get-console` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_resource` | `summer engine inspect-resource` |
+| `summer_is_running` | `summer engine is-running` |
+| `summer_play` | `summer engine play` |
+| `summer_project_setting` | `summer engine project-setting` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_stop` | `summer engine stop` |
+<!-- /shell-commands -->

package/library/skills/tune-performance/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/tune-performance
 kind: skill
 version: 1.0.3
-summary: Profile a slow game with a measurement probe, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations.
+summary: "Profile a slow game, find rendering, physics or script hotspots, and propose fixes with expected gains."
 use_when:
   - the game is slow, drops framerate, stutters, takes forever to start, or runs poorly on specific hardware
   - fps drops or stutter when many units, projectiles, or particles spawn at once and the hotspot is unknown

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:`.
 
@@ -167,3 +172,17 @@ text = "Start Game"
 ## Collaborative protocol
 
 This skill writes UI scene nodes and wires button signals. Always ask before applying: "May I add the MainMenu (Control + Margin + VBox + Title + Start/Quit buttons) and connect Start.pressed to `_on_start_pressed`?".
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_add_node` | `summer engine add-node` |
+| `summer_connect_signal` | `summer engine connect-signal` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+<!-- /shell-commands -->

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,21 @@ 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`.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_image`, `summer_assets_generate_image` | `summer assets generate-image` |
+| `summer_assets_search` | `summer assets search` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+<!-- /shell-commands -->

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
@@ -217,3 +217,17 @@ Check `metadata.schemaVersion` on the pack: `null` (or absent) = legacy, `1` = c
 - Auto-tiling terrain (Wang / 47-tile). Different format entirely — see `tileable-texture`.
 - Animated UI (button press-down sprites, hover glow). The wizard captures static frames; for animation see `sprite-sheet`.
 - Non-AABB widgets in the 9-slice path. See the **Shape support** table at the top — for circles, hexagons, organic shapes, fall through to `TextureRect` and skip 9-slice entirely.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+<!-- /shell-commands -->

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,13 @@ 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.
+
+**No `summer_*` tools in this session?** Summer was set up without MCP (`summer setup <agent> --cli`). Every tool and operation is also a `summer` command in the shell: use the `summer-cli` skill. Each skill's **From a shell** table gives the command for each tool it names.
 
 **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 +54,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 +70,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
 
@@ -162,3 +165,27 @@ After the refresh, restart or reload the agent/MCP session if tools were missing
 ## User Instructions Trump Everything
 
 A direct user instruction ("skip the brainstorm", "just write the code", "don't use the MCP, edit files") overrides this skill. Surface the trade-off in one sentence ("Skipping brainstorm — heads up, scope creep is the most common reason game projects die.") and proceed as instructed.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_3d` | `summer assets generate-3d` |
+| `docs.feedback` | `summer docs feedback` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_docs_search` | `summer docs search` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_project_context` | `summer engine get-project-context` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_play` | `summer engine play` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `jobs.wait` | `summer jobs wait` |
+| `summer_search` | `summer ops search "<what you want>"` |
+<!-- /shell-commands -->

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.
+version: 1.0.6
+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
@@ -31,6 +31,7 @@ related:
     - skill/play
     - skill/scene-composition
     - skill/gdscript-patterns
+    - skill/summer-cli
 source: official
 license: MIT
 status: stable