summer-engine 3.8.0 → 4.2.0

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,31 @@ 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.
+
+<!-- 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` | `summer assets generate-3d` |
+| `summer_assets_generate_image` | `summer assets generate-image` |
+| `summer_assets_get` | `summer assets get` |
+| `summer_assets_search` | `summer assets search` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_import_asset_by_id` | `summer engine import-asset-by-id` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_inspect_asset` | `summer engine inspect-asset` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_resource` | `summer engine inspect-resource` |
+| `summer_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `jobs.wait`, `summer_jobs_wait` | `summer jobs wait` |
+| `summer_search` | `summer ops search "<what you want>"` |
+<!-- /shell-commands -->

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

package/library/skills/verification-before-completion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verification-before-completion
-description: "Run verification commands and confirm output before claiming work complete, fixed, or passing — evidence before assertions, always."
+description: "Run verification and read its output before claiming work done, fixed or passing: evidence first."
 ---
 
 # Verification Before Completion

package/library/skills/verification-before-completion/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/verification-before-completion
 kind: skill
 version: 1.0.3
-summary: Run verification commands and confirm output before claiming work complete, fixed, or passing — evidence before assertions, always.
+summary: "Run verification and read its output before claiming work done, fixed or passing: evidence first."
 use_when:
   - about to claim work is complete, fixed, or passing, before committing or creating PRs
   - about to report a test, build, or fix as passing without having run the command and read its output

package/library/skills/verifying-scenes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verifying-scenes
-description: "Prove scene work landed (snapshot, diff, screenshots, runtime reads), audit 3D scenes for holes and misplacement, review them with shot sheets and zooms."
+description: "Prove scene work landed: snapshot, diff, screenshots, runtime reads, 3D audits, shot sheets and zooms."
 ---
 
 # Verifying Scenes
@@ -153,7 +153,7 @@ When the next step depends on the engine reaching a moment — the game booting
 - NEVER describe an image you did not receive. A failed capture is a result — report it and climb down (scene → viewport) or ask the user.
 - Preset-framing scene renders are static (t=0), synthetic-camera, flat-environment: no claims about animation, particles, lighting, or mood from them.
 - Pass structured failures (`failure_reason`, `terminalState`) through verbatim — never soften them into "it didn't work".
-- After the result is verified, record the outcome with `summer_library_feedback` (worked / worked with fixes / wrong / outdated / incomplete + a short note). Optional and fire-and-forget; if telemetry is off, move on.
+- After the result is verified, record the outcome with `summer_call` `{"op":"docs.feedback"}` (worked / worked with fixes / wrong / outdated / incomplete + a short note). Optional and fire-and-forget; if telemetry is off, move on.
 
 ## Red Flags — STOP
 
@@ -170,3 +170,32 @@ When the next step depends on the engine reaching a moment — the game booting
 | "Looks great!" with no capture in the transcript | Fabrication. Capture, look, then claim. |
 
 **Related skills:** `scene-scripting` carries the mutation loop and ctx API this discipline wraps; `playtesting-a-feature` and `verification-before-completion` carry the broader done-claiming rules.
+
+<!-- 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 |
+|---|---|
+| `docs.feedback` | `summer docs feedback` |
+| `summer_debug_views` | `summer engine debug-views` |
+| `summer_frame_nodes` | `summer engine frame-nodes` |
+| `summer_frame_shot` | `summer engine frame-shot` |
+| `summer_get_runtime_tree` | `summer engine get-runtime-tree` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_inspect_asset` | `summer engine inspect-asset` |
+| `summer_inspect_runtime_node` | `summer engine inspect-runtime-node` |
+| `summer_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_is_running` | `summer engine is-running` |
+| `summer_camera_bookmark` | `summer engine list-camera-bookmarks`, `summer engine delete-camera-bookmark`, `summer engine save-camera-bookmark` |
+| `summer_play` | `summer engine play` |
+| `summer_recent_events` | `summer engine recent-events` |
+| `summer_scene_audit` | `summer engine scene-audit` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_shot_sheet` | `summer engine shot-sheet` |
+| `summer_snapshot_diff` | `summer engine snapshot-diff` |
+| `summer_wait_for_event` | `summer engine wait-for-event` |
+| `summer_world_snapshot` | `summer engine world-snapshot` |
+| `summer_zoom` | `summer engine zoom` |
+<!-- /shell-commands -->

package/library/skills/verifying-scenes/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/verifying-scenes
 kind: skill
 version: 1.5.0
-summary: 'Prove scene work landed (snapshot, diff, screenshots, runtime reads), audit 3D scenes for holes and misplacement, review them with shot sheets and zooms.'
+summary: "Prove scene work landed: snapshot, diff, screenshots, runtime reads, 3D audits, shot sheets and zooms."
 use_when:
   - after any mutation batch, asset import, or lighting change, before claiming it worked
   - during a playtest, to read live runtime state (spawned nodes, actual stats) without stopping the game

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

@@ -1,6 +1,6 @@
 ---
 name: vfx-dissolve
-description: "Dissolve effect — a mesh disintegrating with a glowing burning edge, driven by a noise-threshold ShaderMaterial overriding the target's material."
+description: "Dissolve effect: a mesh burns away with a glowing edge, from a noise-threshold ShaderMaterial."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -256,7 +256,7 @@ material, no play-mode round-trip:
 
 ```gdscript
 func run(ctx):
-    var mat := ctx.make_shader("<section 2 source>", {"threshold": 0.4})
+    var mat = ctx.make_shader("<section 2 source>", {"threshold": 0.4})
     ctx.apply_material(ctx.find("TestDummy"), mat)   # eyeball it with summer_screenshot
 ```
 
@@ -409,3 +409,22 @@ After firing this recipe, suggest:
 - `vfx-magic-glow` — for arrival/departure beams
 - `vfx-fire` — for the burn-up variant pairing
 - `gdscript-patterns` — for the static-API class pattern
+
+<!-- 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_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_screenshot` | `summer engine screenshot` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

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

@@ -1,7 +1,7 @@
 id: skill/vfx-dissolve
 kind: skill
 version: 1.0.3
-summary: Dissolve effect — a mesh disintegrating with a glowing burning edge, driven by a noise-threshold ShaderMaterial overriding the target's material.
+summary: "Dissolve effect: a mesh burns away with a glowing edge, from a noise-threshold ShaderMaterial."
 use_when:
   - authoring a dissolve effect — an object disintegrating with a glowing burning edge (disintegrate, burn away, vanish into ash)
   - a defeated unit, teleport exit, or removed object should burn away with a glowing edge instead of vanishing

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

@@ -1,6 +1,6 @@
 ---
 name: vfx-fire
-description: "Fire effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp — torches, campfires, candles."
+description: "Fire effect: animated flames from GPUParticles3D, a particle shader and a noise color ramp."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -285,50 +285,21 @@ apply here — a draw pass mesh carries its material in `Mesh.material`.
 
 Add an OmniLight3D as a sibling (parented to the same anchor as the GPUParticles3D, NOT under it) for proper light cast. Recommended: `light_color = Color(1.0, 0.6, 0.25)`, `light_energy = 1.6`, `omni_range = 6.0`. Pulse it lightly via the controller for free atmosphere.
 
-### 6. Wire it in (MCP calls)
+### 6. Wire it in
 
-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 three files, then wire everything in ONE `summer_run_script` call with
+an explicit `scenePath` — transactional (rollback on a mid-script error), no
+`.tres` sidecar files needed because the script builds the resources directly:
 
 ```
 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/fire/fire.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/fire/fire_controller.gd", content="<section 4>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./World/Torch", type="GPUParticles3D", name="Fire")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="script", value="res://addons/vfx/fire/fire_controller.gd")
-
-# ParticleProcessMaterial is a Material, not a Node — you cannot summer_add_node it.
-# Assign the resource by path; the controller configures it on _ready().
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="process_material", value="res://addons/vfx/fire/process_mat.tres")
-
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="draw_pass_1", value="res://addons/vfx/fire/quad.tres")
-# quad.tres is a QuadMesh with size (1,1) and material = fire_material.tres (ShaderMaterial wrapping fire.gdshader)
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Torch/Fire", resourceProperty="draw_pass_1", subProperty="size", value="Vector2(1, 1)")
-
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="flame_height", value=1.2)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="flame_radius", value=0.35)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="particle_count", value=96)
-
-summer_add_node(scenePath="res://main.tscn", parent="./World/Torch", type="OmniLight3D", name="FireLight")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/FireLight", key="light_color", value="Color(1.0, 0.6, 0.25)")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/FireLight", key="light_energy", value=1.6)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/FireLight", key="omni_range", value=6.0)
-
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-### 6a. One-script wiring (summer_run_script)
-
-On engines with `summer_run_script` (see `scene-scripting`), everything after
-the `summer_write_file` calls above is ONE ctx script — transactional (rollback on a
-mid-script error), no `.tres` sidecar files needed because the script builds the
-resources directly:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var anchor := ctx.find("Torch")
-    var fire := ctx.add_node("GPUParticles3D", "Fire", anchor)
+    var anchor = ctx.find("Torch")
+    var fire = ctx.add_node("GPUParticles3D", "Fire", anchor)
     fire.set_script(load("res://addons/vfx/fire/fire_controller.gd"))
     fire.process_material = ParticleProcessMaterial.new()   # controller configures it on _ready
     var quad := QuadMesh.new()
@@ -343,13 +314,16 @@ func run(ctx):
     ctx.add_node("OmniLight3D", "FireLight", anchor, {
         "light_color": Color(1.0, 0.6, 0.25), "light_energy": 1.6, "omni_range": 6.0})
     ctx.save_scene()
+""")
 ```
 
-`ctx.add_node` sets owners for you. Take a `summer_world_snapshot` before, and verify
-after with `summer_snapshot_diff` (exactly `Fire` + `FireLight` added) plus a
-`summer_screenshot` — flames are pixels, judge them as pixels.
+`ParticleProcessMaterial` is a Material, not a Node: the script assigns it to
+`process_material`, it is never a child. `ctx.add_node` sets owners for you. Take
+a `summer_world_snapshot` before, and verify after with `summer_snapshot_diff`
+(exactly `Fire` + `FireLight` added) plus a `summer_screenshot` — flames are
+pixels, judge them as pixels.
 
-### 6b. Verify
+### 6a. Verify
 
 Every file this recipe writes is compiled code. Check it before claiming the fire works.
 
@@ -503,3 +477,29 @@ After firing this recipe, suggest neighbors:
 - `vfx-magic-glow` — for the light source pulsing
 - `game-feel` — non-particle game-feel pairings
 - `gdscript-patterns` — for the controller's 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-fire/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-fire
 kind: skill
 version: 1.0.3
-summary: Fire effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp — torches, campfires, candles.
+summary: "Fire effect: animated flames from GPUParticles3D, a particle shader and a noise color ramp."
 use_when:
   - authoring a fire visual effect — torch, campfire, bonfire, flame, burning object, candle
   - adding fire to props, hazards, or projectiles — torches, braziers, burning wreckage, a fireball or flame jet

package/library/skills/vfx-hit-spark/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-hit-spark
-description: "Hit-spark effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact."
+description: "Hit-spark effect: a one-shot burst of additive particles oriented to the surface, fired on impact."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -371,3 +371,26 @@ After firing this recipe, suggest:
 - `vfx-lightning` — caller; spawns sparks at bolt endpoints
 - `vfx-water-ripple` — surface companion for water impacts
 - `game-feel` — shake/hit-stop pairings
+
+<!-- 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_replace_node` | `summer engine replace-node` |
+| `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-hit-spark/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-hit-spark
 kind: skill
 version: 1.0.2
-summary: Hit-spark effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact.
+summary: "Hit-spark effect: a one-shot burst of additive particles oriented to the surface, fired on impact."
 use_when:
   - authoring a hit-spark effect — impact spark, bullet hit, sword clash, ricochet, sparks at a hit point
   - melee hits, bullet impacts, or ricochets have no visual feedback at the contact point