summer-engine 2.3.0 → 2.6.0

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

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

@@ -0,0 +1,125 @@
+---
+name: scene-to-level
+description: Use when the user wants to go from a single scene reference image (a screenshot or concept art of how the final game should look) all the way to a playable Godot scene populated with the right assets and terrain. Orchestrates concept → asset pack → terrain → composition → scene assembly. Trigger on "build this scene", "make this playable", "I want a level that looks like this", "from a screenshot to a game", "implement this concept".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: level-design
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_create_scene summer_open_scene summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_scene_tree summer_inspect_node summer_search_assets summer_import_from_url
+paths: ["**/*.tscn", "**/*.gd", "assets/**", ".summer/**", "levels/**"]
+---
+
+# scene-to-level — From a reference image to a playable scene
+
+This is the **orchestrator** skill. It doesn't generate art, doesn't slice sheets, doesn't write game code — it routes the user through the chain of skills that do, and stitches their outputs together into a placeable Godot scene.
+
+Use it when the user shows you a screenshot or concept image and says "build this." The output is a `.tscn` you can hit play on, populated with assets that match the reference's style.
+
+## The pipeline (decision tree)
+
+```
+1. Read the reference image (vision).
+   └── What kind of scene is it?
+        ├─ 2D top-down / isometric / side-scroller
+        │   └── route to TERRAIN + 2D ASSETS path
+        ├─ 3D third-person / first-person
+        │   └── route to 3D ASSETS path (out of scope for this skill —
+        │       use summer:3d-assets/ subskills directly)
+        └─ UI-only screen (menu, HUD)
+            └── route to UI ASSETS path (just plan-asset-pack)
+
+2. For each visible element, route to the right sub-pipeline:
+
+   TERRAIN  → summer:2d-assets/tileable-texture
+              (auto-tiling Wang / 47-tile sheet; CURRENTLY a placeholder
+              that generates a single tile — full auto-tile work is
+              tracked in publicsummerengine/Docs/assetCreation/
+              TERRAIN_AUTOTILE_IDEA.md and not yet built)
+
+   PROPS / DECOR / LIGHTING / NATURE / WATER / BUILDINGS / UI / VFX
+       ── If user has time for individual generation, prefer:
+       │   summer:2d-assets/create-asset-sheet (Plan + Generate Pack
+       │   mode at /studio/plan-asset-pack — higher quality, each asset
+       │   gets full model attention)
+       └── If user wants fast / exploratory:
+           summer:2d-assets/create-asset-sheet (Slice from a sheet at
+           /studio/create-tileset — one sheet, autoslice, cheaper)
+
+   CHARACTERS → summer:2d-assets/character-portrait first for the static
+                frame, then summer:2d-assets/sprite-sheet for animation
+
+3. Once assets exist, USE-WIDGET-ASSET on any UI / panel / bar /
+   toggle pack files to wire them as NinePatchRect / TextureProgressBar
+   / etc. (see summer:2d-assets/use-widget-asset)
+
+4. Compose the scene:
+   - summer_create_scene with a Node2D / Control root depending on the
+     scene type
+   - Add a TileMap node for terrain; assign the generated tileset
+     resource
+   - Place props as Sprite2D / TextureRect children, positioned to
+     match the reference's composition
+   - Wire UI as Control nodes anchored to the viewport
+
+5. Validate:
+   - summer_get_script_errors
+   - summer_play (the user takes over from here)
+```
+
+## When to use
+
+- "Make this screenshot playable."
+- "I want a level that looks exactly like this concept art."
+- "Build a Japanese village scene like this reference."
+- "I have a UI mockup — implement it."
+
+## When NOT to use
+
+- The user wants a **single asset** → `summer:2d-assets/pixel-art` or a leaf skill directly.
+- The user wants to **design** a level from scratch (gameplay beats, pacing, encounters) → `summer:level-design/design-level`. This skill is post-design — it implements a known visual target.
+- The user wants a **3D level** → use `summer:3d-assets/` subskills directly; the orchestration for 3D scenes isn't in this skill yet.
+- The user wants a **playable prototype with mechanics already** → mechanics aren't in scope. This skill produces the *visuals*; the mechanic skills (e.g. `summer:gameplay-mechanics/design-mechanic`) handle behavior.
+
+## Required up-front
+
+Before starting, you need either:
+
+1. A reference image (URL or local file) the user provides, OR
+2. A vivid text description of the target scene from the user
+
+If neither is offered, stop and ask. Don't guess what a "japanese village scene" looks like — get the reference first.
+
+## Honest reliability map
+
+| Pipeline node | Reliability | Cost (rough) | What can go wrong |
+|---|---|---|---|
+| Reading the reference (vision call) | High | $0.02 | Model misidentifies the scene type |
+| Plan + Generate Pack (theme → per-asset) | High for props / icons / UI | $0.10–0.50 per pack | Style drift across items if no style ref |
+| Slice from a sheet (single-sheet path) | Medium for dense sheets | $0.08 + upscales | Touching sprites merge into one slice |
+| Tileable terrain (auto-tile) | LOW today — not built. | n/a | Use a single tile placeholder or stitch by hand |
+| Sprite-sheet animation | Medium — see that skill's own honesty section | varies | Frame consistency is the hard part |
+| Scene assembly via `summer_*` tools | High | free | Engine must be running |
+
+Surface this map to the user when relevant — don't claim "ready to play in 10 minutes" if terrain auto-tiling is what they actually need.
+
+## A worked example
+
+User shows you a screenshot of a Japanese village with multiple islands, water between them, buildings, characters, and a bottom palette UI:
+
+1. **Vision pass** identifies the scene as 2D isometric with: water terrain (large area), grass terrain (per island), buildings (5+ distinct), characters (2), UI palette + toolbar.
+2. **Plan the props pack** via the create-asset-sheet planner: 12 props at minimum (torii, sakura, lantern, pagoda, bridge, well, sign, banner, bucket, hay, fence, crate). Generated per-asset for quality.
+3. **Plan the buildings pack**: 5 distinct buildings (small house, barn, shop, pagoda, watchtower).
+4. **Generate terrain**: today, single grass tile + single water tile + edge variant placeholders. Full Wang-tile auto-tiling is the TERRAIN_AUTOTILE_IDEA.md unbuilt path.
+5. **Plan the UI pack** via the planner with theme "isometric voxel game UI: bottom palette, toolbar with Place/Erase/Pan/Save/Reset, asset category tabs, instruction panel."
+6. **For each UI slice that's a panel / button**, use `summer:2d-assets/use-widget-asset` to wire as NinePatchRect.
+7. **Compose**: TileMap for terrain; Sprite2D placement matching the reference; Control nodes for the UI.
+8. **Validate + hand off**.
+
+Total wall-clock: maybe 30 min for the asset packs (parallel), another 15 for scene composition. NOT a five-minute thing.
+
+## What this skill explicitly defers
+
+- **3D scene assembly.** Out of scope; use `summer:3d-assets/` directly until a 3D variant of this orchestrator exists.
+- **Auto-tiling terrain.** The pipeline node exists in the decision tree but the leaf skill that implements it is not built — see `publicsummerengine/Docs/assetCreation/TERRAIN_AUTOTILE_IDEA.md`.
+- **Animation orchestration.** Per-character `summer:2d-assets/sprite-sheet` is invoked manually; no auto-pairing of characters with their animation pipelines yet.
+- **Gameplay code.** Player movement, interactions, win conditions — those are level-design + gameplay-mechanics skills, not this one.

package/skills/multiplayer-and-networking/host-authoritative-state/SKILL.md

@@ -321,12 +321,12 @@ This skill writes new autoload files (one per Manager). Always ask before each:
 
 Don't bulk-create five Managers in one shot. Walk one Manager end-to-end (data → mutators → requests → broadcasts → lifecycle) so the user can verify the shape, then repeat for the next domain.
 
-After each Manager file lands, call `summer_get_script_errors` to confirm clean compile. See [`_shared/collaborative-protocol.md`](../../_shared/collaborative-protocol.md).
+After each Manager file lands, call `summer_get_script_errors` to confirm clean compile. See [`references/collaborative-protocol.md`](../../references/collaborative-protocol.md).
 
 ## See also
 
 - [`peer-to-peer-multiplayer`](../peer-to-peer-multiplayer/SKILL.md) — the four-layer architecture overview. Read this first if you haven't.
 - [`setup-multiplayer`](../setup-multiplayer/SKILL.md) — lighter intro that just gets a session running. Use that one if the user just wants two players to see each other.
-- [`_shared/godot-version.md`](../../_shared/godot-version.md) — Godot 4.5 multiplayer API stability notes.
-- [`_shared/gd-style.md`](../../_shared/gd-style.md) — typed-GDScript conventions used in the examples above.
-- [`_shared/mcp-tools-reference.md`](../../_shared/mcp-tools-reference.md) — `summer_get_script_errors` for compile verification.
+- [`references/godot-version.md`](../../references/godot-version.md) — Godot 4.5 multiplayer API stability notes.
+- [`references/gd-style.md`](../../references/gd-style.md) — typed-GDScript conventions used in the examples above.
+- [`references/mcp-tools-reference.md`](../../references/mcp-tools-reference.md) — `summer_get_script_errors` for compile verification.

package/skills/multiplayer-and-networking/peer-to-peer-multiplayer/SKILL.md

@@ -361,7 +361,7 @@ This skill writes multiple new files (`autoloads/network_manager.gd`, `autoloads
 
 Don't apply all four layers in one shot — checkpoint after each layer so the user can verify before adding the next.
 
-See [`_shared/collaborative-protocol.md`](../../_shared/collaborative-protocol.md).
+See [`references/collaborative-protocol.md`](../../references/collaborative-protocol.md).
 
 ## Want a working starter?
 
@@ -371,8 +371,8 @@ When the `template-co-op-3d` template ships in the registry, this skill will ref
 
 ## See also
 
-- [`_shared/godot-version.md`](../../_shared/godot-version.md) — Godot 4.5 multiplayer API stability notes
-- [`_shared/mcp-tools-reference.md`](../../_shared/mcp-tools-reference.md) — `summer_project_setting` for autoload registration
-- [`_shared/gd-style.md`](../../_shared/gd-style.md) — typed-GDScript conventions
+- [`references/godot-version.md`](../../references/godot-version.md) — Godot 4.5 multiplayer API stability notes
+- [`references/mcp-tools-reference.md`](../../references/mcp-tools-reference.md) — `summer_project_setting` for autoload registration
+- [`references/gd-style.md`](../../references/gd-style.md) — typed-GDScript conventions
 - [`host-authoritative-state`](../host-authoritative-state/SKILL.md) — deeper dive on JUST the state ownership decision matrix
 - [`setup-multiplayer`](../setup-multiplayer/SKILL.md) — lighter intro that just gets a session running (use that one if the user just wants 2 players to see each other; use this one if they want to ship a real game)

package/skills/multiplayer-and-networking/setup-multiplayer/SKILL.md

@@ -286,7 +286,7 @@ Test checklist:
 | Replicate every property | Replicate position, rotation, health, that's it | Bandwidth + bug surface |
 | Run physics on every peer for every player | Physics on owner only, others receive transform | Otherwise jitter and divergence |
 | Trust the client | Validate `get_remote_sender_id()` in every `any_peer` RPC | Cheaters route through the wrong RPC |
-| Inline `SceneReplicationConfig` sub_resource | Save as standalone `.tres` | Silent-fail trap (see `_shared/mcp-tools-reference.md`) |
+| Inline `SceneReplicationConfig` sub_resource | Save as standalone `.tres` | Silent-fail trap (see `references/mcp-tools-reference.md`) |
 | Roll custom transport | ENet (or WebSocket for browser) | You will hit edge cases ENet already solved |
 | Skip authority check in damage RPC | `if not multiplayer.is_server(): return` at the top of damage handlers | Otherwise damage applied N times |
 | Spawn players on every peer | MultiplayerSpawner — host spawns, clients receive | Otherwise N copies of each player |
@@ -303,22 +303,22 @@ Test checklist:
 
 ## Collaborative protocol
 
-This skill rewires the project at the architectural level. Always ask before each block of changes. Group writes — "I'm about to add the autoload + 2 scenes + 3 scripts + InputMap entries. OK?". See `_shared/collaborative-protocol.md`.
+This skill rewires the project at the architectural level. Always ask before each block of changes. Group writes — "I'm about to add the autoload + 2 scenes + 3 scripts + InputMap entries. OK?". See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
 For a known-good multiplayer scaffold (host + join UI, ENet transport, MultiplayerSpawner, replicated player), point users at:
 
-→ **template-id**: TBD (`template-co-op-online` planned, see `_shared/template-registry.md`)
+→ **template-id**: TBD (`template-co-op-online` planned, see `references/template-registry.md`)
 
 For now: this skill produces the scaffold inline. When the template lands, link from here.
 
 ## See also
 
-- `_shared/mcp-tools-reference.md` — full MCP tool list (project-setting, autoload registration)
-- `_shared/godot-version.md` — `MultiplayerAPI` is medium-churn; `SceneReplicationConfig` settled in 4.0+
-- `_shared/collaborative-protocol.md` — "May I write" pattern
-- `_shared/gd-style.md` — typed GDScript conventions
+- `references/mcp-tools-reference.md` — full MCP tool list (project-setting, autoload registration)
+- `references/godot-version.md` — `MultiplayerAPI` is medium-churn; `SceneReplicationConfig` settled in 4.0+
+- `references/collaborative-protocol.md` — "May I write" pattern
+- `references/gd-style.md` — typed GDScript conventions
 - `multiplayer-and-networking/multiplayerapi-basics/SKILL.md` — deeper MultiplayerAPI patterns
 - `multiplayer-and-networking/client-server-pattern/SKILL.md` — dedicated server architecture
 - `multiplayer-and-networking/peer-replication/SKILL.md` — synchronizer config patterns

package/skills/performance/tune-performance/SKILL.md

@@ -200,7 +200,7 @@ Compare: was the metric movement at least 50% of what was promised? If yes, ship
 
 ## Collaborative protocol
 
-This skill makes scene/resource/code changes. Always ask before each fix is applied. See `_shared/collaborative-protocol.md`.
+This skill makes scene/resource/code changes. Always ask before each fix is applied. See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -208,10 +208,10 @@ No template — this is a workflow. Performance tuning is project-specific by de
 
 ## See also
 
-- `_shared/mcp-tools-reference.md` — full MCP tool list
-- `_shared/godot-version.md` — Godot 4.5 renderer notes (Compositor, RenderSceneBuffers churn)
-- `_shared/collaborative-protocol.md` — "May I write" pattern
-- `_shared/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
+- `references/mcp-tools-reference.md` — full MCP tool list
+- `references/godot-version.md` — Godot 4.5 renderer notes (Compositor, RenderSceneBuffers churn)
+- `references/collaborative-protocol.md` — "May I write" pattern
+- `references/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
 - `performance/profiling-godot/SKILL.md` — deeper Godot profiler usage
 - `performance/draw-call-batching/SKILL.md` — MultiMeshInstance3D patterns
 - `performance/lod-and-culling/SKILL.md` — LOD setup

package/skills/rendering-and-lighting/3d-lighting/SKILL.md

@@ -121,4 +121,4 @@ Then create `Environment` and `Sky` resources via the inspector or load from `.t
 
 ## Collaborative protocol
 
-This skill mutates the scene (adds lights + WorldEnvironment + tunes Environment sub-properties). Always ask before applying: "May I add a DirectionalLight3D Sun with shadows + a WorldEnvironment with a procedural sky?". See `../../_shared/collaborative-protocol.md`.
+This skill mutates the scene (adds lights + WorldEnvironment + tunes Environment sub-properties). Always ask before applying: "May I add a DirectionalLight3D Sun with shadows + a WorldEnvironment with a procedural sky?". See `../../references/collaborative-protocol.md`.

package/skills/rendering-and-lighting/art-direction/SKILL.md

@@ -261,11 +261,11 @@ End with:
 | Procedural skybox without angle | Mid-day sun + uniform fog reads generic. Always angle the sun. |
 | Skipping the lighting plan | Lighting *is* art direction in 3D. Without a plan, every level looks different. |
 | Adopting "AAA realism" at vertical-slice scope | Asset cost is brutal solo. Stylized always wins. |
-| 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 design doc (`.summer/art-bible.md`) and may modify `project.godot` settings + the main scene's `WorldEnvironment`. Always ask. See `_shared/collaborative-protocol.md`.
+This skill writes one design doc (`.summer/art-bible.md`) and may modify `project.godot` settings + the main scene's `WorldEnvironment`. Always ask. See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -273,9 +273,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 rendering API notes (Compositor moved in 4.4 / 4.5)
-- `_shared/mcp-tools-reference.md`
+- `references/collaborative-protocol.md`
+- `references/godot-version.md` — Godot 4.5 rendering API notes (Compositor moved in 4.4 / 4.5)
+- `references/mcp-tools-reference.md`
 - `scene-and-project/brainstorm-game/SKILL.md` — produces the brief that anchors the bible
 - `audio/audio-direction/SKILL.md` — the sonic counterpart
 - `rendering-and-lighting/3d-lighting/SKILL.md` — implements the lighting plan

package/skills/scene-and-project/brainstorm-game/SKILL.md

@@ -193,16 +193,16 @@ Don't auto-pick. Let them decide.
 
 ## Collaborative protocol
 
-This skill writes one file (`.summer/GameSoul.md`). Always ask before writing. Always show the brief inline before saving so the user can react. See `_shared/collaborative-protocol.md`.
+This skill writes one file (`.summer/GameSoul.md`). Always ask before writing. Always show the brief inline before saving so the user can react. See `references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
-No template — this is a workflow that produces the brief that drives template selection later. Once `.summer/GameSoul.md` exists, `/summer:make-game` can match it against `_shared/template-registry.md`.
+No template — this is a workflow that produces the brief that drives template selection later. Once `.summer/GameSoul.md` exists, `/summer:make-game` can match it against `references/template-registry.md`.
 
 ## See also
 
-- `_shared/collaborative-protocol.md` — "May I write?" pattern
-- `_shared/template-registry.md` — templates the brief will be matched against later
+- `references/collaborative-protocol.md` — "May I write?" pattern
+- `references/template-registry.md` — templates the brief will be matched against later
 - `gameplay-mechanics/design-mechanic/SKILL.md` — design the core loop in detail
 - `level-design/design-level/SKILL.md` — sketch level 1
 - `rendering-and-lighting/art-direction/SKILL.md` — turn the one-phrase look into a full bible

package/skills/scene-and-project/play/SKILL.md

@@ -104,5 +104,5 @@ No template — works against any Godot/Summer project that has a main scene set
 
 ## See also
 
-- `_shared/mcp-tools-reference.md` — full tool list
+- `references/mcp-tools-reference.md` — full tool list
 - `debugging/debug/SKILL.md` — what to do when /play surfaces an error

package/skills/scene-and-project/scene-composition/SKILL.md

@@ -112,6 +112,35 @@ Use `./` for paths relative to the scene root:
 
 No fallback for this — Summer MCP required. Handwriting `.tscn` files for hierarchy mutations is error-prone (UID collisions, wrong format version, broken sub_resource refs). If MCP isn't connected, open the scene in the Godot editor and use the SceneTree dock.
 
+## Trap — Cross-scene transform leak when copying a scene as a template
+
+When you duplicate a scene to spawn a sibling level (for example, `level_1.tscn` → `level_2.tscn`), every child instance carries its transform offset baked at the original level's coordinate system. If the source level places its player at world `(223, 108, -1833)` and instances a kill-volume scene at offset `(512, -3, 512)`, those numbers are anchored to the source level's terrain origin. Drop the same kill-volume instance into a level whose player spawns at world `(0, 1, 0)` and the volume's wall colliders may end up slicing the new arena at world `x = 0`. The user sees a "glitching invisible line through the middle of the map" they can't pass through. The colliders are invisible under the floor, so visual diagnosis is hard. Only collision-walking through them reveals the problem.
+
+Rule when copying a scene as a template:
+
+1. Audit every child instance for hardcoded `transform = Transform3D(...)` lines.
+2. Decide for each: keep, re-zero (origin = `(0,0,0)`), or drop entirely.
+3. The bigger the original level's world-space coordinates, the more dangerous the copy. Re-zero by default; you can move things back if needed.
+4. Levels that spawn the player at world origin (for example flat arenas centered on `(0,0,0)`) should drop ALL transform overrides from carry-over instances. Only re-add transforms relative to the new origin.
+
+## Trap — Third-person camera collision when foliage shouldn't block
+
+Godot's `SpringArm3D` shortens the camera boom when it raycasts into geometry on the configured `collision_mask`. If your trees, bushes, or grass have collision so the player physically bumps them, on the same layer the SpringArm queries, the camera shortens for foliage too. Players see the camera awkwardly snap forward whenever they walk near a tree.
+
+The pattern that works:
+
+1. Foliage gets its own physics layer. Conventionally layer 9 ("Foliage").
+   - Foliage `StaticBody3D`: `collision_layer = 256` (which is 2^8, layer 9).
+2. Player still bumps into foliage by including that layer in its `collision_mask`.
+   - Player `CharacterBody3D`: `collision_mask = 259` (which is 1 + 2 + 256, Entities + Level + Foliage).
+3. SpringArm uses a mask that catches solid level geometry but excludes foliage.
+   - SpringArm: `collision_mask = 3` (which is 1 + 2, Entities + Level only).
+4. For the visual fade the user expects when the camera is "behind" a tree, add the foliage mesh to the `camera_fade` group. An existing camera-occlusion fade system can ghost the mesh by AABB intersection with the camera-to-player segment without touching collision.
+
+Why per-layer split: there's no clean way to exclude a single body type from `SpringArm3D`'s collision check via `add_excluded_object` for dynamically-spawned foliage. You'd have to register every tree at spawn time and re-register on level change. Layer-level filtering is set-and-forget.
+
+Don't skip the player mask update. If you only move foliage to layer 9 without adding it to the player's mask, the player walks straight through trees.
+
 ## Collaborative protocol
 
-This skill creates and mutates scene files. Always ask before applying: "May I create `res://scenes/player.tscn` and instantiate it under `./World`?". See `../../_shared/collaborative-protocol.md`.
+This skill creates and mutates scene files. Always ask before applying: "May I create `res://scenes/player.tscn` and instantiate it under `./World`?". See `../../references/collaborative-protocol.md`.

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

@@ -90,6 +90,59 @@ var siblings = get_parent().get_children()
 
 For health systems, input handling, and state machines, see [reference.md](reference.md).
 
+## Anti-patterns — introspection traps
+
+Godot's introspection API has Object-instance methods that look like they should work on script-class references. They don't. Calling them on a `const ScriptName = preload(...)` reference is a parse error, not a runtime no-op.
+
+| Wrong | Right | Why |
+|---|---|---|
+| `if SomeScript.has_static_method("play"): SomeScript.play(...)` | Just call `SomeScript.play(...)` directly. If the method exists in the script, it parses; if not, the parser catches it. | `has_static_method()` is an `Object` instance method. `SomeScript` here is a `Script` reference. It has no `has_static_method` member, so the parser rejects the call. |
+| `if SomeScript.has_method("foo")` (on a script-class ref) | Same. Call `foo()` directly, or check `is_instance_of()` after instancing. | Same trap. |
+| Defensive guards "in case the script ships in parallel" | Don't ship in parallel agents that depend on each other's APIs without one of them landing first. The compiler will catch missing methods at parse time. | Guards that don't compile aren't guards. |
+
+**Rule of thumb:** if you're tempted to write `Klass.has_*("name")` on a `const Klass = preload(...)` reference, you're confusing class-level introspection (compile-time, automatic) with instance-level introspection (`Object` method, runtime). GDScript's parser already does the compile-time check for free.
+
+**Side note on `has_method` vs `has_static_method`:** `has_method` works on a node/instance to check if the *instance* has a method. `has_static_method` works on an *Object* instance to check if its *class* has a static method. Neither is callable on a bare `Script` reference (`preload(...)` result). To check static-method presence at runtime, call the method inside a `try`-equivalent. In practice if your code paths are well-typed you don't need to.
+
+## Anti-pattern — `@onready var = $Path` on nodes that don't exist on every variant
+
+Godot resolves `$Path` (the `get_node` shorthand) at `@implicit_ready` time. If the node is missing from the current scene, you get `Node not found: "X" (relative to "Y")` errors before any of your `_ready()` runtime guards can run.
+
+Common case: a script is shared by multiple scene variants where some variants have an optional child. Even if every code path that touches the variable has a `if inventory_ui:` guard, the `@onready` line itself errors at scene load.
+
+| Wrong | Right |
+|---|---|
+| `@onready var inventory_ui: CanvasLayer = $InventoryUI` | `@onready var inventory_ui: CanvasLayer = get_node_or_null("InventoryUI")` |
+| `@onready var hp_bar: ProgressBar = $HUD/HPBar` (HUD optional) | `@onready var hp_bar: ProgressBar = get_node_or_null("HUD/HPBar")` |
+
+**Rule of thumb:** if the node is required for the script to function at all, use `$Path` and rely on the parse-time error. If the node may be missing in some scene variants the script is reused across, use `get_node_or_null` and guard at every read site.
+
+## Anti-pattern — `Label3D.label_settings` (it doesn't exist)
+
+`LabelSettings` is a resource type used by `Label` (the 2D Control node) to bundle font + size + outline + colors. `Label3D` does NOT accept it. Assigning `LabelSettings` to `label_settings` on a `Label3D` raises `Invalid assignment of property or key 'label_settings' with value of type 'LabelSettings' on a base object of type 'Label3D'.`
+
+`Label3D` exposes the same styling fields as direct properties:
+
+```gdscript
+# WRONG - parses but errors at runtime when label is a Label3D.
+var settings := LabelSettings.new()
+settings.font = my_font
+settings.font_size = 24
+settings.outline_size = 2
+settings.outline_color = my_outline
+my_label_3d.label_settings = settings  # <-- runtime error
+
+# RIGHT - set the styling directly on the Label3D.
+my_label_3d.font = my_font
+my_label_3d.font_size = 24
+my_label_3d.outline_size = 2
+my_label_3d.outline_modulate = my_outline
+```
+
+Note the field name difference too: `LabelSettings.outline_color` (Label 2D) vs `Label3D.outline_modulate` (Label3D). Easy to miss in copy-paste.
+
+**Rule of thumb:** `LabelSettings` is for `Label` only. For `Label3D` use direct properties. For `RichTextLabel`, neither — it has its own theme overrides.
+
 ## Scene Integration
 
 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 or edit `.gd` files with the host agent's normal file-editing tools, then use Summer MCP only to attach the script and connect scene signals.