summer-engine 2.6.6 → 2.8.0

package/skills/deployment/export-and-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: export-and-ship
-description: Use when the user is ready to export a build for distribution to Steam, itch.io, web (HTML5), iOS, Android, or any combination. Validates icons, store banners, screenshots, build config, and runs a pre-flight checklist before producing a release build. Trigger on "export", "ship", "release", "build", "Steam", "itch", "HTML5", "iOS", "Android", "submit", "publish".
+description: Use when the user wants to assess or prepare a Summer game export. Inventories the templates and targets actually available in the installed Summer Engine build, validates release assets and configuration, and produces only locally supported builds after approval. It does not publish, upload, host, or submit a game. Trigger on "export", "ship", "release", "build", "Steam", "itch", "HTML5", "iOS", "Android", "submit", "publish".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment
@@ -13,21 +13,54 @@ paths: ["**/*.gd", "**/*.tscn", "project.godot", "export_presets.cfg", "**/*.png
 
 ## Overview
 
-Shipping is a checklist, not a creative act. This skill walks the platform-specific asset and config requirements, runs a pre-flight check against the project, and produces a release build only after every blocker is green. Better to fail at this step than fail submission.
+Shipping is a checklist, not a creative act. This skill first inventories the
+export templates and targets actually present in the installed Summer Engine
+build. It can then validate platform-specific assets and configuration and
+produce a local build for an available target after approval. It does not
+upload, host, submit, or promise a target that is absent from the installation.
 
-**Core principle:** every platform has a list. Read the list, satisfy the list, ship.
+**Core principle:** prove the target is locally available, then read its list,
+satisfy the list, and build. Treat store submission and hosting as separate
+user-controlled workflows.
 
 ## Steps
 
-### 1. Pick the destination(s)
+### 1. Prove local export capability
 
-Open with the question. Multi-select.
+Do this before presenting destinations, writing presets, or constructing an
+export command.
 
-> Where to? Pick all that apply: **Steam** / **itch.io** / **web (HTML5)** / **iOS App Store** / **Google Play** / **macOS DMG** / **Windows installer** / **other**.
+1. Read `engineBinaryPath` from `summer_get_project_context`.
+2. Resolve the matching export-template directory for that exact Summer
+   technical base.
+3. Inventory the installed templates and any `custom_template/release` paths
+   already configured in `export_presets.cfg`.
+4. Build a capability table with `available`, `missing prerequisite`, or
+   `impossible on this build` for every requested target.
+
+A stock Summer 4.6.1 Mono install has only the macOS template. Web export is
+incompatible with that Mono build. Windows, Linux, Android, and iOS require a
+matching custom template or an external CI/build environment, plus their
+platform toolchains where applicable.
+
+**Hard gate:** an absent template or toolchain means the target is unavailable.
+Do not create its preset, recommend it as a local option, or invoke an export
+command. Route it to an explicitly configured external CI job or stop and tell
+the user which prerequisite is missing. An export pack is not a runnable
+platform build and must not be presented as one.
+
+### 2. Pick among proven destinations
+
+Offer only targets marked `available` by step 1. Record other requested
+destinations as blocked follow-ups with their exact prerequisite.
+
+> Locally proven targets: **macOS**. Requested but blocked: **Windows**
+> (matching template or external CI), **Web** (non-Mono build), **Android**
+> (template + Android toolchain). Which proven target should I prepare?
 
 Each destination has a different list. Multiple destinations = multiple lists. Don't shortcut — the iOS list does not satisfy the Steam list.
 
-### 2. Run the pre-flight checklist
+### 3. Run the pre-flight checklist
 
 Always do this first, regardless of destination.
 
@@ -39,7 +72,9 @@ summer_get_console                # any "import failed" warnings?
 summer_get_scene_tree             # is the main scene set?
 ```
 
-**Fallback (no MCP):** ask the user to confirm via the Godot editor: Project → Project Settings → Application → Run → Main Scene is set; no errors in Output panel.
+**Fallback (no MCP):** ask the user to confirm in Summer Engine: Project →
+Project Settings → Application → Run → Main Scene is set, and the Output panel
+has no errors.
 
 #### Pre-flight blockers (any one = stop)
 
@@ -59,9 +94,11 @@ If any check fails, list them in one message and ask:
 
 > Pre-flight failed on N items: <list>. Fix these before exporting? I can take them one by one.
 
-### 3. Per-platform asset requirements
+### 4. Per-platform distribution requirements
 
-Walk the list for each chosen destination. Each is non-negotiable.
+These lists describe distribution requirements only. They do not establish
+local export capability. Walk a list only after step 1 proves its target or
+the user has selected an external build environment that does.
 
 #### a) Steam
 
@@ -81,7 +118,8 @@ Walk the list for each chosen destination. Each is non-negotiable.
 
 Build config for Steam:
 
-- Export preset: **Windows Desktop** (x86_64) + **Linux** (x86_64) + **macOS** (universal). Steam requires all three for max reach; 99% of Steam revenue is Windows but Linux/macOS doesn't hurt.
+- Export only the platform builds proven in step 1. Additional Steam platforms
+  require their own matching template or external build job.
 - Export options: `Embed PCK = true` for single-EXE distribution.
 - Steam SDK integration: GodotSteam (`https://godotsteam.com`) is the standard. Add the GDExtension before exporting.
 - App ID must be set in the Steam SDK init code.
@@ -100,13 +138,16 @@ Lower bar than Steam. itch is forgiving.
 | Build files | ZIP per platform OR `butler` upload | Yes |
 
 Build config:
-- Export preset: Windows + macOS + Linux; package as ZIP.
+- Package each proven platform build as a ZIP.
 - Or use `butler push` (itch's CLI) for atomic versioning and patches.
-- Web build (HTML5) is free real estate on itch — also do it.
+- A browser build is optional and requires a separately proven non-Mono Web
+  export environment.
 
-#### c) Web (HTML5)
+#### c) Web (HTML5) — unavailable on the stock Mono build
 
-Browser export. Constraints:
+Do not recommend or attempt this target from the stock Summer installation.
+Route it to a verified non-Mono Summer-compatible build environment first.
+Once that prerequisite is proven, these browser constraints apply:
 
 - No threading without `cross-origin-isolated` headers (most hosts don't set them).
 - No ENet — use WebSocket / WebRTC if multiplayer.
@@ -173,7 +214,7 @@ Build config:
 - Code-signing certificate ($75–$300/year from a CA) — without it, SmartScreen flags the EXE.
 - Installer: NSIS or InnoSetup are the standards. Or just ship a ZIP.
 
-### 4. Build config consistency check
+### 5. Build config consistency check
 
 Before producing builds, verify `export_presets.cfg` for each target:
 
@@ -186,34 +227,59 @@ For each preset:
 | Field | Production value | Why |
 |---|---|---|
 | `binary_format/embed_pck` | `true` | Single EXE per platform |
-| `debug` | `false` | Debug builds leak source paths and run slower |
 | `texture_format/etc2_astc` | `true` for mobile | Smaller texture compression |
 | `application/short_version` | matches `application/config/version` | Steam reads it |
-| `script/encryption_key` | set if you don't want PCK extracted | Optional but recommended for paid games |
+| `script_encryption_key` in `export_credentials.cfg` | set only when the user explicitly chooses script encryption | The similarly named preset field does not exist |
 | `application/icon` | path to your `.ico` / `.icns` / `.png` | Otherwise generic Godot icon ships |
 
-### 5. Propose the build sequence
+### 6. Propose the build sequence
 
-> Pre-flight: clean. Targets confirmed: Steam (Win + Mac + Linux) + itch (same builds) + web. Required assets: I see all icons + 5 screenshots in `marketing/`. Missing: trailer (Steam blocks Coming Soon → Released without one). May I produce the builds now and flag the trailer as a follow-up?
+> Capability proof: macOS available locally; Windows and Linux require external
+> CI; Web is unavailable on this Mono build. Pre-flight is clean for the macOS
+> preset. May I produce that one proven build now?
 
-### 6. Produce the builds
+### 7. Produce a proven build
 
-Godot's CLI export is the standard scripted path:
+CLI export is the standard scripted path. **Get the binary from `summer_get_project_context` → `engineBinaryPath`.** Do not type an engine binary name from memory:
 
+- There is no `godot` on a Summer user's machine.
+- `summer` is the npm CLI, not the engine. It takes subcommands and would never accept `--export-release`.
+- On macOS the engine is `/Applications/Summer.app/Contents/MacOS/Summer`; on Windows, `%LOCALAPPDATA%\Summer\current\Summer.exe`.
+
+After step 1 has marked a preset `available`, substitute only that exact proven
+preset and output:
+
+```bash
+ENGINE=<engineBinaryPath>
+PROJ=<absolute project dir>
+PROVEN_PRESET=<exact available preset name>
+PROVEN_OUTPUT=<output path valid for that target>
+
+"$ENGINE" --headless --path "$PROJ" --export-release "$PROVEN_PRESET" "$PROVEN_OUTPUT"
 ```
-godot --headless --export-release "Windows Desktop" build/win/MyGame.exe
-godot --headless --export-release "Linux" build/linux/MyGame.x86_64
-godot --headless --export-release "macOS" build/mac/MyGame.app
-godot --headless --export-release "Web" build/web/index.html
-godot --headless --export-release "Android" build/android/MyGame.aab
-godot --headless --export-release "iOS" build/ios/MyGame.xcodeproj
-```
 
-For Summer Engine: replace `godot` with `summer` (or the local binary path). Same flags.
+`--path` is not optional in a script — without it the export targets the current working directory.
+
+The quoted preset name must match a `name=` in `export_presets.cfg` exactly. That file is plain text you can write yourself if it is missing: a hand-written preset plus this command was measured producing a runnable 144 MB `.app`, exit code 0.
+
+To enable another target, prove one of these before returning to step 2:
+
+- a matching installed export template;
+- a valid `custom_template/release="<path>"` for the current technical base;
+- an external CI/build job with the matching template and platform toolchain.
+
+### Export-option cautions
+
+- **`script/encryption_key` does not exist.** The real key is `script_encryption_key`, and it lives in a separate `export_credentials.cfg`, not `export_presets.cfg` (`editor/export/editor_export.cpp:101,372-373`). Writing the wrong name produces an **unencrypted build with no error at all**.
+- **There is no `debug` field in a preset.** Debug versus release is chosen by `--export-debug` versus `--export-release`, nothing else.
+
+On Apple Silicon, `binary_format/architecture="arm64"` is the natural guess, and it fails leaving a **0-byte `.app` that looks like success**. Only `"universal"` ships.
+
+See `summer:headless-scripting` for the wider pattern this is one instance of.
 
 If the user is on a CI system (GitHub Actions etc), this is the right place to point them at a cross-compile workflow — Godot can export Windows + Linux from a Linux runner.
 
-### 7. Verify each build
+### 8. Verify each build
 
 For each build:
 - Launch it. Confirm the title screen renders.
@@ -221,7 +287,7 @@ For each build:
 - Check the file size (anything over 500 MB needs justification — usually unstripped textures or unused assets).
 - For mobile: install on a real device, not just the emulator.
 
-### 8. Submit / upload
+### 9. Hand off distribution
 
 Per platform, point the user at the correct upload path:
 
@@ -248,7 +314,7 @@ Use this as a one-shot grep before any export:
 | Icon assets present | Per-platform icon files exist at the paths referenced in `export_presets.cfg` |
 | LICENSE file | Exists at repo root |
 | Attribution file | Exists if any community assets used |
-| Export preset `debug = false` | For all release presets |
+| Release mode selected | Build invocation uses `--export-release` |
 | Export preset `embed_pck = true` | For all desktop release presets |
 | `.gitignore` excludes build artifacts | `build/`, `.godot/`, `.import/`, `*.tmp` listed |
 | Screenshots ≥ minimum count for platform | 3 for itch, 5 for Steam, 2 for Play |
@@ -258,7 +324,7 @@ Use this as a one-shot grep before any export:
 
 | Don't | Do | Why |
 |---|---|---|
-| Ship debug builds to Steam | `debug = false` in release export preset | Slower, leaks paths, larger |
+| Ship debug builds to Steam | Use `--export-release` after capability proof | Debug builds leak paths and run slower |
 | Use 256×256 icon for iOS | 1024×1024 (Apple downscales) | iOS rejects undersized icons |
 | Skip Steam trailer | Record at least 30 sec gameplay before launch | Steam blocks the release without it |
 | Ship APK to Play Store | Build AAB | Play requires AAB since 2021 |
@@ -280,7 +346,7 @@ Use this as a one-shot grep before any export:
 
 ## Collaborative protocol
 
-This skill produces release artifacts. Always ask before each build is invoked. Group platforms — "I'm about to build Windows + Mac + Linux release configs into `build/`. OK?". See `references/collaborative-protocol.md`.
+This skill produces release artifacts. Always ask before each build is invoked. Group platforms — "I'm about to build Windows + Mac + Linux release configs into `build/`. OK?". See `../../../references/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -288,9 +354,10 @@ No template — this is a workflow. Each project's export config and store asset
 
 ## See also
 
-- `references/mcp-tools-reference.md` — full MCP tool list
-- `references/godot-version.md` — Godot 4.5 export-template versioning
-- `references/collaborative-protocol.md` — "May I write" pattern
+- `../../../references/mcp-tools-reference.md` — full MCP tool list
+- `../../../references/godot-version.md` — Summer compatibility and
+  export-template versioning
+- `../../../references/collaborative-protocol.md` — "May I write" pattern
 - `deployment/export-presets/SKILL.md` — preset config deep dive
 - `deployment/web-html5-export/SKILL.md` — HTML5-specific traps
 - `deployment/steam-uploader/SKILL.md` — `steamcmd` + GodotSteam (when shipped)

package/skills/deployment/remote-deploy/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: remote-deploy
+description: Use when the user wants to run or test the game on a real target instead of the editor — a phone, tablet, or another computer ("deploy to my phone", "run on device", "test on Android/iOS", "remote deploy", "one-click deploy", "play on hardware"). Covers the topnav Remote Deploy button, runnable export presets, export templates, and on-device remote debugging. Use when the Remote Deploy button is greyed out and the user wants to know why.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: deployment
+user-invocable: true
+allowed-tools: Read Grep Edit summer_project_setting summer_get_diagnostics summer_get_console summer_get_script_errors
+paths: ["project.godot", "export_presets.cfg"]
+---
+
+# /remote-deploy — Test the Game on a Real Device
+
+## Overview
+
+Remote Deploy runs the game on an actual target device — a phone, tablet, or another machine — instead of inside the editor. It exports a **debug** build, installs and launches it on the device, and connects the running game back to the editor's debugger so the Output panel, errors, breakpoints, and profiler all work exactly like a local run.
+
+**Core principle:** Remote Deploy is "Play, but on the hardware." Same debug loop, real device.
+
+**Capability gate comes first:** before adding a Runnable preset or telling the
+user to pick a device, inventory the exact Summer build's export templates and
+the platform toolchain. A stock Summer 4.6.1 Mono install has only the macOS
+template. It cannot export Web, and Android/iOS/Windows/Linux are unavailable
+until a matching custom template or external build environment is configured.
+Never recommend or attempt a Remote Deploy target that has not passed this
+proof.
+
+It is **not** the same as two neighbours:
+
+| Action | What it does | Use it for |
+|---|---|---|
+| **Play** (▶) | Runs in the editor (embedded or windowed) | Fast iteration on the dev machine |
+| **Remote Deploy** | Debug build → installs + runs on a device, remote-debugged | Testing real input/perf/screen on hardware |
+| **export-and-ship** (`summer:export-and-ship`) | Supported local release builds | Preparing an artifact for a separate user-controlled distribution workflow |
+
+If the user wants a release build for Steam / itch / the App Store, that is `summer:export-and-ship`, not this.
+
+## Where it is in the UI
+
+- **Agent-layout topnav:** the button with the remote-play icon, immediately right of the **Play/Stop** button and the **`▾`** run-options dropdown. Hover tooltip reads **"Remote Deploy"**.
+- Clicking it opens a **dropdown of detected targets**, grouped by platform (e.g. an `Android` header with each connected device under it). Picking a target deploys and runs there.
+- It is **disabled (greyed out)** with the tooltip **"No Remote Deploy export presets configured."** until the prerequisites below are met. A greyed button is the #1 thing users ask about — it almost always means "no runnable preset or no device detected," not a bug.
+
+## Step 1 — prove the requested target is available
+
+Use `summer_get_project_context` to identify the exact engine binary and
+technical base, inspect its matching export-template directory, then check the
+requested platform toolchain. Report one of:
+
+- `available`: matching template and toolchain are present;
+- `blocked`: name the missing template, toolchain, signing, or device
+  prerequisite;
+- `impossible on this build`: Web on the stock Mono build.
+
+Stop on `blocked` or `impossible`. Route the user to template installation,
+custom-template setup, or an external CI/device workflow. Do not add a preset
+as if that made the target runnable.
+
+## Step 2 — prerequisites for a proven target
+
+The button auto-enables the moment a runnable preset **and** at least one detected target both exist for the same platform.
+
+| Requirement | How to satisfy it | Why it matters |
+|---|---|---|
+| A **proven template and toolchain** | Complete step 1 | Without both, a visible target still fails at deploy time. |
+| A **runnable export preset** for that proven platform | Project → Export → add the proven preset → toggle **Runnable** on | A preset that exists but isn't marked Runnable does **not** count. |
+| A **detected target** | For example, an authorized Android device or a connected, trusted iOS device | The button enables only when at least one target is reported for a runnable platform. |
+
+**Important nuance:** the button does **not** pre-check that templates/toolchain are installed. Enable state is gated only on *runnable preset + detected target*. If templates or the toolchain are missing, the deploy **fails at run time** and the errors appear in a result dialog. So:
+
+> **Runnable preset + a detected device make the button appear/enable. Installed export templates make the deploy actually succeed.**
+
+This matters when guiding a user mid-setup (e.g. building out a mobile flow): you can see the button enable as soon as a phone is plugged in and the preset is Runnable, even before templates finish downloading.
+
+## Step 3 — deploy after proof (the flow)
+
+1. The editor continuously polls the export platforms and rebuilds the dropdown: each runnable platform, with each of its detected devices listed underneath.
+2. The user picks a target. Summer Engine exports a **debug** build for that
+   preset when the matching template and toolchain are installed.
+3. The build is installed and launched on the device (e.g. `adb install` + launch for Android).
+4. The running game opens a **remote-debug** connection back to the editor — Output, the debugger, and the profiler reflect the on-device session. Stop it from the editor like any normal run.
+5. Any export/deploy error (missing template, no toolchain, unsigned build, device went away) is surfaced in a **result dialog**. Read it; it names the prerequisite to fix.
+
+## Mobile paths after capability proof
+
+**Android**
+1. First prove a matching Android template, Android SDK, `adb`, and debug
+   signing are installed. Otherwise stop.
+2. Enable Developer Options → USB debugging on the phone; plug it in; accept the "Allow USB debugging?" prompt.
+3. Confirm `adb devices` lists it as `device` (not `unauthorized`).
+4. Project → Export → Android preset → **Runnable** on.
+5. The phone appears in the Remote Deploy dropdown → pick it.
+
+**iOS**
+1. First prove a matching iOS template, Xcode toolchain, and signing identity
+   are installed. Otherwise stop.
+2. Connect and trust the device; ensure a valid signing team in the iOS preset.
+3. The device appears in the dropdown → pick it.
+
+**Web**
+
+Web is unavailable on the stock Summer Mono build. Do not add a Web Runnable
+preset or direct the user to a browser target. Use ordinary local Play for a
+sanity check, or first provision and verify a separate non-Mono-compatible
+export environment.
+
+## Guiding the user (orchestrator playbook)
+
+When a user says "deploy to my phone" / "run this on device" and the button is greyed:
+
+1. **Prove target capability first** — inspect the exact build's matching
+   template directory and platform toolchain. Stop or route externally if
+   either is absent; Web is impossible on the stock Mono build.
+2. **Check the build is healthy** — a project with script errors won't export.
+   - `summer_get_script_errors` and `summer_get_diagnostics` clean? If not, fix those before anything else.
+   - `summer_get_console` for "import failed" noise.
+3. **Confirm a runnable preset exists** for the proven target platform — Read/Grep `export_presets.cfg` for the platform and a `runnable=true` entry. If missing, walk them through Project → Export → add preset → mark Runnable.
+4. **Confirm the main scene is set** — `summer_project_setting` / `project.godot` `application/run/main_scene`. A deploy to a blank main scene launches to nothing.
+5. **Confirm a device is detected** — plugged in, debugging enabled, authorized.
+6. Then point them at the topnav **Remote Deploy** button → pick the device.
+
+Order matters: capability proof → healthy project → preset → device. The
+button can enable before the build is actually possible, so its visible state
+never replaces the proof.
+
+## Common mistakes
+
+- **Confusing it with shipping.** Remote Deploy makes *debug* builds for testing. Store/distribution builds are `summer:export-and-ship`.
+- **Preset exists but isn't Runnable** → button stays greyed. The Runnable toggle is the gate, not the preset's existence.
+- **Expecting it to work without export templates** → button may be enabled (device detected) but the deploy then fails in the result dialog. Install templates.
+- **Android device `unauthorized`** in `adb devices` → the device won't show as a target. Re-accept the USB-debugging prompt on the phone.
+- **Trying to script it via MCP** — there is no `summer_*` tool that triggers Remote Deploy; it is a UI action. The orchestrator's job is to get the prerequisites green and point the user at the button.
+
+## Quick reference
+
+| Button state | Meaning | Fix |
+|---|---|---|
+| Greyed, "No Remote Deploy export presets configured." | No runnable preset **or** no detected device | Add a Runnable preset; connect/authorize a device |
+| Enabled, dropdown lists devices | Ready to deploy | Pick a device to build + run |
+| Deploy fails in result dialog | Templates/toolchain/signing/device issue | Read the dialog; install the named missing piece |

package/skills/gameplay-mechanics/auto-fire-targeting/SKILL.md

@@ -167,4 +167,29 @@ Test scenario: spawn a single weak enemy directly in front of the player at poin
 Before: 5-15 bullets continue past the corpse over the next ~0.5s.
 After: 1-2 bullets continue (the ones that were already past the half-flight point), the rest of the fire pool redirects to whatever target Targeting picks next, or stops if there's none in range.
 
-Use `summer_get_diagnostics` to confirm no new errors. Use `summer_inspect_node` on a sample enemy mid-fight to confirm `pending_damage` is being incremented and decremented as expected.
+Use `summer_get_diagnostics` to confirm no new errors.
+
+`summer_inspect_node` will **not** show you `pending_damage` mid-fight. It reads
+the edited scene in the editor — the response even tags itself
+`provenance: editor_scene` — so it reports the saved node, not the live
+instance. Runtime values need a runtime probe.
+
+The route that works from MCP is the `RunVerification` op, sent through
+`summer_batch`. It spins up a hidden, disposable game instance that runs a
+GDScript probe and exits; it never touches the editor:
+
+```
+summer_batch(ops=[{
+  "op": "RunVerification",
+  "max_seconds": 20,
+  "probe_source": "extends SummerProbeBase\nfunc _ready():\n\tawait super._ready()\n\t# spawn one enemy, fire at it, then:\n\treport('pending_damage', enemy.pending_damage)\n\tfinish()"
+}])
+```
+
+Probe API: `report()`, `save_frame()`, `press()`, `key()`, `finish()`. Returns
+`{ok, results, frames, out_dir}`.
+
+Do **not** reach for `SimulateInput` here. It is only reachable from the
+in-editor chat bridge; an MCP or CLI caller gets
+`{ok: false, failure_reason: "unsupported_transport"}` back. Drive input from
+inside the probe with `press()` / `key()` instead.

package/skills/gameplay-mechanics/design-mechanic/SKILL.md

@@ -126,15 +126,27 @@ Show this to the user. Ask:
 **Preferred (Summer MCP):**
 
 ```
-summer_get_scene_tree                       # confirm Player exists where expected
-summer_add_node(parent="./World/Player", type="GPUParticles3D", name="DoubleJumpFX")
-summer_set_prop("./World/Player/DoubleJumpFX", "emitting", "false")
-summer_add_node(parent="./World/Player", type="AudioStreamPlayer3D", name="JumpAudio")
-summer_input_map_bind(name="jump", events=[{type:"key", key:"Space"}])  # idempotent
-summer_save_scene
-summer_get_script_errors
+summer_get_scene_tree()                     # confirm Player exists where expected
+summer_add_node(scenePath="res://main.tscn", parent="./World/Player", type="GPUParticles3D", name="DoubleJumpFX")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Player/DoubleJumpFX", key="emitting", value="false")
+summer_add_node(scenePath="res://main.tscn", parent="./World/Player", type="AudioStreamPlayer3D", name="JumpAudio")
+summer_input_map_bind(name="jump", events=[{"type": "key", "key": "Space"}])   # idempotent
+summer_save_scene(scenePath="res://main.tscn")
+summer_get_script_errors(path="res://scripts/player_controller.gd")
 ```
 
+Argument notes, all of which the tool schema enforces:
+
+- `scenePath` is required on `summer_add_node`, `summer_set_prop` and
+  `summer_save_scene`. It names the exact `res://` scene; there is no
+  "current scene" default.
+- `summer_set_prop` takes named `path` / `key` / `value` — not positional.
+- `summer_input_map_bind` events are dicts. `{"type": "key", "key": "Space"}`
+  works; key names go through Godot's keycode table, so `W`, `Space`, `Shift`,
+  `Escape` resolve and typos silently produce no event.
+- `summer_get_script_errors` checks one file and requires `path`. Use
+  `summer_get_diagnostics()` (no args) for a project-wide check.
+
 **Fallback (no MCP):** Print the `.tscn` snippet for the user to paste:
 
 ```
@@ -148,7 +160,7 @@ lifetime = 0.4
 
 ### 7. Write the GDScript stub
 
-Stub only — implementation is the next session. Use `references/gd-style.md` conventions. For double-jump:
+Stub only — implementation is the next session. Typed GDScript throughout (see `summer:scripting-patterns/gdscript-patterns`). For double-jump:
 
 ```gdscript
 class_name PlayerController
@@ -236,12 +248,12 @@ Ask:
 | Hand-wave depth | "Players will use it strategically" is not depth. Name the choice the player makes. |
 | Tunables hard-coded as `const` | Use `@export` so designers tune in the inspector. |
 | Adding the mechanic without the FX/audio nodes | Without nodes for feedback, the mechanic ships feeling cheap. Scaffold the nodes alongside the script. |
-| Setting `position` for movement instead of `velocity` | Physics objects use `velocity` in `_physics_process`. See `references/gd-style.md`. |
-| Calling SetResourceProperty on inline sub_resources | Silent fail. See `references/mcp-tools-reference.md` § Trap. |
+| Setting `position` for movement instead of `velocity` | Physics objects use `velocity` in `_physics_process`. |
+| Calling SetResourceProperty before the property holds a resource | Explicit `resource is null` error, not a silent drop. Assign the resource first (`summer_set_prop key="mesh" value="BoxMesh"`), then set its sub-properties. Scene-embedded sub_resources are fully supported targets. |
 
 ## Collaborative protocol
 
-This skill writes scene nodes and one or more files (`.gd`, `.summer/mechanics/<name>.md`). Group writes into one ask per phase. See `references/collaborative-protocol.md`.
+This skill writes scene nodes and one or more files (`.gd`, `.summer/mechanics/<name>.md`). Group writes into one ask per phase.
 
 ## Want a working starter?
 
@@ -254,10 +266,6 @@ This skill is a workflow that designs and scaffolds — the templates are runnab
 
 ## See also
 
-- `references/collaborative-protocol.md`
-- `references/mcp-tools-reference.md`
-- `references/gd-style.md` — GDScript conventions
-- `references/godot-version.md` — Godot 4.5 API notes
 - `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md` this skill reads
 - `level-design/design-level/SKILL.md` — design the levels that exercise the mechanic
 - `character-controllers/fps-controller/SKILL.md` — FPS movement scaffolding

package/skills/level-design/design-level/SKILL.md

@@ -150,9 +150,20 @@ Show the skeleton. Ask:
 
 **Preferred (Summer MCP):**
 
+`summer_create_scene` takes `path`, `rootName`, and a mandatory safety gate.
+There is no `root_type` or `root_name` argument. The tool refuses to run unless
+`allow_temporary_scene_mutation` is explicitly true, because of how it works: it
+opens the currently-open scene (or the project's main scene) as a template,
+removes every child, renames the root, saves-as to the new path, then reopens
+the original. Ask the user before setting the flag.
+
+The consequence to plan around: **the new scene's root node type is copied from
+the template's root**, not chosen by you. Create levels from a scene whose root
+is already `Node3D`, or fix the root afterwards in the editor.
+
 ```
-summer_create_scene(path="res://levels/level_01.tscn", root_type="Node3D", root_name="World")
-summer_add_node(parent="./World", type="Node3D", name="Geometry")
+summer_create_scene(path="res://levels/level_01.tscn", rootName="World", allow_temporary_scene_mutation=true)
+summer_add_node(scenePath="res://levels/level_01.tscn", parent="./World", type="Node3D", name="Geometry")
 summer_add_node(parent="./World/Geometry", type="Node3D", name="IntroAtrium")
 summer_add_node(parent="./World/Geometry", type="Node3D", name="Corridor")
 summer_add_node(parent="./World/Geometry", type="Node3D", name="PeakArena")
@@ -167,9 +178,15 @@ summer_add_node(parent="./World/Triggers", type="Area3D", name="E2_GateTrigger")
 summer_add_node(parent="./World", type="Node3D", name="Lighting")
 summer_add_node(parent="./World/Lighting", type="WorldEnvironment", name="WorldEnvironment")
 summer_add_node(parent="./World/Lighting", type="DirectionalLight3D", name="Sun")
-summer_save_scene
+summer_save_scene(scenePath="res://levels/level_01.tscn")
 ```
 
+Every `summer_add_node` above takes the same required
+`scenePath="res://levels/level_01.tscn"`; it is elided after the first line only
+to keep the tree readable. A call without `scenePath` is rejected by the tool
+schema. Better still, send the whole block as one `summer_batch(scenePath=...,
+ops=[...])` so the user can undo the skeleton with a single Ctrl+Z.
+
 This is a **skeleton, not playable geometry**. Markers and Area3Ds, no meshes, no enemy scripts. Implementation in subsequent sessions / templates.
 
 **Fallback (no MCP):** Print the `.tscn` file contents for the user to save manually.
@@ -239,11 +256,11 @@ End with:
 | Reward gating too generous | Free heals before the peak deflate the peak. Gate them after the test. |
 | Blending level types | Stealth + puzzle + boss in one level = three half-baked levels. Pick one. |
 | Building geometry before the skeleton | Skeleton-first lets you iterate on layout cheaply. Geometry comes after the design is locked. |
-| Calling SetResourceProperty on inline sub_resources | Silent fail. See `references/mcp-tools-reference.md` § Trap. |
+| Calling SetResourceProperty before the property holds a resource | Explicit `resource is null` error, not a silent drop. Assign the resource first (`summer_set_prop key="mesh" value="BoxMesh"`), then set its sub-properties. Scene-embedded sub_resources are fully supported targets. |
 
 ## Collaborative protocol
 
-This skill creates a new scene file (`.tscn`) and a design doc (`.md`). Group writes per phase. Always ask before `summer_create_scene`. See `references/collaborative-protocol.md`.
+This skill creates a new scene file (`.tscn`) and a design doc (`.md`). Group writes per phase. Always ask before `summer_create_scene`.
 
 ## Want a working starter?
 
@@ -256,9 +273,6 @@ The skeleton this skill produces is meant to be filled in via `/summer:design-me
 
 ## See also
 
-- `references/collaborative-protocol.md`
-- `references/mcp-tools-reference.md`
-- `references/godot-version.md` — Godot 4.5 API notes
 - `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md`
 - `gameplay-mechanics/design-mechanic/SKILL.md` — designs the verbs the level exercises
 - `ai-and-npcs/design-npc/SKILL.md` — designs the enemies the encounters reference

package/skills/level-design/scene-to-level/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-to-level
-description: Use when the user wants to go from a single scene reference image (a screenshot or concept art of how the final game should look) all the way to a playable Godot scene populated with the right assets and terrain. Orchestrates concept → asset pack → terrain → composition → scene assembly. Trigger on "build this scene", "make this playable", "I want a level that looks like this", "from a screenshot to a game", "implement this concept".
+description: Use when the user wants to go from a scene reference image or concept art to a playable Summer Engine scene populated with the right assets and terrain. Orchestrates concept, asset pack, terrain, composition, and scene assembly. Trigger on "build this scene", "make this playable", "I want a level that looks like this", "from a screenshot to a game", "implement this concept".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: level-design
@@ -11,7 +11,9 @@ paths: ["**/*.tscn", "**/*.gd", "assets/**", ".summer/**", "levels/**"]
 
 # scene-to-level — From a reference image to a playable scene
 
-This is the **orchestrator** skill. It doesn't generate art, doesn't slice sheets, doesn't write game code — it routes the user through the chain of skills that do, and stitches their outputs together into a placeable Godot scene.
+This is the **orchestrator** skill. It does not generate art, slice sheets, or
+write game code. It routes the user through the chain of skills that do and
+stitches their outputs into a placeable Summer Engine scene.
 
 Use it when the user shows you a screenshot or concept image and says "build this." The output is a `.tscn` you can hit play on, populated with assets that match the reference's style.
 
@@ -53,16 +55,20 @@ Use it when the user shows you a screenshot or concept image and says "build thi
    / etc. (see summer:2d-assets/use-widget-asset)
 
 4. Compose the scene:
-   - summer_create_scene with a Node2D / Control root depending on the
-     scene type
-   - Add a TileMap node for terrain; assign the generated tileset
-     resource
+   - summer_create_scene(path=..., rootName=..., allow_temporary_scene_mutation=true).
+     It has no root-type argument: the new scene's root is copied from the
+     currently-open (or main) scene's root, children stripped and root renamed.
+     Start from a 2D scene if you want a Node2D root.
+   - Add a TileMapLayer node for terrain; assign the generated tileset
+     resource (`TileMap` is deprecated on the current Summer technical line)
    - Place props as Sprite2D / TextureRect children, positioned to
      match the reference's composition
    - Wire UI as Control nodes anchored to the viewport
+   - Every mutation tool here takes a required `scenePath`
 
 5. Validate:
-   - summer_get_script_errors
+   - summer_get_diagnostics (no args, project-wide) — or
+     summer_get_script_errors(path="res://...gd") for one specific file
    - summer_play (the user takes over from here)
 ```