summer-engine 3.8.0 → 4.2.0

package/library/skills/fabricating-assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabricating-assets
-description: "Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models."
+description: "Fabricate meshes with a Blender script (summer_fabricate_3d): exact-size kits, VFX meshes, post-processing."
 ---
 
 # Fabricating Assets
@@ -22,10 +22,10 @@ Three facts shape every use:
 | Asset class | First route | Second | Why |
 |---|---|---|---|
 | Blockout / placeholder | `scene-scripting` primitives or CSG | fabricate | Must be instant and in-scene; no process spawn is justified |
-| Generic hard-surface prop ("a barrel") | `summer_search_assets` → `summer_import_asset` (`prop-model`) | `summer_generate_3d` | The free library plus `target_size` beats paid generation and a 2-minute wait, in a consistent style |
-| Bespoke prop ("the artifact from our GDD") | `summer_generate_3d` | fabricate | Image-to-3D is exactly what generation is for; fabricate when exact dimensions or parametric variants matter |
+| Generic hard-surface prop ("a barrel") | `assets.search` → `summer_import_asset` (`prop-model`) | `assets.generate_3d` | The free library plus `target_size` beats paid generation and a 2-minute wait, in a consistent style |
+| Bespoke prop ("the artifact from our GDD") | `assets.generate_3d` | fabricate | Image-to-3D is exactly what generation is for; fabricate when exact dimensions or parametric variants matter |
 | **Modular kit** (walls, pipes, fences, rails that snap) | **fabricate** | generated kit (`environment-kit`) | Generation cannot hold dimensions and style across 30 pieces; array + boolean + bevel + one material is the classic kit workflow |
-| Characters (rigged, animated) | `summer_generate_3d` (`character-model`) | library | Scripted organic modelling is the documented failure mode; fabrication has no path to competitive organics blind |
+| Characters (rigged, animated) | `assets.generate_3d` (`character-model`) | library | Scripted organic modelling is the documented failure mode; fabrication has no path to competitive organics blind |
 | Environments / terrain | in-engine terrain + library set dressing | generation for landmarks | Terrain wants interactive tools; dressing wants scatter |
 | Materials / textures / skies | library (`summer_import_hdri`, texture packs) | generation | Fabricate only to bake a procedural material to images |
 | **VFX meshes** (shatter pieces, trails, sweeps, LOD chains) | **fabricate** | in-engine | Bisect/fracture, curve sweeps, decimate are one-liners in bpy and absent in the engine |
@@ -146,7 +146,7 @@ Factory startup disables add-ons, so cell-fracture operators are not available.
 
 | `failure_reason` | What happened | Do |
 |---|---|---|
-| `engine_lacks_op` | This engine build predates FabricateMesh (nothing was sent) | Route to `summer_generate_3d`, `summer_search_assets` / `summer_import_asset`, or `summer_run_script` blockout geometry; tell the user an engine update enables fabrication |
+| `engine_lacks_op` | This engine build predates FabricateMesh (nothing was sent) | Route to `assets.generate_3d`, `assets.search` / `summer_import_asset`, or `summer_run_script` blockout geometry; tell the user an engine update enables fabrication |
 | `blender_not_found` | No usable Blender executable (see `tried`) | Relay the one-line decision above; never guess a path or install anything |
 | `blender_launch_failed` | The executable exists but did not start (permissions, broken install, wrong architecture) | Show the `error` and `output` tail to the user; a different `blender_path` or a reinstall is their call |
 | `script_error` | Your bpy raised (`traceback_tail`, `script_line`, `blender_version`) | Fix the named line against the reported version; `script_line` maps to your `source` |
@@ -169,14 +169,14 @@ Every failure leaves the project untouched except `import_failed` / `instantiate
 - **Output is unencumbered.** Meshes made with Blender belong to the user; the `.glb` in their project carries no Blender licence obligation.
 - **Scripts you write here are created on the user's machine and never distributed by Summer.** If you adapt a bpy snippet from elsewhere, respect its licence — prefer your own code or CC0 sources, and record the origin in `.summer/memory/decisions/` when it matters for the project.
 - **Trademark.** "Blender" is a trademark of the Blender Foundation. Refer to it factually as the dependency ("requires Blender"); never describe the feature as powered by, built on, or branded with Blender, and never use its logo. Summer's name for this capability is *mesh fabrication*.
-- Imported library assets keep their own licences (`summer_search_assets` results carry `licenseType`); fabrication does not change that.
+- Imported library assets keep their own licences (`assets.search` results carry `license`); fabrication does not change that.
 
 ## Red Flags — STOP
 
 | Red flag | Reality |
 |---|---|
 | Fabricating a barrel, a crate, a chair | Library first, generation second. Fabricate is for kits, VFX meshes, and post-processing |
-| Fabricating a character or creature | Scripted organic modelling is the documented failure mode; `summer_generate_3d` with rigging |
+| Fabricating a character or creature | Scripted organic modelling is the documented failure mode; `assets.generate_3d` with rigging |
 | A script that calls `export_scene.gltf`, saves, or quits | Breaks the contract; the bootstrap exports |
 | A material that is not a Principled BSDF | Exports grey; the `warnings` list said so |
 | Procedural roughness or normal maps left unbaked | Not baked automatically — set constants or bake in the script |
@@ -193,3 +193,26 @@ Every failure leaves the project untouched except `import_failed` / `instantiate
 - `environment-kit`, `prop-model`, `character-model` — the generation and library specialists fabrication defers to.
 - `scene-scripting` — in-scene geometry, placement loops, and wrapping fabricated pieces in bodies and collisions.
 - `verifying-scenes` and `verification-before-completion` — the evidence discipline after import.
+
+<!-- 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` |
+| `assets.search` | `summer assets search` |
+| `summer_fabricate_3d` | `summer engine fabricate-3d` |
+| `summer_get_console` | `summer engine get-console` |
+| `summer_get_project_context` | `summer engine get-project-context` |
+| `summer_import_asset` | `summer engine import-asset` |
+| `summer_import_hdri` | `summer engine import-hdri` |
+| `summer_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_remove_node` | `summer engine remove-node` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_snapshot_diff` | `summer engine snapshot-diff` |
+| `summer_world_snapshot` | `summer engine world-snapshot` |
+<!-- /shell-commands -->

package/library/skills/fabricating-assets/resource.yaml

@@ -1,17 +1,17 @@
 id: skill/fabricating-assets
 kind: skill
 version: 1.0.0
-summary: Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models.
+summary: "Fabricate meshes with a Blender script (summer_fabricate_3d): exact-size kits, VFX meshes, post-processing."
 use_when:
   - writing a Blender Python (bpy) script for summer_fabricate_3d and deciding whether fabrication, generation, or the free library is the right route for an asset
   - a parametric hard-surface set with exact dimensions, booleans, bevels, and shared materials that must stay consistent across many pieces
   - VFX meshes — shatter fragments, curve sweeps, trails, LOD chains — or decimating, UV-unwrapping, and baking a generated model before it goes into the scene
   - a fabrication failed (blender_not_found, script_error, export_empty, import_failed, busy, timeout) and the result needs to be read correctly
 do_not_use_when:
-  - a generic prop — search the free library first (summer_search_assets, prop-model), then generate (summer_generate_3d)
+  - a generic prop — search the free library first (assets.search, prop-model), then generate (assets.generate_3d)
   - a character or any organic shape — character-model / organic-model; scripted organic modelling is the documented failure mode
   - a blockout or placeholder — scene-scripting primitives/CSG are instant and in-scene
-  - "the engine build lacks FabricateMesh (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — route to summer_generate_3d / summer_search_assets / summer_run_script instead"
+  - "the engine build lacks FabricateMesh (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — route to assets.generate_3d / assets.search / summer_run_script instead"
 facets:
   lifecycle:
     - build

package/library/skills/facial-and-lipsync/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: facial-and-lipsync
-description: "Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions."
+description: "Make a character's mouth move with a voice-over: phonemes, viseme blendshapes, facial expressions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
 user-invocable: false
-allowed-tools: Read Grep Edit Write summer_search_assets summer_inspect_resource summer_inspect_node summer_generate_audio summer_generate_motion summer_run_script summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_script_errors
+allowed-tools: Read Grep Edit Write summer_assets_search summer_inspect_resource summer_inspect_node summer_assets_generate_audio summer_assets_generate_motion summer_run_script summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_script_errors summer_jobs_wait summer_call
 paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 ---
 
 # Facial Animation & Lipsync
 
-Half generative, half authored. The *generative* half: an audio file (TTS via `summer_generate_audio` with `capability: "text_to_speech"`) goes through a phoneme-extraction tool (Summer does NOT wrap one — you run it externally), out comes a viseme timeline — a list of `{ phoneme, start_time, duration }` triples. The *authored* half: the character's face mesh must have BlendShapes named for the standard viseme set, or the timeline has nothing to drive. Without both halves, you get a talking robot.
+Half generative, half authored. The *generative* half: an audio file (TTS via `assets.generate_audio` with `capability: "text_to_speech"`) goes through a phoneme-extraction tool (Summer does NOT wrap one — you run it externally), out comes a viseme timeline — a list of `{ phoneme, start_time, duration }` triples. The *authored* half: the character's face mesh must have BlendShapes named for the standard viseme set, or the timeline has nothing to drive. Without both halves, you get a talking robot.
 
 The pipeline:
 
-1. **Audio in** — `.wav`/`.mp3` from `summer_generate_audio({capability: "text_to_speech", ...})` or imported VO.
+1. **Audio in** — `.wav`/`.mp3` from `assets.generate_audio({ capability: "text_to_speech", ... })` or imported VO.
 2. **Phoneme extraction** — done OUTSIDE Summer. Recommended: **Rhubarb Lip Sync** (open source, widely used for game lipsync; outputs JSON with mouth-shape cues over time). Alternatives: gentle, allosaurus, or a Whisper-phoneme model on Replicate / Hugging Face. There is no `summer_*` MCP for this in the current engine.
 3. **Viseme mapping** — phonemes / Rhubarb cues → Oculus / Apple ARKit viseme set (15 standard shapes covers English).
 4. **BlendShape driver** — at runtime, lerp the mesh's BlendShape weights along the timeline, synced to audio playback.
@@ -32,7 +32,7 @@ The pipeline:
 ## When NOT to use this skill
 
 - Character has no face / no BlendShapes (helmeted soldier, robot, mascot). Hard-skip to body language via `generate-motion`.
-- The dialogue is written but not yet voiced — generate audio first via `summer_generate_audio({capability: "text_to_speech", ...})`. Lipsync without audio has nothing to sync to.
+- The dialogue is written but not yet voiced — generate audio first via `assets.generate_audio({ capability: "text_to_speech", ... })`. Lipsync without audio has nothing to sync to.
 - Pre-rendered cinematic from external DCC. Lipsync is in the rendered video, not the engine.
 
 ## Steps
@@ -47,27 +47,26 @@ Look for `mesh.blend_shape_count` > 0 and a list of names. An ARKit-52 head has
 
 If the head has zero BlendShapes, stop. Tell the user: "This head mesh has no BlendShapes — facial animation needs shape keys on the mesh. Options: use an emotional body-language overlay instead, author shape keys in Blender and re-import, or hand the character to a 3D artist." Don't proceed.
 
-Do **not** promise a `face_blendshapes` generation option. `summer_generate_3d`
-has no such parameter and nothing in the Summer generation pipeline handles one
-— `options` is an untyped passthrough, so a bogus key is accepted by the schema
-and then silently ignored by the backend. Regenerating will not add BlendShapes.
+Do **not** promise a `face_blendshapes` generation option. `assets.generate_3d`
+has no such field and nothing in the Summer generation pipeline handles one; a
+field the operation does not list does nothing. Regenerating will not add BlendShapes.
 Shape keys come from the mesh author (Blender / an ARKit-52 source mesh), not
 from a rig pass.
 
 ### 2. Get the audio
 
-If the user has VO already, use it. If not, generate via TTS. The `voiceId` is an ElevenLabs voice ID — the user has to pick one from the ElevenLabs voice library (https://elevenlabs.io/app/voice-library) or upload/clone their own. There is no "voice name" string; it's always an ID like `21m00Tcm4TlvDq8ikWAM` (Rachel) or a custom-cloned ID.
+If the user has VO already, use it. If not, generate via TTS. On the ElevenLabs models the `voiceId` must be one of Summer's game-cast voices (the `voice-line` skill lists them with their ids); any other id is refused. There is no "voice name" string; it's always an ID like `IKne3meq5aSn9XLyUdCD` (Charlie, the hero).
 
 ```
-summer_generate_audio({
+assets.generate_audio({
   capability: "text_to_speech",
   text: "Welcome to the village, traveler.",
-  voiceId: "<elevenlabs_voice_id>"
+  voiceId: "<cast voice id>"
 })
-// returns { jobId, ... } — poll with summer_check_job for the audio asset
+// answers at once with asset: { assetId, fileUrl, durationSeconds }
 ```
 
-If the user hasn't picked a voice yet, stop and ask: "Which ElevenLabs voice ID should I use? You can browse the library at elevenlabs.io/app/voice-library and copy the ID, or paste a custom-clone ID from your account."
+If the user hasn't picked a voice yet, stop and ask which cast voice fits the character (see `voice-line`).
 
 ### 3. Extract phonemes (the generative step — runs OUTSIDE Summer)
 
@@ -296,7 +295,7 @@ production speech recognition or photoreal lip sync.
 
 ## Handoff
 
-- For voice generation upstream, `voice-line` (which wraps `summer_generate_audio({capability: "text_to_speech", ...})`).
+- For voice generation upstream, `voice-line` (which wraps `assets.generate_audio({ capability: "text_to_speech", ... })`).
 - For dialogue scripts and conversation flow, `design-npc`.
 - For the AnimationTree this layer composes into, `animation-tree`.
 - For idle blinks, saccades, and head-tracking that complement lipsync, `procedural-animation`.
@@ -309,3 +308,25 @@ production speech recognition or photoreal lip sync.
 - `animation-tree` — wire the lipsync OneShot into the character's tree.
 - `procedural-animation` — eye blinks, saccades, head idle.
 - Rhubarb Lip Sync — https://github.com/DanielSWolf/rhubarb-lip-sync (external tool; phoneme extraction).
+
+<!-- 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` |
+| `assets.generate_audio`, `summer_assets_generate_audio` | `summer assets generate-audio` |
+| `summer_assets_generate_motion` | `summer assets generate-motion` |
+| `summer_assets_search` | `summer assets search` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_inspect_resource` | `summer engine inspect-resource` |
+| `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_jobs_wait` | `summer jobs wait` |
+<!-- /shell-commands -->

package/library/skills/facial-and-lipsync/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/facial-and-lipsync
 kind: skill
 version: 1.0.2
-summary: Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions.
+summary: "Make a character's mouth move with a voice-over: phonemes, viseme blendshapes, facial expressions."
 use_when:
   - the user has (or wants) a voice-over and needs the character's mouth to move with the words
   - adding emotional facial expressions (smile, frown, surprise)

package/library/skills/fps-controller/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: fps-controller
-description: "Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling."
+description: "First-person controller: WASD, mouse look, jump, coyote time, jump buffering, air control."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: character-controllers
 user-invocable: false
 template-id: template-3d-fps-old-school
-allowed-tools: Read Grep summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_input_map_bind summer_save_scene summer_get_script_errors
+allowed-tools: Read Grep summer_get_scene_tree summer_run_script summer_add_node summer_set_prop summer_set_resource_property summer_input_map_bind summer_save_scene summer_get_script_errors
 paths: ["**/*.gd", "**/*.tscn"]
 ---
 
@@ -32,52 +32,44 @@ The Head/Camera split is the standard: yaw rotates the body, pitch rotates only
 
 Always call `summer_get_scene_tree` before mutating. If `World/Player`, `World/PlayerOld`, or any existing CharacterBody3D is present, ASK the user how to proceed before adding nodes.
 
-### 2. Add the Player root
+### 2. Build the Player rig in one script
 
-```
-summer_add_node(scenePath="res://main.tscn", parent="./World", type="CharacterBody3D", name="Player")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Player", key="position", value="Vector3(0, 1, 0)")
-```
-
-### 3. Add the collision shape and size it
+The body, its capsule, the head pivot and the camera are one `summer_run_script`
+call (one undo step):
 
 ```
-summer_add_node(scenePath="res://main.tscn", parent="./World/Player", type="CollisionShape3D", name="Collision")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Player/Collision", key="shape", value="CapsuleShape3D")
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Player/Collision", resourceProperty="shape", subProperty="radius", value="0.4")
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Player/Collision", resourceProperty="shape", subProperty="height", value="1.8")
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var player = ctx.add_node("CharacterBody3D", "Player", ctx.find("World"), {"position": Vector3(0, 1, 0)})
+    var capsule = CapsuleShape3D.new()
+    capsule.radius = 0.4
+    capsule.height = 1.8
+    ctx.add_node("CollisionShape3D", "Collision", player, {"shape": capsule, "position": Vector3(0, 0.9, 0)})
+    var head = ctx.add_node("Node3D", "Head", player, {"position": Vector3(0, 1.6, 0)})
+    ctx.add_node("Camera3D", "Camera", head)
+    ctx.save_scene()
+""")
 ```
 
-Two rules for these calls:
-
-- **`scenePath` is required** on `summer_add_node`, `summer_set_prop`,
-  `summer_set_resource_property` and `summer_save_scene`. Omit it and the call
-  never reaches the engine. (`summer_input_map_bind` is the exception — it edits
-  `project.godot`, not a scene, and takes only `name` + `events`.)
-- **This inline-resource sequence is the supported pattern, not a trap.**
-  `summer_set_prop` with a class-name string instantiates a scene-embedded
-  (`[sub_resource]`) resource, and `summer_set_resource_property` then reads that
-  property off the node and writes the sub-property straight onto it. Embedded
-  and external `.tres` resources take the same path. Structural failures are
-  explicit — `node not found`, `property is not a resource`, or `resource is
-  null` when the property was never assigned — but a bad value shape is silent
-  on current engines: a JSON object instead of an engine variant string, a
-  misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet
-  no-ops or coerces destructively. Assign the resource first, pass class names
-  and `Vector3(...)`/`Color(...)` strings, and confirm in the saved `.tscn`,
-  never from `ok` alone.
-
-### 4. Add the Head pivot + Camera
+Eye height of 1.6 sits the camera right at the top of a 1.8-tall capsule (capsule center 0.9, plus 0.7 to the eye). Tweak per art style.
 
-```
-summer_add_node(scenePath="res://main.tscn", parent="./World/Player", type="Node3D", name="Head")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Player/Head", key="position", value="Vector3(0, 1.6, 0)")
-summer_add_node(scenePath="res://main.tscn", parent="./World/Player/Head", type="Camera3D", name="Camera")
-```
+Two rules:
 
-Eye height of 1.6 sits the camera right at the top of a 1.8-tall capsule (capsule center 0.9, plus 0.7 to the eye). Tweak per art style.
+- **`scenePath` is required** on `summer_run_script` and on every scene tool
+  (`summer_set_prop`, `summer_set_resource_property`, `summer_save_scene`).
+  Omit it and the call never reaches the engine. (`summer_input_map_bind` is
+  the exception — it edits `project.godot`, not a scene, and takes only
+  `name` + `events`.)
+- **Build and size a shape before you assign it.** Tuning one value later is
+  one `summer_set_resource_property` call on the assigned resource. Structural
+  failures there are explicit — `node not found`, `property is not a resource`,
+  or `resource is null` when the property was never assigned — but a bad value
+  shape is silent on current engines: a JSON object instead of an engine
+  variant string, a misspelled `subProperty`, or a wrong-typed value returns
+  `ok:true` yet no-ops or coerces destructively. Pass `Vector3(...)`/`Color(...)`
+  strings and confirm in the saved `.tscn`, never from `ok` alone.
 
-### 5. InputMap actions
+### 3. InputMap actions
 
 ```
 summer_input_map_bind(name="move_forward", events=[{type:"key", key:"W"}])
@@ -88,7 +80,7 @@ summer_input_map_bind(name="jump",         events=[{type:"key", key:"Space"}])
 summer_input_map_bind(name="sprint",       events=[{type:"key", key:"Shift"}])
 ```
 
-### 6. Attach the controller script
+### 4. Attach the controller script
 
 Ask before writing: "May I create `scripts/player_controller.gd` and attach it to `./World/Player`?" Then `Write` the file with the skeleton in the next section, attach via inspector, and finish with `summer_save_scene(scenePath="res://main.tscn")` + `summer_get_script_errors(path="res://scripts/player_controller.gd")` (that tool checks one file and requires `path`).
 
@@ -356,3 +348,20 @@ If the user asks for a "third-person FPS", flag the contradiction: FPS = first-p
 - `gdscript-patterns` — once movement grows past this skeleton (slide, grapple, hover), refactor into a state machine instead of stuffing more branches into `_physics_process`.
 - `character-movement` — 2D and third-person controllers.
 - `game-feel` — camera shake and hit feedback.
+
+<!-- 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_get_script_errors` | `summer engine get-script-errors` |
+| `summer_input_map_bind` | `summer engine input-map-bind` |
+| `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` |
+<!-- /shell-commands -->

package/library/skills/fps-controller/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/fps-controller
 kind: skill
 version: 1.0.4
-summary: Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling.
+summary: "First-person controller: WASD, mouse look, jump, coyote time, jump buffering, air control."
 use_when:
   - building an FPS, first-person movement, or a 3D character that walks, jumps, and reacts to external forces
   - a first-person prototype needs solid movement feel — coyote time, jump buffering, air control

package/library/skills/game-feel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: game-feel
-description: "Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact."
+description: "Add juice: hit-flash, trauma camera shake and audio ducking, one hit fires all three."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -117,7 +117,7 @@ func flash() -> void:
 
 **Tunable knobs:** `duration` 0.06–0.12s — under 0.06 reads as a flicker, over 0.12 looks slow. `emission_energy_multiplier` 1.5–3.0.
 
-> Note: `summer_set_prop(key="material_override", value="StandardMaterial3D")` creates an inline `StandardMaterial3D` sub_resource that `summer_set_resource_property(resourceProperty="material_override", subProperty="albedo_color", value="Color(r, g, b, a)")` then edits and `summer_save_scene` persists — so the inline route, the script above, and a saved `materials/flash.tres` are all valid. What breaks is the value *shape*: a JSON object instead of a Godot literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or destructively coerces on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Always pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the result in the saved `.tscn` or a snapshot diff — never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
+> Note: `summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Enemy/Mesh", key="material_override", value="StandardMaterial3D")` creates an inline `StandardMaterial3D` sub_resource that `summer_set_resource_property(scenePath="res://levels/world.tscn", nodePath="./World/Enemy/Mesh", resourceProperty="material_override", subProperty="albedo_color", value="Color(r, g, b, a)")` then edits and `summer_save_scene` persists — so the inline route, the script above, and a saved `materials/flash.tres` are all valid. What breaks is the value *shape*: a JSON object instead of a Godot literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or destructively coerces on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Always pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the result in the saved `.tscn` or a snapshot diff — never from `ok` alone. See `summer_docs_read` id `reference/mcp-tools-reference`.
 
 ## Step 5 — Install Section 2 (Trauma Camera Shake)
 
@@ -370,12 +370,12 @@ Tune one knob at a time:
 | Equal pitch/yaw shake | `yaw_factor ≤ 0.5` | Eyes are sensitive to vertical motion; equal axes feel mechanical |
 | `Engine.time_scale` for every hit | Reserve hit-stop for big events only (boss hits, deaths) | Time-scale dips on every hit feel laggy, not impactful |
 | A JSON object (or a misspelled key) as the `summer_set_prop` / `summer_set_resource_property` value — e.g. `value={"type": "StandardMaterial3D", ...}` through `summer_batch`, which forwards ops verbatim | `value="StandardMaterial3D"` to create the inline material, then `summer_set_resource_property(... value="Color(r, g, b, a)")` per field; confirm in the saved `.tscn` | Current engines return `ok:true` and silently no-op or coerce destructively — dict → material cleared, dict → `Color(0,0,0,1)`. The inline sub_resource itself is fine |
-| `summer_set_prop(key="groups", value='["player_camera"]')` | `add_to_group(&"player_camera")` in `_ready()`, or a `groups = [...]` line in the `.tscn` | `Node` has no `groups` property, and `summer_set_prop` takes only string/number/boolean — never an array |
+| `summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Player/Camera3D", key="groups", value='["player_camera"]')` | `add_to_group(&"player_camera")` in `_ready()`, or a `groups = [...]` line in the `.tscn` | `Node` has no `groups` property, and `summer_set_prop` takes only string/number/boolean — never an array |
 | `BaseMaterial3D.new()` | `StandardMaterial3D.new()` | `BaseMaterial3D` is abstract; constructing it is a parse error that kills the whole script |
 
 ## Collaborative protocol
 
-This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `../../references/collaborative-protocol/collaborative-protocol.md`.
+This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `summer_docs_read` id `reference/collaborative-protocol`.
 
 ## When NOT to use this skill
 
@@ -386,11 +386,37 @@ This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always as
 
 ## See also
 
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full MCP tool list, especially `summer_set_resource_property` on inline sub_resources and which failures are loud vs. silent
-- `../../references/godot-version/godot-version.md` — Summer compatibility and
+- `summer_docs_read` id `reference/mcp-tools-reference` — full MCP tool list, especially `summer_set_resource_property` on inline sub_resources and which failures are loud vs. silent
+- `summer_docs_read` id `reference/godot-version` — Summer compatibility and
   version-sensitive API notes
-- `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
-- `../../references/gd-style/gd-style.md` — typed GDScript conventions
+- `summer_docs_read` id `reference/collaborative-protocol` — "May I write" pattern
+- `summer_docs_read` id `reference/gd-style` — typed GDScript conventions
 - `audio-direction` — bus layout setup (prerequisite for ducking)
 - `vfx-hit-spark` — particles to layer on top of the trio
 - `debugging-game-feel` — when the trio is installed and it still feels wrong
+
+<!-- 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_connect_signal` | `summer engine connect-signal` |
+| `summer_get_debugger_errors` | `summer engine get-debugger-errors` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `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_project_setting` | `summer engine project-setting` |
+| `summer_read_file` | `summer engine read-file` |
+| `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/game-feel/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/game-feel
 kind: skill
 version: 1.0.2
-summary: "Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact."
+summary: "Add juice: hit-flash, trauma camera shake and audio ducking, one hit fires all three."
 use_when:
   - a Summer game feels flat, lacks impact, needs juice or punch
   - the user asks for hit feedback, screen shake, camera shake, or audio ducking

package/library/skills/gameskill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gameskill
-description: "Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter."
+description: "Capture what a game-dev session learned as a reusable skill (project, user or Summer library) for next time."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: workflow
@@ -17,7 +17,7 @@ Summer resolves skills in this order: the game project, then the user's agent sk
 
 1. **The game project** (default). Write `SKILL.md` into the project-scoped skills directory of the agent you are running in: `.claude/skills/<slug>/` for Claude Code, `.agents/skills/<slug>/` for Codex, Cursor, Devin Desktop and the other agents that read the shared folder. `summer skills install --scope project` shows the exact path for the current agent. Commit it with the game.
 2. **The user's agent skills directory** when the lesson applies to every project on this machine (`~/.claude/skills/<slug>/`, `~/.agents/skills/<slug>/`). Do not edit skills that Summer installed there; they are overwritten on the next `summer setup`.
-3. **The Summer library** when the lesson is general enough for every Summer user. Only possible inside a checkout of the `summerengine/summer` repository: add `library/skills/<slug>/resource.yaml` and `library/skills/<slug>/SKILL.md` (flat slugs, no category folders), then run `npm run generate:registry` and `npm run validate:library`. Everything under `registry/generated/` and every plugin manifest is generated from `library/`; never hand-edit them. Outside that checkout, send the lesson through `summer_library_feedback` (or `summer tool library-feedback`) with the id of the closest existing skill so the maintainers can fold it in.
+3. **The Summer library** when the lesson is general enough for every Summer user. Only possible inside a checkout of the `summerengine/summer` repository: add `library/skills/<slug>/resource.yaml` and `library/skills/<slug>/SKILL.md` (flat slugs, no category folders), then run `npm run generate:registry` and `npm run validate:library`. Everything under `registry/generated/` and every plugin manifest is generated from `library/`; never hand-edit them. Outside that checkout, send the lesson through `summer_call` `{"op":"docs.feedback"}` (or `summer tool library-feedback`) with the id of the closest existing skill so the maintainers can fold it in.
 
 Read the current project as ground truth. Working code from the real project beats invented examples.
 
@@ -25,7 +25,7 @@ Read the current project as ground truth. Working code from the real project bea
 
 1. One short sentence to the user: "Capturing learnings from this session into a skill." No plan dump.
 
-2. Probe. Check which skills directories exist for this agent and project, and search the bundled library first (`summer_search_library "<topic>"`, or `summer skills list`) so you extend an existing skill instead of duplicating it.
+2. Probe. Check which skills directories exist for this agent and project, and search the bundled library first (`summer_docs_search "<topic>"`, or `summer skills list`) so you extend an existing skill instead of duplicating it.
 
 3. Recap the session. Pull out learnings that are non-obvious AND general, things a future agent could not derive from reading the codebase. Examples that count:
    - A working shader (the actual code)
@@ -36,7 +36,7 @@ Read the current project as ground truth. Working code from the real project bea
    - A spawning, AI or enemy pattern that worked
    - A performance fix with measured before and after
    - An asset workflow that beat the alternatives
-   - A Summer tool that steered you wrong: report that with `summer_library_feedback` on the tool's id, in addition to any skill
+   - A Summer tool that steered you wrong: report that with `summer_call` `{"op":"docs.feedback"}` on the tool's id, in addition to any skill
 
    Examples that do NOT count: one-off code with no general lesson, things already documented in an existing skill or the project's agent instructions, personal preferences without reasoning, anything manufactured to fill space.
 
@@ -62,3 +62,14 @@ Read the current project as ground truth. Working code from the real project bea
 ## When there is nothing worth capturing
 
 Say so: "session was tactical, no durable learnings worth a skill." Better to ship nothing than to ship noise.
+
+<!-- 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_docs_search` | `summer docs search` |
+<!-- /shell-commands -->

package/library/skills/gameskill/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/gameskill
 kind: skill
 version: 1.0.2
-summary: Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter.
+summary: "Capture what a game-dev session learned as a reusable skill (project, user or Summer library) for next time."
 use_when:
   - finishing a game-development session with learnings worth capturing as a reusable skill
   - a session found a technique, workaround, or convention worth reusing across Summer sessions

package/library/skills/gdscript-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdscript-patterns
-description: "GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming."
+description: "GDScript conventions: type hints, signals, exports, onready, lifecycle methods, node paths, naming."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scripting-patterns
@@ -148,3 +148,18 @@ Note the field name difference too: `LabelSettings.outline_color` (Label 2D) vs
 When the AI adds a node with Summer MCP tools and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist first. Create it with guarded `summer_write_file` or edit it with `summer_replace_text`, then attach the script and connect scene signals.
 
 For signal connections, the receiver must have the handler method. Create the script with the method stub before calling `summer_connect_signal`.
+
+<!-- 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_connect_signal` | `summer engine connect-signal` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_input_map_bind` | `summer engine input-map-bind` |
+| `summer_replace_text` | `summer engine replace-text` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/gdscript-patterns/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/gdscript-patterns
 kind: skill
 version: 1.0.3
-summary: GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming.
+summary: "GDScript conventions: type hints, signals, exports, onready, lifecycle methods, node paths, naming."
 use_when:
   - writing or refactoring GDScript — type hints, signals, exports, onready, lifecycle methods, naming conventions
   - reviewing GDScript for idiomatic signals, exports, @onready usage, node references, and naming