summer-engine 2.5.0 → 2.6.1

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

@@ -86,6 +86,143 @@ async function searchAssetsApi(params) {
     }
     return data;
 }
+async function authedGetJson(endpoint, timeoutMs = 15_000) {
+    const token = await getAuthToken();
+    if (!token) {
+        return {
+            status: 401,
+            error: "not_logged_in",
+            message: "Not signed in. Run in your terminal:\n  npx summer-engine login",
+        };
+    }
+    const res = await fetch(`${GATEWAY_URL}${endpoint}`, {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const data = (await res.json());
+    if (!res.ok) {
+        return {
+            status: res.status,
+            data,
+            error: data?.error || "request_failed",
+            message: data?.message || "Request failed",
+        };
+    }
+    return { status: res.status, data };
+}
+async function getAssetApi(assetId) {
+    const result = await authedGetJson(`/api/mcp/assets/${encodeURIComponent(assetId)}`);
+    if (result.error) {
+        return { error: result.error, message: result.message };
+    }
+    return { asset: result.data?.asset };
+}
+async function getAssetDownloadUrlApi(assetId, role) {
+    const result = await authedGetJson(`/api/mcp/assets/${encodeURIComponent(assetId)}/download-url?role=${encodeURIComponent(role)}`);
+    if (result.error) {
+        return { error: result.error, message: result.message };
+    }
+    return { data: result.data };
+}
+function fileNameFromUrl(fileUrl) {
+    return fileUrl.split("/").pop()?.split("?")[0] || "asset";
+}
+function sanitizeNodeName(name) {
+    return ((name || "Asset")
+        .replace(/[^\p{L}\p{N}_]+/gu, "_")
+        .replace(/^_+|_+$/g, "") || "Asset");
+}
+async function buildImportEntriesForAsset(asset, targetPath) {
+    const fileUrl = asset.importUrl || asset.fileUrl;
+    if (!fileUrl)
+        throw new Error("Asset has no import URL.");
+    const fileName = targetPath?.split("/").pop() || asset.fileName || fileNameFromUrl(fileUrl);
+    const packSlug = asset.packSlug ?? getPackSlugFromUrl(fileUrl) ?? "misc";
+    if (targetPath) {
+        if (asset.type === "3d_model" && fileUrl.includes("kenney/3d/")) {
+            const textureUrl = buildKenneyTextureUrl(fileUrl);
+            const hasTexture = await textureExists(textureUrl);
+            if (hasTexture) {
+                const glbDir = targetPath.replace(/\/[^/]+$/, "");
+                return {
+                    importPath: targetPath,
+                    imports: [
+                        { url: textureUrl, path: `${glbDir}/Textures/colormap.png` },
+                        { url: fileUrl, path: targetPath },
+                    ],
+                };
+            }
+        }
+        return {
+            importPath: targetPath,
+            imports: [{ url: fileUrl, path: targetPath }],
+        };
+    }
+    if (asset.type === "3d_model" && fileUrl.includes("kenney/3d/")) {
+        const imports = await buildKenneyImportEntries(fileUrl, packSlug, fileName);
+        return { imports, importPath: imports[imports.length - 1].path };
+    }
+    const path = asset.type === "3d_model"
+        ? `res://assets/models/${fileName}`
+        : `res://assets/${fileName}`;
+    return { imports: [{ url: fileUrl, path }], importPath: path };
+}
+async function importResolvedAsset(args) {
+    const { asset, parent, path, name } = args;
+    const { imports, importPath } = await buildImportEntriesForAsset(asset, path);
+    const client = await getClient();
+    const importResult = imports.length === 1
+        ? await client.executeOps([
+            { op: "ImportFromUrl", url: imports[0].url, path: imports[0].path },
+        ])
+        : await client.executeOps([{ op: "ImportFromUrlBatch", imports }]);
+    const ok = importResult?.results?.[0]?.ok;
+    if (!ok) {
+        throw new Error("Could not import asset. Check engine logs.");
+    }
+    let addedToScene = false;
+    if (parent && asset.type === "3d_model") {
+        await client.executeOps([
+            {
+                op: "InstantiateScene",
+                parent,
+                scene: importPath,
+                name: sanitizeNodeName(name || asset.title),
+            },
+        ]);
+        addedToScene = true;
+    }
+    return {
+        success: true,
+        assetId: asset.id,
+        asset: asset.title,
+        type: asset.type,
+        importedTo: importPath,
+        addedToScene,
+        parent: parent || null,
+    };
+}
+function jsonSuccess(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+function jsonError(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
 export function registerAssetTools(server) {
     server.tool("summer_search_assets", `Search for game assets in the Summer Engine ecosystem. **Free for all users** with rate limits.
 
@@ -129,6 +266,124 @@ Requires authentication (so we can attribute usage and apply per-user rate limit
             ],
         };
     });
+    server.tool("summer_list_my_assets", `List or search the signed-in user's generated and uploaded assets.
+
+Use this after generation jobs complete, when the user says "the model I made",
+"my last character", or when you need to retrieve an asset before importing it
+into the local project.
+
+Returns exact asset IDs plus file/import URLs. Use summer_get_asset for full
+metadata or summer_import_asset_by_id to import a specific result.`, {
+        query: z
+            .string()
+            .default("")
+            .describe("Optional search term. Empty string lists recent assets."),
+        assetType: z
+            .enum(["2d_image", "animation", "3d_model", "audio", "music", "all"])
+            .default("all")
+            .describe("Filter by asset type"),
+        limit: z.number().default(10).describe("Max results (1-20)"),
+    }, async ({ query, assetType, limit }) => {
+        const result = await searchAssetsApi({
+            query,
+            assetType,
+            limit: Math.min(limit, 20),
+            source: "my_assets",
+        });
+        if (result.error) {
+            return jsonError({ error: result.error, message: result.message });
+        }
+        return jsonSuccess({
+            assets: result.assets,
+            count: result.count,
+            message: result.message,
+        });
+    });
+    server.tool("summer_get_asset", `Fetch one asset by exact Summer asset ID.
+
+Use this after a generation job returns assetId/rigAssetId/animationAssetId, or
+after summer_list_my_assets/search results when you need the stable file URL,
+download URL, viewer URL, metadata, license, visibility, parent chain, or
+provider details.`, {
+        assetId: z.string().describe("Summer ArtAssets id"),
+    }, async ({ assetId }) => {
+        const result = await getAssetApi(assetId);
+        if (result.error || !result.asset) {
+            return jsonError({
+                error: result.error || "asset_not_found",
+                message: result.message || "Asset not found.",
+            });
+        }
+        return jsonSuccess({ asset: result.asset });
+    });
+    server.tool("summer_get_asset_download_url", `Get a downloadable URL for a specific asset file.
+
+Today this usually returns the Cloudinary URL plus Summer's download proxy.
+The response shape is future-proofed for signed URLs, so prefer this tool over
+handing users raw fileUrl when they explicitly ask to download.`, {
+        assetId: z.string().describe("Summer ArtAssets id"),
+        role: z
+            .enum(["primary", "thumbnail"])
+            .default("primary")
+            .describe("Which file to download"),
+    }, async ({ assetId, role }) => {
+        const result = await getAssetDownloadUrlApi(assetId, role);
+        if (result.error) {
+            return jsonError({ error: result.error, message: result.message });
+        }
+        return jsonSuccess(result.data);
+    });
+    server.tool("summer_import_asset_by_id", `Import an exact Summer asset ID into the current project.
+
+Use this when the asset was just generated, selected from my assets, or returned
+by search. Unlike summer_import_asset, this does not search or guess: it fetches
+the asset by ID, downloads it through Summer Engine, and runs Godot's import
+pipeline. For 3D models, pass parent to instantiate it in the open scene after
+import.`, {
+        assetId: z.string().describe("Summer ArtAssets id"),
+        path: z
+            .string()
+            .optional()
+            .describe("Optional target res:// path. If omitted, a path is inferred from asset type and filename."),
+        parent: z
+            .string()
+            .optional()
+            .describe("Optional parent node path. For 3D models only; imports and instantiates under this node."),
+        name: z
+            .string()
+            .optional()
+            .describe("Optional scene node name when parent is provided."),
+    }, async ({ assetId, path, parent, name }) => {
+        const fetched = await getAssetApi(assetId);
+        if (fetched.error || !fetched.asset) {
+            return jsonError({
+                error: fetched.error || "asset_not_found",
+                message: fetched.message || "Asset not found.",
+            });
+        }
+        try {
+            const imported = await importResolvedAsset({
+                asset: fetched.asset,
+                parent,
+                path,
+                name,
+            });
+            return jsonSuccess({
+                ...imported,
+                message: imported.addedToScene
+                    ? `Imported "${fetched.asset.title}" and added it to ${parent}.`
+                    : `Imported "${fetched.asset.title}" to ${imported.importedTo}.`,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return jsonError({
+                error: "import_failed",
+                message: msg,
+                hint: "Make sure Summer Engine is running and the target scene is open.",
+            });
+        }
+    });
     server.tool("summer_import_asset", `Search the asset library and import the best match into the project in one step.
 
 Use when the user wants a specific type of asset added: "Add a tree to the scene", "Import a wooden barrel".
@@ -138,8 +393,9 @@ Requires authentication. If the user gets an auth error, they need to run 'npx s
         query: z.string().describe("What to find, e.g. 'low-poly tree', 'wooden crate'"),
         parent: z.string().optional().describe("Parent node path to add the asset under, e.g. './World'. If omitted, only imports (no scene placement)"),
         assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("3d_model").describe("Preferred asset type"),
-    }, async ({ query, parent, assetType }) => {
-        const searchResult = await searchAssetsApi({ query, assetType, limit: 5 });
+        source: z.enum(["library", "my_assets", "all"]).default("all").describe("Where to search before importing"),
+    }, async ({ query, parent, assetType, source }) => {
+        const searchResult = await searchAssetsApi({ query, assetType, limit: 5, source });
         if (searchResult.error) {
             return {
                 content: [
@@ -176,45 +432,8 @@ Requires authentication. If the user gets an auth error, they need to run 'npx s
                 isError: true,
             };
         }
-        const fileName = fileUrl.split("/").pop()?.split("?")[0] || "asset";
-        const packSlug = best.packSlug ?? getPackSlugFromUrl(fileUrl) ?? "misc";
-        let imports;
-        if (best.type === "3d_model" && fileUrl.includes("kenney/3d/")) {
-            imports = await buildKenneyImportEntries(fileUrl, packSlug, fileName);
-        }
-        else {
-            const path = best.type === "3d_model"
-                ? `res://assets/models/${fileName}`
-                : `res://assets/${fileName}`;
-            imports = [{ url: fileUrl, path }];
-        }
-        const importPath = imports[imports.length - 1].path;
         try {
-            const client = await getClient();
-            const importResult = imports.length === 1
-                ? await client.executeOps([{ op: "ImportFromUrl", url: imports[0].url, path: imports[0].path }])
-                : await client.executeOps([{ op: "ImportFromUrlBatch", imports }]);
-            const ok = importResult?.results?.[0]?.ok;
-            if (!ok) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                error: "Import failed",
-                                message: "Could not import asset. Check engine logs.",
-                                asset: best.title,
-                            }, null, 2),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            if (parent && best.type === "3d_model") {
-                await client.executeOps([
-                    { op: "InstantiateScene", parent, scene: importPath, name: best.title.replace(/\s+/g, "_") },
-                ]);
-            }
+            const imported = await importResolvedAsset({ asset: best, parent });
             // 2D sprites and audio: import only; user adds to scene manually
             return {
                 content: [
@@ -222,14 +441,15 @@ Requires authentication. If the user gets an auth error, they need to run 'npx s
                         type: "text",
                         text: JSON.stringify({
                             success: true,
+                            assetId: best.id,
                             asset: best.title,
                             type: best.type,
-                            importedTo: importPath,
-                            addedToScene: parent ? true : false,
-                            parent: parent || null,
-                            message: parent
+                            importedTo: imported.importedTo,
+                            addedToScene: imported.addedToScene,
+                            parent: imported.parent,
+                            message: imported.addedToScene
                                 ? `Imported "${best.title}" and added to ${parent}`
-                                : `Imported "${best.title}" to ${importPath}`,
+                                : `Imported "${best.title}" to ${imported.importedTo}`,
                         }, null, 2),
                     },
                 ],

package/dist/mcp/tools/cloud-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCloudTools(server: McpServer): void;

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

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { cloudCheckpoints, cloudConflicts, cloudInit, cloudPull, cloudPush, cloudRestore, cloudStatus, } from "../../lib/cloud/sync.js";
+const projectArg = z.object({
+    project: z.string().optional().describe("Project root path. Defaults to the current working directory."),
+});
+const bootstrap = z.enum(["keep-cloud", "keep-local", "merge"]);
+function textJson(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+export function registerCloudTools(server) {
+    server.tool("summer_cloud_init", "Enable Summer Cloud for a project.", projectArg.shape, async (args) => textJson(await cloudInit({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_status", "Show Summer Cloud sync status.", projectArg.shape, async (args) => textJson(await cloudStatus({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_push", "Push local project changes to Summer Cloud.", {
+        ...projectArg.shape,
+        confirmDeletes: z.boolean().default(false).describe("Required when a push would delete many cloud files."),
+        bootstrap: bootstrap.optional().describe("No-base bootstrap choice."),
+        adoptPath: z.boolean().optional().describe("Accept that the project folder moved and update the recorded path."),
+    }, async (args) => textJson(await cloudPush({ ...args, face: "mcp" })));
+    server.tool("summer_cloud_pull", "Pull Summer Cloud changes into the local project.", {
+        ...projectArg.shape,
+        bootstrap: bootstrap.optional().describe("No-base bootstrap choice."),
+        adoptPath: z.boolean().optional().describe("Accept that the project folder moved and update the recorded path."),
+    }, async (args) => textJson(await cloudPull({ ...args, face: "mcp" })));
+    server.tool("summer_cloud_restore", "Restore a retained cloud version (creates a new head version server-side, then pulls), or a local pre-sync checkpoint via checkpointStamp.", {
+        ...projectArg.shape,
+        version: z.number().int().positive().optional().describe("Cloud version to restore."),
+        checkpointStamp: z.string().optional().describe("Local checkpoint stamp (see summer_cloud_checkpoints)."),
+    }, async (args) => textJson(await cloudRestore({ project: args.project, version: args.version, checkpoint: args.checkpointStamp, face: "mcp" })));
+    server.tool("summer_cloud_checkpoints", "List local pre-sync checkpoints.", projectArg.shape, async (args) => textJson(await cloudCheckpoints({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_conflicts", "List local Summer Cloud conflict sets, or restore a preserved conflict file with restorePath.", {
+        ...projectArg.shape,
+        restorePath: z.string().optional().describe("Project-relative path to restore from the conflict sets."),
+        set: z.string().optional().describe("Conflict set stamp; defaults to the newest set containing the path."),
+    }, async (args) => textJson(await cloudConflicts({ project: args.project, restorePath: args.restorePath, set: args.set, face: "mcp" })));
+}

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

@@ -1,12 +1,88 @@
+import { createRequire } from "node:module";
 import { z } from "zod";
 import { writeFile, mkdir } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
 import { getAuthToken } from "../../lib/auth.js";
+const require = createRequire(import.meta.url);
+const { version: CLI_VERSION } = require("../../../package.json");
 const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+const TOOL_BY_ENDPOINT = {
+    "/api/mcp/generate/image": "summer_generate_image",
+    "/api/mcp/generate/audio": "summer_generate_audio",
+    "/api/mcp/generate/3d": "summer_generate_3d",
+    "/api/mcp/generate/video": "summer_generate_video",
+    "/api/mcp/generate/motion": "summer_generate_motion",
+};
 // ---------------------------------------------------------------------------
 // Shared helpers
 // ---------------------------------------------------------------------------
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringFrom(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function formatValidationDetailEntry(entry) {
+    const record = asRecord(entry);
+    if (!record) {
+        return stringFrom(entry) ?? null;
+    }
+    const message = stringFrom(record.msg) ??
+        stringFrom(record.message) ??
+        stringFrom(record.error) ??
+        null;
+    if (!message)
+        return null;
+    const loc = Array.isArray(record.loc)
+        ? record.loc.map((part) => String(part)).join(".")
+        : stringFrom(record.path) ?? stringFrom(record.field);
+    return loc ? `${loc}: ${message}` : message;
+}
+function formatValidationDetails(detail) {
+    if (Array.isArray(detail)) {
+        return detail
+            .map(formatValidationDetailEntry)
+            .filter((entry) => !!entry);
+    }
+    const formatted = formatValidationDetailEntry(detail);
+    return formatted ? [formatted] : [];
+}
+function formattedApiErrorMessage(status, data) {
+    const record = asRecord(data);
+    const provider = asRecord(record?.provider);
+    const directDetailMessages = formatValidationDetails(record?.detail);
+    const detailMessages = directDetailMessages.length > 0
+        ? directDetailMessages
+        : Array.isArray(provider?.detailMessages)
+            ? provider.detailMessages.filter((entry) => typeof entry === "string")
+            : formatValidationDetails(provider?.detail);
+    if (status === 422 && detailMessages.length > 0) {
+        return `Request validation failed (422): ${detailMessages.join("; ")}`;
+    }
+    return (stringFrom(record?.message) ??
+        stringFrom(record?.error) ??
+        `Request failed (${status})`);
+}
+async function readJsonResponse(res) {
+    if (typeof res.text !== "function") {
+        if (typeof res.json === "function") {
+            return res.json().catch(() => ({}));
+        }
+        return {};
+    }
+    const text = await res.text().catch(() => "");
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text.slice(0, 1000) };
+    }
+}
 async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
     const token = await getAuthToken();
     if (!token) {
@@ -15,18 +91,30 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
             status: 401,
         };
     }
-    const res = await fetch(`${GATEWAY_URL}${endpoint}`, {
-        method: "POST",
-        headers: {
-            Authorization: `Bearer ${token}`,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(timeoutMs),
-    });
-    const data = await res.json();
+    let res;
+    try {
+        res = await fetch(`${GATEWAY_URL}${endpoint}`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+                "X-Summer-Client": "summer-cli",
+                "X-Summer-Client-Version": CLI_VERSION,
+                "X-Summer-Client-Surface": "mcp",
+                "X-Summer-MCP-Endpoint": endpoint,
+                "X-Summer-MCP-Tool": TOOL_BY_ENDPOINT[endpoint] ?? "unknown",
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `Generation request failed: ${msg}`, status: 0 };
+    }
+    const data = await readJsonResponse(res);
     if (!res.ok) {
-        let message = data.message || data.error || "Request failed";
+        let message = formattedApiErrorMessage(res.status, data);
         if (res.status === 402) {
             message =
                 (data.message || "Insufficient credits.") +
@@ -37,7 +125,7 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
                 (data.message || "Auth token expired.") +
                     "\nRe-authenticate:\n  npx summer-engine login";
         }
-        return { error: message, data, status: res.status };
+        return { error: message, data: { ...data, status: res.status }, status: res.status };
     }
     return { data, status: res.status };
 }
@@ -102,7 +190,7 @@ function errorResult(message, extra) {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ error: true, message, ...extra }, null, 2),
+                text: JSON.stringify({ error: true, ...extra, message }, null, 2),
             },
         ],
         isError: true,

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ASSET_POLICIES, GAME_TASK_MODES, GAME_TASK_TARGETS, VERIFICATION_LEVELS, buildGameTaskPlan, } from "../../lib/game-task-plan.js";
 import { getProjectMemorySummary } from "../../lib/project-memory.js";
 import { withEngine } from "./with-engine.js";
 function asRecord(value) {
@@ -87,6 +88,43 @@ function getCurrentScene(projectState, sceneState, health) {
         null);
 }
 export function registerProjectTools(server) {
+    server.tool("summer_start_game_task", `Start here for any substantial AI game-building task.
+
+Takes the user's goal and returns the recommended Summer workflow: skill routes,
+MCP tool groups, host-file boundaries, asset policy, user confirmation gates,
+and verification steps. This is the router before deep skills and before
+mutating the project.`, {
+        goal: z.string().describe("The user's game-building goal or task."),
+        mode: z
+            .enum(GAME_TASK_MODES)
+            .default("auto")
+            .describe("Optional task mode override."),
+        target: z
+            .enum(GAME_TASK_TARGETS)
+            .default("auto")
+            .describe("Optional content/system target override."),
+        assetPolicy: z
+            .enum(ASSET_POLICIES)
+            .default("ask-before-paid-generation")
+            .describe("How aggressively to use paid asset generation."),
+        verification: z
+            .enum(VERIFICATION_LEVELS)
+            .default("full")
+            .describe("How much engine verification the agent should plan for."),
+    }, async ({ goal, mode, target, assetPolicy, verification }) => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(buildGameTaskPlan({
+                    goal,
+                    mode,
+                    target,
+                    assetPolicy,
+                    verification,
+                }), null, 2),
+            },
+        ],
+    }));
     server.tool("summer_get_agent_playbook", `AI-first operating guide for Summer Engine MCP.
 
 Call this at the start of a fresh chat before touching scenes.
@@ -96,29 +134,33 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                 type: "text",
                 text: JSON.stringify({
                     startupChecklist: [
-                        "Decide first: file edit or engine operation.",
-                        "Write .gd/.cs/.json/docs/simple config with host file-edit tools directly.",
-                        "Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, screenshots/verification.",
-                        "Call summer_get_project_context first.",
+                        "Understand the request and outline a brief plan before reaching for tools.",
+                        "Default medium is host file tools: write/edit .gd/.cs/.tscn/.tres/.json/docs/config directly as text.",
+                        "Use Summer MCP only when you need the LIVE engine: play/stop, diagnostics, screenshots/verification, navmesh or light bake, runtime inspect, or asset import.",
+                        "Call summer_get_project_context first so you do not guess scene paths or the project language.",
                         "Use projectMemory from summer_get_project_context to decide which .summer Markdown files to read before creative/audio/dialogue/level/character work.",
-                        "If no scene is open, call summer_open_main_scene.",
-                        "Call summer_get_scene_tree before structural edits.",
-                        "Call summer_save_scene after edits.",
+                        "After writing code, PLAY the scene you just made and read summer_get_diagnostics; iterate until it launches clean instead of waiting for the user to navigate to it.",
                     ],
                     safeDefaults: [
-                        "Never guess scene filenames (main.tscn/Main.tscn).",
-                        "Do not route ordinary script, JSON, docs, or simple config edits through MCP when direct file tools are available.",
-                        "Never remove multiple top-level nodes unless user explicitly requests destructive edits.",
-                        "Use MCP for scene-tree mutations and inspector-visible values instead of hand-editing live scene state.",
+                        "Never guess scene filenames (main.tscn/Main.tscn) -- get them from summer_get_project_context.",
+                        "Edit files (including .tscn/.tres) with host file tools by default. Reach for MCP scene-ops only for live-engine needs (bake, play, runtime inspect) or when you want the editor to manage node ids / instancing.",
+                        "If you hand-edit a .tscn that is OPEN in the editor, reload it there afterward -- the editor's open tab can overwrite your file (clobber).",
+                        "Write GDScript by default; use C# only if the project already uses it.",
+                        "Never remove multiple top-level nodes unless the user explicitly requests destructive edits.",
                         "Never change priority: locked .summer memory, voice IDs, canon, or provider bindings without explicit user confirmation.",
                     ],
-                    preferredFlow: [
+                    buildFlow: [
+                        "1. Understand what the user wants (one pass, no tool spelunking first).",
+                        "2. Outline the plan fast and briefly; proceed once it is clearly right.",
+                        "3. Execute in pure code -- edit .gd/.tscn/.tres as text (GDScript by default, C# only if the project already uses it).",
+                        "4. Play the scene/game (start with the scene you just made), read console + script/debugger errors via summer_get_diagnostics, fix, and repeat until it launches clean.",
+                    ],
+                    liveEngineFlow: [
+                        "Use this flow ONLY when you genuinely need live engine state (navmesh/light bake, instancing into an already-open scene, runtime inspect):",
                         "summer_get_project_context",
-                        "read relevant .summer memory with host file tools when projectMemory shows matching files",
                         "summer_open_main_scene (if needed)",
                         "summer_get_scene_tree",
-                        "edit via summer_add_node / summer_set_prop / summer_set_resource_property",
-                        "write scripts/data/docs/simple config directly with host file-edit tools",
+                        "summer_add_node / summer_set_prop / summer_set_resource_property",
                         "summer_save_scene",
                         "summer_get_diagnostics",
                     ],
@@ -126,6 +168,7 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                         "If you see 'no scene open': run summer_open_main_scene.",
                         "If open_scene fails: re-check mainScene from summer_get_project_context.",
                         "If save fails: verify scene is open and game is not running.",
+                        "If a .tscn you wrote keeps reverting: the editor has that scene open -- reload or close the tab, then write again.",
                     ],
                 }, null, 2),
             },
@@ -163,7 +206,7 @@ Use this first in every fresh chat to avoid guessing scene filenames or editing
             guidance: mainScene
                 ? "Use `summer_open_scene` with `mainScene` if no scene is open."
                 : "Main scene not found in project state. Open a known scene path explicitly.",
-            fileEditingGuidance: "Write .gd/.cs/.json/docs/simple config directly with host file tools. Use MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.",
+            fileEditingGuidance: "Edit files (including .gd/.cs/.tscn/.tres/.json/docs) with host file tools by default. Use MCP only for live engine state: play/stop, diagnostics, screenshots/verification, navmesh or light bake, runtime inspect, and asset import. If you edit a .tscn that is open in the editor, reload it there afterward so the editor's tab does not overwrite your changes.",
         };
     }));
     server.tool("summer_open_main_scene", `Open the project's configured main scene from project settings.