summer-engine 2.6.6 → 2.8.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'"),
+        type: z.string().describe("Summer Engine 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 }])));
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Summer Engine variant-string format for complex types, native JSON for primitives"),
+    }, 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([
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Summer Engine variant-string format"),
+    }, 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.
 
@@ -211,9 +260,37 @@ Each op in the array uses the same format as the individual tools:
 - {"op": "SetProp", "path": "Floor", "key": "mesh", "value": "PlaneMesh"}
 - {"op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)"}
 
-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().`, {
+RAW RUNTIME OPS (interactive verification — structured failure_reason passes through verbatim):
+- 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(). This is the ONLY way to drive input from MCP, and unlike the editor it renders real pixels, so save_frame() produces a real image.
+- SimulateInput is NOT reachable from MCP or the CLI. It requires the in-editor chat bridge's async reply channel; every queued caller gets {"ok": false, "failure_reason": "unsupported_transport"} on every engine build. Do not send it and do not treat that reply as a version problem — use RunVerification's press()/key() instead.
+
+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/visual-tools.js

@@ -10,14 +10,15 @@ import { withEngine } from "./with-engine.js";
 export function registerVisualTools(server) {
     server.tool("summer_screenshot", `Capture a frame from Summer Engine and return it as an image you can look at directly.
 
-Use this to visually verify your work: scene layout, asset placement, scale, framing, lighting, materials, missing/untextured assets, or runtime gameplay state. You see the actual pixels — no description layer in between.
+Use this to visually verify your work: scene layout, asset placement, scale, framing, missing/untextured assets, or runtime gameplay state. You see the actual pixels — no description layer in between. Lighting and materials are only truthfully shown by the "viewport" and "game" targets — see the note on "scene" below.
 
 target:
   "viewport" (default) — the editor's CURRENT view (whatever scene/tab is open). No game boot. Use for edit-time checks of how the scene looks right now.
-  "scene" — an OFFSCREEN render of a scene file (no game boot; physics/particles/animations are static at t=0). Optionally pass scenePath/framing/size/nodePath. Use for a quick composed look at a scene without touching the editor's open tab.
+  "scene" — an OFFSCREEN render of a scene file (no game boot; physics/particles/animations are static at t=0). Optionally pass scenePath/framing/size/nodePath. Use for COMPOSITION, SCALE and FRAMING without touching the editor's open tab.
+    It does NOT use the scene's environment/sky, and it injects a synthetic camera and light when the scene has none. The scene's WorldEnvironment — sky, fog, tonemap, glow, SSAO, ambient — is replaced by a flat preview environment. So this target CANNOT verify lighting, mood, or any material property that depends on the environment: change them and the frame comes back identical. For those, boot the game or run a RunVerification probe, whose instance renders the real environment.
   "game" — a frame from the RUNNING game (real runtime state). Start the game first (summer_play). Not available over a plain local connection — needs the Summer desktop app bridge.
 
-Static frame only — one moment, not motion. If a game capture is unavailable, use "viewport" or "scene", or ask the user to share a screenshot of the running game.`, {
+Static frame only — one moment, not motion. For a SEQUENCE of frames over time, or for anything lighting-dependent when the desktop bridge is unavailable, use a RunVerification probe's save_frame() — its instance has a real renderer.`, {
         target: z
             .enum(["viewport", "scene", "game"])
             .optional()

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/hooks/session-start.sh

@@ -3,7 +3,7 @@
 #
 # Event:    SessionStart (matcher: startup|clear|compact)
 # Purpose:  Orient Claude on every fresh Summer-enabled session.
-#           Detect Godot project + GameSoul + doctor health, surface a one-line
+#           Detect Summer project + GameSoul + doctor health, surface a one-line
 #           Bob-style greeting as additional context.
 #
 # Input:    JSON on stdin with { session_id, source, model, cwd, ... }
@@ -36,7 +36,7 @@ else
     LINES+=("Summer ready.")
 fi
 
-# Line 2: Godot project + GameSoul one-liner (only if project.godot exists)
+# Line 2: Summer project + GameSoul one-liner (only if project.godot exists)
 if [ -f "${PROJECT_DIR}/project.godot" ]; then
     PROJECT_NAME=$(grep -E '^config/name=' "${PROJECT_DIR}/project.godot" 2>/dev/null \
         | head -1 | sed 's/^config\/name=//;s/^"//;s/"$//')
@@ -48,12 +48,12 @@ if [ -f "${PROJECT_DIR}/project.godot" ]; then
         SOUL_LINE=$(awk 'BEGIN{p=""} /^[^#[:space:]]/ && NF>0 {p=$0; exit} END{print p}' \
             "$SOUL_FILE" 2>/dev/null | cut -c1-120)
         if [ -n "$SOUL_LINE" ]; then
-            LINES+=("Godot project: ${PROJECT_NAME}. GameSoul: ${SOUL_LINE}")
+            LINES+=("Summer project: ${PROJECT_NAME}. GameSoul: ${SOUL_LINE}")
         else
-            LINES+=("Godot project: ${PROJECT_NAME}.")
+            LINES+=("Summer project: ${PROJECT_NAME}.")
         fi
     else
-        LINES+=("Godot project: ${PROJECT_NAME}.")
+        LINES+=("Summer project: ${PROJECT_NAME}.")
     fi
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "2.6.6",
+  "version": "2.8.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",
@@ -41,6 +41,7 @@
   "files": [
     "dist/",
     "skills/",
+    "references/",
     "commands/",
     "hooks/",
     "assets/",
@@ -65,6 +66,7 @@
     "dev": "tsc --watch",
     "summer": "node dist/bin/summer.js",
     "test": "vitest run",
+    "test:public-language": "vitest run src/lib/public-surface-language.test.ts",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build && npm test"
   },

package/references/collaborative-protocol.md

@@ -0,0 +1,50 @@
+# Collaborative Protocol — "May I write?"
+
+> Every Summer skill must follow this. The agent works *with* the user, not around them.
+
+## The rule
+
+**Before any user-visible write step, the agent must explicitly state what it is about to do and ask permission to proceed.**
+
+This applies to:
+- Creating files (`.gd`, `.tscn`, `.tres`, JSON, configs)
+- Modifying existing files (especially `.gd` and `.tscn`)
+- Running irreversible operations (deletion, reset, force-overwrite)
+- Setting up project-wide settings (`project.godot`)
+- Installing tools, libraries, or templates
+
+Reading is unconditional. Inspection, scene-tree walks, diagnostics — never need permission.
+
+## Phrasing
+
+Plain, short, action-first. Examples:
+
+> May I create `scenes/player.tscn` and add a CharacterBody3D + Camera3D?
+
+> I'm about to overwrite `levels/level_01.tscn`. The current version has 14 nodes — I'll preserve them and add the new lighting setup. Continue?
+
+> May I attach `scripts/player_controller.gd` to `./World/Player`?
+
+> I'm going to bind `move_forward`, `move_back`, `move_left`, `move_right`, `jump`. OK?
+
+## What this prevents
+
+1. **Silent overwrites.** The agent stomps the user's hand-edited script.
+2. **Cascading scope creep.** A "small fix" turns into a 30-file refactor.
+3. **Unclear state.** The user has no idea what changed when something breaks.
+4. **Trust loss.** One unauthorized edit and the user stops trusting the agent.
+
+## What this is NOT
+
+- Not a confirmation dialog for every property change in a single skill execution. Group related writes into one ask: "I'm about to add the player root, attach the controller script, and bind 5 input actions. OK?"
+- Not a request for design input. The skill should know what to do; the ask is for permission, not direction.
+- Not a stop on simple read-only ops or single-property tweaks the user clearly directed.
+
+## Linter check
+
+The `workflow/skill-test/SKILL.md` static linter looks for the phrases:
+- "May I" / "May I write" / "May I create" / "May I attach"
+- "I'm about to"
+- "Continue?" / "OK?" / "Proceed?"
+
+A skill that mutates files but never says any of these fails the linter.

package/references/gd-style.md

@@ -0,0 +1,121 @@
+# GDScript Style — Summer Conventions
+
+> The bar for GDScript in Summer. Skills should produce code that matches this. Where Godot's official style guide is silent, this is the tiebreaker.
+
+## File structure
+
+```gdscript
+class_name PlayerController
+extends CharacterBody3D
+
+# 1. Constants
+const SPEED := 5.0
+const JUMP_VELOCITY := 4.5
+const GRAVITY := 9.8
+
+# 2. Exports (designer-tweakable in inspector)
+@export var move_speed: float = 5.0
+@export var jump_height: float = 1.0
+@export_range(0.1, 10.0) var look_sensitivity: float = 1.0
+
+# 3. Signals (events this node emits)
+signal died
+signal health_changed(new_value: int)
+
+# 4. Onready references (cached node lookups)
+@onready var camera: Camera3D = $Camera3D
+@onready var collision: CollisionShape3D = $CollisionShape3D
+
+# 5. Private state (snake_case, leading underscore optional)
+var _is_grounded: bool = false
+var _velocity := Vector3.ZERO
+
+# 6. Lifecycle (in canonical order)
+func _ready() -> void:
+    pass
+
+func _process(delta: float) -> void:
+    pass
+
+func _physics_process(delta: float) -> void:
+    pass
+
+func _input(event: InputEvent) -> void:
+    pass
+
+# 7. Public API (PascalCase or snake_case methods, snake_case for funcs)
+func take_damage(amount: int) -> void:
+    pass
+
+# 8. Private helpers (leading underscore)
+func _calculate_movement(delta: float) -> Vector3:
+    return Vector3.ZERO
+```
+
+## Type hints
+
+**Always type-hint.** No bare `var x = 5`. Use `:=` for inferred typing or `:` for explicit.
+
+```gdscript
+# RIGHT
+var speed: float = 5.0
+var name := "Player"
+func attack(target: Node3D, amount: int) -> bool:
+    return true
+
+# WRONG
+var speed = 5.0
+func attack(target, amount):
+    return true
+```
+
+## Naming
+
+| Thing | Convention | Example |
+|---|---|---|
+| Class | PascalCase | `class_name PlayerController` |
+| File | snake_case | `player_controller.gd` |
+| Variable, function | snake_case | `move_speed`, `take_damage()` |
+| Constant | SCREAMING_SNAKE_CASE | `const MAX_HEALTH := 100` |
+| Signal | snake_case (past tense for events) | `died`, `health_changed` |
+| Private | leading underscore | `_is_grounded`, `_calculate_movement` |
+| Node in scene | PascalCase | `Player`, `Camera3D`, `CollisionShape3D` |
+
+## Signals
+
+Define with typed args. Connect in `_ready()` or in scene `.tscn` directly.
+
+```gdscript
+signal health_changed(new_value: int, max_value: int)
+
+func _ready() -> void:
+    health_changed.connect(_on_health_changed)
+
+func _on_health_changed(new_value: int, max_value: int) -> void:
+    pass
+```
+
+## Tweens
+
+Use `create_tween()` for animation. Don't manually lerp in `_process` unless you need fine control.
+
+```gdscript
+var tween := create_tween()
+tween.tween_property(self, "modulate", Color.WHITE, 0.3)
+```
+
+## What to avoid
+
+- Bare `var x = something` (no type)
+- `Object` typed parameters (use specific class)
+- `match` for two-branch logic (use `if`)
+- Recreating node lookups in `_process` (cache via `@onready`)
+- Hard-coded strings for node paths in code (use `@onready` + scene-relative paths)
+- Setting `position` in `_process` for physics objects (use `_physics_process` and `velocity`)
+
+## See also
+
+- [Official Godot GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html)
+- `scripting-patterns/gdscript-patterns/SKILL.md` — patterns and idioms
+- `scripting-patterns/signal-patterns/SKILL.md` — signal usage
+- `scripting-patterns/state-machine-patterns/SKILL.md` — state machine patterns

package/references/godot-version.md

@@ -0,0 +1,51 @@
+# Summer Engine Compatibility Reference
+
+> Read this before writing version-sensitive code, especially shaders,
+> rendering code, extensions, or export configuration.
+
+## Current technical base
+
+Summer Engine is the product. Its current upstream technical base is **4.6.1**
+(stable, Mono), the approved next target is **4.7.1**, and Summer follows
+upstream continuously. These are compatibility and lineage facts. They are not
+the Summer product name or a permanent SDK version.
+
+The repository source of truth is
+`compatibility/summer-engine.json`. The running engine also reports its measured
+technical version:
+
+```bash
+<engineBinaryPath> --version      # measured: 4.6.1.stable.mono.custom_build.b708b1182
+```
+
+Get `engineBinaryPath` from `summer_get_project_context`. Prefer live
+inspection to a copied version string. Creator onboarding and headlines should
+say Summer Engine, Summer game, Summer SDK, and GDScript. Use the upstream name
+only where technical compatibility, migration, extension APIs, contribution
+routing, attribution, or licensing requires it.
+
+## LLM training cutoff versus upstream releases
+
+| Domain | Godot 4.x churn | Action |
+|---|---|---|
+| Scripting (GDScript core) | low | Trust your training. Spot-check signatures only when something feels off. |
+| Scene / node tree APIs | low | Trust your training. |
+| Renderer (`RenderingServer`, `Compositor`) | high in 4.4 / 4.5 | Verify before writing. Check `MovieMaker`, `Compositor` effects, `RenderSceneBuffers` — these renamed/added recently. |
+| Shaders (`canvas_item`, `spatial`, `compute`) | medium | Built-in functions stable, but `hint_*` flags shifted. Verify `hint_screen_texture` / `hint_depth_texture` syntax. |
+| Animation (`AnimationTree`, `AnimationMixer`) | high (4.0 → 4.3 rename) | Use `AnimationMixer` for new code, not deprecated `AnimationPlayer`-as-mixer. |
+| Multiplayer (`MultiplayerAPI`) | medium | High-level API stable. `SceneReplicationConfig` settled in 4.0+. |
+| Editor / EditorPlugin | medium | Spot-check. |
+| `Tween` / `SceneTreeTween` | low | Stable since 4.0. |
+
+## Summer-specific deltas from the upstream engine
+
+- Local API server runs on `localhost:6550` (set per machine via `~/.summer/api-token`).
+- Engine ships a webview module in `modules/1summer_engine/`. Do not assume the
+  unmodified upstream editor for UI patches.
+- Project root contains `.summer/` for project memory; do not delete it.
+
+## When in doubt
+
+1. Use Summer MCP tools (`summer_inspect_node`, `summer_inspect_resource`) to read live editor state instead of guessing.
+2. Use `summer_get_diagnostics` after every scene change.
+3. Check `references/mcp-tools-reference.md` for the canonical tool list.