summer-engine 2.6.6 → 2.8.0

package/skills/scene-and-project/scene-composition/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-composition
-description: Use when building or organizing scenes in Godot — node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, instance vs add-node decisions. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy", "scene structure", "PackedScene".
+description: Use when building or organizing Summer Engine scenes: node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, and instance-versus-add-node decisions. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy", "scene structure", "PackedScene".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
@@ -80,8 +80,8 @@ Use `./` for paths relative to the scene root:
 
 1. Build the hierarchy in the main scene
 2. Select the root of what you want to extract
-3. Save as scene: `summer_save_scene(path="res://scenes/player.tscn")`. SaveScene saves the current open scene, so build reusable scenes in their own open scene and save them there. Do not handwrite `.tscn` files as the preferred path.
-4. In the main scene, add it with `summer_instantiate_scene(parent="./World", scene="res://scenes/player.tscn", name="Player")`
+3. Save as scene: `summer_save_scene(scenePath="res://scenes/source.tscn", path="res://scenes/player.tscn")`. `scenePath` names the scene being saved and is **required**; `path` is the optional save-as target. There is no "current scene" default.
+4. In the main scene, add it with `summer_instantiate_scene(scenePath="res://main.tscn", parent="./World", scene="res://scenes/player.tscn", name="Player")`
 
 **Practical approach:** Create reusable scenes (player.tscn, enemy.tscn) as separate scene files, then instantiate them into levels.
 
@@ -97,9 +97,9 @@ Use `./` for paths relative to the scene root:
 
 ## Save Conventions
 
-- Always call `summer_save_scene` after changes you want to keep
-- For new scenes: `summer_save_scene(path="res://scenes/level1.tscn")`
-- For existing scenes: `summer_save_scene` (no path, uses current scene path)
+- The mutation tools (`summer_add_node`, `summer_set_prop`, ...) already append one save per call, so a standalone `summer_save_scene` is only for a save-as or an explicit extra flush
+- Save-as: `summer_save_scene(scenePath="res://main.tscn", path="res://scenes/level1.tscn")`
+- Plain save: `summer_save_scene(scenePath="res://main.tscn")` — `scenePath` is required in both forms
 
 ## Common Mistakes
 
@@ -110,7 +110,20 @@ Use `./` for paths relative to the scene root:
 
 ## Fallback
 
-No fallback for this — Summer MCP required. Handwriting `.tscn` files for hierarchy mutations is error-prone (UID collisions, wrong format version, broken sub_resource refs). If MCP isn't connected, open the scene in the Godot editor and use the SceneTree dock.
+MCP is the preferred path, not a requirement. Hand-written `.tscn` text loads and
+instantiates fine — including `[ext_resource]` lines with **no `uid=` field**,
+which the engine resolves by path (verified by loading such a scene on the
+shipped 4.6.1 build). Format version 3 is current for Godot 4.
+
+What actually goes wrong when you hand-write scenes is mundane and checkable:
+a `SubResource("id")` with no matching `[sub_resource id="id"]` block, a
+`parent=` path naming a node that isn't declared above it, or an
+`[ext_resource path=...]` pointing at a file that hasn't been imported yet
+(`--headless --import`, or `summer_import_from_url`, before it will load).
+
+So: use MCP when it's connected because the ops are undoable as one step and the
+engine validates paths for you. When it isn't, write the `.tscn` and then open it
+once to confirm it loads. Do not tell the user it's impossible.
 
 ## Trap — Cross-scene transform leak when copying a scene as a template
 
@@ -143,4 +156,4 @@ Don't skip the player mask update. If you only move foliage to layer 9 without a
 
 ## Collaborative protocol
 
-This skill creates and mutates scene files. Always ask before applying: "May I create `res://scenes/player.tscn` and instantiate it under `./World`?". See `../../references/collaborative-protocol.md`.
+This skill creates and mutates scene files. Always ask before applying: "May I create `res://scenes/player.tscn` and instantiate it under `./World`?".

package/skills/scene-and-project/summer-cloud/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: summer-cloud
+description: Use when the user wants to sync a Summer Engine project, move it to another machine or laptop, share the exact bytes with a collaborator, back up big generated assets that do not belong in git, restore an earlier version, or wants a safety net before a risky bulk operation. Trigger on "sync", "Summer Cloud", "cloud push", "cloud pull", "move to another machine", "other computer", "second machine", "share project", "back up assets", "big assets", "collaborator", "teammate", "restore a version", "checkpoint", "conflict".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+user-invocable: true
+allowed-tools: Read summer_cloud_init summer_cloud_status summer_cloud_push summer_cloud_pull summer_cloud_restore summer_cloud_checkpoints summer_cloud_conflicts
+paths: ["summer-cloud.json"]
+---
+
+# Summer Cloud: Project Sync
+
+## What Summer Cloud is
+
+Summer Cloud is content-addressed sync for a whole Summer Engine project. Every tracked file is identified by its sha256 hash, so identical bytes upload once and dedupe across versions and projects. It syncs the entire project tree at once (code, scenes, resources, import sidecars, and the heavy binary assets), not a hand-picked folder. The only git-tracked cloud artifact is a tiny `summer-cloud.json` binding at the project root; all real sync state lives under `.summer/local/cloud/` and is never committed.
+
+This is not a folder backup and it is not a git replacement. Code that lives happily in git can stay in git. What Cloud adds is a way to move the large generated binaries (models, textures, audio, video) that do not belong in a git repo, and to keep a project byte-identical across machines and collaborators. Git and Cloud can run side by side; the binding file merges trivially.
+
+## When to offer it (proactive triggers)
+
+Surface Cloud, do not wait to be asked, when any of these are true:
+
+- The project has heavy generated assets (large `.glb`, `.png`, `.wav`, `.ogg`, `.mp4` under `assets/`) that should not go into git. Cloud is how those travel.
+- The user mentions a second machine, a laptop, "my other computer", or working from somewhere else. Cloud is how the same bytes show up there.
+- A teammate or collaborator needs the exact same project state. Add them as a collaborator and they pull.
+- A risky bulk operation is about to run (mass asset import, a large refactor, a destructive cleanup). A push first gives a restorable version to fall back to.
+
+If none of these apply, do not push Cloud on the user. It is a tool for a real need, not a default step.
+
+## Command and tool surface
+
+| Action | CLI | MCP tool |
+|---|---|---|
+| Enable Cloud for this project | `summer cloud init` | `summer_cloud_init` |
+| Show what would push/pull | `summer cloud status` | `summer_cloud_status` |
+| Upload local changes | `summer cloud push` | `summer_cloud_push` |
+| Download remote changes | `summer cloud pull` | `summer_cloud_pull` |
+| Restore an earlier version or a local checkpoint | `summer cloud restore --version N` / `--checkpoint <stamp>` | `summer_cloud_restore` |
+| List local pre-sync checkpoints | `summer cloud checkpoints` | `summer_cloud_checkpoints` |
+| List or recover conflict sets | `summer cloud conflicts list` / `restore <path>` | `summer_cloud_conflicts` |
+
+Run `summer cloud status` before any push or pull. It reports the file counts, what would move in each direction, and whether any conflict sets are waiting. Never push blind.
+
+## The safety model (respect this)
+
+The whole point of Cloud is that user data is never destroyed silently. The rules below are how that holds. Do not work around them.
+
+- **Every push is a restorable version.** The server keeps the version history within the retention window. Version numbers are never reused. If a bad push lands, `summer cloud restore --version N` brings the project back as a new head version, then pulls it locally.
+- **Local checkpoints come before destructive applies.** Before a pull modifies or deletes any existing file, the client writes a full-tree checkpoint into the project's local SummerGit repo. `summer cloud checkpoints` lists them; `summer cloud restore --checkpoint <stamp>` rolls back. Note the honest caveat the restore prints: it restores bytes but does not delete files a bad sync added, so review and remove any extras it lists.
+- **Large deletions are gated.** A push that would delete many cloud files (more than 10 files, or at least 20% of the tracked tree, or the entire tree) requires `confirmDeletes: true` on the MCP tool (or `--confirm-deletes` on the CLI). Never pass it blindly. First run `summer cloud status`, read the delete count out loud to the user, and only set the flag once they confirm that count is what they intend. If the local tree reads as completely empty against a non-empty base (a wrong directory or an unmounted volume), the push aborts outright and no flag can force it.
+- **Conflicts become conflict sets, never silent overwrites.** Concurrent edits to the same file are resolved deterministically: the first sync to land wins the canonical path (this is "first to sync wins", not "most recent save wins", because there are no wall clocks). The losing bytes are preserved, never discarded, in a local conflict set and backed up to the cloud. Surface them with `summer cloud conflicts list` and recover any with `summer cloud conflicts restore <path>`, which re-enters the file as a fresh edit. `project.godot` is the one file merged key by key rather than whole-file, so input actions and autoloads from both sides survive.
+- **A modify always beats a delete.** If one side edited a file and the other deleted it, the edited file is kept and the deletion is dropped, with a notice. Offline work is never lost to someone else's delete.
+
+## First sync and the bootstrap choice
+
+When a project already has files on both the local disk and in the cloud but this machine has no sync base (for example a fresh git clone of a project that was cloud-enabled elsewhere), auto-sync will not run. The tool returns a bootstrap choice. Present it to the user and let them pick:
+
+- `keep-cloud` (pull): replace local divergent files with the cloud version. Local divergent files are checkpointed first.
+- `keep-local` (push): make the local tree the new cloud version.
+- `merge`: converge automatically where hashes already match (usually most files); the rest get normal conflict treatment.
+
+If the project folder was moved or Finder-copied, sync blocks until you confirm whether to adopt the new path (`adoptPath: true`) or fork it into a separate cloud project. Two folders must never fight over one project.
+
+## Honest v1 limits
+
+State these plainly when they are relevant; do not paper over them.
+
+- **One linear head per project. No branches yet.** There is a single history line. If a user wants an isolated line to experiment with assets, fork to a separate cloud project: delete `summer-cloud.json` and run `summer cloud init` to create a new binding. Because storage is content-addressed and dedupes, the fork is nearly free in storage.
+- **Per-file cap is 4.995 GiB.** A single file larger than that is rejected with a clear error. There is no multipart path in v1.
+- **No resumable uploads.** A dropped connection mid-upload on a multi-GiB file restarts that file from zero. For large pushes, prefer a stable connection.
+- **No locking or presence.** Two people editing the same binary at once produces a conflict (recoverable, never lost), not a lock.
+- **Git branch switches read as edits.** Switching git branches on a cloud-synced project looks like local edits to Cloud and will push as such. Guidance: sync before and after branch operations, or keep cloud projects on one branch.
+- **Storage rides the plan tiers.** Free, Pro, Pro Plus, and Ultra each have a storage cap. A push past the cap returns a quota error pointing at the upgrade path; surface that to the user rather than retrying.
+
+## Hard rule: drive everything through the CLI or MCP
+
+Never hand-edit anything under `.summer/local/cloud/` (base, journal, hash cache, staging, checkpoints, conflict sets). That state is the integrity model; editing it by hand can corrupt the 3-way base and cause data loss on the next sync. The only file you ever touch directly is the tiny git-tracked `summer-cloud.json` binding, and even then only to remove `pinnedVersion` for a read-only checkout or to delete it when intentionally forking. Every real operation goes through `summer cloud ...` or the `summer_cloud_*` tools.
+
+## Typical flows
+
+- **Move to a second machine.** On machine A: `summer cloud init`, then `summer cloud push`. Commit `summer-cloud.json` so it travels with git, or share the project id. On machine B: get the project (git clone or copy), then `summer cloud pull`. If both sides already had files, take the bootstrap choice.
+- **Back up big assets before a bulk import.** `summer cloud status`, then `summer cloud push`. The resulting version is the restore point.
+- **Recover from a bad change.** `summer cloud checkpoints` (or `summer cloud status` for cloud versions), then `summer cloud restore --checkpoint <stamp>` for local-only work or `--version N` for a pushed version. Remove any extra files the restore lists.
+
+## Fallback
+
+If the MCP tools are unavailable, run the `summer cloud ...` CLI commands directly. The CLI and MCP tools are one to one and share the same engine. If neither is available, the project is not set up; point the user at `summer login` (Cloud auth comes from the login token) and `summer cloud init`.
+
+## Collaborative protocol
+
+Push and pull move bytes and can replace files. Always run `summer cloud status` and say what will move before you push or pull: "Push will upload 4 files and delete 0. OK to push?" For any gated deletion, state the exact count and get explicit confirmation before setting `confirmDeletes`.

package/skills/scripting-patterns/gdscript-patterns/SKILL.md

@@ -145,6 +145,6 @@ Note the field name difference too: `LabelSettings.outline_color` (Label 2D) vs
 
 ## Scene Integration
 
-When the AI adds a node with Summer MCP tools and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist first. Create or edit `.gd` files with the host agent's normal file-editing tools, then use Summer MCP only to attach the script and connect scene signals.
+When the AI adds a node with Summer MCP tools and attaches a script, the script path is set via `summer_set_prop(path, "script", "res://path/to/script.gd")`. The script file must exist first. Create it with guarded `summer_write_file` or edit it with `summer_replace_text`, then attach the script and connect scene signals.
 
 For signal connections, the receiver must have the handler method. Create the script with the method stub before calling `summer_connect_signal`.

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.