summer-engine 2.6.6 → 2.8.0

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

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_video summer_generate_image summer_generate_audio summer_search_assets summer_import_from_url summer_add_node summer_set_prop
+allowed-tools: Read Grep Glob Write Edit summer_generate_video summer_check_job summer_generate_image summer_generate_audio summer_search_assets summer_import_from_url summer_add_node summer_set_prop
 paths: ["assets/video/**", "cinematics/**", "trailers/**"]
 ---
 
@@ -38,10 +38,11 @@ If the user wants 5 seconds of marketing footage, that's `video/trailer-shot`. I
 
 ```
 Read .summer/GameSoul.md
-summer_search_assets(query="cutscene", filter={ kind: "video" })
-summer_search_assets(query="<character name> reference", filter={ kind: "image" })
+summer_search_assets(query="<character name> reference", assetType="2d_image", source="all")
 ```
 
+`summer_search_assets` has no video filter — `assetType` is one of `2d_image`, `animation`, `3d_model`, `audio`, `music`, `all`, and there is no video member. To find prior cutscene clips, list your own assets with `summer_list_my_assets(query="cutscene")` and read the titles.
+
 If a reference image of the character already exists from a prior `concept-art` or `character-portrait` run, **reuse it** as the `imageUrl` — that single decision is the difference between the character looking like themselves and looking like a stranger.
 
 ### 2. Plan the shot list
@@ -58,25 +59,28 @@ For any character or hero scene, generate a reference still with `summer_generat
 
 ```
 summer_generate_image(
-  prompt="<subject>, <setting>, cinematic lighting, film still, <art style from GameSoul.md>",
-  model="nano-banana-2",
-  options={ image_size: "landscape_16_9" }
+  prompt="<subject>, <setting>, cinematic lighting, film still, wide 16:9 framing, <art style from GameSoul.md>",
+  model="nano-banana-2"
 )
 ```
 
+`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.
 
 ### 4. Pick the model
 
-| Model | Cost | Speed | When |
-|---|---|---|---|
-| `ltx` | ~$0.10 | ~30s | Iteration, blocking shots, B-roll, throwaway tests |
-| `kling` | ~$0.50 | 2-4 min | Hero shots, character cutscenes, anything the player will sit and watch |
-| `kling-turbo` | ~$0.30 | 1-2 min | Same as kling when iteration speed matters more than the last 10% of quality |
-| `veo3` | ~$1.00 | 3-5 min | Pitch decks, premium dialogue scenes with synced lip motion, short-form ad |
-| `minimax` | ~$0.40 | 2-3 min | Stylized / anime-leaning content; better at non-photoreal looks than kling |
+**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.
 
-Default policy: **`ltx` first** to validate the prompt and shot framing. If it lands the composition but quality is rough, escalate to `kling`. Only reach for `veo3` if dialogue lip-sync matters and the user has approved the cost.
+| 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 |
+
+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.
 
 ### 5. Generate each shot
 
@@ -90,7 +94,19 @@ summer_generate_video(
 )
 ```
 
-Returns `{ asset: { fileUrl } }`. Show the user the URL and ask:
+`duration` accepts **only 5 or 10** — the server coerces anything else to 5. There is no 3s, 4s, 7s or 8s clip.
+
+Video generation is **asynchronous**. The call returns immediately with `{ success, queued: true, jobId, model, resolvedModel, estimatedCost, duration }` and **no `fileUrl`** — the clip is rendered by a background worker. Poll for it:
+
+```
+summer_check_job(jobId="<jobId from the generate call>")
+```
+
+Only once the job reports `completed` do you have an asset and a URL. Do not tell the user a shot is done off the back of the generate call — at that moment nothing has rendered yet.
+
+`aspectRatio` is applied on the text-to-video path only; on image-to-video the framing comes from the reference image, so a `9:16` cutscene needs a `9:16` reference, not a `9:16` argument.
+
+When the job completes, show the user the URL and ask:
 
 > Shot 1 of 3 done. Land or regenerate? If land, I'll move to shot 2.
 
@@ -110,20 +126,37 @@ Lip-sync caveat: if the video shows the character clearly mouthing words and the
 
 ### 7. Import and wire as a VideoStreamPlayer
 
+**Transcode to Ogg Theora first.** The generated clip is an `.mp4`, and Summer Engine cannot load `.mp4` — the only video container in the build is `.ogv`. Measured against the shipped binary (4.6.1):
+
+```
+$ Summer --headless --path <proj> -s res://probe.gd
+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:
+
+```
+ffmpeg -i intro_shot_01.mp4 -c:v libtheora -q:v 8 -an intro_shot_01.ogv
+```
+
+Then:
+
 ```
-summer_import_from_url(url="<fileUrl>", path="assets/video/cinematics/intro_shot_01.mp4")
+summer_import_from_url(url="<hosted .ogv url>", path="res://assets/video/cinematics/intro_shot_01.ogv")
 ```
 
-Build a controller scene at `cinematics/Intro.tscn`:
+Build a controller scene at `res://cinematics/Intro.tscn`. Every scene-mutating tool takes an explicit `scenePath`, and `summer_set_prop`'s property argument is named `key`, not `property`:
 
 ```
-summer_add_node(parent=".", type="Control", name="Intro")
-summer_add_node(parent="./Intro", type="ColorRect", name="Fade")   # black, alpha 1.0 → 0.0
-summer_add_node(parent="./Intro", type="VideoStreamPlayer", name="Video")
-summer_set_prop(path="./Intro/Video", property="stream", value="res://assets/video/cinematics/intro_shot_01.mp4")
-summer_set_prop(path="./Intro/Video", property="autoplay", value=true)
-summer_set_prop(path="./Intro/Video", property="expand", value=true)
-summer_set_prop(path="./Intro/Fade", property="anchors_preset", value=15)
+summer_create_scene(path="res://cinematics/Intro.tscn", rootName="Intro", allow_temporary_scene_mutation=true)
+summer_add_node(scenePath="res://cinematics/Intro.tscn", parent=".", type="ColorRect", name="Fade")   # black, alpha 1.0 → 0.0
+summer_add_node(scenePath="res://cinematics/Intro.tscn", parent=".", type="VideoStreamPlayer", name="Video")
+summer_set_prop(scenePath="res://cinematics/Intro.tscn", path="./Video", key="stream", value="res://assets/video/cinematics/intro_shot_01.ogv")
+summer_set_prop(scenePath="res://cinematics/Intro.tscn", path="./Video", key="autoplay", value=true)
+summer_set_prop(scenePath="res://cinematics/Intro.tscn", path="./Video", key="expand", value=true)
+summer_set_prop(scenePath="res://cinematics/Intro.tscn", path="./Fade", key="anchors_preset", value=15)
+summer_save_scene(scenePath="res://cinematics/Intro.tscn")
 ```
 
 Attach a `Tween` script that fades the `ColorRect` from black to clear over 0.5s on `_ready`, then back to black when `Video.finished` fires, then `queue_free()`s the scene. For multi-shot cutscenes, queue the next `VideoStreamPlayer` in the `finished` signal handler.
@@ -139,11 +172,11 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 | 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` | `close-up of the witch saying "they will come for you at dawn", candlelight, cinematic, shallow DOF` | $1.00 | 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.40 | 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 |
 
 ### Bad prompts and why
 
@@ -162,11 +195,14 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 - **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.
 - **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.
-- **Forgetting to import the file.** `summer_generate_video` returns a `fileUrl` on Cloudinary; until you call `summer_import_from_url`, it isn't in `res://` and the scene can't reference it.
+- **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.
+- **Asking for `duration=3` or `duration=8`.** Only 5 and 10 exist; anything else is silently coerced to 5.
+- **Pairing `imageUrl` with `kling-turbo` or `veo3`.** Neither has an image-to-video endpoint — that combination is a 400.
 
 ## Edge cases
 
-- **Vertical cutscene for a mobile target.** Set `aspectRatio="9:16"`. Reference image must also be 9:16 — generate it with `image_size: "portrait_16_9"` or the framing will crop wrong on the video.
+- **Vertical cutscene for a mobile target.** On the image-to-video path `aspectRatio` is not applied at all — the clip inherits the reference image's framing. So the reference *must* be 9:16, and MCP image generation cannot produce that: make it in the Summer dashboard, or crop a square generation to 9:16, then pass its URL as `imageUrl`.
 - **Cutscene must match an in-engine character precisely.** No video model will hit pixel-perfect identity. Either (a) accept the artistic license, (b) render the cutscene in-engine with `AnimationPlayer` instead of generating it, or (c) generate a reference image *from* a screenshot of the in-engine character (image-to-image first, then image-to-video).
 - **Dialogue is too long for a 5s shot.** Either trim the line, or split: 5s of speaker, 5s of listener reaction (cheaper because the listener doesn't need synced lips).
 - **Cutscene needs to play and the player isn't looking.** Pause the gameplay timer, push a `Control` overlay with the `VideoStreamPlayer`, restore on finish.
@@ -179,7 +215,7 @@ If the Studio MCP server isn't running, the user can do all of this through the
 1. Generate a reference image in the Image tab.
 2. Open the Video tab, paste the reference URL into the image-to-video field.
 3. Set model, duration, aspect ratio, and prompt as listed above.
-4. Download the `.mp4` and drop it into `assets/video/cinematics/` in the project, then re-import via the Godot editor.
+4. Download the `.mp4`, transcode it to Ogg Theora (`ffmpeg -i in.mp4 -c:v libtheora -q:v 8 -an out.ogv`), and drop the `.ogv` into `assets/video/cinematics/`. Summer Engine has no MP4 or WebM loader — `.ogv` is the only video container it can open.
 
 Print the exact prompt + model + duration + aspect ratio so the user can paste it into the dashboard verbatim.
 
@@ -201,4 +237,4 @@ Once the cutscene is generated and wired:
 - `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`.
-- `references/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/skills/video/trailer-shot/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_video summer_generate_image summer_search_assets summer_import_from_url summer_add_node summer_set_prop
+allowed-tools: Read Grep Glob Write Edit summer_generate_video summer_check_job summer_generate_image summer_search_assets summer_import_from_url summer_add_node summer_set_prop
 paths: ["assets/video/**", "trailers/**", "marketing/**"]
 ---
 
@@ -56,23 +56,26 @@ For shots featuring a specific character, weapon, or environment, generate a ref
 
 ```
 summer_generate_image(
-  prompt="<subject>, <archetype-driven framing>, cinematic, dramatic lighting, film still",
-  model="nano-banana-2",
-  options={ image_size: "landscape_16_9" }
+  prompt="<subject>, <archetype-driven framing>, cinematic, dramatic lighting, film still, wide 16:9 framing",
+  model="nano-banana-2"
 )
 ```
 
-For pure environment / abstract / VFX shots, you can skip this and prompt text-to-video directly.
+`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 build the reference in the Summer dashboard (which exposes aspect ratio) and pass its URL. Since image-to-video inherits the reference's framing, a square reference gives you a square trailer shot.
+
+For pure environment / abstract / VFX shots, you can skip this and prompt text-to-video directly — that also unlocks `aspectRatio`, `kling-turbo`, and `veo3`.
 
 ### 3. Pick the model
 
-| Model | Cost | Speed | When |
-|---|---|---|---|
-| `kling` | ~$0.50 | 2-4 min | Default for trailer hero shots — best motion + composition |
-| `kling-turbo` | ~$0.30 | 1-2 min | Same look as kling, faster, slight quality dip |
-| `veo3` | ~$1.00 | 3-5 min | Pitch deck for investors, the one shot that has to be perfect, premium social ad |
-| `ltx` | ~$0.10 | ~30s | B-roll, throwaway tests, blocking the composition before committing |
-| `minimax` | ~$0.40 | 2-3 min | Anime / stylized trailer looks |
+The available models depend on whether you pass `imageUrl`. With a reference image (step 2) the call goes to the image-to-video route, which accepts only `ltx`, `kling`, and `minimax`; `kling-turbo` and `veo3` exist on the text-to-video route only, and pairing either with an `imageUrl` is a 400 `invalid_model`.
+
+| Model | Text-to-video | Image-to-video | Cost | Speed | When |
+|---|---|---|---|---|---|
+| `kling` | yes | yes | $0.50 | 2-4 min | Default for trailer hero shots — best motion + composition |
+| `ltx` | yes | yes | $0.10 | ~30s | B-roll, throwaway tests, blocking the composition before committing |
+| `minimax` | yes | yes | $0.25 | 2-3 min | Anime / stylized trailer looks |
+| `kling-turbo` | yes | **no** | $0.30 | 1-2 min | Same look as kling, faster, slight quality dip — but you lose `imageUrl` |
+| `veo3` | yes | **no** | $1.00 | 3-5 min | Pitch deck for investors, the one shot that has to be perfect — but you lose `imageUrl` |
 
 Default: **`ltx` first to block the composition, then `kling` for the final**. For the *one* hero shot that drives the Steam page, escalate to `veo3` only if `kling` failed twice.
 
@@ -88,9 +91,11 @@ summer_generate_video(
 )
 ```
 
-For vertical social (TikTok, Reels, Shorts): `aspectRatio="9:16"` and frame the subject vertically in your reference image.
+`duration` accepts **only 5 or 10** — anything else is coerced to 5.
 
-For square (Instagram feed): `aspectRatio="1:1"`.
+The call is **asynchronous**: it returns `{ success, queued: true, jobId, model, resolvedModel, estimatedCost, duration }` and **no URL**. Poll `summer_check_job(jobId="<jobId>")` until it reports `completed` before showing the user anything or claiming the shot is done.
+
+`aspectRatio` (`16:9`, `9:16`, `1:1`, ...) is applied on the **text-to-video path only**. The moment you pass `imageUrl` it is ignored and the clip inherits the reference image's framing — so vertical social needs a genuinely 9:16 reference, and square needs a square one. MCP image generation is square-only, so build non-square references in the Summer dashboard (which exposes aspect ratio) or crop them before use.
 
 ### 5. Review against trailer logic
 
@@ -107,10 +112,13 @@ If "regenerate", revise *one* axis (camera move, lighting, or framing) — don't
 
 ### 6. Import for archive (optional)
 
-Trailer footage usually lives on the user's local disk and goes straight into the NLE. But for shots that double as in-engine splash content, import:
+Trailer footage usually lives on the user's local disk and goes straight into the NLE, where the generated `.mp4` is exactly what you want.
+
+For shots that double as **in-engine** splash content, transcode first — Summer Engine has no MP4 or WebM loader, and `.ogv` (Ogg Theora) is the only video container it can open. `summer_import_from_url` runs Godot's import pipeline and rejects the file if it never becomes a loadable resource, so importing the `.mp4` fails outright rather than half-working.
 
 ```
-summer_import_from_url(url="<fileUrl>", path="assets/video/trailers/hero_boss_reveal.mp4")
+ffmpeg -i hero_boss_reveal.mp4 -c:v libtheora -q:v 8 -an hero_boss_reveal.ogv
+summer_import_from_url(url="<hosted .ogv url>", path="res://assets/video/trailers/hero_boss_reveal.ogv")
 ```
 
 For pure trailer use (DaVinci / Premiere), the user can grab the `fileUrl` and download directly.
@@ -142,7 +150,7 @@ Pattern: `<archetype framing> + <subject> + <action verb> + <camera move> + <lig
 | Vertical social hero | `kling` | `vertical close-up of a young witch raising hands, magical wind, hair flowing, candle-warm key, cinematic, framed for 9:16` | $0.50 | 5s |
 | Pitch-deck premium shot | `veo3` | `wide cinematic of a fleet of airships emerging through cloud cover at dawn, slow truck forward, golden god-rays, soaring orchestral cinematic` | $1.00 | 5s |
 | Cheap B-roll iteration | `ltx` | `mid shot of a knight walking through fog, slow truck backward, dawn light, cinematic` | $0.10 | 5s |
-| Anime style hero | `minimax` | `anime-style hero girl draws a katana in slow motion, sakura petals swirling, dramatic side-light, dynamic camera, Ghibli painterly` | $0.40 | 5s |
+| Anime style hero | `minimax` | `anime-style hero girl draws a katana in slow motion, sakura petals swirling, dramatic side-light, dynamic camera, Ghibli painterly` | $0.25 | 5s |
 
 ### Bad prompts and why
 
@@ -160,7 +168,8 @@ Pattern: `<archetype framing> + <subject> + <action verb> + <camera move> + <lig
 - **Skipping the reference image for the hero shot.** The boss in the Steam capsule must look like the boss in the game. Always lock identity with `imageUrl`.
 - **Using `veo3` for B-roll.** Burn $0.10 on `ltx` for blocking and B-roll; reserve `veo3` for the one shot that has to be perfect.
 - **Generating shots without composing the trailer first.** Make a 6-shot list before generating shot 1. Otherwise you'll generate shots that don't intercut.
-- **Using `aspectRatio="16:9"` for vertical social.** TikTok / Reels / Shorts are `9:16`. Pillarboxed 16:9 reads as a desktop YouTube embed and gets demoted by the algorithm.
+- **Assuming `aspectRatio="9:16"` reframed an image-to-video call.** It is ignored whenever `imageUrl` is set — the reference image decides the framing. Pillarboxed 16:9 on TikTok / Reels / Shorts reads as a desktop YouTube embed and gets demoted by the algorithm, so fix the reference, not the argument.
+- **Treating `summer_generate_video` as synchronous.** It returns `{ queued: true, jobId }` and no URL. Poll `summer_check_job` before handing the user a link.
 - **Forgetting that Studio doesn't cut video.** The user has to take the shots into an NLE. Tell them, don't pretend Studio can stitch.
 - **Asking for "the camera does X then Y then Z".** Pick one camera move per shot.
 
@@ -168,7 +177,7 @@ Pattern: `<archetype framing> + <subject> + <action verb> + <camera move> + <lig
 
 - **Steam capsule animated header (Steam asset).** Steam wants `.webm` at 616x353 or 1920x1080, ≤6s, 30fps, no audio, ≤4MB. Generate at 16:9, transcode in DaVinci, export `.webm` with VP9. The video model gives you the source; format conversion is on you.
 - **Pitch deck for investors.** One shot, `veo3`, money composition (low-angle hero or wide establishing). Worth the $1.00.
-- **Vertical for TikTok / Shorts.** `aspectRatio="9:16"`, reference image at portrait, frame the subject in the upper-middle so titles can sit at the bottom.
+- **Vertical for TikTok / Shorts.** The reference image must genuinely be portrait — `aspectRatio` is ignored once `imageUrl` is set. Frame the subject in the upper-middle so titles can sit at the bottom.
 - **Subject is a UGC environment the player built.** Take a screenshot of the in-engine view, run it through `summer_generate_image` as `referenceImageUrl` to "upgrade" the look, then use that as the video reference. The model can stylize a screenshot; it can't invent the user's level.
 - **Logo splash with motion graphics.** Generate a static logo card in `summer_generate_image` (or use the user's existing logo PNG), then prompt video as `static composition of <logo>, only background particles drifting, cinematic, room for title text` — keep the foreground motionless.
 
@@ -178,7 +187,7 @@ If the Studio MCP server isn't running, route the user to the Studio web dashboa
 
 1. Image tab → generate the reference still.
 2. Video tab → image-to-video with the reference URL, model `kling`, duration 5s, aspect ratio per platform.
-3. Download the `.mp4` directly into the user's editing project (DaVinci / Premiere / CapCut).
+3. Download the `.mp4` directly into the user's editing project (DaVinci / Premiere / CapCut). No transcode needed for an NLE — only in-engine playback requires `.ogv`.
 
 Print the exact prompt + model + duration + aspect ratio so the user can paste it into the dashboard verbatim.
 
@@ -200,4 +209,4 @@ Once the shots are generated:
 - `audio/music-track` — trailer score.
 - `audio/sound-effect` — cut SFX (whooshes, impacts, stingers).
 - `2d-assets/concept-art` — generate the reference image axis when no asset exists yet.
-- `references/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/skills/visual-effects/_building-blocks/additive-billboard-particles.md

@@ -1,28 +1,37 @@
 # Additive Billboard Particles — Canonical Material Settings
 
-Reusable `BaseMaterial3D` configuration for additive particle billboards (motes, sparks, glow, ash). Used by `magic-glow`, optionally substitutable in `hit-spark` and `fire` if a custom shader is overkill.
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `magic-glow`, optionally substitutable in `hit-spark` and `fire` if a custom shader is overkill.
+
+`BaseMaterial3D` is abstract — `BaseMaterial3D.new()` is a parse error ("Native class
+"BaseMaterial3D" cannot be constructed as it is abstract"). Instantiate
+`StandardMaterial3D`; the `BaseMaterial3D.*` enum constants below are still the right
+way to name the values.
 
 ## Settings
 
-```
-transparency: BaseMaterial3D.TRANSPARENCY_ALPHA
-blend_mode: BaseMaterial3D.BLEND_MODE_ADD
-shading_mode: BaseMaterial3D.SHADING_MODE_UNSHADED
-billboard_mode: BaseMaterial3D.BILLBOARD_PARTICLES
-emission_enabled: true
-emission_energy_multiplier: 3.0   // 1.0–5.0 typical; bump for HDR bloom
-disable_receive_shadows: true
-shadow_to_opacity: false
-no_depth_test: false              // true only if particles must read on TOP of opaque geometry
-albedo_color: Color(R, G, B, 1.0)
-emission: Color(R, G, B)          // usually same as albedo for single-color motes
+```gdscript
+var bm := StandardMaterial3D.new()
+bm.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
+bm.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
+bm.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+bm.billboard_mode = BaseMaterial3D.BILLBOARD_PARTICLES
+bm.emission_enabled = true
+bm.emission_energy_multiplier = 3.0   # 1.0–5.0 typical; bump for HDR bloom
+bm.disable_receive_shadows = true
+bm.shadow_to_opacity = false
+bm.no_depth_test = false              # true only if particles must read on TOP of opaque geometry
+bm.billboard_keep_scale = true        # BILLBOARD_PARTICLES drops per-particle scale without this
+bm.albedo_color = Color(R, G, B, 1.0)
+bm.emission = Color(R, G, B)          # usually same as albedo for single-color motes
 ```
 
 ## When to use this vs a custom shader
 
-- **Use this `BaseMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free Godot-managed billboard math.
-- **Use a custom `ShaderMaterial`** when you need per-particle color ramps over `CUSTOM.x` age (fire), shape masks (muzzle flash star burst), or stretched streaks (hit-spark). Those can't be expressed in `BaseMaterial3D`.
+- **Use this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free Godot-managed billboard math.
+- **Per-particle color over age does NOT need a custom shader.** `ParticleProcessMaterial` has `color_ramp`, `color_initial_ramp`, `alpha_curve` and `emission_curve` (all verified present in 4.6) — those drive the particle's `COLOR` from age and feed straight into a plain `StandardMaterial3D`. Reach for a ramp before reaching for a shader.
+- **Use a custom `ShaderMaterial`** when you need per-fragment shape masks (muzzle flash star burst), noise-distorted UVs (fire, smoke), or anything that varies *within* the quad. Those are what `StandardMaterial3D` genuinely can't express.
+- If a custom shader does need the particle age, note that the age lives in `INSTANCE_CUSTOM.y` (normalized by `INSTANCE_CUSTOM.w`, the lifetime), that `INSTANCE_CUSTOM.x` is the rotation angle — not the age — and that `INSTANCE_CUSTOM` is **vertex-stage only**. Pass it to `fragment()` through a `varying`.
 
 ## Performance note
 
-Additive overdraw is fillrate-bound. Keep `draw_pass_1.size <= 0.2` for motes/sparks; larger quads at full additive intensity destroy mobile fillrate budgets fast.
+Additive overdraw is fillrate-bound. `draw_pass_1` is a `Mesh`, so the size dial is on the mesh: keep `QuadMesh.size` at or under `Vector2(0.2, 0.2)` for motes/sparks. Larger quads at full additive intensity destroy mobile fillrate budgets fast.

package/skills/visual-effects/_building-blocks/trauma-shake-snippet.md

@@ -22,8 +22,7 @@ func _process(delta: float) -> void:
         if camera == null:
             return
     if trauma > 0.0:
-        var s = trauma * trauma     // perceived intensity grows quadratically
-        var t = Time.get_ticks_msec() * 0.01
+        var s := trauma * trauma  # perceived intensity grows quadratically
         camera.h_offset = max_offset.x * s * (randf() * 2.0 - 1.0)
         camera.v_offset = max_offset.y * s * (randf() * 2.0 - 1.0)
         camera.rotation.x += max_pitch * s * (randf() * 2.0 - 1.0) * 0.1
@@ -37,7 +36,10 @@ func add_trauma(amount: float) -> void:
     trauma = clamp(trauma + amount, 0.0, 1.0)
 ```
 
-Register `CameraShake` as autoload in Project Settings.
+Register `CameraShake` as autoload in Project Settings. An autoload is a node at
+`/root/CameraShake`, not an engine singleton — reach it with
+`get_node_or_null("/root/CameraShake")`. `Engine.has_singleton("CameraShake")` is
+always `false` for an autoload (measured), so never gate the call on it.
 
 ## Usage
 

package/skills/visual-effects/game-feel/SKILL.md

@@ -1,17 +1,22 @@
 ---
 name: game-feel
-description: Use when the user says the game "feels flat", "lacks impact", "needs juice", "needs punch", or asks for hit feedback, screen shake, camera shake, audio ducking, or general "game feel". Walks the user through the canonical Godot 4.5 game-feel stack — hit-flash + trauma camera shake + audio ducking — wired together so a single hit fires all three. Trigger on "vfx", "juice", "punch", "feels flat", "game feel", "hit flash", "screen shake", "camera shake", "ducking".
+description: Use when a Summer game "feels flat", "lacks impact", "needs juice", or "needs punch", or the user asks for hit feedback, screen shake, camera shake, audio ducking, or general game feel. Walks through Summer Engine's hit-flash, trauma camera shake, and audio-ducking stack, wired so one hit fires all three. Trigger on "vfx", "juice", "punch", "feels flat", "game feel", "hit flash", "screen shake", "camera shake", "ducking".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_add_node summer_set_prop summer_set_resource_property summer_connect_signal summer_save_scene summer_get_script_errors summer_play summer_stop
+allowed-tools: Read Grep Edit Write summer_write_file summer_read_file summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_add_node summer_set_prop summer_set_resource_property summer_connect_signal summer_project_setting summer_save_scene summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 ---
 
 # /vfx — The Trio That Makes Games Feel Punchy
 
-Particles don't make a game feel good. Screen shake alone doesn't either. What makes a hit *land in the body* is three systems firing on the same frame: a sub-frame **hit flash** on the body that got hit, **trauma-based camera shake** with quadratic falloff so big hits saturate, and **audio ducking** that briefly squashes Music/Ambient so the impact SFX punches through. Skip any one and the game drops back to "tech demo". This skill installs the canonical Godot 4.5 stack — three small, self-contained systems wired to a single signal — so one `hit()` call fires all three.
+Particles do not make a game feel good. Screen shake alone does not either.
+What makes a hit land is three systems firing on the same frame: a sub-frame
+**hit flash** on the body that got hit, **trauma-based camera shake** with
+quadratic falloff so big hits saturate, and **audio ducking** that briefly
+squashes Music/Ambient so the impact SFX punches through. This skill installs
+the canonical Summer Engine stack as three small systems wired to one signal.
 
 ## Step 1 — Ask what feels flat
 
@@ -62,13 +67,15 @@ World/
     HitFlash (Node)              # holds the script, no transform
 ```
 
-**MCP path:**
+**MCP path** (every scene-mutating call takes an explicit `scenePath`):
 
 ```
-summer_add_node(parent="./World/Enemy", type="Node", name="HitFlash")
+summer_add_node(scenePath="res://levels/world.tscn", parent="./World/Enemy", type="Node", name="HitFlash")
+summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Enemy/HitFlash", key="script", value="res://scripts/vfx/hit_flash.gd")
 ```
 
-Then write `scripts/vfx/hit_flash.gd`:
+Then write `scripts/vfx/hit_flash.gd` (via `summer_write_file`, which requires exactly
+one of `create_only` or `expected_sha256`):
 
 ```gdscript
 class_name HitFlash
@@ -110,7 +117,7 @@ func flash() -> void:
 
 **Tunable knobs:** `duration` 0.06–0.12s — under 0.06 reads as a flicker, over 0.12 looks slow. `emission_energy_multiplier` 1.5–3.0.
 
-> CRITICAL: do NOT inline a `StandardMaterial3D` as a `sub_resource` via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres`. Inline sub_resources break `summer_set_resource_property` silently — see `references/mcp-tools-reference.md` § "Trap".
+> CRITICAL: do NOT inline a `StandardMaterial3D` as a `sub_resource` via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres`. Inline sub_resources break `summer_set_resource_property` silently — see `../../../references/mcp-tools-reference.md` § "Trap".
 
 ## Step 5 — Install Section 2 (Trauma Camera Shake)
 
@@ -121,8 +128,8 @@ func flash() -> void:
 **Node tree:** the script attaches to the existing `./World/Player/Camera3D`. No new nodes.
 
 ```
-summer_inspect_node "./World/Player/Camera3D"
-# attach scripts/vfx/camera_shake.gd
+summer_inspect_node(path="./World/Player/Camera3D")
+summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Player/Camera3D", key="script", value="res://scripts/vfx/camera_shake.gd")
 ```
 
 `scripts/vfx/camera_shake.gd`:
@@ -138,6 +145,11 @@ extends Camera3D
 var _trauma: float = 0.0
 var _shake_offset: Vector3 = Vector3.ZERO
 
+func _ready() -> void:
+    # Node has no `groups` property, so there is nothing to set from the outside.
+    # Joining the group here is how any actor finds this camera later.
+    add_to_group(&"player_camera")
+
 func add_trauma(amount: float) -> void:
     _trauma = clamp(_trauma + amount, 0.0, 1.0)
 
@@ -236,12 +248,9 @@ func duck(amount: float, duration: float = 0.5) -> void:
         var drop_db := -24.0 * amount * weight
         var target_db := base_db + drop_db
 
-        var seq := create_tween()
-        seq.tween_property(AudioServer, "bus_volume_db", target_db, attack).set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)\
-            .from(base_db)
-        # NOTE: AudioServer doesn't expose bus volume as an animatable
-        # property — use a method tween instead. See actual call below.
-        # (The simpler, real implementation:)
+        # AudioServer exposes bus volume through a method, not an animatable
+        # property, so tween_method is the only form that works here.
+        # `tween_property(AudioServer, "bus_volume_db", ...)` errors at runtime.
         _tween.tween_method(_set_bus_db.bind(idx), base_db, target_db, attack)\
             .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)
         _tween.tween_method(_set_bus_db.bind(idx), target_db, base_db, release)\
@@ -255,9 +264,12 @@ func _set_bus_db(idx: int, db: float) -> void:
 Register it as an autoload:
 
 ```
-Project Settings → Autoload → Add scripts/vfx/audio_ducker.gd as "AudioDucker"
+summer_project_setting(...)   # autoload/AudioDucker = "*res://scripts/vfx/audio_ducker.gd"
 ```
 
+(Equivalently, by hand: Project Settings → Autoload → Add `scripts/vfx/audio_ducker.gd`
+as `AudioDucker`.)
+
 **Calling it:**
 
 ```gdscript
@@ -290,25 +302,27 @@ func _on_damaged(amount: float) -> void:
     # 1. Hit flash on this body.
     _hit_flash.flash()
     # 2. Camera shake on the player's camera, scaled by hit weight.
-    var trauma := clamp(0.2 + amount * 0.05, 0.2, 0.9)
+    # clampf(), not clamp(): clamp() returns Variant, and inferring a variable from
+    # a Variant is an error under Godot's default warning settings.
+    var trauma := clampf(0.2 + amount * 0.05, 0.2, 0.9)
     if _player_camera:
         _player_camera.add_trauma(trauma)
     # 3. Audio duck, scaled by hit weight.
-    var duck_amount := clamp(0.3 + amount * 0.04, 0.3, 1.0)
+    var duck_amount := clampf(0.3 + amount * 0.04, 0.3, 1.0)
     AudioDucker.duck(duck_amount, 0.45)
 ```
 
-Add the camera to a group so any actor can find it:
-
-```
-summer_add_node(...)   # ./World/Player/Camera3D already exists
-summer_set_prop(path="./World/Player/Camera3D", key="groups", value='["player_camera"]')
-```
+The camera joins `player_camera` from its own `_ready()` (Step 5). `Node` has no
+`groups` property, so `summer_set_prop(key="groups", ...)` cannot do this — and
+`summer_set_prop` only accepts a string, number, or boolean anyway, never an array.
+The two ways that do work are the `add_to_group()` call in `_ready()` or a `groups =
+["player_camera"]` line written into the `.tscn` node header.
 
-Or wire the signal explicitly via MCP if you prefer:
+Or wire the signal explicitly via MCP if you prefer (`emitter`/`receiver`, not
+`from`/`to`, and `scenePath` is required):
 
 ```
-summer_connect_signal(from="./World/Enemy", signal="damaged", to="./World/Enemy/HitFlash", method="flash")
+summer_connect_signal(scenePath="res://levels/world.tscn", emitter="./World/Enemy", signal="damaged", receiver="./World/Enemy/HitFlash", method="flash")
 ```
 
 ## Step 8 — Scaling intensity per hit weight
@@ -328,10 +342,11 @@ Because trauma is squared inside the camera, the *felt* difference between 0.35
 ## Step 9 — Verify
 
 ```
-summer_save_scene
-summer_get_script_errors
+summer_save_scene(scenePath="res://levels/world.tscn")
+summer_get_script_errors          # all three scripts parsed?
 summer_play
 # user reproduces a hit
+summer_get_debugger_errors        # runtime errors from the tweens / bus lookups
 summer_stop
 ```
 
@@ -355,10 +370,12 @@ Tune one knob at a time:
 | Equal pitch/yaw shake | `yaw_factor ≤ 0.5` | Eyes are sensitive to vertical motion; equal axes feel mechanical |
 | `Engine.time_scale` for every hit | Reserve hit-stop for big events only (boss hits, deaths) | Time-scale dips on every hit feel laggy, not impactful |
 | Inline `StandardMaterial3D` sub_resource via `summer_set_prop` | Build in script or save standalone `.tres` | Inline sub_resources silently break `summer_set_resource_property` |
+| `summer_set_prop(key="groups", value='["player_camera"]')` | `add_to_group(&"player_camera")` in `_ready()`, or a `groups = [...]` line in the `.tscn` | `Node` has no `groups` property, and `summer_set_prop` takes only string/number/boolean — never an array |
+| `BaseMaterial3D.new()` | `StandardMaterial3D.new()` | `BaseMaterial3D` is abstract; constructing it is a parse error that kills the whole script |
 
 ## Collaborative protocol
 
-This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `references/collaborative-protocol.md`.
+This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `../../../references/collaborative-protocol.md`.
 
 ## When NOT to use this skill
 
@@ -369,10 +386,11 @@ This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always as
 
 ## See also
 
-- `references/mcp-tools-reference.md` — full MCP tool list, especially the inline-sub_resource trap
-- `references/godot-version.md` — Godot 4.5 API notes
-- `references/collaborative-protocol.md` — "May I write" pattern
-- `references/gd-style.md` — typed GDScript conventions
+- `../../../references/mcp-tools-reference.md` — full MCP tool list, especially the inline-sub_resource trap
+- `../../../references/godot-version.md` — Summer compatibility and
+  version-sensitive API notes
+- `../../../references/collaborative-protocol.md` — "May I write" pattern
+- `../../../references/gd-style.md` — typed GDScript conventions
 - `audio/audio-direction/SKILL.md` — bus layout setup (prerequisite for ducking)
 - `post-processing/screen-shake/SKILL.md` — deeper trauma variants (Perlin noise, stacked sources)
 - `visual-effects/gpuparticles-3d-basics/SKILL.md` — particles to layer on top of the trio