summer-engine 3.3.0 → 3.4.1

package/library/skills/lumera-single-image-scene-reconstruction/SKILL.md

@@ -13,13 +13,13 @@ tags:
 confidence: extracted
 ---
 
-# Single-Image → Editable Scene Reconstruction (Lumera-style) in SummerEngine
+# Single-Image → Editable Scene Reconstruction (Lumera-style) in Summer Engine
 
 ## Outcome
 
-Turn one reference image into an **editable, engine-native scene** in SummerEngine: individual `MeshInstance3D` objects with transforms, countable parametric light nodes, and an HDR environment probe — not a fused point cloud, Gaussian splat, or baked texture. This is the adaptation of the Lumera pipeline (arXiv:2607.20889, Tsinghua AIRSUN lab) from UE5 to SummerEngine.
+Turn one reference image into an **editable, engine-native scene** in Summer Engine: individual `MeshInstance3D` objects with transforms, countable parametric light nodes, and an HDR environment probe — not a fused point cloud, Gaussian splat, or baked texture. This adapts the Lumera pipeline (arXiv:2607.20889, Tsinghua AIRSUN lab), which was built on another engine, to Summer Engine.
 
-**Honesty caveat:** Lumera itself is UE5-only with no public code as of retrieval (2026-08-30); the paper explicitly lists Godot/engine-portable extraction as future work. This skill documents the architecture and the parts an agent can build in SummerEngine today (assembly, scene representation, refinement loop, evaluation), and flags the parts that require external model components (VLM box/light parsers, per-object mesh generator, HDR estimator).
+**Caveat:** Lumera has no public code, and the paper lists engine-portable extraction as future work. This skill documents the architecture and the parts an agent can build in Summer Engine today (assembly, scene representation, refinement loop, evaluation), and flags the parts that require external model components (VLM box/light parsers, per-object mesh generator, HDR estimator).
 
 ## When to Use
 
@@ -44,11 +44,11 @@ Lumera's stages (from paper abstract + appendices):
 3. **Per-object mesh reconstruction** — a mesh per parsed box.
 4. **HDR environment estimation** — environment probe (IntrinsicHDR partially compensates for SkyLight/unseen near-camera lights).
 5. **Bounded agentic refinement loop** — dual-agent (geometry stage, then light stage) edits + verifies against the reference image.
-6. **Assembly** — emit engine-native scene (Blender/UE5 in the paper; `.tscn` in SummerEngine).
+6. **Assembly** — emit an engine-native scene (`.tscn` in Summer Engine).
 
-Dataset backing it: Lumera-2K, 2,513 UE5 projects → 3.73M components, 63M object instances, 102.6K parametric lights, 95.1K camera views.
+Dataset backing it: Lumera-2K, 2,513 game-engine projects → 3.73M components, 63M object instances, 102.6K parametric lights, 95.1K camera views.
 
-## Scene / Node Shape (SummerEngine target)
+## Scene / Node Shape (Summer Engine target)
 
 The assembly stage should emit this node tree so output stays inspectable/editable:
 
@@ -65,10 +65,10 @@ ReconstructedScene (Node3D)
     ├── OmniLight3D / SpotLight3D / DirectionalLight3D × M
     │     # position/rotation from (x,y,z); color from (r,g,b);
     │     # light_energy from I (mind log-scale calibration, see Tunables)
-    └── (SkyLight-equivalent is carried by WorldEnvironment in Godot)
+    └── (the sky-light equivalent is carried by WorldEnvironment)
 ```
 
-Keep objects and lights as **separate siblings under named containers** — this mirrors UE5's component structure and is what makes the scene "editable" rather than "looks 3D".
+Keep objects and lights as **separate siblings under named containers**. That separation is what makes the scene editable rather than just looking 3D.
 
 ## Implementation Steps
 
@@ -97,15 +97,15 @@ Add a **repair layer** on ingest: drop/fix invalid labels, non-positive sizes, d
 
 ### 2. Box + light parsing (external VLM components)
 
-Lumera-Box/Lumera-Light are VLMs SFT'd on Lumera-2K; there is no public checkpoint. Options: use a hosted VLM prompted to emit the JSON tuples above, or fine-tune an open VLM on your own engine-exported scenes (Godot scenes are text `.tscn` and trivially exportable — this is the "build Lumera-2K for your engine" step the paper identifies as missing for non-UE5 engines).
+Lumera-Box/Lumera-Light are VLMs SFT'd on Lumera-2K; there is no public checkpoint. Options: use a hosted VLM prompted to emit the JSON tuples above, or fine-tune an open VLM on your own engine-exported scenes (`.tscn` scenes are text and easy to export; this is the "build Lumera-2K for your engine" step the paper identifies as missing for other engines).
 
 ### 3. Per-object mesh generation + HDR environment estimation
 
-Also external model components in Lumera (per-object mesh reconstruction; IntrinsicHDR-style environment estimation). For a SummerEngine blockout you can substitute: box mesh (`BoxMesh` sized to the parsed box) per object and a generated/estimated panorama `Sky`. Swap in real reconstructed meshes later without changing the schema.
+Also external model components in Lumera (per-object mesh reconstruction; IntrinsicHDR-style environment estimation). For a Summer Engine blockout you can substitute: box mesh (`BoxMesh` sized to the parsed box) per object and a generated/estimated panorama `Sky`. Swap in real reconstructed meshes later without changing the schema.
 
 ### 4. Assembly: write a `.tscn`
 
-Deterministic GDScript/tool script: instantiate the node shape above from the repaired records. Godot's `.tscn` is text — generating it directly keeps the output diffable and versionable. Save with `PackedScene.pack()` / `ResourceSaver.save()` from an editor tool.
+Deterministic GDScript/tool script: instantiate the node shape above from the repaired records. A `.tscn` is text, so generating it directly keeps the output diffable and versionable. Save with `PackedScene.pack()` / `ResourceSaver.save()` from an editor tool.
 
 ### 5. Bounded dual-agent refinement loop
 
@@ -148,17 +148,17 @@ Reproduce the paper's metrics on held-out scenes so improvements are measurable:
 - **Per-light localization is weak** (F1 0.209 @ 0.5 m) while scene-level light *count* recall is strong (0.998). Frame the output as "right number of lights, roughly right places."
 - **SkyLight / near-camera lights whose source is off-screen** are not supervised; the environment probe (IntrinsicHDR) only partially compensates.
 - **Large outdoor scenes drift geometrically** (~17 m Chamfer-L2); consider joint camera+geometry calibration if you need metric outdoor consistency.
-- **Engine conventions don't transfer for free** — the dataset and light conventions are UE5's; Godot's light units/probes differ, so recalibrate intensity and validate the representation on Godot-native scenes.
+- **Engine conventions don't transfer for free.** The dataset's light conventions come from another engine; Summer Engine's light units and probes differ, so recalibrate intensity and validate the representation on Summer-native scenes.
 
 ## Verification
 
-Not summerengine-verified. To validate an implementation in SummerEngine:
+Not yet verified in Summer Engine. To validate an implementation:
 
 1. Assemble a scene from a test image; confirm the `.tscn` contains separate, selectable `MeshInstance3D`s and light nodes (editability check).
 2. Move/replace one mesh and re-tune one light in the editor without breaking the scene.
-3. Run the evaluation harness (§6) against a held-out set of known Godot scenes and compare to the reference numbers above.
+3. Run the evaluation harness (§6) against a held-out set of known scenes and compare to the reference numbers above.
 4. Confirm the refinement loop terminates within `T_g`/`T_l` and the history window never exceeds the VLM context budget.
 
 ## Confidence
 
-`extracted` — Architecture, metrics, refinement-loop design, and limitations are drawn directly from the arXiv paper (abstract, intro, appendices H.7–I as retrieved; middle method sections were truncated and are not documented here) and the author's announcement post. The SummerEngine node mapping and GDScript schema are adaptations, not from the sources; no public Lumera code exists to reference.
+`extracted` — Architecture, metrics, refinement-loop design, and limitations are drawn directly from the arXiv paper (abstract, intro, appendices H.7–I as retrieved; middle method sections were truncated and are not documented here) and the author's announcement post. The Summer Engine node mapping and GDScript schema are adaptations, not from the sources; no public Lumera code exists to reference.

package/library/skills/lumera-single-image-scene-reconstruction/resource.yaml

@@ -10,7 +10,6 @@ use_when:
 do_not_use_when:
   - "you only need a visual backdrop (a splat or depth-mesh bake is cheaper), large unbounded outdoor scenes, or exact light positions and intensities"
   - "Lumera itself has no public code; the VLM box/light parsers, per-object mesh generator, and HDR estimator are external components you must supply"
-  - "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

package/library/skills/make-game/SKILL.md

@@ -40,9 +40,9 @@ Distilled blueprints for common genres live in this skill's `references/` folder
 | Third-person action / 3D platformer | `references/3d-third-person.md` | `references/3d-third-person-systems.md` | Node3D / CharacterBody3D / SpringArm3D |
 | First-person horror | `references/3d-horror.md` | `references/3d-horror-systems.md` | Node3D / CharacterBody3D / Camera3D on Head |
 
-No playbook (racing, sandbox, sim): build fresh through the phases below. The playbooks lean on these system skills — load one when its mechanic comes up: `character-movement`, `camera-rigs`, `combat-basics`, `save-load`, `ui-basics`, `setup-multiplayer`.
+No playbook (racing, sandbox, sim): build fresh through the phases below. The playbooks lean on these system skills — load one when its mechanic comes up: `character-movement`, `camera-rigs`, `combat-basics`, `save-load`, `ui-basics`, `multiplayer-project`.
 
-Two rules from the playbooks apply to every genre:
+These rules from the playbooks apply to every genre:
 
 - **2D scales to the viewport.** Set `display/window/stretch/mode = canvas_items` and `stretch/aspect = expand`; UI uses Control anchors; code-positioned nodes compute from `get_viewport_rect().size`. Never hardcode 1920x1080.
 - **Playable slice, not tech demo.** Name the core loop in one sentence; every input gets feedback (tween, sound, particle, flash, shake); progression is visible; a restart exists. The bar is "feels good for 30 seconds".
@@ -198,7 +198,7 @@ Repeat until every mechanic in the plan is implemented OR the user calls cut.
 Skill: art-direction
 ```
 
-That writes `.summer/art-bible.md` if it doesn't exist, then guides the lighting / material / palette pass. Use `3d-lighting` for the actual scene work. If the game plays in the browser or is exported for the web, it runs the Compatibility renderer only: follow `web-compatibility-look` instead of Forward+-only features (SDFGI, SSAO, SSR, volumetric fog), and keep `rendering/renderer/rendering_method` on `gl_compatibility`.
+That writes `.summer/art-bible.md` if it doesn't exist, then guides the lighting / material / palette pass. Use `3d-lighting` for the actual scene work. For the web, check the target first. A summer.games web build (`summer_export_game` with `targets:["web"]`) runs on Summer's WebGPU template, which needs the Forward+ or Mobile renderer. A WebGL 2 target runs the Compatibility renderer only: follow `web-compatibility-look` there, avoid Forward+-only features (SDFGI, SSAO, SSR, volumetric fog), and keep `rendering/renderer/rendering_method` on `gl_compatibility`.
 
 ```
 Skill: audio-direction
@@ -277,8 +277,6 @@ By the end of a successful run, the user has:
 - `summer_get_diagnostics` returns clean
 - `summer_play` runs end-to-end and the win condition is reachable
 
-That's a real game. Not a half-finished prototype.
-
 ## Closing line
 
 When all phases are done:

package/library/skills/make-game/references/2d-platformer.md

@@ -56,7 +56,7 @@ separate Area under the player masking only the Enemies layer.
 
 ## Building the level with a TileMap
 
-Use a `TileMapLayer` (Godot 4.3+) for the solid world. Create a `TileSet`, paint
+Use a `TileMapLayer` for the solid world. Create a `TileSet`, paint
 the collision polygon on the solid tiles, put the layer on the World collision
 layer. The player collides with it for free - no per-tile StaticBody.
 

package/library/skills/multiplayer-project/SKILL.md

@@ -476,7 +476,7 @@ Import once so new scripts register, then start two players.
 With the Summer MCP tools:
 
 ```
-summer_project_setting name="summer/local_play/players" value=2
+summer_project_setting key="summer/local_play/players" value=2
 summer_play
 summer_get_diagnostics
 summer_stop

package/library/skills/multiplayer-testing/SKILL.md

@@ -26,7 +26,7 @@ Pick whichever the session has.
 **Summer MCP tools** (they set project settings, then play):
 
 ```
-summer_project_setting name="summer/local_play/players" value=2
+summer_project_setting key="summer/local_play/players" value=2
 summer_play
 summer_get_diagnostics
 summer_stop
@@ -59,9 +59,9 @@ Loopback has no latency, so it hides every timing bug. Always run once with
 these settings; they apply to every client:
 
 ```
-summer_project_setting name="summer/local_play/network/round_trip_msec" value=100
-summer_project_setting name="summer/local_play/network/jitter_msec" value=10
-summer_project_setting name="summer/local_play/network/loss_percent" value=1
+summer_project_setting key="summer/local_play/network/round_trip_msec" value=100
+summer_project_setting key="summer/local_play/network/jitter_msec" value=10
+summer_project_setting key="summer/local_play/network/loss_percent" value=1
 ```
 
 Or put them in `project.godot` while testing:

package/library/skills/music-track/SKILL.md

@@ -13,7 +13,7 @@ paths: ["audio/music/**", "scripts/**", "**/*.tscn"]
 
 ## Overview
 
-ElevenLabs Music renders a track from a prompt. Summer clamps the requested length to **3–600 seconds** before sending it, so anything outside that range is silently pulled to the nearest bound. The output quality depends entirely on prompt specificity: tempo (BPM), key, instrumentation, mood, structural cue. "Epic orchestral" returns generic stock music. "85 BPM, D minor, solo cello and detuned upright piano, sparse, melancholic, no drums, 4/4" returns a usable score for a melancholic exploration scene.
+ElevenLabs Music renders a track from a prompt. Summer clamps the requested length to **3–600 seconds** before sending it, so anything outside that range is silently pulled to the nearest bound. Quality depends on prompt specificity: tempo (BPM), key, instrumentation, mood, structural cue. "Epic orchestral" returns generic stock music. "85 BPM, D minor, solo cello and detuned upright piano, sparse, melancholic, no drums, 4/4" returns a usable score for a melancholic exploration scene.
 
 This skill produces one track aligned with the audio bible's music style and dynamic music plan, then wires it as an `AudioStreamPlayer` on the `Music` bus with a marked loop point if it's a loop, or as a linear cinematic stream if it's a one-shot.
 
@@ -25,9 +25,9 @@ This skill produces one track aligned with the audio bible's music style and dyn
 
 ## When NOT to use
 
-- Short stings / event punctuation (<5s) → use `audio/sound-effect` with class `Stinger`.
-- Adaptive layered stems with state-driven crossfades → `audio/adaptive-music`.
-- Ambient bed with no melody → `audio/ambient-bed`.
+- Short stings / event punctuation (<5s) → use `sound-effect` with class `Stinger`.
+- Adaptive layered stems with state-driven crossfades → `adaptive-music`.
+- Ambient bed with no melody → `ambient-bed`.
 
 ## Steps
 
@@ -116,7 +116,7 @@ Prompts that DON'T work (and why):
 
 For loops: generate **≥30s, prefer 45–60s**. Shorter loops are recognized as repetition within 90s of play and become annoying. The bible's "no state stays >90s without variation" rule means even a 60s loop should contain internal variation (instrument swap on alternating cycles).
 
-For linear: generate **≥60s for cutscenes, up to 300s for endings**. The model handles long arcs better than people expect; ask for one rendered piece rather than splicing.
+For linear: generate **≥60s for cutscenes, up to 300s for endings**. Ask for one rendered piece rather than splicing; the model handles long arcs.
 
 ### 6. Confirm and call
 
@@ -124,7 +124,7 @@ Show the prompt:
 
 > Prompt:
 > `85 BPM, D minor, 4/4, solo cello and detuned upright piano, sparse, melancholic exploration loop, no drums, gentle reverb, 60s loop`
-> Duration 60s. Cost: ~12 credits. Generate?
+> Duration 60s. This uses credits. Generate?
 
 The `music` capability reads the description from **`prompt`**, not `text` — the mirror image of `sound_effects`. Passing `text` here is a 400 `prompt_required`.
 
@@ -155,9 +155,9 @@ loop = true
 loop_offset = 0.0
 ```
 
-If the start has a fade-in but the body is loopable, set `loop_offset = 4.0` (4 seconds of intro skipped on loop, plays full track first time). `bpm` + `beat_count` + `bar_beats` are what you set if you want beat-synced transitions later — see `audio/adaptive-music`.
+If the start has a fade-in but the body is loopable, set `loop_offset = 4.0` (4 seconds of intro skipped on loop, plays full track first time). `bpm` + `beat_count` + `bar_beats` are what you set if you want beat-synced transitions later — see `adaptive-music`.
 
-For seamless looping, the cleaner option is to ask the model to generate a cell (one bar / one phrase) and concatenate; or generate at 60s and trust the model's structural cue. Crossfade looping in code is the practical fallback (see step 9).
+For seamless looping, the cleaner option is to ask the model to generate a cell (one bar / one phrase) and concatenate; or generate at 60s and trust the model's structural cue. Crossfade looping in code is the practical fallback (step 9).
 
 ### 8. Wire it as `AudioStreamPlayer` on the `Music` bus
 
@@ -175,40 +175,42 @@ Music is `AudioStreamPlayer` (not 2D / 3D) — non-positional. The bible's `Musi
 
 ### 9. Crossfade-loop pattern (no marked loop point)
 
-If the loop click bothers the user, use a two-player crossfade:
+If the loop click bothers the user, crossfade two players. Set `loop = false` in the import file first, so each player stops at the end.
 
 ```gdscript
 # scripts/audio/MusicLoopCrossfade.gd
 extends Node
 @export var stream: AudioStream
-@export var fade: float = 1.0
-var _a: AudioStreamPlayer
-var _b: AudioStreamPlayer
-var _active: AudioStreamPlayer
+@export var fade := 1.0
+@export var volume_db := -8.0
+var _players: Array[AudioStreamPlayer] = []
+var _current := 0
 
 func _ready() -> void:
-	_a = _make_player()
-	_b = _make_player()
-	_active = _a
-	_active.play()
-	_active.finished.connect(_on_finished)
-
-func _make_player() -> AudioStreamPlayer:
-	var p := AudioStreamPlayer.new()
-	p.stream = stream
-	p.bus = "Music"
-	p.volume_db = -8.0
-	add_child(p)
-	return p
-
-func _on_finished() -> void:
-	var next := _b if _active == _a else _a
-	next.play()
-	next.finished.connect(_on_finished, CONNECT_ONE_SHOT)
-	_active = next
+	for i in 2:
+		var p := AudioStreamPlayer.new()
+		p.stream = stream
+		p.bus = "Music"
+		p.volume_db = volume_db
+		add_child(p)
+		_players.append(p)
+	_players[0].play()
+
+func _process(_delta: float) -> void:
+	var a := _players[_current]
+	if not a.playing or a.get_playback_position() < stream.get_length() - fade:
+		return
+	_current = 1 - _current
+	var b := _players[_current]
+	b.volume_db = -80.0
+	b.play()
+	var t := create_tween().set_parallel()
+	t.tween_property(a, "volume_db", -80.0, fade)
+	t.tween_property(b, "volume_db", volume_db, fade)
+	t.chain().tween_callback(a.stop)
 ```
 
-The next instance starts at 0:00 the moment the previous finishes — gapless.
+The next player starts `fade` seconds before the current one ends and the two cross over, so the seam is never heard.
 
 ## Reference card — prompts by slot
 
@@ -249,7 +251,7 @@ Cutscene (cinematic):   varies tempo, D minor, 4/4, solo piano opens,
 
 ## Edge cases
 
-- **Clip is 50s but you wanted 60s.** Either regenerate (cheaper than you think) or extend by overlap-crossfading the last 5s onto the start in an audio editor.
+- **Clip is 50s but you wanted 60s.** Either regenerate or extend by overlap-crossfading the last 5s onto the start in an audio editor.
 - **Loop click on every cycle.** Use the crossfade pattern in step 9.
 - **Clip is too long.** Trim the tail in the import dock with `loop_offset`, or in an audio editor.
 - **Track sounds nothing like the references.** Re-read the bible; the prompt may be missing the anchor instrument. Add it explicitly.
@@ -268,7 +270,7 @@ Print the prompt and instruct the user to run via the Summer dashboard, then `su
 
 ## See also
 
-- `audio/audio-direction` — defines style, tempo, key, model
-- `audio/adaptive-music` — wiring stems to game state
-- `audio/sound-effect` — short stings
-- `audio/ambient-bed` — non-melodic location bed
+- `audio-direction` — defines style, tempo, key, model
+- `adaptive-music` — wiring stems to game state
+- `sound-effect` — short stings
+- `ambient-bed` — non-melodic location bed

package/library/skills/new-project/SKILL.md

@@ -11,7 +11,7 @@ paths: ["**/project.godot"]
 
 # /new-project — Scaffold a fresh empty project
 
-When the user wants to start from a blank canvas — not a community template, not a built-in starter scene — this is the path.
+Use this when the user wants a blank project instead of a template.
 
 ## When to use this skill
 
@@ -42,7 +42,7 @@ Default: `my-game`. If they say "anything is fine" or similar, use `my-game` and
 Two built-in options:
 
 - `empty` — root `Node3D` only. Pure blank canvas. Best for: experimentation, when the user knows exactly what they want to build.
-- `3d-basic` — root `Node3D` with `Camera3D`, `DirectionalLight3D`, a floor `MeshInstance3D`, and a `WorldEnvironment`. Best for: first-time users, when "just give me something I can press play on" is the vibe.
+- `3d-basic` — root `Node3D` with `Camera3D`, `DirectionalLight3D`, a floor `MeshInstance3D`, and a `WorldEnvironment`. Best for: first-time users who want something they can press Play on.
 
 If you're not sure which fits, ask:
 
@@ -62,7 +62,7 @@ or
 summer create 3d-basic my-game
 ```
 
-The command writes `project.godot` and the chosen `main.tscn`. No network call, fast, deterministic.
+The command writes `project.godot` and the chosen `main.tscn`. It makes no network call.
 
 ### 4. Open it
 
@@ -96,11 +96,9 @@ Ask: "Project is open. What do you want to build?"
 ## Edge cases
 
 - **Engine not running** → that's fine. `summer create` doesn't need the engine. After scaffolding, `summer run <name>` will start it.
-- **User wants 2D but `empty` is the only 2D-friendly built-in** → use `empty`, then in the next breath set up a 2D scene root via `summer_replace_node` (Node3D → Node2D). Mention this — don't surprise the user.
+- **User wants 2D but `empty` is the only 2D-friendly built-in** → use `empty`, then set up a 2D scene root via `summer_replace_node` (Node3D → Node2D). Mention this — don't surprise the user.
 - **Directory exists** → the CLI errors out. Ask for a different name; don't try to overwrite.
 
 ## Closing
 
 End with: "Project `<name>` is created and open. What do you want to build first?"
-
-That's the handoff to whatever skill comes next.

package/library/skills/organic-model/SKILL.md

@@ -13,9 +13,9 @@ paths: ["assets/organic/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 
 Organic shapes (trees, rocks, mushrooms, coral, alien flora, crystals, vines, bones) are **the most forgiving category for AI 3D generation**. Lumps look natural. Asymmetry looks natural. Smoothing-group artifacts read as bark texture. The "melted" look that ruins vehicles and characters is fine on a mossy boulder.
 
-This is the cheapest, fastest way to fill out a scene. Use it liberally — it's the recommended go-to when the user says "this scene feels empty". Each generation is ~$0.30–0.50, and the failure rate is the lowest of any 3D-asset family.
+This is the cheapest, fastest way to fill out a scene, and the first choice when the user says "this scene feels empty". The failure rate is the lowest of any 3D-asset family.
 
-Backing tool: `summer_generate_3d`. Default `hunyuan` is great here, but `trellis` is faster and quality difference is mostly invisible on organic shapes — `trellis` is the recommended pick when generating many at once.
+Backing tool: `summer_generate_3d`. Default `hunyuan` works well here, but `trellis` is faster and the quality difference is hard to see on organic shapes. Pick `trellis` when generating many at once.
 
 ## When to use
 
@@ -25,7 +25,7 @@ Backing tool: `summer_generate_3d`. Default `hunyuan` is great here, but `trelli
 - "Fill this forest scene with foliage."
 - "Alien plants for the planet surface."
 - "Coral for the underwater level."
-- The user wants visual density without spending a lot of money or time.
+- The user wants visual density quickly and cheaply.
 
 ## When NOT to use
 
@@ -84,11 +84,11 @@ Organic prompts that DON'T work:
 
 ### 3. Confirm and call
 
-> About to generate `pine_tree_01` via `trellis`, target ~2k tris. ~$0.30, ~30s. OK?
+> About to generate `pine_tree_01` via `trellis`, target ~2k tris, ~30s. This uses credits. OK?
 
 For batch generation, batch the confirmation:
 
-> About to generate 3 trees + 3 rocks + 5 mushrooms (11 generations, ~$3.50, ~5 min). All low-poly via `trellis`. OK?
+> About to generate 3 trees + 3 rocks + 5 mushrooms (11 generations, ~5 min). All low-poly via `trellis`. OK?
 
 ```
 summer_generate_3d(
@@ -144,11 +144,11 @@ Every scene-mutating tool takes an explicit `scenePath`; node paths are relative
 For dense forests, the cheapest fix beyond MultiMesh is the billboard imposter:
 
 1. Generate the tree mesh once at high polycount.
-2. Render it from one angle to a transparent PNG (Godot's `EditorScript` can capture a viewport).
+2. Render it from one angle to a transparent PNG (an `EditorScript` can capture a viewport).
 3. Use that PNG as a `Sprite3D` with `billboard = enabled`.
-4. Swap from `MeshInstance3D` to `Sprite3D` at ~50m camera distance via Godot's `VisibleOnScreenNotifier3D` or a custom LOD script.
+4. Swap from `MeshInstance3D` to `Sprite3D` at ~50m camera distance with `visibility_range_end` on the mesh and `visibility_range_begin` on the sprite (both on `GeometryInstance3D`), or a custom LOD script.
 
-For a 200-tree forest, ~10 close trees are real meshes, 190 are billboards. Frame budget saved: ~80%.
+In a 200-tree forest, only the ~10 closest trees need to be real meshes; the other 190 can be billboards.
 
 ## Anti-patterns
 
@@ -166,7 +166,7 @@ For a 200-tree forest, ~10 close trees are real meshes, 190 are billboards. Fram
 - **Branching meshes (vines, roots) come back too thick.** Specify `thin tendril, fine branches`, or accept and scale Y down in the editor.
 - **Snow / ice / frozen variant.** Add `covered in snow, frosted, ice crystals` to the prompt — works well on trees and rocks. For temperature variants of the same scene, generate the variant rather than retexturing.
 - **Crystal/glass organic.** Mesh comes back opaque. Generate the geometry, then assign a `StandardMaterial3D` with `transparency = ALPHA` and emissive in the editor.
-- **Bones, skulls, dead trees.** All work great — organic forgives them more than props would. Add `weathered, sun-bleached` for desert / tundra feel.
+- **Bones, skulls, dead trees.** All work; organic forgives them more than props would. Add `weathered, sun-bleached` for desert / tundra feel.
 
 ## Fallback (no MCP)
 

package/library/skills/pixel-art/SKILL.md

@@ -11,13 +11,13 @@ paths: ["assets/**", "art/pixel/**", "sprites/**"]
 
 # pixel-art — Pixel-Perfect Sprites and Tiles
 
-This skill generates pixel-art assets — sprites, items, tiles, icons, portraits — at a target resolution (32×32, 64×64, 128×128, etc.). Pixel art has hard constraints (grid alignment, limited palette, no anti-aliased edges) that diffusion models violate by default. This skill encodes the prompt patterns and post-processing discipline that makes the output actually look like pixel art and not "blurry small image."
+This skill generates pixel-art sprites, items, tiles, icons and portraits at a target resolution (32×32, 64×64, 128×128). Pixel art has hard constraints (grid alignment, limited palette, no anti-aliased edges) that diffusion models break by default. The prompt patterns and post-processing below make the output read as pixel art instead of a blurry small image.
 
 **Backing tool:** `summer_generate_image` with an explicit pixel-art prompt.
 
 Two things about that tool you have to know before writing a call, because both silently do nothing:
 
-- **There is no `"pixel"` style preset.** `style` accepts exactly `realistic`, `cartoon`, `anime`, `none`; anything else is coerced to `none`. Only `cartoon` and `anime` do anything at all (they append a short suffix); `realistic` and `none` append nothing. So `style: "pixel"` is identical to `style: "none"` — the pixel look has to come entirely from the prompt. Use `style: "none"` and say so honestly.
+- **There is no `"pixel"` style preset.** `style` accepts exactly `realistic`, `cartoon`, `anime`, `none`; anything else is coerced to `none`. Only `cartoon` and `anime` do anything at all (they append a short suffix); `realistic` and `none` append nothing. So `style: "pixel"` is identical to `style: "none"` — the pixel look has to come entirely from the prompt. Use `style: "none"`.
 - **`options` is not a general passthrough.** The MCP tool forwards `options` to the server, which only recognizes Nano Banana provider keys: `seed`, `outputFormat`, `safetyTolerance`, `syncMode`, `systemPrompt`, `limitGenerations`, `thinkingLevel`. `image_size` and `negative_prompt` are not among them and are dropped without an error. There is no size or aspect-ratio argument on this tool at all — MCP images come back at the server's 1:1 default. Put framing and exclusions in the prompt text instead.
 
 Pixel-perfect output is enforced in Summer Engine with Nearest texture filtering
@@ -82,14 +82,14 @@ summer_generate_image(
   prompt="pixel art slime monster, 32x32 sprite, PICO-8 palette, hard 1px outline in palette's darkest color, 3-tone shading, no anti-aliasing, no blur, sharp pixel edges, front-facing. Not blurry, no smooth gradients, no soft edges, not photorealistic, no 3D render.",
   model="nano-banana-2",
   style="none",
-  options={ removeBackground: true }
+  removeBackground=true
 )
 ```
 
 Two deliberate choices there:
 
 - **The negations live in the prompt.** There is no `negative_prompt` argument — putting one in `options` is dropped silently. Diffusion models honor in-prompt negations less reliably than a real negative-prompt field, so state them as plain sentences at the end and expect to regenerate more often than you would on a provider UI that exposes the field.
-- **`options.removeBackground: true` is real** and is the only `options` key in this skill that does anything: it runs a real background-removal pass after generation and returns a PNG with true alpha. Prefer it over asking for "transparent background" in the prompt, which is what makes models paint a literal checkerboard.
+- **`removeBackground: true` is a top-level argument**, not an `options` key. It runs a background-removal pass after generation and returns a PNG with true alpha. Prefer it over asking for "transparent background" in the prompt, which makes models paint a literal checkerboard.
 
 ### 5. Downscale to target resolution
 
@@ -158,7 +158,7 @@ Confirm `Filter: Nearest` is set in the import dock OR project-wide.
 - **User wants the entire game in pixel art.** Set `Project Settings → Rendering → Textures → Default Texture Filter: Nearest` once. Saves you from re-setting it on every import.
 - **User wants a high-res "pixel art" portrait that's not actually pixelated** (faux-pixel-aesthetic at full resolution). That's `character-portrait` with a "pixel art aesthetic" prompt — not this skill.
 - **User specifies a palette like "Sweetie-16" or "Endesga-32" and the model ignores it.** Name the hex codes explicitly. Palette names alone are unreliable below the top 5-10 famous ones.
-- **Tilesets need to tile cleanly.** Pixel-art tile-edge cleanliness from raw generation is poor. Generate the tile grid, then manually fix edge seams in Aseprite. The AI gets you 80% there.
+- **Tilesets need to tile cleanly.** Pixel-art tile-edge cleanliness from raw generation is poor. Generate the tile grid, then fix edge seams by hand in Aseprite.
 
 ## Fallback (no MCP)
 
@@ -169,7 +169,7 @@ summer_generate_image(
   prompt="<pixel art prompt with full anchor>. Not blurry, no smooth gradients, no anti-aliasing.",
   model="nano-banana-2",
   style="none",
-  options={ removeBackground: true }
+  removeBackground=true
 )
 ```
 

package/library/skills/play/SKILL.md

@@ -104,11 +104,10 @@ Leave the game running. The user wants to play it. Stop only on explicit ask.
 
 This skill mutates engine state (clearing console, starting play). It's a read-side workflow with one safe write (`summer_play`). No "May I" needed — this is what the user asked for. Do confirm before stopping a running game.
 
-## Want a working starter?
+## Requirements
 
-No template. Works against any Summer project that has a main scene set in the
-technical `project.godot` file.
+Any Summer project with a main scene set in `project.godot`.
 
 ## See also
 
-- `debugging/debug/SKILL.md` — what to do when /play surfaces an error
+- `debug` — what to do when /play surfaces an error

package/library/skills/playtesting-a-feature/SKILL.md

@@ -31,7 +31,7 @@ NO "FEATURE SHIPPED" CLAIM WITHOUT A PLAYED WALKTHROUGH
 
 If you have not, in this session, driven the feature and read back what happened, you cannot claim it works.
 
-**You walk the feature. Not the user.** A `RunVerification` probe presses your game's real inputs, reads state back across frames, and saves real rendered frames. Handing the walkthrough to the user is a last resort for things a probe genuinely cannot judge — see [What only a human can answer](#what-only-a-human-can-answer) — not the default.
+**You walk the feature. Not the user.** A `RunVerification` probe presses your game's real inputs, reads state back across frames, and saves real rendered frames. Handing the walkthrough to the user is a last resort for things a probe cannot judge — see [What only a human can answer](#what-only-a-human-can-answer) — not the default.
 
 On an engine build with the runtime-control ops (`summer_game_probe`, `summer_game_input`, `summer_game_control`, `summer_runtime_*`), drive the LIVE game instead of a hidden probe: deterministic launch, frame-stamped probe before and after every action, exact frame steps. That doctrine is the `agent-playtesting` skill; this skill's probe loop below is the path when those tools answer `engine_lacks_op`.
 
@@ -130,13 +130,13 @@ If anything is non-zero or unexpected, the feature is not done. Go to `debug`.
 
 ### What only a human can answer
 
-A probe reports facts. It cannot hold an opinion. Ask the user only when the question is genuinely experiential:
+A probe reports facts. It cannot hold an opinion. Ask the user only when the question is experiential:
 
 - **Does it feel right?** Floaty jumps, sluggish input, mushy hit feedback — see `debugging-game-feel`.
 - **Does it look good?** Composition, colour, readability. A probe can prove a light exists and prove the frame is not black; it cannot tell you the scene is ugly.
 - **Is this fun?** Not a measurable property.
 
-"I cannot simulate input" is not on that list, and has not been true since `RunVerification` shipped. If you catch yourself asking the user to press a key, write the probe instead.
+"I cannot simulate input" is not on that list: `RunVerification` presses real inputs. If you catch yourself asking the user to press a key, write the probe instead.
 
 ### 4. Probe the edges
 
@@ -210,7 +210,7 @@ Don't ask reflexively. A saved frame sequence answers most "did it visually work
 | "It would take too long to play" | Playtest takes 60 seconds. Shipping a broken feature costs hours. |
 | "The unit test passes" | Unit tests cover code paths, not gameplay sequences. |
 | "I already played it in a previous session" | State changed. Verify in this session. |
-| "I'll let the user catch any issues" | That is the user's job description for a non-AI engineer. Yours is to ship working features. |
+| "I'll let the user catch any issues" | Catching them is your job. Ship working features. |
 | Skipping `summer_clear_console` before `summer_play` | You will chase last session's errors. |
 | Sleeping a fixed delay after `summer_play` | Boot time varies. Wait for `play.started` with `summer_wait_for_event`, or confirm with `summer_is_running`. |
 | Skipping `summer_get_console` because diagnostics looked fine | Silent warnings and signal misfires hide there. |
@@ -254,8 +254,6 @@ So if `summer_play` returns "Summer Engine is not running":
 
 ## The Bottom Line
 
-A game feature is a promise to the player. Verifying it means seeing the promise kept on screen, not seeing the code that would, in theory, keep it.
-
 Press play. Walk the path. Probe the edges. Read the diagnostics. Then claim done.
 
 **Related skills:**

package/library/skills/procedural-animation/SKILL.md

@@ -11,9 +11,9 @@ paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 
 # Procedural Animation — Bones Driven by Code
 
-Generated clips give you 80% of a character. The remaining 20% — the eye contact when an NPC speaks, feet that plant on slopes, hands that wrap a sword grip, the lean into a sprint, the recoil from a hit on the left shoulder — is procedural. In Summer Engine this is done via the `SkeletonModifier3D` family attached to the `Skeleton3D`, plus tween-driven additive blend layers on the `AnimationTree`. None of it is generative; this skill is a recipe set.
+Generated clips cover most of a character's motion. The rest — the eye contact when an NPC speaks, feet that plant on slopes, hands that wrap a sword grip, the lean into a sprint, the recoil from a hit on the left shoulder — is procedural. In Summer Engine this is done via the `SkeletonModifier3D` family attached to the `Skeleton3D`, plus additive blend layers on the `AnimationTree`. None of it is generative; this skill is a set of recipes.
 
-Honest limit: Summer Engine's current IK is good enough for look-at, foot-snap,
+Limit: Summer Engine's current IK is good enough for look-at, foot-snap,
 and simple two-bone arm/leg chains. It is not a full-body IK system with weight
 redistribution. For combat-grappling or contact-heavy interactions, hand-author
 the contact frame and accept some clipping.
@@ -40,7 +40,7 @@ Almost every procedural request maps to one of these three. Pick the right one b
 
 ### Pattern A — SkeletonModifier3D (post-clip bone overrides)
 
-Attached as a child of `Skeleton3D`. Runs after the AnimationTree writes the pose, modifies specific bones in-place. Includes `LookAtModifier3D`, `SkeletonIK3D` (legacy, still supported), and the new (4.4+) `LookAtModifier3D` chain. Cheap, deterministic, no animation graph dependency.
+Attached as a child of `Skeleton3D`. Runs after the AnimationTree writes the pose, modifies specific bones in-place. Includes `LookAtModifier3D` and `SkeletonIK3D`. Cheap, deterministic, no animation graph dependency.
 
 ### Pattern B — Additive AnimationNodeAdd2 layer in the tree
 
@@ -54,7 +54,7 @@ The skeleton hands off to physics on death. Bones become `PhysicalBone3D` rigid
 
 ### A1 — Head look-at the player
 
-The bread-and-butter NPC liveliness fix.
+The most common NPC liveliness fix.
 
 **ctx lane (animation-tier engines):** one `summer_run_script` call creates the owned modifier and sets the props — prefer it over the 10-call CRUD chain below:
 
@@ -109,7 +109,7 @@ func _process(_delta: float) -> void:
     head_look.influence = clamp(1.0 - (dist - 6.0) / 2.0, 0.0, 1.0)   # fade out 6→8m
 ```
 
-`use_angle_limitation` is the production trick, and it defaults to **false** — a stock `LookAtModifier3D` does not clamp at all, so the head can rotate 180° and the model looks possessed. Turn it on and set `primary_limit_angle` to ~80° (1.4 rad), which matches a human's neck-only range; for a "whole-body turn" use it with the spine chain (next recipe). `primary_limit_angle` defaults to 2π, i.e. unlimited.
+`use_angle_limitation` is the key setting, and it defaults to **false** — a stock `LookAtModifier3D` does not clamp at all, so the head can rotate 180° and the model looks possessed. Turn it on and set `primary_limit_angle` to ~80° (1.4 rad), which matches a human's neck-only range; for a "whole-body turn" use it with the spine chain (next recipe). `primary_limit_angle` defaults to 2π, i.e. unlimited.
 
 ### A2 — Spine + head chain (look-at with body turn)
 
@@ -118,8 +118,7 @@ Multiple `LookAtModifier3D` nodes on the same chain — one for `Spine1` (`prima
 ### A3 — Foot IK (slopes & uneven terrain)
 
 The clip has the foot at Y=0; on a slope the ground is at Y=0.15. Without IK,
-the foot floats. `SkeletonIK3D` remains available for two-bone chains in the
-current Summer technical base; prefer the newer chain modifier for production:
+the foot floats. Use `SkeletonIK3D` on each two-bone leg chain:
 
 ```gdscript
 @onready var skel: Skeleton3D = $Skeleton3D
@@ -149,7 +148,7 @@ func _solve_foot(ik: SkeletonIK3D, bone_name: String) -> void:
         ik.stop()
 ```
 
-The 0.5m up-offset on the ray prevents self-occlusion. The "only lift, never drop" rule is the production fix — letting IK push feet into the ground breaks knee bends.
+The 0.5m up-offset on the ray prevents self-occlusion. The "only lift, never drop" rule matters: letting IK push feet into the ground breaks knee bends.
 
 Limits: this works for stairs and gentle slopes. On 45°+ slopes, use a pelvis lowering pass first (drop the root by `min(left_offset, right_offset)`) so the body squats and the legs don't over-extend.
 
@@ -168,7 +167,7 @@ In the AnimationTree, wrap Locomotion in an `AnimationNodeAdd2`:
     add: AnimationNodeAnimation         # an additive clip — must be authored as delta
 ```
 
-Drive `parameters/Locomotion/Add/blend_amount` (0..1) from script. Use cases: turn-lean (lean amount = clamp(turn_rate, -1, 1)), aim offset (lean while aiming up/down), breathing-while-idle. The "lean" clip must be exported with `track_type = additive` from Blender, or you'll see a 2x-pose stacked on the base.
+Drive `parameters/Locomotion/Add/blend_amount` (0..1) from script. Use cases: turn-lean (lean amount = clamp(turn_rate, -1, 1)), aim offset (lean while aiming up/down), breathing-while-idle. The lean clip must be authored as a delta from the base pose, or the pose is applied twice.
 
 ## Pattern C — Ragdoll on death
 
@@ -220,7 +219,7 @@ You need PhysicalBone3D children matching every major bone (set up once via the
 - **LookAt rotates wildly / no clamp at all.** `use_angle_limitation` is false by default and `primary_limit_angle` defaults to 2π. Set both. ~80° (1.4 rad) for a head-only modifier; ~25° (0.4 rad) for a single spine bone.
 - **IK pops on the first frame.** Solver hasn't been initialized. Call `ik.start()` after the AnimationTree's first tick, not in `_ready()` — the bone pose is identity until the tree runs.
 - **Foot IK pushes the body up on stairs but the camera doesn't follow.** Camera is parented to the root, not the head. Either parent the camera to a chest bone via `BoneAttachment3D`, or accept that the camera doesn't bob with foot IK.
-- **Additive layer doubles the clip.** The "additive" clip wasn't authored as a delta. Re-export from Blender with `Pose Mode → bake additive`.
+- **Additive layer doubles the clip.** The "additive" clip wasn't authored as a delta from the base pose. Re-author it as a delta.
 - **Ragdoll just collapses, no spread.** Missing per-bone impulse + missing collision shapes on hands/feet PhysicalBone3D children. Auto-generate via Skeleton3D inspector → "Create Physical Skeleton" with the "Add collisions" option.
 - **Modifiers run before the AnimationTree, not after.** Modifier order is set by tree-position in the scene. SkeletonModifier3D nodes must be CHILDREN of Skeleton3D and appear AFTER any nodes that drive the pose. AnimationTree itself doesn't sit under Skeleton3D — it sits at the character root and writes into Skeleton3D's pose every frame.
 - **Look-at influence flickers at fade boundary.** Use `lerp(current_influence, target, 5 * delta)` instead of an instant assignment. Avoids the sub-pixel oscillation when the player walks the threshold.
@@ -233,7 +232,7 @@ You need PhysicalBone3D children matching every major bone (set up once via the
 
 ## Anti-patterns
 
-- Writing `skel.set_bone_pose_position(...)` in `_process`. Bypasses the AnimationTree, fights it next frame, results in jitter. Use modifiers instead — they integrate with the pipeline. (Edit-time STILL poses — a corpse, a statue — are the exception: no tree is running, so `ctx.bone_pose(skel, bone, {position/rotation/scale})` on animation-tier engines, or `set_bone_pose_*` in a one-off `summer_run_script`, is exactly right. See `character-animation-wiring`.)
+- Writing `skel.set_bone_pose_position(...)` in `_process`. Bypasses the AnimationTree, fights it next frame, results in jitter. Use modifiers instead; they run after the tree. (Edit-time STILL poses — a corpse, a statue — are the exception: no tree is running, so `ctx.bone_pose(skel, bone, {position/rotation/scale})` on animation-tier engines, or `set_bone_pose_*` in a one-off `summer_run_script`, is exactly right. See `character-animation-wiring`.)
 - Putting IK targets in worldspace and forgetting they don't follow the character. Parent IK targets under the character root or bone — IK target is in the modifier's local space.
 - Procedural look-at without a fade-out at distance. Distant NPCs all snap to player every frame, looks like a hivemind.
 - Foot IK on flying / floating characters. Disable when `is_on_floor() == false`.