summer-engine 3.4.0 → 3.4.1

package/library/skills/cinematic-cutscene/SKILL.md

@@ -13,7 +13,7 @@ paths: ["assets/video/**", "cinematics/**", "trailers/**"]
 
 A cutscene is a non-interactive video clip the game plays back at a fixed moment — opening, story beat, character intro, ending. Quality is dominated by **two things**: continuity (the character on screen looks like the character in the game) and shot length (every clip past 10s drifts in identity, hands, and physics). This skill enforces both — generate a reference image first to lock the look, then image-to-video each shot, then chain shots in sequence rather than asking the model for one long take.
 
-If the user wants 5 seconds of marketing footage, that's `video/trailer-shot`. If they want a 3-second seamless background loop, that's `video/animated-loop`. This skill is for narrative beats with a defined start, middle, and end — usually with dialogue or VO.
+If the user wants 5 seconds of marketing footage, that's `trailer-shot`. If they want a seamless background loop, that's `animated-loop`. This skill is for narrative beats with a defined start, middle, and end — usually with dialogue or VO.
 
 ## When to use
 
@@ -26,10 +26,10 @@ If the user wants 5 seconds of marketing footage, that's `video/trailer-shot`. I
 
 ## When NOT to use
 
-- "5-second slow-mo combat shot for the trailer" — `video/trailer-shot`.
-- "Looping splash screen background" — `video/animated-loop`.
-- "Animated logo backdrop on the title screen" — `video/animated-loop`.
-- Real-time in-engine cinematic with the actual gameplay characters and camera — that's a Godot AnimationPlayer / Timeline job, not generated video. Route to `scene-composition`.
+- "5-second slow-mo combat shot for the trailer" — `trailer-shot`.
+- "Looping splash screen background" — `animated-loop`.
+- "Animated logo backdrop on the title screen" — `animated-loop`.
+- Real-time in-engine cinematic with the actual gameplay characters and camera — that's an AnimationPlayer job, not generated video. Route to `scene-composition`.
 - Voice-only narration over a static image — generate the dialogue with `summer_generate_audio` and use a static `TextureRect`, no video needed.
 
 ## Steps
@@ -51,7 +51,7 @@ Cutscenes longer than 10 seconds are **multiple shots**, not one take. Ask the u
 
 > Want this as one 10s shot, or three shots (e.g. wide → close on face → reaction)? Each shot is 5-10s. I'll generate a reference image once, then image-to-video each shot off of it.
 
-Default if the user is vague: **3 shots, 5s each, ~$1.50 total on kling**. Confirm before spending.
+Default if the user is vague: **3 shots, 5s each, on kling**. Confirm before spending credits.
 
 ### 3. Lock the look — generate a reference image first
 
@@ -66,19 +66,19 @@ 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. For image-to-video this matters more than usual: the clip's framing is inherited from the reference, so a square reference gives you a square cutscene.
 
-Show the user the still and confirm it's the right look before video-ing it. Regenerating a $0.05 still beats regenerating a $0.50 video.
+Show the user the still and confirm it's the right look before video-ing it. Regenerating a still costs far less than regenerating a video.
 
 ### 4. Pick the model
 
 **This skill always passes `imageUrl`, which puts every call on the image-to-video route — and that route only accepts three models.** `kling-turbo` and `veo3` are text-to-video only; asking for either with an `imageUrl` set is a 400 `invalid_model`, not a silent downgrade.
 
-| Model | i2v? | Cost | Speed | When |
-|---|---|---|---|---|
-| `ltx` | yes | $0.10 | ~30s | Iteration, blocking shots, B-roll, throwaway tests |
-| `kling` | yes | $0.50 | 2-4 min | Hero shots, character cutscenes, anything the player will sit and watch |
-| `minimax` | yes | $0.25 | 2-3 min | Stylized / anime-leaning content; better at non-photoreal looks than kling |
-| `kling-turbo` | **no** | $0.30 | 1-2 min | Text-to-video only — usable only if you drop the reference image |
-| `veo3` | **no** | $1.00 | 3-5 min | Text-to-video only — usable only if you drop the reference image |
+| Model | i2v? | Speed | When |
+|---|---|---|---|
+| `ltx` | yes | ~30s | Iteration, blocking shots, B-roll, throwaway tests |
+| `kling` | yes | 2-4 min | Hero shots, character cutscenes, anything the player will sit and watch |
+| `minimax` | yes | 2-3 min | Stylized / anime-leaning content; better at non-photoreal looks than kling |
+| `kling-turbo` | **no** | 1-2 min | Text-to-video only — usable only if you drop the reference image |
+| `veo3` | **no** | 3-5 min | Text-to-video only — usable only if you drop the reference image |
 
 Default policy: **`ltx` first** to validate the prompt and shot framing. If it lands the composition but quality is rough, escalate to `kling`. `veo3` is a real tradeoff, not an upgrade: reaching for it means giving up `imageUrl`, which is the one thing that holds character identity across shots. Take that trade only when on-camera lip-sync matters more than continuity, and only with the user's approval on cost.
 
@@ -112,13 +112,13 @@ When the job completes, show the user the URL and ask:
 
 ### 6. Generate dialogue audio (if the scene has dialogue)
 
-Cutscene dialogue is TTS, not in the video model. The video model can render mouth motion that *looks* like talking, but the audio comes from `summer_generate_audio`. Generate it separately and the editor (Godot's AnimationPlayer or your `cinematics/` controller scene) syncs them.
+Cutscene dialogue is TTS, not in the video model. The video model can render mouth motion that *looks* like talking, but the audio comes from `summer_generate_audio`. Generate it separately and an AnimationPlayer or your `cinematics/` controller scene syncs them.
 
 ```
 summer_generate_audio(
   capability="text_to_speech",
   text="They'll come for you at dawn. Run while you can.",
-  voiceId="<from audio bible — see audio/voice-line>"
+  voiceId="<from audio bible — see voice-line>"
 )
 ```
 
@@ -134,7 +134,7 @@ VideoStream exts: ["ogv", "tres", "res"]
 ERROR: No loader found for resource: res://clip.mp4 (expected type: unknown)
 ```
 
-Nothing transcodes for you — `summer_import_from_url` downloads the bytes, runs Godot's import pipeline, and *fails the import* if the file never becomes a loadable resource. Convert with ffmpeg or DaVinci before importing:
+Nothing transcodes for you — `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. Convert with ffmpeg or DaVinci before importing:
 
 ```
 ffmpeg -i intro_shot_01.mp4 -c:v libtheora -q:v 8 -an intro_shot_01.ogv
@@ -167,16 +167,16 @@ For dialogue, add an `AudioStreamPlayer` sibling with the TTS clip and call `pla
 
 Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>`. Keep prompts under 50 words; over-prompting confuses the model. Always pair with `imageUrl` to lock the character.
 
-| Goal | Model | Prompt | Cost | Duration |
-|---|---|---|---|---|
-| Opening establishing shot | `kling` | `wide shot of a fog-shrouded medieval village at dawn, slow dolly-in toward the church spire, warm low sun, cinematic, anamorphic lens flare` | $0.50 | 5s |
-| Character intro (hero turns to camera) | `kling` | `young witch with raven on shoulder turns slowly toward camera, candlelit interior, shallow depth of field, cinematic film still` | $0.50 | 5s |
-| Dialogue close-up (no synced lips) | `kling` | `close-up of a grizzled knight, eyes downcast then looking up, firelight on his face, dust motes, 16mm film grain` | $0.50 | 5s |
-| Dialogue close-up (synced lips) | `veo3` — text-to-video only, drop `imageUrl` | `close-up of the witch saying "they will come for you at dawn", candlelight, cinematic, shallow DOF` | $1.00 | 5s |
-| Action beat (village burns) | `kling` | `medium wide of a thatched village engulfed in flames at night, embers rising, silhouettes running through smoke, hand-held camera, cinematic` | $0.50 | 5s |
-| Ending shot (hero walks away) | `kling` | `low wide shot of a cloaked figure walking away across a blasted plain at sunset, slow truck-back, golden hour, dust on the wind` | $0.50 | 5s |
-| Throwaway iteration / blocking | `ltx` | same prompt as above | $0.10 | 5s |
-| Anime / stylized cutscene | `minimax` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | $0.25 | 5s |
+| Goal | Model | Prompt | Duration |
+|---|---|---|---|
+| Opening establishing shot | `kling` | `wide shot of a fog-shrouded medieval village at dawn, slow dolly-in toward the church spire, warm low sun, cinematic, anamorphic lens flare` | 5s |
+| Character intro (hero turns to camera) | `kling` | `young witch with raven on shoulder turns slowly toward camera, candlelit interior, shallow depth of field, cinematic film still` | 5s |
+| Dialogue close-up (no synced lips) | `kling` | `close-up of a grizzled knight, eyes downcast then looking up, firelight on his face, dust motes, 16mm film grain` | 5s |
+| Dialogue close-up (synced lips) | `veo3` — text-to-video only, drop `imageUrl` | `close-up of the witch saying "they will come for you at dawn", candlelight, cinematic, shallow DOF` | 5s |
+| Action beat (village burns) | `kling` | `medium wide of a thatched village engulfed in flames at night, embers rising, silhouettes running through smoke, hand-held camera, cinematic` | 5s |
+| Ending shot (hero walks away) | `kling` | `low wide shot of a cloaked figure walking away across a blasted plain at sunset, slow truck-back, golden hour, dust on the wind` | 5s |
+| Throwaway iteration / blocking | `ltx` | same prompt as above | 5s |
+| Anime / stylized cutscene | `minimax` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | 5s |
 
 ### Bad prompts and why
 
@@ -193,7 +193,7 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 - **Generating a 10s shot when you should chain two 5s shots.** Identity, hand consistency, and physics drift every additional second past ~6s. Two 5s shots cut together look better and cost the same.
 - **Skipping the reference image.** Generating four character cutscenes from text prompts alone produces four different-looking people. Always lock the look with `summer_generate_image` first, then `imageUrl` every subsequent video call.
 - **Asking the video model to render dialogue without `veo3`.** `kling` and `ltx` will animate mouths but the motion does not match any audio. Use `veo3` if dialogue is on-camera, or keep the camera off the speaker.
-- **Using `kling` for blocking iterations.** Burn $0.10 on `ltx` to validate framing and prompt; only spend $0.50 once the composition lands.
+- **Using `kling` for blocking iterations.** Validate framing and prompt on the cheaper `ltx` first; move to `kling` once the composition lands.
 - **Putting the cutscene on a `VideoStreamPlayer` without a fade.** Cuts straight from gameplay to video are jarring. Always wrap in a `ColorRect` fade in/out.
 - **Treating `summer_generate_video` as synchronous.** It returns `{ queued: true, jobId }` and no URL. You must poll `summer_check_job` before there is anything to show or import.
 - **Importing the `.mp4` as-is.** The engine has no MP4 or WebM loader — only Ogg Theora (`.ogv`). Transcode first; an un-transcoded import fails and is rolled back.
@@ -210,7 +210,7 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 
 ## Fallback (no MCP)
 
-If the Studio MCP server isn't running, the user can do all of this through the Studio web dashboard at the Summer Engine cloud console:
+If the MCP server isn't running, the user can do all of this in the Summer dashboard:
 
 1. Generate a reference image in the Image tab.
 2. Open the Video tab, paste the reference URL into the image-to-video field.
@@ -224,17 +224,17 @@ Print the exact prompt + model + duration + aspect ratio so the user can paste i
 Once the cutscene is generated and wired:
 
 > Cutscene `intro` wired at `cinematics/Intro.tscn` with fade in/out and `Video.finished` chained to scene change. Next:
-> - Add the dialogue track with `audio/voice-line` if you haven't yet.
-> - Score the moment with `audio/music-track` — a cutscene without music feels like a placeholder.
+> - Add the dialogue track with `voice-line` if you haven't yet.
+> - Score the moment with `music-track` — a cutscene without music feels like a placeholder.
 > - For the boss reveal cutscene, run this skill again with the same reference image to keep the witch identity stable.
-> - If you want a 5s "money shot" version for marketing, run `video/trailer-shot` against the same reference.
+> - If you want a 5s "money shot" version for marketing, run `trailer-shot` against the same reference.
 
 ## See also
 
-- `video/trailer-shot` — marketing footage, 5-10s, maximum visual punch.
-- `video/animated-loop` — seamless looping background clips.
-- `audio/voice-line` — TTS dialogue used inside cutscenes.
-- `audio/music-track` — score the cutscene.
-- `2d-assets/concept-art` — generate the reference image axis if no character reference exists yet.
-- `2d-assets/character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
+- `trailer-shot` — marketing footage, 5-10s, maximum visual punch.
+- `animated-loop` — seamless looping background clips.
+- `voice-line` — TTS dialogue used inside cutscenes.
+- `music-track` — score the cutscene.
+- `concept-art` — generate the reference image axis if no character reference exists yet.
+- `character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
 - `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/library/skills/combat-basics/SKILL.md

@@ -11,7 +11,7 @@ paths: ["**/*.gd", "**/*.tscn"]
 
 # Combat Basics
 
-The Godot combat pattern is hitbox + hurtbox + health, wired by signals. Build it
+The standard combat pattern is hitbox + hurtbox + health, wired by signals. Build it
 component-first: the same three pieces work for player, enemies, and destructibles.
 
 ## The layer model (set this up first)

package/library/skills/compatibility-renderer-traps/SKILL.md

@@ -13,8 +13,8 @@ paths: ["**/*.gdshader", "**/*.gdshaderinc", "**/*.gd", "project.godot"]
 
 Games built on Forward+ can end up on the Compatibility renderer (OpenGL): phones where Metal/Vulkan is
 unavailable, weak GPUs, or a project that picks it for battery. The failures are silent: no error, just
-black fruit, pale colors, or objects that stop animating after the first few hundred. These are the traps
-that cost real renders in a shipped-quality game, each with the fix and the reason.
+black fruit, pale colors, or objects that stop animating after the first few hundred. Each trap below
+comes with its fix and the reason.
 
 ## 1. Know which renderer you actually got
 

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

@@ -75,9 +75,9 @@ summer_generate_image(
 )
 ```
 
-`style: "none"` is intentional, but be precise about why: only `cartoon` and `anime` append anything to the prompt, `realistic` and `none` append nothing, and any other value is coerced to `none`. So the preset cannot override the prompt's stylistic direction — it just contributes nothing, which is what concept art wants. All four variants' divergence has to come from the prompt.
+`style: "none"` is intentional: only `cartoon` and `anime` append anything to the prompt, `realistic` and `none` append nothing, and any other value is coerced to `none`. So the preset cannot override the prompt's stylistic direction — it just contributes nothing, which is what concept art wants. All four variants' divergence has to come from the prompt.
 
-For a shape other than square, pass `aspectRatio` (`"16:9"`, `"9:16"`, ...) or `width` + `height`; the result reports the real width and height and the model that ran. Exploration images are thrown away, so square is usually fine.
+For a shape other than square, pass `aspectRatio` (`"16:9"`, `"9:16"`, ...) or `width` + `height`; the result reports the real width and height and the model that ran. Exploration images are thrown away, so square is usually fine. Background removal is the top-level `removeBackground` argument, not an `options` key.
 
 ### 5. Present the batch
 
@@ -114,7 +114,7 @@ The structure: **subject + axis variant + "concept art" + lighting/atmosphere**.
 - **Generating 4 near-identical variants** because you didn't pick a real axis. The user can't choose between four images that all look like the same painting.
 - **Importing concept art as final assets.** These are exploration. The polished version comes from `character-portrait` after a direction is picked.
 - **Treating `style` as the variant axis.** The presets are `realistic | cartoon | anime | none`, and only two of them append anything. Four "stylization" variants have to differ in their prompt text, not in the `style` argument.
-- **Skipping the disambiguation question.** If you don't ask, you'll get yelled at when you generate 4 portraits and the user wanted one polished bust.
+- **Skipping the disambiguation question.** If you don't ask, you may generate four rough variants when the user wanted one polished bust.
 - **Generating before the GameSoul.md is written.** If `.summer/GameSoul.md` exists, read it first — its visual-style section narrows the axis.
 
 ## Edge cases

package/library/skills/create-asset-sheet/SKILL.md

@@ -11,15 +11,15 @@ paths: ["assets/**", "art/**", "sprites/**"]
 
 # create-asset-sheet — Generate a coherent pack of 2D assets
 
-This skill turns a single prompt into a categorized pack of isolated, named 2D assets ready to drop into a game. It exists because the alternative — generating each asset one-by-one, then losing visual coherence between them, then manually matting backgrounds in Photoshop — is the most-cited pain point from indie devs working with image models in 2026.
+This skill turns a single prompt into a categorized pack of isolated, named 2D assets ready to drop into a game. Generating assets one by one loses visual coherence between them and leaves you matting backgrounds by hand; one sheet keeps the pack consistent.
 
 **Pipeline:**
 
 1. **Generate a sheet** of N isolated assets in one image-gen call.
-2. **Remove background** (fal/bria) so each asset can stand on its own.
-3. **Detect + name + classify** each asset in one vision call (Gemini 3 Pro outputs bbox + snake_case name + category per region).
-4. **Crop** each region with sharp.
-5. **Optionally upscale** any small slice via fal flux-2/edit i2i, preserving aspect.
+2. **Remove the background** so each asset can stand on its own.
+3. **Detect, name and classify** each asset in one vision pass (bounding box + snake_case name + category per region).
+4. **Crop** each region.
+5. **Optionally upscale** any small slice, preserving aspect.
 6. **Save** as a single pack ArtAsset with `packFiles: [{url, name, type}]` and `metadata.sliceBboxes`.
 
 Categories the classifier outputs (used to route into downstream pipelines):
@@ -42,13 +42,7 @@ Categories the classifier outputs (used to route into downstream pipelines):
 
 ## The cleanest path: the studio wizard
 
-The fastest, most reliable way to invoke this flow today is the **Create Asset Sheet** wizard in the Summer studio:
-
-```
-https://summerengine.com/studio/create-tileset
-```
-
-Direct the user there if they're working in the browser. The wizard:
+The most reliable way to run this flow is the **Create Asset Sheet** wizard in Summer Studio's guided workflows. Open it for the user with `summer open workflows` (or `summer_open`) if they're working in the browser. The wizard:
 
 - Offers a 2D / 3D mode toggle (2D is the slice flow described here; 3D is a soft pointer to `concept-art` + per-asset image-to-3D for now)
 - Surfaces six prompt templates (tile sheet, UI kit, menu, character pack, biome, freeform)
@@ -59,7 +53,7 @@ Direct the user there if they're working in the browser. The wizard:
 - Saves as a pack ArtAsset visible in the user's library
 
 If the user is in a chat / agent context, use the programmatic path below. It
-now calls the same server-side slicer as the Studio wizard.
+calls the same server-side slicer as the Studio wizard.
 
 ## Programmatic path (chat / agent driving the engine)
 
@@ -88,14 +82,13 @@ now calls the same server-side slicer as the Studio wizard.
    returned slice ids/names/categories; do not reimplement the vision boxes
    locally.
 
-4. **Optional upscale.** For any crop where longest side < 256px, send through fal flux-2/edit i2i with prompt:
+4. **Optional upscale.** The Studio wizard has per-slice HD upscale. Over MCP, for any crop where the longest side is under 256px, call `summer_generate_image` with the slice as `referenceImageUrl` and this prompt:
 
    ```
    Recreate this exact <name> at high resolution. Preserve every detail, the exact pose, the exact style. Sharper edges, more detail. Transparent background. Single isolated asset, no scene.
    ```
 
-   - Scale longest side to 1024, preserve aspect ratio (FLUX requires multiples of 32).
-   - Don't blindly upscale everything — high-res slices get diminishing returns and you spend $0.04/slice.
+   - Don't upscale everything: each upscale is a paid generation, and large slices gain little.
 
 5. **Import what the game needs.** Use the returned asset ids with
    `summer_import_asset_by_id`. Keep the source pack in My Assets so the agent
@@ -140,26 +133,14 @@ now calls the same server-side slicer as the Studio wizard.
 | Slicer returns 1 giant bbox covering the whole sheet | Items overlap / no gaps in the source | Re-prompt with "each item fully isolated, empty space around each item". Re-generate. |
 | Slicer misses items | Items too small in the source, classifier dropped them as noise | Generate at higher resolution (2048) or with fewer items per sheet |
 | Two items merge into one slice | Items touching in the source | Re-prompt with more isolation. Or accept and let the user split manually in step 2's review. |
-| Slice has a sliver of neighbor in it | Vision bbox is off by 5–15px | Expected. The slicer pads but doesn't snap-to-content yet. Live with it or upscale the slice (FLUX often cleans the edge) |
+| Slice has a sliver of neighbor in it | Vision bbox is off by 5–15px | Expected. The slicer pads but doesn't snap-to-content yet. Live with it or upscale the slice (upscaling often cleans the edge) |
 | Upscaled slice looks invented | Source was too small / too ambiguous | Don't upscale slices below ~32×32. Or accept the hallucination and edit |
 | Detection returns wrong category | Model misjudged context | User can override in the review step; not a blocker |
 
 ## What this skill does NOT do (yet)
 
-- Per-asset planning + individual generation (the Codex-style flow where each asset is generated separately at full resolution). The planner endpoint exists (`POST /api/art/plan-asset-pack`) but the per-asset gen loop is not wired into the wizard yet.
+- Per-asset planning and individual generation, where each asset is generated separately at full resolution.
 - 3D pack assembly. The 3D mode in the wizard is a placeholder pointer to `concept-art` + image-to-3D for now.
-- Character animation routing. Once a slice is classified as `character`, the next step (sprite-sheet generation) is a separate skill that the user has to invoke manually. Auto-routing is on the roadmap.
+- Character animation routing. Once a slice is classified as `character`, the next step (sprite-sheet generation) is a separate skill that the user has to invoke manually.
 - Terrain auto-tiling / Wang-tile generation. Use `tileable-texture` for that.
 - Level composition / scene assembly. Use `design-level`.
-
-## Honest cost estimate
-
-Per 12-asset sheet, end to end through the wizard:
-
-- Generate sheet: $0.04–0.10 (varies by model)
-- Background removal: $0.05
-- Vision detect + classify: $0.02–0.03
-- Save pack: free
-- Optional bulk upscale: ~$0.04 per slice ($0.48 for 12)
-
-**Without upscale:** ~$0.12. **With full upscale:** ~$0.60. About a third of what a Photoshop hour would cost.

package/library/skills/debug/SKILL.md

@@ -28,7 +28,7 @@ victory. Never grep the codebase before reading the actual error.
 
 - The user is asking how to *prevent* a class of bug — that's a design question. Use the relevant discipline skill (`gdscript-patterns`, `scene-composition`).
 - The user is asking for a feature with a known unfinished spec — that's `make-game` territory.
-- The bug is in a non-Godot file the host agent can debug natively (CI config, npm scripts) — use the host's debugger.
+- The bug is in a file outside the game project that the host agent can debug natively (CI config, npm scripts) — use the host's debugger.
 
 ## The Loop
 
@@ -143,7 +143,7 @@ Surface the proposed fix in plain language and ask permission. Two patterns:
 
 - For GDScript edits: `Read` the 20–40 lines around the error, `Edit` the exact change. Don't read the whole file. Don't reformat. Don't rename other things.
 - For scene edits: use the appropriate `summer_*` tool (`summer_add_node`, `summer_set_prop`, `summer_replace_node`). Group multi-step changes in `summer_batch` for one undo step.
-- **Nested resource properties:** `summer_set_resource_property` works against inline `sub_resource` targets too — pass `nodePath`, `resourceProperty`, and `subProperty` (there is no dotted `"mesh.size"` form). Structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors; a bad value shape is not — a JSON object instead of a Godot literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the fix in the saved `.tscn` or a snapshot diff, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
+- **Nested resource properties:** `summer_set_resource_property` works against inline `sub_resource` targets too — pass `nodePath`, `resourceProperty`, and `subProperty` (there is no dotted `"mesh.size"` form). Structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors; a bad value shape is not — a JSON object instead of an engine literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the fix in the saved `.tscn` or a snapshot diff, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
 
 ### 6. Verify — re-run the diagnostic that found it
 
@@ -160,7 +160,7 @@ If the diagnostic is still red after the fix, you formed the wrong hypothesis. G
 | Don't | Why |
 |---|---|
 | Grep the whole project before reading the error | The error already names the file and line. Save the user's tokens. |
-| Read whole files | 20–40 lines around the error is enough 90% of the time. |
+| Read whole files | 20–40 lines around the error is usually enough. |
 | Run multiple diagnostics in parallel | They mask each other's signal. Cheapest first, escalate. |
 | Edit before asking | The user owns the fix decision, you own the diagnosis. |
 | "Try this, see if it works" | That's not a hypothesis, that's gambling. State the theory or ask another question. |
@@ -177,7 +177,7 @@ If the diagnostic is still red after the fix, you formed the wrong hypothesis. G
 | "Cannot find type 'X'" | `summer_get_script_errors` | Class name mismatch, missing autoload, missing `class_name` |
 | Game runs but visuals wrong | `summer_get_console` + `summer_inspect_node` | Material/light/camera misconfigured |
 | Game freezes (no crash) | `summer_get_console` after `summer_play` for ~3s | Infinite loop in `_process` or `_ready` |
-| `summer_set_resource_property` "succeeded" but nothing changed | n/a | Inline sub-resource silent-fail. Use `summer_set_prop` with class name first. |
+| `summer_set_resource_property` "succeeded" but nothing changed | n/a | Bad value shape (JSON object, misspelled `subProperty`, wrong type). Pass engine literal strings and confirm in the saved `.tscn`. |
 
 ## Closing
 
@@ -200,6 +200,7 @@ The static and boot-time tools (`summer_get_script_errors`, `summer_get_console`
 - **Runtime debugger warning text** (`summer_get_debugger_warnings`) — same structured shape as the errors tool, filtered to severity `warning`. Use it whenever `summer_get_diagnostics` shows a non-zero `debugger.warnings`; do not report a warning count you never read.
 - **Diagnostics summary** (`summer_get_diagnostics`) — counts of console errors, debugger errors, debugger warnings, script errors. Tells you where to drill. **Counts only** — it carries no FPS, frame time, draw calls, or physics-body numbers.
 - **Scene tree + node properties** (`summer_get_scene_tree`, `summer_inspect_node`) — only the **edited** scene, not the running game's live tree.
+- **Live runtime state** (`summer_get_runtime_tree`, `summer_inspect_runtime_node`, `summer_game_probe`) — the running game's tree, properties and frames, on engine builds with the runtime-control ops. See `agent-playtesting`.
 - **Rendered pixels** (`summer_screenshot`) — `target:"viewport"` for the editor's current view, `target:"scene"` for an offscreen render of a scene file, `target:"game"` for a frame of the running game (that one needs the Summer desktop app bridge and fails cleanly over a plain local connection). You look at the actual image, not a description of it.
 - **Gameplay behaviour, driven by you** (`RunVerification` via `summer_batch`) — see the next section. Input, live tree, and frames from a real running instance.
 - **Whether the game is running** (`summer_is_running`) — and on which scene.

package/library/skills/debugging-game-feel/SKILL.md

@@ -184,11 +184,8 @@ After diagnosis pins down which variable(s) are wrong, the tuning is done — bu
 - `game-feel` — for the screen-shake, hit-stop, particle, sound layer once tuning is locked.
 - `debug` — if mid-debug you discover an actual error (signal not firing, node freed) hiding under the feel issue.
 
-## The Bottom Line
+## Related skills
 
-Feel bugs are tuning bugs. Tuning is a one-variable-at-a-time discipline. Anchor to a reference. Tweak one number. Play it. Decide. Repeat.
-
-**Related skills:**
 - `investigating-bugs` — for logical bugs with concrete repros, not feel.
 - `playtesting-a-feature` — the playtest discipline this skill plugs into.
 - `debug` — when the feel investigation surfaces an actual error.

package/library/skills/debugging-game-feel/resource.yaml

@@ -6,7 +6,7 @@ use_when:
   - a gameplay feature works correctly but feels wrong — floaty jumps, mushy combat, sluggish camera, weightless impacts
   - tuning jump height, gravity, camera lag, hit-stop, or impact feedback until controls feel right
 do_not_use_when:
-  - the bug is a logic error rather than subjective feel — use logical bug debugging
+  - the bug is a logic error rather than subjective feel — use investigating-bugs
 facets:
   lifecycle:
     - build

package/library/skills/design-level/SKILL.md

@@ -273,8 +273,8 @@ The skeleton this skill produces is meant to be filled in via `/design-mechanic`
 
 ## See also
 
-- `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md`
-- `gameplay-mechanics/design-mechanic/SKILL.md` — designs the verbs the level exercises
-- `ai-and-npcs/design-npc/SKILL.md` — designs the enemies the encounters reference
-- `rendering-and-lighting/3d-lighting/SKILL.md` — sets the lighting in `WorldEnvironment` + lights
-- `rendering-and-lighting/art-direction/SKILL.md` — defines the visual style the level expresses
+- `brainstorm-game` — produces `.summer/GameSoul.md`
+- `design-mechanic` — designs the verbs the level exercises
+- `design-npc` — designs the enemies the encounters reference
+- `3d-lighting` — sets the lighting in `WorldEnvironment` + lights
+- `art-direction` — defines the visual style the level expresses

package/library/skills/design-mechanic/SKILL.md

@@ -142,7 +142,7 @@ Argument notes, all of which the tool schema enforces:
   "current scene" default.
 - `summer_set_prop` takes named `path` / `key` / `value` — not positional.
 - `summer_input_map_bind` events are dicts. `{"type": "key", "key": "Space"}`
-  works; key names go through Godot's keycode table, so `W`, `Space`, `Shift`,
+  works; key names go through the engine's keycode table, so `W`, `Space`, `Shift`,
   `Escape` resolve and typos silently produce no event.
 - `summer_get_script_errors` checks one file and requires `path`. Use
   `summer_get_diagnostics()` (no args) for a project-wide check.
@@ -266,8 +266,8 @@ This skill is a workflow that designs and scaffolds — the templates are runnab
 
 ## See also
 
-- `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md` this skill reads
-- `level-design/design-level/SKILL.md` — design the levels that exercise the mechanic
-- `character-controllers/fps-controller/SKILL.md` — FPS movement scaffolding
-- `scripting-patterns/state-machine-patterns/SKILL.md` — state machines for complex mechanics
-- `audio/audio-direction/SKILL.md` — defines the SFX vocabulary the mechanic draws from
+- `brainstorm-game` — produces `.summer/GameSoul.md` this skill reads
+- `design-level` — design the levels that exercise the mechanic
+- `fps-controller` — FPS movement scaffolding
+- `gdscript-patterns` — state machines and other script patterns for complex mechanics
+- `audio-direction` — defines the SFX vocabulary the mechanic draws from

package/library/skills/design-npc/SKILL.md

@@ -211,7 +211,7 @@ resources exactly as it does against external `.tres` files — it reads the
 property off the node and writes the sub-property onto whatever Resource is
 there. Structural failures are explicit errors (`node not found`, `property is
 not a resource`, `resource is null`); a bad value shape is not — a JSON object
-instead of a Godot literal string, a misspelled `subProperty`, or a wrong-typed
+instead of an engine literal string, a misspelled `subProperty`, or a wrong-typed
 value returns `ok:true` yet silently no-ops or coerces destructively on current
 engines. Pass class names and literal strings (`"12.0"`, `"Color(r, g, b, a)"`)
 and confirm the result in the saved `.tscn`, never from `ok` alone. The order
@@ -490,20 +490,13 @@ This skill writes scenes and scripts. Always ask before each step. Group related
 
 ## Want a working starter?
 
-For a fully-rigged enemy with anim controller + loot drop:
-
-→ **template-id**: `template-3d-fps` — ships with a sample patrol enemy
-→ For higher-complexity AI (boss with phases, behavior trees), defer to `ai-and-npcs/behavior-trees/SKILL.md`.
+For an animated NPC in a runnable project: `summer create 3d-fps-simple-animated-npc`. Run `summer list templates` for the current list.
 
 ## See also
 
-- `ai-and-npcs/state-machine-npc/SKILL.md` — FSM pattern deep dive
-- `ai-and-npcs/behavior-trees/SKILL.md` — when complexity demands a BT
-- `ai-and-npcs/perception-sight-and-hearing/SKILL.md` — sensor patterns
-- `ai-and-npcs/navmesh-pathfinding/SKILL.md` — NavigationAgent3D for movement
-- `ai-and-npcs/llm-driven-dialogue/SKILL.md` — Summer's wedge for talking NPCs
-- `ai-and-npcs/boss-patterns/SKILL.md` — phase transitions, mechanics
-- `visual-effects/recipes/hit-spark/SKILL.md` — hit flash recipe
-- `visual-effects/recipes/dissolve/SKILL.md` — death dissolve recipe
-- `visual-effects/game-feel/SKILL.md` — screen-feel discipline (camera shake, hit-stop)
-- `scripting-patterns/state-machine-patterns/SKILL.md` — generic FSM patterns
+- `animation-tree` — wire the action states to animation clips
+- `ai-characters-in-games` — NPCs that answer free-form player text
+- `vfx-hit-spark` — hit flash recipe
+- `vfx-dissolve` — death dissolve recipe
+- `game-feel` — screen-feel discipline (camera shake, hit-stop)
+- `gdscript-patterns` — generic state machine and script patterns

package/library/skills/diagnosing-perf-regressions/SKILL.md

@@ -117,7 +117,7 @@ If a single commit is the obvious suspect (e.g. "Added 200 enemies to spawner"),
 
 ### 4. Match to one of the four Summer Engine performance cliffs
 
-Godot 4.x regressions cluster heavily into four categories. Knowing them shortens diagnosis to minutes.
+Regressions cluster into four categories. Matching the symptom to one shortens diagnosis.
 
 | Cliff | Symptom | How to verify | Common cause |
 |---|---|---|---|
@@ -156,7 +156,7 @@ State the result with the number: "Reverted the per-frame `get_tree().get_nodes_
 |---|---|
 | Regression confirmed and root cause known, but the fix is "make the feature cheaper" rather than "undo the change" | `tune-performance` for the optimization pass |
 | The regression turns out to be a crash or error in disguise (the slow path is throwing exceptions in a tight loop) | `debug` |
-| The cause is a Godot version change or engine-side regression | Surface to the user; this is not a project-side fix |
+| The cause is an engine version change or engine-side regression | Surface to the user; this is not a project-side fix |
 | Bisect lands on a commit that touches 40 files | Subdivide the commit: check out the commit, revert subsets, re-measure |
 
 ## Red Flags — STOP
@@ -179,9 +179,9 @@ State the result with the number: "Reverted the per-frame `get_tree().get_nodes_
 | Excuse | Reality |
 |---|---|
 | "User wants it fixed now, no time to bisect" | Bisect is 5-15 minutes. Blind optimization can burn a day. |
-| "The slow commit is obvious, no need to A/B" | The "obvious" cause is wrong ~30% of the time. Verify before fixing. |
+| "The slow commit is obvious, no need to A/B" | The "obvious" cause is often wrong. Verify before fixing. |
 | "I'll measure after I fix it" | If you don't have the bad number, you can't prove the fix worked. |
-| "It's probably just Godot" | Engine-side regressions exist but are rare. Suspect your project first. |
+| "It's probably the engine" | Engine-side regressions exist but are rare. Suspect your project first. |
 | "Adding a pool / LOD / cache will help anyway" | Premature optimization on the wrong system is wasted work. |
 
 ## When The Engine Isn't Running
@@ -202,13 +202,8 @@ If the MCP tools report the engine isn't running:
 3. Only if neither is possible: ask the user for an in-game perf overlay reading (FPS, frame time, draw call count) and walk the bisect with them — "run on commit X, tell me the FPS; run on commit Y, tell me the FPS."
 4. Do not claim a fix is verified from code reading alone.
 
-## The Bottom Line
+## Related skills
 
-A regression is a delta. Diagnose the delta, not the codebase.
-
-Measure now. Measure last-good. Bisect what changed. Match to a Godot perf cliff. A/B one variable. Re-measure. Done.
-
-**Related skills:**
 - `tune-performance` — for general optimization once the regression is fixed or when no regression exists.
 - `investigating-bugs` — when the slow path turns out to be a logic bug (errors in a tight loop).
 - `debug` — when the perf issue is actually a crash or freeze.

package/library/skills/dispatching-parallel-agents/SKILL.md

@@ -130,7 +130,7 @@ Return: Summary of what you found and what you fixed.
 **Exploratory debugging:** You don't know what's broken yet
 **Shared state:** Agents would interfere (editing same files, using same resources)
 
-## Real Example from Session
+## Example
 
 **Scenario:** 6 test failures across 3 files after major refactoring
 
@@ -155,15 +155,6 @@ Agent 3 → Fix tool-approval-race-conditions.test.ts
 
 **Integration:** All fixes independent, no conflicts, full suite green
 
-**Time saved:** 3 problems solved in parallel vs sequentially
-
-## Key Benefits
-
-1. **Parallelization** - Multiple investigations happen simultaneously
-2. **Focus** - Each agent has narrow scope, less context to track
-3. **Independence** - Agents don't interfere with each other
-4. **Speed** - 3 problems solved in time of 1
-
 ## Verification
 
 After agents return:
@@ -171,12 +162,3 @@ After agents return:
 2. **Check for conflicts** - Did agents edit same code?
 3. **Run full suite** - Verify all fixes work together
 4. **Spot check** - Agents can make systematic errors
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-- 6 failures across 3 files
-- 3 agents dispatched in parallel
-- All investigations completed concurrently
-- All fixes integrated successfully
-- Zero conflicts between agent changes

package/library/skills/environment-kit/SKILL.md

@@ -13,7 +13,7 @@ paths: ["assets/kits/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 
 A kit is a *family* of meshes — wall, floor, door, pillar, corner, arch — that the level designer snaps together to build interiors and exteriors. The skill exists to solve **one specific failure mode**: generating each piece with a fresh prompt produces six pieces that look like they came from six different games. The fix is the **style anchor pattern** — generate one piece first, lock its prompt suffix, and reuse that exact suffix for every subsequent piece.
 
-The backing tool is `summer_generate_3d`, called multiple times. Each call costs ~$0.50, so a 6-piece kit is ~$3 and ~5 minutes. Confirm scope before starting.
+The backing tool is `summer_generate_3d`, called once per piece. A 6-piece kit is six generations and about 5 minutes. Generation uses credits, so confirm scope before starting.
 
 ## When to use
 
@@ -32,7 +32,7 @@ The backing tool is `summer_generate_3d`, called multiple times. Each call costs
 
 ## The style anchor pattern
 
-This is the whole skill. Get this right and the kit looks unified. Get this wrong and you waste $3.
+This is the whole skill. Get it right and the kit looks unified. Get it wrong and every piece is wasted.
 
 1. **Generate the anchor piece first.** Pick the most visually defining piece — usually the wall or the door. Iterate the prompt until the user approves it visually.
 2. **Extract the style suffix.** Everything after the object description. Example anchor prompt:
@@ -69,7 +69,7 @@ Kit pieces only feel modular if they snap to a fixed grid. Pick the grid before
 
 ### 1. Confirm scope and pick the grid
 
-> About to build a dungeon kit. Suggested pieces: wall, floor, pillar, door, corner, arch (6 pieces, ~$3, ~5 min). Snap grid: 2m (standard interior). OK?
+> About to build a dungeon kit. Suggested pieces: wall, floor, pillar, door, corner, arch (6 generations, ~5 min). Snap grid: 2m (standard interior). OK?
 
 ### 2. Generate the anchor (wall)
 
@@ -131,13 +131,13 @@ Three things the shape of those calls encodes:
 summer_inspect_resource(path="res://assets/kits/dungeon/wall.glb")
 ```
 
-Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the editor (or re-import with `Scale` in the import dock). Pivots should sit at the *bottom-back* corner for walls and *bottom-center* for floors — that makes snapping to a 2m grid trivial. If pivots are wrong, use Godot's "Center to Origin" import option.
+Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the editor (or re-import with `Scale` in the import dock). Pivots should sit at the *bottom-back* corner for walls and *bottom-center* for floors — that makes snapping to a 2m grid trivial. If pivots are wrong, use the "Center to Origin" import option.
 
 ## Anti-patterns
 
 - **Drifting style suffix.** Each piece gets a slightly different suffix → the kit looks mismatched. Copy-paste the exact string.
 - **Different polycount per piece.** A 5k-tri pillar next to a 500-tri wall reads as "the pillar is a hero piece" — wrong; they should feel like equal kit citizens. Match polycount within ~2× across the kit.
-- **Skipping the anchor approval.** If you generate all six pieces in a batch, you bake in whatever the first call's interpretation of the style was — and the user may hate it after $3 of generation.
+- **Skipping the anchor approval.** If you generate all six pieces in a batch, you bake in whatever the first call's interpretation of the style was — and the user may hate it after six generations.
 - **Generating walls / floors as individual meshes when you only need a tileable texture.** A flat wall section is cheaper as a textured `CSGBox3D`. Reserve the kit for pieces that need actual geometric detail (sconces, mouldings, doorways, arches).
 - **No scale cue in the prompt.** Wall comes back 0.4m tall. Always include `2 meter wide by 3 meter tall` (or your chosen grid).
 - **Forgetting the snap grid.** A 1.87m-tall wall with no scale fix → level looks crooked when tiled.