summer-engine 3.8.0 → 4.2.0

package/library/skills/sound-effect/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: sound-effect
-description: "Make SFX one-shots and timed sequences (swings, hits, whooshes, reloads, UI) - offer three model versions to pick from, then wire them as AudioStreamPlayers."
+description: "Make sound effects (swings, hits, whooshes, reloads, UI): three versions to pick from, then wire them."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_sfx_choices summer_get_choices summer_generate_audio summer_search_assets summer_import_from_url summer_import_asset_by_id summer_add_node summer_set_prop summer_instantiate_scene summer_inspect_node summer_get_scene_tree
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_sfx_choices summer_assets_choices summer_assets_generate_audio summer_assets_search summer_import_from_url summer_import_asset_by_id summer_add_node summer_set_prop summer_instantiate_scene summer_inspect_node summer_get_scene_tree summer_call
 paths: ["audio/sfx/**", "scripts/**", "**/*.tscn"]
 ---
 
@@ -17,8 +17,8 @@ paths: ["audio/sfx/**", "scripts/**", "**/*.tscn"]
 >
 > Say why in one plain line: the best model changes a lot from one sound to the next, so picking by ear gives a better result.
 >
-> - **Yes** → `summer_generate_sfx_choices`, tell them the returned `say` text, then `summer_get_choices` until they decide. Import the approved clips and wire them. The model they approve becomes their default.
-> - **No** → `summer_generate_audio` with `capability: "sound_effects"` and **no** `modelId` (it uses their approved default, else ElevenLabs).
+> - **Yes** → `assets.generate_sfx_choices`, tell them where to listen (their Studio tab opens the page, else `reviewUrl`), then `assets.choices` until they decide. Import the approved clips and wire them. The model they approve becomes their default.
+> - **No** → `assets.generate_audio` with `capability: "sound_effects"` and **no** `modelId` (it uses their approved default, else ElevenLabs).
 >
 > Ask once per chat. After they answer, do not ask again in the same chat; follow their answer for the rest of it.
 
@@ -38,7 +38,7 @@ Read `.summer/audio-bible.md` if it exists and map the request to one of its SFX
 
 ### 2. Reuse before you generate
 
-Generation costs credits. `summer_search_assets(query="<subject>", assetType="audio", source="all")`; if a clip fits, ask whether to use it.
+Generation costs credits (`dryRun: true` on the generate call shows how many). `assets.search({ query: "<subject>", assetType: "audio", scope: "all" })`; if a clip fits, ask whether to use it.
 
 ### 3. Write the prompt
 
@@ -60,7 +60,7 @@ Foley one-shot: <physical event with materials>, <transient + tail described>, c
 Foley sequence, exactly 2 seconds, three distinct mechanical sounds: at 0.2 s the empty magazine is released and pulled out with a metal click; at 1.0 s a full magazine is slammed in with a solid clack; at 1.6 s the charging handle is pulled back and released with a sharp metallic snap. Close-mic, dry, no gunshot, no music.
 ```
 
-**Loops:** write `seamless loop` in the text and pass `loop: true`. Only ElevenLabs SFX v2 makes loops: use `summer_generate_audio` with `modelId: "eleven_text_to_sound_v2"`, or include it in a choice set.
+**Loops:** write `seamless loop` in the text and pass `loop: true`. Only ElevenLabs SFX v2 makes loops: use `assets.generate_audio` with `modelId: "eleven_text_to_sound_v2"`, or include it in a choice set.
 
 Avoid: vibe words (`epic`, `cool`, `realistic`), several unrelated events in one prompt (split them, unless it is a timed sequence), and no length.
 
@@ -87,34 +87,34 @@ Show the prompt and the length before you call; every version is a billed genera
 **Choice set (the person said yes):**
 
 ```
-summer_generate_sfx_choices(text: "<prompt>", durationSeconds: 1.0)
+assets.generate_sfx_choices({ text: "<prompt>", durationSeconds: 1.0 })
 ```
 
-The page opens in their open Summer Studio tab, else in the browser. Tell them the returned `say` text; if `shown` is `not_opened`, give them `reviewUrl`. Do not pick for them. Then:
+The answer has `choiceSetId`, `reviewUrl`, the `clips` and `studioTabOpened`. The page opens in their open Summer Studio tab; if `studioTabOpened` is false, give them `reviewUrl`. Do not pick for them. Then:
 
 ```
-summer_get_choices(choiceSetId: "<id>", waitSeconds: 50)
+assets.choices({ choiceSetId: "<id>", waitSeconds: 50 })
 ```
 
-Call it again while `status` is `pending`. When it is `decided`, each entry in `approved` has `audioUrl`, `assetId`, `fileExtension` and the person's `note`. If they approved none, ask what to change and make a new set.
+Call it again while `status` is `pending`. When it is `decided`, each clip with `approved: true` has `audioUrl`, `assetId` and the person's `note`. If they approved none, ask what to change and make a new set.
 
 **One version (the person said no, or later sounds after a decided set):**
 
 ```
-summer_generate_audio(capability: "sound_effects", text: "<prompt>", durationSeconds: 1.0)
+assets.generate_audio({ capability: "sound_effects", text: "<prompt>", durationSeconds: 1.0 })
 ```
 
-Leave out `modelId` so their approved default runs. The description goes in `text`, not `prompt` (`prompt` gives a 400 `text_required` here).
+Leave out `modelId` so their approved default runs. The description goes in `text`, not `prompt` (without `text` the call is refused: `text_required`). The answer's `asset` has `assetId`, `fileUrl` and `durationSeconds`.
 
 No Summer project (an asset-only request, or the engine is not installed or not running): stop here. The clips are in the person's Summer library; give them the `audioUrl` of each approved version and skip steps 7 and 8.
 
 ### 7. Import
 
 ```
-summer_import_from_url(url: "<audioUrl>", path: "res://audio/sfx/sword_clash_01.<fileExtension>")
+summer_import_from_url(url: "<audioUrl>", path: "res://audio/sfx/sword_clash_01.<ext>")
 ```
 
-or `summer_import_asset_by_id(assetId: "<assetId>", path: "res://audio/sfx/sword_clash_01.<fileExtension>")`. Keep the extension of the file you got. When the person approved several versions, import each one (`_01`, `_02`, …) and play a random one per event for variety.
+or `summer_import_asset_by_id(assetId: "<assetId>", path: "res://audio/sfx/sword_clash_01.<ext>")`. Keep the extension of the file you got (the end of `audioUrl` or `fileUrl`). When the person approved several versions, import each one (`_01`, `_02`, …) and play a random one per event for variety.
 
 One-shots keep loop OFF in the Import dock; looping a one-shot clicks. For a loop: WAV uses Edit > Loop Mode = Forward; OGG/MP3 use Loop = on.
 
@@ -126,13 +126,18 @@ One-shots keep loop OFF in the Import dock; looping a one-shot clicks. For a loo
 | `AudioStreamPlayer2D` | 2D positional |
 | `AudioStreamPlayer3D` | 3D positional (weapon swing in the world, footstep) |
 
-Every scene-mutating tool takes an explicit `scenePath`, node paths are relative to the scene root (`./`), and the property argument is `key`:
+One script adds the player with its settings; `scenePath` is the exact scene to change:
 
 ```
-summer_add_node(scenePath="res://main.tscn", parent="./Player", type="AudioStreamPlayer3D", name="SwingSFX")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/SwingSFX", key="stream", value="res://audio/sfx/sword_swing_01.wav")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/SwingSFX", key="bus", value="SFX")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/SwingSFX", key="max_distance", value=25.0)
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    ctx.add_node("AudioStreamPlayer3D", "SwingSFX", ctx.find("Player"), {
+        "stream": load("res://audio/sfx/sword_swing_01.wav"),
+        "bus": "SFX",
+        "max_distance": 25.0,
+    })
+    ctx.save_scene()
+""")
 ```
 
 The bus must match the bible (`SFX`, `UI`, `Ambient`, …); the default bus is `Master`. If the bus does not exist, run `/audio-direction`.
@@ -156,6 +161,10 @@ Save it as a `.tscn` and instantiate it per event in GDScript (`preload(...).ins
 
 `summer_inspect_node(path="Player/SwingSFX")`: verify `stream`, `bus`, `volume_db`. Too quiet: raise `volume_db` (+3 to +9, never past +12), else regenerate with a heavier description. Too long: `stop()` on a timer.
 
+## 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 steps 7-9 (import, wiring, scene check). With `assets.generate_sfx_choices`, the person picks in the page; then save each approved clip where the person asked with `assets.get` and `out` (the `summer-assets` skill says how), and tell them the path and format.
+
 ## Fallback (no MCP)
 
 Print the prompt, the length and the target path (`res://audio/sfx/<name>.wav`), and tell the person to make it in Summer Studio, then import it.
@@ -166,4 +175,27 @@ Print the prompt, the length and the target path (`res://audio/sfx/<name>.wav`),
 - `ambient-bed` — long looping textures
 - `music-track` — music
 - `voice-line` — speech
-- `../../references/mcp-tools-reference/mcp-tools-reference.md`
+- `summer_docs_read` id `reference/mcp-tools-reference`
+
+<!-- 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.choices`, `summer_assets_choices` | `summer assets choices` |
+| `assets.generate_audio`, `summer_assets_generate_audio` | `summer assets generate-audio` |
+| `assets.generate_sfx_choices`, `summer_assets_generate_sfx_choices` | `summer assets generate-sfx-choices` |
+| `assets.get` | `summer assets get` |
+| `assets.search`, `summer_assets_search` | `summer assets search` |
+| `summer_docs_read` | `summer docs read` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_import_asset_by_id` | `summer engine import-asset-by-id` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_set_prop` | `summer engine set-prop` |
+<!-- /shell-commands -->

package/library/skills/sound-effect/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/sound-effect
 kind: skill
 version: 1.1.0
-summary: "Make SFX one-shots and timed sequences (swings, hits, whooshes, reloads, UI) - offer three model versions to pick from, then wire them as AudioStreamPlayers."
+summary: "Make sound effects (swings, hits, whooshes, reloads, UI): three versions to pick from, then wire them."
 use_when:
   - generating short SFX one-shots — footsteps, weapon swings, UI clicks, hit impacts, environmental cues
   - an action, impact, or UI interaction is silent and needs a short one-shot sound wired to it

package/library/skills/spatial-placement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spatial-placement
-description: "Place 3D objects and modular kit pieces from measured geometry — inspect, place, starcast, measure, correct; floor, wall, facade, pipe and alcove recipes."
+description: "Place 3D objects and modular kit pieces from measured geometry: floors, walls, facades, pipes, alcoves."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project
@@ -108,17 +108,25 @@ with its back `-z` and open loops at both ends; `wall_lamp` has its back `-z`;
 `wall_clamp` is small with its back `-z`. Scene `res://facade_test.tscn` with a
 `Facade` Node3D at the origin.
 
+Place every piece at a rough pose in one `summer_batch`, then let the measured
+tools seat each one:
+
 ```text
-summer_instantiate_scene {scenePath:"res://facade_test.tscn", parent:"./Facade",
-  scene:"res://kit/wall_double.tscn", name:"G1", position:[0,0,0]}
-summer_instantiate_scene {..., scene:"res://kit/window_double.tscn", name:"G2", position:[2,0,0]}
+summer_batch {scenePath:"res://facade_test.tscn", receipt:"summary", ops:[
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/wall_double.tscn", name:"G1", position:[0,0,0]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/window_double.tscn", name:"G2", position:[2,0,0]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/window_double.tscn", name:"U1", position:[0,3,0]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/window_double.tscn", name:"U2", position:[2,3,0]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/gutter_section.tscn", name:"Pipe_1", position:[2.15,0.1,0.5]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/gutter_section.tscn", name:"Pipe_2", position:[2.15,1.1,0.1]},
+  {op:"InstantiateScene", parent:"./Facade", scene:"res://kit/wall_lamp.tscn", name:"Lamp", position:[1,2.6,0.5]}]}
+    -> one compact receipt: the seven nodes and their poses
+
 summer_place_adjacent {scenePath:"res://facade_test.tscn", subject:"./Facade/G2",
   reference:"./Facade/G1", axis:"x", side:"max", alignOtherAxes:{y:"min", z:"max"}}
     -> verify {gap:0, residuals:{y:0, z:0}}
-summer_instantiate_scene {..., scene:"res://kit/window_double.tscn", name:"U1", position:[0,3,0]}
 summer_place_adjacent {..., subject:"./Facade/U1", reference:"./Facade/G1",
   axis:"y", side:"max", alignOtherAxes:{x:"min", z:"max"}}
-summer_instantiate_scene {..., scene:"res://kit/window_double.tscn", name:"U2", position:[2,3,0]}
 summer_place_adjacent {..., subject:"./Facade/U2", reference:"./Facade/U1",
   axis:"x", side:"max", alignOtherAxes:{y:"min", z:"max"}}
 summer_measure {scenePath:"res://facade_test.tscn", mode:"plane",
@@ -127,11 +135,9 @@ summer_measure {scenePath:"res://facade_test.tscn", mode:"plane",
 
 summer_raycast {scenePath:"res://facade_test.tscn", origin:[2.15,0.5,1], direction:[0,0,-1]}
     -> hit ./Facade/G2, normal [0,0,1]: the wall front, by physics
-summer_instantiate_scene {..., scene:"res://kit/gutter_section.tscn", name:"Pipe_1", position:[2.15,0.1,0.5]}
 summer_attach_to_surface {scenePath:"res://facade_test.tscn", subject:"./Facade/Pipe_1",
   ray:{origin:[2.15,0.5,1], direction:[0,0,-1]}, backAxis:"-z", upAxis:"+y", standoff:0.02}
     -> seated_on "Facade/G2", final_gap 0.02, back_face_gap 0.02; the pipe keeps y 0.1
-summer_instantiate_scene {..., scene:"res://kit/gutter_section.tscn", name:"Pipe_2", position:[2.15,1.1,0.1]}
 summer_connect_ports {scenePath:"res://facade_test.tscn", subject:"./Facade/Pipe_2", subjectPort:"-Y",
   target:"./Facade/Pipe_1", targetPort:"+Y"}
     -> tilt_degrees 0, verify {distance:0, angle_degrees:0}, other_ports [{id:"+Y", direction:[0,1,0]}]
@@ -139,7 +145,6 @@ summer_repeat_along {scenePath:"res://facade_test.tscn", template:"res://kit/wal
   parent:"./Facade", start:[2.15,0.3,0.02], end:[2.15,1.9,0.02], spacing:0.45}
     -> count 4, created ["Facade/wall_clamp_1", ...]
 
-summer_instantiate_scene {..., scene:"res://kit/wall_lamp.tscn", name:"Lamp", position:[1,2.6,0.5]}
 summer_attach_to_surface {scenePath:"res://facade_test.tscn", subject:"./Facade/Lamp",
   surface:"./Facade/G1", backAxis:"-z", standoff:0}
 summer_starcast {scenePath:"res://facade_test.tscn", path:"./Facade/Lamp", directionSpace:"local"}
@@ -203,3 +208,33 @@ anchors, pass their names instead.
 - A piece seated flush against a single-sided wall can read `open` in the
   wall's direction while `contacts` lists the wall: Starcast's one ray per
   direction starts at the touching face. Read `contacts` too.
+
+<!-- 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_align_distribute_3d` | `summer engine align-distribute-3d` |
+| `summer_attach_to_surface` | `summer engine attach-to-surface` |
+| `summer_batch` | `summer engine batch` |
+| `summer_connect_ports` | `summer engine connect-ports` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_inspect_asset` | `summer engine inspect-asset` |
+| `summer_inspect_node` | `summer engine inspect-node` |
+| `summer_instantiate_scene` | `summer engine instantiate-scene` |
+| `summer_measure` | `summer engine measure` |
+| `summer_open_scene` | `summer engine open-scene` |
+| `summer_place_adjacent` | `summer engine place-adjacent` |
+| `summer_raycast` | `summer engine raycast` |
+| `summer_repeat_along` | `summer engine repeat-along` |
+| `summer_run_script` | `summer engine run-script` |
+| `summer_screenshot` | `summer engine screenshot` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_snap_to_surface` | `summer engine snap-to-surface` |
+| `summer_snapshot_diff` | `summer engine snapshot-diff` |
+| `summer_starcast` | `summer engine starcast` |
+| `summer_test_placement` | `summer engine test-placement` |
+| `summer_world_snapshot` | `summer engine world-snapshot` |
+<!-- /shell-commands -->

package/library/skills/spatial-placement/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/spatial-placement
 kind: skill
 version: 1.1.0
-summary: Place 3D objects and modular kit pieces from measured geometry — inspect, place, starcast, measure, correct; floor, wall, facade, pipe and alcove recipes.
+summary: "Place 3D objects and modular kit pieces from measured geometry: floors, walls, facades, pipes, alcoves."
 use_when:
   - positioning a prop, character, collider, or platform so it sits flush, avoids overlap, or keeps clearance
   - placing something against a wall, inside an alcove, or on a shelf and needing to know which side is blocked and by how much

package/library/skills/sprite-sheet/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: sprite-sheet
-description: "Generate animated 2D character sprites laid out as a sprite sheet — walk cycle, attack, idle, death — wired into AnimatedSprite2D / SpriteFrames."
+description: "Generate animated 2D character sprite sheets (walk, attack, idle, death) for AnimatedSprite2D."
 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_slice_asset_sheet summer_get_studio_workflow summer_search_assets summer_import_from_url summer_import_asset_by_id summer_set_resource_property summer_write_file summer_add_node summer_set_prop summer_save_scene
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_slice_sheet summer_assets_search summer_import_from_url summer_import_from_url_batch summer_import_asset_by_id summer_set_resource_property summer_write_file summer_add_node summer_set_prop summer_save_scene summer_call
 paths: ["assets/**", "sprites/**", "art/sprites/**"]
 ---
 
@@ -18,10 +18,10 @@ Sprite-sheet generation from a single text-to-image call is **unreliable**. Mode
 This skill therefore offers **three paths**, ranked by reliability:
 
 1. **Per-frame img2img** (most reliable) — generate the base pose, then generate each subsequent frame via `referenceImageUrl` with a small pose delta. Composite the frames into a sheet externally or wire each as a separate `SpriteFrames` entry.
-2. **Single-call sheet + auto-slice** (fast; sheet coherence is the gamble, not the cutting) — one prompt asks for the grid, then `summer_slice_asset_sheet` cuts it into individual frame assets server-side. Worth trying once for short cycles (4 frames or fewer) before falling back to (1).
+2. **Single-call sheet + auto-slice** (fast; sheet coherence is the gamble, not the cutting) — one prompt asks for the grid, then `assets.slice_sheet` cuts it into individual frames server-side. Worth trying once for short cycles (4 frames or fewer) before falling back to (1).
 3. **Manual authoring** (most reliable, slowest) — hand-author in **Aseprite** or **Piskel**. For pixel art at 32×32, this is often faster than fixing AI generations.
 
-There is no single "generate a sprite sheet" tool, but there **is** a shared two-tool sheet pipeline, and it is the same one Studio's Guided "sprite-sheet" workflow runs: `summer_generate_image` produces one sheet, then `summer_slice_asset_sheet({ assetId })` runs the server-side vision slicer that removes the background, detects each frame's bounding box, crops, and uploads every frame as its own asset. Call `summer_get_studio_workflow({ workflowId: "sprite-sheet" })` for the current ordered recipe and its stated limitations. Only Studio's frame-preview and visual timing-review UI is unreachable from MCP — the generation and the slicing both are reachable.
+There is no single "generate a sprite sheet" operation, but there **is** a shared two-step sheet pipeline, and it is the same one Studio's Guided "sprite-sheet" workflow runs: `assets.generate_image` produces one sheet, then `assets.slice_sheet({ assetId })` runs the server-side vision slicer that removes the background, detects each frame's bounding box, crops, and uploads every frame as its own image (one URL per slice). Call `summer_call({ op: "docs.workflows", input: { workflowId: "sprite-sheet" } })` for the current ordered recipe and its stated limitations. Only Studio's frame-preview and visual timing-review UI is unreachable from MCP — the generation and the slicing both are reachable.
 
 So do not tell the user to cut a generated sheet by hand or in ImageMagick. The cutting is automated; what is unreliable is inter-frame *consistency* inside the generated sheet.
 
@@ -38,7 +38,7 @@ So do not tell the user to cut a generated sheet by hand or in ImageMagick. The
 - The character is 3D — use `generate-motion` for skeletal animation.
 - The user wants a single static sprite → `pixel-art` or `character-portrait`.
 - The user wants UI animation (loading spinner, button hover) — animate via `AnimationPlayer` rotating/tweening a static texture instead. Don't sprite-sheet UI.
-- The user has 12+ frames per animation and 4+ animations. That is dozens to hundreds of generations, each using credits. Pause and agree on scope first.
+- The user has 12+ frames per animation and 4+ animations. That is dozens to hundreds of generations, each using credits. Pause and agree on scope first; `dryRun: true` on one frame's call shows its credits.
 
 ## Steps
 
@@ -69,16 +69,16 @@ State the path before starting: "I'll do per-frame img2img: 6 generations. The f
 Generate frame 1 (or use existing base). For each subsequent frame, prompt the pose delta and pass the previous frame as `referenceImageUrl`:
 
 ```
-summer_generate_image(
-  prompt="goblin warrior, walk cycle frame 2 of 6, right leg forward, slight bob upward, identical character, same costume, same palette. Not a different character, not a different costume, no scene background.",
-  referenceImageUrl="<frame 1 fileUrl>",
-  model="nano-banana-2",
-  style="<same as base>",
-  removeBackground=true
-)
+assets.generate_image({
+  prompt: "goblin warrior, walk cycle frame 2 of 6, right leg forward, slight bob upward, identical character, same costume, same palette. Not a different character, not a different costume, no scene background.",
+  referenceImageUrl: "<frame 1 fileUrl>",
+  model: "nano-banana-2",
+  style: "<same as base>",
+  removeBackground: true
+})
 ```
 
-`summer_generate_image` has no size argument; put negations in the prompt text. `removeBackground: true` gives you real alpha instead of a prompted "transparent background" that the model may paint as a literal checkerboard. `referenceImageUrl` only works on edit-capable models (`nano-banana-2`, `seedream-5-pro`, `nano-banana-lite`, `gpt-image-2`, `gemini-flash`, `flux-2`); `grok-imagine` has no edit endpoint and returns `edit_not_supported`.
+Keep `aspectRatio` (and `width` / `height`, if you set them) the same for every frame; put negations in the prompt text. `removeBackground: true` gives you real alpha instead of a prompted "transparent background" that the model may paint as a literal checkerboard. `referenceImageUrl` only works on edit-capable models (`nano-banana-2`, `seedream-5-pro`, `nano-banana-lite`, `gpt-image-2`, `gemini-flash`, `flux-2`); `grok-imagine` has no edit endpoint and returns `edit_not_supported`.
 
 Repeat for each frame. Save each as `goblin_walk_01.png`, `goblin_walk_02.png`, etc.
 
@@ -89,23 +89,24 @@ composite them into one sheet image.
 ### 3b. Path 2 — Single-call sheet, then auto-slice
 
 ```
-summer_generate_image(
-  prompt="goblin warrior walk cycle, sprite sheet, 6 frames in a horizontal row, identical character across frames, side view, frames clearly separated with empty space between them, consistent lighting, consistent palette. No scene background, no varying lighting, not a different character per frame.",
-  model="nano-banana-2",
-  style="none",
-  removeBackground=true
-)
+assets.generate_image({
+  prompt: "goblin warrior walk cycle, sprite sheet, 6 frames in a horizontal row, identical character across frames, side view, frames clearly separated with empty space between them, consistent lighting, consistent palette. No scene background, no varying lighting, not a different character per frame.",
+  model: "nano-banana-2",
+  style: "none",
+  aspectRatio: "21:9",
+  removeBackground: true
+})
 ```
 
-There is no `"pixel"` style preset (`style` is `realistic | cartoon | anime | none`; anything else is coerced to `none`) and no size argument; the layout and the negations have to be in the prompt.
+There is no `"pixel"` style preset (`style` is `realistic | cartoon | anime | none`). A wide `aspectRatio` gives a row of frames room; the layout and the negations have to be in the prompt.
 
 Then cut it with the same server-side slicer Studio uses, passing the asset id the generation returned:
 
 ```
-summer_slice_asset_sheet(assetId="<generated sheet assetId>")
+assets.slice_sheet({ assetId: "<generated sheet assetId>" })
 ```
 
-It returns the source dimensions plus per-slice URLs, names, categories, and bounding boxes. Import the frames you want by id with `summer_import_asset_by_id`.
+It returns `source` (the sheet's width and height) and `slices`: each slice's `url`, `name`, `category` and `bbox`. The slices are image URLs, not assets: import the frames you want with `summer_import_from_url_batch`.
 
 Inspect the result. If the frames are coherent and the count matches, proceed. If anatomy morphs across the row, or the slicer returns one giant box (items touching / no gaps), fall back to Path 1 or Path 3 — re-prompting with more separation between frames is the first thing to try.
 
@@ -202,7 +203,7 @@ func _physics_process(delta):
 - **Wiring an inconsistent sheet anyway** because you don't want to regenerate. Ship the inconsistency and the player notices the morphing limbs immediately. Cut the frame count or hand-author instead.
 - **Sprite-sheeting things that don't need to be sprite-sheeted.** UI animation, simple bobs, fades — use `AnimationPlayer` to tween a static texture instead. Sprite sheets are for character animation specifically.
 - **Pretending Aseprite is a failure.** Hand-authoring 4 pixel-art frames takes 10 minutes and looks better than 8 AI generations. Don't oversell AI here.
-- **Sending the user to ImageMagick or Aseprite to *cut* a generated sheet.** `summer_slice_asset_sheet` does that server-side. Hand off the creative work, not the mechanical work.
+- **Sending the user to ImageMagick or Aseprite to *cut* a generated sheet.** `assets.slice_sheet` does that server-side. Hand off the creative work, not the mechanical work.
 
 ## Edge cases
 
@@ -212,14 +213,18 @@ func _physics_process(delta):
 - **User wants a turn-around (rotating in place over 8 frames).** Same as 8-direction; generate single-frame per angle as anchor, accept that AI rotation won't be perfectly consistent.
 - **Animation needs to loop seamlessly.** Make frame N+1 explicitly bridge back to frame 1 in your prompt. Or generate one extra "bridge" frame and drop it.
 
+## 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 skip steps 4-6 (import, `AnimatedSprite2D`, trigger code). Pass `out` with the person's folder for each frame, or slice a sheet with `assets.slice_sheet` and save each piece with `assets.get` and `out` (the `summer-assets` skill says how). Tell the person the frame order and the frame rate you planned.
+
 ## Fallback (no MCP)
 
 Print the per-frame call sequence:
 
 ```
-Frame 1: summer_generate_image(prompt="<base>", model="nano-banana-2", style="none", ...)
-Frame 2: summer_generate_image(prompt="<base + delta>", referenceImageUrl="<frame 1>", ...)
-Frame 3: summer_generate_image(prompt="<base + delta>", referenceImageUrl="<frame 2>", ...)
+Frame 1: assets.generate_image({ prompt: "<base>", model: "nano-banana-2", style: "none", ... })
+Frame 2: assets.generate_image({ prompt: "<base + delta>", referenceImageUrl: "<frame 1>", ... })
+Frame 3: assets.generate_image({ prompt: "<base + delta>", referenceImageUrl: "<frame 2>", ... })
 ...
 ```
 
@@ -241,4 +246,27 @@ After the animation is wired:
 - `character-portrait` — base portrait for higher-res characters.
 - `generate-motion` — 3D-skeletal counterpart.
 - `sound-effect` — frame-synced SFX.
-- `../../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`.
+
+<!-- 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` |
+| `assets.get` | `summer assets get` |
+| `summer_assets_search` | `summer assets search` |
+| `assets.slice_sheet`, `summer_assets_slice_sheet` | `summer assets slice-sheet` |
+| `summer_docs_read` | `summer docs read` |
+| `docs.workflows` | `summer docs workflows` |
+| `summer_add_node` | `summer engine add-node` |
+| `summer_import_asset_by_id` | `summer engine import-asset-by-id` |
+| `summer_import_from_url` | `summer engine import-from-url` |
+| `summer_import_from_url_batch` | `summer engine import-from-url-batch` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `summer_set_resource_property` | `summer engine set-resource-property` |
+| `summer_write_file` | `summer engine write-file` |
+<!-- /shell-commands -->

package/library/skills/sprite-sheet/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/sprite-sheet
 kind: skill
 version: 1.0.4
-summary: Generate animated 2D character sprites laid out as a sprite sheet — walk cycle, attack, idle, death — wired into AnimatedSprite2D / SpriteFrames.
+summary: "Generate animated 2D character sprite sheets (walk, attack, idle, death) for AnimatedSprite2D."
 use_when:
   - generating animated 2D character sprites laid out as a grid of frames — walk cycle, attack frames, idle bob, death sequence
   - a 2D sprite needs its frames laid out as one grid image for AnimatedSprite2D or SpriteFrames

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

@@ -1,11 +1,11 @@
 ---
 name: store-art
-description: "Make Summer Games store art per slot and flow: key art, covers, icons, screenshots, trailer: size, shape, text rules, fallbacks."
+description: "Make Summer Games store art per slot: key art, covers, icons, screenshots, trailer, size and text rules."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment
 user-invocable: true
-allowed-tools: summer_read_library
+allowed-tools: summer_docs_read
 ---
 
 # /store-art — store art
@@ -14,10 +14,21 @@ This skill covers every store art slot per flow (desktop and mobile): size, shap
 
 Its current text lives on the hosted Summer Engine MCP, the same text the Studio agent reads, so it changes with the store and is never stale here. Load it before you act:
 
-1. `summer_read_library` with id `skill/store-art` returns the current text when this machine has a store sign-in (`summer login --store`).
+1. `summer_docs_read` with id `skill/store-art` returns the current text when this machine is signed in (`summer login`).
 2. A host that shows MCP prompts or resources has it as the `store-art` prompt and the resource `summer://skills/store-art`.
 3. Without a store sign-in: https://docs.summerengine.com/llms.txt lists every docs page; fetch any page as .md.
 
 Screenshots: `summer_capture_gameplay` takes them offscreen. Get past the title screen with the game's own flags in `args` or with `steps`, e.g. `{"args":["--autostart"],"steps":[{"wait":3000},{"shot":true},{"key":"Space"},{"wait":800},{"shot":true}]}`.
 
 The one rule to keep even before you load it: Key art, covers and icons carry no text: the stores draw the title over them. Screenshots are real play.
+
+<!-- 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_docs_read` | `summer docs read` |
+| `summer_capture_gameplay` | `summer engine capture-gameplay` |
+<!-- /shell-commands -->

package/library/skills/store-art/resource.yaml

@@ -1,10 +1,10 @@
 id: skill/store-art
 kind: skill
 version: 1.0.0
-summary: "Make Summer Games store art per slot and flow: key art, covers, icons, screenshots, trailer: size, shape, text rules, fallbacks."
+summary: "Make Summer Games store art per slot: key art, covers, icons, screenshots, trailer, size and text rules."
 use_when:
   - "making or choosing store art for Summer Games: key art, cover, icon, screenshots, trailer"
-  - "summer_store_set_art rejects an image for its shape or size, or summer_store_get_listing says an art slot is missing"
+  - "store.set_art rejects an image for its shape or size, or store.get_listing says an art slot is missing"
   - "deciding whether a store image may carry text, and which slot falls back to which"
 facets:
   lifecycle:

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

@@ -1,11 +1,11 @@
 ---
 name: store-listing
-description: "Write a Summer Games store page per flow (desktop, mobile): targets, title, tagline, descriptions, tags, and what never to write."
+description: "Write a Summer Games store page: title, tagline, descriptions, tags, per platform, and what never to write."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment
 user-invocable: true
-allowed-tools: summer_read_library
+allowed-tools: summer_docs_read
 ---
 
 # /store-listing — store listing
@@ -14,8 +14,18 @@ This skill covers the store page text per flow (desktop and mobile): targets, ti
 
 Its current text lives on the hosted Summer Engine MCP, the same text the Studio agent reads, so it changes with the store and is never stale here. Load it before you act:
 
-1. `summer_read_library` with id `skill/store-listing` returns the current text when this machine has a store sign-in (`summer login --store`).
+1. `summer_docs_read` with id `skill/store-listing` returns the current text when this machine is signed in (`summer login`).
 2. A host that shows MCP prompts or resources has it as the `store-listing` prompt and the resource `summer://skills/store-listing`.
 3. Without a store sign-in: https://docs.summerengine.com/llms.txt lists every docs page; fetch any page as .md.
 
 The one rule to keep even before you load it: Never invent features, modes, player counts, awards or prices.
+
+<!-- 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_docs_read` | `summer docs read` |
+<!-- /shell-commands -->

package/library/skills/store-listing/resource.yaml

@@ -1,10 +1,10 @@
 id: skill/store-listing
 kind: skill
 version: 1.0.0
-summary: "Write a Summer Games store page per flow (desktop, mobile): targets, title, tagline, descriptions, tags, and what never to write."
+summary: "Write a Summer Games store page: title, tagline, descriptions, tags, per platform, and what never to write."
 use_when:
   - "writing or fixing a game's store page text on Summer Games: title, tagline, description, tags"
-  - "summer_store_update_listing or summer_store_get_listing says a text field is missing or wrong"
+  - "store.update_listing or store.get_listing says a text field is missing or wrong"
   - "choosing the targets (web, Mac, Windows, Linux, iPhone, Android) that decide the desktop and mobile store flows"
 facets:
   lifecycle:

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

@@ -5,11 +5,11 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: multiplayer-and-networking
 user-invocable: true
-allowed-tools: Read Grep Edit Write summer_get_script_errors summer_play summer_stop summer_get_diagnostics summer_open
+allowed-tools: Read Grep Edit Write summer_get_script_errors summer_play summer_stop summer_get_diagnostics summer_call
 paths: ["**/*.gd"]
 ---
 
-# /summer-analytics — game events you can chart later
+# /summer-analytics — game events you read in Grow
 
 ## Overview
 
@@ -105,9 +105,11 @@ On the client, after a menu choice:
 
 ### 4. Read the results
 
-Open the game's analytics in Studio: `summer_open` with target `game` and
-params `gameId` (your game's id) and `section: "analytics"`. Events show up
-there after a short delay.
+`analytics.summary` (hosted, after `summer login`) returns the
+game's top custom events next to its store page views, launches and play
+time; the `grow-analytics` skill says how to read them. In Studio:
+`studio.open` with target `game`, params `gameId` (your game's id) and
+`section: "analytics"`. Events show up after a short delay.
 
 ## Result codes
 
@@ -145,3 +147,18 @@ Every failure is final: none of them asks you to capture again.
 - `multiplayer` — where the client and the authority run
 - `multiplayer-state` — the authority's Command handlers, where most events happen
 - `summer-match-results` — results and ratings, which Summer records itself
+
+<!-- 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 |
+|---|---|
+| `analytics.summary` | `summer analytics summary` |
+| `summer_get_diagnostics` | `summer engine get-diagnostics` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_play` | `summer engine play` |
+| `summer_stop` | `summer engine stop` |
+| `studio.open` | `summer studio open` |
+<!-- /shell-commands -->

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

@@ -1,6 +1,6 @@
 id: skill/summer-analytics
 kind: skill
-version: 1.0.0
+version: 1.0.1
 summary: "Send game events to Summer analytics from the authority or client: fire-and-forget, never blocking gameplay."
 use_when:
   - "adding analytics, telemetry or event tracking to a Summer game: level completed, coin collected, tutorial funnel"
@@ -25,5 +25,5 @@ related:
     - skill/grow-analytics
 source: official
 license: MIT
-status: preview
+status: stable
 recommended: false