summer-engine 2.8.2 → 3.1.0

package/{references → library/references/summer-folder}/summer-folder.md

@@ -4,16 +4,17 @@
 
 ## Files at the root of `.summer/`
 
-- `GameSoul.md` — the project brief. Created by `/summer:brainstorm-game`. Contains: name, one-sentence pitch, core loop, 3 mechanics max, art direction summary, scope. Updated whenever the game's high-level direction changes.
-- `art-bible.md` — visual style reference. Created by `/summer:art-direction`. Contains: palette (6–15 hex codes), mood adjectives, lighting plan, post-processing notes, do/don't list, references.
-- `audio-bible.md` — sonic identity. Created by `/summer:audio-direction`. Contains: music style + tempo range, SFX vocabulary (8 classes), dynamic music FSM, bus layout reference.
-- `build-plan.md` — implementation plan derived from `GameSoul.md`. Created by `/summer:make-game` before scaffold/build work.
+- `GameSoul.md` — the project brief. Created by `/brainstorm-game`. Contains: name, one-sentence pitch, core loop, 3 mechanics max, art direction summary, scope. Updated whenever the game's high-level direction changes.
+- `art-bible.md` — visual style reference. Created by `/art-direction`. Contains: palette (6–15 hex codes), mood adjectives, lighting plan, post-processing notes, do/don't list, references.
+- `audio-bible.md` — sonic identity. Created by `/audio-direction`. Contains: music style + tempo range, SFX vocabulary (8 classes), dynamic music FSM, bus layout reference.
+- `build-plan.md` — implementation plan derived from `GameSoul.md`. Created by `/make-game` before scaffold/build work.
+- `project.json` — written by `summer create`, not by skills: the template pin (`id`, `version`, and `repo` + `commit` + `tree_digest` or `builtin: true`), `toolkit_version`, `created_at`. Read it to learn which template started the project; never edit it by hand.
 
 ## Subdirectories
 
-- `mechanics/<mechanic-name>.md` — one file per designed mechanic (e.g., `double-jump.md`, `parry.md`). Created by `/summer:design-mechanic`. Contains: input → response → feedback → failure modes → tunable parameters.
-- `levels/<level-name>.md` — one file per designed level. Created by `/summer:design-level`. Contains: teaching goal, pacing curve (5 beats), encounters, secrets, reward gating.
-- `npcs/<npc-name>.md` — one file per designed NPC. Created by `/summer:design-npc`. Contains: archetype, perception model, decision tree, escalation, defeat sequence.
+- `mechanics/<mechanic-name>.md` — one file per designed mechanic (e.g., `double-jump.md`, `parry.md`). Created by `/design-mechanic`. Contains: input → response → feedback → failure modes → tunable parameters.
+- `levels/<level-name>.md` — one file per designed level. Created by `/design-level`. Contains: teaching goal, pacing curve (5 beats), encounters, secrets, reward gating.
+- `npcs/<npc-name>.md` — one file per designed NPC. Created by `/design-npc`. Contains: archetype, perception model, decision tree, escalation, defeat sequence.
 - `memory/` — structured project memory for durable facts that must survive future sessions. Use this for locked cast decisions, character facts, provider IDs, world canon, and conflict notes.
 - `skills/` — installed project-scoped Summer skills. Do not put game design memory here.
 
@@ -71,20 +72,20 @@ Then write the fact in normal Markdown so users can inspect and edit it:
 
 | Skill | Writes |
 |---|---|
-| `/summer:brainstorm-game` | `.summer/GameSoul.md` |
-| `/summer:art-direction` | `.summer/art-bible.md` |
-| `/summer:audio-direction` | `.summer/audio-bible.md` |
-| `/summer:design-mechanic` | `.summer/mechanics/<name>.md` |
-| `/summer:design-level` | `.summer/levels/<name>.md` |
-| `/summer:design-npc` | `.summer/npcs/<name>.md` |
-| `/summer:voice-line` | `.summer/memory/casting/voices.md` |
-| `/summer:debug` | does NOT write here |
-| `/summer:play` | does NOT write here |
-| `/summer:vfx` | does NOT write here (VFX edits scenes/scripts) |
-| `/summer:tune-performance` | optionally writes `.summer/perf-notes.md` if user requests |
-| `/summer:setup-multiplayer` | optionally writes `.summer/multiplayer-architecture.md` |
-| `/summer:export-and-ship` | does NOT write here (writes export configs in `project.godot`) |
+| `/brainstorm-game` | `.summer/GameSoul.md` |
+| `/art-direction` | `.summer/art-bible.md` |
+| `/audio-direction` | `.summer/audio-bible.md` |
+| `/design-mechanic` | `.summer/mechanics/<name>.md` |
+| `/design-level` | `.summer/levels/<name>.md` |
+| `/design-npc` | `.summer/npcs/<name>.md` |
+| `/voice-line` | `.summer/memory/casting/voices.md` |
+| `/debug` | does NOT write here |
+| `/play` | does NOT write here |
+| `/game-feel`, `/vfx-<effect>` | does NOT write here (VFX edits scenes/scripts) |
+| `/tune-performance` | optionally writes `.summer/perf-notes.md` if user requests |
+| `/setup-multiplayer` | optionally writes `.summer/multiplayer-architecture.md` |
+| `/export-and-ship` | does NOT write here (writes export configs in `project.godot`) |
 
 ## Linter check (future)
 
-Once `workflow/skill-test` gains an executable mode, it should validate that any skill writing to `.summer/` is documented in the table above.
+Once the `skill-test` skill gains an executable mode, it should validate that any skill writing to `.summer/` is documented in the table above.

package/{skills/rendering-and-lighting → library/skills}/3d-lighting/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting
 user-invocable: false
-allowed-tools: Read Grep summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
+allowed-tools: Read Grep summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_run_script summer_screenshot
 paths: ["**/*.tscn", "**/*.tres"]
 ---
 
@@ -109,8 +109,9 @@ Always use `Color(r, g, b, a)` with values 0.0–1.0:
 
 ## Baked lighting — what you can and cannot do from here
 
-Real-time lighting (everything above) is fully scriptable. Baking is not, and the
-split is worth stating before you promise a user a bake.
+Real-time lighting (everything above) is fully scriptable. Baking mostly is too on
+this build — the split that matters is *which process* runs the bake, not whether a
+script can trigger it.
 
 | Approach | Callable from MCP / a script? |
 |---|---|
@@ -118,14 +119,17 @@ split is worth stating before you promise a user a bake.
 | `WorldEnvironment` + `Environment` (sky, ambient, tonemap, glow, SSAO, SSR) | Yes |
 | `SDFGI` real-time GI | Yes — `Environment.sdfgi_enabled = true`, no bake step at all |
 | `VoxelGI` | Yes — `VoxelGI.bake()` **is** bound to script (`ClassDB.class_has_method("VoxelGI", "bake")` is true) |
-| **`LightmapGI` bake** | **No.** `LightmapGI` exposes only its `set_*` / `get_*` configuration methods — there is no `bake` in its method list on this build. It runs from the editor's Bake Lightmaps button only. |
-| **`OccluderInstance3D` occlusion bake** | **No.** `bake_single_node` is not script-callable either. Editor-only. |
-
-So when the user asks for baked lighting: add and configure the `LightmapGI`
-node and set the meshes' `gi_mode`, then tell them plainly that the bake itself
-is a button they press in the editor and that you cannot trigger it. Do not claim
-a bake happened. If they want GI without a manual step, steer to `SDFGI`
-(`Environment.sdfgi_enabled`, no bake) or `VoxelGI` (whose `bake()` you can call).
+| **`LightmapGI` bake** | **Yes, from the live editor.** Summer binds `LightmapGI.bake(from_node, image_data_path)` to script (upstream leaves it button-only). Call it from `summer_run_script`. The GPU lightmapper needs a real renderer (a RenderingDevice): a normal desktop editor has one; a cloud container needs xvfb + GL (`running-in-the-cloud`); a **pure-headless** process has none and the call returns `BAKE_ERROR_NO_LIGHTMAPPER`. |
+| **`OccluderInstance3D` occlusion bake** | **No.** `bake_single_node` is not script-callable. Editor-button only. |
+
+So when the user asks for baked lighting: add and configure the `LightmapGI` node,
+set the meshes' `gi_mode`, then run the bake yourself from `summer_run_script` —
+`lgi.bake(lgi, "res://lightmaps/scene_lm.exr")` — and check the returned bake-error
+enum (0 is OK; `BAKE_ERROR_NO_LIGHTMAPPER` means no renderer in this process, not a
+missing binding). Verify with a `framing:"camera"` screenshot, which renders the
+real environment. Only fall back to "press Bake Lightmaps in the editor" when
+there is genuinely no renderer available. If they want GI with zero bake step,
+steer to `SDFGI` (`Environment.sdfgi_enabled`) or `VoxelGI`.
 
 Note the related trap: `Engine.has_singleton("EditorInterface")` returns **true**
 even in a headless non-editor process, so it is not a valid capability probe.

package/library/skills/3d-lighting/resource.yaml

@@ -0,0 +1,27 @@
+id: skill/3d-lighting
+kind: skill
+version: 1.0.3
+summary: Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions.
+use_when:
+  - setting up lighting in a Summer Engine 3D scene — adding lights, configuring WorldEnvironment, sky, or shadows
+  - a 3D scene looks flat, too dark, or washed out, or has harsh or missing shadows
+facets:
+  lifecycle:
+    - build
+  domains:
+    - rendering
+    - lighting
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/running-in-the-cloud
+    - skill/scene-scripting
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/rendering-and-lighting/3d-lighting

package/library/skills/README.md

@@ -0,0 +1,242 @@
+# Summer skills
+
+> 94 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
+
+The folder is flat on purpose (`docs/design/DECISIONS.md`, D3): a skill usually belongs to several domains, so categories live in each skill's `facets.domains` and this index is rendered from them. The first domain listed is the primary one. `summer skills list --by-domain` prints the same grouping; `summer skills info <slug>` shows one skill.
+
+Status: **stable** unless marked; *preview* = not yet exercised in-engine by the Summer team; ~~deprecated~~ installs only by name. ★ = installed by `--recommended`.
+
+## Domains
+
+- [2d](#2d) (10)
+- [3d](#3d) (6)
+- [agent-workflow](#agent-workflow) (17)
+- [ai](#ai) (1)
+- [animation](#animation) (6)
+- [assets](#assets) (3)
+- [audio](#audio) (6)
+- [character-controller](#character-controller) (1)
+- [debug](#debug) (1)
+- [deployment](#deployment) (2)
+- [editor](#editor) (1)
+- [gameplay](#gameplay) (3)
+- [level-design](#level-design) (2)
+- [multiplayer](#multiplayer) (3)
+- [navigation](#navigation) (1)
+- [performance](#performance) (1)
+- [rendering](#rendering) (4)
+- [runtime](#runtime) (1)
+- [scenes](#scenes) (11)
+- [scripting](#scripting) (1)
+- [ui](#ui) (1)
+- [vfx](#vfx) (9)
+- [video](#video) (3)
+
+## 2d
+
+| skill | when to use | also |
+|---|---|---|
+| [character-portrait](./character-portrait/SKILL.md) ★ | Generate a single polished character bust for dialogue UI, character select, lore cards, or codex entries. One character, locked composition, VN-style. | assets |
+| [concept-art](./concept-art/SKILL.md) ★ | Explore art direction with 3-4 rough concept variants of a character, environment, or prop to pick a vibe before committing to a final asset. | assets |
+| [create-asset-sheet](./create-asset-sheet/SKILL.md) | Generate a pack of 2D game assets from one prompt — tile sheet, UI kit, character pack, or biome set — sliced, classified, and saved as one pack ArtAsset. | assets |
+| [instantiate-asset-pack](./instantiate-asset-pack/SKILL.md) | Import a whole create-asset-sheet pack into the scene: groups composites, sorts paint order, emits Sprite2D/Node2D/NinePatchRect ops to lay it out. | assets |
+| [pixel-art](./pixel-art/SKILL.md) ★ | Generate pixel-art assets — sprites, items, tiles, portraits — at a specific resolution with pixel-perfect grid, limited palette, retro feel. | assets |
+| [skybox-panorama](./skybox-panorama/SKILL.md) | Generate a 360-degree equirectangular sky panorama and wire it as a PanoramaSkyMaterial Sky resource on WorldEnvironment in a 3D scene. | assets |
+| [sprite-sheet](./sprite-sheet/SKILL.md) | Generate animated 2D character sprites laid out as a sprite sheet — walk cycle, attack, idle, death — wired into AnimatedSprite2D / SpriteFrames. | assets |
+| [tileable-texture](./tileable-texture/SKILL.md) | Generate a seamless tileable texture for walls, floors, or terrain — repeats cleanly on all four edges, wired as a StandardMaterial3D albedo. | assets |
+| [ui-graphics](./ui-graphics/SKILL.md) | Generate game-UI elements — icons, buttons, panels, frames, HUD widgets, badges — flat design, transparent background, wired via TextureRect/NinePatchRect. | assets |
+| [use-widget-asset](./use-widget-asset/SKILL.md) | Wire a widget slice from a create-asset-sheet pack (panel, button, slider, bar, toggle) into NinePatchRect, TextureProgressBar, or TextureRect via sliceMeta. | assets |
+
+## 3d
+
+| skill | when to use | also |
+|---|---|---|
+| [character-model](./character-model/SKILL.md) ★ | Generate a rigged humanoid — player, NPC, enemy, boss — via T-pose reference, user-gated preview, and Meshy auto-rig, wired as CharacterBody3D or Node3D. | assets |
+| [environment-kit](./environment-kit/SKILL.md) | Generate a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corners — snap-together meshes sharing one visual style. | assets |
+| [*fabricating-assets*](./fabricating-assets/SKILL.md) (preview) | Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models. | assets, scripting, agent-workflow |
+| [organic-model](./organic-model/SKILL.md) | Generate organic 3D shapes — trees, rocks, mushrooms, coral, plants, vines, crystals — where AI artifacts read as natural irregularity. | assets |
+| [prop-model](./prop-model/SKILL.md) ★ | Generate a single static 3D prop — sword, barrel, chest, lantern, throne, statue — one isolated object, no rigging, wired as a MeshInstance3D. | assets |
+| [vehicle-model](./vehicle-model/SKILL.md) | Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as Vehicle3D or MeshInstance3D. | assets |
+
+## agent-workflow
+
+| skill | when to use | also |
+|---|---|---|
+| [brainstorming](./brainstorming/SKILL.md) ★ | Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior. | game-design |
+| [debugging-game-feel](./debugging-game-feel/SKILL.md) | Debug features that work but feel wrong — floaty jumps, mushy combat, sluggish camera — subjective bugs living in tuning, timing, and feedback layers. | gameplay |
+| [diagnosing-perf-regressions](./diagnosing-perf-regressions/SKILL.md) | Find why frame rate, frame time, or load time got worse since a known-good state — regression hunting, not general performance tuning. | performance |
+| [dispatching-parallel-agents](./dispatching-parallel-agents/SKILL.md) | Work 2+ independent tasks in parallel when they share no state and have no sequential dependencies. | meta |
+| [gameskill](./gameskill/SKILL.md) | Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter. | meta |
+| [*godogen-visual-proof-game-generation*](./godogen-visual-proof-game-generation/SKILL.md) (preview) | Godogen-style game generation with a visual QC loop — capture frames from the running game, self-verify against the brief, bounded fix rounds, proof clip. | verification |
+| [headless-scripting](./headless-scripting/SKILL.md) ★ | Run a GDScript file against Summer Engine from the shell for operations no MCP tool exposes — navmesh baking, collision shapes, TileSets, re-imports. | headless |
+| [investigating-bugs](./investigating-bugs/SKILL.md) ★ | Systematic investigation of any bug, test failure, or unexpected behavior before proposing fixes. | debug |
+| [playtesting-a-feature](./playtesting-a-feature/SKILL.md) ★ | Before claiming a gameplay feature done: actually run the game and walk through the feature. Static diagnostics and type checks do not count. | verification |
+| [running-in-the-cloud](./running-in-the-cloud/SKILL.md) | 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. | project |
+| [skill-create](./skill-create/SKILL.md) | Bootstrap a new Summer library skill (library/skills/<slug>/ with resource.yaml and SKILL.md), frontmatter, and stub sections. | meta |
+| [skill-improve](./skill-improve/SKILL.md) | Upgrade an underperforming Summer skill — run it against a behavioral spec with and without changes via a parallel-eval harness; ship the winner. | meta |
+| [skill-test](./skill-test/SKILL.md) | Lint a Summer skill before commit, audit the whole library, or check a behavioral spec assertion — static structural rules plus behavioral specs. | meta |
+| [using-summer](./using-summer/SKILL.md) | Session bootstrap for Summer projects — establishes how to find and use Summer skills and the summer-engine MCP before any response. | meta |
+| [verification-before-completion](./verification-before-completion/SKILL.md) ★ | Run verification commands and confirm output before claiming work complete, fixed, or passing — evidence before assertions, always. | verification |
+| [writing-plans](./writing-plans/SKILL.md) | Turn a spec or requirements for a multi-step task into a written implementation plan before touching code. | meta |
+| [writing-skills](./writing-skills/SKILL.md) | Create, edit, and verify agent skills — format, structure, testing with subagents, and best practices. | meta |
+
+## ai
+
+| skill | when to use | also |
+|---|---|---|
+| [design-npc](./design-npc/SKILL.md) ★ | Design enemy/NPC/boss/companion behavior — perception, personality, intent, action state machine, telegraphs — outputs a GDScript stub plus node tree. | npc |
+
+## animation
+
+| skill | when to use | also |
+|---|---|---|
+| [animation-tree](./animation-tree/SKILL.md) | Design and wire AnimationTree state machines and blend trees so clips respond to gameplay — locomotion blends, attack interrupts, hit reactions. | 3d |
+| [character-animation-wiring](./character-animation-wiring/SKILL.md) | Wire a rigged, animated character end to end — inspect real clips and bones, locomotion state machine, method-track events, poses, blend shapes, root motion. | 3d |
+| [facial-and-lipsync](./facial-and-lipsync/SKILL.md) | Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions. | 3d |
+| [generate-motion](./generate-motion/SKILL.md) ★ | Attach an animation clip to a rigged character from the curated Meshy motion library — idle, walk, run, attack — wired via AnimationPlayer. | 3d |
+| [procedural-animation](./procedural-animation/SKILL.md) | Runtime bone modification on top of clips — head look-at, foot IK, hand-grabs-prop, additive lean, recoil. Code-and-modifier patterns, not generation. | 3d |
+| [retarget](./retarget/SKILL.md) | Apply existing animation clips from one rigged character to a different rigged character — same library, multiple models, no regeneration. | 3d |
+
+## assets
+
+| skill | when to use | also |
+|---|---|---|
+| [asset-strategy](./asset-strategy/SKILL.md) ★ | Route any 'I need a [thing]' asset request to the right specialist skill — disambiguates 2D / 3D / audio / video / VFX / animation pipelines. | pipeline |
+| [*lumera-single-image-scene-reconstruction*](./lumera-single-image-scene-reconstruction/SKILL.md) (preview) | Lumera-style single image to editable 3D scene — VLM-parsed object boxes and parametric lights, per-object meshes, HDR probe, .tscn assembly, refinement loop. | pipeline, 3d, scenes |
+| [*skintokens-auto-rigging*](./skintokens-auto-rigging/SKILL.md) (preview) | Offline auto-rigging with skin-tokens.cpp (GGML SkinTokens/TokenRig port) — skeleton and skin weights from a static GLB mesh on CPU/Vulkan, into Godot 4. | pipeline, 3d, animation |
+
+## audio
+
+| skill | when to use | also |
+|---|---|---|
+| [adaptive-music](./adaptive-music/SKILL.md) | Wire music stems to game state — combat/explore/boss/tension crossfades on a shared bus, paired with a state machine and AudioBus structure. | gameplay |
+| [ambient-bed](./ambient-bed/SKILL.md) | Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop. | assets |
+| [audio-direction](./audio-direction/SKILL.md) ★ | Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md. | game-design |
+| [music-track](./music-track/SKILL.md) ★ | Generate a looped or cinematic music track — loops authored at >=30s with a marked loop point, cinematic tracks at >=60s linear. | assets |
+| [sound-effect](./sound-effect/SKILL.md) ★ | Generate short SFX one-shots — footsteps, weapon swings, UI clicks, hit impacts — wired as AudioStreamPlayer/2D/3D that auto-frees on finished. | assets |
+| [voice-line](./voice-line/SKILL.md) ★ | Generate TTS voice lines — NPC barks, narrator, dialogue — with voice-id sourcing, a character-to-voice decision tree, and multi-line dialogue support. | assets |
+
+## character-controller
+
+| skill | when to use | also |
+|---|---|---|
+| [fps-controller](./fps-controller/SKILL.md) ★ | Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling. | gameplay |
+
+## debug
+
+| skill | when to use | also |
+|---|---|---|
+| [debug](./debug/SKILL.md) ★ | Disciplined bug/crash/error loop for Summer projects — script errors, console, debugger, hypothesis, fix, verify — before making code or scene changes. | verification |
+
+## deployment
+
+| skill | when to use | also |
+|---|---|---|
+| [export-and-ship](./export-and-ship/SKILL.md) ★ | Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval. | project |
+| [remote-deploy](./remote-deploy/SKILL.md) ★ | 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. | project |
+
+## editor
+
+| skill | when to use | also |
+|---|---|---|
+| [*driving-the-editor-ui*](./driving-the-editor-ui/SKILL.md) (preview) | Drive the editor UI by name: invoke actions, clear blocking dialogs, switch the main screen, read a dock — and route scene work to the scene tools instead. | agent-workflow, verification |
+
+## gameplay
+
+| skill | when to use | also |
+|---|---|---|
+| [auto-fire-targeting](./auto-fire-targeting/SKILL.md) | Design or fix auto-fire weapon targeting (survivors, top-down ARPG, tower defense) — the pending-damage pattern that prevents over-commit and overkill. | game-design |
+| [*celeste-momentum-platforming*](./celeste-momentum-platforming/SKILL.md) (preview) | Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction. | character-controller, game-design |
+| [design-mechanic](./design-mechanic/SKILL.md) ★ | Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub. | game-design |
+
+## level-design
+
+| skill | when to use | also |
+|---|---|---|
+| [design-level](./design-level/SKILL.md) ★ | Design a single level — layout, pacing, encounters, secrets, reward gating — outputs a level design doc and a node-tree skeleton for summer_create_scene. | game-design |
+| [scene-to-level](./scene-to-level/SKILL.md) | Go from a scene reference image or concept art to a playable scene — orchestrates concept, asset pack, terrain, composition, and scene assembly. | game-design |
+
+## multiplayer
+
+| skill | when to use | also |
+|---|---|---|
+| [host-authoritative-state](./host-authoritative-state/SKILL.md) ★ | Design the state layer of a multiplayer game — what the host owns, how clients request changes, and how the host validates and broadcasts. | game-design |
+| [peer-to-peer-multiplayer](./peer-to-peer-multiplayer/SKILL.md) ★ | Start a multiplayer game from scratch with peer-to-peer host authority — network architecture built top-down, before writing game logic. | project |
+| [setup-multiplayer](./setup-multiplayer/SKILL.md) ★ | Add multiplayer to an existing game — LAN/online co-op, PvP, lobbies — via MultiplayerAPI, MultiplayerSpawner, and MultiplayerSynchronizer. | scripting |
+
+## navigation
+
+| skill | when to use | also |
+|---|---|---|
+| [navigate-summer](./navigate-summer/SKILL.md) ★ | When to open a Summer web page or editor surface FOR the user (billing, their games, the scene just built) versus acting through the API, using summer_open. | agent-workflow, meta |
+
+## performance
+
+| skill | when to use | also |
+|---|---|---|
+| [tune-performance](./tune-performance/SKILL.md) ★ | Profile a slow game via summer_get_diagnostics, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations. | debug |
+
+## rendering
+
+| skill | when to use | also |
+|---|---|---|
+| [3d-lighting](./3d-lighting/SKILL.md) ★ | Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions. | lighting |
+| [art-direction](./art-direction/SKILL.md) ★ | Define the game's visual style — references, palette, mood, lighting plan, post-processing, do/don't list — output as an art bible at .summer/art-bible.md. | lighting |
+| [*psx-retro-rendering*](./psx-retro-rendering/SKILL.md) (preview) | Hardware-informed PlayStation 1 rendering in Godot 4 — low-res output, RGB5 and exact dither, affine textures, vertex snapping, blend modes, fog; limits named. | 3d |
+| [*realtime-wet-surfaces*](./realtime-wet-surfaces/SKILL.md) (preview) | Real-time wetness on existing Godot 4 materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount. | vfx |
+
+## runtime
+
+| skill | when to use | also |
+|---|---|---|
+| [*agent-playtesting*](./agent-playtesting/SKILL.md) ★ (preview) | Playtest by driving the LIVE game — deterministic launch, frame-stamped probes before/after each action, exact frame steps, scripted or recorded input. | playtest, verification, agent-workflow |
+
+## scenes
+
+| skill | when to use | also |
+|---|---|---|
+| [brainstorm-game](./brainstorm-game/SKILL.md) ★ | Turn a vague idea into a buildable plan — genre, scope, core loop, mechanics, art direction — written as a 1-page brief to .summer/GameSoul.md. | project |
+| [browse-templates](./browse-templates/SKILL.md) ★ | List available Summer Engine project templates, present the choices, and create a project from the chosen one via summer create. | project |
+| [make-game](./make-game/SKILL.md) ★ | Orchestration spine for 'make me a game': brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship — delegates to specialist skills. | project |
+| [new-project](./new-project/SKILL.md) ★ | Create a fresh blank Summer Engine project — asks one question (project name) and runs summer create empty. | project |
+| [play](./play/SKILL.md) ★ | Run the project in Summer Engine, wait briefly, then report what's happening — clean run, errors, or warnings. | project |
+| [scene-composition](./scene-composition/SKILL.md) ★ | Scene structure conventions — node hierarchy, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions. | project |
+| [*scene-hierarchy-design*](./scene-hierarchy-design/SKILL.md) (preview) | Structure Summer Engine scenes by access pattern — asset vs live hierarchies, wrapper nodes per operation, sub-scenes for reuse, path-agnostic logic. | project, agent-workflow |
+| [*scene-scripting*](./scene-scripting/SKILL.md) ★ (preview) | One GDScript in the live editor (summer_run_script) builds scenes, 2D levels, HUDs and gameplay wiring instead of CRUD chains; verify with diff + screenshot. | scripting, 2d, ui, agent-workflow |
+| [*spatial-placement*](./spatial-placement/SKILL.md) ★ (preview) | Place and verify 3D objects with Starcast evidence — inspect, place, starcast, correct, verify; floor, shelf, wall, alcove recipes and overlap repair. | 3d, world-building, level-design, verification |
+| [*verifying-scenes*](./verifying-scenes/SKILL.md) ★ (preview) | Prove scene work landed — snapshot before, diff + screenshot after (bookmarked viewpoint, labels), live runtime reads during playtests — then claim. | verification, agent-workflow |
+| [*world-building-3d*](./world-building-3d/SKILL.md) ★ (preview) | Compose, ground, space, and validate 3D scenes with Summer's four bounded spatial tools — exact paths, one geometric decision at a time, verified. | 3d, world-building, level-design, verification |
+
+## scripting
+
+| skill | when to use | also |
+|---|---|---|
+| [gdscript-patterns](./gdscript-patterns/SKILL.md) ★ | GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming. | conventions |
+
+## ui
+
+| skill | when to use | also |
+|---|---|---|
+| [ui-basics](./ui-basics/SKILL.md) ★ | Build Summer Engine UI — HUDs, menus, health bars, dialogue boxes, Control trees — anchors, containers, responsive layout, theme vs inline styling. | ux |
+
+## vfx
+
+| skill | when to use | also |
+|---|---|---|
+| [game-feel](./game-feel/SKILL.md) ★ | Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact. | gameplay |
+| [vfx-dissolve](./vfx-dissolve/SKILL.md) | Dissolve effect — a mesh disintegrating with a glowing burning edge, driven by a noise-threshold ShaderMaterial overriding the target's material. | rendering |
+| [vfx-fire](./vfx-fire/SKILL.md) ★ | Fire effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp — torches, campfires, candles. | rendering |
+| [vfx-hit-spark](./vfx-hit-spark/SKILL.md) | Hit-spark effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact. | rendering |
+| [vfx-lightning](./vfx-lightning/SKILL.md) | Lightning bolt effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake. | rendering |
+| [vfx-magic-glow](./vfx-magic-glow/SKILL.md) | Magic-glow effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh. | rendering |
+| [vfx-muzzle-flash](./vfx-muzzle-flash/SKILL.md) ★ | Muzzle-flash effect — a one-shot ~80 ms burst at a gun barrel built with a particle one-shot or a flashing quad with a star-burst shader. | rendering |
+| [vfx-smoke](./vfx-smoke/SKILL.md) | Smoke effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D. | rendering |
+| [vfx-water-ripple](./vfx-water-ripple/SKILL.md) | Water-ripple effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts. | rendering |
+
+## video
+
+| skill | when to use | also |
+|---|---|---|
+| [animated-loop](./animated-loop/SKILL.md) | Generate a short seamlessly-looping video clip — splash background, animated logo backdrop, idle title-screen footage — wired as a looping VideoStreamPlayer. | assets |
+| [cinematic-cutscene](./cinematic-cutscene/SKILL.md) ★ | Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer. | assets |
+| [trailer-shot](./trailer-shot/SKILL.md) | Generate marketing or trailer footage — slow-mo combat, establishing shots, hero beats, splash screens, pitch-deck B-roll — max punch in 5-10 seconds. | assets |

package/{skills/audio → library/skills}/adaptive-music/SKILL.md

@@ -326,5 +326,5 @@ in Summer Engine.
 - `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
-- `../../../references/godot-version.md` — Summer compatibility for AudioServer
+- `../../references/godot-version/godot-version.md` — Summer compatibility for AudioServer
   and Tween APIs

package/library/skills/adaptive-music/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/adaptive-music
+kind: skill
+version: 1.0.2
+summary: Wire music stems to game state — combat/explore/boss/tension crossfades on a shared bus, paired with a state machine and AudioBus structure.
+use_when:
+  - wiring music stems to game state — combat / explore / boss / tension crossfades on a shared bus
+  - layered or vertical music that changes when combat starts
+facets:
+  lifecycle:
+    - build
+  domains:
+    - audio
+    - gameplay
+  modalities:
+    - audio
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/audio-direction
+    - skill/music-track
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/audio/adaptive-music

package/library/skills/agent-playtesting/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: agent-playtesting
+description: Use when proving a gameplay feature, reproducing a bug, or comparing two variants by driving the LIVE running game yourself — deterministic launch (seed, fixed_fps, offscreen instances), frame-stamped probes before and after every action, exact frame stepping, scripted or recorded input. The doctrine behind summer_game_probe, summer_game_input, summer_game_control and the summer_runtime_* tools.
+---
+
+# Agent Playtesting
+
+## Overview
+
+`playtesting-a-feature` says a feature is not done until someone has played it. This skill is how *you* play it — not a hidden probe that dies when it finishes, but the live game, driven one action at a time, with a frame-stamped record of what each action did.
+
+The engine's runtime-control ops make the running game a thing you can see and touch:
+
+| Tool | Does |
+|---|---|
+| `summer_play` | Start the game. With `instance` + `mode:"offscreen"` a disposable parallel instance; with `seed` / `fixed_fps` (and `deterministic:true` offscreen) a reproducible one. |
+| `summer_game_probe` | State AND pixels of ONE frame, atomically: live tree, property reads, screenshot, all stamped with the same frame counters. The evidence tool. |
+| `summer_game_control` | `pause`, `resume`, `step` exactly N physics/process frames, `speed`, `instances`. |
+| `summer_game_input` | `script` timed synthetic input; `record_start` / `record_stop` real input into `res://.summer/replays/`; `replay` a recording (with `seed` on a deterministic instance). |
+| `summer_runtime_set` / `summer_runtime_call` | Set a property / call a method on a live node. Actions, not evidence. |
+| `summer_runtime_spawn` | Spawn a PackedScene into, or free a node from, the live game. |
+| `summer_runtime_animate` | Read/drive an AnimationPlayer, an AnimationTree state machine, or read Skeleton3D bone poses. |
+| `summer_stop` | Stop the main game, or `instance` to stop one offscreen instance. |
+
+Every one of these needs a RUNNING game and answers `game_not_running` otherwise. On an engine build that predates them the result is `engine_lacks_op` naming the fallback — usually the `RunVerification` probe from `playtesting-a-feature`. Record that as the expected outcome, not a failure.
+
+<EXTREMELY-IMPORTANT>
+An action is not evidence. `summer_runtime_set` returning `applied: true`, `summer_game_input` returning `completed: true`, `summer_runtime_call` returning a value — each proves the request was honoured, not that the game did what the feature promises. Only a probe of the frame AFTER, compared with a probe of the frame BEFORE, proves motion, spawning, damage, or a state change. Never claim any of those without the two frame numbers.
+</EXTREMELY-IMPORTANT>
+
+## The Loop
+
+```
+  Launch deterministically → Wait for boot → Probe BEFORE → Act → Step (or run) → Probe AFTER → Assert → Stop
+```
+
+### 1. Launch deterministically
+
+Decide before pressing play what the run must pin.
+
+- **Embedded main game** (`summer_play` with no instance): the game the user sees. Add `seed` and `fixed_fps` to pin the RNG and the frame clock — `seed` only applies to a game that is not already running (`determinism.applied: false` with `reason: already_running` means `summer_stop` first).
+- **Offscreen instance** (`summer_play {instance:"a", mode:"offscreen"}`): a hidden child process the user never sees, addressed by name on every runtime tool. Up to three at once. `deterministic: true` launches it with `--fixed-fps 60 --summer-seed <seed> --audio-driver Dummy`; this is the only kind of instance on which `summer_game_input action:"replay"` accepts a `seed`.
+- **Two variants side by side**: `instance:"before"` and `instance:"after"` (different scenes or different `summer_runtime_set` setups), the same recorded input replayed into each, probes compared frame for frame.
+
+The result's `determinism.seed_scope` tells you what the seed does NOT pin: `RandomNumberGenerator` instances (self-randomized on construction), scripts that call `randomize()`, wall-clock reads, thread timing. A feature that uses any of those is not deterministic under a seed; assert ranges there, or fix the script to use the global RNG.
+
+### 2. Wait for boot — never sleep a guessed delay
+
+Boot time varies. Confirm, do not assume:
+
+- Main game: `summer_is_running` until it reports running.
+- Offscreen instance: `summer_game_control action:"instances"` until the instance shows `attached: true`. Before that, every runtime op answers `request_failed` ("session has not attached yet"). `session_timeout` means the child never attached and was killed — read `summer_get_console` for its stderr.
+
+### 3. Probe BEFORE
+
+```
+summer_game_probe
+  tree: {path: "/root/Main", depth: 2}
+  props: ["/root/Main/Player:position", "/root/Main/Player:velocity", "/root/Main/HUD/Health:value"]
+```
+
+Write down `frame.process_frames` and `frame.physics_frames`. Every path you will act on comes from this tree — runtime paths are absolute (`/root/Main/Player`) and differ from the edited scene when nodes spawn, rename, or reparent at runtime. Look at the screenshot and say what is in it.
+
+### 4. Act
+
+One action per step, so the AFTER probe attributes cleanly:
+
+- `summer_runtime_set path:"/root/Main/Player" property:"position" value:"Vector3(0, 2, 0)"` — read `applied`. `applied: false` (`not_applied`) means a script rewrote the value the same frame, or the literal type was wrong; do not proceed as if it landed.
+- `summer_runtime_call path:"/root/Main/Boss" method:"take_damage" args:[25]` — `return` is what the method answered; the effect still needs the probe.
+- `summer_game_input action:"script" events:[{at_frame:0, type:"action", action:"move_right", hold_ms:500}, {at_frame:30, type:"action", action:"jump", hold_ms:50}]` — `rejected[]` names events the game refused (`unknown_action` = not in the InputMap; bind it with `summer_input_map_bind` and restart, or drive `type:"key"`). One script in flight per instance: `busy` means wait for the first.
+- `summer_runtime_spawn action:"spawn" parent:"/root/Main/Enemies" scene:"res://enemies/goblin.tscn" props:{position:"Vector3(4, 0, -2)"}` — use the returned `node.path` from here on.
+
+### 5. Step — for exact assertions
+
+When "after 3 physics frames the velocity is zero" is the claim, do not let wall-clock time decide how many frames ran:
+
+```
+summer_game_control action:"pause"
+summer_game_probe props:[...]                 # frame N
+summer_runtime_set ... / summer_game_input ... wait:false
+summer_game_control action:"step" frames:3   # kind "physics" (default)
+summer_game_probe props:[...]                 # frame N+3 — the step draws its last frame before replying
+```
+
+The step result carries `before`, `after`, `exact`, and `overshoot`; cite them. The game stays suspended after a step — `summer_game_control action:"resume"` when you want it to run again. Time-based behaviour (a 500 ms hold, a 2 s cooldown) runs on the game's clock: with `fixed_fps` a step of N frames IS N/fps seconds; without it, use `at_ms` and read `clock_mapping` ("approximate" means the mapping went through the physics tick rate).
+
+A minimized game window draws no frames and cannot step (`timeout`). `game_breaked` means the game sits at a script breakpoint; continue it in the debugger first.
+
+### 6. Probe AFTER, then assert
+
+Same probe as step 3. Compare the two:
+
+- positions, velocities, HUD values — as inequalities (`x > before.x + 50`), never exact equality unless the run is deterministic AND frame-stepped;
+- `tree` — the spawned node exists under its parent; the freed one is gone (a `queue_free` takes effect at the end of the frame, so step once before asserting absence);
+- the screenshots — look at both and describe the difference in words. A tree that says "goblin spawned" and a frame that shows no goblin is a bug, not a pass.
+
+Then `summer_get_debugger_errors` — a feature that "worked" while logging null-reference errors did not work.
+
+### 7. Stop
+
+`summer_stop` (main) or `summer_stop instance:"a"` for each offscreen instance you started. Offscreen children also die when the editor exits, but do not leave them for the user to discover.
+
+## Input scripts vs. recordings
+
+| | `action:"script"` | `record_start` / `record_stop` / `replay` |
+|---|---|---|
+| Source | You write it from the spec | Whatever actually happened — a human's hands or a script's output |
+| Readable | Yes; edit a frame number and re-run | A JSON file of events; treat it as an artifact |
+| Timing | `at_frame` exact; `at_ms` exact only with `fixed_fps` | Recorded frames re-based on the first event |
+| Best for | Golden paths, edge probes, regression checks | "Do exactly what the user did", A/B of two builds under identical input |
+| Reproducible | With `seed` + `fixed_fps` on the instance | With `seed` on a `deterministic:true` offscreen instance (`replay` refuses `seed` elsewhere: `nondeterministic_instance`) |
+
+Recording caps at 20,000 events / about 1 MiB (`truncated: true` when hit). Files land in `res://.summer/replays/<id>.json`; pass that exact path to `replay`. A waited script or replay is capped at 20 s by the engine — for longer sequences pass `wait:false` and follow along with probes.
+
+## What seed does not pin
+
+Read `determinism.seed_scope` on the play result and believe it. Pinned: the global RNG (`randi`, `randf`, `randi_range`, `randf_range`, `randfn`, `Array.shuffle`, `Array.pick_random`), re-seeded after `SceneTree` init and before autoloads and the main scene. Not pinned: `RandomNumberGenerator` instances, scripts calling `randomize()`, wall-clock reads (`Time.get_ticks_msec` used as a source of variation), thread timing, and anything read from the network or the file system. When a replay diverges on a deterministic instance, one of these is the reason — find it in the script before doubting the tooling.
+
+## Honesty rules
+
+- **Cite frames.** "At frame 1834 the player was at x=12.0; after `move_right` for 30 frames, at frame 1864 x=57.3" is a verification. "The player moved" is not.
+- **`applied: false` is a no.** Do not narrate a value change the read-back denied.
+- **`completed: false` is a no.** The script did not finish inside the wait; probe to see how far it got, do not call it done.
+- **`rejected[]` is part of the result.** Report the rejected events and why, even when the rest applied.
+- **`engine_lacks_op` is the expected outcome on an engine without these ops.** Say so, fall back to the `playtesting-a-feature` probe loop, and do not describe a runtime playtest you could not run.
+- **A screenshot you did not look at is not a screenshot.** Describe what is in it.
+- **Parallel instances are not the user's game.** Findings from `instance:"a"` describe that instance's launch (scene, seed, fixed_fps); say which instance a claim came from.
+- **Do not hand the walkthrough to the user** while any of these tools works. Ask a human only for what a probe cannot judge — feel, beauty, fun (`debugging-game-feel`).
+
+## Red flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| Asserting motion from a `summer_runtime_set` result | applied means the write landed; probe to see the motion |
+| One probe, then "it works" | One frame proves a state, not a change; two frames prove a change |
+| Sleeping a fixed delay after `summer_play` | Boot varies; `summer_is_running` / `instances` `attached:true` |
+| `position.x == 250.0` on a non-deterministic run | Assert inequality, or pin the run with `fixed_fps` + steps |
+| Ignoring `rejected[]` because `applied > 0` | The rejected event may be the one the feature needed |
+| `seed` on the embedded game called "deterministic" | It pins the global RNG only; `deterministic:true` needs an offscreen instance |
+| Leaving offscreen instances running | Stop each one you started |
+
+## Related skills
+
+- `playtesting-a-feature` — the iron law (no shipped claim without a played walkthrough) and the `RunVerification` probe loop this skill replaces when the runtime tools exist.
+- `verifying-scenes` — evidence discipline for the EDITED scene (snapshot, diff, screenshot).
+- `verification-before-completion` — the code layer that must be green before any of this.
+- `debugging-game-feel` — when the feature works but feels wrong.
+- `investigating-bugs` — root-causing a reproducible bug once a recording reproduces it.