summer-engine 2.3.0 → 2.5.0

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.

package/skills/ui-and-ux/ui-basics/SKILL.md

@@ -147,4 +147,4 @@ text = "Start Game"
 
 ## Collaborative protocol
 
-This skill writes UI scene nodes and wires button signals. Always ask before applying: "May I add the MainMenu (Control + Margin + VBox + Title + Start/Quit buttons) and connect Start.pressed to `_on_start_pressed`?". See `../../_shared/collaborative-protocol.md`.
+This skill writes UI scene nodes and wires button signals. Always ask before applying: "May I add the MainMenu (Control + Margin + VBox + Title + Start/Quit buttons) and connect Start.pressed to `_on_start_pressed`?". See `../../references/collaborative-protocol.md`.

package/skills/video/animated-loop/SKILL.md

@@ -197,4 +197,4 @@ Once the loop is wired:
 - `audio/music-track` — score the menu.
 - `2d-assets/ui-graphics` — logo, menu buttons, HUD that sits over the loop.
 - `2d-assets/concept-art` — produce the reference still that anchors the loop.
-- `_shared/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.
+- `references/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/skills/video/cinematic-cutscene/SKILL.md

@@ -201,4 +201,4 @@ Once the cutscene is generated and wired:
 - `audio/music-track` — score the cutscene.
 - `2d-assets/concept-art` — generate the reference image axis if no character reference exists yet.
 - `2d-assets/character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
-- `_shared/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.
+- `references/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/skills/video/trailer-shot/SKILL.md

@@ -200,4 +200,4 @@ Once the shots are generated:
 - `audio/music-track` — trailer score.
 - `audio/sound-effect` — cut SFX (whooshes, impacts, stingers).
 - `2d-assets/concept-art` — generate the reference image axis when no asset exists yet.
-- `_shared/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.
+- `references/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/skills/visual-effects/game-feel/SKILL.md

@@ -110,7 +110,7 @@ func flash() -> void:
 
 **Tunable knobs:** `duration` 0.06–0.12s — under 0.06 reads as a flicker, over 0.12 looks slow. `emission_energy_multiplier` 1.5–3.0.
 
-> CRITICAL: do NOT inline a `StandardMaterial3D` as a `sub_resource` via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres`. Inline sub_resources break `summer_set_resource_property` silently — see `_shared/mcp-tools-reference.md` § "Trap".
+> CRITICAL: do NOT inline a `StandardMaterial3D` as a `sub_resource` via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres`. Inline sub_resources break `summer_set_resource_property` silently — see `references/mcp-tools-reference.md` § "Trap".
 
 ## Step 5 — Install Section 2 (Trauma Camera Shake)
 
@@ -358,7 +358,7 @@ Tune one knob at a time:
 
 ## Collaborative protocol
 
-This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `_shared/collaborative-protocol.md`.
+This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `references/collaborative-protocol.md`.
 
 ## When NOT to use this skill
 
@@ -369,10 +369,10 @@ This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always as
 
 ## See also
 
-- `_shared/mcp-tools-reference.md` — full MCP tool list, especially the inline-sub_resource trap
-- `_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, especially the inline-sub_resource trap
+- `references/godot-version.md` — Godot 4.5 API notes
+- `references/collaborative-protocol.md` — "May I write" pattern
+- `references/gd-style.md` — typed GDScript conventions
 - `audio/audio-direction/SKILL.md` — bus layout setup (prerequisite for ducking)
 - `post-processing/screen-shake/SKILL.md` — deeper trauma variants (Perlin noise, stacked sources)
 - `visual-effects/gpuparticles-3d-basics/SKILL.md` — particles to layer on top of the trio

package/skills/workflow/brainstorming/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: brainstorming
+description: "Use when starting creative work — designing a game, picking a mechanic, building features or components, modifying behavior. Explores user intent, requirements, and design before implementation. MUST run before any creative work."
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
+3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — in sections scaled to their complexity, get user approval after each section
+6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
+7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+8. **User reviews written spec** — ask user to review the spec file before proceeding
+9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Visual questions ahead?" [shape=diamond];
+    "Offer Visual Companion\n(own message, no other content)" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write design doc" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews spec?" [shape=diamond];
+    "Invoke writing-plans skill" [shape=doublecircle];
+
+    "Explore project context" -> "Visual questions ahead?";
+    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
+    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
+    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write design doc" [label="yes"];
+    "Write design doc" -> "Spec self-review\n(fix inline)";
+    "Spec self-review\n(fix inline)" -> "User reviews spec?";
+    "User reviews spec?" -> "Write design doc" [label="changes requested"];
+    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
+}
+```
+
+**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**Design for isolation and clarity:**
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+**Working in existing codebases:**
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## After the Design
+
+**Documentation:**
+
+- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+  - (User preferences for spec location override this default)
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Spec Self-Review:**
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**User Review Gate:**
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+**Implementation:**
+
+- Invoke the writing-plans skill to create a detailed implementation plan
+- Do NOT invoke any other skill. writing-plans is the next step.
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Visual Companion
+
+A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
+
+**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
+> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
+
+**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
+
+**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
+
+- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
+
+A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
+
+If they agree to the companion, read the detailed guide before proceeding:
+`skills/brainstorming/visual-companion.md`