summer-engine 2.7.0 → 2.8.0

package/skills/ui-and-ux/ui-basics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ui-basics
-description: Use when building Godot UI — HUDs, main menus, pause menus, health bars, progress bars, dialogue boxes, or any Control-node tree. Covers anchors, containers (VBox/HBox/Margin), responsive layout, and theme vs inline styling. Trigger on "UI", "HUD", "menu", "health bar", "Control", "anchors", "VBoxContainer", "main menu", "pause menu".
+description: Use when building Summer Engine UI: HUDs, main menus, pause menus, health bars, progress bars, dialogue boxes, or any Control-node tree. Covers anchors, containers (VBox/HBox/Margin), responsive layout, and theme versus inline styling. Trigger on "UI", "HUD", "menu", "health bar", "Control", "anchors", "VBoxContainer", "main menu", "pause menu".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: ui-and-ux
@@ -11,7 +11,8 @@ paths: ["**/*.tscn", "**/*.gd"]
 
 # UI Basics for Summer Engine
 
-Build menus and HUDs using Godot's Control nodes. Follow these patterns for layout, buttons, and responsive design.
+Build menus and HUDs using Summer Engine Control nodes. Follow these patterns
+for layout, buttons, and responsive design.
 
 ## Control Hierarchy
 
@@ -57,14 +58,17 @@ summer_add_node(parent="./MainMenu/Margin/VBox", type="Button", name="QuitButton
 summer_set_prop(path="./MainMenu/Margin/VBox/QuitButton", key="text", value="Quit")
 ```
 
-For nested theme overrides, use `summer_set_resource_property` if the property is on a resource. For `theme_override_constants/margin_left`, it may be a direct node property—check Godot docs. Some constants are set via `add_theme_constant_override`. If `summer_set_prop` accepts `theme_override_constants/margin_left`, use it; otherwise the UI may need a script or theme resource.
+For nested theme overrides, use `summer_set_resource_property` if the property
+is on a resource. For `theme_override_constants/margin_left`, inspect the live
+node or the upstream API reference matching the current Summer technical base.
+Some constants use `add_theme_constant_override`.
 
 ## HUD (Health Bar)
 
 ```
 summer_add_node(parent="./", type="CanvasLayer", name="HUD")
 summer_add_node(parent="./HUD", type="MarginContainer", name="TopLeft")
-summer_set_prop(path="./HUD/TopLeft", key="anchors_preset", value="1")  # Top-left
+summer_set_prop(path="./HUD/TopLeft", key="anchors_preset", value="0")  # Top-left is 0; 1 is Top-right
 summer_add_node(parent="./HUD/TopLeft", type="HBoxContainer", name="HealthContainer")
 summer_add_node(parent="./HUD/TopLeft/HealthContainer", type="Label", name="HealthLabel")
 summer_set_prop(path="./HUD/TopLeft/HealthContainer/HealthLabel", key="text", value="Health:")
@@ -78,7 +82,7 @@ ProgressBar uses `value` and `max_value` for the fill. Update `value` from a scr
 
 ## Anchors Preset
 
-Common preset values (Godot 4):
+Common preset values in the current Summer Engine UI API:
 
 | Preset | Value | Description |
 |--------|-------|-------------|
@@ -95,9 +99,14 @@ Set via `summer_set_prop(path, key="anchors_preset", value="15")`.
 Wire the `pressed` signal to a handler:
 
 ```
-summer_connect_signal(emitter="./MainMenu/Margin/VBox/StartButton", signal="pressed", receiver="./MainMenu", method="_on_start_pressed")
+summer_connect_signal(scenePath="res://main.tscn", emitter="./MainMenu/Margin/VBox/StartButton", signal="pressed", receiver="./MainMenu", method="_on_start_pressed")
 ```
 
+`scenePath` is required on every scene-mutating tool in this skill
+(`summer_add_node`, `summer_set_prop`, `summer_connect_signal`,
+`summer_save_scene`). The examples above omit it only for readability — a real
+call without it is rejected before it reaches the engine.
+
 The receiver node must have a script with `func _on_start_pressed() -> void:`.
 
 ## Property Reference
@@ -147,4 +156,4 @@ text = "Start Game"
 
 ## Collaborative protocol
 
-This skill writes UI scene nodes and wires button signals. Always ask before applying: "May I add the MainMenu (Control + Margin + VBox + Title + Start/Quit buttons) and connect Start.pressed to `_on_start_pressed`?". See `../../references/collaborative-protocol.md`.
+This skill writes UI scene nodes and wires button signals. Always ask before applying: "May I add the MainMenu (Control + Margin + VBox + Title + Start/Quit buttons) and connect Start.pressed to `_on_start_pressed`?".

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

@@ -5,13 +5,15 @@ 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/**", "menus/**", "ui/**"]
 ---
 
-# animated-loop — 3-5 Second Seamless Background Loop
+# 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: keep the duration short (3-5s), 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 cheap 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.
 
@@ -30,13 +32,13 @@ If the user wants a 5s punchy marketing shot, that's `video/trailer-shot`. If th
 - 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.
 - 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 3-5s clip designed to loop.
+- 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.
 
 ## Steps
 
 ### 1. Confirm the loop will be visible for a long time
 
-> 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 keep it 3-5s and prompt for ambient motion (drift, flicker, shimmer) rather than a narrative beat. OK?
+> 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`.
 
@@ -44,13 +46,15 @@ If the user wants narrative motion (a character walking, a door opening), this i
 
 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.
 
-| Model | Cost | Speed | When |
-|---|---|---|---|
-| `ltx` | ~$0.10 | ~30s | Default. Use this. |
-| `kling` | ~$0.50 | 2-4 min | Only if the loop is the centerpiece of a premium splash and quality is visibly lacking on `ltx` |
-| `kling-turbo` | ~$0.30 | 1-2 min | Same as `kling` but faster |
-| `veo3` | ~$1.00 | 3-5 min | Almost never — `veo3` shines on dialogue/identity, neither matters for ambient loops |
-| `minimax` | ~$0.40 | 2-3 min | Stylized / anime aesthetic loops |
+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 |
 
 ### 3. Lock the look with a reference still
 
@@ -58,13 +62,14 @@ The reference still doubles as the *target* loop frame. Generate it deliberately
 
 ```
 summer_generate_image(
-  prompt="<subject>, ambient atmospheric scene, cinematic lighting, painterly, balanced composition with no clear focal action",
-  model="nano-banana-2",
-  options={ image_size: "landscape_16_9" }
+  prompt="<subject>, ambient atmospheric scene, cinematic lighting, painterly, wide 16:9 framing, balanced composition with no clear focal action",
+  model="nano-banana-2"
 )
 ```
 
-For vertical menus (mobile portrait splash), generate at portrait and use `aspectRatio="9:16"` on the video call.
+`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.
 
 ### 4. Prompt for loopable motion only
 
@@ -79,13 +84,16 @@ summer_generate_video(
   prompt="<subject from reference>, <ambient loopable motion>, slow continuous, looping, seamless, cinematic",
   model="ltx",
   imageUrl="<reference URL from step 3>",
-  duration=4,
-  aspectRatio="16:9",
+  duration=5,
   options={ negative_prompt: "sudden movement, character action, narrative event, fade to black" }
 )
 ```
 
-The phrase **"looping, seamless"** in the prompt biases the model toward stable first/last frames. The negative prompt rules out narrative drift.
+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.
+
+`aspectRatio` is omitted deliberately: it is applied on the text-to-video path only, and this call passes `imageUrl`.
+
+The call returns `{ success, queued: true, jobId, ... }` and **no URL** — video generation is asynchronous. Poll `summer_check_job(jobId="<jobId>")` until it reports `completed`, and only then treat the clip as existing.
 
 ### 5. Inspect the seam
 
@@ -93,25 +101,40 @@ Watch the result and the seam (the cut between the last and first frame on repla
 
 - **Most common cause:** something moved across the frame and didn't return (a particle drifted off-screen, a cloud moved). Regenerate with `slow continuous, returning motion, oscillating` in the prompt.
 - **Second cause:** lighting drifted. Regenerate with `constant lighting, no time of day change`.
-- **Third cause:** the duration was too long. Drop from 5s to 3s and regenerate.
+- **Third cause:** the motion is simply too fast to close in the time available. You cannot shorten the clip — 5s is the minimum the API offers — so slow the motion in the prompt instead (`very slow`, `barely perceptible drift`).
 
 If three regenerations don't seam-close, accept a small crossfade in the engine: set up two `VideoStreamPlayer` nodes and crossfade between them via a `Tween`. This is a fallback, not the goal.
 
 ### 6. Import and wire as a looping VideoStreamPlayer
 
+**Transcode to Ogg Theora first.** The generated clip is an `.mp4`, and Summer Engine cannot load `.mp4`. `.ogv` is the only video container in the build — there is no bundled WebM or MP4 plugin, and nothing transcodes on your behalf. 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)
+```
+
+`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:
+
+```
+ffmpeg -i title_screen_bg.mp4 -c:v libtheora -q:v 8 -an title_screen_bg.ogv
+```
+
 ```
-summer_import_from_url(url="<fileUrl>", path="assets/video/loops/title_screen_bg.ogv")
+summer_import_from_url(url="<hosted .ogv url>", path="res://assets/video/loops/title_screen_bg.ogv")
 ```
 
-Note: Godot's `VideoStreamPlayer` natively plays Ogg Theora (`.ogv`); for `.mp4` you may need to transcode or rely on the engine's bundled WebM/MP4 plugin. Studio's import pipeline handles transcoding when the path extension is set explicitly — confirm the resulting resource type with `summer_inspect_resource` if playback fails.
+Then wire it. Every scene-mutating tool takes an explicit `scenePath`, and `summer_set_prop`'s property argument is named `key`, not `property`:
 
 ```
-summer_add_node(parent="./TitleScreen", type="VideoStreamPlayer", name="BackgroundLoop")
-summer_set_prop(path="./TitleScreen/BackgroundLoop", property="stream", value="res://assets/video/loops/title_screen_bg.ogv")
-summer_set_prop(path="./TitleScreen/BackgroundLoop", property="autoplay", value=true)
-summer_set_prop(path="./TitleScreen/BackgroundLoop", property="loop", value=true)
-summer_set_prop(path="./TitleScreen/BackgroundLoop", property="expand", value=true)
-summer_set_prop(path="./TitleScreen/BackgroundLoop", property="anchors_preset", value=15)
+summer_add_node(scenePath="res://ui/title_screen.tscn", parent=".", type="VideoStreamPlayer", name="BackgroundLoop")
+summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="stream", value="res://assets/video/loops/title_screen_bg.ogv")
+summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="autoplay", value=true)
+summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="loop", value=true)
+summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="expand", value=true)
+summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="anchors_preset", value=15)
+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).
@@ -121,7 +144,7 @@ Anchors preset 15 is "full rect" — the loop fills the menu. Place the logo and
 Loops should never have a baked audio track that loops with them — the audio seam will be even more obvious than the visual one. The video models don't generate audio anyway, but if you ever import a clip that has audio, mute it:
 
 ```
-summer_set_prop(path="./TitleScreen/BackgroundLoop", property="volume_db", value=-80)
+summer_set_prop(scenePath="res://ui/title_screen.tscn", path="./BackgroundLoop", key="volume_db", value=-80)
 ```
 
 Score the menu separately with `audio/music-track`.
@@ -132,13 +155,13 @@ Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping
 
 | 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 | 4s |
-| 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 | 4s |
+| 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 | 3s |
+| 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 | 4s |
-| Title — anime sky | `minimax` | `anime style cumulus clouds drifting slowly across a pastel sunset sky, soft, painterly, looping, seamless, Ghibli` | $0.40 | 4s |
+| 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 |
 
 ### Bad prompts and why
@@ -153,18 +176,19 @@ Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping
 
 ## Anti-patterns
 
-- **Asking the model for a 10s loop.** Past ~6s, identity drifts and the seam shows. Cap at 5s.
+- **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.
 - **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.
-- **Using `aspectRatio="16:9"` for a portrait splash.** Pillarboxed loops on a vertical splash look broken. Set `9:16` and frame portrait.
-- **Importing without transcoding to a Godot-friendly container.** `VideoStreamPlayer` natively wants Ogg Theora; `.mp4` works with the bundled plugin but isn't guaranteed across platforms — confirm with `summer_inspect_resource`.
+- **Expecting `aspectRatio` to reframe an image-to-video call.** It is applied on the text-to-video path only. A portrait splash needs a portrait *reference image* — the argument does nothing here.
+- **Importing the `.mp4` as-is.** `.ogv` is the only video container the engine can load; there is no bundled WebM or MP4 plugin. An un-transcoded import fails and is rolled back.
 
 ## 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.** `aspectRatio="9:16"`, reference image at portrait, anchors preset 15 still works.
+- **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.
 - **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.
@@ -197,4 +221,4 @@ Once the loop is wired:
 - `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.
-- `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/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.