summer-engine 2.3.0 → 2.6.0

package/skills/3d-assets/prop-model/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
 paths: ["assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -37,7 +37,7 @@ The backing tool is `summer_generate_3d`. Default model is `hunyuan` (Hunyuan 3D
 ### 1. Search before generating
 
 ```
-summer_search_assets(query="<prop name>", filter={ kind: "model" })
+summer_search_assets(query="<prop name>", assetType="3d_model", source="all")
 ```
 
 If a fitting model exists, propose reuse:
@@ -83,25 +83,33 @@ summer_generate_3d(
 )
 ```
 
-Returns `{ asset: { fileUrl }, ... }`.
+Returns a job result with `assetId` and `fileUrl`. Treat `assetId` as the
+stable handle and `fileUrl` as a fallback preview/import URL.
 
 ### 5. Import and wire
 
 ```
-summer_import_from_url(url="<fileUrl>", path="res://assets/models/viking_axe.glb")
-summer_add_node(parent="./World/Props", type="MeshInstance3D", name="VikingAxe")
-summer_set_prop(path="./World/Props/VikingAxe", property="mesh", value="res://assets/models/viking_axe.glb")
+summer_get_asset(assetId="<assetId>")
+summer_import_asset_by_id(
+  assetId="<assetId>",
+  path="res://assets/models/viking_axe.glb",
+  parent="./World/Props",
+  name="VikingAxe"
+)
 summer_save_scene
 ```
 
-For interactive props (chest the player opens, lantern the player picks up), wrap the MeshInstance3D in a `StaticBody3D` (or `RigidBody3D` for physics props) with a `CollisionShape3D` sibling — see `summer:scene-composition` for the parent-shape pattern.
+For interactive props (chest the player opens, lantern the player picks up),
+wrap the instantiated model in a `StaticBody3D` (or `RigidBody3D` for physics
+props) with a `CollisionShape3D` sibling — see `summer:scene-composition` for
+the parent-shape pattern.
 
 ## Anti-patterns
 
 - **Scene context in the prompt.** "A sword lying on a wooden table" → the table becomes geometry. Always say `isolated object`.
 - **Multi-object prompts.** "A sword and a shield" → fused single mesh. Generate separately.
 - **Skipping `target_polycount` for background props.** A 30k-tri barrel in the background tanks frame rate when the level has 50 of them.
-- **Forgetting to import.** `fileUrl` from `summer_generate_3d` is a remote URL — you MUST `summer_import_from_url` before referencing it as `res://...`.
+- **Forgetting to import.** `fileUrl` from `summer_generate_3d` is a remote URL — you MUST `summer_import_asset_by_id` or `summer_import_from_url` before referencing it as `res://...`.
 - **Generating before searching.** Reuse beats regenerate every time.
 - **Picking `meshy` by default.** It's legacy. `hunyuan` is better; `trellis` is faster.
 
@@ -130,4 +138,4 @@ After the prop is wired:
 - `summer:asset-pipeline/asset-strategy` — the meta-router that decides between this skill and Pipeline 2 (textures).
 - `summer:3d-assets/character-model` — for humanoids.
 - `summer:3d-assets/environment-kit` — for style-locked sets.
-- `_shared/mcp-tools-reference.md` — `summer_generate_3d` parameter schema.
+- `references/mcp-tools-reference.md` — `summer_generate_3d` parameter schema.

package/skills/3d-assets/vehicle-model/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
 user-invocable: true
-allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene
 paths: ["assets/vehicles/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 ---
 
@@ -69,7 +69,7 @@ If the user has reference images already (concept art, photos), prefer those —
 ### 1. Search before generating
 
 ```
-summer_search_assets(query="<vehicle type>", filter={ kind: "model" })
+summer_search_assets(query="<vehicle type>", assetType="3d_model", source="all")
 ```
 
 ### 2. Pick model and polycount
@@ -101,7 +101,8 @@ summer_generate_3d(
   options={ target_polycount: 25000 },
   wait=true
 )
-summer_import_from_url(url="<fileUrl>", path="res://assets/vehicles/race_car.glb")
+summer_get_asset(assetId="<assetId>")
+summer_import_asset_by_id(assetId="<assetId>", path="res://assets/vehicles/race_car.glb")
 ```
 
 ### 5. Inspect for hard-surface artifacts
@@ -199,4 +200,4 @@ After the vehicle is wired:
 - `summer:3d-assets/prop-model` — for separable parts (rotors, decals as decals, modular kit pieces).
 - `summer:asset-pipeline/asset-strategy` — meta-router.
 - `summer:character-controllers` — for player-driven vehicle input wiring.
-- `_shared/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.
+- `references/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.

package/skills/README.md

@@ -7,32 +7,45 @@ When an agent is asked to make a game in Summer Engine, this is what it reads to
 ## Layout
 
 ```
-skills/
-├── README.md                  # this file
-├── catalog.yaml               # canonical registry (name, category, status, template-id)
-├── _shared/                   # cross-skill references every skill can link
+summer-cli/
+├── .claude-plugin/plugin.json    # the registry (skills: array). Sibling Codex/Cursor manifests mirror it.
+├── references/                   # cross-skill shared docs (sibling of skills/)
 │   ├── godot-version.md
 │   ├── mcp-tools-reference.md
 │   ├── collaborative-protocol.md
 │   ├── template-registry.md
+│   ├── summer-folder.md
 │   └── gd-style.md
-├── _meta/
-│   ├── skill-test/            # static + behavioral linter
-│   ├── skill-create/          # bootstrap a new skill
-│   └── skill-improve/         # eval-harness iteration
-├── _tests/
-│   ├── runner.md              # how /skill-test works
-│   └── specs/                 # behavioral specs per skill
-└── <category>/<skill>/
-    ├── SKILL.md               # < 500 lines, frontmatter + body
-    ├── references/            # loaded on demand
-    ├── examples/              # working snippets
-    └── tests/spec.md          # behavioral spec
+├── tests/
+│   ├── runner.md                 # how /skill-test works
+│   └── specs/                    # behavioral specs per skill
+└── skills/
+    ├── README.md                 # this file
+    ├── workflow/                 # process skills (brainstorming, debugging, planning, etc.)
+    │   ├── using-summer/
+    │   ├── skill-create/
+    │   ├── skill-improve/
+    │   ├── skill-test/
+    │   ├── brainstorming/
+    │   ├── investigating-bugs/
+    │   ├── verification-before-completion/
+    │   ├── writing-plans/
+    │   ├── dispatching-parallel-agents/
+    │   ├── writing-skills/
+    │   ├── playtesting-a-feature/
+    │   ├── debugging-game-feel/
+    │   └── diagnosing-perf-regressions/
+    └── <category>/<skill>/       # gamedev domain skills
+        ├── SKILL.md              # < 500 lines, frontmatter + body
+        ├── reference.md          # optional, loaded on demand
+        └── examples/             # optional, working snippets
 ```
 
-## Categories (20)
+## Categories (21)
 
-`character-controllers`, `gameplay-mechanics`, `scripting-patterns`, `scene-and-project`, `rendering-and-lighting`, `shaders`, `visual-effects`, `post-processing`, `animation`, `audio`, `physics`, `multiplayer-and-networking`, `ai-and-npcs`, `level-design`, `performance`, `ui-and-ux`, `asset-pipeline`, `input-and-controls`, `debugging`, `deployment`.
+`workflow` (process discipline) plus 20 gamedev domains: `character-controllers`, `gameplay-mechanics`, `scripting-patterns`, `scene-and-project`, `rendering-and-lighting`, `shaders`, `visual-effects`, `post-processing`, `animation`, `audio`, `physics`, `multiplayer-and-networking`, `ai-and-npcs`, `level-design`, `performance`, `ui-and-ux`, `asset-pipeline`, `input-and-controls`, `debugging`, `deployment`.
+
+Folder structure is for humans only — Claude resolves skills as `summer:<skill-name>` regardless of category nesting.
 
 ## Standard
 
@@ -45,7 +58,7 @@ description: <when-to-use, key trigger phrases first>
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: <one of the 20>
-template-id: <optional, resolved against _shared/template-registry.md>
+template-id: <optional, resolved against references/template-registry.md>
 allowed-tools: Read Grep summer_add_node summer_set_prop ...
 paths: ["**/*.gd", "**/*.tscn"]
 ---
@@ -57,7 +70,7 @@ Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
 
 1. **SKILL.md ≤ 500 lines.** Push detail into `references/`. Progressive disclosure.
 2. **MCP-preferred + file-edit-fallback.** Every code-touching skill must show both paths so the skill works without Summer MCP installed.
-3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `_shared/collaborative-protocol.md`.
+3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `references/collaborative-protocol.md`.
 4. **Template cross-link.** When a working starter exists, link via `template-id` and the section "Want a working starter?".
 5. **Test spec.** Every non-`_meta` skill ships `tests/spec.md` with at least one Test Case.
 
@@ -67,7 +80,7 @@ Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
 /skill-create
 ```
 
-(See `_meta/skill-create/SKILL.md`.)
+(See `workflow/skill-create/SKILL.md`.)
 
 ## Testing
 
@@ -78,17 +91,11 @@ Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
 /skill-improve <name>        # parallel-eval harness for iteration
 ```
 
-(See `_meta/skill-test/SKILL.md` and `_tests/runner.md`.)
-
-## Roadmap
-
-Status legend in `catalog.yaml`:
+(See `workflow/skill-test/SKILL.md` and `tests/runner.md`.)
 
-- **HAVE** — ships today.
-- **NEXT** — next wave, in active development.
-- **LATER** — on roadmap.
+## What ships today
 
-Currently: **7 HAVE / ~50 NEXT / ~30 LATER ≈ 85 skills across 20 categories**. Subagents fill content category by category.
+The `skills:` array in `.claude-plugin/plugin.json` is the registry — what ships, ships there. New skills are added via `/skill-create` (see `workflow/skill-create/SKILL.md`).
 
 ## See also
 

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

@@ -22,6 +22,8 @@ Character (CharacterBody3D)
 └── AnimationTree              # references AnimationPlayer, drives behavior
 ```
 
+Before adding the tree, prove direct `AnimationPlayer.play()` visibly moves the rig. Godot may import animation GLBs as `AnimationLibrary` resources or as `PackedScene`s with embedded `AnimationPlayer`s. If a copied clip appears in the list but the mesh T-poses, its tracks probably target a different root/skeleton path. Use the embedded player that came with the matching GLB, or remap/copy tracks only after confirming they target the active `Skeleton3D`. An inactive AnimationTree is also a no-op, so always set `AnimationTree.active = true`.
+
 ## When to use this skill
 
 - Character has 3+ clips and switching between them via `AnimationPlayer.play("walk")` is causing pops, T-poses, or "starts halfway through".
@@ -256,5 +258,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

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
 user-invocable: false
-allowed-tools: Read Grep summer_search_assets summer_generate_motion summer_inspect_resource summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
+allowed-tools: Read Grep summer_search_assets summer_list_my_assets summer_get_asset summer_get_asset_download_url summer_generate_motion summer_inspect_resource summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
 paths: ["**/*.tscn", "**/*.tres", "**/*.gd"]
 ---
 
@@ -17,6 +17,22 @@ The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `
 
 > **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on the roadmap but not shipped yet. For one-off signature moves not on the curated list, fall back to hand-authoring in the Godot editor or importing from Mixamo. See the Edge cases section.
 
+## Web Chat / Public Orchestrator Equivalent
+
+In PublicSummerEngine chat, the equivalent direct tools are:
+
+```
+rigModel({ modelAssetId })
+generateAnimation({ rigAssetId, animationName })
+meshyJobStatus({ jobId })
+```
+
+If the character came from `createCharacter`, it may already be rigged and have `metadata.meshyRigTaskId`; generate animations directly against that rig asset. Verified animation names from the recovered production flow are `idle`, `walk`, `run`, `jump`, and `attack`. `fall` returned `invalid_animation`, so do not present it as a default.
+
+Before generating clips in PublicSummerEngine chat, confirm the rig asset listing/status exposes `hasMeshyRigTask` or `animationsReady:true`. If `generateAnimation` returns `animations_preparing`, wait, poll/list the rig again, and retry; this is the post-rig setup catching up, not a reason to send the user to Studio.
+
+After animation jobs complete, import the rig plus child animation assets together and wire them through `import-character`. Do not hand off to Studio unless the user asked for Studio/manual control or the direct chat tools fail.
+
 ## When to use this skill
 
 - "Add a walk animation to the goblin."
@@ -38,7 +54,7 @@ The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `
 ### 1. Verify the target is a rigged humanoid
 
 ```
-summer_search_assets(query="<character name>", kind="model")
+summer_search_assets(query="<character name>", assetType="3d_model", source="my_assets")
 ```
 
 The result must include `rigAssetId: <id>` on a Meshy rig. If it shows `rigAssetId: null`, the model isn't rigged — stop, propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` first (the result includes `rigAssetId`), or route to `summer:asset-pipeline/asset-strategy`.
@@ -57,7 +73,12 @@ summer_generate_motion(
 )
 ```
 
-Returns `{ animationAssetId, durationSeconds, previewUrl }`.
+Returns `animationAssetId`, `durationSeconds`, and `previewUrl`. Resolve the
+asset before handoff so you have the stable file/download metadata:
+
+```
+summer_get_asset(assetId="<animationAssetId>")
+```
 
 ### 4. Attach to the character's AnimationPlayer
 
@@ -99,7 +120,7 @@ The full list is ~70 names. If the user asks for something not on the top-30, tr
 ## Anti-patterns
 
 - Calling `summer_generate_motion` on a `.glb` that wasn't rigged — wastes a generation; the API errors but only after 30s.
-- Generating the same clip twice because you forgot to save the `animationAssetId` from the first call. Search the asset library first: `summer_search_assets(query: "goblin run", kind: "animation")`.
+- Generating the same clip twice because you forgot to save the `animationAssetId` from the first call. Search the asset library first: `summer_search_assets(query: "goblin run", assetType: "animation", source: "my_assets")`.
 - Wiring clips into an AnimationTree inside this skill. That's the next skill's job. Generate, attach, hand off.
 - Asking the model to invent a `motionName` that isn't on the list. Quote from the list verbatim, or fall back to manual authoring.
 
@@ -123,7 +144,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/asset-pipeline/asset-strategy/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: asset-pipeline
 user-invocable: false
-allowed-tools: Read Grep Skill summer_search_assets
+allowed-tools: Read Grep Skill summer_search_assets summer_list_my_assets summer_get_asset summer_import_asset_by_id
 ---
 
 # Asset Strategy — Meta-Router for Asset Creation
@@ -117,7 +117,8 @@ VFX is **code, not generative** — recipes are shader + GDScript + node setup,
 
 - The user already named the specific skill — go straight there.
 - The user is debugging or running the game — route to `summer:debug` or `summer:play`.
-- The asset is being imported, not generated (existing `.glb` / `.wav` from Sketchfab, Quaternius, AmbientCG) — call `summer_import_from_url` directly.
+- The asset is an existing Summer asset ID — call `summer_get_asset`, then `summer_import_asset_by_id`.
+- The asset is being imported from a non-Summer URL (`.glb` / `.wav` from Sketchfab, Quaternius, AmbientCG) — call `summer_import_from_url` directly.
 - The user wants to plan the whole game's asset list — `summer:brainstorm-game` first, then this router on each item.
 
 ## Anti-patterns

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)