summer-engine 2.6.6 → 2.7.0

package/dist/mcp/tools/scene-tools.js

@@ -2,6 +2,27 @@ import { z } from "zod";
 import { withEngine } from "./with-engine.js";
 import { readFile } from "fs/promises";
 import { join } from "path";
+function sceneMutationOps(ops) {
+    const saveIndexes = ops
+        .map((op, index) => op.op === "SaveScene" ? index : -1)
+        .filter((index) => index >= 0);
+    if (saveIndexes.length > 1) {
+        throw new Error("A scene mutation batch may contain only one SaveScene");
+    }
+    if (saveIndexes.length === 1) {
+        if (saveIndexes[0] !== ops.length - 1) {
+            throw new Error("SaveScene must be the final operation in a scene mutation batch");
+        }
+        return ops;
+    }
+    return [...ops, { op: "SaveScene" }];
+}
+function executeSceneMutation(client, scenePath, ops, options) {
+    return client.executeIdentityBoundOps(sceneMutationOps(ops), {
+        ...(options ?? {}),
+        scenePath,
+    });
+}
 async function readMainSceneFromProject(projectPath) {
     if (!projectPath)
         return null;
@@ -14,6 +35,20 @@ async function readMainSceneFromProject(projectPath) {
         return null;
     }
 }
+function requireSuccessfulOps(result, context) {
+    const receipt = (result ?? {});
+    const results = Array.isArray(receipt.results)
+        ? receipt.results
+        : [];
+    const failed = results.find((entry) => entry?.ok === false);
+    if (receipt.status === "error" || failed) {
+        const error = (typeof failed?.error === "string" && failed.error) ||
+            (typeof receipt.error === "string" && receipt.error) ||
+            `${context} failed`;
+        throw new Error(error);
+    }
+    return receipt;
+}
 export function registerSceneTools(server) {
     server.tool("summer_create_scene", `Create a new empty scene file safely.
 
@@ -45,19 +80,22 @@ Recommended workflow:
             throw new Error("No scene open and could not resolve main scene. Call summer_get_project_context first, then open a known scene.");
         }
         await client.executeOps([{ op: "OpenScene", path: templateScene }]);
-        const tree = (await client.getSceneState());
+        const tree = (await client.getSceneState(templateScene));
         const children = tree.data?.children ?? tree.children ?? [];
         const removeOps = children
             .map((c) => c.path)
             .filter((p) => typeof p === "string" && p.length > 0)
             .map((p) => ({ op: "RemoveNode", path: `./${p}` }));
-        if (removeOps.length > 0) {
-            await client.executeOps(removeOps, { groupUndo: true });
-        }
-        await client.executeOps([{ op: "SetProp", path: ".", key: "name", value: rootName }]);
-        await client.executeOps([{ op: "SaveScene", path }]);
+        const createOps = [
+            ...removeOps,
+            { op: "SetProp", path: ".", key: "name", value: rootName },
+            { op: "SaveScene", path },
+        ];
+        const createReceipt = requireSuccessfulOps(await executeSceneMutation(client, templateScene, createOps, {
+            groupUndo: true,
+        }), `Creating ${path}`);
         if (currentScene && currentScene !== path) {
-            await client.executeOps([{ op: "OpenScene", path: currentScene }]);
+            requireSuccessfulOps(await client.executeOps([{ op: "OpenScene", path: currentScene }]), `Restoring ${currentScene}`);
         }
         return {
             ok: true,
@@ -65,14 +103,13 @@ Recommended workflow:
             rootName,
             templateScene,
             restoredScene: currentScene,
+            receipt: createReceipt,
         };
     }));
     server.tool("summer_add_node", `Add a new node to the scene tree.
 
-Preflight (fresh chat):
-1) summer_get_project_context
-2) summer_open_main_scene (if no scene open)
-3) summer_get_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
@@ -81,10 +118,11 @@ Common node types:
 - 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.`, {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         parent: z.string().describe("Parent node path, e.g. './World' or './World/Enemies'"),
         type: z.string().describe("Godot node type, e.g. 'MeshInstance3D', 'CharacterBody3D'"),
         name: z.string().describe("Name for the new node, e.g. 'Player', 'MainCamera'"),
-    }, async ({ parent, type, name }) => withEngine(async (client) => client.executeOps([{ op: "AddNode", parent, type, name }])));
+    }, async ({ scenePath, parent, type, name }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [{ op: "AddNode", parent, type, name }])));
     server.tool("summer_set_prop", `Set a property on a node. This is the primary way to configure nodes after adding them.
 
 VALUE FORMAT — Godot string syntax for complex types:
@@ -106,29 +144,37 @@ COMMON PROPERTIES:
 - shadow_enabled: true — for lights
 - light_energy: 1.5 — light intensity
 - fov: 75.0 — camera field of view`, {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         path: z.string().describe("Node path, e.g. './World/Player'"),
         key: z.string().describe("Property name, e.g. 'position', 'mesh', 'visible'"),
         value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Godot string format for complex types, native JSON for primitives"),
-    }, async ({ path, key, value }) => withEngine(async (client) => client.executeOps([{ op: "SetProp", path, key, value }])));
+    }, async ({ scenePath, path, key, value }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [{ op: "SetProp", path, key, value }])));
     server.tool("summer_set_resource_property", `Set a nested property on a resource attached to a node.
 
 Use when you need to modify a sub-property of a resource, like:
 - CollisionShape3D shape size: nodePath="./Player/CollisionShape3D", resourceProperty="shape", subProperty="size", value="Vector3(1, 2, 1)"
 - Material albedo color: nodePath="./Floor", resourceProperty="material_override", subProperty="albedo_color", value="Color(0.2, 0.5, 0.2, 1)"
 - Mesh size: nodePath="./Box", resourceProperty="mesh", subProperty="size", value="Vector3(2, 2, 2)"`, {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         nodePath: z.string().describe("Node path, e.g. './Player/CollisionShape3D'"),
         resourceProperty: z.string().describe("Resource property on the node, e.g. 'shape', 'mesh', 'material_override'"),
         subProperty: z.string().describe("Property on the resource, e.g. 'size', 'radius', 'albedo_color'"),
         value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Godot string format"),
-    }, async ({ nodePath, resourceProperty, subProperty, value }) => withEngine(async (client) => client.executeOps([
+    }, async ({ scenePath, nodePath, resourceProperty, subProperty, value }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [
         { op: "SetResourceProperty", nodePath, resourceProperty, subProperty, value },
     ])));
-    server.tool("summer_remove_node", "Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo. Destructive operation: do not delete multiple top-level nodes unless the user explicitly requests destructive changes.", { path: z.string().describe("Node path to remove, e.g. './World/OldEnemy'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "RemoveNode", path }])));
-    server.tool("summer_save_scene", "Save the current scene to disk. Call this after making scene changes to persist them. Without saving, changes only exist in the editor's memory.", { path: z.string().optional().describe("Save-as path for creating a new scene file, e.g. 'res://levels/level2.tscn'") }, async ({ path }) => withEngine(async (client) => {
+    server.tool("summer_remove_node", "Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo. Destructive operation: do not delete multiple top-level nodes unless the user explicitly requests destructive changes.", {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
+        path: z.string().describe("Node path to remove, e.g. './World/OldEnemy'"),
+    }, async ({ scenePath, path }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [{ op: "RemoveNode", path }])));
+    server.tool("summer_save_scene", "Save an explicit scene to disk. Mutation tools already append one save; use this for a standalone save or save-as.", {
+        scenePath: z.string().describe("Scene to save, e.g. 'res://main.tscn'"),
+        path: z.string().optional().describe("Optional save-as path, e.g. 'res://levels/level2.tscn'"),
+    }, async ({ scenePath, path }) => withEngine(async (client) => {
         const op = { op: "SaveScene" };
         if (path)
             op.path = path;
-        return client.executeOps([op]);
+        return executeSceneMutation(client, scenePath, [op]);
     }));
     server.tool("summer_open_scene", `Open a scene file in the editor. Use this to switch between scenes.
 
@@ -142,14 +188,15 @@ Do not guess paths. Prefer:
 - Compose scenes from smaller scenes (e.g., add a "Player" scene into a "Level" scene)
 
 The scene must already exist in the project. Use summer_import_from_url first if importing from external sources.`, {
+        scenePath: z.string().describe("Target scene to receive the instance, e.g. 'res://main.tscn'"),
         parent: z.string().describe("Parent node path, e.g. './World'"),
         scene: z.string().describe("Scene/model path, e.g. 'res://player.tscn' or 'res://models/tree.glb'"),
         name: z.string().optional().describe("Override the instance name"),
-    }, async ({ parent, scene, name }) => withEngine(async (client) => {
+    }, async ({ scenePath, parent, scene, name }) => withEngine(async (client) => {
         const op = { op: "InstantiateScene", parent, scene };
         if (name)
             op.name = name;
-        return client.executeOps([op]);
+        return executeSceneMutation(client, scenePath, [op]);
     }));
     server.tool("summer_connect_signal", `Connect a signal between two nodes. Signals are Godot's event system — they notify when something happens.
 
@@ -161,11 +208,12 @@ Common signals:
 - "input_event" — CollisionObject received input
 
 The receiver node must have a script with the specified method.`, {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         emitter: z.string().describe("Node that fires the signal, e.g. './Player/HitArea'"),
         signal: z.string().describe("Signal name, e.g. 'body_entered'"),
         receiver: z.string().describe("Node with the handler script, e.g. './Player'"),
         method: z.string().describe("Method name in the receiver's script, e.g. '_on_hit_area_body_entered'"),
-    }, async ({ emitter, signal, receiver, method }) => withEngine(async (client) => client.executeOps([
+    }, async ({ scenePath, emitter, signal, receiver, method }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [
         { op: "ConnectSignal", emitter, signal, receiver, method },
     ])));
     server.tool("summer_select_node", "Select a node in the editor's scene tree and show it in the inspector panel. Useful for focusing the editor on a specific node.", {
@@ -178,16 +226,17 @@ The receiver node must have a script with the specified method.`, {
         return client.executeOps([op]);
     }));
     server.tool("summer_replace_node", "Replace a node with a different type or scene, preserving its position in the tree and its children. Useful for changing a StaticBody3D to a RigidBody3D, or swapping a placeholder with a proper prefab.", {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         path: z.string().describe("Node path to replace"),
         type: z.string().optional().describe("New node type, e.g. 'RigidBody3D'"),
         scene: z.string().optional().describe("Scene to replace with, e.g. 'res://enemies/boss.tscn'"),
-    }, async ({ path, type, scene }) => withEngine(async (client) => {
+    }, async ({ scenePath, path, type, scene }) => withEngine(async (client) => {
         const op = { op: "ReplaceNode", path };
         if (type)
             op.type = type;
         if (scene)
             op.scene = scene;
-        return client.executeOps([op]);
+        return executeSceneMutation(client, scenePath, [op]);
     }));
     server.tool("summer_inspect_node", `Get all editable properties of a node with their current values, types, and resource info.
 
@@ -213,7 +262,35 @@ Each op in the array uses the same format as the individual tools:
 
 RAW RUNTIME OPS (interactive verification — engine-build dependent; structured failure_reason incl "unsupported" passes through verbatim):
 - SimulateInput — drive the RUNNING game (summer_play first): {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. type is "action" | "key" | "mouse_click" | "axis".
-- RunVerification — spawn a hidden, disposable game instance that runs a GDScript probe and dies (never touches the editor): {"op": "RunVerification", "probe_source": "extends SummerProbeBase\\nfunc _ready(): await super._ready(); report('ok', true); finish()", "max_seconds": 20}. Returns {ok, results, frames, out_dir}. Probe API: report()/save_frame()/press()/key()/finish().`, {
+- RunVerification — spawn a hidden, disposable game instance that runs a GDScript probe and dies (never touches the editor): {"op": "RunVerification", "probe_source": "extends SummerProbeBase\\nfunc _ready(): await super._ready(); report('ok', true); finish()", "max_seconds": 20}. Returns {ok, results, frames, out_dir}. Probe API: report()/save_frame()/press()/key()/finish().
+
+Do not mix OpenScene with scene mutations in one batch. OpenScene is a UI action;
+send it separately. scenePath selects every mutation target. The tool appends one
+final SaveScene when the batch mutates a scene; if supplied explicitly, SaveScene
+must appear exactly once and be the final operation.`, {
+        scenePath: z.string().optional().describe("Required when ops contains scene mutations; exact res:// target scene path"),
         ops: z.array(z.record(z.unknown())).describe("Array of operation objects, each with 'op' plus its parameters"),
-    }, async ({ ops }) => withEngine(async (client) => client.executeOps(ops, { groupUndo: true })));
+    }, async ({ scenePath, ops }) => withEngine(async (client) => {
+        const rawFileMutation = ops.find((op) => {
+            const kind = String(op.op ?? "");
+            return kind === "WriteFile" || kind === "ReplaceText";
+        });
+        if (rawFileMutation) {
+            throw new Error(`summer_batch does not accept raw ${String(rawFileMutation.op)} operations. ` +
+                "Use summer_write_file or summer_replace_text so project identity, content guards, and same-file ordering are enforced.");
+        }
+        const sceneMutations = new Set([
+            "AddNode", "RemoveNode", "MoveNode", "ReparentNode", "ReplaceNode",
+            "SetProp", "SetResourceProperty", "ConnectSignal", "DisconnectSignal",
+            "InstantiateScene", "SaveScene", "Undo",
+        ]);
+        const needsScenePath = ops.some((op) => sceneMutations.has(String(op.op ?? "")));
+        if (needsScenePath && !scenePath) {
+            throw new Error("summer_batch requires scenePath when ops contains scene mutations");
+        }
+        const options = { groupUndo: true, ...(scenePath ? { scenePath } : {}) };
+        return needsScenePath
+            ? executeSceneMutation(client, scenePath, ops, options)
+            : client.executeOps(ops, options);
+    }));
 }

package/dist/mcp/tools/with-engine.js

@@ -19,7 +19,10 @@ const SUCCESS_TERMINAL_STATES = new Set(["applied", "no_op"]);
 // `error` string (queue-full / lease-reject / identity-mismatch / no-progress
 // timeout frequently arrive with terminalState set and results[] absent).
 const TERMINAL_STATE_MESSAGES = {
-    timed_out: "Engine operation timed out (terminalState: timed_out). Nothing was applied.",
+    timed_out: "Engine operation timed out. Its final state is unknown; inspect the target before retrying.",
+    still_queued: "Summer Engine accepted the operation, but it was still queued when the client stopped waiting. It may still run; do not retry blindly.",
+    still_running: "Summer Engine accepted and started the operation, but no final receipt arrived. It may still be running or may already have applied; inspect the target before retrying.",
+    uncertain: "Summer Engine did not provide a final operation receipt. The current state is uncertain; inspect the target before retrying.",
     not_connected: "Summer Engine is not connected (terminalState: not_connected). Nothing was applied.",
     identity_mismatch: "Operation rejected — wrong project/instance (terminalState: identity_mismatch). Nothing was mutated.",
     content_mismatch: "Operation rejected — content changed since last read (terminalState: content_mismatch). Nothing was applied.",
@@ -117,9 +120,6 @@ function buildActionHint(message) {
     if (normalized.includes("failed to open scene")) {
         return "Scene path could not be opened. Call `summer_get_project_context` to get `mainScene`, then open that exact path. Avoid guessing scene filenames.";
     }
-    if (normalized.includes("writefile cannot edit .tscn/.scn")) {
-        return "Write .gd/.cs/.json/docs/simple config files with normal file-edit tools. Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.";
-    }
     return null;
 }
 export async function withEngine(fn, opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "2.6.6",
+  "version": "2.7.0",
   "description": "Local Summer CLI and MCP server for Summer Engine. Install and run the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games with bundled skills, hooks, and plugins.",
   "keywords": [
     "summer-engine",

package/skills/2d-assets/create-asset-sheet/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_search_assets summer_import_from_url
+allowed-tools: Read Grep Glob Write Edit summer_get_studio_workflow summer_generate_image summer_slice_asset_sheet summer_search_assets summer_import_asset_by_id summer_import_from_url
 paths: ["assets/**", "art/**", "sprites/**"]
 ---
 
@@ -58,13 +58,16 @@ Direct the user there if they're working in the browser. The wizard:
 - Has per-slice HD upscale + bulk "Upscale all"
 - Saves as a pack ArtAsset visible in the user's library
 
-If the user is in a chat / agent context and can't open the browser, fall back to the programmatic path below.
+If the user is in a chat / agent context, use the programmatic path below. It
+now calls the same server-side slicer as the Studio wizard.
 
 ## Programmatic path (chat / agent driving the engine)
 
-The slicing + classification endpoints are not yet exposed as `summer_*` MCP tools. Until they are, the agent can replicate the flow manually:
+1. **Load the exact current recipe.** Call
+   `summer_get_studio_workflow({workflowId: "asset-pack"})`. Follow its ordered
+   steps and report any `manual` handoff instead of pretending it ran.
 
-1. **Generate the sheet.** Call `summer_generate_image` with a prompt like:
+2. **Generate the sheet.** Call `summer_generate_image` with a prompt like:
 
    ```
    <theme> asset sheet: <comma-separated list of items>. Each item isolated with empty space around it, transparent or neutral background.
@@ -74,21 +77,18 @@ The slicing + classification endpoints are not yet exposed as `summer_*` MCP too
    - 1024x1024 is the sweet spot. Larger sheets fragment in the slicer when individual assets get below ~64px.
    - Keep the asset list to 6–20 items per sheet. Past 20, model attention degrades and slices get muddy.
 
-2. **Remove background.** Call `fal-ai/bria/background/remove` on the generated URL. Cost: $0.05.
-
-3. **Detect + name + classify.** Send the transparent PNG to a vision LLM (Gemini 3 Pro is currently the strongest at bbox + category in one shot). Use this system prompt structure:
+3. **Slice, remove background, detect, name, classify, crop, and save.** Pass
+   the returned image asset id to:
 
    ```
-   Output strict JSON array, no prose:
-   [{"name":"snake_case_name","category":"character|terrain|nature|lighting|water|decorative|buildings|ui|vfx","x":<0-100>,"y":<0-100>,"w":<0-100>,"h":<0-100>}]
-
-   Coordinates are percentages of image dimensions, top-left origin.
-   Names are 1-3 words, snake_case, specific (stone_lantern, not lamp).
+   summer_slice_asset_sheet({ assetId: "<generated asset id>" })
    ```
 
-4. **Crop** each region with sharp / PIL / equivalent. Pad bboxes by 4px to leave breathing room.
+   This is the same cloud slicing pipeline used by the Studio flow. Keep the
+   returned slice ids/names/categories; do not reimplement the vision boxes
+   locally.
 
-5. **Optional upscale.** For any crop where longest side < 256px, send through fal flux-2/edit i2i with prompt:
+4. **Optional upscale.** For any crop where longest side < 256px, send through fal flux-2/edit i2i with prompt:
 
    ```
    Recreate this exact <name> at high resolution. Preserve every detail, the exact pose, the exact style. Sharper edges, more detail. Transparent background. Single isolated asset, no scene.
@@ -97,7 +97,9 @@ The slicing + classification endpoints are not yet exposed as `summer_*` MCP too
    - Scale longest side to 1024, preserve aspect ratio (FLUX requires multiples of 32).
    - Don't blindly upscale everything — high-res slices get diminishing returns and you spend $0.04/slice.
 
-6. **Save** as a pack record in `art_assets`: `isPack: true`, `packFiles: [{url, name, type: "image/png"}]`, `metadata.sliceBboxes`, `parentAssetId` pointing to the source sheet.
+5. **Import what the game needs.** Use the returned asset ids with
+   `summer_import_asset_by_id`. Keep the source pack in My Assets so the agent
+   and the human Studio session see the same result.
 
 ## Prompt patterns that work
 

package/skills/debugging/debug/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: debugging
 user-invocable: true
-allowed-tools: Read Edit Grep summer_get_diagnostics summer_get_script_errors summer_get_console summer_clear_console summer_get_debugger_errors summer_play summer_stop summer_is_running summer_inspect_node summer_inspect_resource summer_get_scene_tree
+allowed-tools: Read Edit Grep summer_create_debug_report summer_get_diagnostics summer_get_script_errors summer_get_console summer_clear_console summer_get_debugger_errors summer_play summer_stop summer_is_running summer_inspect_node summer_inspect_resource summer_get_scene_tree
 paths: ["**/*.gd", "**/*.cs", "**/*.tscn", "**/*.tres", "project.godot"]
 ---
 
@@ -18,6 +18,7 @@ The disciplined debugging loop for Godot/Summer projects. Read the error before
 ## When to use this skill
 
 - The user says "it crashes", "it broke", "throws an error", "doesn't work", "freezes", "wrong behavior".
+- The user invokes `/summer debug`, asks for a support report, or wants something they can send to Summer.
 - The user pastes a stack trace.
 - A previous build or test step failed and the user wants to fix it.
 
@@ -35,6 +36,27 @@ The disciplined debugging loop for Godot/Summer projects. Read the error before
 
 Do not skip steps. Do not loop back to "Hypothesize" without re-running the cheap diagnostic.
 
+### 0. Support report mode
+
+If the user asks for `/summer debug`, "send this to Summer", "make a report", or they are stuck in Codex/cloud/another agent environment, create a portable report first:
+
+```
+summer_create_debug_report({
+  issue: "<one-sentence user symptom>",
+  include_play_session: <true only when the issue appears during runtime>
+})
+```
+
+Tell the user where the Markdown file was written and remind them to review local paths and stack traces before sending. Then continue the normal debug loop only if they also asked you to fix the bug.
+
+Fallback when the MCP tool is not available but shell is available:
+
+```
+summer debug "<one-sentence user symptom>"
+```
+
+Add `--play` only when the issue appears after pressing Play.
+
 ### 1. Listen
 
 Ask the user **one** focused question and wait for the answer:

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

@@ -0,0 +1,107 @@
+---
+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.
+
+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`) | Final, signed distribution builds | Submitting to stores |
+
+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.
+
+## Prerequisites — what makes the button light up
+
+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 **runnable export preset** for the platform | Project → Export → add a preset (Android / iOS / Web / desktop) → toggle **Runnable** on | The dropdown only lists platforms that have a *runnable* preset. A preset that exists but isn't marked Runnable does **not** count. |
+| **Export templates** installed for that platform/engine version | Export dialog → **Manage Export Templates…** → download | Needed to actually build the debug build when you deploy. |
+| The platform **toolchain** | Android: Android SDK + `adb` + a debug keystore. iOS: Xcode + signing. Web: any browser. | The deploy step shells out to these; without them the build can't be installed/run. |
+| A **detected target** | Android: a device with USB debugging enabled (and authorized), or a running emulator. iOS: a connected, trusted device. Web: the built-in **"Run in Browser"** target. | The button enables only when ≥1 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.
+
+## How it works (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. Godot exports a **debug** build for that preset.
+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 quick paths
+
+**Android**
+1. Enable Developer Options → USB debugging on the phone; plug it in; accept the "Allow USB debugging?" prompt.
+2. Confirm `adb devices` lists it as `device` (not `unauthorized`).
+3. Project → Export → Android preset → **Runnable** on; install Android export templates.
+4. The phone appears in the Remote Deploy dropdown → pick it.
+
+**iOS**
+1. Connect and trust the device; ensure a valid signing team in the iOS preset.
+2. Xcode command-line tools installed; iOS export templates installed.
+3. The device appears in the dropdown → pick it.
+
+**Web (sanity check on the target browser)**
+1. Web (HTML5) preset → **Runnable** on; Web export templates installed.
+2. Pick **"Run in Browser"** from the dropdown.
+
+## Guiding the user (orchestrator playbook)
+
+When a user says "deploy to my phone" / "run this on device" and the button is greyed:
+
+1. **Check the build is healthy first** — 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.
+2. **Confirm a runnable preset exists** for the 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.
+3. **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.
+4. **Confirm export templates + toolchain** for the platform are installed (Manage Export Templates; adb/Xcode/browser).
+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: preset → templates/toolchain → device. Resolve them top-down; the button enables as soon as preset + device are both true, and the deploy succeeds once templates/toolchain are present.
+
+## 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/scene-and-project/brainstorm-game/SKILL.md

@@ -146,21 +146,21 @@ Compose the 1-page brief. Format:
 
 ### 9. Ask permission and write
 
-**Preferred (Summer MCP + host file write):**
+**Preferred (Summer MCP):**
 
 > May I create `.summer/GameSoul.md` with this brief?
 
-On yes, use `Write` (host file tool) — `.summer/GameSoul.md` is plain markdown, no engine import needed:
+On yes, use guarded `summer_write_file` — `.summer/GameSoul.md` is plain markdown but still belongs to the bound project:
 
 ```
-Write .summer/GameSoul.md
+summer_write_file path="res://.summer/GameSoul.md" create_only=true content="<brief>"
 ```
 
 If `.summer/GameSoul.md` already exists, read it first, show what would change, ask:
 
 > `.summer/GameSoul.md` already exists. May I overwrite it, or merge into a "Revision 2" section below the existing brief?
 
-**Fallback (no host write tool — agent is read-only):**
+**Fallback (Summer MCP unavailable — agent is read-only):**
 
 Print the full brief to the user with the explicit instruction:
 

package/skills/scene-and-project/summer-cloud/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: summer-cloud
+description: Use when the user wants to sync a Summer Engine project, move it to another machine or laptop, share the exact bytes with a collaborator, back up big generated assets that do not belong in git, restore an earlier version, or wants a safety net before a risky bulk operation. Trigger on "sync", "Summer Cloud", "cloud push", "cloud pull", "move to another machine", "other computer", "second machine", "share project", "back up assets", "big assets", "collaborator", "teammate", "restore a version", "checkpoint", "conflict".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+user-invocable: true
+allowed-tools: Read summer_cloud_init summer_cloud_status summer_cloud_push summer_cloud_pull summer_cloud_restore summer_cloud_checkpoints summer_cloud_conflicts
+paths: ["summer-cloud.json"]
+---
+
+# Summer Cloud: Project Sync
+
+## What Summer Cloud is
+
+Summer Cloud is content-addressed sync for a whole Summer Engine project. Every tracked file is identified by its sha256 hash, so identical bytes upload once and dedupe across versions and projects. It syncs the entire project tree at once (code, scenes, resources, import sidecars, and the heavy binary assets), not a hand-picked folder. The only git-tracked cloud artifact is a tiny `summer-cloud.json` binding at the project root; all real sync state lives under `.summer/local/cloud/` and is never committed.
+
+This is not a folder backup and it is not a git replacement. Code that lives happily in git can stay in git. What Cloud adds is a way to move the large generated binaries (models, textures, audio, video) that do not belong in a git repo, and to keep a project byte-identical across machines and collaborators. Git and Cloud can run side by side; the binding file merges trivially.
+
+## When to offer it (proactive triggers)
+
+Surface Cloud, do not wait to be asked, when any of these are true:
+
+- The project has heavy generated assets (large `.glb`, `.png`, `.wav`, `.ogg`, `.mp4` under `assets/`) that should not go into git. Cloud is how those travel.
+- The user mentions a second machine, a laptop, "my other computer", or working from somewhere else. Cloud is how the same bytes show up there.
+- A teammate or collaborator needs the exact same project state. Add them as a collaborator and they pull.
+- A risky bulk operation is about to run (mass asset import, a large refactor, a destructive cleanup). A push first gives a restorable version to fall back to.
+
+If none of these apply, do not push Cloud on the user. It is a tool for a real need, not a default step.
+
+## Command and tool surface
+
+| Action | CLI | MCP tool |
+|---|---|---|
+| Enable Cloud for this project | `summer cloud init` | `summer_cloud_init` |
+| Show what would push/pull | `summer cloud status` | `summer_cloud_status` |
+| Upload local changes | `summer cloud push` | `summer_cloud_push` |
+| Download remote changes | `summer cloud pull` | `summer_cloud_pull` |
+| Restore an earlier version or a local checkpoint | `summer cloud restore --version N` / `--checkpoint <stamp>` | `summer_cloud_restore` |
+| List local pre-sync checkpoints | `summer cloud checkpoints` | `summer_cloud_checkpoints` |
+| List or recover conflict sets | `summer cloud conflicts list` / `restore <path>` | `summer_cloud_conflicts` |
+
+Run `summer cloud status` before any push or pull. It reports the file counts, what would move in each direction, and whether any conflict sets are waiting. Never push blind.
+
+## The safety model (respect this)
+
+The whole point of Cloud is that user data is never destroyed silently. The rules below are how that holds. Do not work around them.
+
+- **Every push is a restorable version.** The server keeps the version history within the retention window. Version numbers are never reused. If a bad push lands, `summer cloud restore --version N` brings the project back as a new head version, then pulls it locally.
+- **Local checkpoints come before destructive applies.** Before a pull modifies or deletes any existing file, the client writes a full-tree checkpoint into the project's local SummerGit repo. `summer cloud checkpoints` lists them; `summer cloud restore --checkpoint <stamp>` rolls back. Note the honest caveat the restore prints: it restores bytes but does not delete files a bad sync added, so review and remove any extras it lists.
+- **Large deletions are gated.** A push that would delete many cloud files (more than 10 files, or at least 20% of the tracked tree, or the entire tree) requires `confirmDeletes: true` on the MCP tool (or `--confirm-deletes` on the CLI). Never pass it blindly. First run `summer cloud status`, read the delete count out loud to the user, and only set the flag once they confirm that count is what they intend. If the local tree reads as completely empty against a non-empty base (a wrong directory or an unmounted volume), the push aborts outright and no flag can force it.
+- **Conflicts become conflict sets, never silent overwrites.** Concurrent edits to the same file are resolved deterministically: the first sync to land wins the canonical path (this is "first to sync wins", not "most recent save wins", because there are no wall clocks). The losing bytes are preserved, never discarded, in a local conflict set and backed up to the cloud. Surface them with `summer cloud conflicts list` and recover any with `summer cloud conflicts restore <path>`, which re-enters the file as a fresh edit. `project.godot` is the one file merged key by key rather than whole-file, so input actions and autoloads from both sides survive.
+- **A modify always beats a delete.** If one side edited a file and the other deleted it, the edited file is kept and the deletion is dropped, with a notice. Offline work is never lost to someone else's delete.
+
+## First sync and the bootstrap choice
+
+When a project already has files on both the local disk and in the cloud but this machine has no sync base (for example a fresh git clone of a project that was cloud-enabled elsewhere), auto-sync will not run. The tool returns a bootstrap choice. Present it to the user and let them pick:
+
+- `keep-cloud` (pull): replace local divergent files with the cloud version. Local divergent files are checkpointed first.
+- `keep-local` (push): make the local tree the new cloud version.
+- `merge`: converge automatically where hashes already match (usually most files); the rest get normal conflict treatment.
+
+If the project folder was moved or Finder-copied, sync blocks until you confirm whether to adopt the new path (`adoptPath: true`) or fork it into a separate cloud project. Two folders must never fight over one project.
+
+## Honest v1 limits
+
+State these plainly when they are relevant; do not paper over them.
+
+- **One linear head per project. No branches yet.** There is a single history line. If a user wants an isolated line to experiment with assets, fork to a separate cloud project: delete `summer-cloud.json` and run `summer cloud init` to create a new binding. Because storage is content-addressed and dedupes, the fork is nearly free in storage.
+- **Per-file cap is 4.995 GiB.** A single file larger than that is rejected with a clear error. There is no multipart path in v1.
+- **No resumable uploads.** A dropped connection mid-upload on a multi-GiB file restarts that file from zero. For large pushes, prefer a stable connection.
+- **No locking or presence.** Two people editing the same binary at once produces a conflict (recoverable, never lost), not a lock.
+- **Git branch switches read as edits.** Switching git branches on a cloud-synced project looks like local edits to Cloud and will push as such. Guidance: sync before and after branch operations, or keep cloud projects on one branch.
+- **Storage rides the plan tiers.** Free, Pro, Pro Plus, and Ultra each have a storage cap. A push past the cap returns a quota error pointing at the upgrade path; surface that to the user rather than retrying.
+
+## Hard rule: drive everything through the CLI or MCP
+
+Never hand-edit anything under `.summer/local/cloud/` (base, journal, hash cache, staging, checkpoints, conflict sets). That state is the integrity model; editing it by hand can corrupt the 3-way base and cause data loss on the next sync. The only file you ever touch directly is the tiny git-tracked `summer-cloud.json` binding, and even then only to remove `pinnedVersion` for a read-only checkout or to delete it when intentionally forking. Every real operation goes through `summer cloud ...` or the `summer_cloud_*` tools.
+
+## Typical flows
+
+- **Move to a second machine.** On machine A: `summer cloud init`, then `summer cloud push`. Commit `summer-cloud.json` so it travels with git, or share the project id. On machine B: get the project (git clone or copy), then `summer cloud pull`. If both sides already had files, take the bootstrap choice.
+- **Back up big assets before a bulk import.** `summer cloud status`, then `summer cloud push`. The resulting version is the restore point.
+- **Recover from a bad change.** `summer cloud checkpoints` (or `summer cloud status` for cloud versions), then `summer cloud restore --checkpoint <stamp>` for local-only work or `--version N` for a pushed version. Remove any extra files the restore lists.
+
+## Fallback
+
+If the MCP tools are unavailable, run the `summer cloud ...` CLI commands directly. The CLI and MCP tools are one to one and share the same engine. If neither is available, the project is not set up; point the user at `summer login` (Cloud auth comes from the login token) and `summer cloud init`.
+
+## Collaborative protocol
+
+Push and pull move bytes and can replace files. Always run `summer cloud status` and say what will move before you push or pull: "Push will upload 4 files and delete 0. OK to push?" For any gated deletion, state the exact count and get explicit confirmation before setting `confirmDeletes`. See `../../references/collaborative-protocol.md`.