summer-engine 2.7.0 → 2.8.0

package/skills/audio/sound-effect/SKILL.md

@@ -49,7 +49,7 @@ The bible defines an SFX *class* (UI, Pickup positive, Damage, Footstep, Attack,
 Generation is metered. Reuse beats regenerate.
 
 ```
-summer_search_assets(query="<class> <subject>", filter={ kind: "audio" })
+summer_search_assets(query="<class> <subject>", assetType="audio", source="all")
 ```
 
 If something fits, ask:
@@ -93,18 +93,21 @@ Show the prompt and the call before running:
 
 > Prompt: `metal sword swing whoosh, dry, sharp, 250ms`. Duration 0.5s (model floor). Model: ElevenLabs SFX. Cost: ~1 credit. Generate?
 
+The `sound_effects` capability reads the description from **`text`**, not `prompt`. Passing `prompt` here is a 400 `text_required` — `prompt` is only for the `music` capability.
+
 ```
 summer_generate_audio(
   capability: "sound_effects",
-  prompt: "metal sword swing whoosh, dry, sharp, 250ms",
+  text: "metal sword swing whoosh, dry, sharp, 250ms",
   durationSeconds: 0.5
 )
-// Result: { asset: { fileUrl, ... } }
 // Then: summer_import_from_url(url: "<fileUrl>", path: "res://audio/sfx/sword_swing_01.wav")
 ```
 
 `durationSeconds` floor is 0.5, ceiling is 22. If the user wants a 100ms click, generate 0.5s and the player only plays the front; or trim in the engine.
 
+SFX comes back as **WAV**, not MP3 — Summer requests raw PCM from the provider, trims the model's lead-in silence, applies short anti-click fades, and emits a 16-bit mono WAV. A `.wav` target path is therefore correct, and the usual "ElevenLabs one-shots start with dead air" problem is already handled upstream.
+
 ### 5. Decision: one-shot vs loop
 
 | Use case | Setup |
@@ -126,13 +129,15 @@ Choose the right player node:
 
 Add it under the emitting node:
 
+Every scene-mutating tool takes an explicit `scenePath`, node paths are relative to the scene root (`./`), and the property argument is named `key`, not `property`:
+
 ```
-summer_add_node(parentPath="/root/Game/Player", type="AudioStreamPlayer3D", name="SwingSFX")
-summer_set_prop(path="/root/Game/Player/SwingSFX", property="stream", value="res://audio/sfx/sword_swing_01.wav")
-summer_set_prop(path="/root/Game/Player/SwingSFX", property="bus", value="SFX")
-summer_set_prop(path="/root/Game/Player/SwingSFX", property="volume_db", value=0.0)
-summer_set_prop(path="/root/Game/Player/SwingSFX", property="max_distance", value=25.0)
-summer_set_prop(path="/root/Game/Player/SwingSFX", property="attenuation_model", value=0)
+summer_add_node(scenePath="res://main.tscn", parent="./Player", type="AudioStreamPlayer3D", name="SwingSFX")
+summer_set_prop(scenePath="res://main.tscn", path="./Player/SwingSFX", key="stream", value="res://audio/sfx/sword_swing_01.wav")
+summer_set_prop(scenePath="res://main.tscn", path="./Player/SwingSFX", key="bus", value="SFX")
+summer_set_prop(scenePath="res://main.tscn", path="./Player/SwingSFX", key="volume_db", value=0.0)
+summer_set_prop(scenePath="res://main.tscn", path="./Player/SwingSFX", key="max_distance", value=25.0)
+summer_set_prop(scenePath="res://main.tscn", path="./Player/SwingSFX", key="attenuation_model", value=0)
 ```
 
 Bus name must match the bible (`SFX`, `UI`, `Ambient`, etc.). If the bus doesn't exist, run `/audio-direction` step 8.
@@ -150,7 +155,7 @@ func _ready() -> void:
 	play()
 ```
 
-Save it as a `.tscn`, then `summer_instantiate_scene` at the emitter's global position when the event fires. The node frees itself when the stream finishes — no leaks.
+Save it as a `.tscn`, then `summer_instantiate_scene(scenePath, parent, scene, name)` to place it. Note this only wires the node into a scene at author time — spawning one per event at the emitter's runtime position is a job for GDScript (`preload(...).instantiate()` + `add_child`), not for an MCP call. The node frees itself when the stream finishes — no leaks.
 
 ### 8. Volume calibration
 
@@ -233,5 +238,5 @@ After the SFX is wired:
 - `audio/ambient-bed` — long looping textures
 - `audio/music-track` — music
 - `audio/voice-line` — TTS
-- `references/mcp-tools-reference.md`
-- `references/godot-version.md` — Godot 4.5 audio nodes
+- `../../../references/mcp-tools-reference.md`
+- `../../../references/godot-version.md` — Summer compatibility for audio nodes

package/skills/audio/voice-line/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: voice-line
-description: Use when generating TTS voice lines — NPC barks, narrator, dialogue. Includes voice-id discovery via summer_list_models family:'audio-voice', a character-to-voice decision tree, stability/style/similarity guidance, and the multi-line dialogue case via text_to_dialogue. Trigger on "make a voice line", "narrator", "NPC says", "voice for the merchant", "TTS line", "dialogue".
+description: Use when generating TTS voice lines — NPC barks, narrator, dialogue. Covers where voice ids come from, a character-to-voice decision tree, stability/style/similarity guidance, and the multi-line dialogue case via text_to_dialogue. Trigger on "make a voice line", "narrator", "NPC says", "voice for the merchant", "TTS line", "dialogue".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_voice summer_generate_audio summer_list_models summer_search_assets summer_import_from_url summer_add_node summer_set_prop summer_inspect_node
+allowed-tools: Read Grep Glob Write Edit summer_generate_audio summer_search_assets summer_import_from_url summer_add_node summer_set_prop summer_inspect_node
 paths: [".summer/**", "audio/voice/**", "scripts/**", "**/*.tscn"]
 ---
 
@@ -13,7 +13,7 @@ paths: [".summer/**", "audio/voice/**", "scripts/**", "**/*.tscn"]
 
 ## Overview
 
-The hardest part of TTS isn't the line — it's picking the right voice. ElevenLabs ships hundreds; pick wrong and a tough warlord NPC sounds like a podcast host. This skill walks the voice-id discovery flow (`summer_list_models` family `audio-voice`), narrows by gender / accent / age / energy, presents 4–5 finalists with sample URLs for the user to audition, and locks the pick before generating.
+The hardest part of TTS isn't the line — it's picking the right voice. ElevenLabs ships hundreds; pick wrong and a tough warlord NPC sounds like a podcast host. **There is no MCP tool that lists voices** — the only voice-related input Summer exposes is the `voiceId` string on `summer_generate_audio`. So the voice pick has to come from the user (or from the project's cast bible), and this skill's job is to get that pick made deliberately and then locked.
 
 Then it generates one line (or a multi-turn dialogue) with the right stability / style / similarity / speed for the delivery — flat for narration, expressive for a bark, fast for an excited shout.
 
@@ -44,24 +44,21 @@ If a character bible exists, the voice should match the character's age / gender
 
 > Tell me the character: gender, rough age, accent or regional flavor, and energy (calm / measured / excited / gruff). Or just give me a reference — "sounds like the captain in Mass Effect" works.
 
-### 2. Browse the voice catalog
+### 2. Get the voice id
 
-```
-summer_list_models(family="audio-voice")
-```
+Check the cast bible first (step 1). If the character already has a locked id, use it and skip to step 5.
 
-Returns a list with `id`, `name`, `accent`, `gender`, `age`, `description`, and `previewUrl`. Filter mentally to 8–12 candidates by the character's hard constraints (gender + age + accent), then pick 4–5 finalists with maximally distinct character (gruff vs warm vs neutral vs theatrical).
+If not, you need a `voiceId` from the user. There is no catalog tool and no preview-URL endpoint on this surface — do not invent one, and do not claim you auditioned anything. Ask:
 
-Present them to the user like this:
+> I need an ElevenLabs voice id for `<character>`. Two ways to get one:
+> - Browse and audition at `elevenlabs.io/app/voice-library` (or your Voices page) and paste me the voice id.
+> - Or say "use the default" and I'll generate with Summer's default voice so you can hear the line, then we swap the id later.
+>
+> Describe the target if it helps me sanity-check the pick: gender, rough age, accent, and energy (calm / measured / excited / gruff).
 
-> Four finalists for "old gruff dwarven warlord":
-> 1. **Brogan** — male, 50s, rough Scottish, gravelly. Sample: `<previewUrl>`
-> 2. **Hodge** — male, 60s, neutral, weathered baritone. Sample: `<previewUrl>`
-> 3. **Marrick** — male, 40s, rough English, mid-energy. Sample: `<previewUrl>`
-> 4. **Old Drum** — male, 70s, deep, slow speech. Sample: `<previewUrl>`
-> Audition and pick one. Or ask for four more.
+Omitting `voiceId` entirely is valid — `summer_generate_audio` falls back to a single default voice (`JBFqnCBsd6RMkjVDRZzb`). That is fine for a throwaway read-through, never for a shipped cast.
 
-Wait for the user. Do not pick for them — voice is the highest-stakes audio decision in the project.
+Voice is the highest-stakes audio decision in the project. Do not pick an id for the user and do not guess ids — a wrong id is a hard provider error, not a different-sounding voice.
 
 ### 3. Character-to-voice decision tree (when the user wants a recommendation)
 
@@ -117,18 +114,18 @@ If legacy `.summer/voice-cast.md` already exists, read it first and either keep
 
 ### 5. Tune stability / similarity / style / speed for delivery
 
-ElevenLabs voice options:
+These are **not** top-level tool arguments. They go inside `options.voiceSettings`, in camelCase, exactly as the ElevenLabs SDK's `VoiceSettings` type spells them — `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`. `options` is spread straight into the SDK call, so a flat `similarity_boost` at the top of `options` is silently dropped.
 
 | Param | Range | Effect |
 |---|---|---|
 | `stability` | 0.0–1.0 | Higher = monotone, consistent. Lower = expressive, variable. |
-| `similarity_boost` | 0.0–1.0 | Higher = closer to the original sample. Lower = more freedom (can drift). |
+| `similarityBoost` | 0.0–1.0 | Higher = closer to the original sample. Lower = more freedom (can drift). |
 | `style` | 0.0–1.0 | Higher = more theatrical / exaggerated. 0 = neutral. |
 | `speed` | 0.7–1.2 | Speech speed multiplier. |
 
 Defaults that work as a starting point:
 
-| Delivery | stability | similarity_boost | style | speed |
+| Delivery | stability | similarityBoost | style | speed |
 |---|---|---|---|---|
 | Calm narration | 0.75 | 0.75 | 0.0 | 1.0 |
 | Cinematic narration | 0.5 | 0.85 | 0.4 | 0.95 |
@@ -166,50 +163,52 @@ Example lines:
 ### 7. Confirm and call
 
 ```
-summer_generate_voice(
+summer_generate_audio(
+  capability="text_to_speech",
   text="Hold the line. They're coming through the south gate. Ready arrows.",
   voiceId="21m00Tcm4TlvDq8ikWAM",
   modelId="eleven_multilingual_v2",
-  stability=0.6,
-  similarity_boost=0.75,
-  style=0.2,
-  speed=1.0,
-  outputPath="audio/voice/hodge_hold_the_line.mp3"
+  options={ voiceSettings: { stability: 0.6, similarityBoost: 0.75, style: 0.2, speed: 1.0 } }
 )
 ```
 
 `modelId` defaults to `eleven_multilingual_v2`. For very short / latency-sensitive in-game barks, `eleven_turbo_v2_5` is faster; for highest fidelity, `eleven_multilingual_v2` is the default.
 
+There is no `outputPath` — the tool returns a hosted asset (MP3, `audio/mpeg`). Land it in the project explicitly:
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://audio/voice/hodge_hold_the_line.mp3")
+```
+
 ### 8. Multi-line dialogue (two or more speakers)
 
 Use `summer_generate_audio` with `capability: "text_to_dialogue"`:
 
+There is no `speakers` roster and no `script` array. The whole conversation is one flat `inputs` array of `{ text, voiceId }` objects, in turn order — the voice id is repeated on every line:
+
 ```
 summer_generate_audio(
   capability="text_to_dialogue",
-  speakers=[
-    { name: "Hodge",   voiceId: "21m00Tcm4TlvDq8ikWAM" },
-    { name: "Brogan",  voiceId: "<brogan-id>" }
-  ],
-  script=[
-    { speaker: "Hodge",  text: "They're at the gate." },
-    { speaker: "Brogan", text: "Aye. Let 'em come." },
-    { speaker: "Hodge",  text: "Steady. On my mark." }
-  ],
-  outputPath="audio/voice/dialogue_gate_warning.mp3"
+  inputs=[
+    { text: "They're at the gate.",   voiceId: "21m00Tcm4TlvDq8ikWAM" },
+    { text: "Aye. Let 'em come.",     voiceId: "<brogan-id>" },
+    { text: "Steady. On my mark.",    voiceId: "21m00Tcm4TlvDq8ikWAM" }
+  ]
 )
 ```
 
-This produces a single MP3 with both voices, with dialogue-aware pacing the model handles internally. For very long scripts, split into chunks of ~6 turns and concatenate.
+`inputs` is required for this capability; omitting it is a 400 `inputs_required`. `modelId` defaults to `eleven_v3` here, not `eleven_multilingual_v2`. The result is a single MP3 with both voices and dialogue-aware pacing the model handles internally — import it with `summer_import_from_url` like any other clip. For very long scripts, split into chunks of ~6 turns and concatenate.
 
 ### 9. Wire the line as `AudioStreamPlayer` on the Voice bus
 
+Every scene-mutating tool takes an explicit `scenePath`, node paths are relative to the scene root (`./`), and the property argument is named `key`, not `property`:
+
 ```
-summer_add_node(parentPath="/root/Game/NPC", type="AudioStreamPlayer", name="VoiceLine")
-summer_set_prop(path="/root/Game/NPC/VoiceLine", property="stream", value="res://audio/voice/hodge_hold_the_line.mp3")
-summer_set_prop(path="/root/Game/NPC/VoiceLine", property="bus", value="Voice")
-summer_set_prop(path="/root/Game/NPC/VoiceLine", property="volume_db", value=0.0)
-summer_set_prop(path="/root/Game/NPC/VoiceLine", property="autoplay", value=false)
+summer_add_node(scenePath="res://main.tscn", parent="./NPC", type="AudioStreamPlayer", name="VoiceLine")
+summer_set_prop(scenePath="res://main.tscn", path="./NPC/VoiceLine", key="stream", value="res://audio/voice/hodge_hold_the_line.mp3")
+summer_set_prop(scenePath="res://main.tscn", path="./NPC/VoiceLine", key="bus", value="Voice")
+summer_set_prop(scenePath="res://main.tscn", path="./NPC/VoiceLine", key="volume_db", value=0.0)
+summer_set_prop(scenePath="res://main.tscn", path="./NPC/VoiceLine", key="autoplay", value=false)
 ```
 
 For positional NPCs, `AudioStreamPlayer3D` with `max_distance=15.0` so distant NPCs aren't audible.
@@ -239,7 +238,8 @@ Narrator intimate:        warmer mid pitch, lower stability for breath
 
 ## Anti-patterns
 
-- **Picking a voice without auditioning samples.** The user must hear it.
+- **Inventing a voice catalog.** There is no `summer_list_models`, no voice-listing tool, and no preview URLs on this surface. Ask the user for the id.
+- **Guessing a voice id.** A wrong id is a provider error, not a different voice.
 - **Reusing a voice id across two characters.** Players notice instantly. Lock the cast.
 - **Changing a locked voice without approval.** A cast voice is project memory, not a throwaway generation option.
 - **Stage directions in the text.** `(angrily) Get out!` is read literally as "angrily get out". Use stability/style.

package/skills/character-controllers/fps-controller/SKILL.md

@@ -35,27 +35,40 @@ Always call `summer_get_scene_tree` before mutating. If `World/Player`, `World/P
 ### 2. Add the Player root
 
 ```
-summer_add_node(parent="./World", type="CharacterBody3D", name="Player")
-summer_set_prop(path="./World/Player", key="position", value="Vector3(0, 1, 0)")
+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 (standalone resource, NOT inline)
+### 3. Add the collision shape and size it
 
 ```
-summer_add_node(parent="./World/Player", type="CollisionShape3D", name="Collision")
-summer_set_prop(path="./World/Player/Collision", key="shape", value="CapsuleShape3D")
-summer_set_resource_property(nodePath="./World/Player/Collision", resourceProperty="shape", subProperty="radius", value="0.4")
-summer_set_resource_property(nodePath="./World/Player/Collision", resourceProperty="shape", subProperty="height", value="1.8")
+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_set_prop` with a class-name string creates a standalone sub-resource. NEVER call `summer_set_resource_property` against an inline `sub_resource` — the value is silently dropped. See `references/mcp-tools-reference.md`.
+Two things the older version of this skill got wrong:
+
+- **`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. The op has no silent-drop
+  branch: the only failures are explicit — `node not found`, `property is not a
+  resource`, or `resource is null` when the property was never assigned. Assign
+  the resource first, then set its sub-properties.
 
 ### 4. Add the Head pivot + Camera
 
 ```
-summer_add_node(parent="./World/Player", type="Node3D", name="Head")
-summer_set_prop(path="./World/Player/Head", key="position", value="Vector3(0, 1.6, 0)")
-summer_add_node(parent="./World/Player/Head", type="Camera3D", name="Camera")
+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")
 ```
 
 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.
@@ -73,7 +86,7 @@ summer_input_map_bind(name="sprint",       events=[{type:"key", key:"Shift"}])
 
 ### 6. 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` + `summer_get_script_errors`.
+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`).
 
 ## Physics-Process Flow (the order matters)
 
@@ -328,14 +341,11 @@ Then patch `project.godot` with the InputMap actions (`input/move_forward = { ..
 
 ## Collaborative Protocol
 
-This skill writes scene nodes, an InputMap, and a `.gd` script. Always ask before applying. Group writes per phase: "May I add the Player + Collision + Head + Camera, bind WASD/jump/sprint, and attach `player_controller.gd`?" See `../../references/collaborative-protocol.md`.
+This skill writes scene nodes, an InputMap, and a `.gd` script. Always ask before applying. Group writes per phase: "May I add the Player + Collision + Head + Camera, bind WASD/jump/sprint, and attach `player_controller.gd`?"
 
 If the user asks for a "third-person FPS", flag the contradiction: FPS = first-person. Either clarify, or hand off to the `tps-controller` skill when it ships.
 
 ## See Also
 
-- `references/gd-style.md` — typed GDScript conventions used in the skeleton.
-- `references/mcp-tools-reference.md` — `summer_set_resource_property` rules + the inline-sub-resource silent-fail trap.
-- `references/collaborative-protocol.md` — when to ask before writing.
 - `scripting-patterns/state-machine-patterns/SKILL.md` — once movement grows past this skeleton (slide, grapple, hover), refactor into a state machine instead of stuffing more branches into `_physics_process`.
 - `physics/character-body-tuning/SKILL.md` (when shipped) — slope handling, step-up, floor-snap.

package/skills/debugging/debug/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: debug
-description: Use when the user reports a bug, crash, error, or unexpected behavior in a Godot/Summer project, before making any code or scene changes — runs a disciplined script-errors → console → debugger → hypothesis → fix → verify loop. Trigger on "debug", "crash", "error", "broken", "not working", "freezes", "wrong".
+description: Use when the user reports a bug, crash, error, or unexpected behavior in a Summer project, before making code or scene changes. Runs a disciplined script-errors, console, debugger, hypothesis, fix, and verify loop. Trigger on "debug", "crash", "error", "broken", "not working", "freezes", "wrong".
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: debugging
 user-invocable: true
-allowed-tools: Read Edit Grep summer_create_debug_report summer_get_diagnostics summer_get_script_errors summer_get_console summer_clear_console summer_get_debugger_errors summer_play summer_stop summer_is_running summer_inspect_node summer_inspect_resource summer_get_scene_tree
+allowed-tools: Read Edit Grep summer_create_debug_report summer_get_diagnostics summer_get_script_errors summer_get_console summer_clear_console summer_get_debugger_errors summer_get_debugger_warnings summer_play summer_stop summer_is_running summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_screenshot summer_batch
 paths: ["**/*.gd", "**/*.cs", "**/*.tscn", "**/*.tres", "project.godot"]
 ---
 
 # /debug — Triage and Fix a Bug End-to-End
 
-The disciplined debugging loop for Godot/Summer projects. Read the error before guessing. Form a hypothesis before editing. Verify the fix before declaring victory. Never grep the codebase before reading the actual error.
+The disciplined debugging loop for Summer projects. Read the error before
+guessing. Form a hypothesis before editing. Verify the fix before declaring
+victory. Never grep the codebase before reading the actual error.
 
 **Core principle:** The debugger already knows what's wrong. Your job is to listen to it before doing anything else.
 
@@ -76,29 +78,37 @@ In strict order. Stop at the first one that returns useful signal.
 | 2 | `summer_get_diagnostics` | Aggregate console + debugger error counts. One call, broad picture. |
 | 3 | `summer_get_console` | Read the editor Output panel — print statements, warnings, errors that didn't crash. |
 | 4 | `summer_get_debugger_errors` | Runtime errors caught by the debugger. Use AFTER `summer_play` for runtime-only bugs. |
+| 5 | `summer_get_debugger_warnings` | Warning bodies (file/line/function/callstack). Use when diagnostics reports a non-zero `debugger.warnings`. |
 
 **If `summer_get_script_errors` is clean and the user says it crashes only when running:** it's a runtime bug. Go to step 2b.
 
 ### 2b. Runtime-only bugs
 
+**Reproduce it yourself first.** Write a `RunVerification` probe that performs the repro steps (`press` / `key`), reports the state you expect to be wrong, and saves a frame. See "Drive the game yourself" below for the exact call. The returned `results.errors_seen` and `reports` are the diagnostic. This costs one call, touches nothing the user owns, and gives you a repro you can re-run after the fix.
+
+Fall back to the editor session only when the repro genuinely needs a human (feel, hardware, "is this what you meant?"):
+
 ```
   summer_clear_console
   summer_play
   ─▶ ASK USER: "Reproduce the bug now."
   (wait for confirmation)
   summer_get_debugger_errors
+  summer_get_debugger_warnings   (if diagnostics showed warnings)
   summer_stop
 ```
 
-Do not skip the "reproduce now" prompt. Auto-running and grabbing whatever's in the buffer leads you to chase ghosts from previous sessions.
+If you go this route, do not skip the "reproduce now" prompt. Auto-running and grabbing whatever's in the buffer leads you to chase ghosts from previous sessions.
 
 ### 2c. MCP unavailable (engine not running, or no Summer install)
 
 If `summer_get_script_errors` returns "Summer Engine is not running" or the tool isn't available:
 
-1. Ask the user to copy-paste the Output panel and the Debugger panel from the Godot editor.
-2. Reason over the pasted text exactly as you would over MCP output.
-3. Continue with the rest of the loop unchanged.
+1. Tell the user `summer run` starts it. One command restores every tool in this loop — try that before degrading to an interview.
+2. If they cannot or will not, ask the user to copy-paste the Output panel and
+   the Debugger panel from Summer Engine.
+3. Reason over the pasted text exactly as you would over MCP output.
+4. Continue with the rest of the loop unchanged.
 
 Do NOT loop on MCP retry. Do NOT pretend the engine will come back. Use the fallback the moment it fails once.
 
@@ -133,7 +143,7 @@ Surface the proposed fix in plain language and ask permission. Two patterns:
 
 - For GDScript edits: `Read` the 20–40 lines around the error, `Edit` the exact change. Don't read the whole file. Don't reformat. Don't rename other things.
 - For scene edits: use the appropriate `summer_*` tool (`summer_add_node`, `summer_set_prop`, `summer_replace_node`). Group multi-step changes in `summer_batch` for one undo step.
-- **Trap to avoid:** never call `summer_set_resource_property` against an inline `sub_resource` — the value is silently dropped. If the property is on a nested resource, first call `summer_set_prop` with the resource class name to instantiate a standalone resource, then drill in. See `references/mcp-tools-reference.md`.
+- **Trap to avoid:** never call `summer_set_resource_property` against an inline `sub_resource` — the value is silently dropped. If the property is on a nested resource, first call `summer_set_prop` with the resource class name to instantiate a standalone resource, then drill in. See `../../../references/mcp-tools-reference.md`.
 
 ### 6. Verify — re-run the diagnostic that found it
 
@@ -158,7 +168,7 @@ If the diagnostic is still red after the fix, you formed the wrong hypothesis. G
 | Auto-fix linter warnings unrelated to the bug | Same reason. |
 | Declare victory after editing | Re-run the diagnostic. Always. |
 
-## Quick reference — common Godot bug families
+## Quick reference — common Summer Engine bug families
 
 | Symptom | First tool | Common cause |
 |---|---|---|
@@ -180,24 +190,45 @@ Tell the user one short sentence: "Fixed `<file>:<line>` — `<change>`. Diagnos
 
 ## What the MCP debug tools CAN and CAN'T see (read this before claiming "clean")
 
-The `summer_*` tools are powerful for static + boot-time issues but **can't substitute for play-testing**. Knowing the gaps prevents false-clean reports.
+The static and boot-time tools (`summer_get_script_errors`, `summer_get_console`, `summer_get_diagnostics`) **can't substitute for play-testing** — but you have a play-testing route, so a false-clean report is a choice, not a limitation. Know which tool answers which question.
 
 ### What the MCP CAN see
 
 - **Script parse errors** (`summer_get_script_errors`) — full text + file:line. Reliable.
 - **Editor console output** (`summer_get_console`) — `print` statements, editor-side warnings, std startup messages. Full text.
 - **Runtime debugger error count + full text** (`summer_get_debugger_errors`) — returns `errors_data` with `error`, `error_descr`, `callstack`, `file`, `function`, `line`. Reliable for errors.
-- **Diagnostics summary** (`summer_get_diagnostics`) — counts of console errors, debugger errors, debugger warnings, script errors. Tells you where to drill.
+- **Runtime debugger warning text** (`summer_get_debugger_warnings`) — same structured shape as the errors tool, filtered to severity `warning`. Use it whenever `summer_get_diagnostics` shows a non-zero `debugger.warnings`; do not report a warning count you never read.
+- **Diagnostics summary** (`summer_get_diagnostics`) — counts of console errors, debugger errors, debugger warnings, script errors. Tells you where to drill. **Counts only** — it carries no FPS, frame time, draw calls, or physics-body numbers.
 - **Scene tree + node properties** (`summer_get_scene_tree`, `summer_inspect_node`) — only the **edited** scene, not the running game's live tree.
+- **Rendered pixels** (`summer_screenshot`) — `target:"viewport"` for the editor's current view, `target:"scene"` for an offscreen render of a scene file, `target:"game"` for a frame of the running game (that one needs the Summer desktop app bridge and fails cleanly over a plain local connection). You look at the actual image, not a description of it.
+- **Gameplay behaviour, driven by you** (`RunVerification` via `summer_batch`) — see the next section. Input, live tree, and frames from a real running instance.
 - **Whether the game is running** (`summer_is_running`) — and on which scene.
 
-### What the MCP CAN'T see (right now)
+### Drive the game yourself — `RunVerification`
+
+For any bug that only fires from gameplay (movement, weapon firing, level transitions, button clicks), do **not** hand the repro to the user first. Spawn a hidden, disposable game instance that runs a GDScript probe and dies. It never touches the user's editor session.
+
+```
+summer_batch ops:[{
+  "op": "RunVerification",
+  "probe_source": "extends SummerProbeBase\nfunc _ready() -> void:\n\tawait super._ready()\n\tawait get_tree().process_frame\n\tvar p := get_tree().root.find_child(\"Player\", true, false)\n\treport(\"y0\", p.global_position.y)\n\tawait press(\"jump\", 120)\n\tawait get_tree().create_timer(0.4).timeout\n\treport(\"y1\", p.global_position.y)\n\tsave_frame(\"after\")\n\tdump_tree()\n\tfinish()",
+  "max_seconds": 20
+}]
+```
+
+Probe API: `report(key, value)`, `save_frame(name)`, `dump_tree(max_depth)`, `press(action, hold_ms)`, `key(keycode, hold_ms)`, `finish()`. Returns `{ok, results, frames, out_dir}`; `results.errors_seen` carries error-level engine/script messages from that run, so a probe is also a clean way to catch a runtime error without polluting the editor's debugger buffer.
+
+This covers what static diagnostics cannot: pressed input, live scene tree (`dump_tree` reads the *running* tree, unlike `summer_get_scene_tree`), state sampled over several frames, and real rendered frames.
+
+`summer_batch` forwards unknown ops verbatim, which is how you reach `RunVerification` with no dedicated tool. Note that the sibling `SimulateInput` op is **not** reachable this way — non-bridge callers get `{ok:false, failure_reason:"unsupported_transport"}`; it only works from the in-editor chat bridge. Drive input with `press()` / `key()` inside a probe instead.
+
+### What still genuinely needs the user
+
+- **Whether it feels right.** Frame counts and reports cannot tell you the jump feels floaty. See `summer:debugging-game-feel`.
+- **Hardware-specific and non-deterministic behaviour.** A bug that only fires on their GPU, their controller, or one run in twenty.
+- **A judgement call on intent.** "Is this the behaviour you wanted?" is a question, not a measurement.
 
-- **Debugger warning text.** `summer_get_debugger_errors` returns a `warnings: <count>` integer but no `warnings_data` array. You see "the game has 66 warnings" but you can't read them through MCP. **Tell the user: "I see N warnings exist but the MCP doesn't expose their text — paste the Debugger panel if any feel relevant."**
-- **Live runtime scene tree.** `summer_get_scene_tree` returns the editor's edited scene, not what's currently instantiated in the running game. When debugging runtime state, you can't introspect the live nodes.
-- **Keyboard / mouse / controller input simulation.** No tool sends key presses or mouse motion. So bugs that only fire from gameplay (player movement, weapon firing, level transitions, button clicks) require the user to play.
-- **Screenshot / visual diff.** No tool captures the rendered viewport. Visual regressions ("the floor looks wrong", "the camera clips through terrain") require user eyes.
-- **Frame-by-frame physics state.** No tool steps the simulation or watches for transient errors over time.
+Everything else — press the button, read the state, look at the frame — is yours to do.
 
 ### The "static-only is not testing" rule
 
@@ -207,11 +238,12 @@ When you've made code changes and want to declare them "verified":
 
 1. **Required**: `summer_get_script_errors` clean on every modified file.
 2. **Required**: `summer_play` boot returns 0 errors (use the scene most likely to exercise the change).
-3. **Recommended**: ask the user to play through the specific scenario the change touches, then re-run `summer_get_diagnostics`.
-4. **Never claim "verified" from static analysis alone.** Say "compiles and boots clean — needs play-test to confirm <specific behavior>."
+3. **Required**: exercise the specific scenario the change touches with a `RunVerification` probe — press the input, assert the state, save a frame. Quote the reports you got back.
+4. Ask the user to play only for what a probe cannot judge: feel, hardware-specific behaviour, or whether the result is what they wanted.
+5. **Never claim "verified" from static analysis alone.** Say "compiles and boots clean — needs play-test to confirm <specific behavior>."
 
 ### The cost of skipping it
 
-A typical cautionary scenario: many parallel agents write thousands of lines of game code in one batch with verification static-only. The build is "diagnostic-clean" yet the running game has telegraph meshes that render the wrong axis, parse-valid scripts that crash on first autoload because of a guard pattern that doesn't compile, projectile tracers sized so they read as straight lines instead of projectiles, transform-leaked colliders from a copied scene, and `@onready` paths that throw on every boot when the script is loaded into a sibling scene that lacks one of the referenced children. None of these surface in `summer_get_diagnostics` until the user actually plays.
+A typical cautionary scenario: many parallel agents write thousands of lines of game code in one batch with verification static-only. The build is "diagnostic-clean" yet the running game has telegraph meshes that render the wrong axis, parse-valid scripts that crash on first autoload because of a guard pattern that doesn't compile, projectile tracers sized so they read as straight lines instead of projectiles, transform-leaked colliders from a copied scene, and `@onready` paths that throw on every boot when the script is loaded into a sibling scene that lacks one of the referenced children. None of these surface in `summer_get_diagnostics` until something actually plays the game — which is exactly what a `RunVerification` probe does, and why "I had no way to test it" is not an available excuse.
 
 Static analysis is necessary but never sufficient.