summer-engine 2.8.1 → 3.0.0

package/library/skills/realtime-wet-surfaces/resource.yaml

@@ -0,0 +1,31 @@
+id: skill/realtime-wet-surfaces
+kind: skill
+version: 0.1.1
+summary: "Real-time wetness on existing Godot 4 materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount."
+use_when:
+  - "make surfaces look wet when it rains and dry off afterwards"
+  - "add rain wetness to the level without redoing every material"
+  - "darken and gloss up the ground after rain, driven by a weather system"
+  - "wet cave, shoreline, or post-rain look on existing PBR materials"
+do_not_use_when:
+  - "transparent or unshaded materials, water bodies, or puddle simulation — this targets opaque PBR surfaces"
+  - "intake from the gamedev-knowledge pipeline (source-cited, pipeline-validated, not yet exercised in-engine by the Summer team) — verify results in the engine as you would any technique"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - rendering
+    - vfx
+  modalities:
+    - shaders
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/vfx-water-ripple
+    - skill/3d-lighting
+source: official
+license: MIT
+status: preview
+recommended: false

package/{skills/deployment → library/skills}/remote-deploy/SKILL.md

@@ -31,9 +31,9 @@ It is **not** the same as two neighbours:
 |---|---|---|
 | **Play** (▶) | Runs in the editor (embedded or windowed) | Fast iteration on the dev machine |
 | **Remote Deploy** | Debug build → installs + runs on a device, remote-debugged | Testing real input/perf/screen on hardware |
-| **export-and-ship** (`summer:export-and-ship`) | Supported local release builds | Preparing an artifact for a separate user-controlled distribution workflow |
+| **export-and-ship** (`export-and-ship`) | Supported local release builds | Preparing an artifact for a separate user-controlled distribution workflow |
 
-If the user wants a release build for Steam / itch / the App Store, that is `summer:export-and-ship`, not this.
+If the user wants a release build for Steam / itch / the App Store, that is `export-and-ship`, not this.
 
 ## Where it is in the UI
 
@@ -125,7 +125,7 @@ never replaces the proof.
 
 ## Common mistakes
 
-- **Confusing it with shipping.** Remote Deploy makes *debug* builds for testing. Store/distribution builds are `summer:export-and-ship`.
+- **Confusing it with shipping.** Remote Deploy makes *debug* builds for testing. Store/distribution builds are `export-and-ship`.
 - **Preset exists but isn't Runnable** → button stays greyed. The Runnable toggle is the gate, not the preset's existence.
 - **Expecting it to work without export templates** → button may be enabled (device detected) but the deploy then fails in the result dialog. Install templates.
 - **Android device `unauthorized`** in `adb devices` → the device won't show as a target. Re-accept the USB-debugging prompt on the phone.

package/library/skills/remote-deploy/resource.yaml

@@ -0,0 +1,23 @@
+id: skill/remote-deploy
+kind: skill
+version: 1.0.2
+summary: Run or test the game on a real device — phone, tablet, another computer — via the Remote Deploy button, runnable export presets, and on-device debugging.
+use_when:
+  - the user wants to run or test the game on a real target instead of the editor — a phone, tablet, or another computer
+  - the Remote Deploy button is greyed out and the user wants to know why
+facets:
+  lifecycle:
+    - launch
+  domains:
+    - deployment
+    - project
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/deployment/remote-deploy

package/{skills/animation → library/skills}/retarget/SKILL.md

@@ -15,8 +15,7 @@ paths: ["**/*.tscn", "**/*.tres"]
 
 Summer ships **no** `summer_retarget_motion` tool, and no other MCP tool that
 re-projects an existing animation asset onto a second rig. Verify it yourself:
-`grep -rn 'summer_' tools/summer-cli/src/mcp/tools/*.ts` lists every registered
-tool and there is no retarget entry. Never call one — the MCP server rejects
+`summer tool --list` prints every registered tool and there is no retarget entry. Never call one — the MCP server rejects
 unknown tool names outright, and inventing a cost table for it ("$0.05 a clip")
 is worse than saying nothing.
 
@@ -39,8 +38,8 @@ retarget API that does not exist; the honest math is below.
 
 ## When NOT to use this skill
 
-- The user wants ONE new clip on ONE character — just call `summer:animation/generate-motion`.
-- The user wants to retime, edit, or layer the animation — that's `summer:animation/animation-tree` and the `summer:animation/procedural-animation` additive layers.
+- The user wants ONE new clip on ONE character — just call `generate-motion`.
+- The user wants to retime, edit, or layer the animation — that's `animation-tree` and the `procedural-animation` additive layers.
 - Target is a quadruped or non-humanoid (wings-only, mech, blob). The curated Meshy
   library is humanoid-only and `SkeletonProfileHumanoid` is a humanoid profile.
   Hand-author instead.
@@ -67,7 +66,7 @@ summer_search_assets(query: "<target character>", assetType: "3d_model", source:
 
 Confirm a `rigAssetId` is present. If it is null the model was never rigged —
 stop and propose `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })`
-first, or route to `summer:asset-pipeline/asset-strategy`.
+first, or route to `asset-strategy`.
 
 ### 3. Confirm with user before spending
 
@@ -167,7 +166,7 @@ same rigged `.glb`, nothing needs retargeting — instance the scene.
   humanoid profile.
 - **Proportion mismatch.** A library authored on a 1.8m humanoid on a 2.5m ogre
   runs, but you get foot-float and limb-twist. Layer foot IK afterwards — see
-  `summer:animation/procedural-animation`.
+  `procedural-animation`.
 
 ### Quality bar
 
@@ -188,7 +187,7 @@ same rigged `.glb`, nothing needs retargeting — instance the scene.
 ## Edge cases
 
 - **Source has facial blendshape tracks.** Skeleton retargeting only handles
-  bones. Facial tracks do not transfer. Hand off to `summer:animation/facial-and-lipsync`
+  bones. Facial tracks do not transfer. Hand off to `facial-and-lipsync`
   to re-author per character.
 - **Target rig is a different Meshy skeleton generation.** Symptom: bone-count
   mismatch even though both are Meshy. Re-rig the target with a fresh
@@ -207,14 +206,16 @@ Documented in the Godot 4.x "Retargeting 3D Skeletons" docs.
 ## Handoff
 
 - After the clips are on the target, the wiring is identical to a freshly-generated
-  clip — hand off to `summer:animation/animation-tree` for state-machine integration.
+  clip — hand off to `character-animation-wiring` for the end-to-end
+  path (inspect the target's real clip/bone names first — retargeted imports rename
+  things), or `animation-tree` for blend-space/overlay graph design.
 - If the result shows foot-clipping or hand-pen-through-prop issues, hand off to
-  `summer:animation/procedural-animation` for IK correction.
-- For NPC behavior driving these clips, hand off to `summer:ai-and-npcs/design-npc`.
+  `procedural-animation` for IK correction.
+- For NPC behavior driving these clips, hand off to `design-npc`.
 
 ## See also
 
-- `summer:animation/generate-motion` — the tool that actually produces clips, and the curated name list.
-- `summer:asset-pipeline/asset-strategy` — getting characters rigged in the first place.
-- `summer:animation/animation-tree` — wire the clips into a state machine.
-- `summer:animation/procedural-animation` — fix proportional mismatches with foot IK.
+- `generate-motion` — the tool that actually produces clips, and the curated name list.
+- `asset-strategy` — getting characters rigged in the first place.
+- `animation-tree` — wire the clips into a state machine.
+- `procedural-animation` — fix proportional mismatches with foot IK.

package/library/skills/retarget/resource.yaml

@@ -0,0 +1,33 @@
+id: skill/retarget
+kind: skill
+version: 1.0.3
+summary: Apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration.
+use_when:
+  - applying existing animation clips from one rigged character to a different rigged character — sharing one animation library across models
+  - the same clips must play on several differently proportioned rigs without regenerating them
+facets:
+  lifecycle:
+    - build
+  domains:
+    - animation
+    - 3d
+  modalities:
+    - animation
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/character-animation-wiring
+    - skill/design-npc
+    - skill/animation-tree
+    - skill/facial-and-lipsync
+    - skill/generate-motion
+    - skill/procedural-animation
+    - skill/asset-strategy
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/animation/retarget

package/library/skills/running-in-the-cloud/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: running-in-the-cloud
+description: Use when Summer Engine runs in a cloud container, CI job, remote agent sandbox, or any Linux box with no desktop — installing the engine there, launching it headless, deciding when xvfb-run and software GL are required, and authenticating without a browser. Also use when a tool reports "engine not running" in an environment that has no display, or when SUMMER_ENGINE_BINARY / SUMMER_TOKEN come up.
+---
+
+# Running in the Cloud
+
+## Overview
+
+Summer Engine runs fine on a Linux machine with no display and no human. Everything in this skill was measured in a real cloud container: headless engine boots, MCP tools answer, and renders work under xvfb + llvmpipe.
+
+Three facts carry the whole setup:
+
+1. **Local engine ops need no login.** The engine mints its own API token (`~/.summer/api-token`, per-instance tokens in `~/.summer/instances/*.json`) on every launch. Scene mutation, inspection, play, diagnostics, headless scripting — all of it works with zero accounts.
+2. **Only gateway features need a credential** — asset search, asset/image/3D generation, releases. In the cloud, pass it as an env var instead of a browser login.
+3. **Most containers have no GPU and no Vulkan.** Pure headless work does not care. Anything that produces pixels needs a virtual display and software GL.
+
+## Install the engine
+
+`summer install` on Linux (x86_64) resolves in this order:
+
+| Priority | Source | When |
+|---|---|---|
+| 1 | `SUMMER_ENGINE_BINARY=<abs path>` | The container already carries a prebuilt engine binary (for example a source build's `bin/godot.linuxbsd.editor.x86_64`). Registers that binary — no download. |
+| 2 | `SUMMER_ENGINE_URL=<url>` | Download any artifact URL: `.tar.gz`, `.zip`, or a raw executable. |
+| 3 | (default) | The newest published Linux release artifact (`Summer-linux-x86_64-<tag>.tar.gz`). |
+
+All three register the binary at `~/.summer/engine/summer-linux-x86_64`, which is where `summer run` and `summer doctor` look. `SUMMER_ENGINE_BINARY` is also honored directly at lookup time, so setting the env var alone (without ever running `summer install`) is enough for `summer doctor` to report the engine as installed.
+
+```bash
+# Container with a prebuilt binary — today's cloud unlock:
+export SUMMER_ENGINE_BINARY=/abs/path/to/engine-binary
+summer install      # registers it; summer doctor now shows Engine: ok
+```
+
+`summer doctor` is the readiness check: Engine, Local API, MCP tools. "Login: not signed in" is a warning, not a blocker — engine ops do not need it.
+
+## Launch headless
+
+```bash
+<engine-binary> --headless --editor --path <project-dir>
+```
+
+That boots the real editor — import pipeline, local API server, MCP reachability — with no window and no display. Give it a few seconds, then `summer doctor` should show `Local API: :6550`.
+
+- One-shot work (bake, import, export, scripted authoring) uses `--headless ... -s res://script.gd` — load `headless-scripting`, it is the authoritative guide including the crash-handler flag and the exit-code traps.
+- **Boot → act → exit.** A long-lived headless editor never rescans the filesystem; it serves a boot-time snapshot forever.
+
+### Instance discovery
+
+Every running editor writes `~/.summer/instances/<id>.json` — pid, port, token, project root, heartbeat. The CLI and MCP discover engines through those files; stale entries (dead pid, old heartbeat) are ignored automatically. In a container you can read them yourself to find the port/token for raw HTTP against `http://127.0.0.1:<port>/api/...`.
+
+## Pixels: when you need xvfb-run + software GL
+
+`--headless` uses the dummy renderer: **no pixels, ever**. Any path that renders an image needs a real (virtual) display:
+
+| Needs xvfb + GL | Pure headless is fine |
+|---|---|
+| `summer_screenshot` scene previews (ScenePreview images) | Scene mutation, inspection, scene tree reads |
+| GameSnapshot / viewport captures | Diagnostics, script errors, console |
+| RunVerification frames (`--summer-verify` probes) | Imports, exports, navmesh/collision baking |
+| Anything judged by looking at a frame | Play/stop, project context, file ops |
+
+Most cloud containers have no Vulkan device. The working recipe is X virtual framebuffer plus Mesa's software rasterizer (llvmpipe), driving the GL compatibility renderer:
+
+```bash
+apt-get install -y xvfb libgl1-mesa-dri   # names vary by distro
+xvfb-run -a <engine-binary> --path <project-dir> --rendering-driver opengl3 ...
+```
+
+Honest limitations:
+
+- **No Vulkan in most containers** → Forward+/Mobile renderers are unavailable; you get software GL (Compatibility). Colors and composition are trustworthy; GPU-specific effects, performance numbers, and driver-dependent output are not.
+- Software rendering is slow. Budget seconds per frame, not milliseconds, and never quote FPS measured this way.
+- If a render tool returns a null/blank image in a container, check for a display before suspecting the scene: no `$DISPLAY` means no pixels.
+
+## Authentication without a browser
+
+- **Engine ops: nothing to do.** The local API token is auto-generated; `summer login` is never required for them.
+- **Gateway features** (asset search, generation, releases): set `SUMMER_TOKEN` to a CLI token from a logged-in machine (`~/.summer/auth-token`). It overrides the stored file for that process only.
+
+```bash
+export SUMMER_TOKEN="$(cat ~/.summer/auth-token)"  # gateway: assets/generation/releases
+```
+
+Treat it as a secret: env-inject it from the runner's secret store, never bake it into images or logs. Without it, gateway tools fail with a clear "not signed in" message — everything else keeps working.
+
+## Red Flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| "Linux isn't supported, download manually" | `summer install` supports Linux x86_64; set `SUMMER_ENGINE_BINARY` when the container has its own build. |
+| Running `summer login` in a container | There is no browser. Engine ops need no login; gateway needs `SUMMER_TOKEN`. |
+| Screenshot/preview attempted under plain `--headless` | Dummy renderer, null image. Use `xvfb-run` + `--rendering-driver opengl3`. |
+| Expecting Forward+ output in a container | No Vulkan device in most containers. Software GL (Compatibility) is what you get. |
+| Quoting performance numbers from a software-GL run | llvmpipe measures the CPU, not the game. |
+| Polling the engine before it finished booting | Give it seconds; watch `summer doctor` / `~/.summer/instances/`. |
+| Baking a token into an image or committing it | Tokens are secrets. Env-inject at runtime. |
+
+**Related skills:**
+- `headless-scripting` — the headless invocation contract, exit-code traps, and what scripts unlock.
+- `playtesting-a-feature` — the verify instance and probes (run them under xvfb in the cloud).
+- `verification-before-completion` — judging work by artifacts, which matters double when nobody can see a screen.

package/library/skills/running-in-the-cloud/resource.yaml

@@ -0,0 +1,33 @@
+id: skill/running-in-the-cloud
+kind: skill
+version: 1.0.3
+summary: Run Summer Engine on a Linux box with no display — install it, launch headless, know when xvfb + software GL are needed, authenticate without a browser.
+use_when:
+  - Summer Engine runs in a cloud container, CI job, remote agent sandbox, or any Linux machine with no desktop
+  - installing the engine on Linux, or a tool reports "engine not running" in an environment that has no display
+  - deciding whether a render path (screenshots, previews, verification frames) needs xvfb-run and software GL
+  - SUMMER_ENGINE_BINARY, SUMMER_ENGINE_URL, or SUMMER_TOKEN come up
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - project
+  modalities:
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/headless-scripting
+    - skill/playtesting-a-feature
+    - skill/verification-before-completion
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/workflow/running-in-the-cloud
+lint_exceptions:
+  - install-command
+  - credential-pattern
+lint_exception_reason: "Linux CI prerequisites: `apt-get install xvfb` is a documented, user-run setup step for headless engines (not agent-autonomous), and `export SUMMER_TOKEN=...` documents Summer's own auth env var — no third-party credential is referenced."

package/{skills/scene-and-project → library/skills}/scene-composition/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-composition
-description: Use when building or organizing Summer Engine scenes: node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy", "scene structure", "PackedScene".
+description: "Use when building or organizing Summer Engine scenes: node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions. Trigger on \"scene\", \"sub-scene\", \"instance\", \"prefab\", \"node hierarchy\", \"scene structure\", \"PackedScene\"."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
@@ -101,6 +101,14 @@ Use `./` for paths relative to the scene root:
 - Save-as: `summer_save_scene(scenePath="res://main.tscn", path="res://scenes/level1.tscn")`
 - Plain save: `summer_save_scene(scenePath="res://main.tscn")` — `scenePath` is required in both forms
 
+## Spatial Placement
+
+When a 3D prop, character, collider, platform, wall-mounted object, shelf item,
+or tight-space asset must sit flush, avoid overlap, or preserve clearance, load
+the `spatial-placement` skill. Follow its inspect -> place -> Starcast -> correct
+-> verify loop instead of judging precise placement from transforms or a
+screenshot alone.
+
 ## Common Mistakes
 
 1. **Wrong parent path:** `./NonExistent` fails. Ensure the parent exists before adding children.

package/library/skills/scene-composition/resource.yaml

@@ -0,0 +1,27 @@
+id: skill/scene-composition
+kind: skill
+version: 1.0.3
+summary: Scene structure conventions — node hierarchy, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions.
+use_when:
+  - "building or organizing Summer Engine scenes: node hierarchy conventions, sub-scene extraction, prefab patterns, PackedScene decisions"
+  - deciding whether to extract a sub-scene, instance a prefab, or add nodes inline as a scene grows
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - project
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/spatial-placement
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/scene-and-project/scene-composition

package/library/skills/scene-hierarchy-design/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: scene-hierarchy-design
+description: "Use when applying data-oriented hierarchy principles (from Sander Mertens' ECS hierarchies article) to structure Summer Engine scenes: split asset vs. live hierarchies, group by dominant access pattern, use sub-scenes for reuse, and keep logic path-agnostic via MCP scene tools."
+license: MIT
+category: workflow
+tags:
+  - scenes
+  - hierarchy
+  - composition
+  - ecs
+confidence: extracted
+adaptation: translated
+---
+
+# Scene Hierarchy Design for Summer Engine (Data-Oriented Principles)
+
+## Outcome
+
+Scenes in Summer Engine (Godot-based) that are organized by **access pattern**, not by accident: clear separation between reusable asset scenes (`.tscn` prefabs) and the live node tree, wrapper grouping where whole subtrees are operated on together, flat siblings where type-wide queries dominate, and gameplay logic that does not depend on deep fragile node paths.
+
+## When to Use
+
+- Structuring a new scene (level, character, prop cluster, UI screen) from scratch.
+- Reorganizing a scene that has grown ad hoc (long chains, duplicate setups, hard-to-delete clusters).
+- Deciding whether a setup belongs inline or as a separate sub-scene.
+- Reviewing whether existing scenes match the dominant operations the game performs on them (spawn/despawn clusters, iterate all of a type, move single nodes).
+
+Do not use this for shader/material work, asset import mechanics, or gameplay tuning — it is purely about hierarchy shape.
+
+## Core Principle (translated)
+
+Sander Mertens' ECS article evaluates hierarchies on two axes and both translate directly:
+
+1. **Usability: two hierarchy kinds must compose.** *Asset hierarchies* (inheritance, variations, property overrides → Godot `.tscn` sub-scenes and scene inheritance) and *scene hierarchies* (live parent-child relations → the node tree). A scene that repeatedly rebuilds the same inline cluster is missing its asset hierarchy; an asset scene nobody instantiates is dead weight.
+2. **Performance: match structure to dominant access patterns.** Group nodes stored/operated together under one parent (subtree operations become one operation); keep nodes queried independently as flat siblings. There is no universally optimal depth — analyze usage before picking one.
+3. **Hierarchy-agnostic logic.** The article's hybrid design keeps application code independent of storage; the Summer translation is: scripts and agents should not hardcode deep paths. Use groups, signals, and exported `NodePath` references instead of long ancestor chains.
+
+## Summer Engine Integration
+
+Scene hierarchy features from the article map onto Summer MCP tools as follows:
+
+| Feature (article) | Summer Engine tool |
+|---|---|
+| Instantiate assets | `summer_instantiate_scene` |
+| Recursively despawn | `summer_remove_node` on the wrapper parent (removes the subtree) |
+| Reparent children | `summer_remove_node` + `summer_add_node`/`summer_instantiate_scene` under the new parent |
+| Iterate the live hierarchy | `summer_get_scene_tree` (always read before mutating) |
+| Lookup by name | descriptive, unique node names resolved from `summer_get_scene_tree` |
+
+Recommended scene shape — group by operation, name by role:
+
+```
+World (Node3D)                  # scene root
+├── Camera3D                    # unique to this scene → inline
+├── DirectionalLight3D          # unique → inline
+├── Level (Node3D)              # wrapper: geometry operated as one subtree
+├── Props (Node3D)              # wrapper: spawn/despawn clusters together
+│   ├── Crate_01 (instance of res://scenes/props/crate.tscn)
+│   └── Barrel_01 (instance)
+├── Enemies (Node3D)            # wrapper: recursive clear of all enemies
+│   └── Grunt_01 (instance of res://scenes/enemies/grunt.tscn)
+└── Player (instance of res://scenes/player.tscn)
+```
+
+Rules of thumb:
+
+- **Wrapper node per operation boundary.** If you ever need to "remove all enemies", "hide all props", or "rebuild the level", they share one parent; the operation becomes a single node op.
+- **Sub-scene per reusable setup.** Same cluster appearing twice or more → extract to its own `.tscn` and instantiate. One-offs (main camera, a level-specific light) stay inline.
+- **Flat over deep.** Every extra level of nesting adds path length and fragility. Prefer named sibling containers over long chains.
+- **Unique descriptive names.** Godot auto-renames duplicates (`Node`, `Node2`); that breaks name lookup. Name by role and index (`Crate_01`).
+- **Never mix 2D under 3D** (or vice versa) in one hierarchy.
+
+## Agent Procedure
+
+Follow the canonical scene loop from the Summer MCP reference: route → orient → read rules → resolve `scenePath` → mutate → verify.
+
+1. **Orient.** `summer_start_game_task` to route the goal; `summer_get_project_context`; `summer_get_agent_playbook`.
+2. **Read before writing.** `summer_get_scene_tree` on the exact `res://...tscn`. Never mutate blind, and never edit `.tscn` text while the engine is running — use the MCP tools.
+3. **Pick the access pattern.** For each planned cluster decide: operated as a subtree (→ wrapper parent), queried by type across the scene (→ flat siblings + group), or unique (→ inline under root container).
+4. **Build asset hierarchies first.** For reusable setups create the sub-scene (`summer_create_scene` / build inline then `summer_save_scene(scenePath="res://main.tscn", path="res://scenes/<name>.tscn")`), then bring them in with `summer_instantiate_scene(scenePath="res://main.tscn", parent="./<Wrapper>", scene="res://scenes/<name>.tscn", name="<Role>_01")`.
+5. **Add inline nodes** with `summer_add_node(parent="./<Wrapper>", type="...", name="...", scenePath="res://main.tscn")`. Parent paths are relative with the `./` prefix (`./`, `./World/Props`); never `/World` or bare `World`.
+6. **Keep logic path-agnostic.** When a script must reach another node, add it to a group or export a `NodePath`/signal connection (`summer_connect_signal`) rather than hardcoding `./World/Enemies/Grunt_01/Weapon`.
+7. **Every mutation names its target.** Pass the exact `scenePath` to every add/set/remove/instantiate call. Dedicated mutation tools append one final save; use `summer_save_scene` only for save-as or an explicit flush.
+8. **Verify.** `summer_get_script_errors`, then `summer_get_scene_tree` again to confirm the intended shape; `summer_screenshot` (editor viewport) for visual confirmation; `summer_play` → `summer_get_debugger_errors` → `summer_stop` only when runtime behaviour matters.
+
+## Failure Modes
+
+- **Deep fragile paths in scripts.** Hardcoded ancestor chains break on any reorganization; this is the direct analogue of the article's warning against logic coupled to hierarchy storage. Use groups/signals/exported paths.
+- **Inline duplication instead of sub-scenes.** The same 5-node cluster rebuilt in three levels → edits must be made three times, and despawn/iteration must enumerate each copy. Extract the asset hierarchy.
+- **Over-grouping.** Wrapping every node in its own container adds depth without enabling any operation. Group only where a real subtree operation exists.
+- **Duplicate/unnamed nodes.** Auto-renamed `Node2` nodes break lookup-by-name. Rename immediately after adding.
+- **Wrong parent path.** `./NonExistent` fails; ensure the parent exists before adding children (read the tree first).
+- **Copying a scene as a template without auditing transforms.** Carried-over instances keep world-space offsets baked for the source level; re-zero or drop transform overrides per instance.
+- **Direct `.tscn` edits while running.** They get overwritten when the editor saves; always go through MCP scene tools.
+
+## Verification
+
+1. `summer_get_scene_tree` shows the intended wrapper structure with unique descriptive names and no auto-renamed nodes.
+2. Each repeated setup exists once as a `.tscn` and appears elsewhere only as instances.
+3. Deleting a wrapper parent (`summer_remove_node`) removes exactly its subtree — the recursive-despawn feature works.
+4. No script references a path deeper than one or two segments; group/signal/NodePath used instead.
+5. `summer_get_script_errors` and (if played) `summer_get_debugger_errors` are clean; `summer_screenshot` matches the intended layout.

package/library/skills/scene-hierarchy-design/resource.yaml

@@ -0,0 +1,31 @@
+id: skill/scene-hierarchy-design
+kind: skill
+version: 0.1.1
+summary: "Structure Summer Engine scenes by access pattern — asset vs live hierarchies, wrapper nodes per operation, sub-scenes for reuse, path-agnostic logic."
+use_when:
+  - "how should I structure the node hierarchy for this level or character"
+  - "reorganize a scene that grew ad hoc — long node chains, duplicated clusters, hard-to-delete groups"
+  - "should this setup be inline or its own sub-scene"
+  - "scripts break whenever I move nodes because of hardcoded paths"
+do_not_use_when:
+  - "shader or material work, asset import mechanics, or gameplay tuning — this is purely about hierarchy shape"
+  - "intake from the gamedev-knowledge pipeline (source-cited, pipeline-validated, not yet exercised in-engine by the Summer team) — verify results in the engine as you would any technique"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - project
+    - agent-workflow
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-composition
+    - skill/gdscript-patterns
+source: official
+license: MIT
+status: preview
+recommended: false