summer-engine 2.8.1 → 3.0.0

package/library/skills/ui-graphics/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/ui-graphics
+kind: skill
+version: 1.0.3
+summary: Generate game-UI elements — icons, buttons, panels, frames, HUD widgets, badges — flat design, transparent background, wired via TextureRect/NinePatchRect.
+use_when:
+  - generating UI elements — icons, buttons, panels, frames, HUD widgets, badges — in flat-design, transparent-background game-UI style
+  - a HUD still uses placeholder icons, buttons, or panels and needs consistent flat-design art
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 2d
+    - assets
+  modalities:
+    - images
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/character-portrait
+    - skill/pixel-art
+    - skill/asset-strategy
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/2d-assets/ui-graphics

package/{skills/2d-assets → library/skills}/use-widget-asset/SKILL.md

@@ -183,7 +183,7 @@ The wizard's Break-down pass produces two new per-slice fields the runtime must
 | `zOrder` | number | Back-to-front paint order on children. Lower = behind. Matches Godot `z_index`, Unity `sortingOrder`, CSS `z-index`. |
 | `parentSliceIndex` | number | Set on each child, points at the composite parent. Used to group children. |
 
-The full schema is the zod definition at `publicsummerengine/src/lib/asset-packs/schema.ts` (`SliceMetaSchema`, `PACK_SCHEMA_VERSION`, and the legacy-migration helper). Read it once if you need to know every field.
+The table above lists every field this skill reads; treat any other field in the pack manifest as opaque.
 
 ### Consume recipe
 
@@ -197,7 +197,7 @@ The full schema is the zod definition at `publicsummerengine/src/lib/asset-packs
    - `position = Vector2(child.bbox.x - parent.bbox.x, child.bbox.y - parent.bbox.y)` — offset relative to the parent's source-sheet rect.
 5. **Apply widget post-processing.** If any child has a `widget` field, wrap or replace its `Sprite2D` with the appropriate Control node per the recipes above (panel → `NinePatchRect`, progress_bar → `TextureProgressBar`, etc.).
 
-For the full instantiation flow (op JSON, examples), use `summer:2d-assets/instantiate-asset-pack`.
+For the full instantiation flow (op JSON, examples), use `instantiate-asset-pack`.
 
 ### Legacy compatibility
 
@@ -214,6 +214,6 @@ Check `metadata.schemaVersion` on the pack: `null` (or absent) = legacy, `1` = c
 
 ## What this skill does NOT cover
 
-- Auto-tiling terrain (Wang / 47-tile). Different format entirely — see `summer:2d-assets/tileable-texture`.
-- Animated UI (button press-down sprites, hover glow). The wizard captures static frames; for animation see `summer:2d-assets/sprite-sheet`.
+- Auto-tiling terrain (Wang / 47-tile). Different format entirely — see `tileable-texture`.
+- Animated UI (button press-down sprites, hover glow). The wizard captures static frames; for animation see `sprite-sheet`.
 - Non-AABB widgets in the 9-slice path. See the **Shape support** table at the top — for circles, hexagons, organic shapes, fall through to `TextureRect` and skip 9-slice entirely.

package/library/skills/use-widget-asset/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/use-widget-asset
+kind: skill
+version: 1.0.3
+summary: Wire a widget slice from a create-asset-sheet pack (panel, button, slider, bar, toggle) into NinePatchRect, TextureProgressBar, or TextureRect via sliceMeta.
+use_when:
+  - consuming a widget slice (panel, button, slider, progress bar, toggle pair) from a create-asset-sheet pack so it behaves like a real UI control
+  - turning a panel, button, slider, or bar slice from a generated UI kit into a working NinePatchRect or TextureProgressBar
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 2d
+    - assets
+  modalities:
+    - scenes
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/create-asset-sheet
+    - skill/instantiate-asset-pack
+    - skill/sprite-sheet
+    - skill/tileable-texture
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/2d-assets/use-widget-asset

package/{skills/workflow → library/skills}/using-summer/SKILL.md

@@ -36,7 +36,7 @@ If `CLAUDE.md` says "skip the brainstorm, just build it" and a skill says "alway
 Two layers:
 
 - **Skills** — discipline guides that fire on specific situations: brainstorming a game, designing a mechanic, building an FPS controller, debugging a crash, shipping a build. Each one is a SKILL.md you load via the Skill tool.
-- **MCP tools** — `summer_*` tools that talk to the running Summer Engine on `localhost:6550`. Scene mutation (`summer_add_node`, `summer_set_prop`), inspection (`summer_get_scene_tree`, `summer_inspect_node`), play/diagnostics (`summer_play`, `summer_get_diagnostics`), asset import/generation (`summer_import_from_url`, `summer_generate_3d`), whole-project sync to Summer Cloud (`summer_cloud_push`, `summer_cloud_pull`; see `summer:summer-cloud`), and 30+ more.
+- **MCP tools** — `summer_*` tools that talk to the running Summer Engine on `localhost:6550`. Scene mutation (`summer_add_node`, `summer_set_prop`), inspection (`summer_get_scene_tree`, `summer_inspect_node`), play/diagnostics (`summer_play`, `summer_get_diagnostics`), asset import/generation (`summer_import_from_url`, `summer_generate_3d`), and 30+ more.
 
 **Scripting language:** The user is making a Summer game with the Summer SDK.
 GDScript is the default creator language. Summer currently uses the 4.6.1
@@ -45,9 +45,9 @@ continuously. Confirm version-sensitive behavior from the engine's own version
 string rather than turning that base into the product identity. You can write
 game code in either:
 
-- **GDScript** (`.gd`) — the default. Best supported by Summer skills (see `summer:gdscript-patterns`). Use this unless the user has explicitly chosen C#.
-- **C#** (`.cs`) — supported by the shipped Mono build. There is no
-  `summer:csharp-patterns` skill yet. When writing C#, use the upstream C# API
+- **GDScript** (`.gd`) — the default. Best supported by Summer skills (see `gdscript-patterns`). Use this unless the user has explicitly chosen C#.
+- **C#** (`.cs`) — supported by the shipped Mono build. The GDScript
+  conventions in `gdscript-patterns` have no C# counterpart yet. When writing C#, use the upstream C# API
   reference matching the current Summer technical base. The lifecycle, signal
   API, and export attributes differ, so do not blindly translate GDScript
   idioms. Confirm that the user wants C# before producing it; switching
@@ -67,6 +67,10 @@ The engine must be running for MCP tools that touch scenes or diagnostics. If it
 
 **OpenCode:** Skills are auto-discovered from the registered directory; load via OpenCode's native skill mechanism.
 
+## Finding the Right Entry
+
+Not sure which skill, tool, template, or reference covers the task? Ask the library before guessing: call `summer_search_library` with the task in plain words ("make stylized water", "the player falls through the floor"), then `summer_read_library` with the id you pick — it returns the entry itself (a skill's body and metadata, a tool's call recipe, a template's pin) and ends with the `entry_id` line to report through `summer_library_feedback` once the outcome is verified. From a shell the same two are `summer tool search-library --args '{"query":"…"}'` and `summer tool read-library --args '{"id":"…"}'`; neither needs the engine. When search names a skill, invoke it by its bare slug through your host's skill mechanism (`vfx-water-ripple`, `fps-controller`, `design-mechanic`) rather than paraphrasing the body from the read.
+
 ## The Rule
 
 **Invoke the relevant skill BEFORE any response or action.** Even a 1% chance a skill might apply means you check. If the loaded skill turns out not to fit, you don't have to follow it — but you do have to load it first to know.
@@ -79,7 +83,7 @@ User message arrives.
   │                                 Yes
   │                                  │
   ├── Invoke the Skill tool.
-  ├── Announce: "Using summer:<skill> to <purpose>."
+  ├── Announce: "Using <skill> to <purpose>."
   ├── If the skill has a checklist, create a todo per item.
   └── Follow the skill exactly.
 ```
@@ -97,10 +101,9 @@ These thoughts mean STOP. Check skills first.
 | "I'll skip the soul file" | `.summer/GameSoul.md` is what every other skill reads. Honor it. |
 | "This voice or canon fact is probably fine to change" | Check `.summer/memory` first. `priority: locked` facts require explicit user confirmation. |
 | "I don't need to brainstorm — they said FPS" | Even with the genre named, brainstorm-game scopes mechanics, art direction, and the cut list. Skip only if explicitly told to. |
-| "I'll write the GDScript myself, no skill" | `gdscript-patterns` encodes idioms that Claude/Codex/Cursor regularly get wrong (signal connection, type hints, `_ready` vs `_process`). |
+| "I'll write the GDScript myself, no skill" | `gdscript-patterns` encodes idioms that coding agents regularly get wrong (signal connection, type hints, `_ready` vs `_process`). |
 | "The engine isn't running, I'll just edit files" | Editing scene files directly while the engine is running silently overwrites in-memory state. Check the skill. |
 | "I remember this skill" | Skills evolve. Re-read the current version. |
-| "I'll just zip the project to move it to another machine" | `summer:summer-cloud` syncs the whole project (big assets included) by hash, with restorable versions. Load it whenever the user mentions sync, a second machine, sharing with a teammate, backing up assets, or restoring a version. |
 
 ## Skill Priority
 
@@ -136,7 +139,7 @@ Do NOT fall back to editing `.tscn` files directly. The engine reads them on dis
 If skills aren't found or the MCP server fails to start:
 
 1. Check whether `summer` is on PATH: `which summer` / `where summer`.
-2. If not, point them at: `npx -y summer-engine@latest setup <agent> --yes --force`.
+2. If not, point them at: `npx -y summer-engine@latest setup <agent> --yes --force` (use `@next` and `--channel next` while a release is soaking on the `next` tag; `summer doctor` prints the right command).
 3. If `summer doctor` is available, run it: `summer doctor` reports auth, engine, port, project memory, and skill state.
 
 ## When Summer Is Stale
@@ -147,7 +150,7 @@ Run `summer doctor` early in a fresh Summer session when setup, MCP tools, slash
 npx clear-npx-cache && npx -y summer-engine@latest setup <agent> --yes --force
 ```
 
-Use the real agent slug from doctor or the current environment (`claude-code`, `codex`, `cursor`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, etc.).
+Use the dist-tag `summer doctor` recommends: `@latest` normally, `@next` (with `--channel next`) when this CLI was installed from the soaking release, otherwise the MCP server silently drops back to the older `latest`. Use the real agent slug from doctor or the current environment (`claude-code`, `codex`, `cursor`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, etc.).
 
 Why this exact command matters:
 

package/library/skills/using-summer/resource.yaml

@@ -0,0 +1,41 @@
+id: skill/using-summer
+kind: skill
+version: 1.0.4
+summary: Session bootstrap for Summer projects — establishes how to find and use Summer skills and the summer-engine MCP before any response.
+use_when:
+  - starting any conversation in a Summer Engine project
+  - deciding which Summer skill or summer_* tool applies before answering a game-development request
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - meta
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/search-library
+    - tool/read-library
+  skills:
+    - skill/audio-direction
+    - skill/fps-controller
+    - skill/debug
+    - skill/design-mechanic
+    - skill/design-level
+    - skill/setup-multiplayer
+    - skill/art-direction
+    - skill/brainstorm-game
+    - skill/play
+    - skill/scene-composition
+    - skill/gdscript-patterns
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/workflow/using-summer
+lint_exceptions:
+  - install-command
+lint_exception_reason: The body documents `npx clear-npx-cache`, Summer's own documented fix for machines whose stale npx cache keeps serving an old summer-engine CLI; it is a user-run recovery step in the body, not agent-autonomous package installation.

package/{skills/3d-assets → library/skills}/vehicle-model/SKILL.md

@@ -25,10 +25,10 @@ Backing tool: `summer_generate_3d`. Default model is `hunyuan` (best general qua
 
 ## When NOT to use
 
-- Character driving the vehicle → that's `summer:3d-assets/character-model`. Generate them separately and parent the character to the vehicle's seat.
-- Vehicle interior (cockpit, dashboard) as a first-person view → generate as a separate "interior" prop via `summer:3d-assets/prop-model` with first-person framing.
-- A scenery vehicle that never moves and is far from camera (parked truck in the distance) → `summer:3d-assets/prop-model` is fine; vehicle-model's overhead isn't worth it.
-- Procedural / customizable vehicles (modular ship parts) → use `summer:3d-assets/environment-kit` to generate a vehicle-parts kit instead.
+- Character driving the vehicle → that's `character-model`. Generate them separately and parent the character to the vehicle's seat.
+- Vehicle interior (cockpit, dashboard) as a first-person view → generate as a separate "interior" prop via `prop-model` with first-person framing.
+- A scenery vehicle that never moves and is far from camera (parked truck in the distance) → `prop-model` is fine; vehicle-model's overhead isn't worth it.
+- Procedural / customizable vehicles (modular ship parts) → use `environment-kit` to generate a vehicle-parts kit instead.
 
 ## Polycount targets
 
@@ -145,7 +145,7 @@ This re-textures the existing mesh with sharper detail — panel lines, decals,
 | Use case | Parent type | Notes |
 |---|---|---|
 | Player-driven (car, bike, hover) | `VehicleBody3D` (wheeled) or `RigidBody3D` (free physics) | Add `VehicleWheel3D` children for wheeled vehicles |
-| Player-driven (spaceship, mech) | `RigidBody3D` or `CharacterBody3D` | Custom thrust / walk code, see `summer:character-controllers` |
+| Player-driven (spaceship, mech) | `RigidBody3D` or `CharacterBody3D` | Custom thrust / walk code, see `fps-controller` |
 | Background scenery (parked, flyby) | `MeshInstance3D` under a `Node3D` | No physics, no collision needed for distant traffic |
 | Background traffic (moving but not interactive) | `Node3D` + `AnimationPlayer` driving the position | Cheap, no physics overhead |
 
@@ -184,11 +184,11 @@ summer_save_scene(scenePath="res://main.tscn")
 
 ## Edge cases
 
-- **Tracked vehicle (tank).** AI mesh-gen handles the hull but the tracks come back as a fused ring. Generate the hull only, then add tracks as a separate `summer:3d-assets/prop-model` (or use a tiled texture on a torus). For animation, scroll the track texture's UV.
-- **Articulated vehicle (mech with shoulders, hips, knees).** The mesh is one piece — joints aren't separated. For animated mechs, treat as a humanoid: generate as `summer:3d-assets/character-model` with the rig pass, then animate via `summer:animation/generate-motion` (custom backend, prompt as "mech walks heavily").
-- **Vehicle with rotor (helicopter, drone).** Generate without rotor, then add the rotor as a separate `summer:3d-assets/prop-model` and parent it. Spin via code in `_process`.
+- **Tracked vehicle (tank).** AI mesh-gen handles the hull but the tracks come back as a fused ring. Generate the hull only, then add tracks as a separate `prop-model` (or use a tiled texture on a torus). For animation, scroll the track texture's UV.
+- **Articulated vehicle (mech with shoulders, hips, knees).** The mesh is one piece — joints aren't separated. For animated mechs, treat as a humanoid: generate as `character-model` with the rig pass, then animate via `generate-motion` (custom backend, prompt as "mech walks heavily").
+- **Vehicle with rotor (helicopter, drone).** Generate without rotor, then add the rotor as a separate `prop-model` and parent it. Spin via code in `_process`.
 - **Open-top vehicle (convertible, jeep).** Specify "open top, no roof" — defaults often add a roof.
-- **The user wants the cockpit interior visible.** Generate exterior here, then a separate `summer:3d-assets/prop-model` for the interior, and switch meshes when the camera enters first-person view.
+- **The user wants the cockpit interior visible.** Generate exterior here, then a separate `prop-model` for the interior, and switch meshes when the camera enters first-person view.
 
 ## Fallback (no MCP)
 
@@ -202,15 +202,15 @@ summer_save_scene(scenePath="res://main.tscn")
 After the vehicle is wired:
 
 > `race_car.glb` placed at `./World/RaceCar` as a VehicleBody3D. Next:
-> - **Vehicle controls:** WASD steering / accel — see `summer:character-controllers` for the vehicle controller pattern (or write directly with `engine_force`, `steering`, and `brake` on VehicleBody3D).
-> - **Driver character:** generate via `summer:3d-assets/character-model` and parent to the seat position.
-> - **Engine sound + tire screech:** `summer:audio/sound-effect` for one-shots, `summer:audio/ambient-bed` for the engine loop.
-> - **Particles:** exhaust smoke, dust trail, sparks on collision — `summer:vfx/particles` (when available) or built-in GPUParticles3D.
+> - **Vehicle controls:** WASD steering / accel — see `fps-controller` for the vehicle controller pattern (or write directly with `engine_force`, `steering`, and `brake` on VehicleBody3D).
+> - **Driver character:** generate via `character-model` and parent to the seat position.
+> - **Engine sound + tire screech:** `sound-effect` for one-shots, `ambient-bed` for the engine loop.
+> - **Particles:** exhaust smoke, dust trail, sparks on collision — `vfx-smoke` / `vfx-hit-spark` or built-in GPUParticles3D.
 
 ## See also
 
-- `summer:3d-assets/character-model` — for the driver/pilot.
-- `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.
-- `../../../references/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.
+- `character-model` — for the driver/pilot.
+- `prop-model` — for separable parts (rotors, decals as decals, modular kit pieces).
+- `asset-strategy` — meta-router.
+- `fps-controller` — for player-driven vehicle input wiring.
+- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.

package/library/skills/vehicle-model/resource.yaml

@@ -0,0 +1,34 @@
+id: skill/vehicle-model
+kind: skill
+version: 1.0.3
+summary: Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as Vehicle3D or MeshInstance3D.
+use_when:
+  - generating a hard-surface vehicle — car, motorcycle, spaceship, hover bike, boat, mech, tank, helicopter
+  - a racing, flying, or combat game needs a hard-surface vehicle mesh as a Vehicle3D or MeshInstance3D
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 3d
+    - assets
+  modalities:
+    - 3d-models
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/character-model
+    - skill/environment-kit
+    - skill/prop-model
+    - skill/generate-motion
+    - skill/asset-strategy
+    - skill/ambient-bed
+    - skill/sound-effect
+    - skill/organic-model
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/3d-assets/vehicle-model

package/{skills/workflow → library/skills}/verification-before-completion/SKILL.md

@@ -79,32 +79,32 @@ Skip any step = lying, not verifying
 
 **Tests:**
 ```
-✅ [Run test command] [See: 34/34 pass] "All tests pass"
-❌ "Should pass now" / "Looks correct"
+Good: [Run test command] [See: 34/34 pass] "All tests pass"
+Bad: "Should pass now" / "Looks correct"
 ```
 
 **Regression tests (TDD Red-Green):**
 ```
-✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
-❌ "I've written a regression test" (without red-green verification)
+Good: Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+Bad: "I've written a regression test" (without red-green verification)
 ```
 
 **Build:**
 ```
-✅ [Run build] [See: exit 0] "Build passes"
-❌ "Linter passed" (linter doesn't check compilation)
+Good: [Run build] [See: exit 0] "Build passes"
+Bad: "Linter passed" (linter doesn't check compilation)
 ```
 
 **Requirements:**
 ```
-✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
-❌ "Tests pass, phase complete"
+Good: Re-read plan → Create checklist → Verify each → Report gaps or completion
+Bad: "Tests pass, phase complete"
 ```
 
 **Agent delegation:**
 ```
-✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
-❌ Trust agent report
+Good: Agent reports success → Check VCS diff → Verify changes → Report actual state
+Bad: Trust agent report
 ```
 
 ## Why This Matters

package/library/skills/verification-before-completion/resource.yaml

@@ -0,0 +1,23 @@
+id: skill/verification-before-completion
+kind: skill
+version: 1.0.3
+summary: Run verification commands and confirm output before claiming work complete, fixed, or passing — evidence before assertions, always.
+use_when:
+  - about to claim work is complete, fixed, or passing, before committing or creating PRs
+  - about to report a test, build, or fix as passing without having run the command and read its output
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - verification
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/workflow/verification-before-completion

package/library/skills/verifying-scenes/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: verifying-scenes
+description: Use when verifying that scene work actually landed — after any mutation batch, asset import, lighting change, or during a playtest — and before claiming any visual or structural result. Runs the before/after discipline (summer_world_snapshot → mutate → summer_snapshot_diff + summer_screenshot), reads live runtime state with summer_get_runtime_tree / summer_inspect_runtime_node instead of stopping the game, and enforces honest-claim rules.
+---
+
+# Verifying Scenes
+
+## Two signals, two jobs
+
+- **Structured state** (`summer_world_snapshot`, `summer_snapshot_diff`, `summer_get_scene_tree`, runtime reads) proves **facts**: paths, classes, transforms, world AABBs, counts, what changed.
+- **Pixels** (`summer_screenshot`) prove **appearance**: composition, scale-to-the-eye, lighting, "does it read as a forest".
+
+Neither substitutes for the other. A diff can say "40 trees added at plausible positions" while the screenshot shows them all untextured magenta; a screenshot can look right while the diff reveals half the trees are unowned and will vanish on save. Run both.
+
+## The before/after discipline
+
+Around **every** mutation batch (script, scene tools, import):
+
+1. **BEFORE**: `summer_world_snapshot` — keep `snapshot_id`. First time in a session, also screenshot so you know the starting state.
+2. Mutate.
+3. **AFTER**: `summer_snapshot_diff from_id:<id>` (omit `to_id` — the engine snapshots now). Check the receipt against your INTENT:
+   - `added` = exactly what you meant to add — no more, no less.
+   - `removed` = empty unless you deleted on purpose. A node you created appearing here (or missing from `added` after a save) is the ownership bug — see `scene-scripting`.
+   - `changed` = only nodes you touched. Unexpected entries mean your script had side effects.
+4. **AFTER**: `summer_screenshot` — and LOOK at it.
+5. Fix before stacking more work on a broken base. An empty diff after a "successful" mutation is a red flag, not a success.
+
+Snapshot ids: the engine retains the last 8 per session; `unknown_snapshot` means the baseline expired — take a fresh one and redo the pair.
+
+## Physical plausibility — check AABBs
+
+`summer_world_snapshot` carries a world AABB per 3D visual. After placing or importing anything:
+
+- Nothing clips that shouldn't (compare AABBs of neighbors).
+- Nothing floats above or sinks into its support.
+- Sizes are real-world plausible: door ≈ 2 units, person ≈ 1.7, car ≈ 4.5. An AABB of 40 on a "chair" is an import-scale bug — pass `target_size` to `summer_instantiate_scene` and re-check.
+
+## Choosing the right screenshot
+
+| Question | Call |
+|---|---|
+| How does the open tab look right now? | `target:"viewport"` (default) |
+| Is the composition/scale of a scene file right? | `target:"scene"` (+ `scenePath`, preset framing) |
+| Is the **lighting / mood / environment** right? | `target:"scene" framing:"camera"` — renders through the scene's OWN camera with its REAL WorldEnvironment. Preset framings substitute a flat environment and CANNOT answer this. |
+| Did **this change** move/add/break something — before vs after from the SAME viewpoint? | `target:"scene" framing:"bookmark" bookmark_name:"<name>"` (+ `marks:true` for numbered labels mapped to node paths) — see Stable viewpoints below |
+| What does the running game show? | `target:"game"` (`summer_play` first; needs the desktop bridge) |
+| Is a **2D scene or UI layout** right? | `target:"scene"` on a 2D scene synthesizes a `Camera2D` and auto-fits the `CanvasItem` bounds (3D presets and `framing:"camera"` do not apply); `nodePath` frames one node, `size` sets the resolution anchors resolve against. A `CanvasLayer` HUD or anything input-driven: `summer_play` + `target:"game"`. |
+
+Read the confession warnings in every capture (no camera, no light, synthetic camera, project mismatch, "engine predates camera framing"). They are part of the result.
+
+### Stable viewpoints (newer engines)
+
+A preset framing re-fits the scene bounds on every capture, so a before/after pair drifts whenever anything moves. For comparisons that line up, fix the pose:
+
+- **Bookmark once, reuse forever.** `summer_camera_bookmark action:"save" name:"hero"` (omit `position`/`look_at` to capture the current editor 3D viewport camera, or pass both as `"Vector3(x, y, z)"` literals). Then every capture is `summer_screenshot target:"scene" framing:"bookmark" bookmark_name:"hero"` — same pose, real WorldEnvironment, project-persisted (`res://.summer/camera_bookmarks.json`), so it survives sessions and machines. `action:"list"` / `"delete"` manage them.
+- **One-off pose:** `framing:"free"` with `camera_position` + `camera_look_at` (+ `fov`).
+- **Name what you see:** add `marks:true` (cap with `max_marks`) and the caption lists `label -> node path` for the numbered tags drawn over the largest visible 3D nodes. Cite the label AND the path in your claim: "label 3 (`Props/Crate_02`) floats above the floor" — then fix it by that exact path. 2D scenes come back `marks_unsupported`, not annotated.
+- **Read the confession.** An engine that predates these framings echoes the preset it fell back to, and the caption says the frame is NOT pose-stable; `marks:true` on such a build draws nothing. Do not compare, and do not read labels, across that warning.
+
+## Runtime reads during playtests
+
+The edited scene is not the running game. While the game runs:
+
+- `summer_get_runtime_tree` — what ACTUALLY spawned (enemies, projectiles, autoloads, pooled nodes). Runtime paths often differ from edited-scene paths.
+- `summer_inspect_runtime_node path:"/root/..."` — one node's live properties: actual stats, actual position, actual flags.
+
+Inspect live instead of stopping the game — stopping usually resets the bug you are chasing. `game_not_running` means exactly that: `summer_play`, then re-run. For input-driven proof, climb to a RunVerification probe (see the playbook's `rawOpsViaBatch`).
+
+### Waiting for engine moments
+
+When the next step depends on the engine reaching a moment — the game booting after `summer_play`, a long import finishing, a save landing — wait for the event instead of sleeping and re-polling:
+
+1. `summer_recent_events` first: note its `next_seq`. Events are delivered live from a cursor, so one taken BEFORE the trigger is the only way not to miss a moment that arrives immediately.
+2. Trigger (`summer_play`, the import, the save).
+3. `summer_wait_for_event since:<next_seq> kinds:["play.started"]` — or `["import.completed"]`, `["scene.saved"]`, `["op.applied","op.failed"]` with `match:{requestId}`. During a playtest, wait on `script.error` to catch runtime script errors as they fire.
+
+`timed_out: true` means no matching event arrived — not that the thing did not happen. Verify with `summer_is_running` / diagnostics, and never claim an event you did not receive. Engines without the events channel return `engine_lacks_events`; fall back to the reads above.
+
+## Honest-claim rules
+
+- Claim only what a diff, frame, or diagnostics call **proved**, and cite it: "the diff shows 40 trees added; the camera-framing screenshot shows them lit on the terrain."
+- NEVER describe an image you did not receive. A failed capture is a result — report it and climb down (scene → viewport) or ask the user.
+- Preset-framing scene renders are static (t=0), synthetic-camera, flat-environment: no claims about animation, particles, lighting, or mood from them.
+- Pass structured failures (`failure_reason`, `terminalState`) through verbatim — never soften them into "it didn't work".
+- After the result is verified, record the outcome with `summer_library_feedback` (worked / worked with fixes / wrong / outdated / incomplete + a short note). Optional and fire-and-forget; if telemetry is off, move on.
+
+## Red Flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| Mutating twice in a row without a diff or screenshot between | You are compounding on an unverified base. Verify, then continue. |
+| "The diff is probably fine, the script said ok" | `ok:true` scripts still drop unowned nodes on save. Read the diff. |
+| Judging lighting from an iso/top framing | Flat substitute environment. Use `framing:"camera"`, boot the game, or a probe. |
+| Stopping the game to inspect a runtime bug | The stop resets the state. Use the runtime reads first. |
+| Sleeping a guessed delay after `summer_play` or a long op | Boot and import times vary. Wait for `play.started` / `op.applied` with `summer_wait_for_event`, or confirm with `summer_is_running`. |
+| "Looks great!" with no capture in the transcript | Fabrication. Capture, look, then claim. |
+
+**Related skills:** `scene-scripting` carries the mutation loop and ctx API this discipline wraps; `playtesting-a-feature` and `verification-before-completion` carry the broader done-claiming rules.

package/library/skills/verifying-scenes/resource.yaml

@@ -0,0 +1,42 @@
+id: skill/verifying-scenes
+kind: skill
+version: 1.1.1
+summary: Prove scene work landed — snapshot before, diff + screenshot after (bookmarked viewpoint, labels), live runtime reads during playtests — then claim.
+use_when:
+  - after any mutation batch, asset import, or lighting change, before claiming it worked
+  - during a playtest, to read live runtime state (spawned nodes, actual stats) without stopping the game
+  - deciding what counts as evidence for a visual or structural claim
+  - taking before/after screenshots from the same saved camera viewpoint, or an annotated screenshot whose numbered labels map to node paths
+do_not_use_when:
+  - "the engine build lacks GetWorldSnapshot/DiffWorldSnapshot/GetRuntimeSceneTree/GetRuntimeNode (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — fall back to summer_get_scene_tree + summer_screenshot"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - verification
+    - agent-workflow
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/world-snapshot
+    - tool/snapshot-diff
+    - tool/get-runtime-tree
+    - tool/inspect-runtime-node
+    - tool/screenshot
+    - tool/wait-for-event
+    - tool/recent-events
+    - tool/camera-bookmark
+  skills:
+    - skill/scene-scripting
+    - skill/playtesting-a-feature
+    - skill/verification-before-completion
+source: official
+license: MIT
+status: preview
+recommended: true
+aliases:
+  - skills/workflow/verifying-scenes

package/{skills/visual-effects/recipes/dissolve → library/skills/vfx-dissolve}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: dissolve
+name: vfx-dissolve
 description: Use when authoring a dissolve effect — an object's mesh disintegrating with a glowing burning edge, driven by a noise threshold ShaderMaterial overriding the target's existing material. Trigger on "dissolve", "disintegrate", "burn away", "Thanos snap", "vanish into ash", "enemy fades out", "object burns up".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_write_file summer_read_file summer_inspect_node summer_inspect_resource summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
+allowed-tools: Read Write Edit summer_write_file summer_read_file summer_inspect_node summer_inspect_resource summer_run_script summer_screenshot summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -246,6 +246,26 @@ DissolveController.dissolve_object(target, 1.2, Color(1, 0.55, 0.1), 6.0, false)
 DissolveController.materialize_object(target, 0.8)
 ```
 
+### 5a. Iterate on the shader with ctx.make_shader (summer_run_script)
+
+On engines with the geometry-tier ctx stdlib (see `scene-scripting`), prototype the
+shader BEFORE committing it to a file: `ctx.make_shader(code, params)` compiles the
+source and returns compile errors **verbatim** in the result (the
+`make_shader_errors` report entry, line numbers included) — no silent magenta
+material, no play-mode round-trip:
+
+```gdscript
+func run(ctx):
+    var mat := ctx.make_shader("<section 2 source>", {"threshold": 0.4})
+    ctx.apply_material(ctx.find("TestDummy"), mat)   # eyeball it with summer_screenshot
+```
+
+The loop: read the exact error from the report → fix that line → re-run. Once it
+compiles and a screenshot at `threshold: 0.4` shows the edge glow, write the final
+source to `dissolve.gdshader` with `summer_write_file` so the controller can preload
+it. (The editor-side preview does not replace 5b — the tweened runtime effect still
+needs a play-mode check.)
+
 ### 5b. Verify
 
 Both files are compiled code. Check them before claiming the dissolve works.
@@ -376,16 +396,16 @@ Without the MCP connection there is no engine to drive, so the user does it them
 
 After firing this recipe, suggest:
 
-- `summer:visual-effects/recipes/smoke` — recolor pale gray, spawn at the target's bounds for ash particles. Especially good for `thanos-snap`.
-- `summer:visual-effects/recipes/magic-glow` — for `holy-banish` and `summon-arrival` variants, add a vertical beam of light at the target.
-- `summer:visual-effects/recipes/fire` — pair `enemy-burn-death` with a brief flame burst at the start of the dissolve.
-- `summer:visual-effects/game-feel` — add a slow-mo on enemy death (`Engine.time_scale = 0.4` for 0.3 s) to emphasize the dissolve.
-- `summer:audio/sound-effect` — generate `magical disintegration whoosh, fading shimmer, 1.5s` and play in sync.
+- `vfx-smoke` — recolor pale gray, spawn at the target's bounds for ash particles. Especially good for `thanos-snap`.
+- `vfx-magic-glow` — for `holy-banish` and `summon-arrival` variants, add a vertical beam of light at the target.
+- `vfx-fire` — pair `enemy-burn-death` with a brief flame burst at the start of the dissolve.
+- `game-feel` — add a slow-mo on enemy death (`Engine.time_scale = 0.4` for 0.3 s) to emphasize the dissolve.
+- `sound-effect` — generate `magical disintegration whoosh, fading shimmer, 1.5s` and play in sync.
 
 ## See also
 
 - `_building-blocks/noise-3d-fbm.gdshaderinc` — the FBM noise this shader includes
-- `summer:visual-effects/recipes/smoke` — pair for the ash cloud
-- `summer:visual-effects/recipes/magic-glow` — for arrival/departure beams
-- `summer:visual-effects/recipes/fire` — for the burn-up variant pairing
-- `summer:gdscript-patterns` — for the static-API class pattern
+- `vfx-smoke` — pair for the ash cloud
+- `vfx-magic-glow` — for arrival/departure beams
+- `vfx-fire` — for the burn-up variant pairing
+- `gdscript-patterns` — for the static-API class pattern

package/library/skills/vfx-dissolve/resource.yaml

@@ -0,0 +1,33 @@
+id: skill/vfx-dissolve
+kind: skill
+version: 1.0.3
+summary: Dissolve effect — a mesh disintegrating with a glowing burning edge, driven by a noise-threshold ShaderMaterial overriding the target's material.
+use_when:
+  - authoring a dissolve effect — an object disintegrating with a glowing burning edge (disintegrate, burn away, vanish into ash)
+  - a defeated unit, teleport exit, or removed object should burn away with a glowing edge instead of vanishing
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - rendering
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/sound-effect
+    - skill/game-feel
+    - skill/vfx-fire
+    - skill/vfx-magic-glow
+    - skill/vfx-smoke
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/visual-effects/recipes/dissolve
+  - dissolve