summer-engine 3.8.0 → 4.2.0

package/library/skills/character-movement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: character-movement
-description: "Player controllers for 2D and 3D, plus the canonical third-person controller for Summer humanoid packages: movement owns translation, clips follow state."
+description: "Player controllers for 2D and 3D, plus the standard third-person controller for Summer humanoids."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: character-controllers
@@ -248,7 +248,7 @@ func _physics_process(_delta: float) -> void:
 
 Survivors-style games with 200+ agents: enemies are `Area2D` moved with
 `position += dir * speed * delta`, NOT physics bodies. See the `make-game`
-skill's `../make-game/references/2d-survivors.md`. The PLAYER stays a CharacterBody2D.
+skill's survivors blueprint (`summer_docs_read` id `skill/make-game/references/2d-survivors.md`). The PLAYER stays a CharacterBody2D.
 
 ## 3D controller (first + third person)
 
@@ -287,7 +287,7 @@ func _physics_process(delta: float) -> void:
 When the player visual is a Summer character package:
 
 1. Produce or import the package first — it comes from the shared character
-   pipeline (`character-model`; `summer_generate_3d` with rigging and animations)
+   pipeline (`character-model`; `assets.generate_3d` with `rig` and `animationNames`)
    and carries `character.tscn` plus its `character.json` manifest. Instantiate
    `character.tscn`; for clip wiring without this controller see
    `character-animation-wiring`.
@@ -324,3 +324,27 @@ Do not put player controls into the generation pipeline or generic character imp
 - Diagonal speed-up = you forgot to normalize the input vector.
 - Mouse captured with no release traps the user. Always pair
   `Input.MOUSE_MODE_CAPTURED` with a `ui_cancel` handler that sets it VISIBLE.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_3d` | `summer assets generate-3d` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_batch` | `summer engine batch` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_input_map_bind` | `summer engine input-map-bind` |
+| `summer_play` | `summer engine play` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_replace_text` | `summer engine replace-text` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_stop` | `summer engine stop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/character-movement/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/character-movement
 kind: skill
 version: 1.2.1
-summary: "Player controllers for 2D and 3D, plus the canonical third-person controller for Summer humanoid packages: movement owns translation, clips follow state."
+summary: "Player controllers for 2D and 3D, plus the standard third-person controller for Summer humanoids."
 use_when:
   - building or fixing player movement — gravity, collision, side-scroller, top-down, or 3D walk
   - wiring an imported Summer character package (character.tscn) as the playable third-person player

package/library/skills/character-portrait/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: character-portrait
-description: "Generate a single polished character bust for dialogue UI, character select, lore cards, or codex entries. One character, locked composition, VN-style."
+description: "Generate one polished character bust for dialogue UI, character select, lore cards or codex entries."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_search_assets summer_import_from_url summer_set_prop summer_set_resource_property
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_search summer_import_from_url summer_set_prop summer_set_resource_property summer_call
 paths: ["assets/**", "art/portraits/**", "ui/portraits/**"]
 ---
 
@@ -62,14 +62,14 @@ background: muted painterly gradient, dark teal to deep brown, no scene detail
 style: semi-realistic painterly, soft edges, oil-painting feel
 ```
 
-Note there is no aspect line. `summer_generate_image` has no size or aspect argument — every MCP image comes back at the server's 1:1 default. Bust framing reads fine square; if the cast needs true portrait framing, generate in the Summer dashboard (which exposes aspect ratio) and bring the results back with `summer_import_from_url`, or crop after. Whichever you pick, do it for the *whole* cast — mixed aspect is as visible as mixed lighting.
+Note there is no aspect line in the anchor: framing is the `aspectRatio` argument of `assets.generate_image`, not prompt text. Bust framing reads fine square (`1:1`, the default); true portrait framing is `aspectRatio: "3:4"`. Whichever you pick, use it for the *whole* cast — mixed aspect is as visible as mixed lighting.
 
 Every subsequent portrait in this cast appends the anchor to the prompt verbatim. **Do not edit the anchor mid-cast** unless the user explicitly says "I want the new ones to look different."
 
 ### 2. Search for an existing portrait
 
 ```
-summer_search_assets(query="<character name> portrait", assetType="2d_image", source="all")
+assets.search({ query: "<character name> portrait", assetType: "2d_image", scope: "all" })
 ```
 
 Reuse beats regenerate. If the user wants to iterate on an existing one, pull its URL and pass it as `referenceImageUrl` for img2img.
@@ -89,16 +89,17 @@ The character description should include: identity (age, build, hair, distinctiv
 > Generating Aria the witch portrait — 1 image (uses credits), model nano-banana-2, anchor locked from `.summer/portrait-anchor.md`. OK?
 
 ```
-summer_generate_image(
-  prompt="Aria, young witch, mid-twenties, pale skin, long black hair with silver streak, sharp green eyes, half-smile, wearing dark indigo robes with silver embroidery, raven on shoulder. <anchor verbatim>",
-  model="nano-banana-2",
-  style="none"
-)
+assets.generate_image({
+  prompt: "Aria, young witch, mid-twenties, pale skin, long black hair with silver streak, sharp green eyes, half-smile, wearing dark indigo robes with silver embroidery, raven on shoulder. <anchor verbatim>",
+  model: "nano-banana-2",
+  style: "none",
+  aspectRatio: "<the cast's framing>"
+})
 ```
 
 `style: "none"` because the anchor's "semi-realistic painterly" already specifies style. Only `cartoon` and `anime` append anything to the prompt, and `realistic` / `none` append nothing — any other value is coerced to `none`. So the preset cannot "fight" a painterly anchor; it just does nothing either way, and every bit of the look has to be in the prompt.
 
-`options={ image_size: ... }` is dropped without an error — see the anchor note above.
+There is no `options` object: shape and size are `aspectRatio`, `width` and `height`.
 
 ### 5. Import and wire into UI
 
@@ -129,12 +130,12 @@ For character-select with multiple portraits, name files consistently: `aria.png
 If the user wants the portrait tweaked ("smaller smile", "darker robes"), use img2img with the existing image as `referenceImageUrl`. Preserves identity and lighting.
 
 ```
-summer_generate_image(
-  prompt="<original prompt> with a smaller, more subtle smile",
-  referenceImageUrl="<previous fileUrl>",
-  model="nano-banana-2",
-  style="none"
-)
+assets.generate_image({
+  prompt: "<original prompt> with a smaller, more subtle smile",
+  referenceImageUrl: "<previous fileUrl>",
+  model: "nano-banana-2",
+  style: "none"
+})
 ```
 
 ## Prompt patterns
@@ -155,7 +156,7 @@ summer_generate_image(
 | `cool warrior portrait` | No identity, no anchor. Returns generic stock art. |
 | `the witch but make her sad` (no img2img ref) | Without `referenceImageUrl`, you get a *different* witch who is sad. Identity drift. |
 | Anchor inconsistent across cast | Each portrait looks like a different game. The cast doesn't read as a cast. |
-| `full body portrait` | "Portrait" implies bust. If you want full body, say so explicitly in the prompt — there is no size argument to reframe with, and full body in a square frame is a different asset class anyway; consider `concept-art` or the 3D pipeline. |
+| `full body portrait` | "Portrait" implies bust. If you want full body, say so explicitly in the prompt and use a tall `aspectRatio` (`2:3`) — full body is a different asset class anyway; consider `concept-art` or the 3D pipeline. |
 | `transparent background` for a painterly portrait | Painterly + transparent fails on most models. Use a flat or gradient background, then alpha-cut in an editor if you must. |
 
 ## Anti-patterns
@@ -173,12 +174,16 @@ summer_generate_image(
 - **Cast of 12+ characters.** Anchor discipline gets harder as fatigue sets in. Print the anchor as a header in your generation script and don't write any prompt without it.
 - **User wants the portrait to "read at small size" (32×32 in a portrait list).** That's pixel-art territory; route to `pixel-art`.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-4 and 6, and skip step 5 (import and UI wiring). Pass `out` with the person's folder so the PNG lands there (the `summer-assets` skill says how), and tell them the path.
+
 ## Fallback (no MCP)
 
 Print the prompt and the call:
 
 ```
-summer_generate_image(prompt="<character + anchor>", model="nano-banana-2", style="none")
+assets.generate_image({ prompt: "<character + anchor>", model: "nano-banana-2", style: "none" })
 ```
 
 Tell the user to run via the Summer dashboard, then `summer_import_from_url` the result to `res://ui/portraits/<name>.png`.
@@ -198,4 +203,19 @@ After the portrait is wired:
 - `concept-art` — explore the look first if not yet locked.
 - `asset-strategy` — meta-router and the 3D pipeline.
 - `scene-composition` — wiring the portrait into a dialogue UI scene.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_image` parameter schema.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_image`.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_image`, `summer_assets_generate_image` | `summer assets generate-image` |
+| `summer_assets_search` | `summer assets search` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+<!-- /shell-commands -->

package/library/skills/character-portrait/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/character-portrait
 kind: skill
 version: 1.0.4
-summary: Generate a single polished character bust for dialogue UI, character select, lore cards, or codex entries. One character, locked composition, VN-style.
+summary: "Generate one polished character bust for dialogue UI, character select, lore cards or codex entries."
 use_when:
   - generating a single polished bust/portrait of a character for dialogue UI, character-select screens, lore cards, or codex entries
   - a dialogue box, party roster, or codex entry needs one consistent face for a named character

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

@@ -1,11 +1,11 @@
 ---
 name: cinematic-cutscene
-description: "Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer."
+description: "Generate a non-interactive cutscene: a reference-locked 5-10s video shot with optional voiced dialogue."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video
 user-invocable: true
-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
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_video summer_jobs_wait summer_assets_generate_image summer_assets_generate_audio summer_assets_search summer_import_from_url summer_add_node summer_set_prop summer_call
 paths: ["assets/video/**", "cinematics/**", "trailers/**"]
 ---
 
@@ -30,7 +30,7 @@ If the user wants 5 seconds of marketing footage, that's `trailer-shot`. If they
 - "Looping splash screen background" — `animated-loop`.
 - "Animated logo backdrop on the title screen" — `animated-loop`.
 - Real-time in-engine cinematic with the actual gameplay characters and camera — that's an AnimationPlayer job, not generated video. Route to `scene-composition`.
-- Voice-only narration over a static image — generate the dialogue with `summer_generate_audio` and use a static `TextureRect`, no video needed.
+- Voice-only narration over a static image — generate the dialogue with `assets.generate_audio` and use a static `TextureRect`, no video needed.
 
 ## Steps
 
@@ -38,10 +38,10 @@ If the user wants 5 seconds of marketing footage, that's `trailer-shot`. If they
 
 ```
 Read .summer/GameSoul.md
-summer_search_assets(query="<character name> reference", assetType="2d_image", source="all")
+assets.search({ query: "<character name> reference", assetType: "2d_image", scope: "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.
+`assets.search` 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, search your own assets with `assets.search({ query: "cutscene", scope: "mine" })` 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.
 
@@ -51,32 +51,32 @@ Cutscenes longer than 10 seconds are **multiple shots**, not one take. Ask the u
 
 > Want this as one 10s shot, or three shots (e.g. wide → close on face → reaction)? Each shot is 5-10s. I'll generate a reference image once, then image-to-video each shot off of it.
 
-Default if the user is vague: **3 shots, 5s each, on kling**. Confirm before spending credits.
+Default if the user is vague: **3 shots, 5s each, on kling**. Confirm before spending credits: `dryRun: true` on a shot's call returns its `estimate` (credits, balance, enough) and renders nothing.
 
 ### 3. Lock the look — generate a reference image first
 
-For any character or hero scene, generate a reference still with `summer_generate_image` *before* generating video. This still drives `imageUrl` on every subsequent shot, so the character is consistent across cuts.
+For any character or hero scene, generate a reference still with `assets.generate_image` *before* generating video. This still drives `imageUrl` on every subsequent shot, so the character is consistent across cuts.
 
 ```
-summer_generate_image(
-  prompt="<subject>, <setting>, cinematic lighting, film still, wide 16:9 framing, <art style from GameSoul.md>",
-  model="nano-banana-2"
-)
+assets.generate_image({
+  prompt: "<subject>, <setting>, cinematic lighting, film still, wide framing, <art style from GameSoul.md>",
+  model: "nano-banana-2",
+  aspectRatio: "16:9"
+})
 ```
 
-`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.
+Set `aspectRatio` to the cutscene's framing (`16:9`, or `9:16` for mobile); `width` and `height` ask for a minimum size. 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 still costs far less than regenerating a video.
 
 ### 4. Pick the model
 
-**This skill always passes `imageUrl`, which puts every call on the image-to-video route — and that route only accepts three models.** `kling-turbo` and `veo3` are text-to-video only; asking for either with an `imageUrl` set is a 400 `invalid_model`, not a silent downgrade.
+**This skill always passes `imageUrl`, which puts every call on the image-to-video route.** `kling-turbo` and `veo3` are text-to-video only; asking for either with an `imageUrl` set is a 400 `invalid_model`, not a silent downgrade.
 
 | Model | i2v? | Speed | When |
 |---|---|---|---|
 | `ltx` | yes | ~30s | Iteration, blocking shots, B-roll, throwaway tests |
 | `kling` | yes | 2-4 min | Hero shots, character cutscenes, anything the player will sit and watch |
-| `minimax` | yes | 2-3 min | Stylized / anime-leaning content; better at non-photoreal looks than kling |
 | `kling-turbo` | **no** | 1-2 min | Text-to-video only — usable only if you drop the reference image |
 | `veo3` | **no** | 3-5 min | Text-to-video only — usable only if you drop the reference image |
 
@@ -85,24 +85,24 @@ Default policy: **`ltx` first** to validate the prompt and shot framing. If it l
 ### 5. Generate each shot
 
 ```
-summer_generate_video(
-  prompt="<subject does <action>, <camera move>, <lighting>, cinematic, 16mm film grain>",
-  model="kling",
-  imageUrl="<reference image fileUrl from step 3>",
-  duration=5,
-  aspectRatio="16:9"
-)
+assets.generate_video({
+  prompt: "<subject does <action>, <camera move>, <lighting>, cinematic, 16mm film grain>",
+  model: "kling",
+  imageUrl: "<reference image fileUrl from step 3>",
+  duration: 5,
+  aspectRatio: "16:9"
+})
 ```
 
-`duration` accepts **only 5 or 10** — the server coerces anything else to 5. There is no 3s, 4s, 7s or 8s clip.
+On `ltx` and `kling`, `duration` is 5 or 10 — anything else renders 5. The newer models in the `model` list render their nearest supported length.
 
-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:
+`assets.generate_video` always answers at once with a job — `{ status: "running", job: { id } }` and **no `fileUrl`**; the clip is rendered by a background worker. Wait for it:
 
 ```
-summer_check_job(jobId="<jobId from the generate call>")
+jobs.wait({ jobId: "<job.id from the generate call>", timeoutSeconds: 50 })
 ```
 
-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.
+Call `jobs.wait` again until `finished` is true. Only a finished job with state `done` has the asset and URL in its `result`. 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.
 
@@ -112,14 +112,14 @@ When the job completes, show the user the URL and ask:
 
 ### 6. Generate dialogue audio (if the scene has dialogue)
 
-Cutscene dialogue is TTS, not in the video model. The video model can render mouth motion that *looks* like talking, but the audio comes from `summer_generate_audio`. Generate it separately and an AnimationPlayer or your `cinematics/` controller scene syncs them.
+Cutscene dialogue is TTS, not in the video model. The video model can render mouth motion that *looks* like talking, but the audio comes from `assets.generate_audio`. Generate it separately and an AnimationPlayer or your `cinematics/` controller scene syncs them.
 
 ```
-summer_generate_audio(
-  capability="text_to_speech",
-  text="They'll come for you at dawn. Run while you can.",
-  voiceId="<from audio bible — see voice-line>"
-)
+assets.generate_audio({
+  capability: "text_to_speech",
+  text: "They'll come for you at dawn. Run while you can.",
+  voiceId: "<from audio bible — see voice-line>"
+})
 ```
 
 Lip-sync caveat: if the video shows the character clearly mouthing words and the audio is a different cadence, viewers notice. Either (a) keep the camera off the character's face during dialogue, (b) accept the asynchrony for a stylized look, or (c) use `veo3` and prompt the dialogue text directly into the video prompt for synced motion.
@@ -146,19 +146,27 @@ Then:
 summer_import_from_url(url="<hosted .ogv url>", path="res://assets/video/cinematics/intro_shot_01.ogv")
 ```
 
-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`:
+Build a controller scene at `res://cinematics/Intro.tscn`: create it, then build its nodes in one script (`scenePath` names the new scene; the editor's open tab comes back afterwards):
 
 ```
-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")
+summer_create_scene(path="res://cinematics/Intro.tscn", rootName="Intro", rootType="Control")
+summer_run_script(scenePath="res://cinematics/Intro.tscn", source="""
+func run(ctx):
+    var video = ctx.add_node("VideoStreamPlayer", "Video", null, {
+        "stream": load("res://assets/video/cinematics/intro_shot_01.ogv"),
+        "autoplay": true,
+        "expand": true,
+    })
+    video.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+    var fade = ctx.add_node("ColorRect", "Fade", null, {"color": Color(0, 0, 0, 1)})   # black, alpha 1.0 -> 0.0
+    fade.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+    fade.mouse_filter = Control.MOUSE_FILTER_IGNORE
+    ctx.save_scene()
+""")
 ```
 
+`Fade` comes after `Video` in the tree, so it draws on top of it.
+
 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.
 
 For dialogue, add an `AudioStreamPlayer` sibling with the TTS clip and call `play()` in `_ready` after a small delay matching where the line lands in the video.
@@ -176,7 +184,7 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 | Action beat (village burns) | `kling` | `medium wide of a thatched village engulfed in flames at night, embers rising, silhouettes running through smoke, hand-held camera, cinematic` | 5s |
 | Ending shot (hero walks away) | `kling` | `low wide shot of a cloaked figure walking away across a blasted plain at sunset, slow truck-back, golden hour, dust on the wind` | 5s |
 | Throwaway iteration / blocking | `ltx` | same prompt as above | 5s |
-| Anime / stylized cutscene | `minimax` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | 5s |
+| Anime / stylized cutscene | `kling` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | 5s |
 
 ### Bad prompts and why
 
@@ -191,23 +199,27 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 ## Anti-patterns
 
 - **Generating a 10s shot when you should chain two 5s shots.** Identity, hand consistency, and physics drift every additional second past ~6s. Two 5s shots cut together look better and cost the same.
-- **Skipping the reference image.** Generating four character cutscenes from text prompts alone produces four different-looking people. Always lock the look with `summer_generate_image` first, then `imageUrl` every subsequent video call.
+- **Skipping the reference image.** Generating four character cutscenes from text prompts alone produces four different-looking people. Always lock the look with `assets.generate_image` first, then `imageUrl` every subsequent video call.
 - **Asking the video model to render dialogue without `veo3`.** `kling` and `ltx` will animate mouths but the motion does not match any audio. Use `veo3` if dialogue is on-camera, or keep the camera off the speaker.
 - **Using `kling` for blocking iterations.** Validate framing and prompt on the cheaper `ltx` first; move to `kling` once the composition lands.
 - **Putting the cutscene on a `VideoStreamPlayer` without a fade.** Cuts straight from gameplay to video are jarring. Always wrap in a `ColorRect` fade in/out.
-- **Treating `summer_generate_video` as synchronous.** It returns `{ queued: true, jobId }` and no URL. You must poll `summer_check_job` before there is anything to show or import.
+- **Treating `assets.generate_video` as finished.** It answers `{ status: "running", job }` and no URL. Wait with `jobs.wait` until the job is done 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.
+- **Asking `ltx` or `kling` for `duration: 3` or `duration: 8`.** On those two only 5 and 10 exist; anything else renders 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.** 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`.
+- **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: generate it with `aspectRatio: "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.
 - **Multi-shot continuity.** Use the same reference image as `imageUrl` across all shots. If lighting differs by shot, generate one reference per lighting setup, not one per shot.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-6 and skip step 7 (`VideoStreamPlayer`). Skip the soul-file read in step 1 when the project has no `.summer/` folder. Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format. Each shot is an MP4 and each dialogue line an audio file; the person cuts them together in their own editor.
+
 ## Fallback (no MCP)
 
 If the MCP server isn't running, the user can do all of this in the Summer dashboard:
@@ -237,4 +249,25 @@ Once the cutscene is generated and wired:
 - `music-track` — score the cutscene.
 - `concept-art` — generate the reference image axis if no character reference exists yet.
 - `character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_video`; `summer_search` returns its exact input.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_audio`, `summer_assets_generate_audio` | `summer assets generate-audio` |
+| `assets.generate_image`, `summer_assets_generate_image` | `summer assets generate-image` |
+| `assets.generate_video`, `summer_assets_generate_video` | `summer assets generate-video` |
+| `assets.search`, `summer_assets_search` | `summer assets search` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_create_scene` | `summer engine create-scene` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `jobs.wait`, `summer_jobs_wait` | `summer jobs wait` |
+| `summer_search` | `summer ops search "<what you want>"` |
+<!-- /shell-commands -->

package/library/skills/cinematic-cutscene/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/cinematic-cutscene
 kind: skill
 version: 1.0.4
-summary: Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer.
+summary: "Generate a non-interactive cutscene: a reference-locked 5-10s video shot with optional voiced dialogue."
 use_when:
   - generating a non-interactive cutscene clip — opening scene, story beat, character intro, ending
   - a story beat needs a short pre-rendered clip between gameplay sections — intro, transition, ending

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

@@ -1,6 +1,6 @@
 ---
 name: combat-basics
-description: "Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles."
+description: "Damage: hitbox and hurtbox Areas, a reusable Health component, damage signals, knockback, projectiles."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: gameplay-mechanics
@@ -157,3 +157,22 @@ Homing, piercing, AoE, and pooling many bullets are in this skill's
   spawn or find one enemy, press the attack action, `report()` the enemy's
   `Health.current` before and after. A static scene check cannot show that a
   hit registered.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_add_node` | `summer engine add-node` |
+| `summer_batch` | `summer engine batch` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_project_setting` | `summer engine project-setting` |
+| `summer_read_file` | `summer engine read-file` |
+| `summer_replace_text` | `summer engine replace-text` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/combat-basics/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/combat-basics
 kind: skill
 version: 1.0.0
-summary: "Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles."
+summary: "Damage: hitbox and hurtbox Areas, a reusable Health component, damage signals, knockback, projectiles."
 use_when:
   - adding attacks, health and damage, or enemies that can be hit and hit back
   - adding projectiles or bullets — homing, piercing, area-of-effect, or pooling hundreds of them

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

@@ -1,6 +1,6 @@
 ---
 name: compatibility-renderer-traps
-description: "Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors."
+description: "Make a Forward+ game look right on the Compatibility renderer: instance uniforms, MultiMesh, vertex colors."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting
@@ -76,3 +76,14 @@ you test it on both renderers. One path for both renderers means one set of bugs
 - `web-compatibility-look` (a finished look when the game only runs on Compatibility, as on the web)
 - `3d-lighting` (lighting profiles)
 - `bounded-engine-runs` (safe offscreen capture runs)
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_project_setting` | `summer engine project-setting` |
+<!-- /shell-commands -->

package/library/skills/compatibility-renderer-traps/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/compatibility-renderer-traps
 kind: skill
 version: 1.0.0
-summary: "Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors."
+summary: "Make a Forward+ game look right on the Compatibility renderer: instance uniforms, MultiMesh, vertex colors."
 use_when:
   - a game must run on phones or weak GPUs that may use the Compatibility or Mobile renderer
   - objects render black, pale or stop animating on one renderer but not another

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

@@ -1,11 +1,11 @@
 ---
 name: concept-art
-description: "Explore art direction with 3-4 rough concept variants of a character, environment, or prop to pick a vibe before committing to a final asset."
+description: "Explore art direction with 3-4 rough concept variants of a character, environment or prop."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_search_assets summer_import_from_url
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_search summer_import_from_url summer_call
 paths: ["assets/**", "art/**", "concepts/**"]
 ---
 
@@ -44,7 +44,7 @@ If "final" → hand off to `character-portrait`. If "explore" → continue.
 ### 2. Search for prior concepts
 
 ```
-summer_search_assets(query="<subject> concept", assetType="2d_image", source="all")
+assets.search({ query: "<subject> concept", assetType: "2d_image", scope: "all" })
 ```
 
 If something already exists, ask if the user wants to riff on it (img2img via `referenceImageUrl`) or start fresh.
@@ -68,16 +68,16 @@ State the axis to the user before generating: "I'll vary on **stylization** —
 Issue 3-4 calls in parallel, one per variant. Use the same subject phrasing across all four; only the style-modifier changes.
 
 ```
-summer_generate_image(
-  prompt="<subject>. <axis variant 1>. concept art, evocative, rough painterly, atmospheric lighting, wide cinematic framing",
-  model="nano-banana-2",
-  style="none"
-)
+assets.generate_image({
+  prompt: "<subject>. <axis variant 1>. concept art, evocative, rough painterly, atmospheric lighting, wide cinematic framing",
+  model: "nano-banana-2",
+  style: "none"
+})
 ```
 
 `style: "none"` is intentional: only `cartoon` and `anime` append anything to the prompt, `realistic` and `none` append nothing, and any other value is coerced to `none`. So the preset cannot override the prompt's stylistic direction — it just contributes nothing, which is what concept art wants. All four variants' divergence has to come from the prompt.
 
-For a shape other than square, pass `aspectRatio` (`"16:9"`, `"9:16"`, ...) or `width` + `height`; the result reports the real width and height and the model that ran. Exploration images are thrown away, so square is usually fine. Background removal is the top-level `removeBackground` argument, not an `options` key.
+For a shape other than square, pass `aspectRatio` (`"16:9"`, `"9:16"`, ...) or `width` + `height`; the result reports the real width and height and the model that ran. Exploration images are thrown away, so square is usually fine. Background removal is the `removeBackground` argument (there is no `options` object). Four variants are four charges: `dryRun: true` on one call shows its credits.
 
 ### 5. Present the batch
 
@@ -124,13 +124,17 @@ The structure: **subject + axis variant + "concept art" + lighting/atmosphere**.
 - **Subject is a fully described scene, not an asset.** You're producing key art, not asset reference. Pass `aspectRatio: "16:9"` (or `width: 1920, height: 1080` for store key art) and bias toward atmospheric.
 - **User wants the final to be 3D.** After they pick a direction, route to `asset-strategy` — concept-art images are not 3D-ready references (they have backgrounds, scene context, dramatic lighting baked in). The 3D pipeline needs its own clean white-background reference.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), every step works. Pass `out` with the person's folder so the batch lands there (the `summer-assets` skill says how), and skip `summer_import_from_url`.
+
 ## Fallback (no MCP)
 
 Print the 4 prompts and the call for each:
 
 ```
-summer_generate_image(prompt="<variant 1>", model="nano-banana-2", style="none")
-summer_generate_image(prompt="<variant 2>", ...)
+assets.generate_image({ prompt: "<variant 1>", model: "nano-banana-2", style: "none" })
+assets.generate_image({ prompt: "<variant 2>", ... })
 ...
 ```
 
@@ -150,4 +154,17 @@ Once the user picks a direction:
 
 - `asset-strategy` — meta-router that delegates here vs other 2d-assets skills.
 - `character-portrait` — the polished single-image counterpart.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_image` parameter schema.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_image`.
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `assets.generate_image`, `summer_assets_generate_image` | `summer assets generate-image` |
+| `summer_assets_search` | `summer assets search` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+<!-- /shell-commands -->