summer-engine 3.8.0 → 4.0.0

package/library/skills/summer-apps-design/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/summer-apps-design
 kind: skill
 version: 0.1.0
-summary: How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist.
+summary: "How a Summer App should look: layout, Summer UI kit components, tables, charts, states, pre-ship check."
 use_when:
   - building or changing the UI of a Summer App (agent-built team tool inside Summer Studio)
   - an app looks generic, cluttered or off-brand

package/library/skills/summer-assets/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: summer-assets
+description: "Make game assets with Summer without Summer Engine: find, generate and download 3D models, images, audio and video for any engine or web app."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
+category: _meta
+user-invocable: false
+---
+
+# Summer assets without the engine
+
+Use this skill when the session has the Summer **assets profile**: the generation and asset library tools are there, the Summer Engine tools are not (no `summer_get_project_context`, `summer_add_node`, `summer_play` or `summer_screenshot`). The person wants files for their own engine or web app. You deliver files, not scenes.
+
+A call written `area.action({...})` is one operation: use the tool `summer_area_action` when your client lists it, else `summer_call({ op: "area.action", input: {...} })`. `summer_search` finds any operation and its exact input.
+
+## What this session has
+
+| Job | Operations |
+|---|---|
+| Find how to do it | `summer_docs_search`, then `summer_docs_read` the skill |
+| Find an existing asset | `assets.search({ query, scope })` (`scope`: `library` (default), `mine` for the person's own, `all`), then `assets.get({ assetId })` |
+| Make a new asset | `assets.generate_image`, `assets.generate_3d`, `assets.generate_audio`, `assets.generate_sfx_choices` with `assets.choices`, `assets.generate_video`, `assets.generate_motion`, `assets.slice_sheet` |
+| Wait for a job | `jobs.wait({ jobId, timeoutSeconds: 50 })` with the `job.id` a generation returned |
+| Get the file | `out` on the generate call, `jobs.wait` or `assets.get`: the file is saved there and the answer gives `localPath` |
+| More generators | `makers.<tool>` (for example `makers.npc_voice`, `makers.trailer_forge`); `summer_search` lists them |
+
+## The loop
+
+1. **Ask what the asset is for**, once, in one message: the engine or app, the file format, the size or scale, the style, how many.
+2. **Reuse first.** `assets.search({ scope: "mine" })`, then `assets.search({ query, scope: "all" })`. Generate only when nothing fits.
+3. **Read the asset's skill**: sound effect `sound-effect`, music `music-track`, ambience `ambient-bed`, voice `voice-line`, image or style `concept-art`, UI `ui-graphics`, texture `tileable-texture`, sprites `sprite-sheet` or `pixel-art`, sky `skybox-panorama`, 3D prop `prop-model`, character `character-model`, creature or plant `organic-model`, vehicle `vehicle-model`, modular kit `environment-kit`, animation `generate-motion`, video `trailer-shot`. Follow it up to the point where the asset exists. Its **Without Summer Engine** section says where to stop: skip every step that imports the asset into a project or adds nodes to a scene.
+4. **Confirm before you spend.** Generation uses the person's Summer credits. `dryRun: true` on the generate call returns the estimate (`credits`, `balance`, `enough`) and makes nothing. Say what you will make and how many versions, and wait for a yes.
+5. **Generate, then wait.** 3D, video and animation answer at once with `{ status: "running", job }`: call `jobs.wait` until `finished` is true. Never continue on a running job.
+6. **Use the returned id.** `assets.get` with the asset id the finished job's `result` holds. Do not search by name right after a generation.
+7. **Check it.** Look at the preview image or thumbnail you received. For audio, the person listens. Describe only what you actually received.
+8. **Hand it over.** Pass `out` with the folder the person named (or a file path): on the generate call, on `jobs.wait` for 3D, video and animation, or on `assets.get` for an asset you already have. The file is saved there and the answer gives `localPath`. Without `out`, a file made in a game project lands in its asset folder (Godot `assets/`, Unity `Assets/Summer`, Unreal `Content/Summer`, three.js `public/assets`). Tell the person the path and format. Connected only to Summer's hosted server, there is no `out`: download `downloadUrl` from `assets.get` with your own shell.
+
+## Formats
+
+Each asset is a normal file in the person's Summer library: GLB for 3D models, PNG, JPG or WebP for images, MP3 or WAV for audio, MP4 for video. GLB is Y up. Generated models are not at real-world size: give the person the target size (a door about 2 m, a person about 1.7 m). Tell them if their engine needs a conversion step, and let them choose the tool for it.
+
+## Done means
+
+- The job finished without an error.
+- You saw the preview, or the person heard the sound.
+- The file is where the person asked, and you told them the path and format.
+
+## Pitfalls
+
+| Pitfall | Do this instead |
+|---|---|
+| Following an asset skill into its scene steps (`summer_import_asset_by_id`, `summer_add_node`, `AudioStreamPlayer`, `MeshInstance3D`) | Stop at the file. Those tools are not in this session. |
+| Generating before you checked the person's own assets | `assets.search({ scope: "mine" })` first |
+| Generating the same asset again to get the file | `assets.get` with `out` on the asset you already have |
+| Telling the person the asset looks right without a preview | Say what you received, or that no preview came back |
+| The person wants a whole game, not assets | Say that this needs Summer Engine and the full setup: `npx -y summer-engine@latest setup <agent> --yes` |

package/library/skills/summer-assets/resource.yaml

@@ -0,0 +1,34 @@
+id: skill/summer-assets
+kind: skill
+version: 1.0.0
+summary: "Make game assets with Summer without Summer Engine: find, generate and download 3D models, images, audio and video for any engine or web app."
+use_when:
+  - starting a session that has the Summer assets profile (generation tools, no engine tools)
+  - the person wants assets for their own engine or web app, not a game built in Summer Engine
+  - an asset skill ends with Summer Engine steps that this session cannot run
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - agent-workflow
+  modalities:
+    - 3d-models
+    - images
+    - audio
+    - video
+related:
+  tools:
+    - tool/search-assets
+    - tool/list-my-assets
+    - tool/check-job
+    - tool/get-asset
+    - tool/get-asset-download-url
+  skills:
+    - skill/asset-strategy
+    - skill/sound-effect
+    - skill/prop-model
+    - skill/concept-art
+source: official
+license: MIT
+status: stable

package/library/skills/summer-store/SKILL.md

@@ -42,7 +42,7 @@ proves nothing.
 | Local Play | `unavailable` | Works from a fixture: empty unless `.summer/test-users.json` lists item templates (step 5) |
 | Guests, older Summer apps | Readiness reports `unavailable` | Readiness reports `unavailable` |
 
-Items and offers are created in your game's Studio pages (`summer_open` target
+Items and offers are created in your game's Studio pages (`studio.open` target
 `game`). Code never creates items.
 
 This skill extends the Courtyard game from `multiplayer-project` and

package/library/skills/text-to-motion/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: text-to-motion
-description: "Custom 2-second animation clips from text prompts on any of the user's own rigged models — humanoids, animals, creatures, cartoon plants, props."
+description: "Make custom 2-second animation clips from text on the user's own rigged models: people, animals, props."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
 user-invocable: false
-allowed-tools: Read summer_list_my_assets summer_generate_motion summer_check_job summer_get_asset summer_import_asset_by_id
+allowed-tools: Read summer_assets_search summer_assets_generate_motion summer_jobs_wait summer_assets_get summer_import_asset_by_id summer_call
 ---
 
 # Text to Motion
@@ -14,8 +14,8 @@ Summer-hosted text-to-motion turns a text prompt into a 2-second (60 frames) ske
 clip for the user's **own** rigged model. One model covers every skeleton with 5-70 bones:
 humanoids, animals, creatures, cartoon plants, turrets, props.
 
-The tool is `summer_generate_motion` with `backend: "text-to-motion"`. It returns a
-`jobId`; poll `summer_check_job`. The finished job's `result.assets` lists one `animation`
+The operation is `assets.generate_motion` with `backend: "text-to-motion"`. It answers at
+once with a job; `jobs.wait` follows it. The finished job's `result.assets` lists one `animation`
 asset per prompt x take (`id`, `fileUrl`, `animationName`, `prompt`, `take`); each is a GLB
 of the whole model carrying one animation named after its prompt.
 
@@ -37,28 +37,28 @@ doesn't have that move", any animation request for a non-humanoid rig.
 ## The order
 
 1. **Confirm the rig.** The asset must be the user's own `3d_model` GLB/FBX with one
-   skinned armature and 5-70 bones (`summer_list_my_assets` / `summer_get_asset`). If it
+   skinned armature and 5-70 bones (`assets.search({ scope: "mine", assetType: "3d_model" })` / `assets.get`). If it
    is unrigged or has odd bone names, read `rigging-for-text-motion.md` in this directory.
-2. **Agree the clip list and cost.** Each prompt x take is one billed clip. Show the list
-   and the estimated cost and wait for the user's OK before submitting.
+2. **Agree the clip list and cost.** Each prompt x take is one billed clip. Run the call
+   below with `dryRun: true` first: it checks the rig and returns `estimate.credits`. Show
+   the list and the credits and wait for the user's OK before submitting.
 3. **Submit once.** Up to 8 prompts per call, `takes` 1-4. For rooted characters pass
    `lockJoints` with the base bones:
 
    ```
-   summer_generate_motion(
+   assets.generate_motion({
      rigAssetId: "<id>",
      backend: "text-to-motion",
      prompts: ["nods happily", "waves hello with the right leaf"],
      lockJoints: ["Hips", "Spine"],   // rooted flower; omit for characters that move
-     cfgScale: 5,                     // default 3; 5 for clearer gestures on stylized rigs
-     wait: false
-   )
+     cfgScale: 5                      // default 3; 5 for clearer gestures on stylized rigs
+   })
    ```
 
    Pass a stable `idempotencyKey` if you might retry the same request. Prompt writing and
    every control: `prompts-and-controls.md` in this directory.
-4. **Poll to completion.** `summer_check_job(jobId)`. A job takes about 1-2 minutes. Do not
-   resubmit while it runs. (With the default `wait: true` the tool polls for you.)
+4. **Wait for the job.** `jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 })`, again until
+   `finished` is true. A job takes about 1-2 minutes. Do not resubmit while it runs.
 5. **Review, then import.** Import the chosen clip assets with
    `summer_import_asset_by_id(assetId, parent, scenePath)`. Offer to regenerate weak takes
    with a rephrased prompt or a higher `cfgScale`; keep the good ones.
@@ -74,23 +74,30 @@ doesn't have that move", any animation request for a non-humanoid rig.
 - **Report failures with their code.** Job failures starting `text_motion:` (no skinned
   armature, too many or too few joints, multiple armatures, unknown lock joint) are input
   problems and the charge is refunded. Fix the rig or the request; do not retry unchanged.
-- **`backend_unavailable` means text-to-motion is not enabled on this server yet.** Fall
+- **A `backend` without `text-to-motion` means it is not enabled on this server yet.** Fall
   back to `generate-motion` (meshy-library) for humanoid clips and say so; do not retry.
 - **Do not promise facial animation, finger detail or lip sync.** The model animates the
   skeleton only; blendshapes stay untouched (`facial-and-lipsync` covers faces).
 
 ## Request errors
 
-| Code | Meaning | Do |
+Refusals answer the one error shape: `error.code` with one `next` step, and
+`error.details.was` naming the reason below.
+
+| `code` / `details.was` | Meaning | Do |
 | --- | --- | --- |
-| `backend_unavailable` | Server flag off | Use `generate-motion`; do not retry |
-| `prompt_required` | No prompt | Pass `prompt` or `prompts` (1-8, each 1-300 chars) |
-| `invalid_takes` | `takes` outside 1-4 | Fix and resubmit |
-| `invalid_cfg_scale` | `cfgScale` outside 1.5-8 | Fix and resubmit |
-| `invalid_lock_joints` | Bone names wrong | Use bone names that exist in the rig |
-| `rig_asset_not_found` | Not the caller's asset | Find the user's own asset id |
-| `rig_asset_invalid` | Not a rigged GLB/FBX `3d_model` | Rig it first |
-| `insufficient_credits` (402) | Not enough credits | Fewer prompts/takes, or the user tops up |
+| `invalid_input` on `backend` | Text-to-motion is off on this server (`backend` lists only `meshy-library`) | Use `generate-motion`; do not retry |
+| `invalid_input` on `prompts` | No prompt | Pass `prompts` (1-8, each 1-300 chars) |
+| `invalid_input` / `invalid_takes` | `takes` outside 1-4 | Fix and resubmit |
+| `invalid_input` / `invalid_cfg_scale` | `cfgScale` outside 1.5-8 | Fix and resubmit |
+| `invalid_input` / `invalid_lock_joints` | Bone names wrong | Use bone names that exist in the rig |
+| `not_found` / `rig_asset_not_found` | Not the caller's asset | Find the user's own asset id |
+| `invalid_input` / `rig_asset_invalid` | Not a rigged GLB/FBX `3d_model` | Rig it first |
+| `no_credits` | Not enough credits | Fewer prompts/takes, or the person adds credits (`next` has the link) |
+
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), follow the order up to the review in step 5 and skip the import. Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format. Keep the good takes and name each file after its prompt.
 
 ## Do not stop early
 

package/library/skills/text-to-motion/prompts-and-controls.md

@@ -11,19 +11,19 @@
 - Style words that map to motion work ("happily", "slowly", "tiredly"); story or
   appearance words do not.
 
-## Controls (`summer_generate_motion`, `backend: "text-to-motion"`)
+## Controls (`assets.generate_motion`, `backend: "text-to-motion"`)
 
 | Field | Default | Use |
 | --- | --- | --- |
-| `prompt` / `prompts` | - | One action, or 1-8 actions (each 1-300 chars); one clip each. Pass one of the two, not both |
+| `prompts` | - | 1-8 actions (each 1-300 chars); one clip each |
 | `takes` | 1 | 1-4; 2-3 when choosing a hero clip. Every take is billed |
 | `cfgScale` | 3 | 1.5-8; 5 for bigger, clearer gestures on stylized rigs; above 6 gets unstable |
 | `lockJoints` | none | Base bones of rooted characters (plants, turrets, statues), e.g. `["Hips","Spine"]` |
 | `idempotencyKey` | none | Stable key so a retried request is not billed twice |
-| `wait` | true | `false` returns the `jobId` at once; poll `summer_check_job` |
+| `dryRun` | false | `true` checks the rig and returns the `estimate` (credits) without making anything |
 
-Clip count = prompts x takes; each clip is billed. The queued response reports
-`clipCount` and `estimatedCost`.
+Clip count = prompts x takes; each clip is billed. The call answers with a job at once;
+`jobs.wait` follows it to the finished clips.
 
 ## Judging results
 

package/library/skills/text-to-motion/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/text-to-motion
 kind: skill
 version: 1.0.0
-summary: "Custom 2-second animation clips from text prompts on any of the user's own rigged models — humanoids, animals, creatures, cartoon plants, props."
+summary: "Make custom 2-second animation clips from text on the user's own rigged models: people, animals, props."
 use_when:
   - a custom action the curated motion library lacks — nod, bow, shrug, wave with a specific arm, an emotional gesture
   - animating a non-humanoid rig — a talking flower, animal, creature, turret or prop

package/library/skills/text-to-motion/rigging-for-text-motion.md

@@ -43,8 +43,8 @@ clips; keep the package's canonical idle/walk/run/jump from `generate-motion`.
 
 ## Rigging an unrigged mesh
 
-- Humanoid: the Summer auto-rig (`character-model`, `summer_generate_3d` with
-  `options.rig: true`).
+- Humanoid: the Summer auto-rig (`character-model`, `assets.generate_3d` with
+  `rig: true`).
 - Other body plans: rig in the user's own Blender (`fabricating-assets`) or offline
   (`skintokens-auto-rigging`), using the human bone names above where the body plan allows
   (stem as spine, leaves as arms).

package/library/skills/tileable-texture/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: tileable-texture
-description: "Generate a seamless tileable texture for walls, floors, or terrain — repeats cleanly on all four edges, wired as a StandardMaterial3D albedo."
+description: "Generate a seamless tileable texture for walls, floors or terrain, wired as a StandardMaterial3D albedo."
 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_resource_property summer_add_node summer_set_prop summer_inspect_node
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_search summer_import_from_url summer_set_resource_property summer_add_node summer_set_prop summer_inspect_node summer_call
 paths: ["assets/**", "art/textures/**", "materials/**"]
 ---
 
@@ -35,7 +35,7 @@ The hard part is "seamless." Most diffusion models violate edge continuity by de
 ### 1. Search for an existing texture
 
 ```
-summer_search_assets(query="<material> tileable", assetType="2d_image", source="all")
+assets.search({ query: "<material> tileable", assetType: "2d_image", scope: "all" })
 ```
 
 Texture libraries (AmbientCG, Polyhaven) often have free PBR sets that beat AI generation for realism. If the user wants photorealistic tiling, pause and suggest those.
@@ -59,16 +59,16 @@ The load-bearing phrases are:
 ### 3. Generate
 
 ```
-summer_generate_image(
-  prompt="weathered red brick wall, seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square format, photographic detail. No vanishing point, no directional shadow, no vignette, no single standout feature, no scene context, no sky, no sun.",
-  model="nano-banana-2",
-  style="realistic"
-)
+assets.generate_image({
+  prompt: "weathered red brick wall, seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square format, photographic detail. No vanishing point, no directional shadow, no vignette, no single standout feature, no scene context, no sky, no sun.",
+  model: "nano-banana-2",
+  style: "realistic"
+})
 ```
 
 Two things about the arguments:
 
-- **There is no `image_size` and no `negative_prompt`.** `summer_generate_image` takes only `prompt`, `model`, `style`, `referenceImageUrl`, `removeBackground` and `options`, and `options` only recognizes Nano Banana provider keys (`seed`, `outputFormat`, `safetyTolerance`, `syncMode`, `systemPrompt`, `limitGenerations`, `thinkingLevel`). Anything else is dropped without an error, so the call looks like it worked. Put the negations in the prompt text. Square is what you get regardless — MCP images come back at the server's 1:1 default, which is exactly what a tileable texture wants.
+- **There is no `image_size` and no `negative_prompt`.** `assets.generate_image` takes `prompt`, `model`, `style`, `aspectRatio`, `width`, `height`, `numImages`, `referenceImageUrl`, `removeBackground`, `seed` and `title`; a field it does not list does nothing, so the call looks like it worked. Put the negations in the prompt text. Leave `aspectRatio` at its `1:1` default, which is exactly what a tileable texture wants; for a larger tile, leave `model` out and pass `width` and `height`: a model that reaches the size is picked, or the answer names the models that can.
 - **`style: "realistic"` is a no-op.** Only `cartoon` and `anime` append anything to the prompt; `realistic` and `none` append nothing, and any other value is coerced to `none`. The photographic look has to come from the prompt (`photographic detail`). Switching to `"none"` for stylized work likewise changes nothing on its own — change the prompt.
 
 ### 4. Import to project
@@ -178,16 +178,20 @@ Then attach the same material with `uv1_scale` tuned to wall dimensions.
 - **User wants animated water / lava texture.** Generate a still tileable texture and use a `ShaderMaterial` with UV scrolling to animate. Don't try to generate frames.
 - **Visible seam after generation.** Run through GIMP `Filters → Map → Make Seamless` or open in Aseprite, set Tiled mode, paint over the seam manually. AI-generated tileables often need a 5-minute touch-up.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-3 and the seam check in step 5 by eye on the image (tile it 2x2 in an image viewer); skip step 4 and step 6 (import, wiring onto geometry). Pass `out` with the person's folder so the PNG lands there (the `summer-assets` skill says how), and tell them to set the texture to repeat.
+
 ## Fallback (no MCP)
 
 Print the call:
 
 ```
-summer_generate_image(
-  prompt="<material> seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square. No directional shadow, no single standout feature, no scene context.",
-  model="nano-banana-2",
-  style="realistic"
-)
+assets.generate_image({
+  prompt: "<material> seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square. No directional shadow, no single standout feature, no scene context.",
+  model: "nano-banana-2",
+  style: "realistic"
+})
 ```
 
 Tell the user to run via the Summer dashboard, then `summer_import_from_url` to `res://art/textures/<name>.png`, set `Repeat: Enabled`, and tune `uv1_scale` to physical size.
@@ -208,4 +212,4 @@ After the texture is wired:
 - `asset-strategy` — meta-router and 3D pipeline.
 - `skybox-panorama` — sky/environment counterpart.
 - `scene-composition` — applying textures to CSG and MeshInstance3D.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_image`.

package/library/skills/tileable-texture/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/tileable-texture
 kind: skill
 version: 1.0.4
-summary: Generate a seamless tileable texture for walls, floors, or terrain — repeats cleanly on all four edges, wired as a StandardMaterial3D albedo.
+summary: "Generate a seamless tileable texture for walls, floors or terrain, wired as a StandardMaterial3D albedo."
 use_when:
   - generating a seamless tileable texture for walls, floors, terrain, or ceilings — a square tile that repeats cleanly on all four edges
   - a wall, floor, or terrain material shows visible seams or repetition and needs a texture that tiles cleanly

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

@@ -1,11 +1,11 @@
 ---
 name: trailer-shot
-description: "Generate marketing or trailer footage — slow-mo combat, establishing shots, hero beats, splash screens, pitch-deck B-roll — max punch in 5-10 seconds."
+description: "Generate trailer footage: slow-mo combat, establishing shots, hero beats, splash screens, 5-10 seconds."
 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_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_search summer_import_from_url summer_add_node summer_set_prop summer_call
 paths: ["assets/video/**", "trailers/**", "marketing/**"]
 ---
 
@@ -55,25 +55,25 @@ State the archetype and composition out loud before generating: "I'll do a low-a
 For shots featuring a specific character, weapon, or environment, generate a reference still first and pass it as `imageUrl`. Without it, the boss in your trailer looks different from the boss in the game.
 
 ```
-summer_generate_image(
-  prompt="<subject>, <archetype-driven framing>, cinematic, dramatic lighting, film still, wide 16:9 framing",
-  model="nano-banana-2"
-)
+assets.generate_image({
+  prompt: "<subject>, <archetype-driven framing>, cinematic, dramatic lighting, film still, wide framing",
+  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 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.
+Set `aspectRatio` to the platform's framing (`16:9`, `9:16` for vertical social, `1:1` for square). 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
 
-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`.
+The available models depend on whether you pass `imageUrl`. With a reference image (step 2) the call goes to the image-to-video route; `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 | Speed | When |
 |---|---|---|---|---|
 | `kling` | yes | yes | 2-4 min | Default for trailer hero shots — best motion + composition |
 | `ltx` | yes | yes | ~30s | Cheapest. B-roll, throwaway tests, blocking the composition before committing |
-| `minimax` | yes | yes | 2-3 min | Anime / stylized trailer looks |
 | `kling-turbo` | yes | **no** | 1-2 min | Same look as kling, faster, slight quality dip — but you lose `imageUrl` |
 | `veo3` | yes | **no** | 3-5 min | Most expensive. Pitch deck for investors, the one shot that has to be perfect — but you lose `imageUrl` |
 
@@ -82,20 +82,20 @@ Default: **`ltx` first to block the composition, then `kling` for the final**. F
 ### 4. Generate the shot
 
 ```
-summer_generate_video(
-  prompt="<archetype framing>, <subject>, <action>, <camera move>, <lighting>, <film grain / lens / stylistic anchor>",
-  model="kling",
-  imageUrl="<optional reference URL from step 2>",
-  duration=5,
-  aspectRatio="16:9"
-)
+assets.generate_video({
+  prompt: "<archetype framing>, <subject>, <action>, <camera move>, <lighting>, <film grain / lens / stylistic anchor>",
+  model: "kling",
+  imageUrl: "<optional reference URL from step 2>",
+  duration: 5,
+  aspectRatio: "16:9"
+})
 ```
 
-`duration` accepts **only 5 or 10** — anything else is coerced to 5.
+On `ltx` and `kling`, `duration` is 5 or 10 — anything else renders 5. `dryRun: true` returns the shot's `estimate` (credits, balance, enough) without rendering.
 
-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.
+The call answers at once with `{ status: "running", job: { id } }` and **no URL**. Call `jobs.wait({ jobId: "<job.id>", timeoutSeconds: 50 })` until `finished` is true, 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.
+`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: generate the reference with that `aspectRatio`.
 
 ### 5. Review against trailer logic
 
@@ -150,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` | 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` | 5s |
 | Cheap B-roll iteration | `ltx` | `mid shot of a knight walking through fog, slow truck backward, dawn light, cinematic` | 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` | 5s |
+| Anime style hero | `kling` | `anime-style hero girl draws a katana in slow motion, sakura petals swirling, dramatic side-light, dynamic camera, Ghibli painterly` | 5s |
 
 ### Bad prompts and why
 
@@ -169,7 +169,7 @@ Pattern: `<archetype framing> + <subject> + <action verb> + <camera move> + <lig
 - **Using `veo3` for B-roll.** Use `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.
 - **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.
+- **Treating `assets.generate_video` as finished.** It answers `{ status: "running", job }` and no URL. Wait with `jobs.wait` 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.
 
@@ -178,8 +178,12 @@ 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).
 - **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.
+- **Subject is a UGC environment the player built.** Take a screenshot of the in-engine view, run it through `assets.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 with `assets.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.
+
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-5 and 7 and skip step 6 (import for archive). Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format. The MP4 goes straight into the person's video editor.
 
 ## Fallback (no MCP)
 
@@ -209,4 +213,4 @@ Once the shots are generated:
 - `music-track` — trailer score.
 - `sound-effect` — cut SFX (whooshes, impacts, stingers).
 - `concept-art` — generate the reference image axis when no asset exists yet.
-- `../../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.

package/library/skills/trailer-shot/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/trailer-shot
 kind: skill
 version: 1.0.4
-summary: Generate marketing or trailer footage — slow-mo combat, establishing shots, hero beats, splash screens, pitch-deck B-roll — max punch in 5-10 seconds.
+summary: "Generate trailer footage: slow-mo combat, establishing shots, hero beats, splash screens, 5-10 seconds."
 use_when:
   - generating marketing or trailer footage — slow-mo combat, dramatic establishing shots, hero beats, splash screens, pitch-deck B-roll
   - producing a store page, pitch deck, or social clip that shows the game at its most dramatic in seconds

package/library/skills/tune-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tune-performance
-description: "Profile a slow game with a measurement probe, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations."
+description: "Profile a slow game, find rendering, physics or script hotspots, and propose fixes with expected gains."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: performance
@@ -221,7 +221,7 @@ Compare: was the metric movement at least 50% of what was promised? If yes, ship
 
 ## Collaborative protocol
 
-This skill makes scene/resource/code changes. Always ask before each fix is applied. See `../../references/collaborative-protocol/collaborative-protocol.md`.
+This skill makes scene/resource/code changes. Always ask before each fix is applied. See `summer_docs_read` id `reference/collaborative-protocol`.
 
 ## Want a working starter?
 
@@ -229,10 +229,10 @@ No template — this is a workflow. Performance tuning is project-specific by de
 
 ## See also
 
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full MCP tool list
-- `../../references/godot-version/godot-version.md` — renderer API churn notes (Compositor, RenderSceneBuffers)
-- `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
-- `../../references/gd-style/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
+- `summer_docs_read` id `reference/mcp-tools-reference` — full MCP tool list
+- `summer_docs_read` id `reference/godot-version` — renderer API churn notes (Compositor, RenderSceneBuffers)
+- `summer_docs_read` id `reference/collaborative-protocol` — "May I write" pattern
+- `summer_docs_read` id `reference/gd-style` — GDScript conventions (avoid bare types, use `:=`)
 - `debug` — bug triage (related but different)
 - `diagnosing-perf-regressions` — when it *got* slow rather than always was
 - `3d-lighting` — light setup and bake decisions

package/library/skills/tune-performance/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/tune-performance
 kind: skill
 version: 1.0.3
-summary: Profile a slow game with a measurement probe, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations.
+summary: "Profile a slow game, find rendering, physics or script hotspots, and propose fixes with expected gains."
 use_when:
   - the game is slow, drops framerate, stutters, takes forever to start, or runs poorly on specific hardware
   - fps drops or stutter when many units, projectiles, or particles spawn at once and the hotspot is unknown