summer-engine 3.8.0 → 4.2.0

package/library/skills/vfx-lightning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-lightning
-description: "Lightning bolt effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake."
+description: "Lightning bolt effect: a jagged procedural path with a glow shader, end sparks and screen shake."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -222,31 +222,22 @@ Recommended: register one `LightningCaster` as an autoload (`/root/Lightning`) s
 
 Place one `LightningCaster` per "world" (or autoload it), then call from gameplay code.
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
+Write the two files, then place the caster with ONE `summer_run_script` call
+with an explicit `scenePath` — one transactional run, and several casters or
+anything computed is a loop in the same script:
 
 ```
 summer_write_file(path="res://addons/vfx/lightning/lightning.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/lightning/lightning_caster.gd", content="<section 3>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./World", type="Node3D", name="LightningCaster")
-summer_set_prop(scenePath="res://main.tscn", path="./World/LightningCaster", key="script", value="res://addons/vfx/lightning/lightning_caster.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./World/LightningCaster", key="bolt_color", value="Color(0.55, 0.75, 1.0)")
-summer_set_prop(scenePath="res://main.tscn", path="./World/LightningCaster", key="trauma_amount", value=0.6)
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-Or, on engines with `summer_run_script` (see `scene-scripting`), the two node
-calls collapse into one transactional ctx script — worth it when placing several
-casters or anything computed:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var caster := ctx.add_node("Node3D", "LightningCaster", null)
+    var caster = ctx.add_node("Node3D", "LightningCaster", ctx.find("World"))
     caster.set_script(load("res://addons/vfx/lightning/lightning_caster.gd"))
     caster.set("bolt_color", Color(0.55, 0.75, 1.0))
     caster.set("trauma_amount", 0.6)
     ctx.save_scene()
+""")
 ```
 
 Then verify — the caster `preload`s its own shader, so a shader that failed to write
@@ -415,3 +406,26 @@ After firing this recipe, suggest:
 - `vfx-magic-glow` — pre-cast charge-up
 - `vfx-muzzle-flash` — for the cast-release flash
 - `game-feel` — full game-feel pairing
+
+<!-- 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_create_scene` | `summer engine create-scene` |
+| `summer_get_debugger_errors` | `summer engine get-debugger-errors` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_play` | `summer engine play` |
+| `summer_project_setting` | `summer engine project-setting` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/vfx-lightning/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-lightning
 kind: skill
 version: 1.0.3
-summary: Lightning bolt effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake.
+summary: "Lightning bolt effect: a jagged procedural path with a glow shader, end sparks and screen shake."
 use_when:
   - authoring a lightning bolt effect — chain lightning, electric attack, tesla coil, shock spell, energy beam
   - a spell, weapon, or hazard needs a jagged electric arc with glow, endpoint sparks, and camera shake

package/library/skills/vfx-magic-glow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-magic-glow
-description: "Magic-glow effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh."
+description: "Magic-glow effect: a pulsing OmniLight3D, drifting additive motes and an optional emission shader."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -195,42 +195,16 @@ Node3D ("MagicGlow") [script: magic_glow.gd]
 
 ### 4. Wire it in (MCP calls)
 
-For an enchanted sword:
-
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
+Write the script once, then wire each glow with ONE `summer_run_script` call
+with an explicit `scenePath` — one transactional run instead of a chain of
+`summer_set_prop` calls. For an enchanted sword:
 
 ```
 summer_write_file(path="res://addons/vfx/magic-glow/magic_glow.gd", content="<section 2>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./Player/Hand/Sword", type="Node3D", name="Glow")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="script", value="res://addons/vfx/magic-glow/magic_glow.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="glow_color", value="Color(0.55, 0.85, 1.0)")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="light_energy_base", value=1.2)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="light_energy_amplitude", value=0.6)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="mote_count", value=16)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="mote_radius", value=0.20)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="pulse_source_mesh", value="../Blade")
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-For a soul gem on a pedestal:
-
-```
-summer_add_node(scenePath="res://main.tscn", parent="./World/Pedestal/SoulGem", type="Node3D", name="Glow")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow", key="glow_color", value="Color(0.85, 0.45, 1.0)")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow", key="pulse_hz", value=0.4)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow", key="mote_count", value=32)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow", key="mote_radius", value=0.30)
-```
-
-Either wiring block is also ONE ctx script on engines with `summer_run_script`
-(see `scene-scripting`) — the eight `summer_set_prop` calls become one
-transactional run, and computed placement (a glow per gem in a ring) becomes a loop:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var glow := ctx.add_node("Node3D", "Glow", ctx.find("Sword"))
+    var glow = ctx.add_node("Node3D", "Glow", ctx.find("Sword"))
     glow.set_script(load("res://addons/vfx/magic-glow/magic_glow.gd"))
     glow.set("glow_color", Color(0.55, 0.85, 1.0))
     glow.set("light_energy_base", 1.2)
@@ -239,6 +213,23 @@ func run(ctx):
     glow.set("mote_radius", 0.20)
     glow.set("pulse_source_mesh", NodePath("../Blade"))
     ctx.save_scene()
+""")
+```
+
+For a soul gem on a pedestal (computed placement, such as a glow per gem in a
+ring, is a loop in the same script):
+
+```
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var glow = ctx.add_node("Node3D", "Glow", ctx.find("SoulGem"))
+    glow.set_script(load("res://addons/vfx/magic-glow/magic_glow.gd"))
+    glow.set("glow_color", Color(0.85, 0.45, 1.0))
+    glow.set("pulse_hz", 0.4)
+    glow.set("mote_count", 32)
+    glow.set("mote_radius", 0.30)
+    ctx.save_scene()
+""")
 ```
 
 Judge the pulse with `summer_screenshot framing:"camera"` — emissive glow does not
@@ -428,3 +419,26 @@ After firing this recipe, suggest:
 - `vfx-dissolve` — for summon arrival pairing
 - `vfx-fire` — for the `magic-fire` variant
 - `gdscript-patterns` — for the controller idioms (signals, exports, `@tool`)
+
+<!-- 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_create_scene` | `summer engine create-scene` |
+| `summer_get_debugger_errors` | `summer engine get-debugger-errors` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_play` | `summer engine play` |
+| `summer_read_file` | `summer engine read-file` |
+| `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_set_resource_property` | `summer engine set-resource-property` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/vfx-magic-glow/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-magic-glow
 kind: skill
 version: 1.0.2
-summary: Magic-glow effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh.
+summary: "Magic-glow effect: a pulsing OmniLight3D, drifting additive motes and an optional emission shader."
 use_when:
   - authoring a magic-glow effect — enchanted item, soul gem, pulsing aura, rune glow, magical orb, wisp
   - an item, altar, or portal should read as magical or important with a pulsing light and drifting motes

package/library/skills/vfx-muzzle-flash/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-muzzle-flash
-description: "Muzzle-flash effect — a one-shot ~80 ms burst at a gun barrel built with a particle one-shot or a flashing quad with a star-burst shader."
+description: "Muzzle-flash effect: a one-shot ~80 ms burst at a gun barrel, from particles or a star-burst quad."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -201,54 +201,39 @@ Node3D ("MuzzleFlash") [script: muzzle_flash.gd]
 
 Place the node at the **barrel tip** of the weapon. If your gun model has a `BarrelTip` Marker3D, parent there directly.
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
+Write the two files, then mount the flash with ONE `summer_run_script` call with
+an explicit `scenePath` — one transactional run, and mounting a flash on every
+weapon in the scene is a loop instead of a chain of calls per gun:
 
 ```
 summer_write_file(path="res://addons/vfx/muzzle-flash/muzzle_flash.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/muzzle-flash/muzzle_flash.gd", content="<section 3>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./Player/Weapon/BarrelTip", type="Node3D", name="MuzzleFlash")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Weapon/BarrelTip/MuzzleFlash", key="script", value="res://addons/vfx/muzzle-flash/muzzle_flash.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Weapon/BarrelTip/MuzzleFlash", key="flash_size", value=0.6)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Weapon/BarrelTip/MuzzleFlash", key="flash_duration", value=0.08)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Weapon/BarrelTip/MuzzleFlash", key="light_energy", value=4.0)
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-Then in your weapon script, on `fire()`:
-
-```gdscript
-$BarrelTip/MuzzleFlash.fire()
-```
-
-Or connect the weapon's `fired` signal in the scene:
-
-```
-summer_connect_signal(scenePath="res://main.tscn", emitter="./Player/Weapon", signal="fired", receiver="./Player/Weapon/BarrelTip/MuzzleFlash", method="fire")
-```
-
-### 5a. One-script wiring (summer_run_script)
-
-On engines with `summer_run_script` (see `scene-scripting`), the node calls
-above are ONE transactional ctx script — and mounting a flash on every weapon in the
-scene becomes a loop instead of a CRUD chain per gun:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var tip := ctx.find("BarrelTip")
-    var flash := ctx.add_node("Node3D", "MuzzleFlash", tip)
+    var tip = ctx.find("BarrelTip")
+    var flash = ctx.add_node("Node3D", "MuzzleFlash", tip)
     flash.set_script(load("res://addons/vfx/muzzle-flash/muzzle_flash.gd"))
     flash.set("flash_size", 0.6)
     flash.set("flash_duration", 0.08)
     flash.set("light_energy", 4.0)
-    var weapon := ctx.find("Weapon")
+    var weapon = ctx.find("Weapon")
     weapon.connect("fired", Callable(flash, "fire"), CONNECT_PERSIST)
-    # CONNECT_PERSIST is required — a bare connect() works live but is NOT saved
+    # CONNECT_PERSIST is required: a bare connect() works live but is NOT saved
     ctx.save_scene()
+""")
 ```
 
-### 5b. Verify
+Then in your weapon script, on `fire()`:
+
+```gdscript
+$BarrelTip/MuzzleFlash.fire()
+```
+
+The script above already connects the weapon's `fired` signal to the flash; the
+one-call form is `summer_connect_signal(scenePath="res://main.tscn", emitter="./Player/Weapon", signal="fired", receiver="./Player/Weapon/BarrelTip/MuzzleFlash", method="fire")`.
+
+### 5a. Verify
 
 `muzzle_flash.gd` `preload`s its own shader, so a shader that failed to write takes
 the script down at parse time. Check before firing a shot.
@@ -387,3 +372,26 @@ After firing this recipe, suggest:
 - `vfx-hit-spark` — companion impact effect
 - `vfx-lightning` — for energy weapons (replace the flash with a beam)
 - `game-feel` — recoil + hit-stop wiring
+
+<!-- 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_create_scene` | `summer engine create-scene` |
+| `summer_get_debugger_errors` | `summer engine get-debugger-errors` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_play` | `summer engine play` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/vfx-muzzle-flash/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-muzzle-flash
 kind: skill
 version: 1.0.3
-summary: Muzzle-flash effect — a one-shot ~80 ms burst at a gun barrel built with a particle one-shot or a flashing quad with a star-burst shader.
+summary: "Muzzle-flash effect: a one-shot ~80 ms burst at a gun barrel, from particles or a star-burst quad."
 use_when:
   - authoring a muzzle-flash effect — gun fire, weapon flash, barrel flash, spell-cast burst at a hand
   - a gun or spell-casting hand shoots with no visible flash at the barrel or palm

package/library/skills/vfx-smoke/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-smoke
-description: "Smoke effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D."
+description: "Smoke effect: a rising column or puff of soft particles with a noise and density falloff shader."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -228,42 +228,19 @@ child nodes, and `ParticleProcessMaterial` is a `Material` — you cannot
 
 ### 5. Wire it in (MCP calls)
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
-
-For chimney smoke or fire pairing, parent the Smoke just above the heat source:
+Write the three files, then wire the emitter with ONE `summer_run_script` call
+with an explicit `scenePath` — transactional, and it builds the QuadMesh +
+ShaderMaterial resources directly instead of `.tres` sidecars. For chimney
+smoke, parent the Smoke just above the heat source:
 
 ```
 summer_write_file(path="res://addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc", content="<from this skill>", create_only=true)
 summer_write_file(path="res://addons/vfx/smoke/smoke.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/smoke/smoke_controller.gd", content="<section 3>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./World/Cottage/Chimney", type="GPUParticles3D", name="Smoke")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="script", value="res://addons/vfx/smoke/smoke_controller.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="position", value="Vector3(0, 0.3, 0)")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="rise_height", value=4.0)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="particle_count", value=48)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="wind_direction", value="Vector3(0.4, 0, 0.1)")
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-For pairing with a fire:
-
-```
-summer_add_node(scenePath="res://main.tscn", parent="./World/Campfire", type="GPUParticles3D", name="Smoke")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Campfire/Smoke", key="position", value="Vector3(0, 1.5, 0)")  # above flame top
-summer_set_prop(scenePath="res://main.tscn", path="./World/Campfire/Smoke", key="rise_height", value=3.0)
-```
-
-### 5a. One-script wiring (summer_run_script)
-
-On engines with `summer_run_script` (see `scene-scripting`), the node wiring
-above is ONE ctx script — transactional, and it builds the QuadMesh + ShaderMaterial
-resources directly instead of `.tres` sidecars:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var smoke := ctx.add_node("GPUParticles3D", "Smoke", ctx.find("Chimney"))
+    var smoke = ctx.add_node("GPUParticles3D", "Smoke", ctx.find("Chimney"))
     smoke.set_script(load("res://addons/vfx/smoke/smoke_controller.gd"))
     smoke.process_material = ParticleProcessMaterial.new()
     var quad := QuadMesh.new()
@@ -277,11 +254,16 @@ func run(ctx):
     smoke.set("particle_count", 48)
     smoke.set("wind_direction", Vector3(0.4, 0, 0.1))
     ctx.save_scene()
+""")
 ```
 
+For pairing with a fire, run the same script with `ctx.find("Campfire")` as the
+parent, `position = Vector3(0, 1.5, 0)` (above the flame top) and
+`rise_height` 3.0.
+
 Verify with `summer_snapshot_diff` (exactly one node added) and a `summer_screenshot`.
 
-### 5b. Verify
+### 5a. Verify
 
 The shader and the controller are compiled code. Check them before tuning anything.
 
@@ -466,3 +448,29 @@ After firing this recipe, suggest:
 - `vfx-fire` — sister recipe, almost always paired
 - `vfx-dissolve` — for ash particles after disintegration
 - `gdscript-patterns` — for the controller idioms (signals, exports, `@tool`)
+
+<!-- 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_create_scene` | `summer engine create-scene` |
+| `summer_get_debugger_errors` | `summer engine get-debugger-errors` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_resource` | `summer engine inspect-resource` |
+| `summer_play` | `summer engine play` |
+| `summer_read_file` | `summer engine read-file` |
+| `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_set_resource_property` | `summer engine set-resource-property` |
+| `summer_snapshot_diff` | `summer engine snapshot-diff` |
+| `summer_stop` | `summer engine stop` |
+| `summer_world_snapshot` | `summer engine world-snapshot` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/vfx-smoke/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-smoke
 kind: skill
 version: 1.0.2
-summary: Smoke effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D.
+summary: "Smoke effect: a rising column or puff of soft particles with a noise and density falloff shader."
 use_when:
   - authoring a smoke effect — smoke trail, puff, chimney smoke, steam, fog cloud, explosion smoke
   - a chimney, campfire, explosion, or vent needs a rising smoke column or puff in a 3D scene

package/library/skills/vfx-water-ripple/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-water-ripple
-description: "Water-ripple effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts."
+description: "Water-ripple effect: animated normal-distortion ripples on a water plane or Decal, set off by impacts."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -221,54 +221,35 @@ MeshInstance3D ("Water") [script: water_ripple_surface.gd]
 
 ### 5. Wire it in (MCP calls)
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`); `summer_set_resource_property` always needs a `subProperty` and is
-for reaching *into* a resource, not for assigning one.
+Write the two files, then wire the surface with ONE `summer_run_script` call
+with an explicit `scenePath` — transactional, and it builds the subdivided
+PlaneMesh directly, so no `plane.tres` sidecar is needed:
 
 ```
 summer_write_file(path="res://addons/vfx/water-ripple/water_ripple.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/water-ripple/water_ripple_surface.gd", content="<section 3>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./World", type="MeshInstance3D", name="Puddle")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="script", value="res://addons/vfx/water-ripple/water_ripple_surface.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="position", value="Vector3(0, 0.01, 0)")
-
-# Whole resources are assigned by path with summer_set_prop.
-summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="mesh", value="res://addons/vfx/water-ripple/plane.tres")
-# `normal_texture` is an exported script property on the controller, not a
-# MeshInstance3D property — MeshInstance3D has no `normal_texture`.
-summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="normal_texture", value="res://addons/vfx/water-ripple/water_normals.png")
-
-# subProperty is required — this is how you reach into the PlaneMesh itself.
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Puddle", resourceProperty="mesh", subProperty="subdivide_width", value=32)
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Puddle", resourceProperty="mesh", subProperty="subdivide_depth", value=32)
-
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-### 5a. One-script wiring (summer_run_script)
-
-On engines with `summer_run_script` (see `scene-scripting`), the node and
-resource wiring is ONE transactional ctx script — and it builds the subdivided
-PlaneMesh directly, so the `plane.tres` sidecar disappears:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var puddle := ctx.add_node("MeshInstance3D", "Puddle", null)
+    var puddle = ctx.add_node("MeshInstance3D", "Puddle", ctx.find("World"))
     var plane := PlaneMesh.new()
     plane.subdivide_width = 32
     plane.subdivide_depth = 32
     puddle.mesh = plane
     puddle.position = Vector3(0, 0.01, 0)
     puddle.set_script(load("res://addons/vfx/water-ripple/water_ripple_surface.gd"))
+    # normal_texture is an exported property of the controller script, not of MeshInstance3D
     puddle.set("normal_texture", load("res://addons/vfx/water-ripple/water_normals.png"))
     ctx.save_scene()
+""")
 ```
 
 Set the mesh BEFORE the script if the controller reads it in `_ready`; either way,
-`ctx.add_node` has already owned the node, so it survives the save.
+`ctx.add_node` has already owned the node, so it survives the save. Tuning one
+mesh value later is one `summer_set_resource_property` call (`resourceProperty="mesh"`,
+`subProperty="subdivide_width"`): it reaches into a resource, it never assigns one.
 
-### 5b. Verify
+### 5a. Verify
 
 The shader and the controller are compiled code, and the controller `preload`s the
 shader — a shader that failed to write takes the script down at parse time.
@@ -420,3 +401,26 @@ After firing this recipe, suggest:
 - `vfx-hit-spark` — sister recipe for the upward droplets
 - `vfx-smoke` — for steam over hot liquids
 - `gdscript-patterns` — for the controller idioms
+
+<!-- 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_create_scene` | `summer engine create-scene` |
+| `summer_get_debugger_errors` | `summer engine get-debugger-errors` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_resource` | `summer engine inspect-resource` |
+| `summer_play` | `summer engine play` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/vfx-water-ripple/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-water-ripple
 kind: skill
 version: 1.0.2
-summary: Water-ripple effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts.
+summary: "Water-ripple effect: animated normal-distortion ripples on a water plane or Decal, set off by impacts."
 use_when:
   - authoring a water-ripple effect — raindrop ripples, splash ripples, footstep in a puddle, fish jumps
   - rain, footsteps, or falling objects should disturb a water surface with spreading ripples