summer-engine 3.8.0 → 4.0.0

package/library/skills/voice-line/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: voice-line
-description: "Generate TTS voice lines — NPC barks, narrator, dialogue — with voice-id sourcing, a character-to-voice decision tree, and multi-line dialogue support."
+description: "Generate voice lines (NPC barks, narrator, dialogue) with a character-to-voice choice and multi-line support."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: audio
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_audio summer_search_assets summer_import_from_url summer_add_node summer_set_prop summer_inspect_node
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_audio summer_assets_search summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_call
 paths: [".summer/**", "audio/voice/**", "scripts/**", "**/*.tscn"]
 ---
 
@@ -13,7 +13,7 @@ paths: [".summer/**", "audio/voice/**", "scripts/**", "**/*.tscn"]
 
 ## Overview
 
-The hardest part of TTS isn't the line — it's picking the right voice. ElevenLabs ships hundreds; pick wrong and a tough warlord NPC sounds like a podcast host. **There is no MCP tool that lists voices** — the only voice-related input Summer exposes is the `voiceId` string on `summer_generate_audio`. So the voice pick has to come from the user (or from the project's cast bible), and this skill's job is to get that pick made deliberately and then locked.
+The hardest part of TTS isn't the line — it's picking the right voice; pick wrong and a tough warlord NPC sounds like a podcast host. On the ElevenLabs models **only Summer's game cast may speak**: the `voiceId` of `assets.generate_audio` must be one of the cast voices below, and any other id is refused (`voice_not_allowed`). The fal speech models (`minimax-speech-2.8-hd`, `gemini-3.8-flash-tts`, ...) speak with their own prebuilt voices instead. So the pick comes from the cast (or the project's cast bible), and this skill's job is to make that pick deliberately and then lock it.
 
 Then it generates one line (or a multi-turn dialogue) with the right stability / style / similarity / speed for the delivery — flat for narration, expressive for a bark, fast for an excited shout.
 
@@ -48,17 +48,39 @@ If a character bible exists, the voice should match the character's age / gender
 
 Check the cast bible first (step 1). If the character already has a locked id, use it and skip to step 5.
 
-If not, you need a `voiceId` from the user. There is no catalog tool and no preview-URL endpoint on this surface — do not invent one, and do not claim you auditioned anything. Ask:
+If not, pick from Summer's game cast with the user. There is no preview-URL endpoint on this surface — do not claim you auditioned anything; the person listens to the generated line. The cast (name, role, id):
 
-> I need an ElevenLabs voice id for `<character>`. Two ways to get one:
-> - Browse and audition at `elevenlabs.io/app/voice-library` (or your Voices page) and paste me the voice id.
-> - Or say "use the default" and I'll generate with Summer's default voice so you can hear the line, then we swap the id later.
->
-> Describe the target if it helps me sanity-check the pick: gender, rough age, accent, and energy (calm / measured / excited / gruff).
+| Voice | Role | Id |
+|---|---|---|
+| George | Storyteller, warm | `JBFqnCBsd6RMkjVDRZzb` |
+| Charlie | Hero, deep, energetic | `IKne3meq5aSn9XLyUdCD` |
+| Jessica | Heroine, playful | `cgSgspJ2msm6clMCkdW9` |
+| Harry | Warrior, fierce | `SOYHLrjzK2X1ezoPC6cr` |
+| Callum | Trickster, husky | `N2lVS1w4EtoT3dr4eOWO` |
+| Brian | Narrator, deep | `nPczCjzI2devNBz1zQrb` |
+| Bill | Elder, wise | `pqHfZKP75CvOlQylNhV4` |
+| Sarah | Mentor, reassuring | `EXAVITQu4vr4xnSDxMaL` |
+| Adam | Villain, firm | `pNInz6obpgDQGcFmaJgB` |
+| Roger | Captain, laid back | `CwhRBWXzGAHq8TQ4Fs17` |
+| Lily | Actress, velvety | `pFZP5JQG7iQjIQuC4Bku` |
+| Liam | Streamer, energetic | `TX3LPaxmHKxFdv7VOQHJ` |
+| Matilda | Guide, knowledgeable | `XrExE9yKIg1WjnnlVkGX` |
+| Daniel | Broadcaster, steady | `onwK4e9ZLuTAKqWW03F9` |
+| River | Courier, relaxed | `SAz9YHcvj6GT2YYXdXww` |
+| Bella | Healer, bright | `hpp4J3VqNfWAUOO0d1Us` |
+| Laura | Sidekick, quirky | `FGY2WhTYpPnrIDTdsKH5` |
+| Alice | Oracle, clear | `Xb7hH8MSUJpSbSDYk0k2` |
+| Eric | Merchant, smooth | `cjVigY5qzO86Huf0OWal` |
+| Chris | Companion, charming | `iP95p4xoKVk53GoZ742B` |
+| Will | Adventurer, optimistic | `bIHbv24MWmeRgasZH58o` |
+
+Ask:
 
-Omitting `voiceId` entirely is valid — `summer_generate_audio` falls back to a single default voice (`JBFqnCBsd6RMkjVDRZzb`). That is fine for a throwaway read-through, never for a shipped cast.
+> For `<character>` I suggest `<voice>` (<role>). OK, or another cast voice?
 
-Voice is the highest-stakes audio decision in the project. Do not pick an id for the user and do not guess ids — a wrong id is a hard provider error, not a different-sounding voice.
+Omitting `voiceId` entirely is valid — `assets.generate_audio` falls back to the default voice (George, `JBFqnCBsd6RMkjVDRZzb`). That is fine for a throwaway read-through, never for a shipped cast.
+
+Voice is the highest-stakes audio decision in the project. Do not guess ids — an id outside the cast is refused, not a different-sounding voice.
 
 ### 3. Character-to-voice decision tree (when the user wants a recommendation)
 
@@ -81,7 +103,7 @@ If the user says "you pick", lean on this tree:
 
 After the pick:
 
-> Locked voice: `Hodge` (id `21m00Tcm4TlvDq8ikWAM`). I'll use this for all `<character>` lines unless you say otherwise.
+> Locked voice: `Roger` (id `CwhRBWXzGAHq8TQ4Fs17`). I'll use this for all `<character>` lines unless you say otherwise.
 
 Ask before writing:
 
@@ -104,8 +126,8 @@ providers:
 
 | Character | Voice name | Voice id | Notes |
 |---|---|---|---|
-| Captain Hodge | Hodge | 21m00Tcm4TlvDq8ikWAM | Calm, weathered, low-mid |
-| Bram the Smith | Brogan | <id> | Gruff Scottish, mid energy |
+| Captain Hodge | Roger | CwhRBWXzGAHq8TQ4Fs17 | Calm, weathered, low-mid |
+| Bram the Smith | Harry | SOYHLrjzK2X1ezoPC6cr | Gruff, mid energy |
 ```
 
 This is the cast bible. Every future voice line uses these ids — consistency is the point.
@@ -114,7 +136,7 @@ If legacy `.summer/voice-cast.md` already exists, read it first and either keep
 
 ### 5. Tune stability / similarity / style / speed for delivery
 
-These are **not** top-level tool arguments. They go inside `options.voiceSettings`, in camelCase, exactly as the ElevenLabs SDK's `VoiceSettings` type spells them — `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`. `options` is spread straight into the SDK call, so a flat `similarity_boost` at the top of `options` is silently dropped.
+These go in the `voiceSettings` object of `assets.generate_audio`, in camelCase — `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`. A snake_case key such as `similarity_boost` is not one of its fields and does nothing.
 
 | Param | Range | Effect |
 |---|---|---|
@@ -163,18 +185,18 @@ Example lines:
 ### 7. Confirm and call
 
 ```
-summer_generate_audio(
-  capability="text_to_speech",
-  text="Hold the line. They're coming through the south gate. Ready arrows.",
-  voiceId="21m00Tcm4TlvDq8ikWAM",
-  modelId="eleven_multilingual_v2",
-  options={ voiceSettings: { stability: 0.6, similarityBoost: 0.75, style: 0.2, speed: 1.0 } }
-)
+assets.generate_audio({
+  capability: "text_to_speech",
+  text: "Hold the line. They're coming through the south gate. Ready arrows.",
+  voiceId: "CwhRBWXzGAHq8TQ4Fs17",
+  modelId: "eleven_multilingual_v2",
+  voiceSettings: { stability: 0.6, similarityBoost: 0.75, style: 0.2, speed: 1.0 }
+})
 ```
 
-`modelId` defaults to `eleven_multilingual_v2`. For very short / latency-sensitive in-game barks, `eleven_turbo_v2_5` is faster; for highest fidelity, `eleven_multilingual_v2` is the default.
+`modelId` defaults to `eleven_multilingual_v2`. For very short / latency-sensitive in-game barks, `eleven_flash_v2_5` is faster; for highest fidelity, `eleven_multilingual_v2` is the default. A line spends the person's credits; `dryRun: true` returns its `estimate` first.
 
-There is no `outputPath` — the tool returns a hosted asset (MP3, `audio/mpeg`). Land it in the project explicitly:
+There is no `outputPath` — the answer is a hosted asset, `asset` (`assetId`, `fileUrl`, `durationSeconds`; MP3, `audio/mpeg`). Land it in the project explicitly:
 
 ```
 summer_import_from_url(url="<fileUrl>", path="res://audio/voice/hodge_hold_the_line.mp3")
@@ -182,33 +204,38 @@ summer_import_from_url(url="<fileUrl>", path="res://audio/voice/hodge_hold_the_l
 
 ### 8. Multi-line dialogue (two or more speakers)
 
-Use `summer_generate_audio` with `capability: "text_to_dialogue"`:
+Use `assets.generate_audio` with `capability: "text_to_dialogue"`:
 
 There is no `speakers` roster and no `script` array. The whole conversation is one flat `inputs` array of `{ text, voiceId }` objects, in turn order — the voice id is repeated on every line:
 
 ```
-summer_generate_audio(
-  capability="text_to_dialogue",
-  inputs=[
-    { text: "They're at the gate.",   voiceId: "21m00Tcm4TlvDq8ikWAM" },
-    { text: "Aye. Let 'em come.",     voiceId: "<brogan-id>" },
-    { text: "Steady. On my mark.",    voiceId: "21m00Tcm4TlvDq8ikWAM" }
+assets.generate_audio({
+  capability: "text_to_dialogue",
+  inputs: [
+    { text: "They're at the gate.",   voiceId: "CwhRBWXzGAHq8TQ4Fs17" },
+    { text: "Aye. Let 'em come.",     voiceId: "SOYHLrjzK2X1ezoPC6cr" },
+    { text: "Steady. On my mark.",    voiceId: "CwhRBWXzGAHq8TQ4Fs17" }
   ]
-)
+})
 ```
 
-`inputs` is required for this capability; omitting it is a 400 `inputs_required`. `modelId` defaults to `eleven_v3` here, not `eleven_multilingual_v2`. The result is a single MP3 with both voices and dialogue-aware pacing the model handles internally — import it with `summer_import_from_url` like any other clip. For very long scripts, split into chunks of ~6 turns and concatenate.
+`inputs` is required for this capability; omitting it is refused as invalid input (`inputs_required`). `modelId` defaults to `eleven_v3` here, not `eleven_multilingual_v2`. The result is a single MP3 with both voices and dialogue-aware pacing the model handles internally — import it with `summer_import_from_url` like any other clip. For very long scripts, split into chunks of ~6 turns and concatenate.
 
 ### 9. Wire the line as `AudioStreamPlayer` on the Voice bus
 
-Every scene-mutating tool takes an explicit `scenePath`, node paths are relative to the scene root (`./`), and the property argument is named `key`, not `property`:
+One script adds the player with its settings; `scenePath` is the exact scene to change:
 
 ```
-summer_add_node(scenePath="res://main.tscn", parent="./NPC", type="AudioStreamPlayer", name="VoiceLine")
-summer_set_prop(scenePath="res://main.tscn", path="./NPC/VoiceLine", key="stream", value="res://audio/voice/hodge_hold_the_line.mp3")
-summer_set_prop(scenePath="res://main.tscn", path="./NPC/VoiceLine", key="bus", value="Voice")
-summer_set_prop(scenePath="res://main.tscn", path="./NPC/VoiceLine", key="volume_db", value=0.0)
-summer_set_prop(scenePath="res://main.tscn", path="./NPC/VoiceLine", key="autoplay", value=false)
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    ctx.add_node("AudioStreamPlayer", "VoiceLine", ctx.find("NPC"), {
+        "stream": load("res://audio/voice/hodge_hold_the_line.mp3"),
+        "bus": "Voice",
+        "volume_db": 0.0,
+        "autoplay": false,
+    })
+    ctx.save_scene()
+""")
 ```
 
 For positional NPCs, `AudioStreamPlayer3D` with `max_distance=15.0` so distant NPCs aren't audible.
@@ -238,7 +265,7 @@ Narrator intimate:        warmer mid pitch, lower stability for breath
 
 ## Anti-patterns
 
-- **Inventing a voice catalog.** There is no `summer_list_models`, no voice-listing tool, and no preview URLs on this surface. Ask the user for the id.
+- **Inventing voices.** On the ElevenLabs models only the cast in step 2 may speak, and there are no preview URLs on this surface. Pick from the cast with the user.
 - **Guessing a voice id.** A wrong id is a provider error, not a different voice.
 - **Reusing a voice id across two characters.** Players notice instantly. Lock the cast.
 - **Changing a locked voice without approval.** A cast voice is project memory, not a throwaway generation option.
@@ -257,6 +284,10 @@ Narrator intimate:        warmer mid pitch, lower stability for breath
 - **User wants the line shorter on regen.** Edit the text first; don't try to compress with `speed` past 1.15 (artifacts).
 - **NPC bark variants.** Generate 3–5 variants of the same intent (`"They're at the gate!"`, `"Enemy approaching!"`, `"Look out!"`) and pick at random in code so the bark doesn't repeat.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-8 and skip step 9 (`AudioStreamPlayer`). Step 10 still applies when the project has a `.summer/` folder; otherwise give the person the voice id with the files. Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format.
+
 ## Fallback (no MCP)
 
 Print the call (text, voice id, params, target path). User runs via the Summer dashboard, then `summer_import_from_url` the result.

package/library/skills/voice-line/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/voice-line
 kind: skill
 version: 1.0.2
-summary: Generate TTS voice lines — NPC barks, narrator, dialogue — with voice-id sourcing, a character-to-voice decision tree, and multi-line dialogue support.
+summary: "Generate voice lines (NPC barks, narrator, dialogue) with a character-to-voice choice and multi-line support."
 use_when:
   - '"the NPC needs a greeting / a bark / a narrator intro read aloud"'
   - giving a character a voice that fits their personality (gruff, cheerful, robotic)

package/library/skills/web-and-touch-input/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: web-and-touch-input
-description: "Input for the browser and phones: the first-click rule for sound and mouse capture, focus, and touch buttons or a virtual stick on the same actions."
+description: "Browser and phone input: the first-click rule for sound and mouse capture, focus, touch buttons, a stick."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: scene-and-project

package/library/skills/web-and-touch-input/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/web-and-touch-input
 kind: skill
 version: 1.0.0
-summary: "Input for the browser and phones: the first-click rule for sound and mouse capture, focus, and touch buttons or a virtual stick on the same actions."
+summary: "Browser and phone input: the first-click rule for sound and mouse capture, focus, touch buttons, a stick."
 use_when:
   - the game plays in the browser and sound, mouse capture or keys do not work until something is clicked
   - the game should be playable on a phone or tablet with touch controls

package/library/skills/web-compatibility-look/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: web-compatibility-look
-description: "Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance."
+description: "Make a browser game look high-end in the Compatibility renderer (WebGL 2): what works, recipes, speed."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: rendering-and-lighting

package/library/skills/web-compatibility-look/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/web-compatibility-look
 kind: skill
 version: 1.0.0
-summary: "Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance."
+summary: "Make a browser game look high-end in the Compatibility renderer (WebGL 2): what works, recipes, speed."
 use_when:
   - the game plays in the browser or is exported for the web and must look finished
   - the look is flat, grey or default in the web preview, or a Forward+ feature does nothing there

package/library/skills/world-building-3d/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: world-building-3d
-description: "Compose, ground, space, and validate 3D scenes with Summer's four bounded spatial tools — exact paths, one geometric decision at a time, verified."
+description: "Compose, ground and space 3D scenes with Summer's four spatial tools, one geometric decision at a time."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project

package/library/skills/world-building-3d/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/world-building-3d
 kind: skill
 version: 1.1.1
-summary: Compose, ground, space, and validate 3D scenes with Summer's four bounded spatial tools — exact paths, one geometric decision at a time, verified.
+summary: "Compose, ground and space 3D scenes with Summer's four spatial tools, one geometric decision at a time."
 use_when:
   - placing or grounding props on floors, shelves, ramps, or tables without hand-tuning transforms
   - aligning or evenly spacing a group of 3D objects along one world axis

package/library/skills/writing-skills/resource.yaml

@@ -22,6 +22,7 @@ source: official
 license: MIT
 status: stable
 recommended: false
+bundled: false
 aliases:
   - skills/workflow/writing-skills
 lint_exceptions:

package/library/tools/add-node/GUIDE.md

@@ -0,0 +1,14 @@
+# summer_add_node
+
+Add a new node to the scene tree.
+
+Pass the exact res:// scenePath to mutate. The scene does not need to be the
+active editor tab.
+
+Common node types:
+- 3D: Node3D, MeshInstance3D, CharacterBody3D, RigidBody3D, StaticBody3D, Camera3D, DirectionalLight3D, OmniLight3D, SpotLight3D, WorldEnvironment, CollisionShape3D, Area3D
+- 2D: Node2D, Sprite2D, CharacterBody2D, RigidBody2D, StaticBody2D, Camera2D, CollisionShape2D, Area2D, TileMapLayer
+- UI: Control, Label, Button, TextEdit, Panel, VBoxContainer, HBoxContainer, MarginContainer
+- Audio: AudioStreamPlayer, AudioStreamPlayer3D
+
+The parent path uses "./" prefix for relative paths from scene root. E.g., "./World" means the "World" child of the root node.

package/library/tools/align-distribute-3d/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_align_distribute_3d
+
+Align or equal-space an explicit ordered list of 3D subjects along one world-space axis, then save the exact target scene.
+
+Every anchor and extent comes from visible descendant GeometryInstance3D world AABBs (evidence: visual_aabb). The tool never uses editor selection and fails instead of fabricating bounds. It preserves each subject's authored basis and scale, translates only along the normalized axis, and records all changed transforms in one undoable editor operation.
+
+Alignment modes use the first ordered subject's minimum, center, or maximum projected anchor. Distribution modes keep the first and last subjects fixed and honor caller order. distribute_gaps accounts for each subject's projected half-extent and fails if the endpoint span cannot fit non-overlapping equal gaps. The compact result returns ordered before/after origins, resolved spacing, and numeric residuals under 5 KB. On an engine build that predates AlignDistribute3D the result is a structured engine_lacks_op failure naming the fallback.

package/library/tools/app-call/resource.yaml

@@ -6,7 +6,7 @@ use_when:
   - '"nerf the bow using the balance formula in our app"'
   - using logic that lives in an app (a balance formula, an export) while the app is open
 do_not_use_when:
-  - "plain reads and edits of app data: summer_app_data"
+  - "plain reads and edits of app data: apps.read_data, apps.write_data"
 facets:
   lifecycle:
     - build

package/library/tools/app-guide/resource.yaml

@@ -44,8 +44,8 @@ input_schema:
         - design
         - examples
         - types
-      default: all
-      description: "One part of the guide: overview, manifest, sdk, kit, layout, design, examples, or types (the SDK's exact TypeScript types, not in all). Default all"
+      default: overview
+      description: "Start with overview (the default), then read what the app needs: examples (a working app to copy), sdk, manifest, kit, design, layout, types (exact SDK TypeScript types). all returns every section but types (about 100 KB)"
   additionalProperties: false
 authority:
   filesystem: false

package/library/tools/app-page/resource.yaml

@@ -6,7 +6,7 @@ use_when:
   - '"set the budget to 60 in the balance app"'
   - reading what the person has selected in an open app
 do_not_use_when:
-  - "changing shared data with no app open: summer_app_data"
+  - "changing shared data with no app open: apps.write_data"
 facets:
   lifecycle:
     - build

package/library/tools/app-screenshot/resource.yaml

@@ -3,7 +3,7 @@ kind: tool
 version: 1.0.0
 summary: See a Summer App without the person - a headless, read-only render (PNG) with its console, errors, refused calls and declared page.
 use_when:
-  - right after every summer_app_publish, to check the app renders with real data
+  - right after every apps.publish, to check the app renders with real data
   - '"does my app look right on a phone / in dark mode"'
   - finding why an app shows nothing (SDK not connected, script errors)
 do_not_use_when:
@@ -70,6 +70,24 @@ input_schema:
         type: string
         maxLength: 500
       description: Launch params, as in /studio/apps/<id>?key=value
+    steps:
+      type: array
+      maxItems: 5
+      items:
+        type: object
+        properties:
+          click:
+            type: string
+            maxLength: 300
+          press:
+            type: string
+            maxLength: 40
+          wait:
+            type: integer
+            minimum: 0
+            maximum: 3000
+        additionalProperties: false
+      description: "Before the capture, in order: click a CSS selector in the app (\">>>\" reaches inside kit components), press a declared action id, or wait ms. Use it to see a dialog or a second state"
     out:
       type: string
       minLength: 1

package/library/tools/app-tools/resource.yaml

@@ -3,7 +3,7 @@ kind: tool
 version: 1.0.0
 summary: List the agent tools a Summer App declares.
 use_when:
-  - before calling app logic with summer_app_call
+  - before calling app logic with apps.call
   - '"what can our balance app do for me"'
 facets:
   lifecycle:

package/library/tools/attach-to-surface/GUIDE.md

@@ -0,0 +1,15 @@
+# summer_attach_to_surface
+
+Mount a piece on a surface: turn it so its given LOCAL backAxis faces into the surface (opposite the hit normal) with its upAxis kept toward worldUp, then seat its measured back face (the extreme of its visible bounds along backAxis, not its origin) at standoff from the surface. Pipes, gutters, lamps, AC units, signs, fire escapes. Place the piece near its mount first (summer_instantiate_scene with position); this tool turns it and pushes it onto the surface.
+
+Find the surface with surface (a node: the ray runs from the subject's origin to the nearest point of that node's bounds) or ray {origin, direction} (both: the ray, and hits on other nodes are skipped). The ray is physics first; if physics finds nothing it falls back to visual AABBs and says so (the normal is then an AABB face normal). Get backAxis from summer_inspect_asset (the piece's back plane normal), not from a guess.
+
+placeAt "current" (default): the piece keeps its height and its place along the surface and only moves along the surface normal. placeAt "hit": it also slides so the centre of its back face lands on the ray hit point.
+
+Steps (existing ops): a read-only probe (RunSceneScript) reads the piece's bounds in its own axes and casts the ray; one SetProp turns the piece and puts its back face 5 cm in front of the planned seat; SnapToSurface sweeps it along -normal (at most standoff + 0.3) and seats it at standoff (its own physics/visual_aabb evidence). Before saving, the seat is checked:
+- with surface: the seat must be on that node (or inside it), else it is refused;
+- with a ray only: a seat on another node is refused unless it lies on the hit plane (a coplanar neighbour module, warned);
+- the piece must end within maxMove (default 2) of where it started; a longer planned move is refused before anything changes, and so is (with placeAt "current") a ray hit farther than maxMove along the surface from the piece (hit_far_from_piece: aim at the piece, or pass placeAt "hit").
+A refused or failed seat puts the piece back where it started (restored: true), saves nothing, and names the cause: seated_on, the seat's failure_reason, blockers {overlapping, overlaps, first_contact} and a next_step.
+
+Returns {seated_on, final_gap (collider gap from SnapToSurface), back_face_gap (visible back face to the hit plane), moved_by, surface_hit, orientation, back_face_offset, seat {evidence, supportPath, finalGap, gapErrorBound, initiallyOverlapping, ...}, saved, warnings}. A warning visible_back_X_into_surface means the piece's collider sits behind its visible back: add X to standoff.

package/library/tools/batch/GUIDE.md

@@ -0,0 +1,27 @@
+# summer_batch
+
+Execute multiple operations (a multi-node build) in a single call. Each op is forwarded to the engine VERBATIM: this is also how you reach engine ops without a dedicated tool.
+
+UNDO: when nothing in the list forces a split (see SPLITS), the whole batch is ONE undo step (one Ctrl+Z). Single-only ops split the list into sequential requests, and EACH chunk is its own undo step (the receipt shows the chunks).
+
+Ops use the individual tools' format:
+- {"op": "AddNode", "parent": "/", "type": "MeshInstance3D", "name": "Floor"}
+- {"op": "SetProp", "path": "Floor", "key": "position", "value": "Vector3(0, -1, 0)"}
+- {"op": "SetProp", "path": "Floor", "key": "mesh", "value": "PlaneMesh"}
+- {"op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)"}
+
+SPLITS AND SAVE: scenePath selects every mutation target. Send OpenScene (a UI action) separately, never mixed with scene mutations. The tool appends one final SaveScene when the batch mutates a scene; a SaveScene you supply must appear exactly once, as the final op. The engine requires SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads (GetRuntimeSceneTree/GetRuntimeNode) and the Run*/Import* ops to travel alone, so the tool splits the list around them; if a later chunk fails, the receipt names the earlier ops that already applied.
+
+RAW RUNTIME OPS (structured failure_reason passes through verbatim):
+- RunVerification: a hidden, disposable game instance runs a GDScript probe and dies, never touching the editor: {"op": "RunVerification", "probe_source": "...", "max_seconds": 20} returns {ok, results, frames, out_dir}. Probe API: report(name, value) / save_frame(name) / press(action) / key(keycode) / finish(); save_frame() without a name is a script error. Mount scenes deferred (add_child.call_deferred) or the capture can be black; summer_get_agent_playbook has the probe rules.
+- SimulateInput: inject an action/key/mouse/axis into the RUNNING game (summer_play first), sent ALONE: {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. failure_reason "not_running" = start the game first; "unsupported" = the game build predates the handler: use RunVerification or ask the user.
+
+REFUSED: a raw ReplaceNode with scene (it saves the old scene reference; use summer_replace_node) and a raw ConnectSignal (no CONNECT_PERSIST, so the file never holds it; use summer_connect_signal).
+
+REPARENTNODE KEEPS ITS SUBTREE AND IS VERIFIED: the engine op re-owns only the moved node and drops its descendants from the saved file, so the tool saves, sends each ReparentNode alone plus an in-place ReparentNode per scene-owned descendant, then reads the saved .tscn back: persisted:true / verified:true only when every moved node and descendant is at its new path, else failure_reason not_persisted. A move onto a parent with a same-named child is refused (name_collision). scenePath must be a .tscn; Undo cannot share the batch.
+
+PLACED INSTANCES: an InstantiateScene op may carry position, rotation_degrees, scale ([x, y, z] or "Vector3(...)") or transform ("Transform3D(...)"), set on the created node; one op per piece. Each InstantiateScene is its own request and the transforms of a run follow together (up to 200 per request), so N pieces plus the save cost about N + 2 requests and undo steps. Later ops (SetProp, SnapToSurface, the save) see the pieces placed; if one fails, the pieces before it still get their transforms.
+
+RECEIPTS: receipt "summary" returns only counts, failures [{index, op, error}] (index into your ops), created node paths and renames, under 5 KB with any cut declared. Use it for any batch over a few ops: a large full receipt overflows the tool-output limit.
+
+scenePersistence.saved means the SaveScene ran, not what the file holds; verified:true is set only where the tool read the file back.

package/library/tools/camera-bookmark/GUIDE.md

@@ -0,0 +1,12 @@
+# summer_camera_bookmark
+
+Save, list, or delete named camera viewpoints for the edited 3D scene. A bookmark is a fixed pose (position, look_at, fov) stored IN THE PROJECT at res://.summer/camera_bookmarks.json, so it survives sessions and machines — the scene file is never touched.
+
+WHY: screenshots taken from a preset framing re-fit the scene bounds every time, so a before/after pair shifts whenever anything moves; a bookmark is the same pose every time, which makes before/after comparison real. Save once, then reuse on every capture: summer_screenshot target:"scene" framing:"bookmark" bookmark_name:"<name>" (add marks:true for numbered labels mapped to node paths).
+
+action:
+  "save"   — name (1-64 of A-Z a-z 0-9 _ -) plus EITHER position + look_at as Godot literals ("Vector3(x, y, z)", optional fov, default 60) OR neither: omit both to capture the CURRENT editor 3D viewport camera (result pose_source: "editor_viewport" vs "explicit"; overwritten says whether a same-named bookmark was replaced).
+  "list"   — every saved bookmark (names sorted, poses, created timestamps, file path).
+  "delete" — remove one by name (result lists the remaining names).
+
+Failures are structured: bad_args (name grammar, half-given pose, fov outside 1..179, position == look_at), no_editor_camera (no pose given and no 3D viewport camera to capture), not_found (+ available names), io_failed (file unreadable/unwritable; a malformed file is reported, never overwritten). Edit-time only — no running game needed. If this engine build predates the bookmark ops, the result is a structured engine_lacks_op failure (nothing is sent) naming the fallback.

package/library/tools/capture-gameplay/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_capture_gameplay
+
+Capture real gameplay frames without a running editor: starts the game in Summer Engine's offscreen verify instance (--summer-offscreen: a real renderer, a window parked offscreen with no focus, never on screen), lets it run waitSeconds, runs steps, and saves PNG frames of what the game draws, HUD included. Use for store screenshots (1920x1080 landscape or 1080x1920 portrait). The main scene is often a title menu: pass the game's own flags in args (after "--", e.g. ["--autostart"]), a gameplay scene, or steps that play like a player: [{press:"Play"}, {wait:3000}, {key:"Space"}, {action:"jump"}, {click:[960,540]}, {drag:{from:[400,800],to:[1400,800]}}, {shot:true}]. With a shot step, only shot steps save frames; without one, frames are saved after the steps. A step that cannot run (no such button, key or action) becomes a warning. With an editor open, summer_screenshot target game also works. Returns each frame's path, width and height; look at them before using them.

package/library/tools/capture-gameplay/resource.yaml

@@ -1,12 +1,12 @@
 id: tool/capture-gameplay
 kind: tool
-version: 1.0.0
+version: 1.0.1
 summary: Capture real gameplay PNGs (HUD included) offscreen without a running editor; game flags and player steps (press, key, click) get past the title screen.
 use_when:
   - '"take gameplay screenshots for my store page"'
   - '"I need screenshots but the editor is not open"'
   - '"capture a 1920x1080 frame of my game"'
-  - collecting real gameplay screenshots for summer_store_set_art desktop.screenshots or mobile.screenshots
+  - collecting real gameplay screenshots for store.set_art desktop.screenshots or mobile.screenshots
   - every capture shows the title screen — pass the game's flags in args or steps like press Play
 do_not_use_when:
   - the editor is open and the game is running — tool/screenshot with target game shows the live game
@@ -23,7 +23,7 @@ compatibility:
   engine: ">=4.6"
 source: official
 license: MIT
-status: preview
+status: stable
 aliases:
   - summer_capture_gameplay
 implementation:

package/library/tools/check-job/resource.yaml

@@ -3,7 +3,7 @@ kind: tool
 version: 1.0.2
 summary: Check the status of an async generation job by id.
 use_when:
-  - a generation ran without waiting, or timed out, and needs re-checking
+  - a generation timed out and needs re-checking
   - '"is my 3D model / video done yet?"'
   - a generate_* call returned a job id instead of a finished asset
 do_not_use_when:

package/library/tools/clear-console/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_clear_console
+
+Clear the editor's Output panel. Useful before running the game to get a clean slate for error checking.

package/library/tools/connect-ports/GUIDE.md

@@ -0,0 +1,9 @@
+# summer_connect_ports
+
+Move and turn one piece so its port meets another piece's port, facing it: pipe to pipe, duct to duct, gutter section to funnel or outlet. A port is an open-loop id from summer_inspect_asset on that node's scene ("+Y" = the outermost open loop facing +Y in the piece's own axes, "+Y#2" the next one facing +Y; resolved on the live node's meshes in its own frame, so the id is the same in every pose), a Marker3D (or any Node3D) name under the node whose -Z axis points out of the port, or an open-loop index in the same stable order.
+
+The subject turns by the shortest rotation that makes its port direction opposite the target's, then by rollDegrees about the joined axis, then moves so the ports coincide (gap along the target port's direction). rollDegrees: axis = roll_axis in the receipt (the target port direction reversed, pointing into the target); right-hand rule, positive = counter-clockwise seen from inside the target looking back at the subject; zero = the shortest turn from the subject's CURRENT orientation, so the same value differs between start poses. Once the ports are joined, a second call turns by exactly rollDegrees (180 flips a bend's free end to the other side).
+
+Tilt guard: a join that would tilt the subject's up axis (its local +Y) more than maxTiltDegrees (default 5) is refused before anything changes (failure_reason tilt_exceeds_limit, with tilt_degrees and ports_within_limit: the subject ports that would join within the limit, least tilt first). Turning about the up axis is never tilt. Pass allowTilt true for an intended tilt (a bend laid on its side).
+
+One SetProp on transform, saved; a fresh read verifies {distance, angle_degrees, tilt_degrees}. Returns {subject_port {kind, id|name, index, position, direction, radius}, target_port, roll_axis, roll_degrees, rotated_degrees, tilt_degrees, max_tilt_degrees, moved_by, other_ports, verify, warnings}. other_ports: every other port of the subject (its other Marker3D anchors, or its other open loops for an open-loop port) with world position and outward direction AFTER the move, measured by the verify read: read where a bend's free end now points instead of measuring it. Open-loop ports are only as exact as the mesh: check direction_ambiguous warnings and a screenshot.

package/library/tools/connect-signal/GUIDE.md

@@ -0,0 +1,14 @@
+# summer_connect_signal
+
+Connect a signal between two nodes so the connection is SAVED in the scene. Signals are Godot's event system — they notify when something happens.
+
+Common signals:
+- "body_entered" / "body_exited" — Area3D/Area2D detects physics bodies
+- "pressed" — Button clicked
+- "timeout" — Timer finished
+- "area_entered" — Area detects another area
+- "input_event" — CollisionObject received input
+
+The receiver should have the method (a script method, or a built-in such as queue_free); a missing one is saved anyway and reported in warnings. scenePath must be a .tscn.
+
+PERSISTENCE IS VERIFIED: the engine's ConnectSignal op connects without CONNECT_PERSIST, so its connection never reached the file. This tool connects through a RunSceneScript probe with CONNECT_PERSIST (replacing a non-persistent connection of the same pair), saves, reads the saved .tscn back and returns persisted:true / verified:true only when the [connection] line is there; otherwise an error with failure_reason not_persisted. The probe runs in the active tab: a scene in a background tab is brought forward and the user's tab restored (tab_switched). One Ctrl+Z reverts it.

package/library/tools/create-debug-report/GUIDE.md

@@ -0,0 +1,10 @@
+# summer_create_debug_report
+
+Create a support-ready Markdown report for /summer debug.
+
+Use this when the user says "/summer debug", asks to send Summer a bug report,
+or needs a portable artifact from a failing Codex, cloud or agent session. The
+report includes Summer doctor checks, engine health, diagnostics, console
+output, debugger errors/warnings, and an agent handoff prompt. It omits auth
+tokens and project file contents, but the user should still review it before
+sending because local paths and stack traces may appear.

package/library/tools/create-scene/GUIDE.md

@@ -0,0 +1,10 @@
+# summer_create_scene
+
+Create a new empty scene file. Writes a minimal .tscn through the identity-bound engine with a create-only guard: it fails if the path already exists, and it never touches the currently open scene.
+
+The new scene is on disk but NOT opened. Call summer_open_scene to start editing it, then summer_add_node to build it out.
+
+Recommended workflow:
+1) Call summer_get_project_context
+2) Call summer_create_scene with a new res:// path
+3) Call summer_open_scene with that path

package/library/tools/debug-views/GUIDE.md

@@ -0,0 +1,7 @@
+# summer_debug_views
+
+One pose rendered as a grid of debug views next to the beauty pass: beauty, lighting (light only: direction, pools, dead-dark areas), unshaded (albedo: texture quality, value grouping), normals (world-space, x red y green z blue: seams, flipped or faceted normals), overdraw (stacked transparent layers), wireframe (triangle density, floating or duplicated pieces).
+
+Use it on the weakest shot of a sheet to see WHY it reads badly. lighting/unshaded/overdraw/wireframe are the engine's Viewport debug draw modes; normals uses an unshaded override material on a private copy (normal maps and alpha cut-outs are not applied) and works on every renderer. The caption names the method per view.
+
+Returns the grid + caption. Read-only: the scene file, the open tab and the undo history are never touched (the render is an offscreen copy of the SAVED scene). The image arrives inline; the caption carries poses, labels and numbers. Failures are structured (failure_reason), never a silent fallback.

package/library/tools/enable-plugin/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_enable_plugin
+
+Enable an editor plugin in the open project (res://addons/<name>/, for example one paired with a Summer App) and report the real result: enabled with the autoloads it registered, or why it failed (code SCRIPT_ERROR, NOT_TOOL, NOT_EDITOR_PLUGIN, CFG_MISSING, TIMEOUT, ...). Older Summer Engine builds only queue the enable; then the result says queued: true and enabled: null, and you check summer_get_debugger_errors before relying on the plugin.

package/library/tools/export-game/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_export_game
+
+Export the game in the exact file the Summer Games store takes, with the installed Summer Engine headless (no window). format "bundle" (default): the summer.games .zip the Summer apps run on iPhone, Android, macOS and Windows; targets picks the platforms (a game without a server: ios and android only); upload it with summer_publish_build. format "download" with one target: web (an HTML5 .zip on Summer's WebGPU Forward+ web template, played on summer.games), macos (.app zip, macos-universal) or windows (.exe zip, windows-x64); these need the export template from summer_export_templates and are uploaded as store versions. Needs Summer Engine 0.7.0 or newer: an older engine is refused before anything is written (code engine_too_old). A target the installed engine cannot build (android needs 0.7.1) is left out: the other targets export, and skippedTargets plus a warning name it. A game with a server declares its platforms in summer.build.json; when they differ from the exported targets a warning says so (summer_publish_build would be refused), and alignDeclaration:true aligns them. Works without the editor running. Returns path, sha256, size, the manifest or store platform, and warnings.

package/library/tools/export-game/resource.yaml

@@ -1,6 +1,6 @@
 id: tool/export-game
 kind: tool
-version: 1.0.0
+version: 1.0.1
 summary: Export the game in the exact file the Summer Games store takes per platform (iPhone, Android, macOS, Windows bundle; web build; desktop download), headless.
 use_when:
   - '"export my game for summer.games"'
@@ -8,7 +8,7 @@ use_when:
   - '"export my game for iPhone and Android on Summer Games"'
   - '"make a web build of my game for summer.games"'
   - '"export a Mac or Windows download for my store page"'
-  - preparing the bundle that summer_publish_build uploads
+  - preparing the bundle that store.upload_file uploads
 do_not_use_when:
   - exporting for Steam, itch.io, the App Store, Google Play or other stores — skill/export-and-ship
   - the game is still being built; export when the user wants a Build
@@ -23,7 +23,7 @@ compatibility:
   engine: ">=4.6"
 source: official
 license: MIT
-status: preview
+status: stable
 aliases:
   - summer_export_game
 implementation:

package/library/tools/export-templates/GUIDE.md

@@ -0,0 +1,3 @@
+# summer_export_templates
+
+List, download and install Summer Engine export templates from Summer's CDN into the folder the installed engine reads, checking each file's sha256. Needed only for summer_export_game format "download": web (Summer's WebGPU Forward+ template), macos, windows. Store bundles (format "bundle") need no template. action list shows what is installed and published; action install fetches the platforms asked (default web).