summer-engine 3.3.0 → 3.4.1

package/library/skills/ambient-bed/SKILL.md

@@ -13,9 +13,9 @@ paths: ["audio/ambient/**", "**/*.tscn", "**/*.import"]
 
 ## Overview
 
-An ambient bed is the *air* of a place. Forest at dawn, dungeon corridor, spaceship hum, market street, ocean cave. It plays at low energy under everything else — never melodic, never drawing attention, but its absence is immediately felt. Players don't notice an ambient bed; they notice the silence when you forget one.
+An ambient bed is the *air* of a place. Forest at dawn, dungeon corridor, spaceship hum, market street, ocean cave. It plays at low energy under everything else and is never melodic. Players rarely notice a bed, but they notice the silence when a level has none.
 
-This is **not** music. Use `summer_generate_audio({capability: 'sound_effects'})`, not `{capability: 'music'}`. SFX renders textures; Music renders melody. You want texture.
+This is **not** music. Use `summer_generate_audio({capability: 'sound_effects'})`, not `{capability: 'music'}`: the SFX model renders texture, the music model renders melody.
 
 Generated at 15–22 seconds (the SFX duration ceiling) and looped with a Summer
 Engine import loop point and optional crossfade.
@@ -28,9 +28,9 @@ Engine import loop point and optional crossfade.
 
 ## When NOT to use
 
-- Short event SFX (<5s) → `audio/sound-effect`.
-- Music with melody / chord progression → `audio/music-track`.
-- Voice barks → `audio/voice-line`.
+- Short event SFX (<5s) → `sound-effect`.
+- Music with melody / chord progression → `music-track`.
+- Voice barks → `voice-line`.
 
 ## Steps
 
@@ -50,7 +50,7 @@ Ask if it's not pinned by context:
 
 ### 3. Build the prompt — environment + time + weather + 2–3 sources + density + duration
 
-ElevenLabs SFX renders ambient textures well when the prompt names sources, not vibes.
+The SFX model renders ambient texture well when the prompt names sound sources, not moods.
 
 Prompts that work:
 
@@ -117,9 +117,7 @@ If the model returns a clip with a loud event near the start or end (a sudden bi
 
 ### 6. Mark the seamless loop in Summer Engine's Import dock
 
-This step is what makes the bed sound like a place rather than a 22-second sample.
-
-WAV and MP3 use **different importers with different option names** — do not copy the MP3 block from `audio/music-track` here. The WAV importer has no `loop` / `loop_offset`; it has an `edit/loop_mode` enum plus sample-frame bounds.
+WAV and MP3 use **different importers with different option names** — do not copy the MP3 block from `music-track` here. The WAV importer has no `loop` / `loop_offset`; it has an `edit/loop_mode` enum plus sample-frame bounds.
 
 In Summer Engine, select the `.wav` and open the Import dock:
 
@@ -144,7 +142,7 @@ After changing, click `Reimport`.
 
 ### 7. Crossfade-loop pattern for seamlessness
 
-ElevenLabs SFX returns are not gapless. Even with `loop = true`, you'll hear a tiny click on the loop point. Fix it with a two-player crossfade in code:
+Generated SFX clips are not gapless. Even with the loop mode set, you will often hear a small click at the loop point. Fix it with a two-player crossfade in code:
 
 ```gdscript
 # scripts/audio/AmbientBed.gd
@@ -278,7 +276,7 @@ Print the SFX prompt and the import dock settings. User runs via the Summer dash
 
 ## See also
 
-- `audio/audio-direction` — defines the Ambient layer class
-- `audio/sound-effect` — short event SFX layered over the bed
-- `audio/music-track` — melodic music layered over the bed
-- `audio/adaptive-music` — state-driven crossfades use the same pattern
+- `audio-direction` — defines the Ambient layer class
+- `sound-effect` — short event SFX layered over the bed
+- `music-track` — melodic music layered over the bed
+- `adaptive-music` — state-driven crossfades use the same pattern

package/library/skills/animated-loop/SKILL.md

@@ -11,11 +11,11 @@ paths: ["assets/video/**", "menus/**", "ui/**"]
 
 # animated-loop — 5 Second Seamless Background Loop
 
-A loop is the only video format that has to *not have* a beginning or end. The viewer sees it on the title screen for 30 seconds; if the seam between loop iterations is visible, the whole thing reads as broken. This skill exists to force the constraints that make seams invisible: take the shortest duration available, keep the motion ambient (no narrative, no big camera moves), use the cheap fast model (`ltx`), and prompt for a composition where the first and last frames are functionally identical.
+A loop is the only video format that has to *not have* a beginning or end. The viewer sees it on the title screen for 30 seconds; if the seam between loop iterations is visible, the whole thing reads as broken. This skill exists to force the constraints that make seams invisible: take the shortest duration available, keep the motion ambient (no narrative, no big camera moves), use the fast model (`ltx`), and prompt for a composition where the first and last frames are functionally identical.
 
 **Duration is not a dial here.** `summer_generate_video` accepts only `duration=5` or `duration=10`; the server coerces every other value to 5. So "drop to 3s to hide the seam" is not an option — 5s is the floor, and the seam has to be won in the prompt and the reference frame instead.
 
-If the user wants a 5s punchy marketing shot, that's `video/trailer-shot`. If they want a 10s narrative cutscene, that's `video/cinematic-cutscene`. This skill is the one for video that has to *disappear* — atmosphere behind a logo, mood behind a menu, ambience behind a splash card.
+If the user wants a 5s punchy marketing shot, that's `trailer-shot`. If they want a 10s narrative cutscene, that's `cinematic-cutscene`. This skill is the one for video that has to *disappear* — atmosphere behind a logo, mood behind a menu, ambience behind a splash card.
 
 ## When to use
 
@@ -28,9 +28,9 @@ If the user wants a 5s punchy marketing shot, that's `video/trailer-shot`. If th
 
 ## When NOT to use
 
-- Marketing shot for a trailer (5-10s with punch) — `video/trailer-shot`.
-- Narrative cutscene with a beginning and end — `video/cinematic-cutscene`.
-- Static splash image — generate with `2d-assets/concept-art` and use a `TextureRect`. A still is cheaper, lighter, and never seams.
+- Marketing shot for a trailer (5-10s with punch) — `trailer-shot`.
+- Narrative cutscene with a beginning and end — `cinematic-cutscene`.
+- Static splash image — generate with `concept-art` and use a `TextureRect`. A still is cheaper, lighter, and never seams.
 - UI element animation (icons, button states) — those are GDScript `Tween` or sprite sheets, not video.
 - A 10-second shot you want to "loop". That seam will be visible. Either accept a hard cut every 10s (ugly) or generate a 5s clip designed to loop.
 
@@ -40,21 +40,21 @@ If the user wants a 5s punchy marketing shot, that's `video/trailer-shot`. If th
 
 > Quick check — this loop will play on a screen the user might stare at for 30+ seconds. That means the loop point must be invisible. I'll take the 5s minimum and prompt for ambient motion (drift, flicker, shimmer) rather than a narrative beat. OK?
 
-If the user wants narrative motion (a character walking, a door opening), this is the wrong skill — route to `video/cinematic-cutscene`.
+If the user wants narrative motion (a character walking, a door opening), this is the wrong skill — route to `cinematic-cutscene`.
 
 ### 2. Pick the model — `ltx` first, always
 
-For loops, `ltx` is correct ~95% of the time. It's $0.10, ~30s, and the constraints (short duration, ambient motion) are exactly the ones `ltx` handles best. Premium models add cost without adding loop quality.
+For loops, `ltx` is almost always right. It takes ~30s, and short ambient motion is what it handles best. The premium models cost more credits and do not loop better.
 
 This skill always passes `imageUrl` (step 3), which puts every call on the image-to-video route — and that route accepts only `ltx`, `kling`, and `minimax`. `kling-turbo` and `veo3` are text-to-video only; pairing either with an `imageUrl` is a 400 `invalid_model`, not a silent downgrade.
 
-| Model | i2v? | Cost | Speed | When |
-|---|---|---|---|---|
-| `ltx` | yes | $0.10 | ~30s | Default. Use this. |
-| `kling` | yes | $0.50 | 2-4 min | Only if the loop is the centerpiece of a premium splash and quality is visibly lacking on `ltx` |
-| `minimax` | yes | $0.25 | 2-3 min | Stylized / anime aesthetic loops |
-| `kling-turbo` | **no** | $0.30 | 1-2 min | Not reachable from this skill — text-to-video only |
-| `veo3` | **no** | $1.00 | 3-5 min | Not reachable from this skill, and pointless for ambient loops anyway |
+| Model | i2v? | Speed | When |
+|---|---|---|---|
+| `ltx` | yes | ~30s | Default. Use this. |
+| `kling` | yes | 2-4 min | Only if the loop is the centerpiece of a premium splash and quality is visibly lacking on `ltx` |
+| `minimax` | yes | 2-3 min | Stylized / anime aesthetic loops |
+| `kling-turbo` | **no** | 1-2 min | Not reachable from this skill — text-to-video only |
+| `veo3` | **no** | 3-5 min | Not reachable from this skill, and pointless for ambient loops anyway |
 
 ### 3. Lock the look with a reference still
 
@@ -69,7 +69,7 @@ summer_generate_image(
 
 `summer_generate_image` has no size or aspect argument — `options.image_size` is dropped without an error and every MCP image comes back at the server's 1:1 default. Ask for the framing in the prompt, or generate the reference in the Summer dashboard (which exposes aspect ratio) and pass its URL.
 
-This matters more than usual here: on the image-to-video route `aspectRatio` is **not applied at all** — the clip inherits the reference image's framing. So a vertical mobile splash needs a genuinely 9:16 reference image, and setting `aspectRatio="9:16"` on the video call does nothing.
+On the image-to-video route `aspectRatio` is **not applied at all** — the clip inherits the reference image's framing. So a vertical mobile splash needs a 9:16 reference image, and setting `aspectRatio="9:16"` on the video call does nothing.
 
 ### 4. Prompt for loopable motion only
 
@@ -89,7 +89,7 @@ summer_generate_video(
 )
 ```
 
-The phrase **"looping, seamless"** in the prompt biases the model toward stable first/last frames. `options.negative_prompt` is one of the few provider keys that does pass through on the video route (`prompt`, `image_url`, `num_frames`, `duration`, `resolution`, and `model` are stripped; everything else is forwarded), so the negative genuinely rules out narrative drift here — unlike on `summer_generate_image`, where no such argument exists.
+The phrase **"looping, seamless"** in the prompt biases the model toward stable first/last frames. `options.negative_prompt` is one of the few provider keys that does pass through on the video route (`prompt`, `image_url`, `num_frames`, `duration`, `resolution`, and `model` are stripped; everything else is forwarded), so the negative prompt does rule out narrative drift here — unlike on `summer_generate_image`, where no such argument exists.
 
 `aspectRatio` is omitted deliberately: it is applied on the text-to-video path only, and this call passes `imageUrl`.
 
@@ -115,7 +115,7 @@ VideoStream exts: ["ogv", "tres", "res"]
 ERROR: No loader found for resource: res://clip.mp4 (expected type: unknown)
 ```
 
-`summer_import_from_url` downloads the bytes, runs Godot's import pipeline, and *fails the import* if the file never becomes a loadable resource — so importing the `.mp4` does not quietly half-work, it is rejected and rolled back. Convert first:
+`summer_import_from_url` downloads the bytes, runs the engine's import pipeline, and *fails the import* if the file never becomes a loadable resource — so importing the `.mp4` does not quietly half-work, it is rejected and rolled back. Convert first:
 
 ```
 ffmpeg -i title_screen_bg.mp4 -c:v libtheora -q:v 8 -an title_screen_bg.ogv
@@ -137,7 +137,7 @@ summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop",
 summer_save_scene(scenePath="res://ui/title_screen.tscn")
 ```
 
-Anchors preset 15 is "full rect" — the loop fills the menu. Place the logo and menu buttons as children *above* the `VideoStreamPlayer` in the tree (Godot draws siblings in tree order; later siblings render on top).
+Anchors preset 15 is "full rect" — the loop fills the menu. Place the logo and menu buttons as children *above* the `VideoStreamPlayer` in the tree (Controls draw in tree order; later siblings render on top).
 
 ### 7. Mute the audio track
 
@@ -147,22 +147,22 @@ Loops should never have a baked audio track that loops with them — the audio s
 summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="volume_db", value=-80)
 ```
 
-Score the menu separately with `audio/music-track`.
+Score the menu separately with `music-track`.
 
 ## Reference card — prompts that work
 
 Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping, seamless" + <stylistic anchor>`. Keep under 40 words. Always pair with `imageUrl`.
 
-| Goal | Model | Prompt | Cost | Duration |
-|---|---|---|---|---|
-| Title menu — fog forest | `ltx` | `dense pine forest in low fog, fog drifting slowly between trunks, soft moonlight, ambient particles rising, looping, seamless, cinematic painterly` | $0.10 | 5s |
-| Title menu — dungeon torch | `ltx` | `stone dungeon corridor lit by a single torch, flame flickering steadily, dust motes drifting in the light cone, looping, seamless` | $0.10 | 5s |
-| Splash — embers / sky | `ltx` | `dusk sky with slow drifting embers rising upward across frame, deep blue gradient, looping, seamless, cinematic` | $0.10 | 5s |
-| Logo backdrop — magic runes | `ltx` | `dark surface with glowing blue runes pulsing softly in slow rhythm, faint shimmer, no narrative motion, looping, seamless` | $0.10 | 5s |
-| Menu — underwater | `ltx` | `underwater scene with caustic light dancing on a sandy floor, slow drifting bubbles, gentle current sway on kelp, looping, seamless` | $0.10 | 5s |
-| Pause screen — slow rain | `ltx` | `window pane with continuous gentle rain drops, blurred warm interior glow behind, looping, seamless, ambient` | $0.10 | 5s |
-| Title — anime sky | `minimax` | `anime style cumulus clouds drifting slowly across a pastel sunset sky, soft, painterly, looping, seamless, Ghibli` | $0.25 | 5s |
-| Premium splash centerpiece | `kling` | `dragon silhouette breathing in profile against a vast sunset sky, only the chest rising and falling and clouds drifting, looping, seamless` | $0.50 | 5s |
+| Goal | Model | Prompt | Duration |
+|---|---|---|---|
+| Title menu — fog forest | `ltx` | `dense pine forest in low fog, fog drifting slowly between trunks, soft moonlight, ambient particles rising, looping, seamless, cinematic painterly` | 5s |
+| Title menu — dungeon torch | `ltx` | `stone dungeon corridor lit by a single torch, flame flickering steadily, dust motes drifting in the light cone, looping, seamless` | 5s |
+| Splash — embers / sky | `ltx` | `dusk sky with slow drifting embers rising upward across frame, deep blue gradient, looping, seamless, cinematic` | 5s |
+| Logo backdrop — magic runes | `ltx` | `dark surface with glowing blue runes pulsing softly in slow rhythm, faint shimmer, no narrative motion, looping, seamless` | 5s |
+| Menu — underwater | `ltx` | `underwater scene with caustic light dancing on a sandy floor, slow drifting bubbles, gentle current sway on kelp, looping, seamless` | 5s |
+| Pause screen — slow rain | `ltx` | `window pane with continuous gentle rain drops, blurred warm interior glow behind, looping, seamless, ambient` | 5s |
+| Title — anime sky | `minimax` | `anime style cumulus clouds drifting slowly across a pastel sunset sky, soft, painterly, looping, seamless, Ghibli` | 5s |
+| Premium splash centerpiece | `kling` | `dragon silhouette breathing in profile against a vast sunset sky, only the chest rising and falling and clouds drifting, looping, seamless` | 5s |
 
 ### Bad prompts and why
 
@@ -178,7 +178,7 @@ Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping
 
 - **Asking the model for a 10s loop.** Past ~6s, identity drifts and the seam shows. `duration=5` is both the floor and the right answer; 10 is the only other value the API accepts.
 - **Treating `summer_generate_video` as synchronous.** It returns `{ queued: true, jobId }` and no URL. Poll `summer_check_job` before claiming a clip exists.
-- **Spending `kling` money on a loop.** `ltx` is the right call ~95% of the time. The constraints favor the cheap model.
+- **Using `kling` for a loop.** `ltx` is almost always right; short ambient motion is what it does best.
 - **Prompting narrative motion.** "Hero draws sword" doesn't loop. Use ambient verbs.
 - **Forgetting `loop=true` on the `VideoStreamPlayer`.** The clip will play once and freeze on the last frame.
 - **Forgetting to mute baked audio.** If audio is on, the loop point becomes audible even if it's invisible.
@@ -188,17 +188,17 @@ Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping
 ## Edge cases
 
 - **Splash loop must be tiny in build size.** Loops compress aggressively because of low motion. Target ≤2MB by exporting at 720p, low bitrate, in DaVinci. Studio's import doesn't re-encode by default.
-- **Mobile portrait splash.** The reference image must genuinely be portrait — `aspectRatio` is ignored on the image-to-video path, and MCP image generation is square-only, so make the reference in the Summer dashboard or crop it. Anchors preset 15 still works.
+- **Mobile portrait splash.** The reference image must be portrait — `aspectRatio` is ignored on the image-to-video path, and MCP image generation is square-only, so make the reference in the Summer dashboard or crop it. Anchors preset 15 still works.
 - **Loop must sync to a music beat.** The video model doesn't know your BPM. Generate at the duration matching one bar at the menu music tempo (e.g. 120 BPM × 4 beats = 2s, or 8 beats = 4s) and confirm visually.
 - **Loop is behind translucent UI.** Generate with extra contrast headroom — the model tends toward mid-grey, and translucent UI on mid-grey reads muddy. Push for `high contrast cinematic` in the prompt.
 - **Loop seam still visible after 3 regens.** Set up two `VideoStreamPlayer` siblings and crossfade between them with a `Tween` on a 0.5s overlap. Costs an extra GPU decode but hides the seam.
 
 ## Fallback (no MCP)
 
-If the Studio MCP server isn't running, route the user to the Studio web dashboard:
+If the MCP server isn't running, route the user to the Summer dashboard:
 
 1. Image tab → generate the reference still (the loop's "neutral frame").
-2. Video tab → image-to-video with `ltx`, duration 4s, aspect ratio per target.
+2. Video tab → image-to-video with `ltx`, duration 5s, aspect ratio per target.
 3. Prompt with the loopable-motion vocabulary above and `"looping, seamless"`.
 4. Download the result, transcode to `.ogv` if needed, place under `assets/video/loops/`.
 
@@ -209,16 +209,16 @@ Print the exact prompt + model + duration + aspect ratio so the user can paste i
 Once the loop is wired:
 
 > Loop `title_screen_bg` is wired to `TitleScreen/BackgroundLoop` with autoplay + loop. Next:
-> - Score the menu with `audio/music-track` — a quiet ambient bed scored to the loop's mood.
-> - For the logo and menu UI on top, hand off to `2d-assets/ui-graphics`.
-> - If the user wants a punchy 5s shot for the trailer using the same look, hand off to `video/trailer-shot` (reuse the reference image).
-> - If the user wants a narrative intro that plays *before* the title loops, hand off to `video/cinematic-cutscene`.
+> - Score the menu with `music-track` — a quiet ambient bed scored to the loop's mood.
+> - For the logo and menu UI on top, hand off to `ui-graphics`.
+> - If the user wants a punchy 5s shot for the trailer using the same look, hand off to `trailer-shot` (reuse the reference image).
+> - If the user wants a narrative intro that plays *before* the title loops, hand off to `cinematic-cutscene`.
 
 ## See also
 
-- `video/trailer-shot` — punchy marketing footage.
-- `video/cinematic-cutscene` — narrative cutscenes with dialogue.
-- `audio/music-track` — score the menu.
-- `2d-assets/ui-graphics` — logo, menu buttons, HUD that sits over the loop.
-- `2d-assets/concept-art` — produce the reference still that anchors the loop.
+- `trailer-shot` — punchy marketing footage.
+- `cinematic-cutscene` — narrative cutscenes with dialogue.
+- `music-track` — score the menu.
+- `ui-graphics` — logo, menu buttons, HUD that sits over the loop.
+- `concept-art` — produce the reference still that anchors the loop.
 - `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

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

@@ -11,18 +11,18 @@ paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 
 # AnimationTree — Wire Clips Into Behavior
 
-Generation gives you clips. The AnimationTree gives the character life. This skill is **not generative** — no FAL, no MCP AI calls. It composes existing clips on an `AnimationPlayer` into an `AnimationTree` with a `StateMachine` for distinct states (idle / attack / hit / dead) and `BlendSpace` nodes for continuous parameters (walk-run blend by speed). Done right, the character moves like a shipped game; done wrong, you get T-poses, snapping, or animations that "eat" each other.
+This skill generates nothing. It composes existing clips on an `AnimationPlayer` into an `AnimationTree` with a `StateMachine` for distinct states (idle / attack / hit / dead) and `BlendSpace` nodes for continuous parameters (walk-run blend by speed). Wired wrong, you get T-poses, snapping, or clips that cut each other off.
 
 The canonical Summer Engine stack:
 
 ```
 Character (CharacterBody3D)
-├── Skeleton3D (from the Meshy rig)
+├── Skeleton3D (from the rigged GLB)
 ├── AnimationPlayer            # holds the raw clips (idle, walk, run, attack_sword, ...)
 └── AnimationTree              # references AnimationPlayer, drives behavior
 ```
 
-Before adding the tree, prove direct `AnimationPlayer.play()` visibly moves the rig. Godot may import animation GLBs as `AnimationLibrary` resources or as `PackedScene`s with embedded `AnimationPlayer`s. If a copied clip appears in the list but the mesh T-poses, its tracks probably target a different root/skeleton path. Use the embedded player that came with the matching GLB, or remap/copy tracks only after confirming they target the active `Skeleton3D`. An inactive AnimationTree is also a no-op, so always set `AnimationTree.active = true`.
+Before adding the tree, prove direct `AnimationPlayer.play()` visibly moves the rig. The engine may import animation GLBs as `AnimationLibrary` resources or as `PackedScene`s with embedded `AnimationPlayer`s. If a copied clip appears in the list but the mesh T-poses, its tracks probably target a different root/skeleton path. Use the embedded player that came with the matching GLB, or remap/copy tracks only after confirming they target the active `Skeleton3D`. An inactive AnimationTree is also a no-op, so always set `AnimationTree.active = true`.
 
 ## When to use this skill
 
@@ -72,7 +72,7 @@ Before walking the CRUD steps below, check the ctx lane — one `summer_run_scri
 - **Animation-tier engines:** `ctx.anim_state_machine(character, {states: {...}, transitions: [[from, to, {blend_s: 0.2}], ...], start: "idle"})` gets-or-creates the AnimationTree, wires it to the player, builds the state machine, sets `active = true`. Unknown clip names come back as a report entry listing the player's REAL clips — never wire against guessed names. Full recipe (inspect clips/bones first, method-track events, root motion, playtest verification): `character-animation-wiring`.
 - **Any engine (raw fallback):** the same classes are fully script-bound — `AnimationNodeStateMachine.add_node(name, AnimationNodeAnimation)`, `add_transition(from, to, AnimationNodeStateMachineTransition)` (one transition resource each, `xfade_time` on it), then `tree.anim_player = tree.get_path_to(player)`, `tree.tree_root = sm`, `tree.active = true`, and `ctx.set_owner_recursive(tree)`. The raw script is quoted in `character-animation-wiring`.
 
-Note the helper's scope honestly: `anim_state_machine` builds clip states + transitions only. The canonical machine below — BlendSpace1D locomotion, OneShot attack/hit — still needs the `.tres` (or raw-script) lane for those node types. Discrete idle/walk/run backbones don't.
+Scope: `anim_state_machine` builds clip states + transitions only. The canonical machine below — BlendSpace1D locomotion, OneShot attack/hit — still needs the `.tres` (or raw-script) lane for those node types. Discrete idle/walk/run backbones don't.
 
 ## Steps via MCP
 
@@ -259,7 +259,7 @@ Then `summer_play` and watch — the goblin should idle in place, blend up to wa
 
 - **OneShot:** the action is a *temporary override* of an underlying state (attack while running, hit-react while attacking). The base keeps playing.
 - **StateMachine state:** the action is a *replacement* (dead, stunned, ragdoll). Nothing else plays.
-- Combat in 2026-feel games is almost always OneShot for attacks + StateMachine state for "dead". Don't model attacks as StateMachine states unless you need precise transition control between attack-string variants.
+- Action combat is usually OneShot for attacks + a StateMachine state for "dead". Don't model attacks as StateMachine states unless you need precise transition control between attack-string variants.
 
 ### BlendSpace1D vs BlendSpace2D
 
@@ -270,7 +270,7 @@ Then `summer_play` and watch — the goblin should idle in place, blend up to wa
 
 - Skipping AnimationTree and calling `AnimationPlayer.play("walk")` from script. Works for one clip; breaks the moment you need a crossfade.
 - Modeling every attack as a StateMachine state. The transition matrix explodes (N states × N transitions). Use one OneShot per attack and switch its inner clip via `parameters/Attack/animation`.
-- Writing the `.tres` by hand without using sub_resource IDs — Godot loses references and the inspector is unhappy. Always use `[sub_resource id="..."]` blocks.
+- Writing the `.tres` by hand without using sub_resource IDs — the engine loses the references. Always use `[sub_resource id="..."]` blocks.
 - Driving `blend_position` from raw input (`Input.get_axis(...)`). Drive from actual velocity — that way the blend matches the body's real motion, including knockback and slope-slide.
 
 ## Edge cases

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

@@ -13,7 +13,7 @@ paths: [".summer/**", "project.godot", "**/*.tscn"]
 
 ## Overview
 
-A consistent art direction is what makes a low-budget game *look* like a finished game. Most solo devs lose this fight by mixing styles — a toon-shaded character on a photoreal terrain, a pixel UI over a smooth 3D world. This skill builds an art bible the rest of the project obeys: references, palette, mood, lighting plan, post-processing, and a do/don't list. It writes to `.summer/art-bible.md` — the file every rendering / shader / lighting / VFX skill reads later.
+A consistent art direction makes a low-budget game look finished. Solo developers most often lose it by mixing styles — a toon-shaded character on a photoreal terrain, a pixel UI over a smooth 3D world. This skill builds an art bible the rest of the project obeys: references, palette, mood, lighting plan, post-processing, and a do/don't list. It writes to `.summer/art-bible.md` — the file every rendering / shader / lighting / VFX skill reads later.
 
 **Core principle:** Constraint produces style. A game with **15 colors total** looks more intentional than a game with infinite-color textures. Pick the constraint, then defend it.
 
@@ -118,7 +118,7 @@ State the plan in one block. For the current Summer Engine rendering stack:
 ```
 Sun: DirectionalLight3D, color #fff2d9, energy 0.9, angle ~30° (warm low-angle)
 Sky: ProceduralSkyMaterial, sky_top_color #6b88a3, sky_horizon_color #d8b88e
-Ambient: AmbientLight #4a5570, energy 0.15
+Ambient: Environment ambient_light_color #4a5570, ambient_light_energy 0.15
 Indoor fills: OmniLight3D color #ffd9a8, energy 0.6, range 4m
 NEVER: pure-white DirectionalLight, no ambient, hard cube shadows
 ```
@@ -138,7 +138,7 @@ Summer Engine post stack: Glow, SDFGI, SSAO, SSR, Adjustments, Color Correction
 
 ```
 Glow: ON, threshold 0.9, intensity 0.5  (soft bloom on highlights only)
-SDFGI: OFF for vertical-slice scope (perf cost; bake light probes later)
+SDFGI: OFF for vertical-slice scope (perf cost; bake lightmaps later)
 SSAO: ON, light_affect 0.3 (just enough for grounding)
 SSR: OFF unless we have wet/glass surfaces
 Color correction: Filmic tonemap, slight S-curve LUT toward warm
@@ -159,7 +159,7 @@ This is the contract. Five do's, five don'ts. Specific, enforceable.
 - Outline shader on character + interactable props (no outline on environment).
 - Soft shadows (DirectionalLight3D shadow_blur 1.5).
 - Warm key + cool fill — never both warm or both cool.
-- Texture filter: Linear with mipmaps OFF for crunchy near-pixel feel.
+- Texture filter: Nearest for a crunchy, near-pixel feel.
 
 ## DON'T
 - No pure white (#ffffff). Use #f4ecdf.
@@ -176,7 +176,7 @@ Some art-direction calls translate to `project.godot` settings. Apply them.
 **Preferred (Summer MCP):**
 
 ```
-summer_project_setting(key="rendering/textures/canvas_textures/default_texture_filter", value="2")  # Linear no mipmaps if pixel-art-ish
+summer_project_setting(key="rendering/textures/canvas_textures/default_texture_filter", value="0")  # Nearest, if pixel-art-ish (1 = Linear, the default)
 summer_project_setting(key="rendering/environment/defaults/default_clear_color", value="Color(0.227, 0.290, 0.227)")  # palette primary
 summer_project_setting(key="rendering/anti_aliasing/quality/msaa_3d", value="2")  # MSAA 2x for clean edges
 ```
@@ -274,9 +274,6 @@ No template — this is a workflow that produces the bible the rest of the proje
 
 ## See also
 
-- `scene-and-project/brainstorm-game/SKILL.md` — produces the brief that anchors the bible
-- `audio/audio-direction/SKILL.md` — the sonic counterpart
-- `rendering-and-lighting/3d-lighting/SKILL.md` — implements the lighting plan
-- `shaders/shader-basics/SKILL.md` — for outline / toon shaders
-- `post-processing/bloom-and-glow/SKILL.md` — implements the glow rule
-- `post-processing/color-grading/SKILL.md` — implements the LUT and tonemap call
+- `brainstorm-game` — produces the brief that anchors the bible
+- `audio-direction` — the sonic counterpart
+- `3d-lighting` — implements the lighting plan and the environment's glow, tonemap and SSAO settings

package/library/skills/asset-strategy/SKILL.md

@@ -34,7 +34,7 @@ Ask the **exact phrase** before dispatching. Skipping the question is the most c
 | Concept art vs character portrait | "Quick check — exploring the look (3-4 variants for art direction) or generating a final character portrait for dialogue UI?" | `concept-art` (exploring) / `character-portrait` (final) |
 | Prop vs character model | "Static object (sword, chair, lantern) or rigged character that needs animation?" | `prop-model` / `character-model` |
 | Tile vs sprite sheet | "One seamless tile that repeats, or a frame grid for an animated sprite?" | `tileable-texture` / `sprite-sheet` |
-| SFX vs music | "One-shot effect or a longer track (loop, theme, ambient bed)?" | `sound-effect` / `music-track` (or `audio/ambient-bed`) |
+| SFX vs music | "One-shot effect or a longer track (loop, theme, ambient bed)?" | `sound-effect` / `music-track` (or `ambient-bed`) |
 | Generate vs retarget motion | "Generate a new clip on this character, or apply an existing library to a new character?" | `generate-motion` / `retarget` |
 | VFX recipe vs game-feel | "Particle/shader effect in the world or screen-feel (camera shake, hit-stop)?" | `vfx-<name>` / `game-feel` |
 
@@ -61,7 +61,7 @@ Invoke the specialist via the `Skill` tool. Don't paraphrase — let it run. Pas
 | Request | Skill |
 |---|---|
 | Sword / chair / barrel / static object | `prop-model` |
-| Player / NPC / enemy / boss / rigged humanoid | `character-model` (canonical Meshy auto-rig) |
+| Player / NPC / enemy / boss / rigged humanoid | `character-model` (generated mesh + auto-rig) |
 | Modular dungeon / building blocks | `environment-kit` |
 | Car / spaceship / hard-surface vehicle | `vehicle-model` |
 | Tree / rock / mushroom / foliage | `organic-model` |
@@ -132,4 +132,4 @@ VFX is **code, not generative** — recipes are shader + GDScript + node setup,
 
 ## Fallback (no MCP)
 
-The router still works without MCP — classification is text-only. It hands off to the specialist, which surfaces its own no-MCP fallback (typically: run the equivalent generation via the Summer dashboard / Meshy / nano-banana web, then `summer_import_from_url` once MCP is back).
+The router still works without MCP — classification is text-only. It hands off to the specialist, which surfaces its own no-MCP fallback (typically: run the same generation in the Summer dashboard, then `summer_import_from_url` once MCP is back).

package/library/skills/audio-direction/SKILL.md

@@ -13,7 +13,7 @@ paths: [".summer/**", "project.godot", "**/*.tscn", "audio/**"]
 
 ## Overview
 
-Most indie games sound like a single library used flat. The same generic "swoosh" for menu, jump, pickup, hit. That's not audio direction — that's audio absence. This skill builds an audio bible that names the music style, the SFX vocabulary, the dynamic music plan, and the spatial / mix rules. Writes to `.summer/audio-bible.md` and configures the audio bus layout in the project so the rest of the work has a real foundation.
+Many indie games sound like one sound library used flat: the same generic "swoosh" for menu, jump, pickup and hit. This skill builds an audio bible that names the music style, the SFX vocabulary, the dynamic music plan, and the spatial / mix rules. Writes to `.summer/audio-bible.md` and configures the audio bus layout in the project so the rest of the work has a real foundation.
 
 **Core principle:** SFX needs a *vocabulary*, not a *library*. Eight named SFX classes with consistent character beat 80 random library hits.
 
@@ -25,7 +25,7 @@ Ask exactly this:
 
 > Three reference tracks, games, or films for the music. What instruments matter? And what's the SFX vibe — chunky, clean, synthetic, or organic?
 
-Three is the minimum. One or two collapses into a clone. References are the highest-signal input — listen carefully.
+Three is the minimum. One or two collapses into a clone.
 
 If they freeze, offer four axes (not titles):
 
@@ -237,9 +237,9 @@ End with:
 | Music louder than SFX | Players need SFX for gameplay; music is mood. Default mix is -8 dB music vs 0 dB SFX. |
 | No reverb buses | "Send" architecture (rooms route to a small/large/outdoor reverb bus) is mandatory or your mix sounds dry-then-wet inconsistently. |
 | Pure sine "ding" for pickup | Reads as cheap mobile game. Use a major-third interval with character. |
-| Same footstep sample for all surfaces | Material-aware footsteps are 80% of the perceived audio quality. |
+| Same footstep sample for all surfaces | Players hear footsteps constantly; material-aware steps carry much of the perceived audio quality. |
 | No master ceiling / true peak | Audio clips on console builds without `-1 dBTP` ceiling. Always set it. |
-| Assuming SetResourceProperty fails silently on inline sub_resources | It does not — inline targets work, and the structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors. What *is* silent on current engines is a bad value shape: a JSON object instead of a Godot literal string, a misspelled `subProperty`, or a wrong-typed value returns `ok:true` yet no-ops or coerces destructively. Pass class names and literal strings, and confirm in the saved `.tres`/`.tscn`, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`. |
+| Assuming SetResourceProperty fails silently on inline sub_resources | It does not — inline targets work, and the structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors. What *is* silent on current engines is a bad value shape: a JSON object instead of an engine literal string, a misspelled `subProperty`, or a wrong-typed value returns `ok:true` yet no-ops or coerces destructively. Pass class names and literal strings, and confirm in the saved `.tres`/`.tscn`, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`. |
 
 ## Collaborative protocol
 
@@ -255,9 +255,7 @@ No template — this is a workflow that produces the bible the rest of the proje
 - `../../references/godot-version/godot-version.md` — Summer compatibility and
   version-sensitive audio API notes
 - `../../references/mcp-tools-reference/mcp-tools-reference.md`
-- `scene-and-project/brainstorm-game/SKILL.md` — produces the brief that anchors the bible
-- `rendering-and-lighting/art-direction/SKILL.md` — the visual counterpart; audio must rhyme with it
-- `audio/audio-bus-setup/SKILL.md` (NEXT) — implements the bus layout in detail
-- `audio/3d-spatial-audio/SKILL.md` (NEXT) — spatial attenuation patterns
-- `audio/footstep-systems/SKILL.md` (NEXT) — material-aware footstep impl
-- `audio/dynamic-music-stingers/SKILL.md` (LATER) — implements the dynamic music plan
+- `brainstorm-game` — produces the brief that anchors the bible
+- `art-direction` — the visual counterpart; audio must rhyme with it
+- `adaptive-music` — implements the dynamic music plan
+- `sound-effect`, `music-track`, `ambient-bed`, `voice-line` — generate the audio the bible describes

package/library/skills/auto-fire-targeting/SKILL.md

@@ -172,10 +172,11 @@ Use `summer_get_diagnostics` to confirm no new errors.
 `summer_inspect_node` will **not** show you `pending_damage` mid-fight. It reads
 the edited scene in the editor — the response even tags itself
 `provenance: editor_scene` — so it reports the saved node, not the live
-instance. Runtime values need a runtime probe.
+instance. Runtime values need a runtime read: with the game running, read
+the enemy with `summer_inspect_runtime_node` or `summer_game_probe` (engine
+builds with the runtime-control ops; see the `agent-playtesting` skill).
 
-The route that works from MCP is the `RunVerification` op, sent through
-`summer_batch`. It spins up a hidden, disposable game instance that runs a
+On any build, the `RunVerification` op, sent through `summer_batch`, also works. It spins up a hidden, disposable game instance that runs a
 GDScript probe and exits; it never touches the editor:
 
 ```

package/library/skills/bounded-engine-runs/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: bounded-engine-runs
+description: "Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: workflow
+user-invocable: true
+allowed-tools: Read Grep Glob Edit Write Bash
+paths: ["project.godot", "tests/**/*.gd", "tools/**/*.gd"]
+---
+
+# Bounded engine runs for agents
+
+Agents verify games by running the engine many times: imports, tests, captures, multiplayer bots. A run
+that hangs, overlaps another, makes noise or hides an error costs time. These rules keep runs safe when
+several agents share one project on one machine.
+
+## 1. Every run is bounded, muted and alone
+
+- **Bound it.** macOS has no `timeout`. Wrap runs so the engine itself gets killed:
+  ```sh
+  perl -e 'alarm shift; exec @ARGV' 180 <summer> --headless --path . -s res://tests/run_tests.gd
+  ```
+  `alarm` survives `exec`; exit code 142 means the limit hit.
+- **One engine per project at a time.** Two engines writing the same `.godot/` import cache corrupt it or
+  freeze each other's captures. Serialize with a lock file held by the engine process:
+  ```sh
+  perl -e 'use Fcntl qw(:flock); $^F=255; open(my $l,">>",shift) or die; flock($l,LOCK_EX); alarm shift; exec @ARGV' \
+    <project>/.engine.lock 180 <summer> ...
+  ```
+  Put this in one wrapper script and make every agent use it.
+- **Cap its memory.** A time limit does not stop a run from eating all memory first; several engine runs plus a
+  browser loading a large web export can exhaust memory and crash the machine. The wrapper should run the command as a child, sum the resident
+  memory of its whole process tree (browsers spawn GPU/renderer helpers), kill the tree past a cap (e.g.
+  3 GB), and also stop when system free memory falls low (`sysctl -n kern.memorystatus_level` < 15 on macOS),
+  because GPU memory on Apple Silicon is system memory but is not counted in RSS. Refuse to start when the
+  system is already short (< 35).
+- **Mute it.** `--audio-driver Dummy`.
+- **Render only when you must, and offscreen.** `--headless` for logic (no pixels). For visual checks use
+  `--summer-offscreen` with a fixed `--resolution` and a capture script that saves PNGs and quits. Visible
+  windows only when a human asked to watch.
+
+## 2. Imports and parse errors
+
+- New `class_name` scripts are unknown to `-s` scripts until an import pass registers them:
+  `<summer> --headless --audio-driver Dummy --path . --import`.
+- The first import may rewrite `project.godot` (reorder keys, add a `[summer]` section; one trial saw a
+  hand-written `[rendering]` section dropped). Check `git diff project.godot` after it, and pass renderer
+  choices on the command line (`--rendering-method ...`) when a run depends on them.
+- One broken `class_name` script cascades into "Could not parse global class" and dozens of unrelated
+  "cannot infer type" errors. Get the real line with:
+  `<summer> --headless --path . --check-only -s res://path/to/file.gd`
+- Compile every script before booting the game: a tiny `SceneTree` script that `load()`s each `.gd` under
+  a folder and reports `can_instantiate()` failures, exit code = failures.
+
+## 3. Tests that can't lie
+
+- A runtime script error inside a test does not fail it by default; the test just stops and counts as
+  passed. Register a logger and fail the test when its error count rises:
+  ```gdscript
+  class ErrorCounter extends Logger:
+  	var script_errors := 0
+  	func _log_error(_f: String, file: String, _line: int, _c: String, _r: String, _n: bool, type: int, _bt: Array[ScriptBacktrace]) -> void:
+  		if type == Logger.ERROR_TYPE_SCRIPT or file.ends_with(".gd"):
+  			script_errors += 1
+  	func _log_message(_m: String, _e: bool) -> void:
+  		pass
+  # in the runner: OS.add_logger(counter); compare counter.script_errors before and after each test
+  ```
+- Exit 0 is not success. Always grep the log for `SCRIPT ERROR`, `Parse Error` and `ERROR:`, and print
+  one explicit success line (`TESTS passed=N failed=0`) you can check for.
+
+## 4. Typed GDScript traps agents hit repeatedly
+
+- `var x := dict["k"]` cannot infer a type (Dictionary values are Variant). Write `var x: int = dict["k"]`.
+- A loop variable that shadows an outer variable is a parse error that takes the whole class down.
+- Don't name a class after an engine class (`SummerSession`); the error only says it "hides a native class".
+
+## 5. Web exports on a dev machine
+
+- Check the `.pck` size before opening it in a browser; the browser holds all of it in memory. A project that
+  exports every imported asset of a large scene can pass 250 MB. Ship only what the game uses first.
+- Load it in a browser only under the same memory-capped wrapper, one at a time, never next to other engine runs.
+
+## 6. Captures you can trust
+
+- Read every PNG you produce. If several files are identical (`md5 -r *.png`), the run froze; rerun alone.
+- Keep evidence outside the project (logs, PNGs) so imports never pick it up. If it must live inside, put an
+  empty `.gdignore` file in that folder so the editor and imports skip it.
+
+## See also
+
+- `headless-scripting` (writing the SceneTree scripts these runs execute)
+- `multiplayer-testing` (Local Play bot runs)
+- `compatibility-renderer-traps` (dual-renderer captures)

package/library/skills/bounded-engine-runs/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/bounded-engine-runs
+kind: skill
+version: 1.0.0
+summary: "Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes."
+use_when:
+  - running the engine from a shell or agent for tests, imports, captures or bots
+  - several agents or processes share one project
+  - a run hangs, a capture freezes, or errors cascade across unrelated scripts
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - headless
+    - verification
+  modalities:
+    - project
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/headless-scripting
+    - skill/multiplayer-testing
+    - skill/compatibility-renderer-traps
+source: official
+license: MIT
+status: preview
+recommended: true

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

@@ -201,8 +201,8 @@ No template — this is a workflow that produces the brief that drives template
 
 ## See also
 
-- `gameplay-mechanics/design-mechanic/SKILL.md` — design the core loop in detail
-- `level-design/design-level/SKILL.md` — sketch level 1
-- `rendering-and-lighting/art-direction/SKILL.md` — turn the one-phrase look into a full bible
-- `audio/audio-direction/SKILL.md` — sonic identity
-- `scene-and-project/make-game/SKILL.md` — scaffold the project once the brief is locked
+- `design-mechanic` — design the core loop in detail
+- `design-level` — sketch level 1
+- `art-direction` — turn the one-phrase look into a full bible
+- `audio-direction` — sonic identity
+- `make-game` — scaffold the project once the brief is locked