summer-engine 2.3.0 → 2.5.0

package/skills/ai-and-npcs/design-npc/SKILL.md

@@ -190,7 +190,7 @@ summer_set_prop(path="./World/Enemies/Enemy/Sight", key="enabled", value="true")
 summer_set_prop(path="./World/Enemies/Enemy/Sight", key="target_position", value="Vector3(0, 0, -12)")
 ```
 
-Save the Vision sphere as standalone `.tres` (do NOT inline sub_resource — see `_shared/mcp-tools-reference.md` § "Trap"):
+Save the Vision sphere as standalone `.tres` (do NOT inline sub_resource — see `references/mcp-tools-reference.md` § "Trap"):
 
 ```
 summer_set_prop(path="./World/Enemies/Enemy/Vision/VisionShape", key="shape", value="res://shapes/vision_sphere.tres")
@@ -460,7 +460,7 @@ If the enemy doesn't aggro, common causes:
 
 ## Collaborative protocol
 
-This skill writes scenes and scripts. Always ask before each step. Group related writes into one ask. See `_shared/collaborative-protocol.md`.
+This skill writes scenes and scripts. Always ask before each step. Group related writes into one ask. See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -471,10 +471,10 @@ For a fully-rigged enemy with anim controller + loot drop:
 
 ## See also
 
-- `_shared/mcp-tools-reference.md` — full MCP tool list
-- `_shared/godot-version.md` — Godot 4.5 API notes
-- `_shared/collaborative-protocol.md` — "May I write" pattern
-- `_shared/gd-style.md` — typed GDScript conventions
+- `references/mcp-tools-reference.md` — full MCP tool list
+- `references/godot-version.md` — Godot 4.5 API notes
+- `references/collaborative-protocol.md` — "May I write" pattern
+- `references/gd-style.md` — typed GDScript conventions
 - `ai-and-npcs/state-machine-npc/SKILL.md` — FSM pattern deep dive
 - `ai-and-npcs/behavior-trees/SKILL.md` — when complexity demands a BT
 - `ai-and-npcs/perception-sight-and-hearing/SKILL.md` — sensor patterns

package/skills/animation/animation-tree/SKILL.md

@@ -256,5 +256,5 @@ Open the scene in Godot 4.5 editor, add `AnimationTree` node, set `Anim Player`
 
 - `summer:animation/generate-motion` — produce the clips this tree references.
 - `summer:animation/retarget` — share one tree across many characters.
-- `_shared/gd-style.md` — typed GDScript conventions in the controller snippets.
-- `_shared/mcp-tools-reference.md` — `summer_connect_signal` and `summer_set_resource_property` rules.
+- `references/gd-style.md` — typed GDScript conventions in the controller snippets.
+- `references/mcp-tools-reference.md` — `summer_connect_signal` and `summer_set_resource_property` rules.

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

@@ -278,5 +278,5 @@ For projects that can't use any cloud or third-party tool, Godot 4.5's `AudioStr
 - `summer:audio/generate-voice` — TTS upstream of this skill.
 - `summer:animation/animation-tree` — wire the lipsync OneShot into the character's tree.
 - `summer:animation/procedural-animation` — eye blinks, saccades, head idle.
-- `_shared/mcp-tools-reference.md` — `summer_generate_audio` schema (TTS).
+- `references/mcp-tools-reference.md` — `summer_generate_audio` schema (TTS).
 - Rhubarb Lip Sync — https://github.com/DanielSWolf/rhubarb-lip-sync (external tool; phoneme extraction).

package/skills/animation/generate-motion/SKILL.md

@@ -123,7 +123,7 @@ The user can upload to Meshy directly at meshy.ai, generate via the dashboard, d
 
 ## See also
 
-- `_shared/mcp-tools-reference.md` — `summer_generate_motion` parameter schema, error codes.
+- `references/mcp-tools-reference.md` — `summer_generate_motion` parameter schema, error codes.
 - `summer:asset-pipeline/asset-strategy` — how to get a Meshy-rigged character in the first place.
 - `summer:animation/animation-tree` — wire the generated clips into a state machine.
 - `summer:animation/retarget` — re-use one library across many characters without regenerating.

package/skills/animation/procedural-animation/SKILL.md

@@ -229,6 +229,6 @@ Add modifiers in the Godot editor under Skeleton3D, set bone names from the insp
 
 ## See also
 
-- `_shared/gd-style.md` — typed GDScript conventions in the snippets.
-- `_shared/mcp-tools-reference.md` — `summer_set_prop` enum-int conventions for axis settings.
+- `references/gd-style.md` — typed GDScript conventions in the snippets.
+- `references/mcp-tools-reference.md` — `summer_set_prop` enum-int conventions for axis settings.
 - Godot 4.5 docs: `SkeletonModifier3D`, `LookAtModifier3D`, `SkeletonIK3D`, `PhysicalBoneSimulator3D`.

package/skills/audio/adaptive-music/SKILL.md

@@ -323,4 +323,4 @@ Print the bus layout, the node tree, and the GDScript. User constructs in the Go
 - `audio/audio-direction` — defines the dynamic music plan and bus layout
 - `audio/music-track` — generates the stems
 - `audio/voice-line` — the voice bus that triggers ducking
-- `_shared/godot-version.md` — Godot 4.5 AudioServer and Tween API
+- `references/godot-version.md` — Godot 4.5 AudioServer and Tween API

package/skills/audio/audio-direction/SKILL.md

@@ -235,11 +235,11 @@ End with:
 | Pure sine "ding" for pickup | Reads as cheap mobile game. Use a major-third interval with character. |
 | Same footstep sample for all surfaces | Material-aware footsteps are 80% of the perceived audio quality. |
 | No master ceiling / true peak | Audio clips on console builds without `-1 dBTP` ceiling. Always set it. |
-| Calling SetResourceProperty on inline sub_resources | Silent fail. See `_shared/mcp-tools-reference.md` § Trap. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `references/mcp-tools-reference.md` § Trap. |
 
 ## Collaborative protocol
 
-This skill writes one bible (`.summer/audio-bible.md`), creates a bus layout (`audio/default_bus_layout.tres`), modifies `project.godot`, and may generate audio (metered). Always ask before writing or generating. See `_shared/collaborative-protocol.md`.
+This skill writes one bible (`.summer/audio-bible.md`), creates a bus layout (`audio/default_bus_layout.tres`), modifies `project.godot`, and may generate audio (metered). Always ask before writing or generating. See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -247,9 +247,9 @@ No template — this is a workflow that produces the bible the rest of the proje
 
 ## See also
 
-- `_shared/collaborative-protocol.md`
-- `_shared/godot-version.md` — Godot 4.5 audio API notes
-- `_shared/mcp-tools-reference.md`
+- `references/collaborative-protocol.md`
+- `references/godot-version.md` — Godot 4.5 audio API notes
+- `references/mcp-tools-reference.md`
 - `scene-and-project/brainstorm-game/SKILL.md` — produces the brief that anchors the bible
 - `rendering-and-lighting/art-direction/SKILL.md` — the visual counterpart; audio must rhyme with it
 - `audio/audio-bus-setup/SKILL.md` (NEXT) — implements the bus layout in detail

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

@@ -233,5 +233,5 @@ After the SFX is wired:
 - `audio/ambient-bed` — long looping textures
 - `audio/music-track` — music
 - `audio/voice-line` — TTS
-- `_shared/mcp-tools-reference.md`
-- `_shared/godot-version.md` — Godot 4.5 audio nodes
+- `references/mcp-tools-reference.md`
+- `references/godot-version.md` — Godot 4.5 audio nodes

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

@@ -6,7 +6,7 @@ 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
-paths: ["audio/voice/**", "scripts/**", "**/*.tscn"]
+paths: [".summer/**", "audio/voice/**", "scripts/**", "**/*.tscn"]
 ---
 
 # /voice-line — Generate TTS Voice for NPCs, Narrator, Dialogue
@@ -33,8 +33,11 @@ Then it generates one line (or a multi-turn dialogue) with the right stability /
 
 ```
 Read .summer/audio-bible.md
+Read .summer/memory/casting/voices.md   # preferred cast memory, if present
+Read .summer/voice-cast.md              # legacy cast memory, if present
 Read .summer/characters.md   # if present
 Glob .summer/characters/*.md
+Glob .summer/memory/characters/*.md
 ```
 
 If a character bible exists, the voice should match the character's age / gender / regional origin / energy. If it doesn't, ask:
@@ -83,9 +86,23 @@ After the pick:
 
 > Locked voice: `Hodge` (id `21m00Tcm4TlvDq8ikWAM`). I'll use this for all `<character>` lines unless you say otherwise.
 
-Save it in `.summer/voice-cast.md`:
+Ask before writing:
+
+> May I update `.summer/memory/casting/voices.md` with this locked voice assignment?
+
+Save it in `.summer/memory/casting/voices.md`:
 
 ```markdown
+---
+id: casting.voice.main-cast
+type: casting
+status: active
+priority: locked
+stable: true
+providers:
+  - elevenlabs
+---
+
 # Voice Cast
 
 | Character | Voice name | Voice id | Notes |
@@ -96,6 +113,8 @@ Save it in `.summer/voice-cast.md`:
 
 This is the cast bible. Every future voice line uses these ids — consistency is the point.
 
+If legacy `.summer/voice-cast.md` already exists, read it first and either keep using it for this project or ask to migrate it into `.summer/memory/casting/voices.md`. Do not maintain two conflicting cast files.
+
 ### 5. Tune stability / similarity / style / speed for delivery
 
 ElevenLabs voice options:
@@ -199,7 +218,9 @@ The bible's mix rule says voice ducks music: when this player starts, fade the m
 
 ### 10. Save to the cast bible
 
-After generation, append to `.summer/voice-cast.md` so future skills find existing lines and don't regenerate. Include line text + filename + voice id.
+After generation, append to `.summer/memory/casting/voices.md` so future skills find existing lines and don't regenerate. Include line text + filename + voice id.
+
+If the assignment is marked `priority: locked`, do not replace the voice id automatically. If a scene, script, import config, or user prompt conflicts with the locked memory, stop and ask whether to update memory or fix the implementation.
 
 ## Reference card — voice-pick by archetype
 
@@ -220,6 +241,7 @@ Narrator intimate:        warmer mid pitch, lower stability for breath
 
 - **Picking a voice without auditioning samples.** The user must hear it.
 - **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.
 - **One long blob for a multi-turn scene.** Use `text_to_dialogue` so pacing is dialogue-aware.
 - **Voice on `Master` bus.** Must be on `Voice` bus so it can duck music per the bible.

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

@@ -48,7 +48,7 @@ summer_set_resource_property(nodePath="./World/Player/Collision", resourceProper
 summer_set_resource_property(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 `_shared/mcp-tools-reference.md`.
+`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`.
 
 ### 4. Add the Head pivot + Camera
 
@@ -328,14 +328,14 @@ 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 `../../_shared/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`?" See `../../references/collaborative-protocol.md`.
 
 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
 
-- `_shared/gd-style.md` — typed GDScript conventions used in the skeleton.
-- `_shared/mcp-tools-reference.md` — `summer_set_resource_property` rules + the inline-sub-resource silent-fail trap.
-- `_shared/collaborative-protocol.md` — when to ask before writing.
+- `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

@@ -111,7 +111,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 `_shared/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
 
@@ -155,3 +155,41 @@ A debug session is done when:
 3. No new errors or warnings have been introduced.
 
 Tell the user one short sentence: "Fixed `<file>:<line>` — `<change>`. Diagnostic clean." Then stop.
+
+## 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.
+
+### 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.
+- **Scene tree + node properties** (`summer_get_scene_tree`, `summer_inspect_node`) — only the **edited** scene, not the running game's live tree.
+- **Whether the game is running** (`summer_is_running`) — and on which scene.
+
+### What the MCP CAN'T see (right now)
+
+- **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.
+
+### The "static-only is not testing" rule
+
+A clean `summer_get_diagnostics` after `summer_play` only proves: **the game booted without parse errors or @implicit_ready null-derefs.** It does NOT prove gameplay works. Auto-fire weapons, level transitions, spell casting, boss attacks, UI interactions all happen *after* boot and won't surface in the diagnostics until they fire.
+
+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>."
+
+### 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.
+
+Static analysis is necessary but never sufficient.

package/skills/deployment/export-and-ship/SKILL.md

@@ -280,7 +280,7 @@ Use this as a one-shot grep before any export:
 
 ## Collaborative protocol
 
-This skill produces release artifacts. Always ask before each build is invoked. Group platforms — "I'm about to build Windows + Mac + Linux release configs into `build/`. OK?". See `_shared/collaborative-protocol.md`.
+This skill produces release artifacts. Always ask before each build is invoked. Group platforms — "I'm about to build Windows + Mac + Linux release configs into `build/`. OK?". See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -288,9 +288,9 @@ No template — this is a workflow. Each project's export config and store asset
 
 ## See also
 
-- `_shared/mcp-tools-reference.md` — full MCP tool list
-- `_shared/godot-version.md` — Godot 4.5 export-template versioning
-- `_shared/collaborative-protocol.md` — "May I write" pattern
+- `references/mcp-tools-reference.md` — full MCP tool list
+- `references/godot-version.md` — Godot 4.5 export-template versioning
+- `references/collaborative-protocol.md` — "May I write" pattern
 - `deployment/export-presets/SKILL.md` — preset config deep dive
 - `deployment/web-html5-export/SKILL.md` — HTML5-specific traps
 - `deployment/steam-uploader/SKILL.md` — `steamcmd` + GodotSteam (when shipped)

package/skills/gameplay-mechanics/auto-fire-targeting/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: auto-fire-targeting
+description: Use when designing or fixing the targeting system for an auto-fire weapon (survivors-genre, top-down ARPG, tower-defense). Covers the pending-damage pattern that prevents over-commit when bullet flight time is longer than fire rate. Trigger on "auto-fire", "auto-aim", "weapon targeting", "targeting", "wasted bullets", "overkill", "damage prediction", "survivors weapon".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: gameplay-mechanics
+allowed-tools: Read Edit Grep
+paths: ["**/*.gd"]
+---
+
+# Auto-Fire Weapon Targeting — pending-damage pattern
+
+A survivors-genre auto-fire weapon picks a target each fire frame. Naive nearest-enemy targeting wastes bullets when fire rate exceeds bullet flight time. This skill encodes the pending-damage pattern that fixes it.
+
+## The problem
+
+Auto-fire weapon. Bullet speed 22 m/s. Target 10m away. Bullet takes ~0.45s to arrive. With high attack speed the player fires several bullets per second. By the time the first bullet arrives and kills the target, several more bullets are already in flight toward where the target was. They miss into empty space. The player sees bullets "fan out in a cone past the dead enemy" while other enemies stand around untouched.
+
+This is not a re-targeting bug. The weapon's `_fire()` correctly re-runs `find_nearest_enemy()` each shot. The issue is that the target is alive at fire-time and dead at arrival-time. All shots fired in that window aim at it because none of them know about the kill in flight.
+
+## The fix — pending damage commitment
+
+Each enemy carries a counter of damage that is in flight toward it. Targeting de-prefers (but does not exclude) enemies whose pending damage already exceeds their current HP.
+
+### 1. Add the counter to the enemy base class
+
+```gdscript
+# enemy_base_3d.gd
+
+var pending_damage: float = 0.0
+
+
+func commit_pending(amount: float) -> void:
+    pending_damage += amount
+
+
+func release_pending(amount: float) -> void:
+    pending_damage = maxf(0.0, pending_damage - amount)
+
+
+## True if enough damage is already in flight to kill this enemy.
+func is_saturated() -> bool:
+    return pending_damage >= health
+```
+
+### 2. Update the targeting helper
+
+The selector keeps the saturated set as a fallback. If every enemy is saturated, the player must still be able to fire on someone — fall through to a normal nearest pick across saturated enemies. Otherwise prefer non-saturated.
+
+```gdscript
+# targeting.gd
+
+static func pick(origin: Vector3, mode: int, max_range: float, ...) -> Node3D:
+    var enemies: Array = GameManager.get_enemies()
+    var best: Node3D = null
+    var best_score: float = -INF
+    var fallback: Node3D = null
+    var fallback_score: float = -INF
+    for enemy in enemies:
+        # ... existing range + LoS filters ...
+        var score := _score(enemy, d_sq, mode)
+        var saturated: bool = "is_saturated" in enemy and enemy.is_saturated()
+        if saturated:
+            if score > fallback_score:
+                fallback_score = score
+                fallback = enemy
+        else:
+            if score > best_score:
+                best_score = score
+                best = enemy
+    if best != null:
+        return best
+    return fallback  # everyone is saturated; fire on the next-best anyway
+```
+
+### 3. Commit at fire time
+
+```gdscript
+# projectile_weapon.gd
+
+func _spawn_projectile(dir: Vector3, target: Node3D) -> void:
+    var dmg: float = base_damage * GameManager.player_damage_mult
+    # Commit expected damage. No crit factor — we don't gamble on RNG. If crit
+    # over-kills the target, the next-frame release refunds the difference.
+    var commit_amount: float = dmg
+    if target != null and target.has_method("commit_pending"):
+        target.commit_pending(commit_amount)
+    var proj: Node3D = _projectile_scene.instantiate()
+    # ... add_child, position, etc ...
+    proj.setup(dir * PROJECTILE_SPEED, dmg, ..., target, commit_amount)
+```
+
+### 4. Release at bullet death (catch-all)
+
+The bullet must release the commitment exactly once when it leaves the tree, regardless of how. Hit, pierce-out, range-expire, or any other free path. Use `tree_exiting` so the release is guaranteed without each free-site having to remember.
+
+```gdscript
+# bullet.gd
+
+var _committed_target: Node = null
+var _committed_amount: float = 0.0
+var _committed_released: bool = false
+
+
+func setup(..., commit_target: Node = null, commit_amount: float = 0.0) -> void:
+    # ... other setup ...
+    _committed_target = commit_target
+    _committed_amount = commit_amount
+
+
+func _ready() -> void:
+    # ... other wiring ...
+    tree_exiting.connect(_release_committed)
+
+
+## Idempotent so multiple call paths can't double-release.
+func _release_committed() -> void:
+    if _committed_released:
+        return
+    _committed_released = true
+    if _committed_amount <= 0.0:
+        return
+    if _committed_target != null and is_instance_valid(_committed_target) \
+            and _committed_target.has_method("release_pending"):
+        _committed_target.release_pending(_committed_amount)
+```
+
+## Bonus — spread fan across multiple enemies
+
+When the weapon fires N projectiles per shot (extra-projectiles upgrade, multishot), pick a fresh target per projectile instead of fanning all N at the primary target. Combined with the saturation filter this drains follow-on shots toward fresh enemies.
+
+```gdscript
+# projectile_weapon.gd, multishot path
+
+for i in total_projectiles:
+    var per_shot_target := Targeting.pick(global_position, mode, range)
+    if per_shot_target == null:
+        per_shot_target = primary_target  # fall back if nothing else in range
+    _spawn_projectile(dir.rotated(Vector3.UP, fan_angle), per_shot_target)
+```
+
+## Bonus — bump projectile speed
+
+The over-commit window is `attack_speed * bullet_travel_time`. Faster bullets shrink it for free. 22 m/s up to 35 m/s halves the window without affecting balance much. Cheap fix to bundle with the pattern.
+
+## What this does NOT solve
+
+- **Pierce > 1 weapons.** The committed amount is reserved on the first target only. Subsequent pierces are bonus damage to whoever happens to be in line. That is fine — pierce already feels random by design.
+- **AOE / nova / orbital weapons.** They hit everyone in radius regardless of "target," so single-target pending-damage doesn't apply. Skip them.
+- **Slow-but-massive weapons.** A single shot that one-shots multiple enemies in sequence (rocket launcher, railgun) doesn't benefit much. The window where the over-commit happens is too short to matter.
+
+## Why this beats alternatives
+
+| Alternative | Why we didn't pick it |
+|---|---|
+| In-flight bullet retargeting (each bullet seeks the nearest live enemy mid-flight) | Per-bullet logic is expensive and the homing visual reads as a different weapon archetype. Pending-damage is fire-and-forget. |
+| Predict the kill (fire only enough bullets to kill) | Requires knowing exact damage including crit and item modifiers. Edge cases multiply. |
+| Just bump bullet speed | Helps but doesn't eliminate the issue at very high attack-speed builds. |
+| Shoot-through-enemies (everyone gets free pierce) | Changes weapon identity. AOE bleed. |
+
+Pending-damage is local to the targeting query, requires no per-bullet ticking, and keeps each weapon archetype's identity intact.
+
+## Verification
+
+Test scenario: spawn a single weak enemy directly in front of the player at point-blank range. Equip the auto-fire weapon and the highest-attack-speed item. Watch the bullet fan when the enemy dies.
+
+Before: 5-15 bullets continue past the corpse over the next ~0.5s.
+After: 1-2 bullets continue (the ones that were already past the half-flight point), the rest of the fire pool redirects to whatever target Targeting picks next, or stops if there's none in range.
+
+Use `summer_get_diagnostics` to confirm no new errors. Use `summer_inspect_node` on a sample enemy mid-fight to confirm `pending_damage` is being incremented and decremented as expected.

package/skills/gameplay-mechanics/design-mechanic/SKILL.md

@@ -148,7 +148,7 @@ lifetime = 0.4
 
 ### 7. Write the GDScript stub
 
-Stub only — implementation is the next session. Use `_shared/gd-style.md` conventions. For double-jump:
+Stub only — implementation is the next session. Use `references/gd-style.md` conventions. For double-jump:
 
 ```gdscript
 class_name PlayerController
@@ -236,12 +236,12 @@ Ask:
 | Hand-wave depth | "Players will use it strategically" is not depth. Name the choice the player makes. |
 | Tunables hard-coded as `const` | Use `@export` so designers tune in the inspector. |
 | Adding the mechanic without the FX/audio nodes | Without nodes for feedback, the mechanic ships feeling cheap. Scaffold the nodes alongside the script. |
-| Setting `position` for movement instead of `velocity` | Physics objects use `velocity` in `_physics_process`. See `_shared/gd-style.md`. |
-| Calling SetResourceProperty on inline sub_resources | Silent fail. See `_shared/mcp-tools-reference.md` § Trap. |
+| Setting `position` for movement instead of `velocity` | Physics objects use `velocity` in `_physics_process`. See `references/gd-style.md`. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `references/mcp-tools-reference.md` § Trap. |
 
 ## Collaborative protocol
 
-This skill writes scene nodes and one or more files (`.gd`, `.summer/mechanics/<name>.md`). Group writes into one ask per phase. See `_shared/collaborative-protocol.md`.
+This skill writes scene nodes and one or more files (`.gd`, `.summer/mechanics/<name>.md`). Group writes into one ask per phase. See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -254,10 +254,10 @@ This skill is a workflow that designs and scaffolds — the templates are runnab
 
 ## See also
 
-- `_shared/collaborative-protocol.md`
-- `_shared/mcp-tools-reference.md`
-- `_shared/gd-style.md` — GDScript conventions
-- `_shared/godot-version.md` — Godot 4.5 API notes
+- `references/collaborative-protocol.md`
+- `references/mcp-tools-reference.md`
+- `references/gd-style.md` — GDScript conventions
+- `references/godot-version.md` — Godot 4.5 API notes
 - `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md` this skill reads
 - `level-design/design-level/SKILL.md` — design the levels that exercise the mechanic
 - `character-controllers/fps-controller/SKILL.md` — FPS movement scaffolding

package/skills/level-design/design-level/SKILL.md

@@ -239,11 +239,11 @@ End with:
 | Reward gating too generous | Free heals before the peak deflate the peak. Gate them after the test. |
 | Blending level types | Stealth + puzzle + boss in one level = three half-baked levels. Pick one. |
 | Building geometry before the skeleton | Skeleton-first lets you iterate on layout cheaply. Geometry comes after the design is locked. |
-| Calling SetResourceProperty on inline sub_resources | Silent fail. See `_shared/mcp-tools-reference.md` § Trap. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `references/mcp-tools-reference.md` § Trap. |
 
 ## Collaborative protocol
 
-This skill creates a new scene file (`.tscn`) and a design doc (`.md`). Group writes per phase. Always ask before `summer_create_scene`. See `_shared/collaborative-protocol.md`.
+This skill creates a new scene file (`.tscn`) and a design doc (`.md`). Group writes per phase. Always ask before `summer_create_scene`. See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -256,9 +256,9 @@ The skeleton this skill produces is meant to be filled in via `/summer:design-me
 
 ## See also
 
-- `_shared/collaborative-protocol.md`
-- `_shared/mcp-tools-reference.md`
-- `_shared/godot-version.md` — Godot 4.5 API notes
+- `references/collaborative-protocol.md`
+- `references/mcp-tools-reference.md`
+- `references/godot-version.md` — Godot 4.5 API notes
 - `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md`
 - `gameplay-mechanics/design-mechanic/SKILL.md` — designs the verbs the level exercises
 - `ai-and-npcs/design-npc/SKILL.md` — designs the enemies the encounters reference